RPC and networking
RPC security boundaries
Bind RPC and WebSocket listeners to loopback and use a private tunnel for remote
access. If you expose a public API, put authentication and traffic controls in
front of it; the limits below do not make it safe to expose an administration node. genesis_endorse requires an HTTP
Authorization: Bearer <token> header. Configure BURST_RPC_ADMIN_TOKEN with a
securely generated 64-character hexadecimal secret (for example, openssl rand -hex 32). Without that environment variable the HTTP administration action is
disabled. Never commit the token or put it in URLs. Nodes holding a genesis seed
refuse non-loopback RPC binds; use a private tunnel for remote administration.
RPC batches contain at most 32 actions and consume rate-limit capacity per action.
At most 32 handlers run concurrently, with a 30-second request deadline. Work
requests have two active slots, a 15-second cooperative computation deadline and
a maximum requested difficulty of 64 times the protocol requirement in expected
work. These are local service limits, not consensus parameter changes. Native
clients reject JSON response bodies exceeding 16 MiB, including chunked bodies.
That bounds the collected byte buffer, not total HTTP or parsed-JSON memory.
The shared reader does not check HTTP status or define a timeout; callers apply
those policies before interpreting the RPC result.
WebSocket sessions are capped at 64 and incoming frames/messages at 64 KiB.
Block-authoring helpers share the same work capacity and deadline. Legacy
verifier_opt_in / verifier_opt_out server-signing RPCs are available only on
dev/test networks with the faucet enabled. Production wallets use local signing
and submit the signed block through process; never send private keys to a node.
Test faucet
On Dev and Test, an enabled faucet with the network's genesis seed can create
one TRST pending for a recipient by burning one BRN from the genesis account.
The recipient accepts it with a signed receive. This does not verify the wallet;
bootstrap verification uses the separate genesis_endorse action. The faucet
is unavailable on Live.
Client integration
For request formats, pagination and signed block submission, see the RPC guide. For subscriptions and reconnect handling, see WebSocket events.
Peer admission and traffic budgets
Peer limits count both pending connections and established sockets. They use the
observed transport address, not a peer's advertised address or node identity.
IPv4-mapped IPv6 addresses share the IPv4 allowance. Live defaults permit four
connections per IPv4 address or IPv6 /64, and sixteen per IPv4 /24 or IPv6 /48.
Eight of max_peers slots are reserved for outbound connections; this reservation
is clamped to leave at least one inbound slot on small configurations. Permits
remain held until the socket tasks release them, including cancelled handshakes.
Dev/test networks default to allowing a same-address cluster up to max_peers,
without an outbound reservation. An explicit [peer_limits] table overrides that
policy; omitted fields within the table use the live defaults. For a deployment
with many legitimate nodes behind one NAT, set explicit limits rather than
disabling address accounting:
[peer_limits]
per_ip = 12
per_subnet = 24
outbound_reserved = 8
[bandwidth_limits]
total_bytes_per_second = 10485760
bulk_bytes_per_second = 8388608
Block ingress schedules address buckets fairly, retaining PoW priority within each bucket. Each network bucket can queue up to 256 blocks; the scheduler reserves roughly one quarter of ingress capacity for other work (with integer rounding for small capacities). Local submissions and already retained recovery blocks have separate scheduling lanes. Recovery keeps its existing shared retention permit; these policies do not bypass block validation. Ordinary publishes and correlated bootstrap replies use the same network quota.
The P2P egress budget is shared across all peers: by default 10 MiB/s total, of which bulk traffic can use at most 8 MiB/s. Each connection also has a 5 MiB/s budget with bulk limited to 4 MiB/s. Buckets allow one second of burst capacity. Control and bulk messages have separate bounded queues (64 and 256 messages). Control is sent first between frames; an in-progress frame cannot be interrupted. Bulk sends that exceed the bandwidth budget are dropped. Control messages wait for credit within the writer's 30-second deadline. Queue admission can still fail when its bounded queue is full. These limits cover framed P2P traffic, not RPC, WebSocket traffic or the small pre-registration handshake exchange.
These are local resource policies, not changes to consensus rules. They reduce concentration and starvation risks; they do not prevent a distributed attacker from saturating a service. Public-load and release qualification remain separate.