How originprotocol/arm-oeth works
1. This repository is an onchain protocol codebase for Automated Redemption Manager (ARM) contracts. The core product is a family of liquidity/redemption managers deployed on Ethereum and Sonic: Lido ARM, EtherFi ARM, Ethena ARM, OETH ARM, and OS ARM. Each instance wraps a specific base asset and liquidity asset pair, but they share the same operating model.
2. The main onchain boundary is src/contracts. That is where the Solidity contract families live, including shared utilities plus protocol-specific logic under markets and pendle. The contracts expose two important external surfaces: a Uniswap V2-style swap interface, and an ERC-4626-like liquidity provider interface with deposit, requestRedeem, and delayed claimRedeem.
3. The protocol’s data flow is centered on liquidity and redemptions. Users deposit the liquidity asset into an ARM and receive LP shares. When they redeem, they first submit a withdrawal request, then later claim after a waiting period. If the ARM itself lacks enough liquid balance, it can source funds from an active lending market or external withdrawal queue before fulfilling the claim.
4. A second key flow is token swapping. The ARM contract acts like a router-compatible swap endpoint so external callers can trade between supported assets through the contract’s available reserves. The README also notes that the ARM token can be used as collateral on lending platforms, but should not itself be borrowable because its price can be increased by donating assets, which would distort lending risk.
5. Offchain operations are handled by Defender Actions in src/js/actions. These are the automation jobs that keep each ARM healthy: allocating liquidity, collecting fees, setting oracle/pricing inputs, requesting withdrawals, and claiming withdrawals when delays expire. The actions are bundled with Rollup before upload to OpenZeppelin Defender.
6. The automation layer is organized by protocol and task in src/js/tasks. This is the operational control plane for scripts that query chain state, compute actions, and submit transactions for admin, liquidity, rewards, pricing, queue management, swaps, and network-specific workflows. The utilities in src/js/utils encapsulate integrations with external venues and data sources such as Uniswap, 1inch, Curve, Kyber, Fluid, Merkl, Silo, Lido, EtherFi, and Sonic-related pricing/queue logic.
7. Deployment is split from runtime logic. script/deploy contains deployment helpers and network-specific deploy flows for mainnet and Sonic, while build/deployments-*.json stores chain deployment manifests. Verification and registry/tenderly sync are part of the deployment workflow, reflecting that the repo manages already-deployed production contracts across multiple chains.
8. The testing architecture is broad and safety-oriented. test/unit covers isolated contract behavior, test/fork exercises live-chain integrations on mainnet forks, test/invariants checks protocol invariants under adversarial scenarios, and test/smoke provides sanity coverage. This split mirrors the protocol’s risk profile: core accounting, market interactions, and redemption timing need both deterministic and fork-based validation.
9. Documentation and architecture diagrams are first-class artifacts. docs/plantuml contains protocol diagrams for the different ARM variants and supporting process flows, while script/deploy/ARCHITECTURE.md documents deployment structure. The repository also includes Hardhat.md, foundry.toml, and hardhat.config.js, showing a dual-tooling Solidity workflow with both Hardhat and Foundry.
10. The repo is therefore organized around three primary boundaries: onchain ARM contracts, offchain operational automation, and deployment/testing tooling. The contract layer enforces accounting and redemption semantics; the automation layer supplies prices, manages queues, and moves liquidity; and the tooling layer supports safe rollout, verification, and continuous validation across Ethereum and Sonic.
Main entry points: contracts ARM contracts · deploy Deploy flows · actions Defender actions · tasks Task control
Components 20
Onchain contracts
Solidity protocol boundary and shared contract families.
- ARM contracts · Core onchain Automated Redemption Manager contract boundary.
src/contracts - Shared utils · Common contract utilities reused across ARM variants.
src/contracts/utils - Markets · Market and lending integrations used to source liquidity.
src/contracts/markets - Pendle · Pendle-specific contract integration layer.
src/contracts/pendle - Lido ARM · Lido liquidity/redemption manager instance.
- EtherFi ARM · EtherFi liquidity/redemption manager instance.
- Ethena ARM · Ethena liquidity/redemption manager instance.
- OETH ARM · OETH liquidity/redemption manager instance.
- OS ARM · Sonic OS liquidity/redemption manager instance.
Offchain automation
Defender actions, task orchestration, and chain integrations.
- Defender actions · Packaged automation jobs for liquidity, fees, pricing, and withdrawals.
src/js/actions - Task control · Operational task layer for querying state and submitting management transactions.
src/js/tasks - Integrations · Shared integrations for DEXs, staking venues, pricing, and chain data.
src/js/utils
Deployment & tooling
Deployment scripts, manifests, and build/config entrypoints.
- Deploy flows · Network-specific deployment and rollout helpers.
script/deploy - Deployment manifests · Per-chain deployment records and address manifests.
build - Tooling config · Hardhat and Foundry configuration for the Solidity workflow.
Testing
Fork, invariant, unit, and smoke validation layers.
- Unit tests · Isolated behavior and accounting coverage.
test/unit - Fork tests · Mainnet-style integration and protocol interaction coverage.
test/fork - Invariant tests · Protocol invariant and safety property validation.
test/invariants - Smoke tests · Minimal end-to-end sanity coverage.
test/smoke
Docs
Architecture notes and protocol diagrams.
- Protocol diagrams · PlantUML diagrams for ARM variants and process flows.
docs/plantuml
Connections 21
- ARM contracts → Shared utils: shared logic · Common contract utilities underpin all ARM variants.
- ARM contracts → Markets: liquidity source · Uses market integrations to source or rebalance funds.
- ARM contracts → Pendle: pendle path · Pendle-specific contract path for supported integrations.
- ARM contracts → Lido ARM: implements · Lido instance of the ARM protocol.
- ARM contracts → EtherFi ARM: implements · EtherFi instance of the ARM protocol.
- ARM contracts → Ethena ARM: implements · Ethena instance of the ARM protocol.
- ARM contracts → OETH ARM: implements · OETH instance of the ARM protocol.
- ARM contracts → OS ARM: implements · OS/Sonic instance of the ARM protocol.
- Task control → Defender actions: packages · Tasks assemble Defender actions for upload and execution.
- Task control → Integrations: uses · Tasks depend on shared integrations and pricing helpers.
- Defender actions → ARM contracts: admin ops · Automation submits liquidity, fee, pricing, and withdrawal transactions.
- Defender actions → Integrations: reads data · Automation relies on venue adapters and data-source helpers.
- Deploy flows → ARM contracts: deploys · Deployment flows instantiate the ARM contracts.
- Deploy flows → Deployment manifests: writes · Deployment produces chain-specific manifests and address records.
- Tooling config → Deploy flows: supports · Hardhat and Foundry config support build, deploy, and verification flows.
- Unit tests → ARM contracts: verifies · Unit tests cover isolated contract behavior.
- Fork tests → ARM contracts: integrates · Fork tests exercise live-chain interactions.
- Invariant tests → ARM contracts: checks · Invariant suite stresses accounting and redemption safety properties.
- Smoke tests → ARM contracts: sanity-checks · Smoke tests confirm basic protocol operation.
- Protocol diagrams → ARM contracts: documents · Diagrams explain protocol structure and operating flows.
- Protocol diagrams → Deploy flows: documents · Architecture notes also cover deployment structure.