feat: add tempo session hint reconciliation

[brendanjryan]

Summary

This keeps the session flow backward-compatible while making client channel maintenance simpler and more server-authoritative.

• add optional session hint fields in request.methodDetails: requiredCumulative, acceptedCumulative, spent, and deposit
• populate those hints on the server when request.channelId points at a reusable stored channel
• teach the Tempo session client to hydrate from those hints, prefer requiredCumulative when present, and reconcile runtime state from Payment-Receipt
• keep on-chain recovery as the fallback when only channelId is available
• keep verification behavior unchanged so legacy clients can continue sending any valid advancing voucher
• wire receipt reconciliation into normal fetch flows by letting client methods observe successful responses

Current Request-Response Flow

sequenceDiagram
    participant Client
    participant Server
    participant Chain as On-chain channel

    Client->>Server: GET /resource
    Server-->>Client: 402 + optional channelId reuse hint
    alt channelId present
        Client->>Chain: recover by channelId
        Chain-->>Client: settled amount
        Client->>Client: local cumulative = settled
    else no channelId
        Client->>Client: create new local channel state
    end
    Client->>Client: advance local cumulative by request amount
    Client->>Server: retry with open/voucher credential
    Server-->>Client: 200 + Payment-Receipt
    Client->>Client: mostly keep local counters

Loading

Proposed Request-Response Flow

sequenceDiagram
    participant Client
    participant Server
    participant Chain as On-chain channel

    Client->>Server: GET /resource
    Server-->>Client: 402 + channelId + accepted/spent/deposit/required hints when known
    alt server hints present
        Client->>Client: hydrate runtime snapshot from server state
    else only channelId present
        Client->>Chain: recover by channelId
        Chain-->>Client: settled amount
        Client->>Client: fallback snapshot from chain
    else no reusable channel
        Client->>Client: open new channel
    end
    alt requiredCumulative present
        Client->>Client: sign exact server target
    else no target hint
        Client->>Client: fall back to local cumulative + amount
    end
    Client->>Server: retry with open/voucher credential
    Server-->>Client: 200 + Payment-Receipt(channelId, acceptedCumulative, spent)
    Client->>Client: overwrite runtime snapshot from receipt

Loading

Client Control Flow

flowchart TD
    A[Need credential for session request] --> B{Challenge includes session hints?}
    B -->|Yes| C[Hydrate snapshot from channelId acceptedCumulative spent deposit]
    B -->|No| D{Challenge includes channelId?}
    D -->|Yes| E[Fallback recovery from on-chain settled amount]
    D -->|No| F[Open new channel using deposit or suggestedDeposit]
    C --> G{requiredCumulative present?}
    E --> G
    G -->|Yes| H[Sign exact server target]
    G -->|No| I[Advance local cumulative by request amount]
    I --> H
    F --> J[Receive Payment-Receipt]
    H --> J
    J --> K[Reconcile local runtime state from receipt]
    K --> L[Next request starts from reconciled snapshot]

Loading

Server Control Flow

flowchart TD
    A[Session route receives request] --> B[Resolve chainId escrow and normalized request]
    B --> C{request.channelId maps to reusable stored channel?}
    C -->|Yes| D[Author challenge hints acceptedCumulative spent deposit requiredCumulative]
    C -->|No| E[Emit standard challenge fields only]
    D --> F{Credential supplied?}
    E --> F
    F -->|No| G[Return 402 Payment challenge]
    F -->|Yes| H[Verify open topUp voucher or close action]
    H --> I[Keep legacy acceptance: any valid advancing voucher still works]
    I --> J[Emit Payment-Receipt with channelId acceptedCumulative spent]
    J --> K[Return management response or user content response]

Loading

Why This Rollout Is Safe

• no spec change is required; all new fields are optional and additive
• old clients ignore the new fields and still work
• new clients still fall back to the previous on-chain recovery path when hints are missing
• the server only emits reusable-channel hints when it already has matching stored channel state
• verification behavior remains lenient enough for legacy advancing vouchers rather than requiring an exact echo of requiredCumulative

Testing

• pnpm test src/tempo/Methods.test.ts src/tempo/client/Session.test.ts src/client/internal/Fetch.test.ts src/tempo/server/Session.test.ts
• pnpm check:types
• pnpm check

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/mppx@260

commit: 4d37baf