Skip to content

Monitoring Configuration

Jump to bottom
dev-mondoshawan edited this page Apr 24, 2026 · 1 revision

Monitoring Configuration

This guide provides a deep dive into how ScarpShield monitors blockchain contracts and the configuration options available.

Supported Chains

ScarpShield supports the following EVM-compatible chains out of the box:

Chain Chain ID Default RPC Endpoint
Ethereum 1 https://eth.llamarpc.com
Polygon 137 https://polygon.llamarpc.com
BSC 56 https://binance.llamarpc.com
Arbitrum 42161 https://arb1.arbitrum.io/rpc
Base 8453 https://mainnet.base.org

Custom RPCs

You can override the default RPC endpoint for any chain:

  • Via config.json: Edit the rpc_endpoints object
  • Via Settings page: Enter a custom URL in the RPC configuration section
  • Via environment variable: Set SCARPSHIELD_RPC_<CHAIN> (e.g., SCARPSHIELD_RPC_ETHEREUM)

Custom RPCs are useful when:

  • The default public RPC is rate-limiting your requests
  • You have a dedicated node or paid provider (Infura, Alchemy, QuickNode)
  • You need a geographically closer endpoint for lower latency

Public RPC Rate Limits

Public RPC endpoints typically enforce rate limits:

Provider Approximate Limit Notes
LlamaRPC 10-20 req/s Shared public endpoint
Official chain RPCs Varies Often stricter

If you monitor many contracts across multiple chains, consider upgrading to a paid RPC provider with higher quotas.

Monitored Events

ScarpShield listens for the following event types on each monitored contract:

Transfer

Triggered on ERC-20 Transfer events:

event Transfer(address indexed from, address indexed to, uint256 value);

Alert includes:

  • From address
  • To address
  • Value (formatted with correct token decimals)
  • Transaction hash

Approval

Triggered on ERC-20 Approval events:

event Approval(address indexed owner, address indexed spender, uint256 value);

Alert includes:

  • Owner address
  • Spender address
  • Approved value

OwnershipTransferred

Triggered when contract ownership changes:

event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);

Alert includes:

  • Previous owner
  • New owner

Admin Function Calls

ScarpShield also monitors direct calls to common administrative functions:

Function Description
renounceOwnership() Owner gives up control permanently
transferOwnership(address) Owner transfers control to a new address
pause() Contract is paused
unpause() Contract is unpaused
setFeeRecipient(address) Fee recipient address is changed
upgradeTo(address) Proxy contract implementation is upgraded
upgradeToAndCall(address, bytes) Proxy upgrade with initialization call

These are detected by analyzing transaction calldata rather than event logs.

Event Filters

Global filters control which events generate alerts.

Min Transfer Value

Only Transfer events with a value equal to or greater than this threshold will trigger an alert.

Setting Behavior
0 All transfers are reported (default)
1000 Only transfers of 1000+ tokens
1000000 Only large transfers (e.g., whale movements)

The threshold uses the token's actual decimals. For example, a threshold of 1000 on USDC (6 decimals) means 1,000.00 USDC, not 0.000000001 USDC.

Watch Admin Events

A global toggle to enable or disable admin function call monitoring.

  • Enabled: All admin calls on monitored contracts generate alerts
  • Disabled: Admin calls are silently ignored

Useful when you only care about token movements and not contract administration.

Polling Configuration

Interval

The poll_interval_seconds setting controls how often ScarpShield checks each chain for new blocks.

Value Use Case
5s Rapid detection, high RPC usage (development/testing)
15s Balanced detection speed and RPC usage (default)
60s Lower RPC usage, acceptable for low-frequency contracts
120s Minimal RPC usage, suitable for stable long-term monitoring

Trade-offs

  • Lower interval: Faster alert delivery, but more RPC calls and higher chance of rate limiting
  • Higher interval: Fewer RPC calls, but events may go undetected for up to the interval duration

For most production setups, 15-30 seconds is recommended.

Block Range Cap

ScarpShield processes a maximum of 100 blocks per polling cycle per chain. This cap prevents RPC flooding in scenarios such as:

  • The monitor was stopped for an extended period and is now catching up
  • The RPC endpoint experienced downtime and many blocks were missed
  • A chain produces blocks faster than expected

If more than 100 blocks have passed since the last check, ScarpShield processes the latest 100 and logs a warning. The remaining blocks will be processed in subsequent cycles.

State Persistence

ScarpShield stores its monitoring state in a local file:

.scarpshield_state.json

This file tracks:

  • Last processed block number per chain
  • Timestamp of last successful poll

Benefits

  • Survives restarts: After stopping and restarting ScarpShield, it resumes from the last processed block rather than re-scanning from scratch
  • Prevents duplicate alerts: Events are not re-processed across restarts
  • Crash recovery: If the process crashes, the state file ensures minimal data loss

Important Notes

  • Do not delete .scarpshield_state.json unless you want to force a full re-scan
  • The file is auto-created on first run
  • It is safe to copy the state file between machines when migrating your setup

Error Handling

Per-Chain Exponential Backoff

If an RPC call fails (timeout, rate limit, server error), ScarpShield applies exponential backoff to that specific chain:

Attempt Delay
1st failure 5 seconds
2nd failure 10 seconds
3rd failure 20 seconds
4th failure 40 seconds
5th+ failure 5 minutes (max)

Backoff is tracked independently per chain. A failure on Ethereum does not affect polling on Polygon.

Auto-Recovery

When the RPC endpoint comes back online:

  1. The next successful poll resets the backoff counter
  2. Normal polling resumes immediately
  3. A log entry indicates the chain is healthy again

Token Decimals

ScarpShield automatically detects token decimals for each monitored contract by querying the decimals() function on the ERC-20 contract.

Token Decimals Example Display
USDC 6 1,250.00 USDC
USDT 6 500.50 USDT
WBTC 8 2.34567890 WBTC
WETH 18 10.5 WETH

Why This Matters

Without correct decimals, transfer values would be displayed as raw integers:

  • 1,250,000,000 USDC (wrong — looks like 1.25 billion)
  • 1,250.00 USDC (correct)

No Manual Configuration Needed

Token decimals are queried once when a contract is added and cached in memory. If the decimals query fails (e.g., RPC is down), ScarpShield falls back to 18 decimals and logs a warning.

Troubleshooting Decimals

If token values look wrong:

  1. Verify RPC connectivity — the decimals query requires a working RPC
  2. Check that the contract is a standard ERC-20 (non-standard contracts may not implement decimals())
  3. Remove and re-add the contract to force a re-query

Clone this wiki locally