Skip to content

Web Dashboard Guide

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

Web Dashboard Guide

The ScarpShield web dashboard provides a real-time, browser-based interface for monitoring contracts, configuring alerts, and reviewing events without using the terminal.

Launching the Dashboard

Start the GUI from your project directory:

python main.py gui

By default, the server runs on http://127.0.0.1:8050 and will attempt to open your default browser automatically.

Command-Line Options

Option Description Example
--port Bind to a custom port python main.py gui --port 8080
--host Bind to a custom host python main.py gui --host 0.0.0.0
--no-browser Start server without opening browser python main.py gui --no-browser

Common combinations:

# Run on a different port
python main.py gui --port 8080

# Expose on your local network (allows other devices to connect)
python main.py gui --host 0.0.0.0 --port 8050

# Headless server mode
python main.py gui --host 0.0.0.0 --port 8050 --no-browser

Dashboard Page (Landing)

The Dashboard is the first page you see when opening the GUI. It provides a high-level overview of your monitoring system.

Stat Cards

Four summary cards display at the top:

  • Contracts Monitored — Total number of contracts being watched across all chains
  • Active Alerts — Number of alert channels currently enabled
  • Events Today — Total events detected in the last 24 hours
  • Monitoring Status — Whether the engine is currently running or stopped

Start / Stop Monitoring

A prominent toggle button lets you start or stop the monitoring engine directly from the browser. When started, the engine begins polling configured chains in the background.

Live Event Feed

Events appear in real time via Server-Sent Events (SSE) as they are detected by the monitoring engine. The feed shows:

  • Event type (Transfer, Approval, OwnershipTransferred, Admin Call)
  • Contract address and label
  • Chain name
  • Human-readable value (with correct token decimals)
  • Timestamp

The feed auto-scrolls and highlights new events for 3 seconds.

Contract Overview Cards

A grid of cards shows each monitored contract with:

  • Label and chain badge
  • Truncated address with copy button
  • Active event filters for that contract
  • Quick link to remove or edit

Quick Actions

Shortcut buttons to common tasks:

  • Add a new contract
  • Configure alert channels
  • View full event logs
  • Open the Settings page

Contracts Page

Manage all monitored contracts from this page.

Adding a Contract

Click Add Contract to open the form:

Field Description Example
Address The contract address (42-char hex) 0xA0b86a33E6441e0A421e56C5bC6a3B0A4B2B3E5f
Label A friendly name for this contract "USDC Treasury"
Chain Select from supported chains Ethereum, Polygon, BSC, Arbitrum, Base
Events Checkboxes for events to monitor Transfer, Approval, OwnershipTransferred

After filling the form, click Save to add the contract. ScarpShield will immediately begin monitoring it on the next polling cycle.

Contract Table

All monitored contracts are listed in a sortable table with columns:

  • Label
  • Address (click-to-copy icon)
  • Chain
  • Watched Events
  • Actions (edit / remove)

Copy Address

Hover over any contract address to reveal a copy icon. Clicking copies the full address to your clipboard with a brief confirmation tooltip.

Remove Contract

Click the trash icon next to a contract. A confirmation dialog appears to prevent accidental deletion. Removing a contract stops all monitoring for that address.

Alerts Page

Configure and test your multi-channel alert system.

Channel Cards with Toggles

Five channel cards are displayed:

  1. Console — Always enabled (prints to terminal)
  2. Email (SMTP) — Toggle on/off
  3. Discord — Toggle on/off
  4. Slack — Toggle on/off
  5. Telegram — Toggle on/off

Each card shows its current status (enabled/disabled) and a brief summary of its configuration.

Configuring a Channel

  1. Click Configure on the channel card you want to set up
  2. The card expands into a setup form
  3. Fill in the required fields (see the Alert Configuration Guide for per-channel details)
  4. Click Save

Changes take effect immediately — no restart required.

Testing Channels

  • Test Individual — Click the Test button on any channel card to send a sample alert to that channel only
  • Test All — Click Test All Channels at the top of the page to verify every enabled channel at once

A green checkmark or red error indicator appears next to each channel after the test completes.

Event Filter Settings

Located at the bottom of the Alerts page:

Setting Description Default
Min Transfer Value Only alert on transfers equal to or above this value 0 (all transfers)
Watch Admin Events Enable/disable monitoring of admin function calls Enabled

These filters apply globally across all contracts and chains.

Settings Page

Fine-tune system behavior and review configuration.

RPC Endpoint Configuration

Per-chain RPC settings:

Chain Default RPC Custom RPC Override
Ethereum https://eth.llamarpc.com Optional
Polygon https://polygon.llamarpc.com Optional
BSC https://binance.llamarpc.com Optional
Arbitrum https://arb1.arbitrum.io/rpc Optional
Base https://mainnet.base.org Optional

