wallet-arbiter: a hot signer that can only choose between two agreed outcomes #58

New Issue

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

grenade commented

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

Parent: #54

Scope

A wallet-arbiter binary in this workspace (house shape: entities, core logic, data adapters, thin binary) that:

holds per-trade ML-DSA keys pre-derived offline from a dedicated arbiter seed and delivered only for open trades; the seed never touches the host;
approves a proposal only if its bytes equal one of the two templates recorded for that trade, and never approves both for the same trade (enforced by a persisted per-trade decision that cannot be reversed);
runs the BTC judge: for a release, the seller's declared address received at least the agreed amount with the tiered confirmation depth before the trade's deadline block on Quantus, read from our own bitcoind (previous child); for a refund, the deadline passed with no such payment, or both parties requested abort;
enforces per-trade and per-hour value caps, refuses above the cap and hands the trade to the cold path (a Keystone-signed approval through Quantus's quantus_ur QR flow, by a human);
has a kill switch that stops all approvals without stopping the judge's evidence collection;
writes an append-only audit log of every decision with the evidence (Bitcoin txid, heights, template hash) so anyone can reproduce it from public chain data;
exposes only a health endpoint; it takes trade records from the coordinator over an authenticated channel and never accepts a template it did not see at trade creation.

Ships with systemd, sysusers, firewalld and deploy job per convention.

Operator decisions to record here before starting

Fee rate and fee account; confirmation tiers; caps; kill-switch holder; the host.

Acceptance

Unit tests for every invariant in doc/escrow-protocol.md. Against signet plus Planck: approves a valid release, refuses a release whose bytes differ by one byte, refuses a release with N−1 confirmations, refuses a second decision on a decided trade, refuses everything with the kill switch on, and escalates above-cap trades to the cold path with a scannable QR.

Depends on

The protocol document; bitcoind.

Parent: #54 ## Scope A `wallet-arbiter` binary in this workspace (house shape: entities, core logic, data adapters, thin binary) that: - holds per-trade ML-DSA keys **pre-derived offline** from a dedicated arbiter seed and delivered only for open trades; the seed never touches the host; - approves a proposal only if its bytes equal one of the two templates recorded for that trade, and never approves both for the same trade (enforced by a persisted per-trade decision that cannot be reversed); - runs the **BTC judge**: for a release, the seller's declared address received at least the agreed amount with the tiered confirmation depth before the trade's deadline block on Quantus, read from our own bitcoind (previous child); for a refund, the deadline passed with no such payment, or both parties requested abort; - enforces per-trade and per-hour value caps, refuses above the cap and hands the trade to the **cold path** (a Keystone-signed approval through Quantus's `quantus_ur` QR flow, by a human); - has a kill switch that stops all approvals without stopping the judge's evidence collection; - writes an append-only audit log of every decision with the evidence (Bitcoin txid, heights, template hash) so anyone can reproduce it from public chain data; - exposes only a health endpoint; it takes trade records from the coordinator over an authenticated channel and never accepts a template it did not see at trade creation. Ships with systemd, sysusers, firewalld and deploy job per convention. ## Operator decisions to record here before starting Fee rate and fee account; confirmation tiers; caps; kill-switch holder; the host. ## Acceptance Unit tests for every invariant in `doc/escrow-protocol.md`. Against signet plus Planck: approves a valid release, refuses a release whose bytes differ by one byte, refuses a release with N−1 confirmations, refuses a second decision on a decided trade, refuses everything with the kill switch on, and escalates above-cap trades to the cold path with a scannable QR. ## Depends on The protocol document; bitcoind.

grenade added the child label 2026-09-15 14:42:18 +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#58