miden_client/transaction/
store_update.rs

1use alloc::vec::Vec;
2
3use miden_protocol::block::BlockNumber;
4use miden_protocol::note::{NoteDetails, NoteTag};
5use miden_protocol::transaction::ExecutedTransaction;
6use miden_tx::utils::serde::{
7    ByteReader,
8    ByteWriter,
9    Deserializable,
10    DeserializationError,
11    Serializable,
12};
13
14use crate::note::NoteUpdateTracker;
15use crate::sync::NoteTagRecord;
16
17// TRANSACTION STORE UPDATE
18// ================================================================================================
19
20/// Represents the changes that need to be applied to the client store as a result of a
21/// transaction execution.
22#[derive(Debug, Clone, PartialEq)]
23pub struct TransactionStoreUpdate {
24    /// Details of the executed transaction to be inserted.
25    executed_transaction: ExecutedTransaction,
26    /// Block number at which the transaction was submitted.
27    submission_height: BlockNumber,
28    /// Future notes that are expected to be created as a result of the transaction.
29    future_notes: Vec<(NoteDetails, NoteTag)>,
30    /// Information about note changes after the transaction execution.
31    note_updates: NoteUpdateTracker,
32    /// New note tags to be tracked.
33    new_tags: Vec<NoteTagRecord>,
34}
35
36impl TransactionStoreUpdate {
37    /// Creates a new [`TransactionStoreUpdate`] instance populated with all relevant note data.
38    ///
39    /// # Arguments
40    /// - `executed_transaction`: The executed transaction details.
41    /// - `submission_height`: The block number at which the transaction was submitted.
42    /// - `note_updates`: The note updates that need to be applied to the store after the
43    ///   transaction execution.
44    /// - `future_notes`: Notes expected to be received in follow-up transactions (e.g. swap
45    ///   paybacks).
46    /// - `new_tags`: New note tags that need to be tracked because of created notes.
47    pub fn new(
48        executed_transaction: ExecutedTransaction,
49        submission_height: BlockNumber,
50        note_updates: NoteUpdateTracker,
51        future_notes: Vec<(NoteDetails, NoteTag)>,
52        new_tags: Vec<NoteTagRecord>,
53    ) -> Self {
54        Self {
55            executed_transaction,
56            submission_height,
57            future_notes,
58            note_updates,
59            new_tags,
60        }
61    }
62    /// Returns the executed transaction.
63    pub fn executed_transaction(&self) -> &ExecutedTransaction {
64        &self.executed_transaction
65    }
66
67    /// Returns the block number at which the transaction was submitted.
68    pub fn submission_height(&self) -> BlockNumber {
69        self.submission_height
70    }
71
72    /// Returns the future notes that should be tracked as a result of the transaction.
73    pub fn future_notes(&self) -> &[(NoteDetails, NoteTag)] {
74        &self.future_notes
75    }
76
77    /// Returns the note updates that need to be applied after the transaction execution.
78    pub fn note_updates(&self) -> &NoteUpdateTracker {
79        &self.note_updates
80    }
81
82    /// Returns the new tags that were created as part of the transaction.
83    pub fn new_tags(&self) -> &[NoteTagRecord] {
84        &self.new_tags
85    }
86}
87
88impl Serializable for TransactionStoreUpdate {
89    fn write_into<W: ByteWriter>(&self, target: &mut W) {
90        self.executed_transaction.write_into(target);
91        self.submission_height.write_into(target);
92        self.future_notes.write_into(target);
93        self.note_updates.write_into(target);
94        self.new_tags.write_into(target);
95    }
96}
97
98impl Deserializable for TransactionStoreUpdate {
99    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
100        let executed_transaction = ExecutedTransaction::read_from(source)?;
101        let submission_height = BlockNumber::read_from(source)?;
102        let future_notes = Vec::<(NoteDetails, NoteTag)>::read_from(source)?;
103        let note_updates = NoteUpdateTracker::read_from(source)?;
104        let new_tags = Vec::<NoteTagRecord>::read_from(source)?;
105
106        Ok(Self {
107            executed_transaction,
108            submission_height,
109            future_notes,
110            note_updates,
111            new_tags,
112        })
113    }
114}
115
116// TESTS
117// ================================================================================================
118
119#[cfg(test)]
120mod tests {
121    use alloc::boxed::Box;
122
123    use miden_protocol::asset::{Asset, FungibleAsset};
124    use miden_protocol::note::NoteType;
125    use miden_protocol::testing::account_id::{
126        ACCOUNT_ID_PRIVATE_FUNGIBLE_FAUCET,
127        ACCOUNT_ID_SENDER,
128    };
129    use miden_testing::{MockChainBuilder, MockTransactionInput};
130
131    use super::*;
132    use crate::note::NoteUpdateTracker;
133    use crate::store::InputNoteRecord;
134    use crate::sync::NoteTagRecord;
135
136    #[tokio::test]
137    async fn transaction_store_update_serialization_roundtrip() {
138        // Build a minimal MockChain with an account consuming a P2ID note so that we can
139        // produce a real `ExecutedTransaction`.
140        let sender_id = ACCOUNT_ID_SENDER.try_into().unwrap();
141        let faucet_id = ACCOUNT_ID_PRIVATE_FUNGIBLE_FAUCET.try_into().unwrap();
142        let asset = Asset::Fungible(FungibleAsset::new(faucet_id, 100u64).unwrap());
143
144        let mut builder = MockChainBuilder::new();
145        let account = builder.add_existing_mock_account(miden_testing::Auth::IncrNonce).unwrap();
146        let note = builder
147            .add_p2id_note(sender_id, account.id(), &[asset], NoteType::Public)
148            .unwrap();
149        let mut chain = builder.build().unwrap();
150        chain.prove_next_block().unwrap();
151
152        let executed_tx = Box::pin(
153            chain
154                .build_transaction(MockTransactionInput::Account(account.clone()))
155                .unauthenticated_input_note(note.clone())
156                .build()
157                .unwrap()
158                .execute(),
159        )
160        .await
161        .unwrap();
162
163        // Build non-trivial `note_updates` and `new_tags` so that the round-trip covers all
164        // fields that were previously dropped.
165        let input_note = InputNoteRecord::from(note.clone());
166        let note_updates = NoteUpdateTracker::for_transaction_updates([input_note], [], []);
167
168        let tag = NoteTag::with_account_target(account.id());
169        let new_tags = vec![NoteTagRecord::with_account_source(tag, account.id())];
170
171        let future_notes = vec![(Into::<NoteDetails>::into(note.clone()), tag)];
172
173        let update = TransactionStoreUpdate::new(
174            executed_tx,
175            BlockNumber::from(42u32),
176            note_updates,
177            future_notes,
178            new_tags,
179        );
180
181        let bytes = update.to_bytes();
182        let deserialized = TransactionStoreUpdate::read_from_bytes(&bytes).unwrap();
183
184        assert_eq!(update, deserialized);
185    }
186}
miden_client/transaction/store_update.rs

miden_client/transaction/
store_update.rs
