Module buyer_channel 

On-chain PaymentPool buyer-side service (#744).

The node is the buyer when it pulls content from an upstream provider on a cache miss (ADR 003 §node→node). It owns one PaymentPool and signs vouchers against per-(signer, provider) lanes of that single pool: the deposit fans out across every upstream it pays. This service owns the on-chain half of that path that the off-chain voucher signer in decdn_client leaves open:

• One-time USDC approval. openPool escrows the deposit via safeTransferFrom, so the node holds a standing ERC-20 allowance for the PaymentPool contract. At bootstrap it reads the allowance and, if insufficient, issues a single unlimited approve (ADR 003 § Deposit Economics one-time-approval design).
• Lazy open + reuse. BuyerPoolService::open_or_reuse_pool returns a PoolContext pinned to the upstream provider (with_provider) and carrying the node’s own self-issued capability (with_capability), for the requester to sign vouchers against. It reuses the single pool the node owns, or opens one on the first miss (lazy-on-first-miss). One pool amortizes the deposit + gas across many pulls to many providers.
• Abandonment reclaim. A background sweep completes the grace-window reclaim of a pool the node has closed, refunding the residual and dropping the local record.

Structurally this mirrors crate::payment_settlement::PoolSettlementService: a generic-over-Provider struct that owns a background task and aborts it on drop.

Structs

BuyerPoolService

Buyer-side PaymentPool service. Generic over the alloy Provider (a wallet-filled provider is required for the approve / openPool / topUp / closePool / reclaim write paths). Cheap to construct; owns its background reclaim task.

OpenReported

Typed marker: an open failure this layer has already logged and metered, so the caller-side classification ladder does not restate it.

PoolOpenPending

Expiry stamped on the self-owned capability the buyer signs for its own key. Typed sentinel: the caller’s open_or_reuse_pool budget elapsed while the pool open is still in flight. The open keeps going in a detached task; the caller retries the next candidate and a later miss reuses the pool once it lands (#1143).

TopUpLanded

The result of a pool top-up: the pool’s new total deposit, and how much of the growth belongs to the caller.

Traits

PoolOpener

Object-safe seam over BuyerPoolService (#831).