Skip to main content

SettlementIssuer

Trait SettlementIssuer 

pub trait SettlementIssuer: Send + Sync {
    // Required methods
    fn issue<'life0, 'async_trait>(
        &'life0 self,
        req: IssueRequest,
    ) -> Pin<Box<dyn Future<Output = Result<IssueResponse, PayError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             Self: 'async_trait;
    fn status<'life0, 'life1, 'async_trait>(
        &'life0 self,
        settlement_id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<IssueResponse, PayError>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             'life1: 'async_trait,
             Self: 'async_trait;
}
Expand description

The settlement-issuer contract: only a verified, server-revalidated settlement can cause purchased-credit issuance.

Production impl (AGPL, hyprstream::services::pay):

  1. Verify the attestation’s PQ-hybrid signature against the issuer’s key material (reuse #1129 verify_composite).
  2. Check the restricted settlement store for a committed settlement row matching settlement_id.
  3. Derive the deterministic transfer ID (blake3 of settlement_id + catalog_version + line index — idempotent across retries/crashes).
  4. Call the ledger’s internal credit() (the restricted path, NOT the public LedgerHandle::credit).
  5. Return the idempotent outcome.

A client redirect, client-supplied paid field, Checkout completion without a settled PaymentIntent, or unverified webhook can never reach issuance. The externally-reachable generic ledger credit is NOT on this path.

Required Methods§

fn issue<'life0, 'async_trait>( &'life0 self, req: IssueRequest, ) -> Pin<Box<dyn Future<Output = Result<IssueResponse, PayError>> + Send + 'async_trait>>
where 'life0: 'async_trait, Self: 'async_trait,

Issue credits from a verified settlement attestation.

Idempotent: replaying the same settlement_id returns the original IssueResponse verbatim (same transfer id, same outcome). The server never generates a second issuance after an ambiguous timeout — it retries the same deterministic transfer id.

fn status<'life0, 'life1, 'async_trait>( &'life0 self, settlement_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<IssueResponse, PayError>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Query a prior issuance’s status. Used for retry/recovery when the original issue response was lost (e.g. network failure after the ledger committed).

Implementors§