Docs SDK
Threshold sends
Split a transaction into t-of-n encrypted fragments across the slot's proposers, so none can read it alone, with one send call.
A threshold send splits a signed transaction into n encrypted fragments, one per proposer of the target slot. No proposer can read its fragment alone; once t proposers have included theirs, validators rebuild the transaction and it executes in that slot. Threshold transactions tells the mechanism.
const { id } = await acrux.send(tx, { n: 3, t: 2, signer: payer })Choosing n and t
| n | t | What it buys |
|---|---|---|
| 1 | 1 | One proposer carries it in the clear. Cheapest. |
| 2 | 1 | Two copies; either proposer lands it. Survives one drop. |
| 3 | 2 | Split three ways; any two rebuild it, no one reads it alone. |
| 3 | 3 | All three fragments needed. Most private; no drop tolerated. |
With t = 1 there are no fragments: each of the n proposers receives the signed transaction itself.
The signer
With t of 2 or 3 the fee payer signs the transaction's public header, which every fragment carries and every proposer checks before it includes one. send takes the fee payer as signer:
await acrux.send(tx, { n: 3, t: 2, signer: payer })// any function that signs bytes with the fee payer's key, such as a wallet adapter's signMessage
await acrux.send(tx, { n: 3, t: 2, signer: (message) => wallet.signMessage(message) })send checks the signature against the header's fee payer before it submits anything.
What is signed and sealed
The header
deriveHeaderreads the public TxHeader from the signed bytes:id,feePayer,priorityFeePerCu,computeLimit,writableAccounts,targetSlot. Proposers order and schedule by these fields without reading the transaction.The header signature
The fee payer signs
headerBytes(header), the header as compact JSON with its fields in that order.The fragments
sealencrypts the signed transaction with ChaCha20-Poly1305 under a fresh key, with the header bytes as associated data. It erasure-codes the ciphertext intonshards of which anytrebuild it, and Shamir-splits the key the same way. Each fragment carries one shard and one key share.The submissions
sendcallssubmitFragmentonce per receiver, each with its own fragment.
The byte layout is in Wire formats.
Following a threshold send
tx.follow reports one included update per fragment a proposer includes, then executed once the t-th fragment makes it readable:
for await (const update of acrux.tx.follow(id)) {
console.log(update.state, `${update.included} of ${update.threshold}`)
}A transaction whose fragments do not reach t within 8 slots slots of the first included fragment ends expired.
Fees
Each included fragment pays the inclusion fee, 1000 lamports lamports, to the proposer that included it. The base fee and the priority fee are charged once, when the rebuilt transaction executes. Fees and the reserve
Measured on Acrux Net: ten sends of each kind, each a 0.001 SOL transfer with no priority fee through @acrux/sdk, medians from submit.
| Send | Fee (lamports) | To executed | To finalized |
|---|---|---|---|
| Plain, to 1 proposer | 6 000 | 339 ms | 580 ms |
| Plain, to all 3 proposers | 8 000 | 342 ms | 585 ms |
| 2-of-3 threshold | 8 000 | 339 ms | 585 ms |
A 2-of-3 send costs what a plain send to the same three proposers costs, and reaches executed and finalized as fast as a plain send.
Sealing by hand
seal and open are exported for tools that build submissions themselves.
import { deriveHeader, headerBytes, open, seal } from '@acrux/sdk'
const header = deriveHeader(bytes, targetSlot)
const signature = await signer(headerBytes(header))
const fragments = seal(bytes, header, signature, 2, [1, 2, 3]) // t = 2, receivers are proposer indices
const rebuilt = open(fragments.slice(1)) // any two fragments give back the signed bytes| Function | Returns |
|---|---|
deriveHeader(bytes, targetSlot) | the public header the node derives from the same bytes |
headerBytes(header) | the bytes the fee payer signs, also the ciphertext's associated data |
seal(bytes, header, headerSignature, t, receivers) | one FragmentSubmission per receiver |
open(fragments) | the signed transaction bytes, from any t distinct fragments of one seal |