How an attestor works
An attestor reads one chain and signs a statement about the chain’s state at a certain height upon request. The attestor is stateless: it keeps no store of its own, and it reads the chain through an RPC endpoint it trusts to report accurate state. The light client needs those signatures because it stores no commitment root. Every claim it accepts has to arrive signed by its attestor keys. A set of attestors watches one chain, and the client that trusts that set lives on the other. Attestation is pull-based. An attestor signs when a relayer asks, and the relayer aggregates the signatures it gathers into one proof.
What an attestor signs
An attestor signs exactly two kinds of claim, both about a single height:- A state attestation binds a height to that block’s timestamp.
- A packet attestation binds a height to a list of packet paths in the router store and their commitments, where a zero commitment asserts the path is empty.
sha256(tag || sha256(attestationData)), where the tag is 0x01 for a state attestation and 0x02 for a packet attestation.
Before signing, an attestor checks each claim against its own view of the chain. It refuses any height above its attestable height, which is set by a finality offset. For a packet attestation it recomputes each path and reads the value on chain: a packet commitment must exist and match, an acknowledgement must exist, and a receipt must be absent. One failing packet in a batch produces no attestation at all.
The finality offset
Configured per attestor, the finality offset decides how far behind the chain head it will sign. It sets the attestable height, and a request above that height is refused rather than answered:- An offset of zero attests up to the chain’s own
finalizedblock. Omitting the field is the same input as writing0. - A positive offset of n attests up to
latestminus n blocks.
finalized tag lags far behind its head. On Ethereum proof of stake the tag runs roughly 12 to 15 minutes behind, and an offset of zero makes every relay wait out that lag.
The attestor set
An attestor set is the attestor addresses and the signature threshold that a light client accepts proofs from, which makes it the trust root of the connection. A connection has an attestation light client on each of its two chains, and each of those clients has a set of its own. The set itself lives on chain. The relayer’s configuration is a separate list of the attestors it can reach:- On chain, the addresses and threshold are fixed when the client is deployed. The constructor rejects an empty set, a zero threshold, a threshold larger than the set, and duplicate addresses.
- Off chain, the relayer’s configuration lists the attestors it can reach, in one flat
attestors[]list thatibc attestor runreads as well. Atype: localentry is an attestor the process runs itself, naming the chain it watches, a signer, and a finality offset. Atype: remoteentry carries only a name and a barehost:port. A remote attestor reports its own chain and signing address through anInfoRPC when the relayer dials it.
Rotating attestors
Attestor set rotation requires client migration on the router, which replaces the client contract under an existing client ID. Follow Rotate an attestor set to deploy a replacement client and migrate the existing client ID.Attestor keys
An attestor signs with one ECDSA key per attestor entry, resolved through a named signer. The address of that key is what appears in a client’s set: to the client, the attestor is its key. A key lives in one of two places:- A local keyfile on disk.
- A remote signing service that holds the key, reached over gRPC and addressed by a key id.
Use separate keys for independent clients and chains. Signatures are not bound to a chain, router, or verifying client.