Signing relay API

A shared-account close needs enough signer weight on one transaction. The relay in src/server/signing-relay.ts holds that transaction, merges each co-signer's signature into it, and streams every change to the people watching.

The relay never sees a secret key. It holds only the transaction envelope, a public artifact, in process memory, until the request expires.

RoutesCopy Anchor Link

All four run on the Node.js runtime, are force-dynamic, and rate-limit per client address, keyed as described in Self-hosting.

The id is the transaction hash, hex-encoded, so a co-signer can check that the transaction they fetch is the one the link names.

PublishCopy Anchor Link

POST /api/plan
{ "network": "mainnet", "xdr": "<base64 envelope signed by one signer>" }

Success answers { "ok": true, "id": "<64-hex hash>" }. CAPACITY answers 503 and every other refusal 400 with code and reason. A body over 32,768 bytes answers 413, and a throttled request 429.

FetchCopy Anchor Link

GET /api/plan/[id]

Success answers the request's public state:

{
  "ok": true,
  "network": "mainnet",
  "xdr": "<base64>",
  "account": "G...",
  "signers": [{ "key": "G...", "weight": 1 }],
  "thresholds": { "low": 0, "med": 2, "high": 2 },
  "expiresAt": 1760000000000
}

signers and thresholds are the account's, read from Horizon at publish. A missing or expired request answers 404 NOT_FOUND.

SignCopy Anchor Link

POST /api/plan/[id]/sign
{ "xdr": "<base64 envelope carrying the co-signer's signature>" }

Only xdr is read; the network comes from the stored request. Success answers the full public state after the merge, in the same shape as Fetch. NOT_FOUND answers 404, and BAD_XDR, REJECTED and TOO_MANY_SIGNATURES answer 400.

EventsCopy Anchor Link

GET /api/plan/[id]/events

A text/event-stream. Each event carries the full public state as JSON: one on open, and one whenever a signature is accepted. A : ping comment keeps the stream open every 25 seconds. The stream closes when the request expires.

Refusals are plain text: 404 signing request not found, and 503 too many live listeners for this signing request with retry-after: 30 when the request already has 50 listeners, or 3 from the same client address. On a refused stream the browser client (src/lib/multisig/plan-client.ts) polls GET /api/plan/[id], starting at 5 seconds and backing off to 60, and tries the stream again every 60 seconds.

Publish guardsCopy Anchor Link

createPlan sweeps expired requests, then checks in this order:

Guard 3 identifies the account by the account merge's effective source, and refuses a transaction whose operations act on any other account, so a publisher cannot read one account's signer set while merging another.

Guard 12 is the proof of control: only an account's own signer can open a request to close it.

Between guards 12 and 13, the relay manages the account's other open requests. Requests whose sequence number is already used can never be submitted and are dropped. An account holds at most 3 open requests: at the cap, the request with the least signer weight collected (the oldest among equals) gives way to the new one. All of an account's open requests share one sequence number, so at most one of them can land.

A publish that races another publish of the same transaction merges into the request that won, instead of replacing it.

SignaturesCopy Anchor Link

On publishCopy Anchor Link

The published envelope is rebuilt with exactly one verified signature per signer, in signer order, and then trimmed to the close threshold. Junk, duplicates and signatures from other keys are dropped, so a padded envelope cannot block later co-signers.

The close thresholdCopy Anchor Link

thresholdForClose in src/lib/multisig/partial-xdr.ts is the largest of the account's low, medium and high thresholds, and at least 1. The bundle holds high operations (the merge, signer cleanup) and medium ones (the close marker, trustline and offer cleanup), and the network checks the low threshold for the transaction as a whole. The relay and the app count with this one rule.

On signCopy Anchor Link

mergeNewSignatures merges a co-signer's envelope into the stored one and throws on any failure, which the relay answers as REJECTED:

1. The stored and incoming envelopes decode as classic transactions, not fee bumps.
2. The incoming transaction hash equals the stored one, so a signature over a different transaction is never merged.
3. Every new signature verifies over that hash under one of the account's signer keys, read from Horizon at publish. The 4-byte hint only decides which key is tried first; a signature from a wallet with an unusual hint is still matched by verifying against every signer.

Signatures are deduplicated by the recovered signer key, not by their wire bytes. The hint is chosen by whoever sends the envelope, so keying on wire bytes would let one captured signature be replayed under many hints until the envelope hits the 20-signature limit. A merged signature is stored with its signer's canonical hint.

Once the stored envelope meets the threshold it is final: a later valid signature is acknowledged but not added, because the network rejects a transaction that carries a signature it did not need (tx_bad_auth_extra). An envelope that brings several new signatures at once is trimmed to the threshold in envelope order, as the network counts them. A replayed envelope that adds nothing answers success without notifying listeners.

BoundsCopy Anchor Link

A request is served until the earlier of 72 hours after publish and the transaction's maxTime minus 60 seconds. The app builds a signing request's transaction with a 72-hour validity window (SIGNING_WINDOW_SECONDS in src/lib/multisig/signing-request.ts).

State is in process memoryCopy Anchor Link

The relay keeps its requests in memory: a restart loses them, and instances behind a load balancer do not share them. A co-signer routed to another instance does not find the request. Run one instance; see Self-hosting.

Cross-network replayCopy Anchor Link

Stellar binds the network passphrase into the transaction hash, so a signature collected on one network cannot complete the same close on another.