Docs Protocol
Threshold transactions
t-of-n transactions. Sending one transaction to several proposers of a slot, split so that any t rebuild it and fewer than t cannot read it.
A user sends each transaction to n of the target slot's proposers with a threshold t, where 1 ≤ t ≤ n ≤ k. On Acrux Net, k = 3. The two numbers buy different things:
- n buys inclusion. The transaction survives
n − treceivers that censor it or whose blocks are not accepted. - t buys hiding. The content stays hidden from any
t − 1colluding receivers untiltparts are revealed.
Choosing n and t
| n | t | What it buys |
|---|---|---|
| 1 | 1 | One proposer carries it, in the clear |
| 2 | 1 | Two plain copies; survives one censoring or dropped proposer |
| 3 | 1 | Three plain copies; survives two |
| 2 | 2 | Split in two; no single proposer can read it; needs both included |
| 3 | 2 | Split in three; no single proposer can read it; survives one censoring or dropped proposer |
| 3 | 3 | Split in three; hidden from any two colluding proposers; needs all three included |
Every included copy or fragment pays an inclusion fee to the proposer whose block carries it, so a larger n costs more. See Fees and the reserve rule. In the SDK the choice is send(tx, { n, t }); see Threshold sends.
t = 1
The plain signed transaction goes to every receiver. The merge removes duplicates by the hash of the signed message, so it executes once.
t ≥ 2
The client follows Krawczyk's secret sharing made short:
- Encrypt the transaction with a fresh key.
- Erasure code the ciphertext into
nfragments, anytof which rebuild it. - Split the key into
nShamir shares with thresholdt. - Send each receiver one fragment, one key share and the public header.
The public header is signed by the fee payer and carries everything validity, merging and selection use:
| Field | Use |
|---|---|
| transaction ID | the commitment that identifies the transaction across fragments |
| fee payer | the account charged inclusion and priority fees |
| compute limit | its length in the slot's execution schedule |
| writable accounts | its conflicts in the schedule |
| priority fee | its place in the merged order |
| target slot | the slot it was sent for |
Acrux uses Reed-Solomon for the fragments and Shamir over GF(256) for the key shares. The byte layout is in Wire formats.
Decoding
Validators keep accepted fragments in a cache indexed by transaction ID. As soon as the t-th fragment is accepted, in whatever slot, the transaction is decoded and executed in that slot, ordered like every other transaction of the slot by its header's priority. Fragments can land in different slots; the slot of the t-th is the one that counts.
If fewer than t fragments are accepted within the fragment expiry, 8 slots (400 ms) after the slot of the first accepted fragment, the cached fragments are discarded and the transaction does not execute.
How far hiding goes
Hiding ends once t fragments are revealed, which can happen before the transaction is executed. If every receiver includes its fragment in the target slot, this does little: parties who have seen t fragments can react only in later slots, which are ordered after the transaction, so they can back-run it but not front-run it.
A receiver that holds back its fragment until the other t − 1 are revealed can decode early and put a front-running transaction with a higher priority fee in the block that also carries its fragment. This works only within the fragment expiry, which is why expiry is short. If the fragments are disseminated but the slot is skipped, the transaction is revealed without executing, and a resend can be front-run in a later slot.
The Private front-run scenario runs a 2-of-3 swap against a proposer that tries to read and front-run it.
States of a threshold transaction
The states Acrux reports for a transaction, on its page at /tx/[id] and through the SDK:
| State | Meaning |
|---|---|
| sent | fragments and shares delivered to the receivers |
| partly included | some of its t fragments accepted, fewer than t |
| executed | the t-th fragment accepted; decoded, ordered and executed |
| finalized | its cblock finalized |
| failed | executed and failed; fees charged |
| expired | fewer than t fragments accepted within the fragment expiry |