snap-coin-light-node 16.0.0

A simple CLI for hosting a Snap Coin Light Node and managing tracked addresses
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# Snap Coin Light Node

## Installation
```bash
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

```bash
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:

```bash
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:

```bash
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

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

### List tracked wallets

```bash
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](LICENSE)