NETSoon

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.

FieldTypeMeaning
fromusizethe sender's validator index
bodyWirethe message, below
signatureVec<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
IndexWire variantFields
0ShredsVec<Shred>: shreds from the proposer
1RelayVec<Shred>: shreds forwarded by a Rotor relay
2CommitCommitment
3AttestAttestation
4VoteSignedVote
5Certificatecertificate, and proofs: the SignedVotes it was formed from
6Submita plain transaction for a proposer's mempool
7SubmitFragmenta checked threshold fragment
8Handoverslot: 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
9Equivocationfirst, 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).

FieldTypeMeaning
slotu64the slot
proposerusizethe 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:

FieldTypeMeaning
slotu64the slot
proposerusizethe proposer index
key_hash[u8; 32]SHA-256 of the block key
parentOption<BlockRef>the cblock the block builds on
rootsVec<[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.

FieldTypeMeaning
slotu64the slot
proposerusizethe attesting proposer
piVec<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.

InputBytes
noncethe 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
plaintextat most 65,520 bytes
ciphertextat 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.

FieldTypeMeaning
metaShredMetabelow; identical in every shred of the slice
indexu8the shard's position, 0 to 63; 0 to 31 are data
dataVec<u8>the shard, ceil(encrypted_len / 32) bytes
root[u8; 32]the slice's Merkle root
proofVec<[u8; 32]>the six siblings from the leaf up to the root
signatureVec<u8>the proposer's signature, below
ShredMeta fieldTypeMeaning
slotu64the slot
proposerusizethe proposer index
sliceu32the slice's index in the block
final_sliceboolthe block's last slice
key_hash[u8; 32]SHA-256 of the block key
parentOption<(u64, [u8; 32])>the parent cblock's slot and hash
encrypted_lenu32the 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

FieldTypeMeaning
validatorusizethe voter's index
slotu64the consensus slot
hashOption<[u8; 32]>the cblock voted for; none for skip votes
kindVoteKindNotar 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.

FieldEncoding
fragmentbase64 of: version 0x01, the 12-byte nonce, the ciphertext length as u32 little-endian, shard index
keySharebase64 of: version 0x01, the byte index + 1, the 32 share bytes
headerSignaturebase58 of the fee payer's signature over the header bytes
indexthe fragment's index, 0 to n − 1
receiverthe 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).