webycash-referee
A separate native Rust hyper service (Lambda-equivalent) that arbitrates the conditional leg of selected exchange flows. This page documents the public surface only. The referee is not part of this website and it never holds funds, bearer secrets, or both halves of a 2-of-2 signing path.
Scope of this document.
Only public, integrator-facing flows are described. Admin endpoints, key material, the transactional swap-state store, and swap-state internals are intentionally out of scope and are never exposed from this repository. Bearer-leg settlement remains referee-mediated and non-atomic.
Public endpoints (overview)
| Method | Path | Purpose |
|---|---|---|
| GET | /status | Read-only liveness and version. No swap state, no balances. |
| GET | /key | The referee signing public key, so wallets can pin the referee identity. |
| POST | /order-request | A taker requests an exact fill against a published, immutable signed order. The maker returns a ZKP-bound encrypted payload for the exact amount. |
| POST | /proof | Submit a proof-attached envelope (proof bytes, public inputs, circuit id/version, verifying-key commitment) bound to the order and party commitments. |
| POST | /ark/release | Request the referee partial signature for an ARK 2-of-2, released only against fresh proof the counter-leg reached the required state. |
| POST | /fail | Signal a fail-to-deliver: the referee issues a signed failure receipt and the holder callback rotates the bearer secret. |
Paths are illustrative of the public flow shape. Exact request/response schemas live with the referee repository, not here. Every transition is idempotent, signed, and audit-logged.
Verification rules
Before using an order public key, the referee verifies the maker PGP fingerprint binding against Extro identity data. ZKP verification binds ciphertext bytes, order id, fill amount, recipient fingerprint, public token hash, and circuit version against the immutable order and party commitments.
An ARK partial signature is released only against fresh proof that the bearer or RGB side reached the required state. The referee never holds both halves of a MuSig2 secret-signature path.
Runtime model
- •A native Rust hyper service (Lambda-equivalent handler), not a generic edge Worker or interpreted runtime.
- •Swap progress lives in a transactional store, advanced only by compare-and-set so a transition cannot double-apply.
- •Single-instance: at most one active instance owns in-flight swaps; there is no multi-writer race on the store.
- •Every transition is conditional, idempotent, signed, and audit-logged. The referee arbitrates; it never holds funds.
Refund & abort
Abort and refund are distinct paths. An aborted swap does not auto-refund; the refund leg releases only on a signed acknowledgement from the bearer seller.
Ack-gated refund
An aborted swap refunds only against a signed acknowledgement from the bearer seller. There is no automatic refund; the refund leg releases on the signed ack, not on a timer.
Cap-exhaustion stays aborted
If the referee exhausts its release cap, the swap stays aborted. The ark-provider recovers its side independently via the ARK refund timeout — the referee does not force a refund.
Restart aborts in-flight (availability)
Because a single instance owns in-flight swaps, a restart aborts those swaps to the refund path. This is an availability tradeoff of the single-instance model, not a custody or atomicity property.
§4.5 bearer front-running (accepted, bounded)
The §4.5 race is accepted and bounded: the ark-provider bears at most one swap of exposure. This is the same bounded-risk, non-atomic bearer leg already documented — not a custody admission.