Docs Reference
Wire formats
The bytes acrux-node sends and signs. The packet envelope, commitment, attestation, slice encryption, shred and Merkle proof, vote, and the threshold fragment.
Node-to-node messages travel over QUIC as bincode 1.3 with its default options: integers little-endian at fixed width, usize as u64, a Vec or byte string prefixed with its u64 length, a fixed array without a prefix, Option as one byte (0 none, 1 some) before the value, and an enum as its u32 variant index before its fields. Hashes are SHA-256, 32 bytes. Signatures are Ed25519, 64 bytes, checked with strict verification.
The JSON-RPC and event stream carry the same objects as JSON: hashes as lowercase hex, keys and signatures as base58.
Packet
Every packet is one Envelope.
| Field | Type | Meaning |
|---|---|---|
from | usize | the sender's validator index |
body | Wire | the message, below |
signature | Vec<u8> | the sender's signature over the bincode bytes of body, its variant index included; a commitment's or attestation's signature is this one |
| Index | Wire variant | Fields |
|---|---|---|
| 0 | Shreds | Vec<Shred>: shreds from the proposer |
| 1 | Relay | Vec<Shred>: shreds forwarded by a Rotor relay |
| 2 | Commit | Commitment |
| 3 | Attest | Attestation |
| 4 | Vote | SignedVote |
| 5 | Certificate | certificate, and proofs: the SignedVotes it was formed from |
| 6 | Submit | a plain transaction for a proposer's mempool |
| 7 | SubmitFragment | a checked threshold fragment |
| 8 | Handover | slot: u64, parent: BlockRef, shreds: Vec<Shred>, attestations: Vec<(Attestation, Vec<u8>)>: the last cblock's signed shreds and attestations for the next window's proposers |
| 9 | Equivocation | first, second: two (Commitment, signature) pairs of one proposer for one slot, the slashing proof |
BlockRef is slot: u64 then hash: [u8; 32].
Commitment
A proposer's signed hash of its block, sent to its co-proposers with its last slice (Hash exchange).
| Field | Type | Meaning |
|---|---|---|
slot | u64 | the slot |
proposer | usize | the proposer index, 1 to 3 |
hash | [u8; 32] | SHA-256 of the bincode bytes of the block commitment below |
key_hash | [u8; 32] | SHA-256 of the block's 32-byte key |
The block commitment that hash covers:
| Field | Type | Meaning |
|---|---|---|
slot | u64 | the slot |
proposer | usize | the proposer index |
key_hash | [u8; 32] | SHA-256 of the block key |
parent | Option<BlockRef> | the cblock the block builds on |
roots | Vec<[u8; 32]> | the Merkle root of each slice, in slice order |
The commitment binds every slice's ciphertext through its root and the key through its hash, so a key released later opens exactly the committed block. Two commitments signed by one proposer for one slot with different hash are a slashing proof (Guarantees).
Attestation
A proposer's view of the slot's commitments, released with its block key once its exchange closes.
| Field | Type | Meaning |
|---|---|---|
slot | u64 | the slot |
proposer | usize | the attesting proposer |
pi | Vec<Option<[u8; 32]>> | entry q − 1 is proposer q's commitment hash as received on time, or none (⊥) |
key | [u8; 32] | the attesting proposer's block key |
Validators check that each pi entry matches the commitment rebuilt from the block's shreds before they count it (Validator).
Slice encryption
Each slice of a block is encrypted with ChaCha20-Poly1305 under the block's fresh 32-byte key.
| Input | Bytes |
|---|---|
| nonce | the first 12 bytes of SHA-256("acrux-slice-nonce-v1" ‖ slot u64 ‖ proposer u64 ‖ slice u32) |
| associated data | "acrux-slice-v1" ‖ slot u64 ‖ proposer u64 ‖ slice u32 |
| plaintext | at most 65,520 bytes |
| ciphertext | at most 65,536 bytes, the tag included |
All integers are little-endian.
Shred
Rotor sends each encrypted slice as 64 shreds, of which any 32 rebuild it.
Coding. The ciphertext is cut into 32 data shards of ceil(length / 32) bytes, the last zero-padded. Reed-Solomon over GF(2^8) adds 32 coding shards, 64 in all.
Merkle tree. A leaf is SHA-256(0x00 ‖ index u8 ‖ shard); an inner node is SHA-256(0x01 ‖ left ‖ right). The 64 leaves give a tree of depth 6 and one root per slice.
| Field | Type | Meaning |
|---|---|---|
meta | ShredMeta | below; identical in every shred of the slice |
index | u8 | the shard's position, 0 to 63; 0 to 31 are data |
data | Vec<u8> | the shard, ceil(encrypted_len / 32) bytes |
root | [u8; 32] | the slice's Merkle root |
proof | Vec<[u8; 32]> | the six siblings from the leaf up to the root |
signature | Vec<u8> | the proposer's signature, below |
ShredMeta field | Type | Meaning |
|---|---|---|
slot | u64 | the slot |
proposer | usize | the proposer index |
slice | u32 | the slice's index in the block |
final_slice | bool | the block's last slice |
key_hash | [u8; 32] | SHA-256 of the block key |
parent | Option<(u64, [u8; 32])> | the parent cblock's slot and hash |
encrypted_len | u32 | the slice ciphertext's length |
The signature covers the bincode bytes of the tuple ("acrux-shred-v1" as 14 fixed bytes, meta, index, root, SHA-256(data)). A receiver checks the signature, the proof against root, the proof depth of 6 and the shard length before it keeps the shred.
Vote
| Field | Type | Meaning |
|---|---|---|
validator | usize | the voter's index |
slot | u64 | the consensus slot |
hash | Option<[u8; 32]> | the cblock voted for; none for skip votes |
kind | VoteKind | Notar 0, NotarFallback 1, Skip 2, SkipFallback 3, Finalize 4 |
A SignedVote is the vote followed by the voter's signature over its bincode bytes. Thresholds and certificates are on Consensus on cblocks.
Threshold fragment
A t-of-n transaction travels as one FragmentSubmission per receiver, through submitFragment. @acrux/sdk writes these bytes and acrux-node reads them (Threshold sends).
Header bytes. The UTF-8 bytes of the TxHeader as compact JSON, its fields in exactly this order: id, feePayer, priorityFeePerCu, computeLimit, writableAccounts, targetSlot. id is SHA-256 of the signed transaction's message, lowercase hex. The fee payer signs these bytes, and they are the ciphertext's associated data.
Ciphertext. ChaCha20-Poly1305 of the signed transaction's bytes under a fresh 32-byte key and a random 12-byte nonce.
Shards. The ciphertext is cut into t data shards of ceil(length / t) bytes, the last zero-padded, and extended to n with systematic Reed-Solomon over GF(2^8) reduced by 0x11d: a Vandermonde matrix times the inverse of its top t × t square. Fragment i carries shard i.
Key shares. Each key byte is the constant term of a random polynomial of degree t − 1 over GF(2^8) reduced by 0x11b; share i is the polynomials' values at x = i + 1.
| Field | Encoding |
|---|---|
fragment | base64 of: version 0x01, the 12-byte nonce, the ciphertext length as u32 little-endian, shard index |
keyShare | base64 of: version 0x01, the byte index + 1, the 32 share bytes |
headerSignature | base58 of the fee payer's signature over the header bytes |
index | the fragment's index, 0 to n − 1 |
receiver | the receiving proposer's index, 1 to 3 |
Every fragment of one ID carries the same header, n, t, nonce and ciphertext length; a receiver takes one fragment per transaction. Validators rebuild the transaction in the slot that accepts the t-th distinct fragment, by inverting the chosen rows of the coding matrix and interpolating the key at x = 0, then check that the decoded transaction derives the signed header (Threshold transactions).