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
//! # KVStore Module
//!
//! Blockchain-backed key-value storage for BSV applications.
//!
//! This module provides two implementations of persistent key-value storage:
//!
//! - **[`LocalKVStore`]**: Private storage using wallet transactions and baskets.
//! Values are encrypted by default and only accessible by the wallet owner.
//!
//! - **[`GlobalKVStore`]**: Public storage using the overlay network.
//! Values are stored as PushDrop tokens and discoverable via lookup services.
//!
//! ## Features
//!
//! - **Persistent storage**: Values are stored on-chain in transaction outputs
//! - **Encryption**: LocalKVStore encrypts values using wallet-derived keys
//! - **Tagging**: Entries can be tagged for filtering and discovery
//! - **Atomic operations**: Concurrent access is serialized per key
//! - **Cross-SDK compatible**: API matches TypeScript and Go SDK implementations
//!
//! ## Quick Start
//!
//! ### LocalKVStore (Private)
//!
//! ```rust,ignore
//! use bsv_rs::kvstore::{LocalKVStore, KVStoreConfig};
//! use bsv_rs::wallet::ProtoWallet;
//!
//! // Create a local store with default configuration
//! let wallet = ProtoWallet::new(None);
//! let config = KVStoreConfig::default();
//! let store = LocalKVStore::new(wallet, config);
//!
//! // Set a value
//! store.set("my_key", "my_value", None).await?;
//!
//! // Get a value
//! if let Some(entry) = store.get("my_key", None).await? {
//! println!("Value: {}", entry.value);
//! }
//!
//! // List all keys
//! let keys = store.keys().await?;
//!
//! // Remove a value
//! store.remove("my_key", None).await?;
//! ```
//!
//! ### GlobalKVStore (Public)
//!
//! ```rust,ignore
//! use bsv_rs::kvstore::{GlobalKVStore, KVStoreConfig, KVStoreQuery};
//! use bsv_rs::wallet::ProtoWallet;
//!
//! // Create a global store
//! let wallet = ProtoWallet::new(None);
//! let config = KVStoreConfig::default();
//! let store = GlobalKVStore::new(wallet, config);
//!
//! // Set a public value
//! store.set("public_key", "public_value", None).await?;
//!
//! // Query entries
//! let query = KVStoreQuery::new()
//! .with_tags(vec!["important".to_string()])
//! .with_limit(10);
//! let entries = store.query(query).await?;
//!
//! // Get entries by controller
//! let my_entries = store.get_by_controller("02abc...").await?;
//! ```
//!
//! ## PushDrop Token Format
//!
//! Global entries use PushDrop tokens with the following field layout:
//!
//! | Index | Field | Description |
//! |-------|-------|-------------|
//! | 0 | Protocol ID | String identifier (e.g., "kvstore") |
//! | 1 | Key | The key string |
//! | 2 | Value | The value (encrypted for LocalKVStore) |
//! | 3 | Controller | 33-byte compressed public key |
//! | 4 | Tags | JSON array of tag strings (optional) |
//! | 5 | Signature | Controller's signature over fields 0-4 |
//!
//! ## Configuration
//!
//! The [`KVStoreConfig`] struct controls store behavior:
//!
//! - `protocol_id`: Namespace for entries (default: "kvstore")
//! - `service_name`: Overlay lookup service (default: "ls_kvstore")
//! - `token_amount`: Satoshis per token (default: 1)
//! - `topics`: Broadcast topics (default: ["tm_kvstore"])
//! - `encrypt`: Enable encryption for LocalKVStore (default: true)
//!
//! ## Error Handling
//!
//! KVStore operations return [`crate::Result<T>`] with specific error types:
//!
//! - [`Error::KvStoreError`](crate::Error::KvStoreError): General kvstore errors
//! - [`Error::KvStoreKeyNotFound`](crate::Error::KvStoreKeyNotFound): Key doesn't exist
//! - [`Error::KvStoreCorruptedState`](crate::Error::KvStoreCorruptedState): Invalid state
// Re-export main types
pub use ;
// Re-export store implementations
pub use GlobalKVStore;
pub use LocalKVStore;
// Re-export interpreter types
pub use ;