suitop - Sui Uptime Monitor

Monitors validator uptime on the Sui network by subscribing to checkpoint data. Features a modern terminal user interface (TUI) with real-time updates.

Features

• Real-time monitoring of validator signatures on checkpoints
• Dual progress bars: validator count and voting-power participation per checkpoint
• Interactive TUI with progress bars and formatted tables
• Plain text mode for logging or scripting use cases
• Automatic terminal resizing support
• Graceful shutdown handling for clean exits

Configuration

The application can be configured using environment variables:

• SUI_NODE: The gRPC endpoint for Sui node subscriptions (e.g., fullnode.mainnet.sui.io:443).
• SUI_JSON_RPC_URL: The JSON-RPC endpoint for Sui fullnode (e.g., https://fullnode.mainnet.sui.io).
• DEFAULT_RPC_TIMEOUT_SECONDS: Timeout for JSON-RPC calls in seconds (default: 15).
• GRPC_USE_TLS: Set to true or false to enable/disable TLS for gRPC (default: true).
• GRPC_INSECURE_SKIP_VERIFY: Set to true or false to skip TLS certificate verification for gRPC (default: true).
• SUBSCRIBER_RETRY_DELAY_MS: Delay in milliseconds before retrying gRPC subscription (default: 1000).
• PLAIN_MODE: Set to true to use plain text output instead of TUI (default: false).
• NO_ALT_SCREEN: Set to true to run inside current terminal buffer (default: false).
• LOG_TO_FILE: Set to true to write logs to a file (default: false).
• LOG_FILE_PATH: Path to log file (default: ~/.suitop/logs/suitop.log).
• GENERATE_DATASET: Enable dataset generation mode (default: false).
• DATASET_FOLDER: Folder to store dataset files (default: ./data).

Command-line Flags

These flags override the corresponding environment variables:

• --plain: Use plain text output instead of TUI
• --no-alt-screen: Run inside current terminal buffer (useful for tmux logs)
• --log-to-file: Write logs to a file
• --log-file [path]: Path to log file
• --generate-dataset: Enable dataset generation mode

Building

go build -o suitop cmd/suitop/main.go

To embed version information:

go build -ldflags "-X suitop/internal/version.GitCommit=$(git rev-parse HEAD) -X suitop/internal/version.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ) -X suitop/internal/version.Version=0.1.0" -o suitop cmd/suitop/main.go

Running

# Run with default TUI mode
./suitop
# Run for testnet
./suitop --network testnet
# Run with plain text output
./suitop --plain
# Run inside current terminal buffer (good for tmux sessions)
./suitop --no-alt-screen
# Run with logging to a file
./suitop --log-to-file --log-file /path/to/logfile.log
# Generate dataset in plain mode
./suitop --generate-dataset

Dataset Mode

When --generate-dataset (or GENERATE_DATASET=true) is enabled the tool runs in plain mode and keeps validator signatures in memory until you press q then Enter.

Every epoch is flushed to a JSON file inside DATASET_FOLDER (defaults to ./data). Files are named epoch_<epoch>_<start>-<end>.json where <start> and <end> are the first and last checkpoint sequence numbers recorded.

The JSON structure contains an array of validators with a bitmap of all checkpoints in order:

{
"epoch": 42,
"start_checkpoint": 10000,
"end_checkpoint": 10100,
"validators": [
{
"name": "Validator A",
"address": "0x...",
"signed": 90,
"total": 101,
"bitmap": "...base64 bytes..."
}
]
}

The bitmap field is base64‑encoded. When decoded, each bit corresponds to a checkpoint starting from the least significant bit of the first byte. A set bit (value 1) means the validator signed that checkpoint.

Progress is printed every 10 checkpoints with a reminder that you can press q to finish recording.

Usage

• Press q or Ctrl+C to quit the application
• Terminal resizing is automatically handled
• Use SIGINT (Ctrl+C) or SIGTERM for graceful shutdown

Project Structure

(Details of the project structure as provided in the refactoring request can be added here.)

suitop/
├── go.mod
├── go.sum
│
├── cmd/ │ └── suitop/
│ └── main.go │
├── internal/ │ ├── config/ │ │ └── config.go
│ ├── rpc/ │ │ ├── client.go │ │ ├── committee.go │ │ └── systemstate.go │ ├── grpc/ │ │ ├── subscriber.go │ │ └── interceptors.go │ ├── checkpoint/ │ │ ├── bitmap.go │ │ ├── processor.go │ │ └── stats.go │ ├── validator/ │ │ ├── model.go │ │ └── loader.go │ ├── tui/ │ │ ├── messages.go │ │ ├── model.go │ │ ├── update.go │ │ ├── view.go │ │ └── style.go │ ├── types/ │ │ └── common.go │ ├── util/ │ │ ├── logger.go │ │ ├── retry.go │ │ └── signalctx.go │ └── version/ │ └── version.go
│
├── pb/ │ ├── sui/rpc/v2alpha/*.go
│ └── sui/rpc/v2beta/*.go
│
└── README.md