NETSoon

Docs Reference

HTTP API

The Acrux API. Hubs and memberships from the Hub Registry, the schedule preview, transactions, the faucet, Fault Lab runs, measured facts and the spec map, with the error envelope every Acrux service returns.

The API serves what is not the live net itself: the Hub Registry's hubs and members as indexed from Solana, the Algorithm 3 schedule preview for an epoch, transaction lookup, the Acrux Net faucet, Fault Lab runs and their replays, the figures measured on the net, and the map from the paper to the code. The live net is the JSON-RPC gateway and the event stream.

Local
APIhttp://127.0.0.1:4920
OpenAPI 3.1 documentGET /openapi.json

Every response is JSON. Every failure is the error envelope, with the HTTP status its code carries. Lists are paged: pass cursor and limit (1 to 100, default 24) and follow page.nextCursor until page.hasMore is false.

bash
curl -s http://127.0.0.1:4920/v1/hubs?limit=10

Endpoints

GET /health

The service's status and the configuration it still lacks. status is ready when every setting is present, waiting while some are missing; missingConfiguration names them.

GET /v1/hubs

Every hub in the Hub Registry, active, pending and inactive, with members, stake, proposer stake and what a pending hub still needs. Query: cursor, limit.

GET /v1/hubs/{code}

One hub by its code. NOT_FOUND if no hub holds the code.

GET /v1/registry/config

The registry's configuration as the program holds it: program ID, cluster, deposit, registration fee, cooldown and inactivity periods, code rules, the active-hub minimums and the current epoch. /hubs/register reads it to show the deposit and the fee before signing.

GET /v1/registry/members/{identity}

A validator's membership by its identity: hub, stake, proposer stake, whether it is capped, the epoch it takes effect, a pending move or leave and its cooldown. NOT_FOUND if the identity is in no hub.

GET /v1/schedule

The proposer schedule Algorithm 3 draws for an epoch from the registry and a stake snapshot: each hub's share of windows, the regional runs, and every window's hub and proposers. Query: epoch, optional, the next epoch by default. The node computes the same schedule through the same code path. See Proposer schedule.

GET /v1/transactions/{id}

A transaction's trail across the node's store, the same object as the gateway's getTransaction.

GET /v1/faucet/{address}

Whether address can receive a faucet grant now: the policy, the grants left for this key and this IP in the current period, and when the period resets.

POST /v1/faucet

Grants address Acrux Net SOL, and 100 AXA and 100 AXB, the demo pool's tokens, in one transfer from the faucet. Body: FaucetRequest. The grant's transactionId follows the transfer through getTransaction; the balance is spendable once it executes.

CodeCause
FAUCET_LIMITthis key or this IP has used its grants for the period; retryAfterSeconds says when to try again
CONFIGURATION_REQUIREDthe faucet's amount, limits or period are not configured
VALIDATION_ERRORaddress is not a base58 address of 32 bytes

GET /v1/lab/scenarios

The six Fault Lab scenarios, each with its seed, parameters, the lemma it shows and its expected outcome.

GET /v1/lab/runs

Recorded runs, newest first. Query: cursor, limit.

POST /v1/lab/runs

Starts a run of scenario on a fresh sandbox cluster, with the scenario's seed or the one given. Body: LabRunRequest. Answers 201 with the run in status queued; follow it on /stream or by reading the run.

GET /v1/lab/runs/{id}

A run's status, outcome and evidence. NOT_FOUND for an unknown ID.

GET /v1/lab/runs/{id}/events

A run with every event it recorded, in the event stream's envelope, for replay.

GET /v1/lab/runs/{id}/stream

Server-sent events: the run's recorded events, then its live ones until it ends. Each message has event set to the event type, id to its sequence, and data to the full envelope. Send Last-Event-ID to resume after a sequence.

GET /v1/facts

The figures measured on Acrux Net: slot pacing, commit spread, attestation arrival relative to blocks and cblock finalization time, each at p50 and p99, and the window handover per hub link with its floor, with the sample size and time of measurement.

GET /v1/spec

The map from the paper to the code: every algorithm line and lemma with the file and function that implements it and the Fault Lab scenario that shows it, the parameters, and every choice the paper left open with Acrux's decision. /spec renders it.

Types

Health

FieldTypeRequiredMeaning
status"fixture", "waiting", "ready"yesready when every setting is present
contractVersionstringyesversion of @acrux/contract the service speaks
missingConfigurationstring[]yesnames of the settings still missing; empty when ready

