Configuration Reference

Configuration Reference

This document provides a complete reference for every configuration option in ScarpShield.

---

Config.json Schema

The main configuration file is config.json located in the project root.

Top-Level Keys

Key	Type	Default	Description
version	string	"1.0"	Config schema version
poll_interval_seconds	integer	15	Seconds between polling cycles (5-120)
rpc_endpoints	object	{}	Per-chain RPC overrides
contracts	array	[]	List of monitored contracts
alerts	object	{}	Alert channel configurations
filters	object	{}	Global event filters

rpc_endpoints

{
  "rpc_endpoints": {
    "ethereum": "https://eth.llamarpc.com",
    "polygon": "https://polygon.llamarpc.com",
    "bsc": "https://binance.llamarpc.com",
    "arbitrum": "https://arb1.arbitrum.io/rpc",
    "base": "https://mainnet.base.org"
  }
}

Key	Type	Default	Description
ethereum	string	null	Custom Ethereum RPC URL
polygon	string	null	Custom Polygon RPC URL
bsc	string	null	Custom BSC RPC URL
arbitrum	string	null	Custom Arbitrum RPC URL
base	string	null	Custom Base RPC URL

If a key is null or missing, the built-in default is used.

contracts

{
  "contracts": [
    {
      "id": "usdc-treasury-eth",
      "address": "0xA0b86a33E6441e0A421e56C5bC6a3B0A4B2B3E5f",
      "label": "USDC Treasury",
      "chain": "ethereum",
      "events": ["Transfer", "Approval", "OwnershipTransferred"]
    }
  ]
}

Key	Type	Required	Description
id	string	Auto	Unique identifier (auto-generated if omitted)
address	string	Yes	Contract address (42-char hex)
label	string	Yes	Human-readable name
chain	string	Yes	Chain key: ethereum, polygon, bsc, arbitrum, base
events	array	Yes	Event types to monitor for this contract

alerts

{
  "alerts": {
    "email": {
      "enabled": false,
      "host": "smtp.gmail.com",
      "port": 587,
      "user": "",
      "password": "",
      "from_addr": "",
      "to_addr": ""
    },
    "discord": {
      "enabled": false,
      "webhook_url": ""
    },
    "slack": {
      "enabled": false,
      "webhook_url": ""
    },
    "telegram": {
      "enabled": false,
      "bot_token": "",
      "chat_id": ""
    }
  }
}

Email Sub-Schema

Key	Type	Default	Description
enabled	boolean	false	Whether email alerts are active
host	string	""	SMTP server hostname
port	integer	587	SMTP server port
user	string	""	SMTP authentication username
password	string	""	SMTP authentication password
from_addr	string	""	Sender email address
to_addr	string	""	Recipient email address

Discord Sub-Schema

Key	Type	Default	Description
enabled	boolean	false	Whether Discord alerts are active
webhook_url	string	""	Discord webhook URL

Slack Sub-Schema

Key	Type	Default	Description
enabled	boolean	false	Whether Slack alerts are active
webhook_url	string	""	Slack incoming webhook URL

Telegram Sub-Schema

Key	Type	Default	Description
enabled	boolean	false	Whether Telegram alerts are active
bot_token	string	""	Telegram bot token from @BotFather
chat_id	string	""	Telegram chat or channel ID

filters

{
  "filters": {
    "min_transfer_value": 0,
    "watch_admin_events": true
  }
}

Key	Type	Default	Description
min_transfer_value	number	0	Minimum token value to trigger a Transfer alert
watch_admin_events	boolean	true	Whether to monitor admin function calls

---

Config.json vs .env

Both config.json and .env can store configuration, but they serve different purposes:

Aspect	config.json	.env
Best for	Non-sensitive settings (chains, contracts, filters)	Secrets and credentials (passwords, tokens, API keys)
Format	JSON	KEY=VALUE pairs
Git tracking	Usually tracked	Ignored (in .gitignore)
Runtime override	Base configuration	Overrides config.json values
Editing	GUI, CLI, or text editor	Text editor only

