silent-tweak-sdk 0.1.0

Zero-trust BIP352 Silent Payment client SDK — local scan key, verifiable tweaks, delta sync.
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

//! Wire types shared between server and client.
//!
//! These types define the REST API surface.  They are intentionally
//! minimal — no private key material ever appears here.

use serde::{Deserialize, Serialize};

/// A single tweak scalar delivered by the server.
///
/// Each entry corresponds to one eligible Taproot input set found in a
/// block.  The `tweak` field is the 32-byte big-endian encoding of the
/// ECDH scalar: `hash(input_hash || A)` as defined in BIP352 §scanning.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TweakEntry {
    /// Block height this tweak was observed in.
    pub block_height: u32,
    /// Block hash (hex, 64 chars).
    pub block_hash: String,
    /// Transaction ID (hex).
    pub txid: String,
    /// Tweak scalar — 32 bytes, big-endian, hex-encoded.
    pub tweak: String,
}

/// Response from `GET /tweaks/range`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TweaksRangeResponse {
    /// Inclusive start of the block range returned.
    pub from_height: u32,
    /// Inclusive end of the block range returned.
    pub to_height: u32,
    /// Tweak entries in ascending block order.
    pub tweaks: Vec<TweakEntry>,
    /// Merkle root committing to all tweaks in this range (hex, 32 bytes).
    pub merkle_root: String,
    /// Per-block Merkle proofs, keyed by block hash.
    pub proofs: Vec<MerkleProof>,
}

/// A single Merkle inclusion proof.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MerkleProof {
    /// Block hash this proof covers.
    pub block_hash: String,
    /// Index of this block's leaf in the range tree.
    pub leaf_index: u64,
    /// Sibling hashes from leaf to root (ascending).
    pub siblings: Vec<String>,
}

/// Response from `GET /filters/block`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BlockFilterResponse {
    /// Block height.
    pub block_height: u32,
    /// Block hash (hex).
    pub block_hash: String,
    /// BIP158 compact block filter, Golomb-Rice encoded, base64.
    pub filter: String,
}

/// Response from `GET /filters/range`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FiltersRangeResponse {
    /// Filters in ascending block order.
    pub filters: Vec<BlockFilterResponse>,
}

/// Server capability advertisement (`GET /info`).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ServerInfo {
    /// Protocol version string (semver).
    pub version: String,
    /// Lowest indexed block height.
    pub first_indexed_height: u32,
    /// Highest indexed block height.
    pub last_indexed_height: u32,
    /// Bitcoin network ("main", "test", "regtest", "signet").
    pub network: String,
    /// Whether the server supports real-time push via Server-Sent Events.
    pub supports_sse: bool,
    /// Whether threshold scanning is available.
    pub supports_threshold: bool,
}

/// Request body for threshold scan share submission.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ThresholdScanShare {
    /// Session identifier.
    pub session_id: String,
    /// Partial scan result contribution (opaque bytes, base64).
    pub share: String,
}

/// Error envelope returned by the server on HTTP 4xx / 5xx.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ApiError {
    /// Machine-readable error code.
    pub code: String,
    /// Human-readable message.
    pub message: String,
}