Hubs

FieldTypeRequiredMeaning
itemsHub[]yesthe hubs on this page
pageobjectyespaging state
page.nextCursorstring or nullyespass as cursor for the next page; null on the last page
page.hasMorebooleanyeswhether another page follows
asOfUTC timestampyeswhen the list was read

Hub

FieldTypeRequiredMeaning
codehub codeyesthe hub's registered code, such as FRA
namestringyesthe hub's place name
regionstringyesthe region the schedule groups it in for regional runs
ecefobjectyesregistered location as integer ECEF coordinates in metres (WGS84), as in SIMD-0674
ecef.xintegeryesmetres, WGS84 ECEF x
ecef.yintegeryesmetres, WGS84 ECEF y
ecef.zintegeryesmetres, WGS84 ECEF z
latitudenumber, -90 to 90yesdegrees
longitudenumber, -180 to 180yesdegrees
registrantaddressyesthe wallet that registered the hub and receives the deposit on release
depositLamportsu64 stringyesthe deposit held in the hub account
membersMember[]yesthe hub's members
stakeu64 stringyestotal stake of the members, lamports
proposerStakeu64 stringyeshub stake: the sum of the members' proposer stakes, lamports
proposerStakeCapu64 stringyesthe cap c: no member's proposer stake exceeds it, 1/k of the hub stake
status"active", "pending", "inactive"yesactive when it meets every active-hub condition; pending until it does; inactive once it stopped meeting them
needsobjectyeswhat a pending hub still lacks to become active
needs.membersintegeryesmembers still needed; 0 when enough
needs.stakeu64 stringyesproposer stake still needed, lamports; 0 when enough
createdEpochintegeryesthe epoch the hub was registered
lastActiveEpochinteger or nullyesthe last epoch the hub was active; null if never
releasableEpochinteger or nullyesthe epoch from which anyone can release it; null while it is active
releasablebooleanyeswhether release_hub can be called on it now

Member

FieldTypeRequiredMeaning
identityaddressyesthe validator's identity address
hubCodehub codeyesthe hub it is a member of
stakeu64 stringyesits stake, lamports
proposerStakeu64 stringyesits proposer stake: its stake capped at the hub's proposerStakeCap
cappedbooleanyeswhether its stake exceeds the cap, making it a proposer in every window of its hub
effectiveEpochintegeryesthe epoch its membership takes effect in the schedule
joinedEpochintegeryesthe epoch it signed its join
pendingMovehub code or nullyesthe hub it is moving to at the next boundary; null if none
pendingLeavebooleanyeswhether it leaves at the next boundary
cooldownUntilEpochintegeryesthe first epoch it may join, leave or move again

RegistryConfig

FieldTypeRequiredMeaning
status"fixture", "waiting", "ready"yesready when the program is deployed and configured
programIdaddress or nullyesthe hub_registry program address; null until deployed
cluster"localnet", "mainnet-beta"yesthe Solana cluster the registry lives on
depositLamportsu64 string or nullyesthe deposit register_hub takes, returned on release
registrationFeeBpsinteger, 0 to 10000 or nullyesthe registration fee, basis points of the deposit
cooldownEpochsinteger or nullyesepochs a validator waits between membership changes
inactivityEpochsinteger or nullyesepochs a hub may stay inactive before anyone can release it
codeRulesobjectyesthe rule a hub code must meet
codeRules.patternstring or nullyesregular expression a code must match
codeRules.minLengthinteger or nullyesshortest code
codeRules.maxLengthinteger or nullyeslongest code
minimumMembersinteger or nullyesn_min, members an active hub needs
minimumStakeu64 string or nullyesρ_min, hub stake an active hub needs, lamports
currentEpochintegeryesthe Solana epoch the registry reads now
missingConfigurationstring[]yesnames of the settings still missing

SchedulePreview

FieldTypeRequiredMeaning
epochintegeryesthe epoch this schedule is for
seedstringyesthe PRNG seed derived from the epoch
source"fixture", "registry"yesregistry when computed from the registry and a stake snapshot
algorithm3yesalways 3: the paper's Algorithm 3
alphanumber, 0 to 1yesα, the share of windows assigned by hub stake
totalWindowsintegeryeswindows in the epoch
sharesobject[]yeseach active hub's share of the windows
shares.hubCodehub codeyesthe hub
shares.proposerStakeu64 stringyesits hub stake, lamports
shares.probabilitynumberyesπ_h, its probability per window
shares.assignedWindowsintegeryeswindows it was drawn for
regionalRunsobject[]yesthe SIMD-0675 runs of consecutive windows in one region
regionalRuns.regionstringyesthe run's region
regionalRuns.firstWindowintegeryesfirst window of the run
regionalRuns.lastWindowintegeryeslast window of the run
windowsWindow[]yesevery window with its hub and three proposers

