Skip to main content

bsv_rs/
lib.rs

1//! # bsv-rs
2//!
3//! A Rust SDK for BSV: cryptographic primitives, the Bitcoin Script
4//! interpreter, transactions with BEEF/SPV, BRC-42 wallets, BRC-103 mutual
5//! authentication, and the overlay network (SHIP/SLAP/STEAK), with storage,
6//! registry, key-value and identity clients on top. It is a reference-parity
7//! port of the TypeScript `@bsv/sdk` (cross-checked against the Go SDK),
8//! pinned by shared test vectors and the `ts-stack` conformance corpus, and it
9//! builds for `wasm32-unknown-unknown` (Cloudflare Workers, browsers).
10//!
11//! The README (`README.md`) is the guide: every code block in it is a file
12//! under `examples/` that CI compiles. Each module carries its own docs.
13//!
14//! ## Feature flags
15//!
16//! `default = ["primitives", "script"]`. Opt in per module: `transaction`,
17//! `wallet`, `messages`, `compat`, `totp`, `auth`, `overlay`, `storage`,
18//! `registry`, `kvstore`, `identity`, `socketio`; `full` turns every module
19//! on. Transports and platforms: `http` (reqwest: ARC, WhatsOnChain, the
20//! HTTP wallet substrate, overlay hosts), `websocket` (a tokio-tungstenite
21//! auth transport, opt-in), `wasm` (the JS RNG, runtime-agnostic timers,
22//! `js_sys::Date` for wall-clock reads).
23//!
24//! ## Quick start
25//!
26//! ```rust
27//! use bsv_rs::primitives::{sha256, PrivateKey};
28//!
29//! let private_key = PrivateKey::random();
30//! let public_key = private_key.public_key();
31//! let digest = sha256(b"Hello, BSV!");
32//! let signature = private_key.sign(&digest).unwrap();
33//! assert!(public_key.verify(&digest, &signature));
34//! ```
35
36// Error types (shared across modules)
37pub mod error;
38pub use error::{Error, Result};
39
40// Internal utilities (wasm32-safe time helpers, etc.). Not part of the
41// public API — see `src/util/mod.rs`.
42pub(crate) mod util;
43
44// Feature-gated modules
45#[cfg(feature = "primitives")]
46pub mod primitives;
47
48#[cfg(feature = "script")]
49pub mod script;
50
51#[cfg(feature = "block")]
52pub mod block;
53
54#[cfg(feature = "transaction")]
55pub mod transaction;
56
57#[cfg(feature = "wallet")]
58pub mod wallet;
59
60#[cfg(feature = "messages")]
61pub mod messages;
62
63#[cfg(feature = "compat")]
64pub mod compat;
65
66#[cfg(feature = "totp")]
67pub mod totp;
68
69#[cfg(feature = "auth")]
70pub mod auth;
71
72#[cfg(feature = "overlay")]
73pub mod overlay;
74
75#[cfg(feature = "storage")]
76pub mod storage;
77
78#[cfg(feature = "registry")]
79pub mod registry;
80
81#[cfg(feature = "kvstore")]
82pub mod kvstore;
83
84#[cfg(feature = "identity")]
85pub mod identity;
86
87// Convenience re-exports from primitives (most common items)
88#[cfg(feature = "primitives")]
89pub use primitives::{
90    from_hex, hash160, sha256, sha256d, to_hex, BigNumber, PrivateKey, PublicKey, Signature,
91    SymmetricKey,
92};
93
94// Convenience re-exports from script
95#[cfg(feature = "script")]
96pub use script::{Address, LockingScript, Script, ScriptChunk, UnlockingScript};
97
98// Convenience re-exports from transaction
99#[cfg(feature = "transaction")]
100pub use transaction::{ChangeDistribution, Transaction, TransactionInput, TransactionOutput};
101
102// Convenience re-exports from wallet
103#[cfg(feature = "wallet")]
104pub use wallet::{
105    CacheConfig, CachedKeyDeriver, Counterparty, KeyDeriver, KeyDeriverApi, ProtoWallet, Protocol,
106    SecurityLevel,
107};
108
109// Convenience re-exports from messages
110#[cfg(feature = "messages")]
111pub use messages::{decrypt, encrypt, sign, verify};
112
113// Convenience re-exports from compat
114#[cfg(feature = "compat")]
115pub use compat::{Language, Mnemonic, WordCount};
116
117// Convenience re-exports from totp
118#[cfg(feature = "totp")]
119pub use totp::{Algorithm as TotpAlgorithm, Totp, TotpOptions, TotpValidateOptions};
120
121// Convenience re-exports from auth
122#[cfg(feature = "socketio")]
123pub use auth::{
124    install_app_event_listener, run_dispatch, AppEvent, SocketIoFrameSource, SocketIoSink,
125    SocketIoTransport,
126};
127#[cfg(feature = "auth")]
128pub use auth::{
129    AuthMessage, Certificate, MasterCertificate, MessageType, Peer, PeerOptions, PeerSession,
130    RequestedCertificateSet, SessionManager, SimplifiedFetchTransport, Transport,
131    VerifiableCertificate,
132};
133#[cfg(feature = "websocket")]
134pub use auth::{WebSocketTransport, WebSocketTransportOptions};
135
136// Convenience re-exports from overlay
137#[cfg(feature = "overlay")]
138pub use overlay::{
139    LookupAnswer, LookupQuestion, LookupResolver, NetworkPreset, Steak, TaggedBEEF,
140    TopicBroadcaster,
141};
142// Note: overlay::Protocol is separate from wallet::Protocol
143
144// Convenience re-exports from storage
145#[cfg(feature = "storage")]
146pub use storage::{
147    get_hash_from_url, get_url_for_file, is_valid_url, DownloadResult, StorageDownloader,
148    StorageUploader, UploadFileResult, UploadableFile,
149};
150
151// Convenience re-exports from registry
152#[cfg(feature = "registry")]
153pub use registry::{
154    BasketDefinitionData, BasketQuery, BroadcastFailure, BroadcastSuccess,
155    CertificateDefinitionData, CertificateFieldDescriptor, CertificateQuery, DefinitionData,
156    DefinitionType, ProtocolDefinitionData, ProtocolQuery, RegisterDefinitionResult,
157    RegistryClient, RegistryClientConfig, RegistryRecord, RevokeDefinitionResult, TokenData,
158};
159
160// Convenience re-exports from kvstore
161#[cfg(feature = "kvstore")]
162pub use kvstore::{
163    GlobalKVStore, KVStoreConfig, KVStoreEntry, KVStoreGetOptions, KVStoreQuery,
164    KVStoreRemoveOptions, KVStoreSetOptions, KVStoreToken, LocalKVStore,
165};
166
167// Convenience re-exports from identity
168#[cfg(feature = "identity")]
169pub use identity::{
170    Contact, ContactsManager, ContactsManagerConfig, DisplayableIdentity, IdentityClient,
171    IdentityClientConfig, IdentityQuery, KnownCertificateType,
172};