mechanisms/evm/batch-settlement/server

Claim collects claimable vouchers and submits them in batches.

ClaimAndSettle claims any eligible vouchers, then settles when claims fired.

GetClaimableVouchers returns voucher claims ready for onchain settlement. Skips entries whose chargedCumulativeAmount does not exceed totalClaimed.

GetWithdrawalPendingSessions returns sessions that have a pending payer-initiated withdrawal (withdrawRequestedAt > 0).

Refund refunds the listed channels. Channels with a live in-flight request reservation are skipped. Pass an empty slice to refund every stored channel.

RefundIdleChannels cooperatively refunds channels that have been idle for at least idleSecs seconds and still hold a non-zero balance.

Settle transfers claimed funds to the receiver via a settle(receiver, token) call.

Start begins auto-settlement with the given configuration. Each non-zero *IntervalSecs schedules an independent timer; jobs are queued and drained in {claim, settle, refund} priority.

AfterSettleHook returns a hook that updates local session state after the facilitator settles. Pure state-update - Result.Extra is NOT mutated here; EnrichSettlementResponse runs after this hook and additively adds the server-owned chargedCumulativeAmount (and chargedAmount for deposits).

For deposits: read the facilitator's channelState snapshot, compute chargedCumulativeAmount = current + requirements.amount, store the new session state, and remember the channel snapshot so EnrichSettlementResponse can echo chargedCumulativeAmount back to the client.

For refunds: read the facilitator's post-refund channelState, store the updated session (or delete on full-refund when balance <= chargedCumulative).

For vouchers: state was already updated in BeforeSettleHook; nothing to do.

AfterVerifyHook atomically reserves the channel and persists session state after successful verification. Busy / stale / missing-context outcomes abort.

For refund vouchers (refund: true), additionally returns a SkipHandler directive so the resource server bypasses the application handler and settles inline.

BeforeSettleHook returns a hook that implements the core batched settlement logic. For voucher payloads it:

• Increments chargedCumulativeAmount locally via UpdateChannel
• Returns a Skip result so onchain settlement is NOT triggered
• If the voucher has refund=true, rewrites the payload to a refund settle action that the facilitator will execute onchain

For deposit payloads it annotates responseExtra with the new charged amount. All other payload types pass through to the facilitator.

BeforeVerifyHook binds the claimed channelId and reads a channel snapshot. This phase performs no storage mutation. Reservation + persist happen in AfterVerifyHook after successful verification.

ClearPendingRequest clears this request's pending reservation in storage, without affecting any newer reservation that may have replaced it. If the stored channel only existed for this reservation (no snapshot), the channel record is deleted entirely.

CreateChannelManager creates a new channel manager for auto-settlement rooted at this scheme's receiver and the network's default settlement asset.

Pass a custom token via NewBatchSettlementChannelManager directly when you need a non-default settlement asset for this manager.

DeleteSession removes a session for a channel.

EnhancePaymentRequirements adds batched-specific fields to payment requirements.

EnrichPaymentRequiredResponse implements x402.PaymentRequiredEnricher. On a cumulative-amount-mismatch verify failure it adds corrective ChannelState (sourced first from a BeforeVerifyHook snapshot, then from storage) to each matching batch-settlement requirement so the client can resync.

EnrichSettlementPayload supplies server-owned settlement-payload fields before the facilitator settles. For refund payloads it returns the additive {amount?, refundNonce, claims, refundAuthorizerSignature?, claimAuthorizerSignature?} map; the framework's additive policy (AssertAdditivePayloadEnrichment) rejects any attempt to overwrite existing client-set keys.

Returns nil for non-refund payloads. Returns a structured error on validation failure; the framework converts it into a settle abort with the error string as the reason.

EnrichSettlementResponse supplies server-owned settlement-response fields after the facilitator settles. Returns the additive {channelState: {chargedCumulativeAmount}, chargedAmount?} map so the framework can deep-merge it into result.extra without overwriting the channelState.{balance,totalClaimed,...} fields the facilitator already populated.

The snapshot is set by EnrichSettlementPayload (refund) or by AfterSettleHook (deposit) via RememberChannelSnapshot.

GetAssetDecimals implements AssetDecimalsProvider.

GetOnchainStateTtlMs returns the configured TTL (in ms) for trusting cached onchain channel state for local voucher verification.

GetReceiverAddress returns the receiver address.

GetReceiverAuthorizerAddress returns the receiver authorizer's address.

GetSession retrieves a session for a channel.

GetStorage returns the underlying session storage.

GetWithdrawDelay returns the configured withdraw delay.

MergeRequestContext merges fields into the per-payload request context, creating one if none exists.

OnSettleFailureHook releases a reservation when facilitator settlement fails.

OnVerifiedPaymentCanceledHook returns a hook that releases this request's pending reservation when the resource handler errors or returns a non-2xx response.

OnVerifyFailureHook releases a reservation when facilitator verification fails.

ParsePrice parses a price and converts it to an asset amount.

ReadRequestContext returns the per-payload request context without clearing it.

RegisterMoneyParser registers a custom money parser.

RememberChannelSnapshot stores a channel snapshot keyed to a specific payload so EnrichPaymentRequiredResponse can echo it in the corrective 402.

Scheme returns the scheme identifier.

SignClaimBatch signs a ClaimBatch EIP-712 message.

SignRefund signs a cooperative refund EIP-712 message.

TakeChannelSnapshot reads and clears the channel snapshot for a payload.

TakeRequestContext reads and clears the per-payload request context.

UpdateSession updates or creates a session for a channel.

ValidateFacilitatorSupport rejects startup when this scheme delegates the receiver-authorizer role but the facilitator does not advertise a usable receiverAuthorizer.

CompareAndSet uses an exclusive lock file to serialise concurrent writers. The mkdir call ensures the very first CompareAndSet on a fresh directory does not fail with ENOENT on the lock file.

UpdateChannel atomically reads, mutates, and writes a channel record under an exclusive lock file. Returning a different pointer commits the new session; returning nil deletes the file; returning the same pointer is treated as a no-op (status: unchanged).