NETSoon

Docs Reference

JSON-RPC

Every method of the Acrux Net gateway, its params, its result, the errors it returns, and every type those carry.

The Acrux Net gateway answers JSON-RPC 2.0 over HTTP POST, at / or /rpc. It serves the net's slots, windows, schedule, transactions, balances and the demo pool, and it takes transactions and fragments for a target slot. The same data streams live over the event stream.

Local
JSON-RPChttp://127.0.0.1:4930
HealthGET http://127.0.0.1:4930/health

Request and response

bash
curl -s http://127.0.0.1:4930 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getCurrentWindow","params":{}}'

A request is { "jsonrpc": "2.0", "id", "method", "params" }. id is a string or a non-negative integer and comes back unchanged. params is always an object; a method without params takes {}. Unknown keys in params are refused.

A success is { "jsonrpc": "2.0", "id", "result" }. A failure is { "jsonrpc": "2.0", "id", "error": { "code", "message", "data" } }, where data is the error envelope every Acrux service returns; branch on data.error.code.

error.codeWhendata.error.code
-32700the body is not JSONINVALID_INPUT
-32600not a JSON-RPC 2.0 request with an idINVALID_INPUT
-32601unknown methodNOT_FOUND
-32602params fail validation; data.error.fieldErrors names each fieldINVALID_INPUT
-32000the method ran and refused; error.message repeats the codeany ErrorCode

Numbers that can exceed 2^53 (lamports, stake, priority fees) are decimal strings. Times are integers in microseconds, each measured from the anchor its field names. Proposer and track indices start at 1; slice, fragment and merged-order indices start at 0. A null entry in an attestation vector pi is the paper's ⊥, a late proposer.

Methods

MethodReturns
getSnapshotthe whole current view of the net
getSlotone slot, complete
getRecentSlotsthe last slots, up to 64
getCurrentWindowthe window producing now
getSchedulethe windows ahead
getCountersnet-wide counters
getTransactionone transaction's trail
getBalancean address's balance and reserve
getDemoPoolthe demo pool's mints and reserves
getQuotea swap quote on the demo pool
getLatestBlockhashthe blockhash to sign a transaction against
getExecutionSnapshotthe executed state of the latest finalized cblock
getSlotBlocksa slot's agreed blocks, encrypted, with its attestations
submitTransactiontakes a plain transaction for its target slot
submitFragmenttakes one fragment of a t-of-n transaction
getLabReplaya Fault Lab run's recorded events

getSnapshot

Everything a new view of the net needs at once: the stream position, status, current window, the last 64 slots, the windows ahead, the counters and the parameters. The event stream sends the same object as its first message.

Params: an empty object, {}.

Result: NetSnapshot.

getSlot

One slot with everything known about it: its window, each proposer's block and commitment, every attestation, the agreed set, the merged order, the four-track schedule, the state hash and its cblock.

ParamTypeRequiredMeaning
slotintegeryesthe slot number

Result: Slot.

Errors: NOT_FOUND for a slot the gateway does not hold.

getRecentSlots

The most recent slots, oldest first, including the ones still in progress, each in the shape getSlot returns. /net pauses and steps through these.

ParamTypeRequiredMeaning
limitinteger, 1 to 64, default 64nohow many slots, newest last

Result: Slot[].

getCurrentWindow

The window producing now: its hub, slot range, consensus slots and three proposers.

Params: an empty object, {}.

Result: Window.

getSchedule

The windows after the current one, in order, with the hub and proposers each will have.

ParamTypeRequiredMeaning
limitinteger, 1 to 64, default 8nohow many windows ahead

Result: Window[].

getCounters

Params: an empty object, {}.

Result: Counters.

getTransaction

A transaction's trail by its ID: header, receivers, each fragment's inclusion, the slot where it became readable and executed, its position in the merged order, result, logs and finalization. An ID the gateway has never seen returns state unknown.

ParamTypeRequiredMeaning
idhashyesthe transaction ID

Result: Transaction.

getBalance

