Core Concepts¶

This section introduces the fundamental concepts of the LedgerFlow authorization protocol.

Warrants¶

A warrant is the central primitive of LedgerFlow. It is a compact, self-contained, cryptographically signed token that binds payment authority to specific conditions.

Key Properties¶

• Self-contained — everything needed for verification is in the warrant bytes
• Short-lived — warrants expire quickly, defaulting to minutes
• Cryptographically bound — signed by the issuer, verifiable offline
• Monotonically attenuated — delegation can only narrow, never expand, authority
• Hash-addressable — warrants are identified by their content digest

Warrant Types¶

Signer Identity¶

The signer identity provides the cryptographic verification layer.

pub struct SignerRef {
    pub alg: SigningAlgorithm,   // Ed25519 or Secp256k1
    pub public_key: Vec<u8>,
    pub key_id: Option<String>,
}

Supported algorithms:

• Ed25519 — preferred for speed and compactness
• Secp256k1 — for blockchain-native key compatibility

The signer key is used to:

1. Verify warrant signatures
2. Verify proof signatures
3. Bind the warrant to a specific agent

Payment Subject¶

The payment subject represents the settlement identity — the account or wallet that will actually pay.

pub struct PaymentSubjectRef {
    pub kind: PaymentSubjectKind,
    pub value: String,
}

pub enum PaymentSubjectKind {
    Caip10,
    FacilitatorAccount,
    ExchangeAccount,
    Opaque,
}

Examples¶

The merchant never sees or interprets the payment subject. It is opaque to the x402-facing surface and only meaningful to the Facilitator.

Constraints¶

Constraints are the typed rules that bound what the warrant authorizes. LedgerFlow uses a closed set of constraint types instead of a generic expression language.

Constraint Types¶

Constraint Composition¶

Constraints are AND-composed. All constraints must pass for the warrant to authorize a payment.

Delegation¶

Delegation allows a warrant holder to issue a sub-warrant to another agent, with narrower authority.

Monotonic Attenuation¶

Delegation can only narrow authority, never expand it:

• A sub-warrant cannot have a longer TTL than its parent
• A sub-warrant cannot include merchants not in the parent's scope
• A sub-warrant cannot exceed the parent's spending limits
• A sub-warrant cannot delegate deeper than max_depth

Delegation Policy¶

pub struct DelegationPolicy {
    pub can_delegate: bool,   // whether this warrant holder can sub-delegate
    pub max_depth: u8,        // maximum remaining delegation depth
}

If can_delegate is false, the warrant is terminal — no further delegation.

Audience Scope¶

Audience scope restricts which merchants can accept a warrant.

pub enum AudienceScope {
    MerchantIds(Vec<String>),   // by stable merchant identifier
    MerchantHosts(Vec<String>), // by hostname suffix
    Any,                         // unrestricted (rare)
}

Use merchant IDs when a stable identifier exists. Host-based scoping is a fallback for merchants without persistent IDs.

Proof-of-Authorization¶

The proof demonstrates that the agent possesses the warrant and is using it for a specific transaction.

What the Proof Binds To¶

1. Challenge — the LedgerFlow challenge ID from the merchant
2. Warrant — the warrant digest
3. Quote — the exact x402 accepted object (SHA-256 hash)
4. Request — the HTTP request (method, authority, path, body hash)
5. Signer — the agent's signing key
6. Freshness — timestamp + nonce

This multi-binding ensures the proof cannot be detached and reused in a different context.

Warrant Digest¶

The warrant digest is the canonical identifier for a warrant:

warrant_digest = "sha256:" + hex(SHA256(canonical_signed_warrant_bytes))

The digest is used as:

• Cache key for warrant storage
• Reference in proof payloads
• Identifier in audit logs

See Also¶

• Protocol — Wire format and serialization details
• Constraints — Full constraint type reference
• Security — Replay protection and threat model