Networking

Tenzro Network nodes run on residential connections, mobile links, homelabs and data centres. All networking runs on one iroh endpoint per node: QUIC connections between endpoints, found through signed endpoint records, Tenzro's own discovery and relays. A node needs no inbound port.

On that one endpoint run:

• Gossip for network-wide broadcasts on named topics.
• Validator channels for consensus traffic, admitted only for the endpoints the committee names and authenticated by hardware consensus keys.
• Point-to-point protocols, one per ALPN, for block and state sync, the data-availability committee, inference between nodes, and A2A and MCP.
• Content-addressed transport for model weights, sealed shards and other blobs.

A node's endpoint id is vouched for by its hardware key, so the endpoint a peer talks to and the identity it authenticates belong together.

Gossip

Each topic maps to one gossip topic per chain id. A node checks every received message before it delivers it or passes it on: the neighbour that delivered it must not be banned and must stay within its rate limit, a message seen before is dropped, and a message must fit 1 MiB.

A follower executes a block only once a checkpoint certificate it verifies covers it, so blocks need no origin gate. Validators exchange consensus messages over their own channel, not over gossip.

Validator channels

Validator traffic is authenticated by key, not by where it arrives from. Consensus channels admit only the endpoints the committee names, and both ends prove their hardware consensus keys in the handshake. See Consensus.

Discovery

A new node finds the network from its genesis or from one boot identity, with no allowlisting by anyone:

• Boot identities. --boot-nodes takes machine identities (did:tenzro:machine:<id>, optionally with a relay URL), never network addresses. Without it, a node joins through the genesis validators.
• Signed endpoint records. Each machine's hardware key signs a record naming its current endpoint, the relays it is reachable through, a sequence number and a lifetime of a few hours, renewed at half-life. A record signed by another identity, expired, or older than one already held is refused.
• Tenzro discovery. Every node keeps a store of verified records and answers other nodes on the tenzro/discovery protocol. Each minute a node publishes its record to known peers and takes their snapshots, so a node that knows one Tenzro node comes to know the rest.
• Local networks. Cluster members on the same LAN find each other by multicast DNS, with no relay or outside service, so discovery works on a LAN with no internet at all. See LAN clustering.

NAT traversal and relays

Most home, mobile and office networks put a node behind NAT. A node needs no inbound port: it tries five ways to reach its peers, together.

1. Port mapping. The node asks the router to forward its UDP port over UPnP IGD, PCP or NAT-PMP, where the router offers one. Turn it off with [iroh] port_mapping = false.
2. Hole punching. Peers tell the node the address they see it at. When two machines report the same address, the node offers it to other peers, and both sides send packets at the same time so each NAT lets the other in. This works behind NATs that keep one public port for every peer, which most home routers do.
3. Birthday punching. Behind a symmetric NAT (a different public port for every peer), the node opens 256 sockets towards a peer behind an endpoint-independent NAT, and the peer sends 1,024 probes to random ports at the node's public address; one lands with a probability of about 98%. Each attempt runs at most five seconds and is not repeated for the same peer within ten minutes.
4. Peer relays. When neither side can be punched, both nodes go through a staked edge operator's node that both reach directly over UDP. It passes their packets along as QUIC datagrams, still end-to-end encrypted. A node keeps connections to the two lowest-latency peer relays it reaches directly, and names them in its signed endpoint record.
5. Relays. When nothing else works, traffic goes through a relay over HTTPS on TCP 443, end-to-end encrypted. A relay sees only ciphertext, so a node on a network that blocks UDP still reaches the whole network.

Nodes find relays from the boot list, from the endpoints staked edge operators publish on chain (tenzro_listRoleEndpoints with role edge), and from relays they met before. A relay is admitted only when its operator's signed record, served at <url>/identity, announces exactly that URL. tenzro stake relays (tenzro_listRelays) lists the staked relays with their last SLA verdict. Running one is the edge role; see Operators and roles.

tenzro-node doctor, run on the node's machine, reports what it found: addresses, port mapping, the firewall, the NAT type, the address peers see and the relay it uses. Validators should still have a direct address (a public IP, a forwarded UDP 9001, or a router with port mapping); a validator reached only through relays works, with higher latency.

When a local provider can serve a request, the network prefers it: a request goes to a provider on the same LAN before crossing the internet, and falls back to remote providers otherwise.

Restarts

Consensus tolerates up to f of n validator seats failing at once. A restarted node keeps its chain state and identity, generates a fresh endpoint key, publishes a new endpoint record and block-syncs from its tip. To upgrade, replace the binary and restart; never wipe the data directory.

Firewalls

Firewall rules on your host are yours to set. The endpoint binds UDP 9001 by default. Nothing depends on that port being reachable from outside; opening it only makes direct paths more likely.

Inspect

tenzro iroh info --rpc https://rpc.tenzro.com
tenzro iroh endpoint-id
tenzro node peers
tenzro node gossip-stats

Related

• Iroh
• Consensus
• Operators and roles
• Deployment