Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,22 +44,22 @@ Six top-level contracts in [`src/`](src/), grouped by role:

### Asset custody (permanent, audited, not versioned)

- **[CelerWallet](src/CelerWallet.sol)** — Multi-owner / multi-token wallet shared by
the whole network; the only contract that holds funds. Operated by a `CelerLedger`.
- **[AgentPayWallet](src/AgentPayWallet.sol)** — Multi-owner / multi-token wallet shared by
the whole network; the only contract that holds funds. Operated by a `AgentPayLedger`.
- **[PayRegistry](src/PayRegistry.sol)** — Append-only global record of resolved
conditional-payment results, indexed by `payId = keccak256(payHash, setterAddress)`.
- **[VirtContractResolver](src/VirtContractResolver.sol)** — On-demand deployer for
virtual (off-chain) contracts when disputes need them on-chain.

`CelerLedger` additionally depends on the chain's canonical wrapped-native
`AgentPayLedger` additionally depends on the chain's canonical wrapped-native
(WETH9-style) contract for the multi-party-funding path on native channels —
wired at deploy time via the `_nativeWrap` constructor argument. Users still
deposit and receive native; wrapped-native is internal plumbing only.

### Channel & payment logic (versioned, peer-controlled migration)

- **[CelerLedger](src/CelerLedger.sol)** — Channel state machine and primary user entry
point; operator of `CelerWallet`. Logic split across libraries in
- **[AgentPayLedger](src/AgentPayLedger.sol)** — Channel state machine and primary user entry
point; operator of `AgentPayWallet`. Logic split across libraries in
[`src/lib/ledgerlib/`](src/lib/ledgerlib/).
- **[PayResolver](src/PayResolver.sol)** — On-chain resolution of conditional payments;
evaluates conditions or vouched results and writes outcomes to `PayRegistry`.
Expand All @@ -78,9 +78,9 @@ For per-contract APIs, constructor args, events, and storage, see

