Trustless Sessions
This document describes a future enhancement to the escrow system. The current implementation uses a trusted facilitator model. Trustless verification is planned for a future release.
Current Trust Model
The current escrow system has a trusted facilitator model:| Component | Trust Level | Notes |
|---|---|---|
| Deposit authorization | Trustless | ERC-3009 signature verified on-chain |
| Off-chain debits | Trusted | Facilitator tracks in database |
| Capture amounts | Trusted | Facilitator decides what to capture |
| Fund recovery | Trustless | Smart contract enforces reclaim after expiry |
What’s Trustless Today
- Deposits: User signs ERC-3009 authorization - cryptographically verified on-chain
- Reclaims: Smart contract enforces reclaim after
authorizationExpiry- no facilitator involvement needed - Bounded exposure: Only deposited amount at risk, never entire wallet
What Requires Trust
- Usage tracking: Facilitator maintains authoritative ledger of session debits
- Capture amounts: Facilitator decides how much to capture - no cryptographic proof submitted
- Billing accuracy: No on-chain verification that captures match actual consumption
Trustless Architecture (Planned)
Overview
The trustless model replaces facilitator trust with cryptographic verification:Cumulative Receipts
For each API request, the facilitator signs a cumulative receipt showing the running total spent. This prevents users from selectively discarding receipts.facilitatorSignature is the key binding:
- Proves facilitator acknowledged this exact (sessionId, nonce, amount) tuple
- Cannot be forged by user (only facilitator has signing key)
sessionIdlinks to on-chain escrow → links to original ERC-3009 authorization
$5.00 cumulative, they cannot claim less was consumed. No selective discarding possible.
Receipts are returned in the
PAYMENT-RESPONSE header. Clients only need to store their latest receipt as proof.Receipt Re-Fetching
If a receipt response is lost (network failure), clients can re-fetch any past receipt:Why This Prevents Attacks
User claims missing receipts
User claims missing receipts
Attack: “I only received 80 receipts, not 100”Defense: Cumulative model means only the highest nonce receipt matters.
If user’s latest receipt shows
{ nonce: 100, cumulative: $5.00 }, the cumulative amount proves total consumption.User discards high-value receipts
User discards high-value receipts
Attack: User discards receipt showing 3.00 receiptDefense: Facilitator counter-disputes with the higher-nonce receipt:
- User provides:
{ nonce: 60, cumulative: $3.00 } - Facilitator counters:
{ nonce: 100, cumulative: $5.00 }with valid signature - Contract verifies: facilitator’s nonce > user’s nonce → dispute rejected
Facilitator over-captures
Facilitator over-captures
Attack: Facilitator captures 5.00Defense: User disputes with their highest receipt:
- User provides:
{ nonce: 100, cumulative: $5.00 }with valid facilitator signature - Facilitator cannot counter (never issued higher receipt)
- Contract verifies: 10.00 captured → facilitator slashed
Facilitator doesn't return receipts
Facilitator doesn't return receipts
Attack: Facilitator processes requests but doesn’t return receiptsDefense: Without a signed receipt, the charge effectively didn’t happen.
- User’s latest receipt shows actual acknowledged consumption
- Facilitator can only capture up to what they signed for
- Incentivizes facilitator to always return receipts
Network drops receipts
Network drops receipts
Attack: Network failure causes user to miss receiptsDefense: Receipt re-fetch endpoint allows recovery:
- User calls
GET /api/receipts/:sessionId/:noncefor any past receipt - User syncs all receipts before challenge window
- User’s responsibility to ensure they have receipts before disputing
Facilitator inflates receipts (LIMITATION)
Facilitator inflates receipts (LIMITATION)
Attack: Facilitator adds fake receipts to merkle tree before committingStatus: NOT FULLY PREVENTED - this is a known limitation.Why it’s hard: Facilitator controls the merkle tree. They can add fake receipts before committing. Without per-request user acknowledgments, we cannot prove delivery.Mitigations (not cryptographic):
- User’s exposure bounded by deposit (maxAmount)
- Reputation damage deters fraud
- User can stop using facilitator and reclaim remaining balance
- Facilitator cannot capture MORE than tree total (still enforced)
Merkle Commitment
Facilitator batches receipts into a merkle tree. This is critical for preventing receipt forgery - once committed, the facilitator cannot create fake receipts.| Property | Value |
|---|---|
| Leaf format | keccak256(abi.encode(receipt)) |
| Tree type | Binary merkle tree |
| Commitment | commitCapture(sessionId, merkleRoot, captureAmount) |
| Collateral | 10% of batch value |
| Purpose | Prevents facilitator from forging receipts after commitment |
Challenge Window
How disputes work
How disputes work
- Facilitator commits
captureAmount = $50with collateral - User sees capture, checks their latest receipt:
{ nonce: 80, cumulative: $30 } - User submits
disputeOverCapture(sessionId, userReceipt) - Contract verifies: facilitator signature valid, 50
- Dispute opens - facilitator has 24-48h to counter
- If no valid counter →
resolveDispute()slashes facilitator, refunds user $20
- Facilitator submits
{ nonce: 100, cumulative: $50 }receipt - Contract verifies: signature valid, nonce 100 > 80
- User’s dispute rejected (they had a higher receipt)
What can be disputed
What can be disputed
- Over-capture: User’s highest receipt shows less than captured amount
- Invalid signature: Facilitator signature on receipt doesn’t verify
Window parameters
Window parameters
| Parameter | Value | Rationale |
|---|---|---|
| Duration | 3-7 days | Balance security vs UX |
| Collateral | 10% of batch | Economic deterrent |
| Slash | 100% of disputed amount | Full user refund |
Smart Contract Interface
Security Properties
| Property | Current | Trustless | Notes |
|---|---|---|---|
| Over-capture (capture > receipts) | Unverifiable | Trustless | User can prove with receipts |
| Receipt inflation (fake receipts) | Trusted | Trusted | Can’t prove delivery without acks |
| Fraud detection | None | Challenge window | For provable over-capture |
| Economic security | None | Collateral slashing | For provable fraud |
| User recourse | Only reclaim | Dispute + refund | For over-capture only |
| Client signing | Once | Once | Preserves UX |
| Bounded exposure | maxAmount | maxAmount | Limits damage from inflation |
Trade-offs
Advantages
- Users can cryptographically prove over-capture fraud
- Economic incentive against fraud (collateral at risk)
- Preserves “sign once” UX (no per-request client signatures)
- Bounded exposure limits damage from any fraud
Disadvantages
- 3-7 day finality delay (receiver waits for funds)
- Client must store receipts locally (storage overhead)
- Requires collateral capital from facilitator
- More complex implementation
- Higher gas costs (commitment transactions)
- Facilitator must sign each response (compute overhead)
- Receipt inflation still trusted - facilitator can add fake receipts to tree
Migration Path
Phase 1: Trusted (Current)
Current model with trusted facilitator. Faster UX, simpler implementation. Trust assumptions clearly documented.
Phase 2: Hybrid (Opt-in)
Signed receipts as optional feature. Users who want trustless can enable. Default remains trusted for faster UX.
Open Questions
Challenge window duration
Challenge window duration
3 days vs 7 days?
- Shorter = better UX for receivers (faster access to funds)
- Longer = more time to detect and dispute fraud
Collateral source
Collateral source
Facilitator-funded vs protocol treasury?
- Facilitator stake = direct incentive alignment
- Treasury = requires governance, less direct incentive
Watchtower service
Watchtower service
Who monitors for fraud?
- Self-monitoring (users watch own sessions)
- Decentralized watchtower network
- Agentokratia-operated service
Gas sponsorship
Gas sponsorship
Who pays for dispute transactions?
- User pays (may disincentivize small disputes)
- Protocol subsidizes (encourages fraud detection)