Skip to main content
Use this as the technical reference for validator configuration. For setup flow, use Node Setup. For troubleshooting and operator procedures, use Operations. For health endpoints and alerts, use Monitoring.

​
config.toml

Copy config.template.toml to config.toml and fill in your values.

​
[node]

[node]
node_id = "oracle-1"        # Unique identifier used in logs
p2p_listen_addr = "0.0.0.0" # Address to listen on for P2P connections
p2p_port = 6690              # TCP port for ragep2p

​
[keys]

Choose one provisioning pattern. Option 1 — direct hex 
[keys]
offchain_private_key = "76918f97bfe8..."

[keys.onchain_private_key]
private_key = "ed6ca3d3ac17..."
Use this when you want explicit control over the key material. The offchain key is Ed25519 hex, while the dev/testing onchain key is a secp256k1 private key. The config encryption key is derived automatically from your offchain key. Do not try to configure it separately in config.toml. Option 2 — key file 
[keys]
key_file_path = "./keystore/ocr2_<id>.json"
Use this when you want the node to read the OCR2/offchain bundle from disk. The companion P2P identity must live beside it as ./keystore/p2p_<peerID>.json, so mount the whole ./keystore directory into the container if you run Docker. Keep both files at 0600 permissions. Option 3 — AWS KMS for the onchain key 
[keys]
offchain_private_key = "76918f97bfe8..."

[keys.onchain_private_key]
kms_key_id = "arn:aws:kms:us-east-1:123456789:key/abcd-1234"
Use this when you want the offchain/OCR2 identity managed separately from the production onchain signer. Supported KMS identifiers: full ARN, alias, or UUID. The KMS key must be an asymmetric signing key of type ECC_SECG_P256K1. In production, authorize only the validator runtime role to call kms:Sign. Keep admin principals able to manage the key, but do not grant them signing rights unless they also operate the validator. This keeps operational administration separate from report-signing authority.

​
[p2p]

[p2p]
bootstrap_peers = [
  "12D3KooWGc9hJKBWks3oq9e7H4oZseoncbrxcZQfkW5NTBH473un@bootstrap-1.supervaults.superform.xyz:6690",
  "12D3KooWCDXcCoE86B4dfMg5hXpoPr6xj4wGRaYqxHbkgPZW3yer@bootstrap-2.supervaults.superform.xyz:6690",
]
# announce_addresses = ["203.0.113.42:6690"]
Set announce_addresses if your node listens on one address but other validators must dial a different public endpoint. Do not front the P2P port with Cloudflare or any HTTP proxy. ragep2p expects direct TCP reachability.

​
[database]

[database]
url = "postgresql://oracle:password@localhost:5432/oracle_db?sslmode=disable"
max_connections = 10
max_idle_conns = 5
conn_max_lifetime = 3600

​
[monitoring]

[monitoring]
metrics_port = 9090
health_port = 8080
log_level = "info"
log_format = "json"
health_check_interval = "1h"
max_pps_deviation_ppb = 10000000

​
[ocr2]

[ocr2]
config_version = 3
# config_sync_chain_id = 1
config_sync_chain_id defaults to Ethereum mainnet (1). This is the chain where SuperGovernor emits validator config updates, so every node must watch the same source chain. All nodes must use the same config_version. A mismatch produces a different config digest and prevents consensus.

​
chain_config_path

chain_config_path = "./chains.yaml"

​
chains.yaml

chains.yaml maps chain ID to the chain configuration your node should observe. 
1:
  name: ethereum
  chain_id: 1
  https_rpc: "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
  wss_rpc:   "wss://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
  block_time: 12s
  supported_strategies:
    - "0xVault1Address"
    - "0xVault2Address"
  ecdsa_oracle_address:   "0x..."
  super_governor_address: "0x..."

​
Field reference

FieldTypeDescription
namestringHuman-readable chain label used in logs and metrics.
chain_idintegerEVM chain ID; must match the top-level map key.
https_rpcstringHTTPS RPC endpoint for reads and tx submission.
wss_rpcstringWebSocket RPC endpoint for event subscriptions.
block_timedurationExpected block time in Go duration format.
supported_strategiesstring[]Vault addresses this node will observe.
ecdsa_oracle_addressstringECDSAPPSOracle contract address supplied during onboarding.
super_governor_addressstringSuperGovernor contract address supplied during onboarding.

​
RPC requirements

  • HTTPS is required on every configured chain.
  • WSS is required for event subscriptions.
  • Public rate-limited endpoints are not suitable for production.

​
Scope rules

Only include chains that Superform assigned to your validator deployment and for which you have reliable RPC access. A broken chain config creates observation errors for every strategy on that chain. Typical supported deployments include Ethereum, Base, Arbitrum, Optimism, and Polygon, but only configure the chains Superform assigned to your validator.

​
OCR2 timing presets

The versioned config/vN.json files define the OCR2 timing profile. Every validator in the network must use the same version.

​
v2 — high-frequency testing

ParameterValue
delta_round2s
delta_progress120s
delta_resend30s
delta_grace5s
delta_stage10s
r_max3
max_stale_duration5m

​
v3 — hourly production default

ParameterValue
delta_round30m
delta_progress10m
delta_resend5m
delta_grace1m
delta_stage2m
r_max5
max_stale_duration5m

​
Freshness controls

LayerConfig locationPurpose
Round cadencedelta_roundHow often the protocol attempts a report
Report freshnessmax_stale_durationRejects reports that finalize too late
Node health alertinghealth_check_intervalWarns when no onchain confirmation arrives
Contract enforcementmaxStalenessAuto-pauses a strategy if updates stop
For the production v3 profile, that contract-side maxStaleness window is designed around a 24-hour safety boundary even though rounds attempt far more frequently.

​
Switching versions

Update config_version on all nodes and restart them in a coordinated window. Mixed versions split the network until every validator converges on the same config digest.