Attestor Overview - Cosmos Docs

The IBC Attestor is a lightweight, blockchain-agnostic attestation service that provides cryptographically signed attestations of blockchain state for IBC cross-chain communication. IBC Attestors publish attestations on demand and are stateless: consumers of the service must send requests to the service’s gRPC server to receive attestations. Finality thresholds are configurable per deployment.

Attestation structure

IBC attestors support two kinds of attestations:

State attestations: Attest that a given chain produced a block at height x at time y
Packet attestations: Attest to the membership or non-membership of a commitment at a given height, based on the requested CommitmentType:
- COMMITMENT_TYPE_PACKET: asserts presence of a send packet commitment (emitted on SendPacket)
- COMMITMENT_TYPE_ACK: asserts presence of an acknowledgment commitment (emitted on WriteAcknowledgement)
- COMMITMENT_TYPE_RECEIPT: asserts absence of a receipt commitment (non-membership proof, used for timeouts)

Security model and trust assumptions

Within the context of IBC relaying, IBC attestors are an off-chain trusted service. Trust is established with on-chain components via two mechanisms:

Securely managed secp256k1 signing keys used by attestors to create attestations. The public parts of the keys must be registered with an on-chain light client;
An aggregation layer during relaying that asserts that configurable m-of-n signatures attest to the same state.

At the level of individual attestor instances, we make the following trust assumptions:

RPC endpoints provide accurate data
Private key is kept secure

Attestor instances can make the following security guarantees:

Packet commitments must be valid before signing:
- Packet: Must match computed value
- Ack: Must exist on chain
- Receipt: Must be absent (zero)
Signatures are cryptographically sound and 65-byte recoverable ECDSA
Any heights in gRPC queries cannot be greater than the configured finalization height

Architecture

Component Structure

┌────────────────────────────────────────┐
│           Attestor Binary              │
│  ┌──────────────────────────────────┐  │
│  │         gRPC Server              │  │
│  │  - AttestationService            │  │
│  │  - Reflection API                │  │
│  │  - Logging & Tracing             │  │
│  └────────┬──────────────┬──────────┘  │
│           │              │             │
│  ┌────────▼─────┐  ┌──── ▼─────────┐   │
│  │ Attestation  │  │    Signer     │   │
│  │    Logic     │  │ - Local       │   │
│  │ - State      │  │ - Remote      │   │
│  │ - Packet     │  └───────────────┘   │
│  └────────┬─────┘                      │
│  ┌────────▼─────┐                      │
│  │   Adapter    │                      │
│  │ - EVM        │                      │
│  │ - Solana     │                      │
│  │ - Cosmos     │                      │
│  └──────────────┘                      │
└────────────────────────────────────────┘

Operating an attestor instance

CLI and configuration

When running this program you need to specify:

--config <PATH>: path to the TOML config file (required)
--chain-type <evm|cosmos|solana>: the chain adapter to use (required)
--signer-type <local|remote>: the signing backend (optional, default: local)

Each chain and signer type has its own configuration parameters which are captured under separate sections in the configuration toml. Here is an example of how to configure an EVM attestor.

Chain adapters

To add support for new kinds of chains you need to implement the AttestationAdapter and AdapterBuilder interfaces, respectively.

The AttestationAdapter is responsible for retrieving on-chain state and ensuring this state can be parsed as:
- A valid height and timestamp for a StateAttestation
- A valid 32-byte commitment path for an IBC Packet
The AdapterBuilder enables per chain configurations needed by the AttestationAdapter implementation.

The CLI must also be extended to support any new chain types.

Adapter retry and backoff policy

Adapter RPC calls use a shared retry helper based on tokio-retry:

Strategy: exponential backoff
Initial delay: 200ms
Backoff factor: 2x
Maximum backoff delay: 2s
Attempts: 3 total (initial attempt + 2 retries)

Retries are currently applied only to transient retrieval failures (RetrievalError) and are shared across Cosmos, EVM, and Solana adapter implementations. This policy is intentionally code-defined (not part of the application config) to keep the service configuration surface minimal.

Signing requirements

Currently the IBC attestor supports two signing modes: local and remote. The remote signer delegates cryptographic operations to an external gRPC service, keeping private keys off the attestor host and supporting HSMs, KMS systems, or dedicated signing daemons. The attestor signing algorithm is as follows:

Retrieve relevant chain/packet state via the chain adapter
Encode the data using the ABI format to facilitate EVM parsing
The signer produces a 65-byte recoverable ECDSA signature (r||s||v) over sha256(domain_tag || sha256(attested_data)). The domain tag is a single byte: 0x01 for StateAttestation, 0x02 for PacketAttestation. It is not carried on the wire — verifiers reconstruct it from the response type to prevent cross-protocol replay.

Any new signer implementations must guarantee:

Arbitrary ABI-encoded data is hashed before signing
The signature is a 65-byte recoverable ECDSA signature (r||s||v)

Observability

The IBC attestor uses a logging middleware to time requests, set trace IDs, and add structured fields to traces. Currently these fields include:

Adapter kind
Signer kind
Requested height (where applicable)
Number of packets (where applicable)
Packet commitment kind (where applicable)

Documentation Index

​Attestation structure

​Security model and trust assumptions

​Architecture

​Component Structure

​Operating an attestor instance

​CLI and configuration

​Chain adapters

​Adapter retry and backoff policy

​Signing requirements

​Observability

​Logging

​Tracing