FaucetStatus

FieldTypeRequiredMeaning
addressaddressyesthe address asked about
policyFaucetPolicyyesthe faucet's policy
remainingForKeyinteger or nullyesgrants this address has left in the period
remainingForIpinteger or nullyesgrants the caller's IP has left in the period
resetsAtUTC timestamp or nullyeswhen the period resets; null if no grant is counted
eligiblebooleanyeswhether a grant would succeed now

FaucetPolicy

FieldTypeRequiredMeaning
amountLamportsu64 string or nullyeslamports per grant
perKeyinteger or nullyesgrants per address per period
perIpinteger or nullyesgrants per IP per period
periodSecondsinteger or nullyeslength of the period
missingConfigurationstring[]yesnames of faucet settings still missing

FaucetRequest

FieldTypeRequiredMeaning
addressaddressyesthe Acrux Net address to fund

FaucetGrant

FieldTypeRequiredMeaning
idstringyesthe grant's ID
transactionIdhash, optionalnothe transfer's transaction ID, for getTransaction
addressaddressyesthe funded address
amountLamportsu64 stringyeslamports granted
signaturesignatureyesthe Acrux Net transfer's signature
balanceBalanceyesthe address's balance after the grant
grantedAtUTC timestampyeswhen it was granted

LabScenario

FieldTypeRequiredMeaning
idScenarioIdyesthe scenario
titlestringyesits name
descriptionstringyeswhat the faulty node does
seedstringyesthe default seed; a run with the same seed plays the same
parametersmap of string to string or number or booleanyesthe scenario's settings: the faulty proposer, its delay, the target slot and the like
lemmastringyesthe paper's result the outcome shows
expectedOutcomestringyeswhat the protocol does in answer

ScenarioId

ValueMeaning
last-looka proposer delays its commitment to see the others first
censorshiptwo proposers drop a transaction the third carries
crasha proposer is down from the window's start
equivocationa proposer sends two blocks for one slot
split-commitmentsa proposer sends its commitment to one co-proposer only
private-front-runa proposer tries to read a 2-of-3 swap and front-run it

LabRunRequest

FieldTypeRequiredMeaning
scenarioScenarioIdyesthe scenario to run
seedstring, 1 to 128 characters, optionalnoa seed of your own; the scenario's default if omitted

LabRuns

FieldTypeRequiredMeaning
itemsLabRun[]yesthe runs on this page
pageobjectyespaging state
page.nextCursorstring or nullyespass as cursor for the next page; null on the last page
page.hasMorebooleanyeswhether another page follows
asOfUTC timestampyeswhen the list was read

LabRun

FieldTypeRequiredMeaning
idstringyesthe run's ID, the address of /lab/[run]
scenarioLabScenarioyesthe scenario run
seedstringyesthe seed it ran with
status"queued", "running", "done", "failed_to_start"yeswhere the run stands
createdAtUTC timestampyeswhen it was requested
startedAtUTC timestamp or nullyeswhen its sandbox cluster started
endedAtUTC timestamp or nullyeswhen it ended
outcomestring or nullyeswhat the protocol did, once done
evidenceEvidence[]yesthe evidence recorded
failurestring or nullyeswhy it failed to start

Evidence

FieldTypeRequiredMeaning
kind"late_block_dropped", "transaction_included", "two_proposers_continue", "slashing_proof", "skip_certificate", "unreadable_fragment"yeswhich outcome it proves; one per scenario, in the order of ScenarioId
slotintegeryesthe slot it belongs to
proposerproposer index or nullyesthe proposer it concerns
txIdhash or nullyesthe transaction it concerns
descriptionstringyeswhat it shows, in a sentence
hasheshash[]yesthe commitments, blocks or certificates it rests on
signaturessignature[]yesthe signed messages it rests on; for a slashing proof, the two conflicting ones
observedFragmentsinteger or nullyesfor an unreadable fragment: fragments the attacker held
thresholdinteger or nullyesfor an unreadable fragment: the t needed to read it

LabReplay

