> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperlane.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Message Filtering

> Configure which messages to relay, and which to ignore

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](/docs/operate/config/config-reference) whitelist section.

These configs are stringified JSON objects with the following format:

```typescript theme={null}
// 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 hextype 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.

```json theme={null}
[
  { "senderAddress": "*", "destinationDomain": ["1"], "recipientAddress": "*" },
  {
    "senderAddress": "0xca7f632e91B592178D83A70B404f398c0a51581F",
    "destinationDomain": ["42220", "43114"],
    "recipientAddress": "*"
  },
  {
    "senderAddress": "*",
    "destinationDomain": ["42161", "420"],
    "recipientAddress": "0xca7f632e91B592178D83A70B404f398c0a51581F"
  }
]
```

A valid config may look like

```bash theme={null}
--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.