# originprotocol/arm-oeth architecture

> Architecture diagram of the GitHub repository originprotocol/arm-oeth, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/originprotocol/arm-oeth
- Repository: https://github.com/originprotocol/arm-oeth

## Overview

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: [`src/contracts`](https://github.com/originprotocol/arm-oeth/tree/main/src/contracts) (ARM contracts), [`script/deploy`](https://github.com/originprotocol/arm-oeth/tree/main/script/deploy) (Deploy flows), [`src/js/actions`](https://github.com/originprotocol/arm-oeth/tree/main/src/js/actions) (Defender actions), [`src/js/tasks`](https://github.com/originprotocol/arm-oeth/tree/main/src/js/tasks) (Task control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_onchain["Onchain contracts"]
  node_contracts_root["ARM contracts<br/>solidity protocol"]
  node_contracts_utils["Shared utils<br/>solidity helpers"]
  node_contracts_markets["Markets<br/>market adapters"]
  node_contracts_pendle["Pendle"]
  node_arm_lido(("Lido ARM<br/>ARM variant"))
  node_arm_etherfi(("EtherFi ARM<br/>ARM variant"))
  node_arm_ethena(("Ethena ARM<br/>ARM variant"))
  node_arm_oeth(("OETH ARM<br/>ARM variant"))
  node_arm_os(("OS ARM<br/>ARM variant"))
end

subgraph group_ops["Offchain automation"]
  node_actions["Defender actions<br/>automation jobs"]
  node_tasks["Task control<br/>automation cli"]
  node_utils["Integrations<br/>external adapters"]
end

subgraph group_tooling["Deployment & tooling"]
  node_deploy["Deploy flows<br/>deployment scripts"]
  node_manifests[("Deployment manifests<br/>chain registry")]
  node_configs["Tooling config<br/>build config"]
end

subgraph group_testing["Testing"]
  node_unit_tests["Unit tests<br/>contract tests"]
  node_fork_tests["Fork tests<br/>live-chain tests"]
  node_invariant_tests["Invariant tests<br/>adversarial checks"]
  node_smoke_tests["Smoke tests<br/>sanity checks"]
end

subgraph group_docs["Docs"]
  node_diagrams["Protocol diagrams<br/>architecture docs"]
end

node_contracts_root -->|"shared logic"| node_contracts_utils
node_contracts_root -->|"liquidity source"| node_contracts_markets
node_contracts_root -->|"pendle path"| node_contracts_pendle
node_contracts_root -->|"implements"| node_arm_lido
node_contracts_root -->|"implements"| node_arm_etherfi
node_contracts_root -->|"implements"| node_arm_ethena
node_contracts_root -->|"implements"| node_arm_oeth
node_contracts_root -->|"implements"| node_arm_os
node_tasks -->|"packages"| node_actions
node_tasks -->|"uses"| node_utils
node_actions -->|"admin ops"| node_contracts_root
node_actions -->|"reads data"| node_utils
node_deploy -->|"deploys"| node_contracts_root
node_deploy -->|"writes"| node_manifests
node_configs -->|"supports"| node_deploy
node_unit_tests -->|"verifies"| node_contracts_root
node_fork_tests -->|"integrates"| node_contracts_root
node_invariant_tests -->|"checks"| node_contracts_root
node_smoke_tests -->|"sanity-checks"| node_contracts_root
node_diagrams -->|"documents"| node_contracts_root
node_diagrams -->|"documents"| node_deploy

click node_contracts_root "https://github.com/originprotocol/arm-oeth/tree/main/src/contracts"
click node_contracts_utils "https://github.com/originprotocol/arm-oeth/tree/main/src/contracts/utils"
click node_contracts_markets "https://github.com/originprotocol/arm-oeth/tree/main/src/contracts/markets"
click node_contracts_pendle "https://github.com/originprotocol/arm-oeth/tree/main/src/contracts/pendle"
click node_actions "https://github.com/originprotocol/arm-oeth/tree/main/src/js/actions"
click node_tasks "https://github.com/originprotocol/arm-oeth/tree/main/src/js/tasks"
click node_utils "https://github.com/originprotocol/arm-oeth/tree/main/src/js/utils"
click node_deploy "https://github.com/originprotocol/arm-oeth/tree/main/script/deploy"
click node_manifests "https://github.com/originprotocol/arm-oeth/tree/main/build"
click node_unit_tests "https://github.com/originprotocol/arm-oeth/tree/main/test/unit"
click node_fork_tests "https://github.com/originprotocol/arm-oeth/tree/main/test/fork"
click node_invariant_tests "https://github.com/originprotocol/arm-oeth/tree/main/test/invariants"
click node_smoke_tests "https://github.com/originprotocol/arm-oeth/tree/main/test/smoke"
click node_diagrams "https://github.com/originprotocol/arm-oeth/tree/main/docs/plantuml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_contracts_root,node_contracts_utils,node_contracts_markets,node_contracts_pendle,node_arm_lido,node_arm_etherfi,node_arm_ethena,node_arm_oeth,node_arm_os toneBlue
class node_actions,node_tasks,node_utils toneAmber
class node_deploy,node_manifests,node_configs toneMint
class node_unit_tests,node_fork_tests,node_invariant_tests,node_smoke_tests toneRose
class node_diagrams toneIndigo
```

## Components

### Onchain contracts

Solidity protocol boundary and shared contract families.

- [ARM contracts](https://github.com/originprotocol/arm-oeth/tree/main/src/contracts): solidity protocol · Core onchain Automated Redemption Manager contract boundary. · `src/contracts`
- [Shared utils](https://github.com/originprotocol/arm-oeth/tree/main/src/contracts/utils): solidity helpers · Common contract utilities reused across ARM variants. · `src/contracts/utils`
- [Markets](https://github.com/originprotocol/arm-oeth/tree/main/src/contracts/markets): market adapters · Market and lending integrations used to source liquidity. · `src/contracts/markets`
- [Pendle](https://github.com/originprotocol/arm-oeth/tree/main/src/contracts/pendle): pendle adapters · Pendle-specific contract integration layer. · `src/contracts/pendle`
- **Lido ARM**: ARM variant · Lido liquidity/redemption manager instance.
- **EtherFi ARM**: ARM variant · EtherFi liquidity/redemption manager instance.
- **Ethena ARM**: ARM variant · Ethena liquidity/redemption manager instance.
- **OETH ARM**: ARM variant · OETH liquidity/redemption manager instance.
- **OS ARM**: ARM variant · Sonic OS liquidity/redemption manager instance.

### Offchain automation

Defender actions, task orchestration, and chain integrations.

- [Defender actions](https://github.com/originprotocol/arm-oeth/tree/main/src/js/actions): automation jobs · Packaged automation jobs for liquidity, fees, pricing, and withdrawals. · `src/js/actions`
- [Task control](https://github.com/originprotocol/arm-oeth/tree/main/src/js/tasks): automation cli · Operational task layer for querying state and submitting management transactions. · `src/js/tasks`
- [Integrations](https://github.com/originprotocol/arm-oeth/tree/main/src/js/utils): external adapters · Shared integrations for DEXs, staking venues, pricing, and chain data. · `src/js/utils`

### Deployment & tooling

Deployment scripts, manifests, and build/config entrypoints.

- [Deploy flows](https://github.com/originprotocol/arm-oeth/tree/main/script/deploy): deployment scripts · Network-specific deployment and rollout helpers. · `script/deploy`
- [Deployment manifests](https://github.com/originprotocol/arm-oeth/tree/main/build): chain registry · Per-chain deployment records and address manifests. · `build`
- **Tooling config**: build config · Hardhat and Foundry configuration for the Solidity workflow.

### Testing

Fork, invariant, unit, and smoke validation layers.

- [Unit tests](https://github.com/originprotocol/arm-oeth/tree/main/test/unit): contract tests · Isolated behavior and accounting coverage. · `test/unit`
- [Fork tests](https://github.com/originprotocol/arm-oeth/tree/main/test/fork): live-chain tests · Mainnet-style integration and protocol interaction coverage. · `test/fork`
- [Invariant tests](https://github.com/originprotocol/arm-oeth/tree/main/test/invariants): adversarial checks · Protocol invariant and safety property validation. · `test/invariants`
- [Smoke tests](https://github.com/originprotocol/arm-oeth/tree/main/test/smoke): sanity checks · Minimal end-to-end sanity coverage. · `test/smoke`

### Docs

Architecture notes and protocol diagrams.

- [Protocol diagrams](https://github.com/originprotocol/arm-oeth/tree/main/docs/plantuml): architecture docs · PlantUML diagrams for ARM variants and process flows. · `docs/plantuml`

## Connections

- 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.
