Running locally

Run the Watch Tower locally for development and testing

Running locally

Run the Watch Tower locally for development and testing.

Basic usage

Run the Watch Tower with the default configuration:

yarn cli run --config-path ./config.json

CLI commands

The Watch Tower CLI provides two main commands:

run

Start the Watch Tower in monitoring mode:

yarn cli run [options]

Available options:

• —config-path (string, default: ./config.json) Path to the chain configuration file.

  yarn cli run --config-path /path/to/config.json
  

  Environment variable: CONFIG_PATH

• —database-path (string, default: ./database) Path to the LevelDB database directory.

  yarn cli run --database-path /var/lib/watch-tower/db
  

  Environment variable: DATABASE_PATH

• —log-level (string, default: INFO) Set the logging level. Options: TRACE, DEBUG, INFO, WARN, ERROR.

  yarn cli run --log-level DEBUG
  

  Environment variable: LOG_LEVEL

• —dry-run (boolean, default: false) Run without publishing orders to the OrderBook API. Useful for testing.

  yarn cli run --dry-run
  

  Environment variable: DRY_RUN

• —one-shot (boolean, default: false) Run the Watch Tower once and exit instead of continuous monitoring.

  yarn cli run --one-shot
  

  Environment variable: ONE_SHOT

• —api-port (number, default: 8080) Port for the REST API server.

  yarn cli run --api-port 3000
  

  Environment variable: API_PORT

• —disable-api (boolean, default: false) Disable the REST API server.

  yarn cli run --disable-api
  

  Environment variable: DISABLE_API

• —silent (boolean, default: false) Disable notifications (local logging only, no Slack alerts).

  yarn cli run --silent
  

  Environment variable: DISABLE_NOTIFICATIONS

• —slack-webhook (string) Slack webhook URL for error notifications.

  yarn cli run --slack-webhook https://hooks.slack.com/services/YOUR/WEBHOOK/URL
  

  Environment variable: SLACK_WEBHOOK

• —only-owner (string[]) Monitor programmatic orders only from specific owner addresses (safes). Can be specified multiple times.

  yarn cli run --only-owner 0x1234... --only-owner 0x5678...
  

dump-db

Dump the database contents as JSON:

yarn cli dump-db --chain-id <chainId> [options]

Example:

yarn cli dump-db --chain-id 1 --database-path ./database

Expected output

When you start the Watch Tower, you should see output similar to:

[INFO] commands:run - Starting Rest API server...
[INFO] ApiService - REST API server started on port 8080
[INFO] commands:run - Starting chain mainnet...
[INFO] commands:run - Starting chain sepolia...
[INFO] chainContext - Warming up chain mainnet from block 17883049
[INFO] chainContext - Processing block 18234567 on mainnet
[INFO] chainContext - Found 2 ConditionalOrderCreated events
[INFO] chainContext - Found 1 MerkleRootSet event
[INFO] checkForAndPlaceOrder - Placed order 0xabc123... for owner 0xdef456...

What the Watch Tower does

When running, the Watch Tower continuously:

1. Monitors blockchain events - Listens for ConditionalOrderCreated and MerkleRootSet events
2. Fetches programmatic orders - Retrieves order details from the blockchain
3. Posts discrete orders - Submits orders to the CoW Protocol OrderBook API
4. Updates registry - Maintains a local database of active programmatic orders
5. Removes expired orders - Cleans up orders that have expired or been cancelled

Accessing the API server

By default, the Watch Tower starts a REST API server on port 8080 with the following endpoints:

Version information

curl http://localhost:8080/api/version

Response:

{
  "name": "@cowprotocol/watch-tower",
  "version": "2.14.0",
  "description": "A standalone watch tower, keeping an eye on Composable Cows"
}

Configuration

curl http://localhost:8080/config

Response: Returns the current Watch Tower configuration (excluding sensitive data).

Database dump

