silent-payments

A complete BIP 352 Silent Payments library for Rust.

Quick Start

Add the dependency:

[dependencies]
silent-payments = "0.1.1"

For local development against this repository:

[dependencies]
silent-payments = { path = "." }

Complete send + receive roundtrip in under 20 lines:

use std::str::FromStr;
use silent_payments::prelude::*;
// (hidden: bitcoin imports, key construction, transaction building)

let secp = Secp256k1::new();
// Receiver: create keys + address
let scan_sk = ScanSecretKey::from_slice(&[0xea; 32])?;
let spend_sk = SpendSecretKey::from_slice(&[0x93; 32])?;
let (scan_pk, spend_pk) = (scan_sk.public_key(&secp), spend_sk.public_key(&secp));
let sp_addr = SpAddress::new(scan_pk.clone(), spend_pk.clone(), Network::Bitcoin);
// Sender: build inputs, create outputs
let sender = SilentPaymentSender::new(&[(txin, prev, input_sk)], EcdsaSighashType::All)?;
let outputs = sender.create_output_scripts(&sp_addr, &secp)?;
// Receiver: scan transaction, derive spend key
let scanner = BlockScanner::new(scan_sk, spend_pk, LabelManager::new());
let detected = scanner.scan_transaction(&tx, &[prev], &secp)?;
for d in &detected { let _key = d.derive_spend_key(&spend_sk, &secp)?; }

See examples/ for complete, runnable examples:

• send_to_sp_address.rs -- sending to an SP address
• scan_for_payments.rs -- scanning transactions for SP outputs
• full_roundtrip.rs -- end-to-end send + receive

Feature Flags

Architecture Overview

silent-payments (facade)
+-- silent-payments-core     (address, keys, inputs, crypto)
+-- silent-payments-send     (sender builder, output scripts)
+-- silent-payments-receive  (scanner, labels, detected outputs)
+-- silent-payments-psbt     (BIP 375 fields, roles, DLEQ proofs)
+-- silent-payments-scan     (ScanBackend trait, electrum, index-server)
+-- silent-payments-descriptor (BIP 392 sp() descriptors)

silent-payments-core -- BIP 352 primitives: address parsing/encoding, key newtypes with zeroization, input classification, and cryptographic wrappers. All EC operations use bitcoin::secp256k1 (SEC-04).

silent-payments-send -- Builder-style API for constructing SP outputs. Validates SIGHASH_ALL, classifies inputs, computes ECDH shared secrets, and generates P2TR output scripts. Supports batch sending and change outputs.

silent-payments-receive -- Block-level transaction scanner with label support. BlockScanner scans transactions for SP outputs and provides spend key derivation for detected payments.

silent-payments-psbt -- BIP 375 PSBT integration with BIP 374 DLEQ proofs. Typestate role machine (Constructor -> Updater -> Signer -> Extractor) enforces correct ordering at compile time.

silent-payments-scan -- Pluggable scanning backends behind the ScanBackend trait. Swap infrastructure (Electrum, index server) without changing application code.

silent-payments-descriptor -- BIP 392 sp() descriptor parsing and generation with BIP 393 annotations (birthday height, gap limit, max labels).

The facade crate re-exports everything via prelude::* -- depend on silent-payments and import the prelude for the full API.

CLI

The sp binary provides command-line access to Silent Payments functionality:

cargo install --path cli
cargo install silent-payments-cli

# Generate a new SP address (random keys)
sp gen-address

# Generate from specific keys
sp gen-address --scan-key <hex> --spend-key <hex>

# Send to an SP address
sp send --to <sp1...> --amount 100000 --utxo <txid:vout> --key <hex>

# Scan via index server (block range)
sp scan index-server --url http://localhost:8080 \
  --scan-key <hex> --spend-key <hex> \
  --from-height 800000 --to-height 800100

# Scan via Electrum (individual transactions)
sp scan electrum --url tcp://localhost:50001 \
  --scan-key <hex> --spend-key <hex> \
  --txid <hex>

# JSON output for any command
sp --json gen-address

Run sp --help for full flag reference.

Testing

cargo test --workspace --all-features

Tests include BIP 352 official test vector validation for both send and receive flows.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.