@morpho-dev/router

Router

Status: Alpha – this is under active development and interfaces/behavior are subject to change.

CLI

CLI install

pnpm add -g @morpho-dev/router

• Router configuration is read from a TOML file
• router start accepts --config-file (or ROUTER_CONFIG_FILE/./router.toml)
• Indexer chains can be selected in TOML ([indexer].chains) or at runtime with --chains
• Seed mock offers with --mock <n> for testing
• Load offers from JSON file with --file <path>
• When [indexer] is enabled, a monitoring server is started (default :8083) exposing readiness and metrics endpoints
• API /metrics is API-only (HTTP/process telemetry)
• Indexer /metrics is the source of truth for sync gauges (router_collector_block_number, router_chain_block_number, router_chain_remote_block_number)
• Collector lag is derived in PromQL (remote - collector) and is no longer emitted as router_collector_lag_blocks

Examples:

# Start router from a config file
router start --config-file ./router.toml

# Start router using the env fallback
ROUTER_CONFIG_FILE=./router.toml router start

# Start router indexer only on one chain (when [indexer].chains is omitted)
router start --config-file ./router.toml --chains ethereum

# Start router with mock offers for testing
router start --config-file ./router.toml --mock 100

# Start router with offers loaded from a JSON file under the current directory
router start --config-file ./router.toml --file offers.json

Chain

Use router chain to manage the anvil chain for dev and E2E workflows.

# Start a chain and emit JSON status
router chain start --output json

# Check chain status
router chain status --output json

# Stop the chain and purge state
router chain stop --purge

Example router.toml:

[logging]
level = "info"

[database]
# Use url_env for an existing PostgreSQL database, or managed = true
# to launch an ephemeral PostgreSQL 17 server with local binaries.
url_env = "DATABASE_URL"

[api]
port = 7891
timeout_ms = 10000

[indexer]
block_window = 8000
metrics_port = 8083
# interval = 10000
# interval_by_chain = { base = 500, ethereum = 10000 }
# chains = ["ethereum"]
# If omitted, `router start` indexes all chains defined under [chains]

[chains."ethereum"]
rpc_url_env = "ETHEREUM_RPC_URL"

CLI reference

Global

Usage: router [options] [command]

Router package for Morpho protocol

Options:
  -V, --version                    output the version number
  -h, --help                       display help for command

Commands:
  start [options]                  Start Router services.
  chain                            Manage the chain lifecycle (Prool server with
                                   Anvil).
  gatekeeper [options]             Start Gatekeeper validation service.
  query [options]                  Start query projection service.
  operator [options] <command...>  Operator console for a remote router
                                   instance.
  help [command]                   display help for command

start

Usage: router start [options]

Start Router services.

Options:
  --config-file <path>  Path to router TOML config file
  --skip-migrations     Skip database migrations during startup
  --mock <n>            Number of mock offers to seed
  --chains <names>      Comma-separated chain names to index (e.g.
                        ethereum,base)
  --file <path>         Seed offers from a JSON file under the current directory
  -h, --help            display help for command

chain

Usage: router chain [options] [command]

Manage the chain lifecycle (Prool server with Anvil).

Options:
  -h, --help         display help for command

Commands:
  start [options]    Start a Prool server managing an Anvil instance.
  status [options]   Show chain status.
  stop [options]     Stop the chain process.
  restart [options]  Restart the chain process.
  deploy [options]   Deploy contracts to an already-running Anvil instance.
  logs [options]     Read anvil logs.
  help [command]     display help for command

gatekeeper

Usage: router gatekeeper [options]

Start Gatekeeper validation service.

Options:
  --config-file <path>  Path to router TOML config file
  --skip-migrations     Skip database migrations during startup
  -h, --help            display help for command

query

Usage: router query [options]

Start query projection service.

Options:
  --config-file <path>  Path to router TOML config file
  --skip-migrations     Skip database migrations during startup
  -h, --help            display help for command

operator

Usage: router operator [options] <command...>

Operator console for a remote router instance.

Arguments:
  command      Command to execute, e.g. `list offers` or `make offers=...`

Options:
  --url <url>  Router URL to connect to. (default: "https://api.morpho.org")
  --rpc <url>  RPC URL for on-chain transactions. (default:
               "https://base-rpc.publicnode.com")
  --pk <key>   Private key for write operations.
  -h, --help   display help for command