An address's lamports, the part held as the 0.001 SOL fee-payer reserve, and what is spendable above it.

ParamTypeRequiredMeaning
addressaddressyesthe Acrux Net address

Result: Balance.

getDemoPool

Acrux Net's demo constant-product pool: its two demo mints, reserves and fee.

Params: an empty object, {}.

Result: DemoPool.

getQuote

A quote for swapping amountIn of inputMint on the demo pool. The output is computed with integer arithmetic on the current reserves after the pool fee; minimumOut applies slippageBps.

ParamTypeRequiredMeaning
inputMintaddressyesthe demo mint you pay in
amountInu64 stringyesamount in, in the mint's base units; more than 0
slippageBpsinteger, 0 to 10000yestolerance for minimumOut, basis points

Result: Quote.

Errors: INVALID_INPUT when inputMint is not one of the pool's mints.

getLatestBlockhash

A blockhash to sign a transaction against: the one from 8 slots before the latest executed slot, so every validator holds it. A transaction may carry any blockhash of the last 1,200 slots, one minute.

Params: an empty object, {}.

Result:

FieldTypeRequiredMeaning
blockhashaddressyesa blockhash from 8 slots before slot, for a transaction's recentBlockhash
slotintegeryesthe latest executed slot
startedSlotintegeryesthe latest started slot; a send targets a slot after it

getExecutionSnapshot

The executed state of the latest finalized cblock, for a follower to start from: what acrux node follow loads into its own SVM. Params: an empty object, {}.

FieldMeaning
consensusSlotthe finalized cblock's consensus slot
lastSlotits last slot, 4 × consensusSlot + 3
executorthe executed state: every account, the executed transaction IDs, the recent blockhashes, the per-window inclusion charges, the fee totals, the track capacity and the state hash
thresholdthe fragments held toward threshold transactions not yet rebuilt

Errors: NET_UNAVAILABLE before any cblock is finalized.

getSlotBlocks

One slot's agreed blocks as their proposers sent them, encrypted, with the slot's attestations and their released keys. Params: { "slot": n }.

FieldMeaning
slotthe slot
agreedthe agreed set P
blocks[].proposerthe block's proposer index
blocks[].slices[]each slice: meta, its ShredMeta; cipher, the slice's ciphertext in base64; root, its Merkle root in hex
attestations[]each attestation: proposer, pi (hex hashes or null), key (base64)

Decrypting each slice with its proposer's released key and rebuilding the commitment from the slices' roots gives back the agreed block (Wire formats). Errors: NOT_FOUND for a slot outside the last 64, or one not agreed; INVALID_INPUT for a slot that is not a non-negative integer.

submitTransaction

Takes a signed plain transaction (t = 1) for the proposers named in receivers. The gateway hands it to each of them for header.targetSlot. Pick a target a few slots ahead of the latest slot in getSnapshot.

ParamTypeRequiredMeaning
headerTxHeaderyesthe transaction's public header
transactionbase64, non-emptyyesthe signed Solana transaction
receiversarray of proposer index, 1 to 3yesthe proposers of the target slot to send it to, each once

Result: Submission.

Errors:

CodeCause
INVALID_INPUTa receiver is named twice, or the target slot is more than 64 slots ahead
TRANSACTION_EXPIREDthe target slot has already started
IDEMPOTENCY_CONFLICTthe same ID was submitted before with a different header or body

Submitting the same transaction again with the same header and body returns the same result.

submitFragment

Takes one fragment of a t-of-n transaction (t ≥ 2) with its key share, for one receiver. A client sends n calls, one per receiver, each with a different index and receiver and the same header. Threshold transactions says what the parts are; the SDK makes all n calls in one send.

ParamTypeRequiredMeaning
headerTxHeaderyesthe transaction's public header, the same in every fragment
ninteger, 2 to 3yesfragments the transaction is split into
tinteger, 2 to 3yesfragments needed to rebuild it; at most n
indexinteger, 0 to 2yesthis fragment's index, below n
receiverproposer indexyesthe proposer this fragment goes to
fragmentbase64, non-emptyyesthis fragment of the ciphertext
keySharebase64, non-emptyyesthis receiver's Shamir share of the key
headerSignaturesignatureyesthe fee payer's signature over the header

