Skip to main content
The tutorial uses development-friendly keys, permissions, and configuration. Do not copy it into production unchanged.

Configure light-client security

Attestor set and threshold

An n-attestor set with threshold t tolerates n - t unavailable attestors; forging state requires t compromised keys. There is no universal production threshold. Choose n and t by stating how many unavailable and compromised keys the deployment must tolerate. For example, 2-of-3 tolerates one unavailable or compromised key, while 3-of-5 tolerates two. These are example profiles, not protocol requirements. The attestor set and minRequiredSigs are fixed in the on-chain client. Verify both on chain before enabling relaying.
  • Quorum: Never use a one-of-one attestor set in production. One unavailable attestor stops the connection, and one compromised key can forge state.
  • Key reuse: Never reuse an attestor key across clients or chains because signatures are not bound to a chain, router, or verifying client.

Besu clients

For a QBFT or IBFT 2.0 counterparty, see Besu light clients for the parameter mechanics and update rules. In production:
  • Keep the default trustLevel of 2/3 unless the deployment’s threat model explicitly selects a lower value.
  • Choose trustingPeriod from the counterparty’s validator governance and key-retirement policy. It must be long enough that packet activity advances the client before expiry, but no longer than historical validators remain trustworthy.

Set contract permissions deliberately

ibc deploy core makes relaying public. In production, prefer permissioned relaying: grant RELAYER_ROLE to the relayer account for IBCMulticall.multicall and to IBCMulticall for the router’s relay functions before replacing PUBLIC_ROLE. Use permissionless relaying only as an explicit policy choice. See Grant, change, and revoke a role. At minimum, transfer ADMIN_ROLE and each IFT’s authority from the deployer to a multisig. Best practice is a timelocked governance executor controlled by a multisig or on-chain governance, with an on-chain delay for upgrades, role changes, client migrations, and IFT configuration. OpenZeppelin’s TimelockController is one implementation.

Configure IFT rate limits

Configure and verify a rate limit independently on every IFT deployment. Choose its capacity and window from the maximum loss or issuance acceptable before governance can intervene, not merely from expected throughput. Account for token decimals and traffic across every registered bridge. See IFT rate limits for contract behavior and ibc deploy ift for configuration flags.

Configure signing and services

Signing

Use a dedicated key for every role and trust boundary: one administration key, one deployment key, one relayer account per chain, and one key per attestor. Never reuse keys across roles, chains, services, or hosts. In production, use Cosmos KMS as the remote signer for relayer and attestor keys. Protect the administration role with multisig approval where supported. Treat the deployment key as temporary: fund it only for deployment, then revoke its privileges and remove it.

Attestors

Never run attestors in-process with the relayer in production. Run each attestor as a standalone process with a unique signer, and configure it as a remote attestor in the relayer.
An attestor trusts its configured chain RPC for state correctness. Use an endpoint whose operator and data you trust; changing that endpoint changes the attestor’s trust assumptions. Each local attestor selects its highest attestable height:
  • finalityOffset: 0 uses the RPC endpoint’s finalized block.
  • A positive value uses latest - finalityOffset without proving that block final.
Besu QBFT and IBFT 2.0 chains do not support finalityOffset: 0. Use finalityOffset: 1; their committed blocks have immediate finality, so a larger offset only delays attestations. Omitting the field selects zero. Use the same finalityOffset for every attestor in the quorum.

Relayers

For each client end, verify the chain ID, client ID, light-client type, signer, and autoRelay setting. Use a separate funded signer for each destination chain. A relayer trusts each configured chain RPC for operational chain data and transaction submission. Use endpoints whose operators and data you trust; changing an endpoint changes the relayer’s trust assumptions. The light client prevents a relayer RPC from forging packet state, but the RPC still controls the relayer’s view of heads, receipts, nonces, gas, and fees. A relayer database must have only one active relayer process. Multiple active relayers sharing a database are not supported.