docs: Add architecture section to CLAUDE.md by fusmanii · Pull Request #1318 · across-protocol/contracts

fusmanii · 2026-02-17T00:56:17Z

Summary

Added a comprehensive Architecture section to CLAUDE.md that explains the Across Protocol's hub-and-spoke design for new contributors.

Core contracts: HubPool, SpokePool, Chain Adapters
Key roles: Depositor, Relayer, Data Worker, Disputer, LP
Protocol flow: 7-step lifecycle from deposit through refund (including slow fill fallback)
Cross-chain ownership model and supported chains

This documentation helps developers understand how the protocol coordinates fast cross-chain transfers with optimistic verification.

Added comprehensive Architecture section covering core contracts (HubPool, SpokePool, Chain Adapters), key roles (Depositor, Relayer, Data Worker, Disputer, LP), protocol flow, cross-chain ownership model, supported chains, and key libraries. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

nicholaspai

Some ideas for adding more nuanced descriptions. Thanks for taking the initiative on this!

nicholaspai · 2026-02-17T01:18:45Z

CLAUDE.md

+
+| Role | Description |
+|------|-------------|
+| **Depositor** | Calls `deposit()` on origin SpokePool to initiate a cross-chain transfer |


Maybe we shouldn't specify a specific function since there are multiple entry points to depositing now, including sponsored, gasless flows?

nicholaspai · 2026-02-17T01:19:25Z

CLAUDE.md

+|------|-------------|
+| **Depositor** | Calls `deposit()` on origin SpokePool to initiate a cross-chain transfer |
+| **Relayer** | Fills deposits on destination chain by fronting tokens, later reimbursed via merkle proof |
+| **Data Worker** | Off-chain agent that aggregates deposits/fills, constructs merkle trees, and calls `proposeRootBundle()` on HubPool (stakes a bond) |


Importantly also validates not just aggregates

nicholaspai · 2026-02-17T01:23:01Z

CLAUDE.md

+
+### Protocol Flow
+
+1. **Deposit**: User locks tokens in origin SpokePool → `FundsDeposited` event emitted


Sets the amount of fees that they're willing to pay to a filler who fulfills their deposit.

Importantly, the relayer has a decision to determine if the deposit is profitable or not.

I think the profitability decision matrix is maybe important to reference because it might help contributors to be aware that fair prices need to be communicated to depositors somehow, currently done through a hosted API service or directly from an exclusive filler.

I think this will help improve future iterations of these contracts as they really should be "quote API aware" for example

nicholaspai · 2026-02-17T01:23:40Z

CLAUDE.md

+| Role | Description |
+|------|-------------|
+| **Depositor** | Calls `deposit()` on origin SpokePool to initiate a cross-chain transfer |
+| **Relayer** | Fills deposits on destination chain by fronting tokens, later reimbursed via merkle proof |


Maybe worth noting that relayers compete with each other on speed and also their ability to manage their cross chain inventory

nicholaspai · 2026-02-17T01:24:20Z

CLAUDE.md

+
+| Role | Description |
+|------|-------------|
+| **Depositor** | Calls `deposit()` on origin SpokePool to initiate a cross-chain transfer |


Also maybe worth noting the depositor is a just an end user, not technical, doesn't have any other requirements besides wanting to move money across chains

nicholaspai · 2026-02-17T01:25:52Z

CLAUDE.md

+|------|-------------|
+| **Depositor** | Calls `deposit()` on origin SpokePool to initiate a cross-chain transfer |
+| **Relayer** | Fills deposits on destination chain by fronting tokens, later reimbursed via merkle proof |
+| **Data Worker** | Off-chain agent that aggregates deposits/fills, constructs merkle trees, and calls `proposeRootBundle()` on HubPool (stakes a bond) |


Maybe worth noting that the dataworker is supposed to be able to handle sending a lot of on chain requests across different chains with a relatively longer lookback window than the relayer is expected to maintain.

The dataworker unlike the relayer is not expected to be "fast" but they are rpc- and to a lesser extent, compute-, intensive

fusmanii · 2026-02-17T02:17:21Z

@claude add all the changes suggested by @nicholaspai

claude · 2026-02-17T02:17:36Z

Claude finished @fusmanii's task in 1m 29s —— View job

Implementing review feedback

Read current CLAUDE.md content
Add note that depositor is end user, non-technical (line 19)
Change deposit function reference to mention multiple entry points (line 19)
Add note about relayers competing on speed and inventory management (line 20)
Update data worker description to note validation, not just aggregation (line 21)
Add data worker performance characteristics (RPC-intensive, longer lookback) (line 21)
Add depositor fee setting and relayer profitability details (line 27)
Commit and push changes

Summary

All review feedback from @nicholaspai has been incorporated into CLAUDE.md:

Key Roles table updates:

Depositor: Now described as end user (non-technical) with multiple entry points (deposit, sponsored, gasless flows)
Relayer: Added details about competition on speed and inventory management, plus profitability evaluation
Data Worker: Updated to emphasize validation (not just aggregation) and performance characteristics (RPC-intensive, longer lookback window, less speed-critical)

Protocol Flow updates:

Deposit step: Added explanation of depositor fee setting and relayer profitability decision matrix, including how fair pricing is communicated via API services or exclusive relayers
Bundle Proposal step: Changed "aggregates" to "validates and aggregates"