Result: Submission.

Errors:

CodeCause
INVALID_INPUTt > n, index ≥ n, a receiver given two fragments, or the target slot more than 64 slots ahead
TRANSACTION_EXPIREDthe target slot has started
CHAIN_REFUSEDthe node refused the transaction or fragment; message says why
IDEMPOTENCY_CONFLICTthe ID was submitted with a different header, n or t, or this index with a different fragment

getLabReplay

A Fault Lab run with every event it recorded, in the event stream's envelope. The same replay is at GET /v1/lab/runs/{id}/events.

ParamTypeRequiredMeaning
runIdstringyesthe run's ID

Result: LabReplay.

Errors: NOT_FOUND for an unknown run.

Types

NetSnapshot

FieldTypeRequiredMeaning
streamIdstringyesthe stream instance
cursorintegeryesthe last sequence the snapshot includes; resume after it
status"live", "stalled", "unavailable"yesthe net's status: stalled when slots have stopped arriving
currentWindowWindowyesthe window producing now
recentSlotsSlot[], at most 64yesthe most recent slots, oldest first
upcomingWindowsWindow[]yesthe windows ahead
countersCountersyesthe net's counters
parametersParametersyesthe protocol parameters the net runs

Parameters

The protocol parameters the net runs, in microseconds and lamports. Parameters explains each.

FieldTypeRequiredMeaning
k3yesproposers per window
kappa4yesκ, slots per consensus slot
w16yesslots per window
deltaLocalUs10000yesδlocal
deltaBlockUs50000yesδblock, the length of a slot
deltaGlobalUs250000yesδglobal
timeoutUs750000yesΔtimeout
tracks4yesm, execution tracks per slot
reserveLamports"1000000"yesρ, the fee-payer reserve
trackCapacityCuinteger or nullyesbcu, compute units per track per slot
fragmentExpirySlotsinteger or nullyesslots a fragment stays cached after the first accepted one
alphanumber, 0 to 1 or nullyesα, the share of windows assigned by hub stake
minimumHubMembersinteger or nullyesn_min
minimumHubStakeu64 string or nullyesρ_min, lamports

Counters

FieldTypeRequiredMeaning
slotsintegeryesslots produced
finalizedCblocksintegeryescblocks finalized
skipsintegeryesconsensus slots skipped
averageCommitSpreadUsnumberyesmean time from a slot's first to its last commitment

Window

FieldTypeRequiredMeaning
numberintegeryesthe window's number
hubCodehub codeyesthe hub holding the window
firstSlotintegeryesits first slot
lastSlotintegeryesits last slot, 15 after the first
consensusSlotsinteger[]yesits four consensus slots
proposersProposer[], exactly 3yesits three proposers, by index

Proposer

FieldTypeRequiredMeaning
indexproposer indexyesits proposer index in the window, 1 to 3
identityaddressyesits validator identity
stakeu64 stringyesits stake, lamports
status"online", "late", "crashed"yesonline; late when attested late; crashed when silent since the window started

Slot

blocks, attestations and executedUs are measured from the slot's start. attestationDeadlineUs and consensusTimeoutUs are measured from the window's ParentReady.

