Skip to main content

​
Configuration

Configure the Watch Tower to monitor blockchain networks and manage programmatic orders. The Watch Tower uses a JSON configuration file to define network settings, RPC endpoints, and filtering policies.

​
Configuration file

The Watch Tower requires a config.json file. You can use the provided example as a starting point: 
cp config.json.example config.json

​
Configuration schema

The configuration file follows this structure: 
{
  "networks": [
    {
      "name": "mainnet",
      "rpc": "https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY",
      "deploymentBlock": 17883049,
      "filterPolicy": {
        "defaultAction": "ACCEPT"
      }
    }
  ]
}

​
Network configuration

Each network in the networks array supports the following options:

​
Required fields

name (string, required) Network identifier (e.g., mainnet, sepolia, arbitrum_one, gnosis_chain, base) rpc (string, required) RPC endpoint URL. Supports both HTTP/HTTPS and WebSocket connections. Examples:
  • https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
  • wss://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
  • https://sepolia.drpc.org
deploymentBlock (integer, required) Block number where the ComposableCoW contract was deployed. The Watch Tower only processes events from this block onwards to optimize performance. Deployment blocks by network:
  • Mainnet: 17883049
  • Sepolia: 8468184
  • Arbitrum One: 343493668
  • Gnosis Chain: 40394915
  • Base: 31084679
  • Avalanche: 63235114
  • Polygon: 72315184
  • Linea: 25028604
  • Plasma: 4810535
  • Ink: 37142449
See Deployed Contracts for the complete list.
filterPolicy (object, required) Defines filtering rules for conditional orders. See Filter policy below.

​
Optional fields

orderBookApi (string) Custom OrderBook API endpoint URL. If not specified, uses the default CoW Protocol API for the network. pageSize (integer, default: 5000) Number of blocks to fetch per request when querying historical events (eth_getLogs).
  • Default: 5000 (Infura’s maximum)
  • Set to 0 to fetch all blocks in one request (useful for private RPC nodes)
Setting pageSize to 0 may cause issues with some RPC providers that have block range limits.
watchdogTimeout (integer) Timeout in milliseconds for the watchdog timer. If no new blocks are received within this time, the Watch Tower will alert. processEveryNumBlocks (integer, default: 1) Throttle block processing to only process every N blocks.
  • 1 - Process every block (default)
  • 2 - Process every other block
  • 10 - Process every 10th block
Useful for reducing RPC load on networks with high block production rates.

​
Filter policy

The filter policy controls which conditional orders are processed by the Watch Tower.

​
Structure

{
  "filterPolicy": {
    "defaultAction": "ACCEPT",
    "conditionalOrderIds": {
      "0x5b3cdb6ffa3c95507cbfc459162609007865c2e87340312d3cd469c4ffbfae81": "DROP"
    },
    "transactions": {
      "0x33ef06af308d1e4f94dd61fa8df43fe52b67e8a485f4e4fff75235080e663bfa": "DROP"
    },
    "handlers": {
      "0xd3338f21c89745e46af56aeaf553cf96ba9bc66f": "DROP"
    },
    "owners": {
      "0xd3338f21c89745e46af56aeaf553cf96ba9bc66f": "DROP"
    }
  }
}

​
Filter actions

defaultAction (string, required) Default action for items not explicitly listed in filters.
  • ACCEPT - Process the order (recommended)
  • DROP - Ignore the order
  • SKIP - Skip processing temporarily
conditionalOrderIds (object) Map of conditional order IDs to filter actions. Use this to block or allow specific order IDs. transactions (object) Map of transaction hashes to filter actions. Use this to filter orders from specific transactions. handlers (object) Map of handler contract addresses to filter actions. Use this to filter orders by their handler contract. owners (object) Map of owner addresses (safes) to filter actions. Use this to filter orders by the owning address.

​
Example configurations

​
Multi-network setup

{
  "networks": [
    {
      "name": "mainnet",
      "rpc": "https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY",
      "deploymentBlock": 17883049,
      "pageSize": 5000,
      "filterPolicy": {
        "defaultAction": "ACCEPT"
      }
    },
    {
      "name": "arbitrum_one",
      "rpc": "https://arb1.arbitrum.io/rpc",
      "deploymentBlock": 343493668,
      "filterPolicy": {
        "defaultAction": "ACCEPT"
      }
    },
    {
      "name": "gnosis_chain",
      "rpc": "https://rpc.gnosischain.com",
      "deploymentBlock": 40394915,
      "filterPolicy": {
        "defaultAction": "ACCEPT"
      }
    }
  ]
}

​
Development setup (Sepolia)

{
  "networks": [
    {
      "name": "sepolia",
      "rpc": "https://sepolia.drpc.org",
      "deploymentBlock": 8468184,
      "pageSize": 0,
      "filterPolicy": {
        "defaultAction": "ACCEPT"
      }
    }
  ]
}

​
With custom filtering

{
  "networks": [
    {
      "name": "mainnet",
      "rpc": "wss://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY",
      "deploymentBlock": 17883049,
      "filterPolicy": {
        "defaultAction": "ACCEPT",
        "owners": {
          "0xblockedaddress": "DROP"
        },
        "handlers": {
          "0xcustomhandler": "ACCEPT"
        }
      }
    }
  ]
}

​
Configuration via environment variables

You can override the configuration file path using the CONFIG_PATH environment variable: 
CONFIG_PATH=/path/to/custom/config.json yarn cli run

​
Important notes

Conditional order types may consume considerable RPC calls. Monitor your RPC provider’s rate limits and usage.
The deploymentBlock setting is critical for performance. Setting it too low will cause unnecessary historical event queries, while setting it too high will miss orders.

​
Next steps

After configuring the Watch Tower:
Last modified on March 4, 2026