Sync

State chain blocks are synchronised between peers using a dedicated libp2p stream protocol. This ensures all nodes converge on the same chain state, even if they were offline when blocks were published.

#Sync protocol

#Message types

#Request

type syncRequest struct {    TipIndex int64 `json:"tip_index"` // client's latest known block index}

A value of -1 means the client has no blocks (not even genesis) and wants everything from index 1 onward. Genesis (index 0) is never sent over sync -- it is configured locally.

#Response

type syncResponse struct {    Blocks  []*Block `json:"blocks"`    HasMore bool     `json:"has_more"`}

Responses are paginated. If HasMore is true, the client should expect additional response pages on the same stream.

#Sync flow

Client Node                          Server Node    │                                    │    │  open stream                       │    │───────────────────────────────────►│    │                                    │    │  syncRequest{TipIndex: 5}          │    │───────────────────────────────────►│    │  close write                       │    │                                    │    │  syncResponse{Blocks:[6..69],      │    │               HasMore: true}       │    │◄───────────────────────────────────│    │                                    │    │  syncResponse{Blocks:[70..100],    │    │               HasMore: false}      │    │◄───────────────────────────────────│    │                                    │    │  stream closed                     │

1. The client opens a stream to the server using the sync protocol ID.
2. The client sends a syncRequest with its current tip index, then closes the write side.
3. The server reads the request and sends back all blocks after the client's tip, paginated in chunks of 64.
4. Each page is a JSON-encoded syncResponse. The last page has HasMore: false.
5. The client applies each received block via chain.AddBlock().

#Trigger mechanisms

Sync is triggered in two ways:

#On peer connection

When a new peer connects, the node automatically initiates an outbound sync:

New peer connected    │    ▼Rate limit check (30s cooldown)    │    ▼Open sync stream → send tip index → receive blocks

This ensures nodes catch up immediately when they join the network or reconnect after downtime.

#Via gossip

New state chain blocks are broadcast to all peers via the xe/statechain gossip topic. When a node receives a gossip block, it calls chain.AddBlock() directly. If the block has a gap (e.g., the node missed earlier blocks), the add will fail, and the node will catch up on the next peer connection sync.

#Rate limiting

Both inbound and outbound sync are rate-limited independently:

The rate limiter automatically cleans up stale entries when checking for allowance.

#Startup replay

On startup, the chain replays all stored blocks to rebuild the in-memory KV state:

1. NewChain() applies genesis ops.
2. replay() reads all stored blocks (by index) and applies their ops in order.
3. After replay, the chain verifies that a valid sys.dao_keyset exists.
4. Sync handlers are registered so the node can catch up from peers.

#Size limits

#Error handling

• Block validation failures during sync are logged but do not abort the sync. The node continues processing remaining blocks -- a single invalid block does not poison the session.
• Stream errors (timeout, disconnect) terminate the sync. The node will retry on the next peer connection.
• Rate-limited requests are silently dropped by the server.