decdn_incentive/

capacity_bond.rs

//! `CapacityBond` contract ABI bindings (ADR 003 § Node Registry, ADR 019).
//!
//! Generated by the `alloy::sol!` macro from the Solidity surface in
//! `contracts/src/CapacityBond.sol`. The read paths the node runtime
//! consumes plus the operator-onboarding write paths — `bond` /
//! `declareMbps` (`decdn node bond`, ADR 019 § Step 2.1–2.2) and
//! `registerNode` with its nonce getters (`decdn node register`, § Step
//! 2.3) — are mirrored. See the macro body below for the exact surface.
//! Two gotchas worth flagging here rather than at the call site:
//!
//! - `getRegisteredNodes` returns the `_registeredAddrs` page (every
//!   registered operator, unfiltered for bond / unbonding / ejection)
//!   alongside a parallel `active[]` that the contract computes with
//!   `isActive(operator)` per entry — the strict "registered AND bond ≥
//!   minBond AND no unbonding AND not ejected" predicate. Callers take
//!   the membership set from `active[]` and keep the full page for the
//!   payout bindings (an unbonding operator is `active == false` but
//!   still payable), with no per-entry round-trip.
//! - `nodeIdOf` returns `(bytes32 nodeId, bool active)` where the bool
//!   is the full `isActive` predicate, not a separate "registered"
//!   flag.

