Enum PoolError 

pub enum PoolError {
    WrongPool {
        expected: B256,
        got: B256,
    },
    WrongProvider {
        expected: Address,
        got: Address,
    },
    AmountRegression {
        last: U256,
        got: U256,
    },
    UnderFold {
        axis: FoldAxis,
        owed: U256,
        got: U256,
    },
    BytesRegression {
        last: U256,
        got: U256,
    },
    CapExceeded {
        cap: U256,
        got: U256,
    },
    BadPreimage {
        index: u8,
        verified: u8,
    },
    Signature(VoucherError),
    Store(StoreError),
}

Failure modes for LaneState::apply_voucher.

Most in-memory variants map to an on-chain PaymentPool.redeem revert; off-chain we surface them before they cost gas. The ordering and fold guards (PoolError::AmountRegression, PoolError::BytesRegression, PoolError::UnderFold) have no revert — redemption is cumulative — and keep the node’s own ledger consistent. PoolError::Store is the off-chain-only variant for persistent-store failures (issue #527).

PartialEq/Eq are intentionally not derived: StoreError::Io wraps std::io::Error, which is not PartialEq. Tests pattern-match on variants via the matches! macro instead of comparing for equality.

Variants

WrongPool

voucher.pool_id does not match the pool this lane draws from — also the “unknown pool” case surfaced by the caller.

Fields

expected: B256

The pool this lane draws from.

got: B256

The pool the voucher named.

WrongProvider

voucher.provider names a node other than this one — a capability voucher scoped to one provider redeemed against another.

Fields

expected: Address

This node’s provider address.

got: Address

The provider the voucher named.

AmountRegression

Cumulative amount is at or below the lane’s signed watermark — a stale or replayed voucher, or one a concurrent same-lane sibling already settled. amount is the sole ordering key (there is no nonce).

Fields

last: U256

The signed watermark the voucher’s cumulative amount had to beat.

got: U256

The cumulative amount it carried.

UnderFold

A voucher under a different chain_root retires the live epoch but does not fold the frontier the live chain proved: its amount or its bytes_delivered falls short of the signed anchor plus verified_index chunks (ADR 003 §Chain length and rollover). It is at or above the signed watermark under a root no sibling names — at exactly the anchor, a root that opens a chain, never a sealed one — so no sibling settled it; the payer under-signs chunks the node holds preimages for. The node refuses it and sends the resume bundle that states the fold the payer owes. A payer short only on bytes_delivered cannot fold from the bundle, because the bundle does not advance its amount.

Fields

axis: FoldAxis

The axis that falls short. The amount is checked first.

owed: U256

The lane’s live claim on axis: signed anchor plus the proved frontier.

got: U256

The cumulative figure the voucher carried on axis.

BytesRegression

Cumulative bytes delivered went down.

Fields

last: U256

Last accepted cumulative bytes.

got: U256

The lower figure the voucher carried.

CapExceeded

Voucher amount exceeds the capability’s spending cap — the contract would revert at redemption.

Fields

cap: U256

The capability’s spending cap.

got: U256

The voucher amount that exceeds it.

BadPreimage

A released hash-chain preimage does not reach the tracked tip in index − verified steps (ADR 003 §Concurrent Streams, Rule 2).

Terminal, and deliberately not watermark-gated on the wire: a preimage carries no signature of its own, so a payment watermark cannot repair a hash-chain mismatch. On-chain the same mismatch reverts BadPreimage, which is caller error rather than transient state.

Fields

index: u8

Chain index of the released preimage.

verified: u8

Index of the tip the lane has verified to.

Signature(VoucherError)

Signature is malformed or signed by the wrong address.

Store(StoreError)

Lane-store write failed; in-memory state is unchanged. See StoreError for the underlying cause. This is surfaced to the caller so the client resends the same voucher instead of proceeding on state the store never took (#527, ADR 003 §Off-chain voucher state persistence).

PROTOCOL NOTE: this is the only PoolError variant for which the client SHOULD retry the same voucher unchanged. The validation variants mean the voucher is permanently invalid for this lane state and retrying is a client bug.

Trait Implementations

impl Debug for PoolError

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

Formats the value using the given formatter.

impl Display for PoolError

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

Formats the value using the given formatter.

impl Error for PoolError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<StoreError> for PoolError

fn from(source: StoreError) -> Self

Converts to this type from the input type.

impl From<VoucherError> for PoolError

fn from(source: VoucherError) -> Self

Converts to this type from the input type.