Best practice: Keep secrets in .env and everything else in config.json.

---

Environment Variables

All SCARPSHIELD_* environment variables override their config.json equivalents at runtime.

Variable	Overrides	Description
SCARPSHIELD_POLL_INTERVAL	poll_interval_seconds	Polling interval in seconds
SCARPSHIELD_RPC_ETHEREUM	rpc_endpoints.ethereum	Ethereum RPC URL
SCARPSHIELD_RPC_POLYGON	rpc_endpoints.polygon	Polygon RPC URL
SCARPSHIELD_RPC_BSC	rpc_endpoints.bsc	BSC RPC URL
SCARPSHIELD_RPC_ARBITRUM	rpc_endpoints.arbitrum	Arbitrum RPC URL
SCARPSHIELD_RPC_BASE	rpc_endpoints.base	Base RPC URL
SCARPSHIELD_SMTP_HOST	alerts.email.host	SMTP server hostname
SCARPSHIELD_SMTP_PORT	alerts.email.port	SMTP server port
SCARPSHIELD_SMTP_USER	alerts.email.user	SMTP username
SCARPSHIELD_SMTP_PASSWORD	alerts.email.password	SMTP password
SCARPSHIELD_SMTP_FROM	alerts.email.from_addr	Email from address
SCARPSHIELD_SMTP_TO	alerts.email.to_addr	Email to address
SCARPSHIELD_DISCORD_WEBHOOK_URL	alerts.discord.webhook_url	Discord webhook URL
SCARPSHIELD_SLACK_WEBHOOK_URL	alerts.slack.webhook_url	Slack webhook URL
SCARPSHIELD_TELEGRAM_BOT_TOKEN	alerts.telegram.bot_token	Telegram bot token
SCARPSHIELD_TELEGRAM_CHAT_ID	alerts.telegram.chat_id	Telegram chat ID

Example .env File

# Polling
SCARPSHIELD_POLL_INTERVAL=30

# Custom RPC
SCARPSHIELD_RPC_ETHEREUM=https://mainnet.infura.io/v3/YOUR_PROJECT_ID

# Email
SCARPSHIELD_SMTP_USER=alerts@example.com
SCARPSHIELD_SMTP_PASSWORD=your_app_password
SCARPSHIELD_SMTP_FROM=alerts@example.com
SCARPSHIELD_SMTP_TO=team@example.com

# Discord
SCARPSHIELD_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/123/abc

# Slack
SCARPSHIELD_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00/B00/XXX

# Telegram
SCARPSHIELD_TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
SCARPSHIELD_TELEGRAM_CHAT_ID=-1001234567890

---

Config Loading Order

ScarpShield loads configuration in the following order, with later sources overriding earlier ones:

1. Built-in defaults — Hard-coded fallback values
2. config.json — User-defined JSON configuration
3. .env file — Environment variables loaded via python-dotenv
4. System environment variables — Directly set OS env vars

This means a value set in your shell environment takes precedence over the same value in .env, which takes precedence over config.json.

---

config.example.json

The repository includes config.example.json as a starting template. It contains:

• Sensible defaults for all settings
• Placeholder values for sensitive fields (empty strings)
• Sample contract entries (commented or using example addresses)

To create your own config:

cp config.example.json config.json

Then edit config.json with your real values.

---

Backup and Restore

Backup

Your configuration consists of two files:

# Backup both files
cp config.json config.json.backup
cp .env .env.backup

For a complete backup including state:

cp config.json config.json.backup
cp .env .env.backup
cp .scarpshield_state.json .scarpshield_state.json.backup

Restore

cp config.json.backup config.json
cp .env.backup .env

After restoring, restart ScarpShield for changes to take effect.

Version Control

If you track config.json in Git, avoid committing sensitive values:

{
  "alerts": {
    "email": {
      "password": "${SCARPSHIELD_SMTP_PASSWORD}"
    }
  }
}

Or better yet, keep all secrets in .env and only commit config.example.json as a template.