Changes have been committed and pushed to the PR branch.

--- | Branch: fusmanii/update-claude-md-arch

- Note depositor is end user with multiple entry points (deposit/sponsored/gasless) - Add relayer competition details (speed and inventory management) - Expand data worker description to include validation and performance characteristics - Add depositor fee setting and relayer profitability evaluation details - Explain pricing communication via API services or exclusive relayers Co-authored-by: Faisal Usmani <fusmanii@users.noreply.github.com>

grasphoper · 2026-02-20T18:43:46Z

CLAUDE.md

+
+### Supported Chains
+
+SpokePools exist for: Ethereum, Arbitrum, Optimism, Base, Polygon, Polygon zkEVM, zkSync, Scroll, Linea, Blast, Boba, Lisk, WorldChain, Ink, Lens, Mode, and others via `Universal_SpokePool` (generic OP Stack).


`Universal_SpokePool` (generic OP Stack).

This looks incorrect. Instead, it's a Spoke that can be used on any EVM-like chain: L2 or L1 by proving ongoing Ethereum state updates via ZK proofs

updated 24c4460

grasphoper · 2026-02-20T18:44:39Z

CLAUDE.md

+- **CircleCCTPAdapter** — USDC bridging via Circle's CCTP (V1/V2), with burn-limit splitting for large transfers
+- **OFTTransportAdapter** — Token bridging via LayerZero OFT standard
+- **MerkleLib** — Merkle proof verification with bitmap tracking to prevent double-claiming
+- **Lockable** — Custom reentrancy guard used across SpokePools


I feel like this section is a bit bad. These are not key libraries (IMO). And token space is important to save. I'd remove it or perhaps just point to a libraries folder or something

I agree, removed it 24c4460

grasphoper · 2026-02-20T18:55:05Z

@fusmanii great addition!

I've noticed a few more things that we might want to change in CLAUDE.md:

### Deployment Scripts

- Numbered with `.s.sol` suffix: `001DeployHubPool.s.sol`, `004DeployArbitrumAdapter.s.sol`
- Script contracts: `contract Deploy<ContractName> is Script, Test, Constants`

These are no longer numbered :maybe just point to the directory?

## Writing Tests section has a code snippet. Perhaps just point at the example test to save tokens?

Same with ## Deployment Scripts section: I feel like the code snippet here is wasting tokens. Perhaps we just give it an example path

This is a bit dubious (maybe make shorter)

## Configuration

See `foundry.toml` for Foundry configuration. Key settings:

- Source: `contracts/`
- Tests: `test/evm/foundry/`
- Solidity: 0.8.30
- EVM: Prague
- Optimizer: 800 runs with via-ir

This is a bit random: how to improve?

## Linting

yarn lint-solidity    # Solhint for Solidity
yarn lint-js          # Prettier for JS/TS
yarn lint-fix         # Auto-fix all

Replace hardcoded chain list with pointer to broadcast/deployed-addresses.md and remove the Key Libraries section to keep the doc concise. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Signed-off-by: Faisal Usmani <faisal.of.usmani@gmail.com>

fusmanii requested review from bmzig, mrice32, nicholaspai and pxrl as code owners February 17, 2026 00:56

fusmanii marked this pull request as draft February 17, 2026 01:02

nicholaspai reviewed Feb 17, 2026

View reviewed changes

fusmanii requested a review from nicholaspai February 19, 2026 21:13

fusmanii marked this pull request as ready for review February 19, 2026 21:13

fusmanii requested review from grasphoper and tbwebb22 February 19, 2026 21:13

grasphoper reviewed Feb 20, 2026

View reviewed changes

fusmanii and others added 3 commits February 20, 2026 14:51

docs: Trim Supported Chains and remove Key Libraries from CLAUDE.md

24c4460

Replace hardcoded chain list with pointer to broadcast/deployed-addresses.md and remove the Key Libraries section to keep the doc concise. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

scripts/test feedback

70f93f3

Signed-off-by: Faisal Usmani <faisal.of.usmani@gmail.com>

improve linting

bd8185f

Signed-off-by: Faisal Usmani <faisal.of.usmani@gmail.com>

fusmanii requested a review from grasphoper February 20, 2026 23:20

fusmanii added 2 commits February 20, 2026 15:31

add to paths

afdf4e3

Signed-off-by: Faisal Usmani <faisal.of.usmani@gmail.com>

update refferences

a9aac5e

Signed-off-by: Faisal Usmani <faisal.of.usmani@gmail.com>

grasphoper approved these changes Feb 21, 2026

View reviewed changes


		### Protocol Flow

		1. Deposit: User locks tokens in origin SpokePool → `FundsDeposited` event emitted


		### Supported Chains

		SpokePools exist for: Ethereum, Arbitrum, Optimism, Base, Polygon, Polygon zkEVM, zkSync, Scroll, Linea, Blast, Boba, Lisk, WorldChain, Ink, Lens, Mode, and others via `Universal_SpokePool` (generic OP Stack).

Comments

Conversation

fusmanii commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

nicholaspai left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fusmanii commented Feb 17, 2026

Uh oh!

claude bot commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Implementing review feedback

Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

grasphoper commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fusmanii commented Feb 17, 2026 •

edited

Loading

claude bot commented Feb 17, 2026 •

edited

Loading