curl http://localhost:8080/api/dump/1

Response: Returns the complete database state for chain ID 1 (mainnet) in JSON format.

Prometheus metrics

curl http://localhost:8080/metrics

Response: Returns Prometheus-formatted metrics for monitoring.

Viewing logs

The Watch Tower uses a flexible logging system that can be controlled via the LOG_LEVEL environment variable.

Basic log levels

Set the global log level:

LOG_LEVEL=DEBUG yarn cli run --config-path ./config.json

Available levels: TRACE, DEBUG, INFO, WARN, ERROR

Module-specific logging

Enable detailed logging for specific modules:

# Enable INFO level for chainContext module
LOG_LEVEL=WARN,chainContext=INFO yarn cli run --config-path ./config.json

# Enable TRACE level for order placement
LOG_LEVEL=INFO,_placeOrder=TRACE yarn cli run --config-path ./config.json

Advanced logging patterns

Use regex patterns to match specific logger names:

# Match chainContext:processBlock with any chain ID and block number
LOG_LEVEL="chainContext:processBlock:(\d{1,3}):(\d*)$=DEBUG" yarn cli run

# Complex example with multiple overrides
LOG_LEVEL="WARN,commands=DEBUG,^checkForAndPlaceOrder=WARN,^chainContext=INFO" yarn cli run

Running in development mode

1. Set up test configuration

   Create a development configuration file for Sepolia testnet:

   cp config.json.example config.sepolia.json
   

   Edit to include only the Sepolia network with your test RPC endpoint.

2. Enable debug logging

   Run with detailed logging to see all operations:

   LOG_LEVEL=DEBUG yarn cli run --config-path ./config.sepolia.json
   

3. Use dry-run mode

   Test without actually posting orders to the OrderBook API:

   yarn cli run --config-path ./config.sepolia.json --dry-run
   

4. Test one-shot mode

   Process current state once and exit:

   yarn cli run --config-path ./config.sepolia.json --one-shot
   

Using environment variables

You can configure the Watch Tower entirely through environment variables:

export CONFIG_PATH=./config.json
export DATABASE_PATH=./database
export LOG_LEVEL=INFO
export API_PORT=8080
export DRY_RUN=false

yarn cli run

Or use a .env file:

CONFIG_PATH=./config.json
DATABASE_PATH=./database
LOG_LEVEL=INFO
API_PORT=8080
SLACK_WEBHOOK=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

Then run:

yarn cli run

Monitoring specific safes

To monitor programmatic orders from specific Safe addresses only:

yarn cli run \
  --config-path ./config.json \
  --only-owner 0x9008D19f58AAbD9eD0D60971565AA8510560ab41 \
  --only-owner 0x7f92a8b8b4d8d0e1c8d8e8f8a8b8c8d8e8f8a8b8

Stopping the Watch Tower

To gracefully stop the Watch Tower, press Ctrl+C. The Watch Tower will:

1. Stop processing new blocks
2. Complete any in-progress operations
3. Close the API server
4. Close the database connection
5. Exit cleanly

[INFO] commands:stop - Caught interrupt signal.
[INFO] ApiService - Stopping REST API server...
[INFO] DBService - Closing database...
[INFO] commands:stop - Exiting watchtower...

Troubleshooting

Database issues

If you encounter database errors, try removing the database and resyncing:

rm -rf ./database
yarn cli run --config-path ./config.json

RPC connection issues

Enable debug logging to see RPC connection details:

LOG_LEVEL=DEBUG yarn cli run --config-path ./config.json

Check that your RPC endpoint is accessible and has sufficient rate limits.

High RPC usage

Reduce RPC calls by:

• Increasing processEveryNumBlocks to skip blocks
• Setting pageSize appropriately for your RPC provider
• Using a dedicated RPC endpoint with higher rate limits

Next steps

After running locally:

• Deploy with Docker
• Deploy to DAppNode
• Monitor with Prometheus