SilentTweak Protocol

Official 100% Rust implementation of the SilentTweak Protocol — a zero-trust tweak server + client SDK for BIP352 Silent Payments.

What is SilentTweak?

BIP352 Silent Payments let senders pay a static address without on-chain linkability. Scanning for received payments requires checking every Taproot transaction — expensive for light clients.

SilentTweak decouples the heavy indexing work from the privacy-sensitive key material:

The scan key (b_scan) never leaves the client. The server is treated as an untrusted third party — every response is verified against a Merkle commitment.

Architecture

┌─────────────────────────────────────────────────────┐
│                  Bitcoin Full Node                   │
│                  (Bitcoin Core)                      │
└──────────────────────┬──────────────────────────────┘
                       │ JSON-RPC
┌──────────────────────▼──────────────────────────────┐
│            silent-tweak-server                       │
│  ┌──────────────┐  ┌─────────────┐  ┌────────────┐  │
│  │ TaprootIndex │  │ DB (SQLite) │  │ REST API   │  │
│  │ (tweaks +    │→ │ tweaks +    │→ │ /tweaks/   │  │
│  │  GCS filter) │  │ filters     │  │ /filters/  │  │
│  └──────────────┘  └─────────────┘  └──────┬─────┘  │
└─────────────────────────────────────────────┼────────┘
                                              │ HTTPS
┌─────────────────────────────────────────────▼────────┐
│            silent-tweak-sdk (client)                 │
│  1. Fetch compact filters → identify candidates      │
│  2. Fetch tweaks for candidates only                 │
│  3. Verify Merkle commitments                        │
│  4. Locally: P = B_spend + hash(tweak·B_scan)·G     │
│  5. Update ScanMemo (bit-vector resume)              │
└──────────────────────────────────────────────────────┘

Key Innovations

Quick Start

Server

# 1. Set up Bitcoin Core (regtest for testing)
bitcoind -regtest -rpcuser=bitcoin -rpcpassword=secret -daemon

# 2. Run the server
cargo run -p silent-tweak-server -- \
  --rpc-url http://127.0.0.1:18443 \
  --rpc-user bitcoin \
  --rpc-pass secret \
  --network regtest \
  --bind 0.0.0.0:8080

Client (SDK)

use silent_tweak_sdk::{ScanKeys, SilentTweakClient, SilentTweakClientConfig};

let keys = ScanKeys::from_secret_bytes(&b_scan_bytes, &b_spend_bytes)?;
let cfg  = SilentTweakClientConfig::new("http://localhost:8080");
let client = SilentTweakClient::new(keys, cfg)?;

let payments = client.scan_range(840_000, 840_100).await?;

Docker (single container)

docker build -t silenttweak-server .
docker run -p 8080:8080 \
  -e RPC_URL=http://host.docker.internal:18443 \
  -e RPC_USER=bitcoin \
  -e RPC_PASS=secret \
  -e NETWORK=regtest \
  silenttweak-server

Docker Compose (full regtest stack)

# Start Bitcoin Core (regtest) + SilentTweak server
docker compose up -d

# Mine 200 blocks so the indexer has something to work with
docker compose run --rm miner

# Query the server
curl http://localhost:8080/info

REST API

Project Structure

silenttweak/
├── silent-tweak-sdk/       # Client library crate (publishable)
│   ├── src/
│   │   ├── crypto/         # BIP352 primitives (constant-time)
│   │   ├── filters/        # GCS compact block filters
│   │   ├── memo/           # Scan-Memo bit-vector
│   │   ├── client/         # High-level SilentTweakClient
│   │   └── proto/          # Wire types (shared with server)
│   └── examples/
├── silent-tweak-server/    # Reference server binary + lib
│   ├── src/
│   │   ├── indexer/        # Taproot blockchain indexer
│   │   ├── db/             # SQLite storage
│   │   ├── api/            # Axum REST handlers
│   │   ├── commitment/     # Merkle tree builder
│   │   └── gossip/         # P2P gossip layer stub
│   ├── tests/              # End-to-end integration tests
│   └── migrations/
├── silent-tweak-wallet/    # stwallet CLI
├── fuzz/                   # cargo-fuzz harnesses (nightly)
├── docs/                   # Protocol documentation + tutorial
├── SPEC.md                 # Formal protocol specification
├── SECURITY.md             # Threat model + vulnerability reporting
├── CHANGELOG.md            # Release history
├── Dockerfile              # Multi-stage Docker image
├── docker-compose.yml      # Regtest dev stack
└── .github/workflows/ci.yml

Security Model

1. Privacy — b_scan never leaves the client process.
2. Integrity — server-provided tweaks are verified via Merkle/hash commitments.
3. Resilience — multiple independent servers; gossip network (planned).
4. Trustless verification — client can spot-check tweaks against a full node.
5. Forward secrecy — no persistent session state; reorg-safe by design.

Documentation

Contributing

See CONTRIBUTING.md.

License

Licensed under MIT or Apache-2.0 at your option.

SilentTweak is stewarded by Btrust Builders as a privacy primitive for the Bitcoin ecosystem.