miden_client/sync/mod.rs
1//! Provides the client APIs for synchronizing the client's local state with the Miden
2//! network. It ensures that the client maintains a valid, up-to-date view of the chain.
3//!
4//! ## Overview
5//!
6//! This module handles the synchronization process between the local client and the Miden network.
7//! The sync operation involves:
8//!
9//! - Querying the Miden node for state updates using tracked account IDs, note tags, and nullifier
10//! prefixes.
11//! - Processing the received data to update note inclusion proofs, reconcile note state (new,
12//! committed, or consumed), and update account states.
13//! - Incorporating new block headers and updating the local Merkle Mountain Range (MMR) with new
14//! peaks and authentication nodes.
15//! - Aggregating transaction updates to determine which transactions have been committed or
16//! discarded.
17//!
18//! The result of the synchronization process is captured in a [`SyncSummary`], which provides
19//! a summary of the new block number along with lists of received, committed, and consumed note
20//! IDs, updated account IDs, locked accounts, and committed transaction IDs.
21//!
22//! Once the data is requested and retrieved, updates are persisted in the client's store.
23//!
24//! ## Examples
25//!
26//! The following example shows how to initiate a state sync and handle the resulting summary:
27//!
28//! ```rust
29//! # use miden_client::sync::SyncSummary;
30//! # use miden_client::{Client, ClientError};
31//! # use miden_objects::{block::BlockHeader, Felt, Word, StarkField};
32//! # use miden_objects::crypto::rand::FeltRng;
33//! # async fn run_sync(client: &mut Client) -> Result<(), ClientError> {
34//! // Attempt to synchronize the client's state with the Miden network.
35//! // The requested data is based on the client's state: it gets updates for accounts, relevant
36//! // notes, etc. For more information on the data that gets requested, see the doc comments for
37//! // `sync_state()`.
38//! let sync_summary: SyncSummary = client.sync_state().await?;
39//!
40//! println!("Synced up to block number: {}", sync_summary.block_num);
41//! println!("Committed notes: {}", sync_summary.committed_notes.len());
42//! println!("Consumed notes: {}", sync_summary.consumed_notes.len());
43//! println!("Updated accounts: {}", sync_summary.updated_accounts.len());
44//! println!("Locked accounts: {}", sync_summary.locked_accounts.len());
45//! println!("Committed transactions: {}", sync_summary.committed_transactions.len());
46//!
47//! Ok(())
48//! # }
49//! ```
50//!
51//! The `sync_state` method loops internally until the client is fully synced to the network tip.
52//!
53//! For more advanced usage, refer to the individual functions (such as
54//! `committed_note_updates` and `consumed_note_updates`) to understand how the sync data is
55//! processed and applied to the local store.
56
57use alloc::{boxed::Box, collections::BTreeSet, vec::Vec};
58use core::cmp::max;
59
60use miden_objects::{
61 account::AccountId,
62 block::BlockNumber,
63 note::{NoteId, NoteTag},
64 transaction::{PartialBlockchain, TransactionId},
65};
66use miden_tx::utils::{Deserializable, DeserializationError, Serializable};
67
68use crate::{
69 Client, ClientError,
70 note::NoteScreener,
71 store::{NoteFilter, TransactionFilter},
72};
73mod block_header;
74
75mod tag;
76pub use tag::{NoteTagRecord, NoteTagSource};
77
78mod state_sync;
79pub use state_sync::{OnNoteReceived, StateSync, on_note_received};
80
81mod state_sync_update;
82pub use state_sync_update::{
83 AccountUpdates, BlockUpdates, StateSyncUpdate, TransactionUpdateTracker,
84};
85
86/// Client synchronization methods.
87impl Client {
88 // SYNC STATE
89 // --------------------------------------------------------------------------------------------
90
91 /// Returns the block number of the last state sync block.
92 pub async fn get_sync_height(&self) -> Result<BlockNumber, ClientError> {
93 self.store.get_sync_height().await.map_err(Into::into)
94 }
95
96 /// Syncs the client's state with the current state of the Miden network and returns a
97 /// [`SyncSummary`] corresponding to the local state update.
98 ///
99 /// The sync process is done in multiple steps:
100 /// 1. A request is sent to the node to get the state updates. This request includes tracked
101 /// account IDs and the tags of notes that might have changed or that might be of interest to
102 /// the client.
103 /// 2. A response is received with the current state of the network. The response includes
104 /// information about new/committed/consumed notes, updated accounts, and committed
105 /// transactions.
106 /// 3. Tracked notes are updated with their new states.
107 /// 4. New notes are checked, and only relevant ones are stored. Relevant notes are those that
108 /// can be consumed by accounts the client is tracking (this is checked by the
109 /// [`crate::note::NoteScreener`])
110 /// 5. Transactions are updated with their new states.
111 /// 6. Tracked public accounts are updated and private accounts are validated against the node
112 /// state.
113 /// 7. The MMR is updated with the new peaks and authentication nodes.
114 /// 8. All updates are applied to the store to be persisted.
115 pub async fn sync_state(&mut self) -> Result<SyncSummary, ClientError> {
116 _ = self.ensure_genesis_in_place().await?;
117
118 let note_screener =
119 NoteScreener::new(self.store.clone(), &self.tx_executor, self.mast_store.clone());
120
121 let state_sync = StateSync::new(
122 self.rpc_api.clone(),
123 Box::new({
124 let store_clone = self.store.clone();
125 move |committed_note, public_note, note_screener| {
126 Box::pin(on_note_received(
127 store_clone.clone(),
128 committed_note,
129 public_note,
130 note_screener,
131 ))
132 }
133 }),
134 self.tx_graceful_blocks,
135 note_screener,
136 );
137
138 // Get current state of the client
139 let accounts = self
140 .store
141 .get_account_headers()
142 .await?
143 .into_iter()
144 .map(|(acc_header, _)| acc_header)
145 .collect();
146
147 let note_tags: Vec<NoteTag> =
148 self.store.get_unique_note_tags().await?.into_iter().collect();
149
150 let unspent_input_notes = self.store.get_input_notes(NoteFilter::Unspent).await?;
151 let unspent_output_notes = self.store.get_output_notes(NoteFilter::Unspent).await?;
152
153 let uncommitted_transactions =
154 self.store.get_transactions(TransactionFilter::Uncommitted).await?;
155
156 // Build current partial MMR
157 let current_partial_mmr = self.build_current_partial_mmr().await?;
158
159 let all_block_numbers = (0..current_partial_mmr.forest())
160 .filter_map(|block_num| {
161 current_partial_mmr.is_tracked(block_num).then_some(BlockNumber::from(
162 u32::try_from(block_num).expect("block number should be less than u32::MAX"),
163 ))
164 })
165 .collect::<BTreeSet<_>>();
166
167 let block_headers = self
168 .store
169 .get_block_headers(&all_block_numbers)
170 .await?
171 .into_iter()
172 .map(|(header, _has_notes)| header);
173
174 // Get the sync update from the network
175 let state_sync_update = state_sync
176 .sync_state(
177 PartialBlockchain::new(current_partial_mmr, block_headers)?,
178 accounts,
179 note_tags,
180 unspent_input_notes,
181 unspent_output_notes,
182 uncommitted_transactions,
183 )
184 .await?;
185
186 let sync_summary: SyncSummary = (&state_sync_update).into();
187
188 // Apply received and computed updates to the store
189 self.store
190 .apply_state_sync(state_sync_update)
191 .await
192 .map_err(ClientError::StoreError)?;
193
194 // Remove irrelevant block headers
195 self.store.prune_irrelevant_blocks().await?;
196
197 Ok(sync_summary)
198 }
199}
200
201// SYNC SUMMARY
202// ================================================================================================
203
204/// Contains stats about the sync operation.
205#[derive(Debug, PartialEq)]
206pub struct SyncSummary {
207 /// Block number up to which the client has been synced.
208 pub block_num: BlockNumber,
209 /// IDs of new public notes that the client has received.
210 pub new_public_notes: Vec<NoteId>,
211 /// IDs of tracked notes that have been committed.
212 pub committed_notes: Vec<NoteId>,
213 /// IDs of notes that have been consumed.
214 pub consumed_notes: Vec<NoteId>,
215 /// IDs of on-chain accounts that have been updated.
216 pub updated_accounts: Vec<AccountId>,
217 /// IDs of private accounts that have been locked.
218 pub locked_accounts: Vec<AccountId>,
219 /// IDs of committed transactions.
220 pub committed_transactions: Vec<TransactionId>,
221}
222
223impl SyncSummary {
224 pub fn new(
225 block_num: BlockNumber,
226 new_public_notes: Vec<NoteId>,
227 committed_notes: Vec<NoteId>,
228 consumed_notes: Vec<NoteId>,
229 updated_accounts: Vec<AccountId>,
230 locked_accounts: Vec<AccountId>,
231 committed_transactions: Vec<TransactionId>,
232 ) -> Self {
233 Self {
234 block_num,
235 new_public_notes,
236 committed_notes,
237 consumed_notes,
238 updated_accounts,
239 locked_accounts,
240 committed_transactions,
241 }
242 }
243
244 pub fn new_empty(block_num: BlockNumber) -> Self {
245 Self {
246 block_num,
247 new_public_notes: vec![],
248 committed_notes: vec![],
249 consumed_notes: vec![],
250 updated_accounts: vec![],
251 locked_accounts: vec![],
252 committed_transactions: vec![],
253 }
254 }
255
256 pub fn is_empty(&self) -> bool {
257 self.new_public_notes.is_empty()
258 && self.committed_notes.is_empty()
259 && self.consumed_notes.is_empty()
260 && self.updated_accounts.is_empty()
261 && self.locked_accounts.is_empty()
262 && self.committed_transactions.is_empty()
263 }
264
265 pub fn combine_with(&mut self, mut other: Self) {
266 self.block_num = max(self.block_num, other.block_num);
267 self.new_public_notes.append(&mut other.new_public_notes);
268 self.committed_notes.append(&mut other.committed_notes);
269 self.consumed_notes.append(&mut other.consumed_notes);
270 self.updated_accounts.append(&mut other.updated_accounts);
271 self.locked_accounts.append(&mut other.locked_accounts);
272 self.committed_transactions.append(&mut other.committed_transactions);
273 }
274}
275
276impl Serializable for SyncSummary {
277 fn write_into<W: miden_tx::utils::ByteWriter>(&self, target: &mut W) {
278 self.block_num.write_into(target);
279 self.new_public_notes.write_into(target);
280 self.committed_notes.write_into(target);
281 self.consumed_notes.write_into(target);
282 self.updated_accounts.write_into(target);
283 self.locked_accounts.write_into(target);
284 self.committed_transactions.write_into(target);
285 }
286}
287
288impl Deserializable for SyncSummary {
289 fn read_from<R: miden_tx::utils::ByteReader>(
290 source: &mut R,
291 ) -> Result<Self, DeserializationError> {
292 let block_num = BlockNumber::read_from(source)?;
293 let new_public_notes = Vec::<NoteId>::read_from(source)?;
294 let committed_notes = Vec::<NoteId>::read_from(source)?;
295 let consumed_notes = Vec::<NoteId>::read_from(source)?;
296 let updated_accounts = Vec::<AccountId>::read_from(source)?;
297 let locked_accounts = Vec::<AccountId>::read_from(source)?;
298 let committed_transactions = Vec::<TransactionId>::read_from(source)?;
299
300 Ok(Self {
301 block_num,
302 new_public_notes,
303 committed_notes,
304 consumed_notes,
305 updated_accounts,
306 locked_accounts,
307 committed_transactions,
308 })
309 }
310}