# SilentTweak Protocol
> **Official 100% Rust implementation of the SilentTweak Protocol** — a zero-trust tweak server + client SDK for [BIP352 Silent Payments](https://github.com/bitcoin/bips/blob/master/bip-0352.mediawiki).
[](https://github.com/btrust-builders/silenttweak/actions)
[](LICENSE-MIT)
[](https://crates.io/crates/silent-tweak-sdk)
[](https://docs.rs/silent-tweak-sdk)
[](https://www.rust-lang.org)
---
## 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:
| `silent-tweak-server` | Indexes Taproot blockchain, provides compact *tweaks* via REST API. Never learns your keys. |
| `silent-tweak-sdk` | Client library. Keeps `b_scan` local, fetches tweaks, derives outputs, verifies Merkle proofs. |
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
| **Blinded Scan Commitments (BSC)** | Verifiable scan proofs → avoid redundant scans |
| **Scan-Memo** | Compact bit-vector for resumable/incremental scanning |
| **Probabilistic GCS filters + delta tweaks** | ~10 MB/month bandwidth |
| **Merkle commitments** | Client verifies server honesty without a full node |
| **Real-time SSE push** | Optional live update stream |
| **Africa-first optimisations** | Progressive sync, offline-first, low-data |
| **Threshold scanning** | (Planned) Split scan key across N servers |
---
## Quick Start
### Server
```bash
# 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)
```rust
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)
```bash
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)
```bash
# 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
| `GET /info` | Server capabilities and index range |
| `GET /tweaks/range?from=H&to=H` | Tweaks for block range + Merkle proof |
| `GET /filters/range?from=H&to=H` | Compact block filters (BIP158-style) |
| `GET /filters/block?height=H` | Single block filter |
| `GET /tweaks/stream` | Server-Sent Events for live updates |
---
## 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
| [SPEC.md](SPEC.md) | Formal protocol specification |
| [SECURITY.md](SECURITY.md) | Threat model and vulnerability reporting |
| [docs/tutorial.md](docs/tutorial.md) | Step-by-step guide: keys → wallet → server → scan |
| [docs/wallet-integration.md](docs/wallet-integration.md) | Integrating the SDK into an existing wallet |
| [CHANGELOG.md](CHANGELOG.md) | Release history |
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## License
Licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE) at your option.
---
*SilentTweak is stewarded by [Btrust Builders](https://btrust.tech) as a privacy primitive for the Bitcoin ecosystem.*