miden_objects/note/
mod.rs

1use miden_crypto::Word;
2use miden_crypto::utils::{ByteReader, ByteWriter, Deserializable, Serializable};
3use miden_processor::DeserializationError;
4
5use crate::account::AccountId;
6use crate::{Felt, Hasher, NoteError, WORD_SIZE, ZERO};
7
8mod assets;
9pub use assets::NoteAssets;
10
11mod details;
12pub use details::NoteDetails;
13
14mod header;
15pub use header::{NoteHeader, compute_note_commitment};
16
17mod inputs;
18pub use inputs::NoteInputs;
19
20mod metadata;
21pub use metadata::NoteMetadata;
22
23mod execution_hint;
24pub use execution_hint::{AfterBlockNumber, NoteExecutionHint};
25
26mod note_id;
27pub use note_id::NoteId;
28
29mod note_tag;
30pub use note_tag::{NoteExecutionMode, NoteTag};
31
32mod note_type;
33pub use note_type::NoteType;
34
35mod nullifier;
36pub use nullifier::Nullifier;
37
38mod location;
39pub use location::{NoteInclusionProof, NoteLocation};
40
41mod partial;
42pub use partial::PartialNote;
43
44mod recipient;
45pub use recipient::NoteRecipient;
46
47mod script;
48pub use script::NoteScript;
49
50mod file;
51pub use file::NoteFile;
52
53// NOTE
54// ================================================================================================
55
56/// A note with all the data required for it to be consumed by executing it against the transaction
57/// kernel.
58///
59/// Notes consist of note metadata and details. Note metadata is always public, but details may be
60/// either public, encrypted, or private, depending on the note type. Note details consist of note
61/// assets, script, inputs, and a serial number, the three latter grouped into a recipient object.
62///
63/// Note details can be reduced to two unique identifiers: [NoteId] and [Nullifier]. The former is
64/// publicly associated with a note, while the latter is known only to entities which have access
65/// to full note details.
66///
67/// Fungible and non-fungible asset transfers are done by moving assets to the note's assets. The
68/// note's script determines the conditions required for the note consumption, i.e. the target
69/// account of a P2ID or conditions of a SWAP, and the effects of the note. The serial number has
70/// a double duty of preventing double spend, and providing unlikability to the consumer of a note.
71/// The note's inputs allow for customization of its script.
72///
73/// To create a note, the kernel does not require all the information above, a user can create a
74/// note only with the commitment to the script, inputs, the serial number (i.e., the recipient),
75/// and the kernel only verifies the source account has the assets necessary for the note creation.
76/// See [NoteRecipient] for more details.
77#[derive(Clone, Debug, PartialEq, Eq)]
78pub struct Note {
79    header: NoteHeader,
80    details: NoteDetails,
81
82    nullifier: Nullifier,
83}
84
85impl Note {
86    // CONSTRUCTOR
87    // --------------------------------------------------------------------------------------------
88
89    /// Returns a new [Note] created with the specified parameters.
90    pub fn new(assets: NoteAssets, metadata: NoteMetadata, recipient: NoteRecipient) -> Self {
91        let details = NoteDetails::new(assets, recipient);
92        let header = NoteHeader::new(details.id(), metadata);
93        let nullifier = details.nullifier();
94
95        Self { header, details, nullifier }
96    }
97
98    // PUBLIC ACCESSORS
99    // --------------------------------------------------------------------------------------------
100
101    /// Returns the note's header.
102    pub fn header(&self) -> &NoteHeader {
103        &self.header
104    }
105
106    /// Returns the note's unique identifier.
107    ///
108    /// This value is both an unique identifier and a commitment to the note.
109    pub fn id(&self) -> NoteId {
110        self.header.id()
111    }
112
113    /// Returns the note's metadata.
114    pub fn metadata(&self) -> &NoteMetadata {
115        self.header.metadata()
116    }
117
118    /// Returns the note's assets.
119    pub fn assets(&self) -> &NoteAssets {
120        self.details.assets()
121    }
122
123    /// Returns the note's recipient serial_num, the secret required to consume the note.
124    pub fn serial_num(&self) -> Word {
125        self.details.serial_num()
126    }
127
128    /// Returns the note's recipient script which locks the assets of this note.
129    pub fn script(&self) -> &NoteScript {
130        self.details.script()
131    }
132
133    /// Returns the note's recipient inputs which customizes the script's behavior.
134    pub fn inputs(&self) -> &NoteInputs {
135        self.details.inputs()
136    }
137
138    /// Returns the note's recipient.
139    pub fn recipient(&self) -> &NoteRecipient {
140        self.details.recipient()
141    }
142
143    /// Returns the note's nullifier.
144    ///
145    /// This is public data, used to prevent double spend.
146    pub fn nullifier(&self) -> Nullifier {
147        self.nullifier
148    }
149
150    /// Returns a commitment to the note and its metadata.
151    ///
152    /// > hash(NOTE_ID || NOTE_METADATA)
153    ///
154    /// This value is used primarily for authenticating notes consumed when the are consumed
155    /// in a transaction.
156    pub fn commitment(&self) -> Word {
157        self.header.commitment()
158    }
159
160    /// Returns true if this note is intended to be executed by the network rather than a user.
161    pub fn is_network_note(&self) -> bool {
162        self.metadata().tag().execution_mode() == NoteExecutionMode::Network
163    }
164}
165
166// AS REF
167// ================================================================================================
168
169impl AsRef<NoteRecipient> for Note {
170    fn as_ref(&self) -> &NoteRecipient {
171        self.recipient()
172    }
173}
174
175// CONVERSIONS FROM NOTE
176// ================================================================================================
177
178impl From<&Note> for NoteHeader {
179    fn from(note: &Note) -> Self {
180        note.header
181    }
182}
183
184impl From<Note> for NoteHeader {
185    fn from(note: Note) -> Self {
186        note.header
187    }
188}
189
190impl From<&Note> for NoteDetails {
191    fn from(note: &Note) -> Self {
192        note.details.clone()
193    }
194}
195
196impl From<Note> for NoteDetails {
197    fn from(note: Note) -> Self {
198        note.details
199    }
200}
201
202impl From<Note> for PartialNote {
203    fn from(note: Note) -> Self {
204        let (assets, recipient, ..) = note.details.into_parts();
205        PartialNote::new(*note.header.metadata(), recipient.digest(), assets)
206    }
207}
208
209impl From<&Note> for PartialNote {
210    fn from(note: &Note) -> Self {
211        PartialNote::new(
212            *note.header.metadata(),
213            note.details.recipient().digest(),
214            note.details.assets().clone(),
215        )
216    }
217}
218
219// SERIALIZATION
220// ================================================================================================
221
222impl Serializable for Note {
223    fn write_into<W: ByteWriter>(&self, target: &mut W) {
224        let Self {
225            header,
226            details,
227
228            // nullifier is not serialized as it can be computed from the rest of the data
229            nullifier: _,
230        } = self;
231
232        // only metadata is serialized as note ID can be computed from note details
233        header.metadata().write_into(target);
234        details.write_into(target);
235    }
236}
237
238impl Deserializable for Note {
239    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
240        let metadata = NoteMetadata::read_from(source)?;
241        let details = NoteDetails::read_from(source)?;
242        let (assets, recipient) = details.into_parts();
243
244        Ok(Self::new(assets, metadata, recipient))
245    }
246}
miden_objects/note/mod.rs

miden_objects/note/
mod.rs
