silent-payments 0.1.1

High-level BIP 352 Silent Payments library for Rust wallets
Documentation 
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
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

# silent-payments

A complete [BIP 352](https://github.com/bitcoin/bips/blob/master/bip-0352.mediawiki) Silent Payments library for Rust.

## Quick Start

Add the dependency:

```toml
[dependencies]
silent-payments = "0.1.1"
```

For local development against this repository:

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

Complete send + receive roundtrip in under 20 lines:

```rust,no_run
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

| Feature | Default | Description |
|---------|---------|-------------|
| `experimental-dleq` | off | BIP 374 DLEQ proof support for multi-signer PSBT workflows |
| `bip392` | off | BIP 392 sp() descriptor parsing and generation |
| `electrum` | off | Electrum/Esplora scanner backend |
| `index-server` | off | BIP0352 index server scanner backend |
| `cli` | off | CLI binary (`sp` command) |

## 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:

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

```sh
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](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.