LogoLogo
  • ⏩Introduction
    • Hyperlane Introduction
    • Getting started
    • Why Should You Use Hyperlane?
  • Permissionless Interoperability
    • Overview
    • Deploy Hyperlane
    • Warp Routes
      • Deploy a Warp Route
      • Deploy a UI for your Warp Route
    • Modular Rollup Interoperability
  • Build With Hyperlane
    • Quickstarts
      • Messaging
      • Accounts
      • Queries
      • hyperlane-quickstart repo
    • Guides
      • Finding my messages
      • Automatically pay for interchain gas
      • Manually pay for interchain gas
      • Choosing an interchain gas paymaster contract
      • Unit testing
      • Specifying an ISM
      • V2 migration guide
    • Explorer
      • Debugging messages
      • Configuring PI Chains
      • REST API
      • GraphQL API
    • Troubleshooting/Developer FAQ
    • Example apps
  • APIs and SDKs
    • Messaging API
      • Send
      • Receive
    • Accounts API
    • Queries API
    • Warp Route API
    • Interchain gas paymaster API
    • Hyperlane App Framework
      • Example usage
        • HelloWorld
        • Interchain Token
      • Solidity SDK
        • HyperlaneConnectionClient
        • Router
      • NodeJS SDK
        • RPC Providers
        • Deployment
        • Interchain testing
        • Quoting gas payments
        • App Abstraction
    • Hooks API
      • Contract addresses
  • Protocol
    • Overview
    • Mailbox
    • Interchain security modules
      • Interface
      • Multisig ISM
      • Routing ISM
      • Aggregation ISM
      • Optimistic ISM
      • Wormhole ISM
      • Hook ISM
      • CCIP-Read ISM
    • Interchain gas payments
    • Staking and slashing
    • Agents
      • Validators
      • Relayers
      • Watchtowers
    • Warp Routes
    • Implementation Guide
  • Operators
    • Validators
      • Guide
      • AWS setup
      • Monitoring and alerting
    • Relayers
      • Guide
      • Message filtering
    • Agent keys
      • Hexadecimal keys
      • AWS KMS keys
    • Agent configuration
      • Configuration reference
    • Running with docker compose
  • Resources
    • FAQ
    • Glossary
    • Contract addresses
      • Permissionless Deployment Contract Addresses
    • Domain identifiers
      • Permissionless Domain Identifiers
    • Default ISM settings
    • Coming Soon: Hyperlane v3
    • Token sources & faucets
    • Latencies
    • Github
    • Discord
    • Website
Powered by GitBook
On this page
  1. Operators
  2. Relayers

Message filtering

Configure which messages to relay, and which to ignore

PreviousGuideNextAgent keys

Last updated 1 year ago

By default, the relayer will attempt to deliver messages sent from its origin chain to any of the configured destination chains.

Relayers may want to further filter the messages they attempt to deliver. For example, someone building an interchain app may want to run a relayer that only delivers messages sent to that application. Similarly, some relayers may wish to only relay messages to a subset of available chains.

Relayers may optionally filter the messages they deliver by setting the --whitelist or --blacklist environment variables. See also the configuration reference's and sections.

These configs are stringified JSON objects with the following format:

// A list of matching rules. A message matches if any of the list
// elements matches the message.
type MatchingList = Array<ListElement>;

// Matches a message if any of the provided values matches.
interface ListElement {
    originDomain?: NumericFilter
    senderAddress?: HashFilter
    destinationDomain?: NumericFilter
    recipientAddress?: HashFilter
}

type NumericFilter = Wildcard | U32 | Array<U32>;
type HashFilter = Wildcard | H256 | Array<H256>;

// 32-bit unsigned integer
type U32 = number | string;
// 256-bit hash (can also be less) encoded as hex
type H256 = string;
// Matches anything
type Wildcard = "*";

Both the whitelist and blacklists have "any" semantics. In other words, the relayer will deliver messages that match any of the whitelist filters, and ignore messages that match any of the blacklist filters.

For example, the following config used as a whitelist will ensure the relayer will relay any messages sent to Ethereum, any messages sent from address 0xca7f632e91B592178D83A70B404f398c0a51581F to either Celo or Avalanche, and any messages sent to address 0xca7f632e91B592178D83A70B404f398c0a51581F on Arbitrum or Optimism.

[
    {
        senderAddress: "*",
        destinationDomain: ["1"],
        recipientAddress: "*"
    },
    {
        senderAddress: "0xca7f632e91B592178D83A70B404f398c0a51581F",
        destinationDomain: ["42220", "43114"],
        recipientAddress: "*"
    },
    {
        senderAddress: "*",
        destinationDomain: ["42161", "420"],
        recipientAddress: "0xca7f632e91B592178D83A70B404f398c0a51581F"
    }
]

A valid config may look like

--whitelist='[{"senderAddress":"*","destinationDomain":["1"],"recipientAddress":"*"},{"senderAddress":"0xca7f632e91B592178D83A70B404f398c0a51581F","destinationDomain":["42220","43114"],"recipientAddress":"*"},{"senderAddress":"*","destinationDomain":["42161","420"],"recipientAddress":"0xca7f632e91B592178D83A70B404f398c0a51581F"}]'

The blacklist supersedes the whitelist, i.e. if a message matches both the whitelist and the blacklist, it will not be delivered.

whitelist
blacklist