Enter a custom URL to override the default for any chain. The dashboard validates the URL format before saving.

Polling Interval Slider

Adjust how frequently ScarpShield polls for new events:

  • Range: 5 to 120 seconds
  • Default: 15 seconds
  • UI: Drag the slider to your preferred interval

A tooltip explains the trade-off: lower intervals detect events faster but consume more RPC quota.

JSON Config Viewer / Editor

A collapsible panel displays the current config.json content in a syntax-highlighted JSON editor. You can:

  • View the raw configuration
  • Edit directly in the browser (advanced users)
  • Validate before saving — invalid JSON is rejected with an error message

Warning: Direct JSON editing bypasses form validation. Use with caution.

Reset to Defaults

Click Reset to Defaults to restore the factory configuration. A confirmation dialog prevents accidental data loss. This action:

  • Clears custom RPC endpoints
  • Resets polling interval to 15s
  • Keeps monitored contracts intact (only system settings are reset)

About Section

Displays:

  • ScarpShield version
  • Python version
  • Flask / frontend dependency versions
  • Links to GitHub, documentation, and issue tracker

Logs Page

Browse, filter, and export historical events.

Filter Bar

Filter Description
Event Type Transfer, Approval, OwnershipTransferred, Admin Call
Chain Ethereum, Polygon, BSC, Arbitrum, Base
Search Free-text search across addresses, labels, and values
Date Range Start and end date/time pickers

Click Apply Filters to update the table. Click Clear to reset.

Paginated Event Table

Events are listed in reverse chronological order with columns:

  • Timestamp
  • Event Type (color-coded badge)
  • Contract (label + address)
  • Chain
  • Details (value, from/to, etc.)

Navigation controls at the bottom let you move between pages and adjust rows-per-page (10, 25, 50, 100).

Expandable Rows

Click any row to expand it and see the full raw event data, including:

  • Transaction hash
  • Block number
  • Full parameter list
  • Raw log topics and data

Export

Two export formats are supported:

  • JSON — Full structured export with all metadata
  • CSV — Flat table format for spreadsheet analysis

Click Export and choose your format. The file downloads automatically and contains all events matching the current filters.

Auto-Refresh Toggle

Enable auto-refresh to keep the table updated as new events arrive. When on, the table refreshes every 10 seconds. Turn off for static analysis of a fixed time window.

API Reference

The dashboard exposes a REST API on the same port. All endpoints are prefixed with /api.

Method Path Description Request Body Response
GET /api/status Monitoring engine status — { "running": bool, "chains": [...] }
POST /api/start Start monitoring engine — { "success": bool }
POST /api/stop Stop monitoring engine — { "success": bool }
GET /api/contracts List monitored contracts — Array of contract objects
POST /api/contracts Add a new contract { "address", "label", "chain", "events": [...] } { "id": string }
DELETE /api/contracts/<id> Remove a contract — { "success": bool }
GET /api/alerts List alert channels and status — Array of channel objects
POST /api/alerts/<channel>/toggle Enable/disable a channel { "enabled": bool } { "success": bool }
POST /api/alerts/test Test all enabled channels — { "results": {...} }
POST /api/alerts/test/<channel> Test a single channel — { "success": bool, "message": string }
GET /api/settings Get current settings — Settings object
POST /api/settings Update settings { "poll_interval", "rpc_endpoints", ... } { "success": bool }
POST /api/settings/reset Reset to defaults — { "success": bool }
GET /api/logs Query event logs Query params: type, chain, search, from, to, page, limit Paginated log response
GET /api/logs/export Export logs Query params: format (json or csv), filters File download
GET /api/events/stream SSE stream of live events — text/event-stream

Example: Query Logs via API

curl "http://127.0.0.1:8050/api/logs?chain=ethereum&type=Transfer&limit=50"

Example: Add a Contract via API

curl -X POST http://127.0.0.1:8050/api/contracts \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xA0b86a33E6441e0A421e56C5bC6a3B0A4B2B3E5f",
    "label": "Treasury",
    "chain": "ethereum",
    "events": ["Transfer", "Approval"]
  }'

Tips

  • Use --no-browser when running ScarpShield on a remote server and accessing the dashboard via SSH tunnel or VPN
  • The SSE event stream keeps a single persistent connection — ensure your reverse proxy (nginx, Apache) supports SSE if using one
  • All API calls return JSON except /api/events/stream (SSE) and /api/logs/export (file download)
  • Configuration changes via the GUI are saved to config.json immediately

Clone this wiki locally