miden_lib/transaction/memory.rs
1// TYPE ALIASES
2// ================================================================================================
3
4pub type MemoryAddress = u32;
5pub type MemoryOffset = u32;
6pub type DataIndex = usize;
7pub type MemSize = usize;
8pub type StorageSlot = u8;
9
10// PUBLIC CONSTANTS
11// ================================================================================================
12
13// General layout
14//
15// Here the "end address" is the last memory address occupied by the current data
16//
17// | Section | Start address, pointer (word pointer) | End address, pointer (word pointer) | Comment |
18// | ----------------- | :-----------------------------------: | :---------------------------------: | ------------------------------------------- |
19// | Bookkeeping | 0 (0) | 287 (71) | |
20// | Global inputs | 400 (100) | 423 (105) | |
21// | Block header | 800 (200) | 835 (208) | |
22// | Partial blockchain | 1_200 (300) | 1_331? (332?) | |
23// | Kernel data | 1_600 (400) | 1_739 (434) | 34 procedures in total, 4 elements each |
24// | Accounts data | 8_192 (2048) | 532_479 (133_119) | 64 accounts max, 8192 elements each |
25// | Input notes | 4_194_304 (1_048_576) | ? | |
26// | Output notes | 16_777_216 (4_194_304) | ? | |
27
28// Relative layout of one account
29//
30// Here the "end pointer" is the last memory pointer occupied by the current data
31//
32// | Section | Start address, pointer (word pointer) | End address, pointer (word pointer) | Comment |
33// | ----------------- | :-----------------------------------: | :---------------------------------: | ----------------------------------- |
34// | Id and nonce | 0 (0) | 3 (0) | |
35// | Vault root | 4 (1) | 7 (1) | |
36// | Storage root | 8 (2) | 11 (2) | |
37// | Code root | 12 (3) | 15 (3) | |
38// | Padding | 16 (4) | 27 (6) | |
39// | Num procedures | 28 (7) | 31 (7) | |
40// | Procedures info | 32 (8) | 2_079 (519) | 255 procedures max, 8 elements each |
41// | Padding | 2_080 (520) | 2_083 (520) | |
42// | Num storage slots | 2_084 (521) | 2_087 (521) | |
43// | Storage slot info | 2_088 (522) | 4_127 (1031) | 255 slots max, 8 elements each |
44// | Padding | 4_128 (1032) | 8_191 (2047) | |
45
46// RESERVED ACCOUNT STORAGE SLOTS
47// ------------------------------------------------------------------------------------------------
48
49/// The account storage slot at which faucet data is stored.
50///
51/// - Fungible faucet: The faucet data consists of [0, 0, 0, total_issuance].
52/// - Non-fungible faucet: The faucet data consists of SMT root containing minted non-fungible
53/// assets.
54pub const FAUCET_STORAGE_DATA_SLOT: StorageSlot = 0;
55
56// BOOKKEEPING
57// ------------------------------------------------------------------------------------------------
58
59/// The memory address at which the transaction vault root is stored.
60pub const TX_VAULT_ROOT_PTR: MemoryAddress = 0;
61
62/// The memory address at which a pointer to the input note being executed is stored.
63pub const CURRENT_INPUT_NOTE_PTR: MemoryAddress = 4;
64
65/// The memory address at which the number of output notes is stored.
66pub const NUM_OUTPUT_NOTES_PTR: MemoryAddress = 8;
67
68/// The memory address at which the input vault root is stored.
69pub const INPUT_VAULT_ROOT_PTR: MemoryAddress = 12;
70
71/// The memory address at which the output vault root is stored.
72pub const OUTPUT_VAULT_ROOT_PTR: MemoryAddress = 16;
73
74/// The memory address at which the native account's new code commitment is stored.
75pub const NEW_CODE_ROOT_PTR: MemoryAddress = 20;
76
77/// The memory address at which the transaction expiration block number is stored.
78pub const TX_EXPIRATION_BLOCK_NUM_PTR: MemoryAddress = 24;
79
80/// The memory address at which the pointer to the stack element containing the pointer to the
81/// currently active account data is stored.
82///
83/// The stack starts at the address `29`. Stack has a length of `64` elements meaning that the
84/// maximum depth of FPI calls is `63` — the first slot is always occupied by the native account
85/// data pointer.
86///
87/// ```text
88/// ┌───────────────┬────────────────┬───────────────────┬─────┬────────────────────┐
89/// │ STACK TOP PTR │ NATIVE ACCOUNT │ FOREIGN ACCOUNT 1 │ ... │ FOREIGN ACCOUNT 63 │
90/// ├───────────────┼────────────────┼───────────────────┼─────┼────────────────────┤
91/// 28 29 30 92
92/// ```
93pub const ACCOUNT_STACK_TOP_PTR: MemoryAddress = 28;
94
95// GLOBAL INPUTS
96// ------------------------------------------------------------------------------------------------
97
98/// The memory address at which the global inputs section begins.
99pub const GLOBAL_INPUTS_SECTION_OFFSET: MemoryOffset = 400;
100
101/// The memory address at which the commitment of the transaction's reference block is stored.
102pub const BLOCK_COMMITMENT_PTR: MemoryAddress = 400;
103
104/// The memory address at which the account ID is stored.
105pub const ACCT_ID_PTR: MemoryAddress = 404;
106
107/// The memory address at which the initial account commitment is stored.
108pub const INIT_ACCT_COMMITMENT_PTR: MemoryAddress = 408;
109
110/// The memory address at which the input notes commitment is stored.
111pub const INPUT_NOTES_COMMITMENT_PTR: MemoryAddress = 412;
112
113/// The memory address at which the initial nonce is stored.
114pub const INIT_NONCE_PTR: MemoryAddress = 416;
115
116/// The memory address at which the transaction script mast root is store
117pub const TX_SCRIPT_ROOT_PTR: MemoryAddress = 420;
118
119// BLOCK DATA
120// ------------------------------------------------------------------------------------------------
121
122/// The memory address at which the block data section begins
123pub const BLOCK_DATA_SECTION_OFFSET: MemoryOffset = 800;
124
125/// The memory address at which the previous block commitment is stored
126pub const PREV_BLOCK_COMMITMENT_PTR: MemoryAddress = 800;
127
128/// The memory address at which the chain commitment is stored
129pub const CHAIN_COMMITMENT_PTR: MemoryAddress = 804;
130
131/// The memory address at which the state root is stored
132pub const ACCT_DB_ROOT_PTR: MemoryAddress = 808;
133
134/// The memory address at which the nullifier db root is store
135pub const NULLIFIER_DB_ROOT_PTR: MemoryAddress = 812;
136
137/// The memory address at which the TX commitment is stored
138pub const TX_COMMITMENT_PTR: MemoryAddress = 816;
139
140/// The memory address at which the transaction kernel commitment is stored
141pub const TX_KERNEL_COMMITMENT_PTR: MemoryAddress = 820;
142
143/// The memory address at which the proof commitment is stored
144pub const PROOF_COMMITMENT_PTR: MemoryAddress = 824;
145
146/// The memory address at which the block number is stored
147pub const BLOCK_METADATA_PTR: MemoryAddress = 828;
148
149/// The index of the block number within the block metadata
150pub const BLOCK_NUMBER_IDX: DataIndex = 0;
151
152/// The index of the protocol version within the block metadata
153pub const PROTOCOL_VERSION_IDX: DataIndex = 1;
154
155/// The index of the timestamp within the block metadata
156pub const TIMESTAMP_IDX: DataIndex = 2;
157
158/// The memory address at which the note root is stored
159pub const NOTE_ROOT_PTR: MemoryAddress = 832;
160
161// CHAIN DATA
162// ------------------------------------------------------------------------------------------------
163
164/// The memory address at which the chain data section begins
165pub const PARTIAL_BLOCKCHAIN_PTR: MemoryAddress = 1200;
166
167/// The memory address at which the total number of leaves in the partial blockchain is stored
168pub const PARTIAL_BLOCKCHAIN_NUM_LEAVES_PTR: MemoryAddress = 1200;
169
170/// The memory address at which the partial blockchain peaks are stored
171pub const PARTIAL_BLOCKCHAIN_PEAKS_PTR: MemoryAddress = 1204;
172
173// KERNEL DATA
174// ------------------------------------------------------------------------------------------------
175
176/// The memory address at which the number of the procedures of the selected kernel is stored.
177pub const NUM_KERNEL_PROCEDURES_PTR: MemoryAddress = 1600;
178
179/// The memory address at which the section, where the hashes of the kernel procedures are stored,
180/// begins
181pub const KERNEL_PROCEDURES_PTR: MemoryAddress = 1604;
182
183// ACCOUNT DATA
184// ------------------------------------------------------------------------------------------------
185
186/// The size of the memory segment allocated to core account data (excluding new code commitment)
187pub const ACCT_DATA_MEM_SIZE: MemSize = 16;
188
189/// The memory address at which the native account is stored.
190pub const NATIVE_ACCOUNT_DATA_PTR: MemoryAddress = 8192;
191
192/// The length of the memory interval that the account data occupies.
193pub const ACCOUNT_DATA_LENGTH: MemSize = 8192;
194
195/// The offset at which the account ID and nonce are stored relative to the start of
196/// the account data segment.
197pub const ACCT_ID_AND_NONCE_OFFSET: MemoryOffset = 0;
198
199/// The memory address at which the account ID and nonce are stored in the native account.
200pub const NATIVE_ACCT_ID_AND_NONCE_PTR: MemoryAddress =
201 NATIVE_ACCOUNT_DATA_PTR + ACCT_ID_AND_NONCE_OFFSET;
202
203/// The index of the account ID within the account ID and nonce data.
204pub const ACCT_ID_SUFFIX_IDX: DataIndex = 0;
205pub const ACCT_ID_PREFIX_IDX: DataIndex = 1;
206
207/// The index of the account nonce within the account ID and nonce data.
208pub const ACCT_NONCE_IDX: DataIndex = 3;
209
210/// The offset at which the account vault root is stored relative to the start of the account
211/// data segment.
212pub const ACCT_VAULT_ROOT_OFFSET: MemoryOffset = 4;
213
214/// The memory address at which the account vault root is stored in the native account.
215pub const NATIVE_ACCT_VAULT_ROOT_PTR: MemoryAddress =
216 NATIVE_ACCOUNT_DATA_PTR + ACCT_VAULT_ROOT_OFFSET;
217
218/// The offset at which the account storage commitment is stored relative to the start of the
219/// account data segment.
220pub const ACCT_STORAGE_COMMITMENT_OFFSET: MemoryOffset = 8;
221
222/// The memory address at which the account storage commitment is stored in the native account.
223pub const NATIVE_ACCT_STORAGE_COMMITMENT_PTR: MemoryAddress =
224 NATIVE_ACCOUNT_DATA_PTR + ACCT_STORAGE_COMMITMENT_OFFSET;
225
226/// The offset at which the account code commitment is stored relative to the start of the account
227/// data segment.
228pub const ACCT_CODE_COMMITMENT_OFFSET: MemoryOffset = 12;
229
230/// The memory address at which the account code commitment is stored in the native account.
231pub const NATIVE_ACCT_CODE_COMMITMENT_PTR: MemoryAddress =
232 NATIVE_ACCOUNT_DATA_PTR + ACCT_CODE_COMMITMENT_OFFSET;
233
234/// The offset at which the number of procedures contained in the account code is stored relative to
235/// the start of the account data segment.
236pub const NUM_ACCT_PROCEDURES_OFFSET: MemoryAddress = 28;
237
238/// The memory address at which the number of procedures contained in the account code is stored in
239/// the native account.
240pub const NATIVE_NUM_ACCT_PROCEDURES_PTR: MemoryAddress =
241 NATIVE_ACCOUNT_DATA_PTR + NUM_ACCT_PROCEDURES_OFFSET;
242
243/// The offset at which the account procedures section begins relative to the start of the account
244/// data segment.
245pub const ACCT_PROCEDURES_SECTION_OFFSET: MemoryAddress = 32;
246
247/// The memory address at which the account procedures section begins in the native account.
248pub const NATIVE_ACCT_PROCEDURES_SECTION_PTR: MemoryAddress =
249 NATIVE_ACCOUNT_DATA_PTR + ACCT_PROCEDURES_SECTION_OFFSET;
250
251/// The offset at which the number of storage slots contained in the account storage is stored
252/// relative to the start of the account data segment.
253pub const NUM_ACCT_STORAGE_SLOTS_OFFSET: MemoryAddress = 2084;
254
255/// The memory address at which number of storage slots contained in the account storage is stored
256/// in the native account.
257pub const NATIVE_NUM_ACCT_STORAGE_SLOTS_PTR: MemoryAddress =
258 NATIVE_ACCOUNT_DATA_PTR + NUM_ACCT_STORAGE_SLOTS_OFFSET;
259
260/// The offset at which the account storage slots section begins relative to the start of the
261/// account data segment.
262pub const ACCT_STORAGE_SLOTS_SECTION_OFFSET: MemoryAddress = 2088;
263
264/// The memory address at which the account storage slots section begins in the native account.
265pub const NATIVE_ACCT_STORAGE_SLOTS_SECTION_PTR: MemoryAddress =
266 NATIVE_ACCOUNT_DATA_PTR + ACCT_STORAGE_SLOTS_SECTION_OFFSET;
267
268// NOTES DATA
269// ================================================================================================
270
271/// The size of the memory segment allocated to each note.
272pub const NOTE_MEM_SIZE: MemoryAddress = 2048;
273
274#[allow(clippy::empty_line_after_outer_attr)]
275#[rustfmt::skip]
276// INPUT NOTES DATA
277// ------------------------------------------------------------------------------------------------
278// Inputs note section contains data of all notes consumed by a transaction. The section starts at
279// memory offset 4_194_304 with a word containing the total number of input notes and is followed
280// by note nullifiers and note data like so:
281//
282// ┌─────────┬───────────┬───────────┬─────┬───────────┬─────────┬────────┬────────┬───────┬────────┐
283// │ NUM │ NOTE 0 │ NOTE 1 │ ... │ NOTE n │ PADDING │ NOTE 0 │ NOTE 1 │ ... │ NOTE n │
284// │ NOTES │ NULLIFIER │ NULLIFIER │ │ NULLIFIER │ │ DATA │ DATA │ │ DATA │
285// └─────────┴───────────┴───────────┴─────┴───────────┴─────────┴────────┴────────┴───────┴────────┘
286// 4_194_304 4_194_308 4_194_312 4_194_304+4(n+1) 4_259_840 +2048 +4096 +2048(n+1)
287//
288// Each nullifier occupies a single word. A data section for each note consists of exactly 512
289// words and is laid out like so:
290//
291// ┌──────┬────────┬────────┬────────┬────────┬──────┬───────┬────────┬────────┬───────┬─────┬───────┬─────────┬
292// │ NOTE │ SERIAL │ SCRIPT │ INPUTS │ ASSETS │ META │ NOTE │ NUM │ NUM │ ASSET │ ... │ ASSET │ PADDING │
293// │ ID │ NUM │ ROOT │ HASH │ HASH │ DATA │ ARGS │ INPUTS │ ASSETS │ 0 │ │ n │ │
294// ├──────┼────────┼────────┼────────┼────────┼──────┼───────┼────────┼────────┼───────┼─────┼───────┼─────────┤
295// 0 4 8 12 16 20 24 28 32 36 + 4n
296//
297// - NUM_INPUTS is encoded as [num_inputs, 0, 0, 0].
298// - NUM_ASSETS is encoded as [num_assets, 0, 0, 0].
299// - INPUTS_COMMITMENT is the key to look up note inputs in the advice map.
300// - ASSETS_HASH is the key to look up note assets in the advice map.
301
302/// The memory address at which the input note section begins.
303pub const INPUT_NOTE_SECTION_PTR: MemoryAddress = 4_194_304;
304
305/// The memory address at which the nullifier section of the input notes begins.
306pub const INPUT_NOTE_NULLIFIER_SECTION_PTR: MemoryAddress = 4_194_308;
307
308/// The memory address at which the input note data section begins.
309pub const INPUT_NOTE_DATA_SECTION_OFFSET: MemoryAddress = 4_259_840;
310
311/// The memory address at which the number of input notes is stored.
312pub const NUM_INPUT_NOTES_PTR: MemoryAddress = INPUT_NOTE_SECTION_PTR;
313
314/// The offsets at which data of an input note is stored relative to the start of its data segment.
315pub const INPUT_NOTE_ID_OFFSET: MemoryOffset = 0;
316pub const INPUT_NOTE_SERIAL_NUM_OFFSET: MemoryOffset = 4;
317pub const INPUT_NOTE_SCRIPT_ROOT_OFFSET: MemoryOffset = 8;
318pub const INPUT_NOTE_INPUTS_COMMITMENT_OFFSET: MemoryOffset = 12;
319pub const INPUT_NOTE_ASSETS_HASH_OFFSET: MemoryOffset = 16;
320pub const INPUT_NOTE_METADATA_OFFSET: MemoryOffset = 20;
321pub const INPUT_NOTE_ARGS_OFFSET: MemoryOffset = 24;
322pub const INPUT_NOTE_NUM_INPUTS_OFFSET: MemoryOffset = 28;
323pub const INPUT_NOTE_NUM_ASSETS_OFFSET: MemoryOffset = 32;
324pub const INPUT_NOTE_ASSETS_OFFSET: MemoryOffset = 36;
325
326// OUTPUT NOTES DATA
327// ------------------------------------------------------------------------------------------------
328// Output notes section contains data of all notes produced by a transaction. The section starts at
329// memory offset 16_777_216 with each note data laid out one after another in 512 word increments.
330//
331// ┌─────────────┬─────────────┬───────────────┬─────────────┐
332// │ NOTE 0 DATA │ NOTE 1 DATA │ ... │ NOTE n DATA │
333// └─────────────┴─────────────┴───────────────┴─────────────┘
334// 16_777_216 +2048 +4096 +2048n
335//
336// The total number of output notes for a transaction is stored in the bookkeeping section of the
337// memory. Data section of each note is laid out like so:
338//
339// ┌─────────┬──────────┬───────────┬─────────────┬────────────┬─────────┬─────┬─────────┬─────────┐
340// │ NOTE ID │ METADATA │ RECIPIENT │ ASSETS HASH │ NUM ASSETS │ ASSET 0 │ ... │ ASSET n │ PADDING │
341// ├─────────┼──────────┼───────────┼─────────────┼────────────┼─────────┼─────┼─────────┼─────────┤
342// 0 1 2 3 4 5 5 + n
343//
344// Even though NUM_ASSETS takes up a whole word, the actual value of this variable is stored in the
345// first element of the word.
346
347/// The memory address at which the output notes section begins.
348pub const OUTPUT_NOTE_SECTION_OFFSET: MemoryOffset = 16_777_216;
349
350/// The size of the core output note data segment.
351pub const OUTPUT_NOTE_CORE_DATA_SIZE: MemSize = 16;
352
353/// The offsets at which data of an output note is stored relative to the start of its data segment.
354pub const OUTPUT_NOTE_ID_OFFSET: MemoryOffset = 0;
355pub const OUTPUT_NOTE_METADATA_OFFSET: MemoryOffset = 4;
356pub const OUTPUT_NOTE_RECIPIENT_OFFSET: MemoryOffset = 8;
357pub const OUTPUT_NOTE_ASSET_COMMITMENT_OFFSET: MemoryOffset = 12;
358pub const OUTPUT_NOTE_NUM_ASSETS_OFFSET: MemoryOffset = 16;
359pub const OUTPUT_NOTE_ASSETS_OFFSET: MemoryOffset = 20;