FieldTypeRequiredMeaning
runLabRunyesthe run
eventsProtocolEvent[]yesevery event it recorded, in order

Facts

FieldTypeRequiredMeaning
source"fixture", "measured"yesmeasured when taken from the net
measuredAtUTC timestampyeswhen the sample ended
sampleSizeintegeryesslots in the sample
slotPacingUsobjectyestime between consecutive slot starts
slotPacingUs.p50integeryesmedian, µs
slotPacingUs.p99integeryes99th percentile, µs
commitSpreadUsobjectyestime between the first and last commitment of a slot
commitSpreadUs.p50integeryesmedian, µs
commitSpreadUs.p99integeryes99th percentile, µs
attestationRelativeToBlockUsobjectyeswhen attestations reach validators relative to the block; negative is before
attestationRelativeToBlockUs.p50integeryesmedian, µs
attestationRelativeToBlockUs.p99integeryes99th percentile, µs
cblockFinalizationUsobjectyestime from a cblock's first slot to its finalization
cblockFinalizationUs.p50integeryesmedian, µs
cblockFinalizationUs.p99integeryes99th percentile, µs
handoverUsmap of string to objectyeswindow handovers per hub link, keyed like FRA-NYC: p50, p99, the link's floor (50 ms plus the arrival of the second hub's votes for the 60% certificate) and the sample count, in µs

SpecMap

FieldTypeRequiredMeaning
paperstringyesthe paper and version implemented
parametersParametersyesthe parameters the net runs
entriesobject[]yesone per algorithm line or lemma
entries.referencestringyesthe paper's reference, such as Algorithm 1 or Lemma 2.3
entries.linesstring or nullyesthe algorithm's line numbers
entries.filestringyesthe file that implements it
entries.functionstringyesthe function that implements it
entries.scenarioScenarioId or nullyesthe Fault Lab scenario that shows it
entries.status"fixture", "planned", "implemented"yesimplemented once the code stands
decisionsobject[]yesthe choices the paper leaves open
decisions.topicstringyeswhat was left open
decisions.decisionstringyesAcrux's choice
decisions.status"decided", "configuration_required", "fixture_only"yesdecided when fixed; configuration_required when the operator sets it

Errors

ApiError

Every failed response from the API, and the data of every JSON-RPC error from the gateway.

FieldTypeRequiredMeaning
errorobjectyesthe failure
error.codeErrorCodeyesthe stable code to branch on
error.messagestringyesa sentence to show
error.retryablebooleanyeswhether the same request may succeed later
error.stage"validation", "auth", "read", "upload", "build", "wallet", "co_sign", "simulation", "send", "confirmation"yesthe step of the flow that failed
error.fieldErrorsmap of string to string[], optionalnofor invalid input: each field path and what is wrong with it
error.programErrorobject, optionalnofor a refused Solana transaction: the program that raised it
error.programError.programIdaddressyesthe refusing program's address
error.programError.namestringyesthe program's error name
error.programError.numbernumber, optionalnothe program's error number
error.retryAfterSecondsnumber, optionalnowhen to retry, for limits
error.requestIdstring, optionalnothe request's ID, for reports

ErrorCode

CodeHTTPMeaning
VALIDATION_ERROR400the request failed validation; see fieldErrors
UNAUTHORIZED401the request needs credentials it did not carry
ORIGIN_NOT_ALLOWED403a browser origin the service does not serve
NOT_FOUND404no such hub, member, slot, transaction, run or method
PROGRAM_UNAVAILABLE409the Hub Registry program is not deployed or not reachable
CONFIGURATION_REQUIRED409the service lacks a setting the call needs; the message names it
IDEMPOTENCY_CONFLICT409the same ID was submitted before with different content
TRANSACTION_EXPIRED409the target slot has started, or the transaction is already settled
PAYLOAD_TOO_LARGE413the body exceeds the limit
UNSUPPORTED_MEDIA_TYPE415the body is not JSON
SIMULATION_FAILED422a Solana transaction failed simulation
CHAIN_REFUSED422a Solana transaction was refused by a program; see programError
RATE_LIMITED429too many requests; see retryAfterSeconds
INTERNAL_ERROR500the service failed
UPSTREAM_UNAVAILABLE502a service this one depends on did not answer
FAUCET_LIMIT429this key or IP has used its faucet grants for the period
NET_STALLED503Acrux Net has stopped producing slots
NET_UNAVAILABLE503the gateway could not be reached
INVALID_INPUT400the gateway refused the params or the submission