the escrow protocol, written down: trade state machine, the two call templates, messages #57

New Issue

grenade · 2026-09-15T14:41:23Z

grenade commented

2026-09-15 14:41:23 +00:00

Parent: #54

Scope

doc/escrow-protocol.md and the matching types in wallet-entities: the trade record (id, parties, amounts, BTC address, deadline, multisig address, proposal ids), the state machine (Quoted → EscrowFunded → RefundProposed → BtcPaid → ReleaseProposed → Released | Refunded | Aborted | Expired), the byte-exact construction of the refund and release templates including the fee leg, the rule that the seller never pre-approves release and the arbiter never proposes, and the messages exchanged between wallet, maker daemon, coordinator and arbiter, each signed by the sender's ML-DSA key so the coordinator is a relay and not an authority.

Every safety property from #54 is restated here as a numbered invariant with the mechanism that enforces it, so the arbiter and wallet code can cite invariant numbers in tests.

Acceptance

Reviewed against the spike's measured facts (the first child). The types compile and export to TypeScript. A second reader can construct both templates for a sample trade from the document alone and get the same bytes the spike recorded.

Depends on

The multisig spike.

Parent: #54 ## Scope `doc/escrow-protocol.md` and the matching types in `wallet-entities`: the trade record (id, parties, amounts, BTC address, deadline, multisig address, proposal ids), the state machine (`Quoted → EscrowFunded → RefundProposed → BtcPaid → ReleaseProposed → Released | Refunded | Aborted | Expired`), the byte-exact construction of the refund and release templates including the fee leg, the rule that the seller never pre-approves release and the arbiter never proposes, and the messages exchanged between wallet, maker daemon, coordinator and arbiter, each signed by the sender's ML-DSA key so the coordinator is a relay and not an authority. Every safety property from #54 is restated here as a numbered invariant with the mechanism that enforces it, so the arbiter and wallet code can cite invariant numbers in tests. ## Acceptance Reviewed against the spike's measured facts (the first child). The types compile and export to TypeScript. A second reader can construct both templates for a sample trade from the document alone and get the same bytes the spike recorded. ## Depends on The multisig spike.

grenade added the child label 2026-09-15 14:42:17 +00:00

grenade referenced this issue

2026-09-15 14:42:30 +00:00

epic: btc/qtc swaps through arbitrated multisig escrow #54

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: blackbeard/wallet#57