// The `sol!`-generated bindings include macro-emitted code that uses
// patterns workspace clippy denies (raw indexing into ABI fixed-size
// byte arrays, `unwrap` on infallible conversions). These allows scope
// the relaxation to this module only.
#[allow(
    clippy::expect_used,
    clippy::indexing_slicing,
    clippy::panic,
    clippy::unwrap_used,
    clippy::pub_underscore_fields,
    clippy::missing_docs_in_private_items,
    clippy::too_many_arguments,
    missing_debug_implementations,
    missing_docs,
    non_snake_case,
    non_camel_case_types
)]
mod sol_types {
    alloy::sol! {
        #[sol(rpc)]
        contract CapacityBond {
            // -----------------------------------------------------------------
            // Structs
            // -----------------------------------------------------------------

            /// Per-operator registration record. Mirrors the on-chain
            /// struct at `contracts/src/CapacityBond.sol`. Field
            /// order is part of the ABI; do not rearrange.
            struct NodeInfo {
                bytes32 nodeId;
                address ethAddress;
                bool active;
                uint64 lastMultiaddrUpdate;
                bytes multiaddrs;
                string regionHint;
            }

            // -----------------------------------------------------------------
            // View functions (only those consumed by the node runtime)
            // -----------------------------------------------------------------

            /// Full active-bonder predicate: registered AND
            /// `activeBond ≥ minBond` AND no unbonding request in
            /// flight AND not ejected.
            function isActive(address operator) external view returns (bool);

            /// `nodeId`-keyed convenience over `isActive`.
            function isActiveNode(bytes32 nodeId) external view returns (bool);

            /// Operator → `(nodeId, isActive)`. `nodeId` is
            /// `bytes32(0)` if the operator has no binding.
            function nodeIdOf(address operator) external view returns (bytes32 nodeId, bool active);

            /// Raw `nodeId → operator` binding. `address(0)` when the nodeId is
            /// unbound. Read by `decdn node rotate-key` to pre-check the
            /// `NodeIdAlreadyBound` revert before spending gas — `nodeIdOf`
            /// answers the opposite direction and cannot see a collision with a
            /// *different* operator's binding.
            function nodeIdToAddress(bytes32 nodeId) external view returns (address);

            /// Raw `operator → nodeId` binding, the mapping slashability keys
            /// on: `SlashJudge._checkRegistered` reads it through `nodeIdOf` and
            /// deliberately ignores `active`, so a bound-but-deregistered
            /// operator stays slashable (ADR 014). `bindNodeId` swaps it
            /// atomically, which is why key rotation opens no un-slashable
            /// window. `bytes32(0)` when the operator has no binding.
            function addressToNodeId(address operator) external view returns (bytes32);

            /// Unix timestamp of the operator's first bond, or `0` if never
            /// bonded. Write-once — never cleared by `deregisterNode`,
            /// auto-ejection, or `bindNodeId`. Read by `decdn node rotate-key`
            /// to report the `age_ramp` anchor an Ethereum-key rotation
            /// destroys and an iroh-key rotation preserves (ADR 026
            /// § Governance).
            function firstBondedAt(address operator) external view returns (uint64);

            /// On-chain escrow record for one slash (ADR 028 escrow-on-slash).
            /// Field order is ABI-significant — it mirrors `SlashEscrowLib`'s
            /// struct exactly, and a reordering here silently mis-decodes.
            struct SlashRecord {
                address operator;
                uint64 slashedAt;
                uint8 status;
                uint8 offenseType;
                address challenger;
                uint64 appealWindowClose;
                uint256 slashAmount;
                bytes32 evidenceHash;
            }

            /// A slash record was minted. Indexed on `operator`, so a node
            /// filters its own with `topic2` and then point-reads the record —
            /// the live-tail counterpart to the `operatorSlash*` enumeration.
            event SlashRecorded(
                uint256 indexed slashId, address indexed operator, uint64 slashedAt, uint256 slashAmount
            );

            /// Paginated snapshot of `_registeredAddrs` — every operator
            /// with a current registration, **NOT** filtered for bond /
            /// unbonding / ejection — paired with a parallel `active[]`
            /// where `active[i] == isActive(page[i].ethAddress)`, computed
            /// on-chain. Take membership from `active`; keep `page` for the
            /// payout bindings (an unbonding operator is `active == false`
            /// but still present and payable).
            function getRegisteredNodes(uint256 offset, uint256 limit)
                external
                view
                returns (NodeInfo[] memory page, bool[] memory active);

            /// Cardinality of `_registeredAddrs`.
            function getRegisteredNodeCount() external view returns (uint256);

            /// How many slashes have ever been minted against `operator`.
            /// Paired with `operatorSlashIdAt`, this lets a consumer avoid re-scanning
            /// the `Slashed` log tail from a block floor on every start: walk
            /// backwards from `count - 1` and stop at the first record whose
            /// `appealWindowClose` has already passed.
            function operatorSlashCount(address operator) external view returns (uint256);

            /// The `slashId` at `index` in `operator`'s append-only slash list.
            /// Append-only and never reordered, so indices are stable across
            /// calls and no pinned-block read is required. Reverts
            /// `SlashIndexOutOfRange` past the end rather than returning a zero
            /// id, which would alias the legitimate `slashId == 0`.
            function operatorSlashIdAt(address operator, uint256 index) external view returns (uint256);

            /// Full escrow record for `slashId`.
            ///
            /// `appealWindowClose` here is the **base** deadline (`slashedAt +
            /// appealFilingWindow`), fixed at mint. The deadline the contract
            /// actually enforces is `appealWindowClose + pausedTotal`
            /// ([`SlashEscrowLib`] adds the global pause offset at finalize /
            /// appeal-open time), so a consumer that gates on the deadline MUST
            /// read [`pausedTotal`](Self::pausedTotal) at the same block and add
            /// it. `offenseType` and `evidenceHash` are persisted on the record
            /// precisely so it is self-sufficient — the `CapacityBond.Slashed`
            /// event carries the offense but no `slashId`, and `SlashRecorded`
            /// carries the `slashId` but no offense.
            function getSlashRecord(uint256 slashId) external view returns (SlashRecord memory);

            /// Global cumulative appeal-window pause offset, in seconds. Every
            /// slash's enforced deadline is
            /// `getSlashRecord(id).appealWindowClose + pausedTotal`; the offset
            /// only ever grows (`_unpause` credits each ended pause interval), so
            /// it uniformly extends every open window and preserves base-close
            /// ordering.
            function pausedTotal() external view returns (uint64);

            /// The operator's raw registration record. `active` here is
            /// `_nodes[operator].active` alone — the flag `deregisterNode`
            /// gates on — NOT the composite `isActive`, which additionally
            /// requires bond over `minBond` and no unbonding request. An
            /// operator mid-unbonding is `isActive == false` yet still
            /// deregisterable, so `decdn node deregister` reads this (#1359).
            /// Zero-valued for a never-registered address.
            function getNodeByAddress(address ethAddress) external view returns (NodeInfo memory);

            /// Whether the operator was removed by the contract rather than by
            /// choice — auto-ejection on slashing, or a `BLACKLIST_ROLE`
            /// `ejectNode`. Both inactive states exit the same way
            /// (`declareMbps(0)` + unbond), but they differ on RE-ENTRY: an
            /// ejected operator's `registerNode` reverts `OperatorEjected` until
            /// the latch clears, so the advice has to differ (#1359).
            function ejected(address operator) external view returns (bool);

            // -----------------------------------------------------------------
            // Bonding views + writes (ADR 019 § Step 2.1–2.2, consumed by
            // `decdn node bond`)
            // -----------------------------------------------------------------

            /// The bonded ERC-20 (TOKEN). Read so `decdn node bond` can build
            /// the `approve` call without a separate config field.
            function token() external view returns (address);

            /// Active bond posted by `operator` (base units). Top-up target
            /// math reads this to bond only the shortfall.
            function activeBond(address operator) external view returns (uint256);

            /// Global minimum bond floor (base units) enforced by
            /// `registerNode`, independent of the capacity curve.
            function minBond() external view returns (uint256);

            /// Governable lower bound of the declarable-capacity band (Mbps).
            /// Read so `decdn node bond` can reject an out-of-band tier before
            /// bonding, rather than stranding a bond behind a `declareMbps`
            /// revert.
            function minCapacityMbps() external view returns (uint256);

            /// Governable upper bound of the declarable-capacity band (Mbps).
            function maxCapacityMbps() external view returns (uint256);

            /// Operator's currently declared capacity tier (Mbps). Read so a
            /// re-run can skip a redundant `declareMbps`.
            function declaredMbps(address operator) external view returns (uint256);

            /// Active bond required to declare `mbps` of capacity under the
            /// current curve (`k × mbps^α`). `decdn node bond` sizes the
            /// deposit from this rather than recomputing the curve off-chain.
            function bondRequired(uint256 mbps) external view returns (uint256);

            /// Deposit `amount` TOKEN into the operator's active bond
            /// (additive). Requires a prior ERC-20 `approve`.
            function bond(uint256 amount) external;

            /// Self-attest serving capacity `mbps`. Reverts if `activeBond <
            /// bondRequired(mbps)` or `mbps` is outside the governable band.
            function declareMbps(uint256 mbps) external;

            /// Start the unbonding window for `amount` base units (ADR 026
            /// § Capacity-bond curve — lowering a bond is `requestUnbond` +
            /// `unbond`, there is no atomic refund). Moves `amount` out of
            /// `activeBond` immediately and locks it for `unbondingPeriod`.
            /// Reverts if a request is already in flight, or if the remaining
            /// active bond would fall below `bondRequired(declaredMbps)` — note
            /// the curve, NOT `minBond`, is the floor here, so the operator can
            /// legally unbond into an inactive state. `decdn node unbond`
            /// pre-checks both so neither surfaces as a raw revert.
            function requestUnbond(uint256 amount) external;

            /// Withdraw a matured unbonding request (`block.timestamp >=
            /// unlockAt`), transferring the TOKEN back to the operator and
            /// clearing the request.
            function unbond() external;

            /// Operator's in-flight unbonding request as `(amount, unlockAt)`;
            /// `amount == 0` means none. The auto-getter of a
            /// `UnbondingRequest` mapping, so the static struct flattens to
            /// this tuple. (Unlike `nodeIdOf` above, which is a hand-written
            /// multi-return view rather than a struct getter.) A
            /// non-zero `amount` also makes `isActive` false for the whole
            /// window, which is why `decdn node unbond` warns before starting
            /// one.
            function unbondingOf(address operator) external view returns (uint256 amount, uint256 unlockAt);

            /// Governable unbonding window in seconds (ADR 026 § Capacity-bond
            /// curve — 14 days by default). Read so the CLI can report the
            /// unlock time it is about to commit the operator to.
            function unbondingPeriod() external view returns (uint256);

            /// Governable ceiling (bytes) on the packed `multiaddrs` field an
            /// operator may publish. `updateMultiaddrs` reverts
            /// `MultiaddrsTooLarge` above it; `decdn node update-multiaddrs`
            /// pre-checks against it so the cap surfaces before the send.
            function maxMultiaddrSize() external view returns (uint256);

            /// Governable minimum interval (seconds) between an operator's
            /// `updateMultiaddrs` calls. `readyAt = lastMultiaddrUpdate +
            /// multiaddrUpdateCooldown`; a call before it reverts
            /// `MultiaddrCooldownActive(readyAt)`. Read so the CLI can report
            /// the ready time rather than surface a bare revert.
            function multiaddrUpdateCooldown() external view returns (uint256);

            /// Region self-attestation state for `operator` (ADR 030), as
            /// `(regionHint, regionPrev, regionLastChanged, regionStabilityWindow)`:
            /// the current on-chain region, the previous region retained for the
            /// blacklist-scope ripening predicate, the unix-second stamp of the
            /// last change (registration counts), and the governable cooldown
            /// between `updateRegion` calls. `decdn node update-region` reads it to
            /// report the current region and the cooldown state — `readyAt =
            /// regionLastChanged + regionStabilityWindow`; a call before it reverts
            /// `RegionCooldownActive(readyAt)` — before the send.
            function regionScopeData(address operator)
                external
                view
                returns (
                    string memory regionHint,
                    string memory regionPrev,
                    uint64 regionLastChanged,
                    uint256 regionStabilityWindow
                );

            /// Per-operator EIP-712 `BindNodeId` nonce. Feeds the
            /// `bindingSignature` digest at registration time (ADR 019
            /// § Step 2.3). `0` for an operator that has never bound.
            function bindingNonce(address operator) external view returns (uint64);

            /// Per-nodeId registration nonce. Feeds the ed25519
            /// ownership-proof digest (ADR 019 § Step 2.3); incremented on
            /// deregistration / rebinding so a fresh signature is required on
            /// re-onboarding. `0` for a never-registered nodeId.
            function registrationNonce(bytes32 nodeId) external view returns (uint64);

            /// Governance-canonical operator-terms hash new registrants must
            /// accept (ADR 019 § Terms Acceptance). `registerNode` requires the
            /// submitted `termsHash` to equal this value.
            function currentTermsHash() external view returns (bytes32);

            // -----------------------------------------------------------------
            // Node registry write path (ADR 019 § Step 2.3)
            // -----------------------------------------------------------------

            /// Atomically bind `nodeId` ↔ `msg.sender` and activate the node.
            /// Verifies the EIP-712 `bindingSignature` over
            /// `RegisterNode(nodeId, bindingNonce[msg.sender], termsHash)` and
            /// the ed25519 `ed25519Signature` over the ownership digest
            /// (`decdn_incentive::node_register::ownership_message_digest`).
            /// `termsHash` must equal `currentTermsHash` (ADR 019 § Terms
            /// Acceptance). Reverts if the operator's bond is below `minBond` /
            /// the declared-capacity curve — Phase 2.1/2.2 (`bond` /
            /// `declareMbps`) are a precondition.
            function registerNode(
                bytes32 nodeId,
                bytes multiaddrs,
                string regionHint,
                bytes32 termsHash,
                bytes bindingSignature,
                bytes ed25519Signature
            ) external;

            /// Leave the active set: clears `_nodes[msg.sender].active`, bumps
            /// `registrationNonce[nodeId]`, and clears `declaredMbps` —
            /// releasing the `bondRequired(declaredMbps)` floor that
            /// `requestUnbond` enforces, which is what makes a full bond exit
            /// reachable (ADR 003 § Node Registry, ADR 026 § Capacity-bond
            /// curve). Does NOT move the bond. Reverts `NodeNotActive` unless
            /// the caller is currently registered.
            function deregisterNode() external;

            /// Rebind the caller's operator address to `nodeId` — the iroh
            /// node-key rotation path (`appendix-operator-key-rotation.md`
            /// § iroh node-key rotation only), wrapped by `decdn node
            /// rotate-key --key iroh`.
            ///
            /// Atomically deletes the old `nodeId → address` mapping (bumping
            /// its `registrationNonce`) and writes the new one, so the operator
            /// is never un-slashable mid-rotation. The bond, `declaredMbps`,
            /// `firstBondedAt`, and every open lane paying this operator
            /// survive untouched — all of them key on the Ethereum address,
            /// which does not change.
            ///
            /// `bindingSignature` covers `BindNodeId(nodeId,
            /// bindingNonce[msg.sender])` — the terms-free typehash, NOT
            /// `RegisterNode`: rebinding does not re-accept operator terms
            /// (ADR 019 § enforcement at registration only). `ed25519Signature`
            /// is the **new** node key's proof over
            /// `node_register::ownership_message_digest`. Reverts
            /// `NodeIdAlreadyBound` if a different operator holds `nodeId`,
            /// `ZeroNodeId` on an all-zero id, and `InvalidBindingSignature` /
            /// `InvalidEd25519Signature` on a mis-built digest.
            function bindNodeId(bytes32 nodeId, bytes bindingSignature, bytes ed25519Signature) external;

            /// (Re)publish the caller's packed `multiaddrs` (ADR 019 §
            /// Multiaddr encoding — a sequence of `(uint16 length, bytes
            /// data)` entries, the same `node_register::pack_multiaddrs`
            /// framing `registerNode` takes). Wrapped by `decdn node
            /// update-multiaddrs`, the only non-destructive way for an active
            /// operator to promote direct QUIC addresses after registering an
            /// empty set. Stores the bytes into `_nodes[msg.sender].multiaddrs`
            /// and stamps `lastMultiaddrUpdate`. Reverts `NodeNotActive` unless
            /// the caller is registered, `MultiaddrsTooLarge(size, ceiling)`
            /// above `maxMultiaddrSize`, and `MultiaddrCooldownActive(readyAt)`
            /// within `multiaddrUpdateCooldown` of the last update — all three
            /// pre-checked by the CLI.
            function updateMultiaddrs(bytes multiaddrs) external;

            /// (Re)attest the caller's region (ADR 030), storing `newRegion` into
            /// `_nodes[msg.sender].regionHint`, retaining the prior value in
            /// `regionPrev`, and stamping `regionLastChanged`. Wrapped by `decdn
            /// node update-region`, the non-destructive way for an active operator
            /// to correct or move its region after registering. Reverts
            /// `NodeNotActive` unless the caller is registered,
            /// `RegionHintTooLong(size, ceiling)` above `MAX_REGION_HINT_BYTES`,
            /// and `RegionCooldownActive(readyAt)` within `regionStabilityWindow`
            /// of the last change — the active and cooldown gates pre-checked by the
            /// CLI (a validated ISO 3166-1 alpha-2 code never nears the ceiling).
            function updateRegion(string newRegion) external;

            // -----------------------------------------------------------------
            // Events that mutate active-set membership
            // -----------------------------------------------------------------

            /// Operator (re)published its dialable addresses via
            /// `updateMultiaddrs`. `nodeId`-indexed; carries the new packed
            /// `multiaddrs` field.
            event NodeMultiaddrUpdated(bytes32 indexed nodeId, bytes multiaddrs);

            /// Operator (re)attested its region via `updateRegion`.
            /// `nodeId`-indexed; carries the prior and new region strings.
            event RegionUpdated(bytes32 indexed nodeId, string oldRegion, string newRegion);

            /// Node activated via `registerNode`. `nodeId`-indexed.
            event NodeRegistered(
                bytes32 indexed nodeId,
                address indexed ethAddress,
                bytes multiaddrs,
                string regionHint,
                uint64 bindingNonce,
                uint64 registrationNonce
            );

            /// Node deactivated via `deregisterNode`. `nodeId`-indexed.
            event NodeDeregistered(bytes32 indexed nodeId);

            /// A `nodeId ↔ operator` binding was written, by either
            /// `registerNode` or `bindNodeId`. The confirmation
            /// `decdn node rotate-key` looks for in the bind receipt.
            /// `bindingNonce` is the nonce the accepted signature consumed, not
            /// the post-increment value.
            event NodeIdBound(address indexed ethAddress, bytes32 indexed nodeId, uint64 bindingNonce);

            /// Node deactivated by `slash` or `ejectNode` dropping
            /// bond below `minBond / 2`. `nodeId`-indexed.
            event NodeAutoEjected(bytes32 indexed nodeId, uint256 remainingBond);

            /// Node deactivated by `ContentBlacklist`-role caller.
            /// **Operator-indexed** — translate via `nodeIdOf`.
            event EjectedByBlacklist(address indexed operator);

            /// Previously ejected operator brought bond back to
            /// `minBond` via `bond()`. **Operator-indexed** —
            /// translate via `nodeIdOf`.
            event Reinstated(address indexed operator);

            /// Operator requested unbonding; flips `isActive` to
            /// `false` immediately even though the operator stays in
            /// `_registeredAddrs`. **Operator-indexed** — translate
            /// via `nodeIdOf`.
            event UnbondingRequested(
                address indexed operator,
                uint256 amount,
                uint256 unlockAt,
                uint256 newActiveBond
            );
        }
    }
}

pub use sol_types::CapacityBond;