Threat model

What SettleProof protects, and what it does not.

SettleProof turns post-purchase settlement into a verifiable state machine. It does not magically prove real-world truth; it makes the merchant's delivery claim cryptographic, attributable, and enforceable by escrow rules.

Trust boundaries

Actor	Can do	Cannot do
Agent owner	Create escrow, fund vault, claim refund after TTL	Release merchant funds without a valid merchant attestation
Merchant	Register an attestor key and sign delivery proofs	Move escrowed funds without the custody program accepting proof
Attestor key	Sign a proof hash for a specific escrow and timestamp	Reuse a stale proof outside the accepted freshness window
Relay / API / x402 middleware	Submit signed transactions, expose reads, and sponsor UX	Forge delivery proof without the merchant attestor key
Registry admin	Initialize registry and suspend/slash merchants in current MVP	Bypass escrow release/refund state checks

Core controls in the current programs

Escrow PDA is derived from agent_owner and task_hash, which prevents accidental duplicate escrows for the same task.
release_escrow only runs while EscrowState::Pending.
The merchant account passed to release must match the merchant stored in the escrow.
The attestor program scans previous transaction instructions for an Ed25519 sysvar instruction and checks pubkey, payload, and freshness.
The signed payload binds escrow_pda, proof_hash, and timestamp_le.
Refund does not require the merchant; after TTL, anyone can triggerclaim_refund back to the agent owner.

Known beta limitations

Merchant truth is attributable, not magic

SettleProof verifies that a registered merchant attestor signed a delivery proof. It does not independently inspect the physical world. Fraudulent merchant attestations become attributable evidence for reputation, slashing, and future arbitration.

Attestor key custody

The devnet dashboard exposes the base64 attestor secret by design to demonstrate merchant self-custody: SettleProof cannot sign proof of delivery for the merchant. Mainnet deployments should use HSM/KMS or a merchant-owned signing service, plus rotation policy.

x402 post-handler failure

The middleware settles after the handler returns a body. If settlement fails, it marks response headers with x-payment-settled: false and leaves the escrow pending for TTL refund. Production integrations should treat that as a retry/refund path.

Registry policy

Current registry/admin policy is MVP-grade. Mainnet needs merchant KYB rules, upgrade authority policy, emergency pause design, and public incident procedure.

Replay and stale-proof handling

signed_message = escrow_pda (32 B) || proof_hash (32 B) || timestamp_le (8 B)

Controls:
  • escrow_pda binds proof to one escrow
  • escrow state must be Pending
  • timestamp freshness window rejects stale attestations
  • merchant attestor pubkey must match MerchantAccount
  • task_hash binds x402 request intent to escrow creation

Mainnet readiness checklist

Area	Required before real value
Contracts	External Anchor review/audit + expanded negative tests
USDC	Real mint integration and token-account edge-case review
Keys	Merchant attestor KMS/HSM custody and rotation flow
Registry	KYB policy, admin controls, suspension/slashing process
Operations	Indexer, alerts, event monitoring, incident runbook
Governance	Upgrade authority, pause/emergency policy, disclosure
x402	Retry semantics and settlement-failure UX