```
src/
├── CelerLedger.sol # channel state machine; primary entry point (versioned)
├── CelerLedgerMock.sol # test-only ledger variant
├── CelerWallet.sol # multi-owner asset custodian (permanent)
├── AgentPayLedger.sol # channel state machine; primary entry point (versioned)
├── AgentPayLedgerMock.sol # test-only ledger variant
├── AgentPayWallet.sol # multi-owner asset custodian (permanent)
├── PayRegistry.sol # global resolved-payment registry (permanent)
├── PayResolver.sol # conditional-pay resolution (versioned)
├── RouterRegistry.sol # optional relay-router registry
Expand All @@ -89,10 +89,10 @@ src/
├── interfaces/ # I*.sol — public ABI surface
└── lib/
├── data/ # auto-generated protobuf decoders + .proto sources
└── ledgerlib/ # CelerLedger logic split into libraries (EIP-170 size-split)
└── ledgerlib/ # AgentPayLedger logic split into libraries (EIP-170 size-split)

test/ # Foundry tests
├── invariants/ # property-based / fuzz invariants for CelerLedger
├── invariants/ # property-based / fuzz invariants for AgentPayLedger
├── utils/ # shared test base + fixtures + signing utils
└── *.t.sol # per-contract unit tests
script/ # Forge deploy scripts
Expand Down
22 changes: 11 additions & 11 deletions docs/architecture-summary.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,13 @@ conditional payments through routed paths. The blockchain is only touched for de
withdrawals, settlement, dispute resolution, and (rarely) deploying virtual contracts.

The six contracts split cleanly into two roles. **Asset custody** lives in
permanent, audited contracts that change rarely or never (`CelerWallet`, `PayRegistry`,
permanent, audited contracts that change rarely or never (`AgentPayWallet`, `PayRegistry`,
`VirtContractResolver`). **Channel and payment logic** lives in *versioned*
contracts (`CelerLedger`, `PayResolver`) that peers can cooperatively migrate between
contracts (`AgentPayLedger`, `PayResolver`) that peers can cooperatively migrate between
without disturbing the assets — see [Decentralized Versioning][versioning] in the full
docs. `RouterRegistry` is an optional advertisement registry for relay nodes.

`CelerLedger` additionally depends on the chain's canonical wrapped-native
`AgentPayLedger` additionally depends on the chain's canonical wrapped-native
(wrapped-native) contract for the multi-party-funding path on native channels —
wired at deploy time, never user-visible. Users still deposit and receive native.

Expand All @@ -51,16 +51,16 @@ These shape every choice in the codebase. Read the full text in

A sixth, structural principle: **decentralized, peer-controlled versioning** — instead
of admin-controlled proxy upgrades, channel peers cooperatively migrate to new
`CelerLedger` / `PayResolver` versions. This eliminates trusted upgrade controllers and
keeps asset custody (`CelerWallet`) immutable.
`AgentPayLedger` / `PayResolver` versions. This eliminates trusted upgrade controllers and
keeps asset custody (`AgentPayWallet`) immutable.

[system-overview]: https://agentpay-docs.celer.network/agentpay-architecture/system-overview

---

## Channel state machine

The status of a payment channel inside `CelerLedger` (see
The status of a payment channel inside `AgentPayLedger` (see
[`LedgerStruct.ChannelStatus`](../src/lib/ledgerlib/LedgerStruct.sol)):

```
Expand All @@ -79,13 +79,13 @@ The status of a payment channel inside `CelerLedger` (see
(on the OLD ledger)
```

- **Uninitialized** — channel does not yet exist in this `CelerLedger` instance.
- **Uninitialized** — channel does not yet exist in this `AgentPayLedger` instance.
- **Operable** — active; deposits, withdrawals, snapshots, off-chain pay forwarding.
- **Settling** — `intendSettle` opened a challenge window; counterparty can submit
newer simplex states.
- **Closed** — terminal; balances paid out, channel finalized.
- **Migrated** — terminal *on the old ledger*; the channel continues life on a new
`CelerLedger` version. Migration outranks `intendSettle`: peers can migrate even
`AgentPayLedger` version. Migration outranks `intendSettle`: peers can migrate even
while `Settling`, returning the channel to `Operable` on the new ledger.

For the full state-transition rules, see
Expand All @@ -99,8 +99,8 @@ For the full state-transition rules, see

| Contract | Role | Versioned? |
|---|---|---|
| [`CelerWallet`](../src/CelerWallet.sol) | Multi-owner / multi-token asset custodian. One global instance. | No (permanent) |
| [`CelerLedger`](../src/CelerLedger.sol) | Channel state machine + primary user entry point. Operator of `CelerWallet`. | **Yes** |
| [`AgentPayWallet`](../src/AgentPayWallet.sol) | Multi-owner / multi-token asset custodian. One global instance. | No (permanent) |
| [`AgentPayLedger`](../src/AgentPayLedger.sol) | Channel state machine + primary user entry point. Operator of `AgentPayWallet`. | **Yes** |
| [`PayResolver`](../src/PayResolver.sol) | On-chain conditional-pay resolution; writes results to `PayRegistry`. | **Yes** (chosen per-payment) |
| [`PayRegistry`](../src/PayRegistry.sol) | Global `payId → (amount, deadline)` map; immutable, public reference. | No (permanent) |
| [`VirtContractResolver`](../src/VirtContractResolver.sol) | On-demand deployment of virtual contracts during disputes. | No (permanent) |
Expand All @@ -124,7 +124,7 @@ not violate them.
never lowered. This protects relay nodes from collusive source/dest pairs.
- Migration outranks `intendSettle`. Cooperative migration always wins over a unilateral
settle in flight.
- `CelerWallet` has exactly one **operator** (a `CelerLedger` instance). Operatorship
- `AgentPayWallet` has exactly one **operator** (a `AgentPayLedger` instance). Operatorship
transfer is the migration pivot; only the current operator (or all owners
cooperatively, via `voteForOperator`) can transfer it.

Expand Down
Loading
Loading