snap-coin-light-node 16.0.0

A simple CLI for hosting a Snap Coin Light Node and managing tracked addresses
snap-coin-light-node-16.0.0 is not a library.

Snap Coin Light Node

Installation

cargo install snap-coin-light-node

A CLI for running a Snap Coin light node and managing tracked wallet addresses. Instead of downloading the full blockchain, the light node syncs only block metadata and filters for UTXOs belonging to your watched addresses - letting you verify balances and receive notifications of new blocks without the storage and bandwidth overhead of a full node.

Features

  • Lightweight sync - downloads block metadata in parallel 1024-block chunks, requiring consensus from a majority of peers before accepting each chunk
  • UTXO tracking - watches one or more wallet addresses (base36-encoded public keys) and indexes only the UTXOs relevant to them
  • Wallet restore - re-syncs from a specified block height to recover UTXOs for an existing wallet
  • Auto peer discovery - automatically connects to additional full nodes via peer referral
  • Snap Coin API server - exposes a local REST API for querying node state
  • Persistent storage - node state and UTXO index are persisted to disk via an embedded sled database

Usage

Start the node

snap-coin-light-node

Connects to the default bootstrap peers (node.snap-coin.net:8998 and node.snap-coin.net:7887), starts auto peer discovery, and begins syncing. The API server listens on port 3003 by default.

Options

Flag Short Default Description
--peers <addr,...> -P - Comma-separated list of peer addresses to connect to on startup
--api <port> -A 3003 Port for the local Snap Coin API server
--no-auto-peer false Disable automatic peer discovery
--no-default-peer false Do not connect to the default bootstrap peers
--node-path <path> -d ./light-node-mainnet Path to the node data directory

Track a new (empty) wallet

Use this when the wallet has no transaction history yet:

snap-coin-light-node new-wallet <base36-address>

Track an existing wallet

Use this to add a wallet that already has transaction history. The node will re-sync from the specified block height to discover its UTXOs:

snap-coin-light-node track <base36-address> --restore-height <block-height>

If --restore-height is omitted it defaults to 0 (full history scan).

Stop tracking a wallet

snap-coin-light-node untrack <base36-address>

List tracked wallets

snap-coin-light-node tracked

Running the binary with no subcommand also prints tracked wallets before starting the node.

The data directory is created automatically on first run. You can run multiple independent nodes by pointing --node-path at different directories.

Sync behaviour

On startup the node:

  1. Resolves and connects to all specified peers
  2. Starts the auto peer discovery loop (unless --no-auto-peer)
  3. Waits ~5 seconds for the peer list to stabilise
  4. Requests block metadata from all peers in parallel, chunked at 1024 metadatas per request
  5. Accepts a chunk only when a consensus threshold of peers agree on its contents
  6. After the initial sync completes, continues to accept new blocks as they are announced

Progress is logged to the active log file:

[SYNC] Starting sync local height: 99980 remote height: 127209
[SYNC] Chunk 1/27 synced 99980-101004 | 1024 metadatas | consensus 50% (2/4)
...
[SYNC] Done

License

Licensed MIT