bsv/wallet/
types.rs

1//! Semantic type aliases and core types for the wallet module.
2//!
3//! Mirrors the Go SDK wallet/wallet.go and wallet/interfaces.go type
4//! definitions, providing strongly-typed aliases for protocol parameters.
5
6use crate::primitives::private_key::PrivateKey;
7use crate::primitives::public_key::PublicKey;
8
9// ---------------------------------------------------------------------------
10// Semantic type aliases
11// ---------------------------------------------------------------------------
12
13/// Hex-encoded public key string.
14pub type PubKeyHex = String;
15
16/// Satoshi value (unsigned 64-bit integer).
17pub type SatoshiValue = u64;
18
19/// Outpoint string in "txid.index" format.
20pub type OutpointString = String;
21
22/// Transaction ID as a hex string.
23pub type TXIDHexString = String;
24
25/// Description string (5 to 50 bytes).
26pub type DescriptionString5to50Bytes = String;
27
28/// Basket name string (under 300 bytes).
29pub type BasketStringUnder300Bytes = String;
30
31/// Output tag string (under 300 bytes).
32pub type OutputTagStringUnder300Bytes = String;
33
34/// Label string (under 300 bytes).
35pub type LabelStringUnder300Bytes = String;
36
37/// Key ID string (under 800 bytes).
38pub type KeyIDStringUnder800Bytes = String;
39
40/// Originator domain name string (under 250 bytes).
41pub type OriginatorDomainNameStringUnder250Bytes = String;
42
43/// Certificate field name (under 50 bytes).
44pub type CertificateFieldNameUnder50Bytes = String;
45
46/// Base64-encoded string.
47pub type Base64String = String;
48
49/// Hex-encoded string.
50pub type HexString = String;
51
52/// Boolean that defaults to true when None.
53///
54/// A newtype around `Option<bool>` that dereferences to `true` when the inner
55/// value is `None` or `Some(true)`. Serializes transparently as `Option<bool>`
56/// on the wire and in JSON.
57#[derive(Clone, Debug, PartialEq)]
58#[cfg_attr(feature = "network", derive(serde::Serialize, serde::Deserialize))]
59#[cfg_attr(feature = "network", serde(transparent))]
60pub struct BooleanDefaultTrue(pub Option<bool>);
61
62impl Default for BooleanDefaultTrue {
63    fn default() -> Self {
64        BooleanDefaultTrue(Some(true))
65    }
66}
67
68impl std::ops::Deref for BooleanDefaultTrue {
69    type Target = bool;
70    fn deref(&self) -> &bool {
71        static TRUE: bool = true;
72        static FALSE: bool = false;
73        match self.0 {
74            Some(true) | None => &TRUE,
75            Some(false) => &FALSE,
76        }
77    }
78}
79
80impl From<BooleanDefaultTrue> for Option<bool> {
81    fn from(v: BooleanDefaultTrue) -> Self {
82        v.0
83    }
84}
85
86impl From<Option<bool>> for BooleanDefaultTrue {
87    fn from(v: Option<bool>) -> Self {
88        BooleanDefaultTrue(v)
89    }
90}
91
92impl BooleanDefaultTrue {
93    /// Returns true if the inner value is None.
94    /// Used by serde skip_serializing_if.
95    pub fn is_none(&self) -> bool {
96        self.0.is_none()
97    }
98}
99
100/// Boolean that defaults to false when None.
101///
102/// A newtype around `Option<bool>` that dereferences to `false` when the inner
103/// value is `None` or `Some(false)`. Serializes transparently as `Option<bool>`
104/// on the wire and in JSON.
105#[derive(Clone, Debug, PartialEq)]
106#[cfg_attr(feature = "network", derive(serde::Serialize, serde::Deserialize))]
107#[cfg_attr(feature = "network", serde(transparent))]
108pub struct BooleanDefaultFalse(pub Option<bool>);
109
110impl Default for BooleanDefaultFalse {
111    fn default() -> Self {
112        BooleanDefaultFalse(Some(false))
113    }
114}
115
116impl std::ops::Deref for BooleanDefaultFalse {
117    type Target = bool;
118    fn deref(&self) -> &bool {
119        static TRUE: bool = true;
120        static FALSE: bool = false;
121        match self.0 {
122            Some(true) => &TRUE,
123            Some(false) | None => &FALSE,
124        }
125    }
126}
127
128impl From<BooleanDefaultFalse> for Option<bool> {
129    fn from(v: BooleanDefaultFalse) -> Self {
130        v.0
131    }
132}
133
134impl From<Option<bool>> for BooleanDefaultFalse {
135    fn from(v: Option<bool>) -> Self {
136        BooleanDefaultFalse(v)
137    }
138}
139
140impl BooleanDefaultFalse {
141    /// Returns true if the inner value is None.
142    /// Used by serde skip_serializing_if.
143    pub fn is_none(&self) -> bool {
144        self.0.is_none()
145    }
146}
147
148/// Positive integer defaulting to 10, max 10000.
149pub type PositiveIntegerDefault10Max10000 = Option<u32>;
150
151/// Positive integer or zero.
152pub type PositiveIntegerOrZero = u32;
153
154// ---------------------------------------------------------------------------
155// Protocol
156// ---------------------------------------------------------------------------
157
158/// Defines a protocol with its security level and name.
159///
160/// The security level determines how strictly the wallet enforces
161/// user confirmation:
162/// - 0: Silent (no user interaction)
163/// - 1: Every app (user confirms per app)
164/// - 2: Every app and counterparty (user confirms per app + counterparty)
165///
166/// Serializes as a JSON array `[securityLevel, "protocolName"]` matching
167/// the Go SDK encoding.
168#[derive(Clone, Debug)]
169pub struct Protocol {
170    pub security_level: u8,
171    pub protocol: String,
172}
173
174#[cfg(feature = "network")]
175impl serde::Serialize for Protocol {
176    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
177        use serde::ser::SerializeSeq;
178        let mut seq = serializer.serialize_seq(Some(2))?;
179        seq.serialize_element(&self.security_level)?;
180        seq.serialize_element(&self.protocol)?;
181        seq.end()
182    }
183}
184
185#[cfg(feature = "network")]
186impl<'de> serde::Deserialize<'de> for Protocol {
187    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
188        use serde::de::{self, SeqAccess, Visitor};
189        use std::fmt;
190
191        struct ProtocolVisitor;
192
193        impl<'de> Visitor<'de> for ProtocolVisitor {
194            type Value = Protocol;
195
196            fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
197                formatter.write_str("an array [securityLevel, protocolName]")
198            }
199
200            fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> Result<Protocol, A::Error> {
201                let security_level: u8 = seq
202                    .next_element()?
203                    .ok_or_else(|| de::Error::invalid_length(0, &self))?;
204                let protocol: String = seq
205                    .next_element()?
206                    .ok_or_else(|| de::Error::invalid_length(1, &self))?;
207                Ok(Protocol {
208                    security_level,
209                    protocol,
210                })
211            }
212        }
213
214        deserializer.deserialize_seq(ProtocolVisitor)
215    }
216}
217
218// ---------------------------------------------------------------------------
219// Counterparty
220// ---------------------------------------------------------------------------
221
222/// The type of counterparty in a cryptographic operation.
223#[derive(Clone, Debug, PartialEq)]
224pub enum CounterpartyType {
225    /// Uninitialized / unknown.
226    Uninitialized,
227    /// The wallet itself.
228    Self_,
229    /// The special "anyone" key (PrivateKey(1)).
230    Anyone,
231    /// A specific other party identified by public key.
232    Other,
233}
234
235/// Represents the other party in a cryptographic operation.
236///
237/// Can be a specific public key, or one of the special values
238/// "self" or "anyone".
239///
240/// Serializes as a JSON string: "anyone", "self", or DER hex public key,
241/// matching the Go SDK encoding.
242#[derive(Clone, Debug)]
243pub struct Counterparty {
244    pub counterparty_type: CounterpartyType,
245    pub public_key: Option<PublicKey>,
246}
247
248#[cfg(feature = "network")]
249impl serde::Serialize for Counterparty {
250    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
251        match self.counterparty_type {
252            CounterpartyType::Anyone => serializer.serialize_str("anyone"),
253            CounterpartyType::Self_ => serializer.serialize_str("self"),
254            CounterpartyType::Other => {
255                if let Some(ref pk) = self.public_key {
256                    serializer.serialize_str(&pk.to_der_hex())
257                } else {
258                    serializer.serialize_none()
259                }
260            }
261            CounterpartyType::Uninitialized => serializer.serialize_str(""),
262        }
263    }
264}
265
266#[cfg(feature = "network")]
267impl<'de> serde::Deserialize<'de> for Counterparty {
268    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
269        let s = String::deserialize(deserializer)?;
270        match s.as_str() {
271            "anyone" => Ok(Counterparty {
272                counterparty_type: CounterpartyType::Anyone,
273                public_key: None,
274            }),
275            "self" => Ok(Counterparty {
276                counterparty_type: CounterpartyType::Self_,
277                public_key: None,
278            }),
279            "" => Ok(Counterparty {
280                counterparty_type: CounterpartyType::Uninitialized,
281                public_key: None,
282            }),
283            hex_str => {
284                let pk = PublicKey::from_string(hex_str).map_err(serde::de::Error::custom)?;
285                Ok(Counterparty {
286                    counterparty_type: CounterpartyType::Other,
287                    public_key: Some(pk),
288                })
289            }
290        }
291    }
292}
293
294// ---------------------------------------------------------------------------
295// Anyone key helper
296// ---------------------------------------------------------------------------
297
298/// Returns the "anyone" public key: the public key corresponding to
299/// PrivateKey(1), which is the generator point G.
300///
301/// This is used when no specific counterparty is specified, making
302/// operations available to anyone who knows the protocol.
303pub fn anyone_pubkey() -> PublicKey {
304    let priv_key = PrivateKey::from_bytes(&{
305        let mut buf = [0u8; 32];
306        buf[31] = 1;
307        buf
308    })
309    // SAFETY: PrivateKey(1) is always valid -- 1 is within the secp256k1 scalar range.
310    .expect("PrivateKey(1) is always valid");
311    priv_key.to_public_key()
312}
313
314/// Returns the "anyone" private key: PrivateKey(1).
315pub fn anyone_private_key() -> PrivateKey {
316    PrivateKey::from_bytes(&{
317        let mut buf = [0u8; 32];
318        buf[31] = 1;
319        buf
320    })
321    // SAFETY: PrivateKey(1) is always valid -- 1 is within the secp256k1 scalar range.
322    .expect("PrivateKey(1) is always valid")
323}
bsv/wallet/types.rs

bsv/wallet/
types.rs
