Concept
Peer-to-peer network
How Tenrai nodes find, authenticate and limit each other, how blocks, transactions and cuts travel, and how a node catches up.
Nodes form a peer-to-peer network over QUIC and TCP. For the operator's view, ports and options, see Networking and peers.
Joining
A node starts from peers its operator configured. Each one is named by its node identity and an address, so a node knows who it expects before it connects. From there it learns further peers.
A peer is admitted to chain traffic only when all of these agree:
- the transport identity of the connection,
- ML-DSA-65 authentication of this very connection, bound to its TLS session,
- the protocol, whose name includes the chain ID and the wire version,
- the peer's chain status.
Addresses that peers advertise are hints for dialing and nothing more. Public discovery refuses private, loopback, link-local and multicast addresses and DNS names supplied by peers.
Bootstrap and relay peers
Bootstrap peers help new nodes find the network. Relay peers pass connections for nodes that cannot be reached directly. Both provide connectivity only. Neither can change a rule or a state transition, because every node checks everything it receives.
A node behind a router works over the connections it opens itself; no port has to be opened. AutoNAT tells a node whether others can reach it, and optional UPnP asks the router to forward the port. None of them guarantees an inbound route.
What travels
| Data | How |
|---|---|
| Transactions | Relayed to a few peers at a time after local admission |
| Work blocks | Relayed as they are found, on a lane of their own |
| Cuts and votes | Certified cuts are relayed to all; validators exchange votes on a separate overlay among themselves, directly or through other validators |
| History | Served on request to nodes that catch up |
A node pushes each new block and transaction to 6 peers by default. Fresh work has its own bounded backlog, separate from synchronization, so a flood of new blocks cannot stall a node that is catching up.
Every message is bounded in size, every peer in how much it may send and ask per minute, and every address in how many connections it may hold. A peer that exceeds those limits is cut off.
Catching up
A node that is behind asks a peer for the certified cuts that follow its own finalized head.
- The range must start at the requested height and rise by exactly one. Gaps, overlaps and reorderings are rejected.
- Each cut is verified against its certificate and applied only when every work block it registers or executes is present. Missing blocks are fetched from the peer that served the cut.
- If that peer disappears, the node keeps what it applied and continues from its head with the next qualified peer.
Because cuts are final, a syncing node never has to choose between competing histories. It only verifies certificates along one line of heights.
The mempool
Transactions enter a node's mempool through its API or from peers. Both ways run the same admission: size and mass, fee floor, validity interval, signatures, and that the inputs are not already used by another pooled transaction.
The pool is bounded by count, bytes and mass. When it is full it refuses new entries instead of dropping others silently. A transaction leaves when a finalized cut executes it, when its validity ends, when a cut spends one of its inputs, or when it proves invalid.
Mempools are local. They differ between nodes, they are not consensus state, and a restart begins with an empty one.