FieldTypeRequiredMeaning
slotintegeryesthe slot number
wallTimeUTC timestampyeswhen the slot started
windowWindowyesits window
consensusSlotintegeryesthe consensus slot it belongs to
status"pending", "executed", "finalized", "skipped"yeswhere the slot stands; finalized once its cblock is
blocksProposerBlock[]yeseach proposer's block
attestationsAttestation[]yesevery attestation received for the slot
agreedSetarray of proposer index or nullyesP, the accepted proposers; null until agreed
skipSkip or nullyeswhy the slot was skipped; null otherwise
mergedOrderMergedTransaction[]yesevery transaction of the slot in merged order
scheduleExecutionSchedule or nullyesthe four-track schedule; null until merged
stateHashhash or nullyeshash of the state after the slot; null until executed
xblockHashhash or nullyeshash of the slot's execution block
cblockCblockyesthe cblock the slot belongs to
executedUsinteger or nullyeswhen it executed, µs after the slot's start
attestationDeadlineUsintegeryesthe window's attestation deadline, µs after ParentReady
consensusTimeoutUsintegeryesits consensus slot's timeout T(i), µs after ParentReady

ProposerBlock

FieldTypeRequiredMeaning
proposerproposer indexyesproposer index
identityaddressyesthe proposer's identity
status"streaming", "sealed", "accepted", "dropped", "missing"yesstreaming, sealed once committed, accepted in P, dropped when outside P, or missing
bytesintegeryessize of the encrypted block
slicesSlice[]yesits slices
commitmentCommitment or nullyesits commitment; null until sent
attestationAttestation or nullyesits proposer's attestation; null until sent
parentobject or nullyesin a window's first slot, the parent cblock it names; null otherwise
parent.consensusSlotintegeryesthe parent's consensus slot
parent.hashhashyesthe parent's hash

Slice

FieldTypeRequiredMeaning
indexintegeryesslice index within the block, from 0
shredCount64yesshreds the slice is coded into
rebuildShreds32yesshreds that rebuild it
bytesintegeryesencrypted size of the slice
sentUsintegeryeswhen sent, µs after the slot's start
arrivedUsintegeryeswhen rebuilt at the validator, µs after the slot's start
merkleRoothashyesMerkle root over its shreds

Commitment

FieldTypeRequiredMeaning
slotintegeryesthe slot
proposerproposer indexyesthe committing proposer
hashhashyesh(b), the hash of the encrypted block
keyHashhashyesH(K), the hash of the block's key, bound in the header
signaturesignatureyesthe proposer's signature over Commit(s, q, h)
sentUsintegeryeswhen sent, µs after the slot's start
arrivalsCommitmentArrival[]yesits arrival at each co-proposer

CommitmentArrival

FieldTypeRequiredMeaning
receiverproposer indexyesthe co-proposer it reached
startUsintegeryesthe receiver's start[s], µs after the slot's start
arrivedUsintegeryeswhen it arrived, µs after the slot's start
relativeToStartUsintegeryesarrival minus the receiver's start[s]
deadlineUs20000yesthe on-time window, 2δlocal
onTimebooleanyeswhether it arrived within the window

Attestation

FieldTypeRequiredMeaning
slotintegeryesthe slot
proposerproposer indexyesthe attesting proposer
piarray of hash or null, exactly 3yesπ: per proposer, its commitment if on time, null if late
keybase64yesthe attester's block key, released here
signaturesignatureyesthe proposer's signature over the attestation
sentUsintegeryeswhen sent, µs after the slot's start
validatorArrivalsobject[]yesits arrival at each validator
validatorArrivals.identityaddressyesthe validator
validatorArrivals.arrivedUsintegeryeswhen it arrived, µs after the slot's start

Skip

FieldTypeRequiredMeaning
reasonSkipReasonyeswhy
detailstringyesa sentence on what happened
disagreeingVectorsAttestation[]yesthe attestations that disagreed
affectedSlotsinteger[]yesevery slot the skip covers, to the window's end
atUsintegeryeswhen the validator decided to skip, µs after the slot's start

SkipReason

ValueMeaning
disagreeing_vectorstwo attestations for the slot carry different vectors
missing_attestationan attestation of the agreed set did not arrive before the timeout
equivocationa proposer signed two blocks or two attestations for the slot
majority_lostfewer than two proposers are attested
window_skippedan earlier consensus slot of the window was skipped

MergedTransaction

One entry of a slot's merged order: the transaction's public header plus where it came from and whether it was selected.

