Struct PoolContext 

#[non_exhaustive]
pub struct PoolContext {
    pub pool_id: B256,
    pub provider: Address,
    pub deposit: U256,
    pub client_signer: Arc<PrivateKeySigner>,
    pub voucher_domain: Eip712Domain,
    pub prior_bytes_delivered: U256,
    pub prior_amount: U256,
    pub client_binding: Option<ClientBinding>,
    pub capability: Option<SignedCapability>,
}

Per-lane context the requester needs to sign pool vouchers.

A voucher is scoped to a (pool_id, signer, provider) lane. pool_id is the on-chain deposit, the signer is client_signer.address() (the capability key the pool owner delegated spend to — the owner’s own key in the single-user case), and provider is the delivering node this stream pays.

The prior_* fields capture the lane’s cumulative state from earlier streams so a reused lane resumes correctly: vouchers are cumulative across the lane’s lifetime, so the node’s last_bytes_delivered / last_amount are non-zero after the first stream. Starting a fresh stream from zero would be rejected (AmountRegression / BytesRegression). For a brand-new lane pass U256::ZERO for both.

Build one with Self::new or Self::for_pool, then pin it with Self::with_provider and bind it with Self::bind_endpoint.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

pool_id: B256

On-chain poolId the vouchers draw from.

provider: Address

The delivering node this stream pays — the voucher’s provider field. A capability voucher is scoped to one provider and is invalid if redeemed against another.

deposit: U256

On-chain pool deposit (informational here; the node enforces it).

client_signer: Arc<PrivateKeySigner>

Client key that signs vouchers — its address is the lane’s capability signer.

voucher_domain: Eip712Domain

PaymentPool EIP-712 domain.

prior_bytes_delivered: U256

Cumulative bytes paid for on this lane before this stream.

prior_amount: U256

Cumulative amount paid on this lane before this stream.

client_binding: Option<ClientBinding>

Optional ADR 005 client identity binding (address + BindNodeId signature over the requester’s own iroh NodeId, see [sign_client_binding]). Attached to every cdn/client/v1 request’s ext so the serving node can recover the buyer address, confirm it owns the pool (pull_authorized), and reactively populate from its configured origin (#1115). None ⇒ no binding is sent (an unconfigured capacity_bond on the client, or an on-chain/registered requester).

capability: Option<SignedCapability>

Optional pool owner capability delegating spend to client_signer (ADR 003 §Capability delegation, issue_self_capability / buyer_pool::open_pool). Attached to every cdn/client/v1 request’s ext alongside client_binding so the serving node can register the signer on that signer’s first on-chain redemption. Node-agnostic — the same SignedCapability is valid at every node this context streams from, since it grants spend against the pool rather than a specific provider. None ⇒ no capability is sent (the signer is already registered on-chain, or this stream reuses a lane a prior stream this session already delivered the capability for).

Implementations

impl PoolContext

pub const fn new( pool_id: B256, deposit: U256, client_signer: Arc<PrivateKeySigner>, voucher_domain: Eip712Domain, ) -> Self

A context that signs vouchers on pool_id with client_signer under voucher_domain, against a deposit of deposit. It pays no provider yet, starts its lane at zero, and carries no binding or capability: Self::with_provider, Self::bind_endpoint and Self::with_capability add each. A delegated signer, which holds no pool row of its own, starts here.

pub const fn for_pool( state: &BuyerPoolState, client_signer: Arc<PrivateKeySigner>, voucher_domain: Eip712Domain, ) -> Self

Self::new for a pool the buyer store records: its pool_id and committed deposit.

pub const fn with_provider( self, provider: Address, prior_bytes_delivered: U256, prior_amount: U256, ) -> Self

Pin the delivering node this context pays (the voucher’s provider) and seed the lane’s prior cumulative totals. A pool serves many providers, so the target is chosen per-fetch rather than at pool open.

pub fn lane(&self) -> LaneKey

This context’s (pool_id, signer, provider) lane — the scope of one hash chain, and the key every seed is derived under.

pub fn new_ledger(&self) -> PoolLedger

The ledger for this lane, seeded from its persisted cumulative and nothing else.

A chain is never resumed across a restart — the resume folds the frontier the node proved into a signed amount and opens a fresh chain (ADR 003 §Resumption folds) — so there is no chain secret to reproduce here, no counter to read back, and nothing that could have been persisted wrong. What carries across an invocation is the money owed.

pub fn with_client_binding(self, binding: ClientBinding) -> Self

Attach an ADR 005 client identity binding so this context’s cdn/client/v1 requests prove pool ownership to the serving node, enabling reactive cache-miss origin pull-through (#1115). Self::bind_endpoint signs and attaches one in a single call. A hand-built ClientBinding whose ethereum_address and signature don’t correspond (or that doesn’t own the pool) is rejected by the serving node, so this only ever hurts the caller itself.

pub fn bind_endpoint( self, endpoint: &Endpoint, bind_domain: &Eip712Domain, ) -> Result<Self>

Bind endpoint to this context’s signer, so a node that misses the blob in its cache may pull it from its origin for this buyer. Without a binding, such a node refuses the open as NotFound. bind_domain is decdn_incentive::bind_node_id_domain(chain_id, capacity_bond).

Errors

A signing error from client_signer.

pub const fn with_capability(self, capability: SignedCapability) -> Self

Attach a pool owner capability so this context’s cdn/client/v1 requests carry it to the serving node at session start, letting the node register client_signer on that signer’s first on-chain redemption (ADR 003 §Capability delegation). Pass the SignedCapability produced by buyer_pool::open_pool / issue_self_capability; a capability whose signer doesn’t match client_signer or that fails owner-signature recovery only ever hurts the caller itself, exactly like Self::with_client_binding.

Trait Implementations

impl Clone for PoolContext

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PoolContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.