From 5a6977c3e84d5d3380f74bcff515fd1da21d3efc Mon Sep 17 00:00:00 2001 From: AdekunleBamz Date: Sat, 10 Jan 2026 14:39:07 +0100 Subject: [PATCH] docs: Add README documentation for missing contract directories - Add automation/README.md documenting Safe modules for protocol operations - Add beacon/README.md explaining Beacon Chain proof verification - Add bridges/README.md documenting LayerZero OFT adapters - Add buyback/README.md explaining yield buyback mechanisms - Add poolBooster/README.md documenting liquidity incentive contracts - Add zapper/README.md explaining cross-chain zapper utilities --- contracts/contracts/automation/README.md | 45 +++++++++++++++++++++ contracts/contracts/beacon/README.md | 30 ++++++++++++++ contracts/contracts/bridges/README.md | 30 ++++++++++++++ contracts/contracts/buyback/README.md | 35 ++++++++++++++++ contracts/contracts/poolBooster/README.md | 49 +++++++++++++++++++++++ contracts/contracts/zapper/README.md | 35 ++++++++++++++++ 6 files changed, 224 insertions(+) create mode 100644 contracts/contracts/automation/README.md create mode 100644 contracts/contracts/beacon/README.md create mode 100644 contracts/contracts/bridges/README.md create mode 100644 contracts/contracts/buyback/README.md create mode 100644 contracts/contracts/poolBooster/README.md create mode 100644 contracts/contracts/zapper/README.md diff --git a/contracts/contracts/automation/README.md b/contracts/contracts/automation/README.md new file mode 100644 index 0000000000..de247e1141 --- /dev/null +++ b/contracts/contracts/automation/README.md @@ -0,0 +1,45 @@ +# Automation + +This directory contains Safe Module contracts for automating protocol operations. + +## Overview + +Automation modules extend Gnosis Safe functionality to enable operators to execute specific, pre-approved actions without requiring full multisig approval for each transaction. + +## Contracts + +### Base Contracts + +| Contract | Description | +|----------|-------------| +| `AbstractSafeModule.sol` | Base contract for all Safe modules with operator role management | + +### Bridge Helpers + +| Contract | Description | +|----------|-------------| +| `AbstractCCIPBridgeHelperModule.sol` | Base for Chainlink CCIP bridge operations | +| `AbstractLZBridgeHelperModule.sol` | Base for LayerZero bridge operations | +| `BaseBridgeHelperModule.sol` | Common bridge helper functionality | +| `EthereumBridgeHelperModule.sol` | Ethereum mainnet bridge operations | +| `PlumeBridgeHelperModule.sol` | Plume network bridge operations | + +### Operational Modules + +| Contract | Description | +|----------|-------------| +| `ClaimBribesSafeModule.sol` | Automate claiming of bribe rewards | +| `ClaimStrategyRewardsSafeModule.sol` | Automate claiming strategy rewards | +| `CollectXOGNRewardsModule.sol` | Automate collection of xOGN rewards | +| `CurvePoolBoosterBribesModule.sol` | Automate Curve pool booster bribes | + +## Architecture + +All modules inherit from `AbstractSafeModule` which provides: +- **Operator Role**: Designated addresses can trigger module actions +- **Safe Integration**: Modules execute transactions through the Safe contract +- **Access Control**: OpenZeppelin's `AccessControlEnumerable` for role management + +## Usage + +Modules are registered with a Gnosis Safe and can then be triggered by operators to execute pre-defined actions safely. diff --git a/contracts/contracts/beacon/README.md b/contracts/contracts/beacon/README.md new file mode 100644 index 0000000000..c4f1d241d2 --- /dev/null +++ b/contracts/contracts/beacon/README.md @@ -0,0 +1,30 @@ +# Beacon + +This directory contains contracts for Ethereum Beacon Chain proof verification. + +## Overview + +These contracts enable verification of Beacon Chain data through Merkle proofs, which is essential for OETH's native staking functionality. They verify validator states, withdrawal credentials, and other beacon chain data. + +## Contracts + +| Contract | Description | +|----------|-------------| +| `BeaconProofs.sol` | Main contract for verifying beacon chain Merkle proofs | +| `BeaconProofsLib.sol` | Library implementation of proof verification logic | +| `BeaconConsolidation.sol` | Handles validator consolidation proofs | +| `BeaconRoots.sol` | Access to beacon block roots (EIP-4788) | +| `Merkle.sol` | Merkle tree utilities for proof verification | +| `Endian.sol` | Endianness conversion utilities | +| `PartialWithdrawal.sol` | Handles partial withdrawal proofs | + +## Use Cases + +- **Validator Verification**: Verify validator public keys and indices +- **Withdrawal Credentials**: Confirm validators point to correct withdrawal addresses +- **Withdrawal Proofs**: Verify partial and full validator withdrawals +- **Consolidation**: Handle validator consolidation operations + +## Integration + +These contracts are used by the Native Staking strategy (`strategies/NativeStaking/`) to verify on-chain that validators are correctly configured and to process withdrawals trustlessly. diff --git a/contracts/contracts/bridges/README.md b/contracts/contracts/bridges/README.md new file mode 100644 index 0000000000..11cb1655cf --- /dev/null +++ b/contracts/contracts/bridges/README.md @@ -0,0 +1,30 @@ +# Bridges + +This directory contains contracts for cross-chain token bridging using omnichain standards. + +## Overview + +Bridge adapters enable OETH and other Origin tokens to be bridged across multiple chains using LayerZero's Omnichain Fungible Token (OFT) standard. + +## Contracts + +| Contract | Description | +|----------|-------------| +| `OmnichainL2Adapter.sol` | LayerZero OFT adapter for L2 chains (mint/burn mechanism) | +| `OmnichainMainnetAdapter.sol` | LayerZero OFT adapter for Ethereum mainnet (lock/unlock mechanism) | + +## Architecture + +### Mainnet (Lock/Unlock) +On Ethereum mainnet, the adapter locks tokens when bridging out and unlocks when receiving from L2s. + +### L2 (Mint/Burn) +On L2 chains, the adapter mints tokens when receiving from mainnet and burns when bridging back. + +## Integration + +These adapters integrate with LayerZero's messaging infrastructure to enable secure cross-chain token transfers while maintaining a unified token supply across all chains. + +## Related + +- See `automation/` for bridge helper modules that assist with cross-chain operations diff --git a/contracts/contracts/buyback/README.md b/contracts/contracts/buyback/README.md new file mode 100644 index 0000000000..842e1d8ee4 --- /dev/null +++ b/contracts/contracts/buyback/README.md @@ -0,0 +1,35 @@ +# Buyback + +This directory contains contracts for protocol buyback mechanisms. + +## Overview + +Buyback contracts swap protocol yield (OUSD/OETH) for governance tokens (OGN) and CVX, supporting token value and protocol governance power. + +## Contracts + +| Contract | Description | +|----------|-------------| +| `AbstractBuyback.sol` | Base buyback implementation with common logic | +| `OUSDBuyback.sol` | OUSD-specific buyback contract | +| `OETHBuyback.sol` | OETH-specific buyback contract | +| `ARMBuyback.sol` | ARM (Automated Redemption Manager) buyback contract | + +## Mechanism + +1. **Yield Collection**: Protocol yield is collected from strategies +2. **Swap Execution**: Yield tokens are swapped via 1inch or other DEX aggregators +3. **Token Distribution**: + - OGN is sent to treasury or staking + - CVX is locked in vlCVX for voting power + +## Configuration + +- **CVX Share BPS**: Configurable percentage split between OGN and CVX +- **Rewards Source**: Address that receives buyback proceeds +- **Treasury Manager**: Address managing treasury operations +- **Swap Router**: DEX aggregator for executing swaps + +## Access Control + +Buyback operations are restricted to the Strategist role, ensuring controlled execution of swaps with appropriate slippage parameters. diff --git a/contracts/contracts/poolBooster/README.md b/contracts/contracts/poolBooster/README.md new file mode 100644 index 0000000000..4a68c1dca7 --- /dev/null +++ b/contracts/contracts/poolBooster/README.md @@ -0,0 +1,49 @@ +# Pool Booster + +This directory contains contracts for boosting liquidity pool incentives. + +## Overview + +Pool Booster contracts distribute Origin token rewards to liquidity providers through various incentive distribution platforms like Merkl and Metropolis. + +## Contracts + +### Core + +| Contract | Description | +|----------|-------------| +| `PoolBoostCentralRegistry.sol` | Central registry tracking all pool boosters | +| `AbstractPoolBoosterFactory.sol` | Base factory for deploying pool boosters | + +### Merkl Integration + +| Contract | Description | +|----------|-------------| +| `PoolBoosterMerkl.sol` | Pool booster using Merkl distribution | +| `PoolBoosterFactoryMerkl.sol` | Factory for deploying Merkl boosters | + +### Metropolis Integration + +| Contract | Description | +|----------|-------------| +| `PoolBoosterMetropolis.sol` | Pool booster using Metropolis distribution | +| `PoolBoosterFactoryMetropolis.sol` | Factory for deploying Metropolis boosters | + +### Swapx Integration + +| Contract | Description | +|----------|-------------| +| `PoolBoosterSwapxSingle.sol` | Single-token Swapx pool booster | +| `PoolBoosterSwapxDouble.sol` | Dual-token Swapx pool booster | +| `PoolBoosterFactorySwapxSingle.sol` | Factory for single-token Swapx boosters | +| `PoolBoosterFactorySwapxDouble.sol` | Factory for dual-token Swapx boosters | + +## Architecture + +1. **Registry**: Tracks all deployed pool boosters +2. **Factories**: Deploy new pool boosters with consistent configuration +3. **Boosters**: Distribute rewards to target liquidity pools + +## Usage + +Pool boosters are funded with Origin tokens (OS) and create incentive campaigns on the respective platforms to attract liquidity to OETH/OUSD pools. diff --git a/contracts/contracts/zapper/README.md b/contracts/contracts/zapper/README.md new file mode 100644 index 0000000000..077ebbe335 --- /dev/null +++ b/contracts/contracts/zapper/README.md @@ -0,0 +1,35 @@ +# Zapper + +This directory contains zapper contracts for simplified token operations. + +## Overview + +Zappers provide one-transaction convenience functions that combine multiple operations, such as wrapping and bridging in a single call. + +## Contracts + +| Contract | Description | +|----------|-------------| +| `WOETHCCIPZapper.sol` | Zap ETH on mainnet directly to WOETH on L2 chains | + +## WOETHCCIPZapper + +The WOETH CCIP Zapper enables users to convert ETH on Ethereum mainnet directly into Wrapped OETH (WOETH) on supported L2 chains in a single transaction. + +### Flow + +1. User sends ETH to the zapper +2. Zapper converts ETH to OETH via the OETH Zapper +3. OETH is wrapped to WOETH +4. WOETH is bridged to the destination chain via Chainlink CCIP +5. WOETH arrives at the recipient address on L2 + +### Benefits + +- **Gas Efficient**: Single transaction instead of multiple +- **User Friendly**: No need to manage intermediate tokens +- **Cross-Chain**: Direct mainnet ETH to L2 WOETH + +## Events + +- `Zap`: Emitted on each successful zap with message ID, sender, recipient, and amount