FieldTypeRequiredMeaning
idhashyesthe transaction ID
feePayeraddressyesthe fee payer
priorityFeePerCuu64 stringyespriority fee, micro-lamports per compute unit
computeLimitinteger, at least 1yesdeclared compute limit
writableAccountsaddress[]yesaccounts it writes
targetSlotintegeryesthe slot it was sent for
kind"plain", "fragments"yesa plain copy, or fragments of a t ≥ 2 transaction
sourceProposersarray of proposer indexyesthe proposers whose blocks carried it
ninteger, 1 to 3yesreceivers it was sent to
tinteger, 1 to 3yesthreshold
fragmentIndicesinteger[]yesfor fragments: the indices accepted
positionintegeryesits index in the merged order, from 0
selectedbooleanyeswhether Algorithm 4 placed it
exclusion"capacity", "priority_fee", "incomplete" or nullyeswhy not placed: capacity, priority_fee (could not pay above the reserve), or incomplete (fewer than t fragments); null if placed

ExecutionSchedule

FieldTypeRequiredMeaning
algorithm4yesalways 4: the paper's Algorithm 4
tracks4yesm, the number of tracks
capacityCuinteger, at least 1yesbcu, compute units per track
placementsPlacement[]yeseach selected transaction's place
gapsobject[]yesthe free intervals left
gaps.tracktrackyesthe track
gaps.startCuintegeryeswhere the gap starts, compute units
gaps.lengthCuintegeryesits length, compute units

Placement

FieldTypeRequiredMeaning
tracktrackyesthe track
startCuintegeryesits start on the track, compute units
lengthCuintegeryesits compute limit
txIdhashyesthe transaction

Cblock

FieldTypeRequiredMeaning
consensusSlotintegeryesthe consensus slot
slotsinteger[]yesits four slots
parentobject or nullyesthe parent cblock
parent.consensusSlotintegeryesthe parent's consensus slot
parent.hashhashyesthe parent's hash
hashhash or nullyesh(c_i), the hash validators vote on; null until assembled
stateHashhash or nullyeshash of the state after its four slots
votesVote[]yesvotes received
certificatesCertificate[]yescertificates formed
status"pending", "notarized", "finalized", "skipped"yeswhere the cblock stands in Alpenglow
finalizedUsinteger or nullyeswhen finalized, µs after its first slot's start

Vote

FieldTypeRequiredMeaning
consensusSlotintegeryesthe consensus slot
validatoraddressyesthe voter
kind"notar", "notar_fallback", "skip", "skip_fallback", "finalize"yesthe Alpenglow vote
stakeSharenumber, 0 to 1yesthe voter's share of total stake
hashhash or nullyesthe cblock hash voted for; null for skip
atUsintegeryeswhen cast, µs after the cblock's first slot

Certificate

FieldTypeRequiredMeaning
consensusSlotintegeryesthe consensus slot
kind"notarization", "notar_fallback", "fast_finalization", "slow_finalization", "skip"yesthe Alpenglow certificate
stakeSharenumber, 0 to 1yesstake share of its signers
thresholdnumber, 0 to 1yesthe share it needed: 0.6, or 0.8 for fast finalization
hashhash or nullyesthe cblock hash; null for skip
signersaddress[]yesthe validators whose votes it aggregates
atUsintegeryeswhen formed, µs after the cblock's first slot
linkedConsensusSlotinteger or nullyeson a skip certificate for a later consensus slot of a window: the first skipped consensus slot of that window, whose skip abandoned the rest; null on that first skip and on every other certificate

Transaction

FieldTypeRequiredMeaning
headerTxHeaderyesits public header
state"unknown", "sent", "partly_included", "executed", "finalized", "failed", "expired"yeswhere the transaction stands; Threshold transactions defines each
kind"plain", "fragments"yesa plain transaction, or fragments of a t ≥ 2 transaction
ninteger, 1 to 3yesreceivers
tinteger, 1 to 3yesthreshold
receiversProposer[]yesthe proposers it was sent to
fragmentsFragmentInclusion[]yeseach copy or fragment's inclusion
includedCountintegeryescopies or fragments included so far
readableSlotinteger or nullyesthe slot its t-th fragment was accepted in
executedSlotinteger or nullyesthe slot it executed in
mergedPositioninteger or nullyesits position in that slot's merged order
result"success", "error" or nullyessuccess or error, once executed
logsstring[]yesprogram logs
failurestring or nullyeswhy it failed or expired
expiresAfterSlotinteger or nullyesthe last slot its fragments stay cached
finalizationCertificate or nullyesthe certificate that finalized its cblock

TxHeader

The public header of a transaction, signed by the fee payer. For a t ≥ 2 transaction it is all a proposer and the merge see until the t-th fragment is accepted.

FieldTypeRequiredMeaning
idhashyesthe transaction ID: for plain, the hash of the signed message; for fragments, the commitment that names it
feePayeraddressyesthe account charged its fees
priorityFeePerCuu64 stringyespriority fee, micro-lamports per compute unit
computeLimitinteger, at least 1yesdeclared compute limit, at least 1
writableAccountsaddress[]yesaccounts it writes
targetSlotintegeryesthe slot it is sent for

FragmentInclusion

FieldTypeRequiredMeaning
indexintegeryesfragment index; 0 for a plain copy
receiverproposer indexyesthe proposer it was sent to
slotintegeryesthe slot it was included in
proposerproposer indexyesthe proposer whose block carried it
includedUsintegeryeswhen included, µs after that slot's start

Balance

FieldTypeRequiredMeaning
addressaddressyesthe address
lamportsu64 stringyestotal balance
reserveLamportsu64 stringyesthe fee-payer reserve held
spendableLamportsu64 stringyesbalance above the reserve
slotintegeryesthe slot it was read at

DemoPool

FieldTypeRequiredMeaning
addressaddressyesthe pool account
mintstuple of DemoMint, DemoMintyesits two demo mints
reservestuple of u64 string, u64 stringyesthe reserve of each mint, base units, in the order of mints
feeBpsintegeryesswap fee, basis points
slotintegeryesthe slot it was read at

DemoMint

FieldTypeRequiredMeaning
addressaddressyesthe mint
symbolstringyesits symbol
namestringyesits name
decimalsintegeryesits decimals

QuoteRequest

FieldTypeRequiredMeaning
inputMintaddressyesthe demo mint you pay in
amountInu64 stringyesamount in, in the mint's base units; more than 0
slippageBpsinteger, 0 to 10000yestolerance for minimumOut, basis points

Quote

FieldTypeRequiredMeaning
inputMintaddressyesthe mint paid in
outputMintaddressyesthe mint received
amountInu64 stringyesamount in, base units
amountOutu64 stringyesamount out at the current reserves, base units
minimumOutu64 stringyesamountOut less the slippage tolerance
feeAmountu64 stringyesthe pool fee taken from amountIn
slotintegeryesthe slot the reserves were read at

PlainSubmission

FieldTypeRequiredMeaning
headerTxHeaderyesthe transaction's public header
transactionbase64, non-emptyyesthe signed Solana transaction
receiversarray of proposer index, 1 to 3yesthe proposers of the target slot to send it to, each once

FragmentSubmission

FieldTypeRequiredMeaning
headerTxHeaderyesthe transaction's public header, the same in every fragment
ninteger, 2 to 3yesfragments the transaction is split into
tinteger, 2 to 3yesfragments needed to rebuild it; at most n
indexinteger, 0 to 2yesthis fragment's index, below n
receiverproposer indexyesthe proposer this fragment goes to
fragmentbase64, non-emptyyesthis fragment of the ciphertext
keySharebase64, non-emptyyesthis receiver's Shamir share of the key
headerSignaturesignatureyesthe fee payer's signature over the header

Submission

FieldTypeRequiredMeaning
idhashyesthe transaction ID
acceptedtrueyesalways true; a refusal is an error
targetSlotintegeryesthe slot it is queued for