miden_protocol/transaction/kernel/

memory.rs

use miden_core::program::KernelDescriptor;

use crate::WORD_SIZE;
// TYPE ALIASES
// ================================================================================================
use crate::account::AccountHeader;

pub type MemoryAddress = u32;
pub type MemoryOffset = u32;
pub type DataIndex = usize;
pub type MemSize = usize;
pub type StorageSlot = u8;

// PUBLIC CONSTANTS
// ================================================================================================

// General layout
//
// | Section            | Start address | Size in elements | Comment                                     |
// | ------------------ | ------------- | ---------------- | ------------------------------------------- |
// | Kernel procs       | 0             | 1_024            | 255 procedures, 4 elements each + num_procs |
// | Bookkeeping        | 1_200         | 85               |                                             |
// | Global inputs      | 1_600         | 40               |                                             |
// | Block header       | 2_000         | 44               |                                             |
// | Protocol config    | 2_200         | 24               |                                             |
// | Partial blockchain | 2_400         | 132              |                                             |
// | Accounts data      | 8_192         | 524_288          | 64 accounts max, 8192 elements each         |
// | Account delta      | 532_480       | 264              | fungible + non-fungible ptr + 256 patches   |
// | Account upgrade    | 532_744       | 8                | code + storage upgrade commitment           |
// | Input notes        | 4_194_304     | 1_114_112        | nullifiers data segment (2^16 elements)     |
// |                    |               |                  | + 1024 input notes max, 1024 elements each  |
// | Output notes       | 16_777_216    | 1_048_576        | 1024 output notes max, 1024 elements each   |
// | Link Map Memory    | 33_554_432    | 33_554_432       | Enough for 2_097_151 key-value pairs        |

// Relative layout of one account
//
// | Section            | Start address | Size in elements | Comment                                |
// | ------------------ | ------------- | ---------------- | -------------------------------------- |
// | Metadata           | 0             | 4                | version + nonce + account ID           |
// | Vault root         | 4             | 4                |                                        |
// | Storage commitment | 8             | 4                |                                        |
// | Code commitment    | 12            | 4                |                                        |
// | Padding            | 16            | 12               |                                        |
// | Num procedures     | 28            | 4                |                                        |
// | Procedures roots   | 32            | 1_024            | 256 procedures max, 4 elements each    |
// | Padding            | 1_056         | 4                |                                        |
// | Proc tracking      | 1_060         | 256              | 256 procedures max, 1 element each     |
// | Num storage slots  | 1_316         | 4                |                                        |
// | Initial slot info  | 1_320         | 2_040            | Only initialized on the native account |
// | Active slot info   | 3_360         | 2_040            | 255 slots max, 8 elements each         |
// | Padding            | 5_400         | 2_792            |                                        |
//
// Storage slots are laid out as [[0, slot_type, slot_id_suffix, slot_id_prefix], SLOT_VALUE].

// Relative layout of the native account's delta.
//
// For now each Storage Map pointer (a link map ptr) occupies a single element.
//
// | Section                      | Start address | Size in elements | Comment                      |
// | ---------------------------- | ------------- | ---------------- | ---------------------------- |
// | Fungible Asset Delta Ptr     | 0             | 4                |                              |
// | Non-Fungible Asset Delta Ptr | 4             | 4                |                              |
// | Storage Map Patch Ptrs       | 8             | 256              | Max 255 storage map patches  |

// KERNEL DATA
// ------------------------------------------------------------------------------------------------

/// The procedure roots of the kernel procedures.
///
/// Placed at address 0 so that multiple kernels can share the same dispatcher procedure.
pub const KERNEL_PROCEDURES_PTR: MemoryAddress = 0;

/// The maximum number of procedures which the transaction kernel can have.
pub const MAX_KERNEL_PROCEDURES: usize = KernelDescriptor::MAX_NUM_PROCEDURES;

/// The memory address at which the number of the kernel procedures is stored.
pub const NUM_KERNEL_PROCEDURES_PTR: MemoryAddress =
    MAX_KERNEL_PROCEDURES as MemoryAddress * WORD_SIZE as MemoryAddress;

// BOOKKEEPING
// ------------------------------------------------------------------------------------------------

/// The memory address at which a pointer to the currently active input note is stored.
pub const ACTIVE_INPUT_NOTE_PTR: MemoryAddress = 1200;

/// The memory address at which the number of output notes is stored.
pub const NUM_OUTPUT_NOTES_PTR: MemoryAddress = 1201;

/// The memory address at which the transaction expiration block number is stored.
pub const TX_EXPIRATION_BLOCK_NUM_PTR: MemoryAddress = 1202;

/// The memory address at which the dirty flag of the storage commitment of the native account is
/// stored.
///
/// This binary flag specifies whether the commitment is outdated: it holds 1 if some changes were
/// made to the account storage since the last re-computation, and 0 otherwise.
pub const NATIVE_ACCT_STORAGE_COMMITMENT_DIRTY_FLAG_PTR: MemoryAddress = 1203;

/// The memory address at which the input vault root is stored.
pub const INPUT_VAULT_ROOT_PTR: MemoryAddress = 1204;

/// The memory address at which the output vault root is stored.
pub const OUTPUT_VAULT_ROOT_PTR: MemoryAddress = 1208;

// Pointer to the suffix and prefix of the ID of the foreign account which will be loaded during the
// upcoming FPI call. This ID is updated during the `prepare_fpi_call` kernel procedure.
pub const UPCOMING_FOREIGN_ACCOUNT_PREFIX_PTR: MemoryAddress = 1212;
pub const UPCOMING_FOREIGN_ACCOUNT_SUFFIX_PTR: MemoryAddress =
    UPCOMING_FOREIGN_ACCOUNT_PREFIX_PTR + 1;

// Pointer to the 16th input value of the foreign procedure which will be loaded during the upcoming
// FPI call. This "buffer" value helps to work around the 15 value limitation of the
// `exec_kernel_proc` kernel procedure, so that any account procedure, even if it has 16 input
// values, could be executed as foreign.
pub const UPCOMING_FOREIGN_PROC_INPUT_VALUE_15_PTR: MemoryAddress = 1214;

// The memory address at which the flag indicating that the epilogue is running the account's
// authentication procedure is stored.
pub const EPILOGUE_AUTH_IN_PROGRESS_FLAG_PTR: MemoryAddress = 1215;

// Pointer to the root of the foreign procedure which will be executed during the upcoming FPI call.
// This root is updated during the `prepare_fpi_call` kernel procedure.
pub const UPCOMING_FOREIGN_PROCEDURE_PTR: MemoryAddress = 1216;

/// The memory address at which the pointer to the stack element containing the pointer to the
/// active account data is stored.
///
/// The stack starts at the address `1221`. Stack has a length of `64` elements meaning that the
/// maximum depth of FPI calls is `63` — the first slot is always occupied by the native account
/// data pointer.
///
/// ```text
/// ┌───────────────┬────────────────┬───────────────────┬─────┬────────────────────┐
/// │ STACK TOP PTR │ NATIVE ACCOUNT │ FOREIGN ACCOUNT 1 │ ... │ FOREIGN ACCOUNT 63 │
/// ├───────────────┼────────────────┼───────────────────┼─────┼────────────────────┤
///       1220             1221              1222                      1284
/// ```
pub const ACCOUNT_STACK_TOP_PTR: MemoryAddress = 1220;

// GLOBAL INPUTS
// ------------------------------------------------------------------------------------------------

/// The memory address at which the global inputs section begins.
pub const GLOBAL_INPUTS_SECTION_OFFSET: MemoryOffset = 1600;

/// The memory address at which the commitment of the transaction's reference block is stored.
pub const BLOCK_COMMITMENT_PTR: MemoryAddress = 1600;

/// The memory address at which the native account ID suffix provided as a global transaction input
/// is stored.
pub const GLOBAL_ACCOUNT_ID_SUFFIX_PTR: MemoryAddress = 1604;
/// The memory address at which the native account ID prefix provided as a global transaction input
/// is stored.
pub const GLOBAL_ACCOUNT_ID_PREFIX_PTR: MemoryAddress = GLOBAL_ACCOUNT_ID_SUFFIX_PTR + 1;

/// The memory address at which the initial account commitment is stored.
pub const INIT_ACCT_COMMITMENT_PTR: MemoryAddress = 1608;

/// The memory address at which the initial nonce is stored.
pub const INIT_NONCE_PTR: MemoryAddress = 1612;

/// The memory address at which the initial vault root of the native account is stored.
pub const INIT_NATIVE_ACCT_VAULT_ROOT_PTR: MemoryAddress = 1616;

/// The memory address at which the initial storage commitment of the native account is stored.
pub const INIT_NATIVE_ACCT_STORAGE_COMMITMENT_PTR: MemoryAddress = 1620;

/// The memory address at which the input notes commitment is stored.
pub const INPUT_NOTES_COMMITMENT_PTR: MemoryAddress = 1624;

/// The memory address at which the transaction script mast root is store
pub const TX_SCRIPT_ROOT_PTR: MemoryAddress = 1628;

/// The memory address at which the transaction script arguments are stored.
pub const TX_SCRIPT_ARGS: MemoryAddress = 1632;

/// The memory address at which the key of the auth procedure arguments is stored.
pub const AUTH_ARGS_PTR: MemoryAddress = 1636;

// BLOCK DATA
// ------------------------------------------------------------------------------------------------

/// The memory address at which the block data section begins, holding the block metadata.
///
/// The section holds the reference block header, see
/// [`BlockHeader::to_elements`](crate::block::BlockHeader::to_elements) for its layout.
pub const BLOCK_METADATA_PTR: MemoryAddress = 2000;

/// The index of the block header version within the block metadata.
pub const BLOCK_VERSION_IDX: DataIndex = 0;

/// The index of the block number within the block metadata.
pub const BLOCK_NUMBER_IDX: DataIndex = 1;

/// The index of the timestamp within the block metadata.
pub const TIMESTAMP_IDX: DataIndex = 2;

/// The memory address at which the previous block commitment is stored.
pub const PREV_BLOCK_COMMITMENT_PTR: MemoryAddress = 2004;

/// The memory address at which the chain commitment is stored.
pub const CHAIN_COMMITMENT_PTR: MemoryAddress = 2008;

/// The memory address at which the state root is stored.
pub const ACCT_DB_ROOT_PTR: MemoryAddress = 2012;

/// The memory address at which the nullifier db root is store.
pub const NULLIFIER_DB_ROOT_PTR: MemoryAddress = 2016;

/// The memory address at which the TX commitment is stored.
pub const TX_COMMITMENT_PTR: MemoryAddress = 2020;

/// The memory address at which the protocol config commitment is stored.
pub const PROTOCOL_CONFIG_COMMITMENT_PTR: MemoryAddress = 2024;

/// The memory address at which the validator config commitment is stored.
pub const VALIDATOR_CONFIG_COMMITMENT_PTR: MemoryAddress = 2028;

/// The memory address at which the next protocol config commitment is stored.
pub const NEXT_PROTOCOL_CONFIG_COMMITMENT_PTR: MemoryAddress = 2032;

/// The memory address at which the fee parameters are stored.
pub const FEE_PARAMETERS_PTR: MemoryAddress = 2036;

/// The index of the verification base fee within the block fee parameters.
pub const VERIFICATION_BASE_FEE_IDX: DataIndex = 0;

/// The memory address at which the note root is stored.
pub const NOTE_ROOT_PTR: MemoryAddress = 2040;

// PROTOCOL CONFIG
// ------------------------------------------------------------------------------------------------

/// The memory address at which the protocol config section begins.
pub const PROTOCOL_CONFIG_SECTION_OFFSET: MemoryOffset = 2200;

/// The memory address at which the fee asset ID is stored.
pub const FEE_ASSET_ID_PTR: MemoryAddress = 2200;

/// The memory address at which the transaction kernel config commitment is stored.
pub const TX_KERNEL_CONFIG_COMMITMENT_PTR: MemoryAddress = 2204;

/// The memory address at which the batch kernel config commitment is stored.
pub const BATCH_KERNEL_CONFIG_COMMITMENT_PTR: MemoryAddress = 2208;

/// The memory address at which the block kernel config commitment is stored.
pub const BLOCK_KERNEL_CONFIG_COMMITMENT_PTR: MemoryAddress = 2212;

/// The memory address at which the proof verification config commitment is stored.
pub const PROOF_VERIFICATION_COMMITMENT_PTR: MemoryAddress = 2216;

// CHAIN DATA
// ------------------------------------------------------------------------------------------------

/// The memory address at which the chain data section begins.
pub const PARTIAL_BLOCKCHAIN_PTR: MemoryAddress = 2400;

/// The memory address at which the total number of leaves in the partial blockchain is stored.
pub const PARTIAL_BLOCKCHAIN_NUM_LEAVES_PTR: MemoryAddress = 2400;

/// The memory address at which the partial blockchain peaks are stored.
pub const PARTIAL_BLOCKCHAIN_PEAKS_PTR: MemoryAddress = 2404;

// ACCOUNT DATA
// ------------------------------------------------------------------------------------------------

/// The memory address at which the native account is stored.
pub const NATIVE_ACCOUNT_DATA_PTR: MemoryAddress = 8192;

/// The length of the memory interval that the account data occupies.
pub const ACCOUNT_DATA_LENGTH: MemSize = 8192;

/// The offset at which the account metadata word is stored relative to the start of the account
/// data segment.
pub const ACCT_METADATA_OFFSET: MemoryOffset = 0;

/// The memory address at which the account metadata word is stored in the native account.
pub const NATIVE_ACCT_METADATA_PTR: MemoryAddress = NATIVE_ACCOUNT_DATA_PTR + ACCT_METADATA_OFFSET;

/// The index of the account version within the account metadata word.
pub const ACCT_VERSION_IDX: DataIndex = AccountHeader::VERSION_IDX;

/// The index of the account nonce within the account metadata word.
pub const ACCT_NONCE_IDX: DataIndex = AccountHeader::NONCE_IDX;

/// The index of the account ID within the account metadata word.
pub const ACCT_ID_SUFFIX_IDX: DataIndex = AccountHeader::ID_SUFFIX_IDX;
pub const ACCT_ID_PREFIX_IDX: DataIndex = AccountHeader::ID_PREFIX_IDX;

/// The offset at which the account vault root is stored relative to the start of the account
/// data segment.
pub const ACCT_VAULT_ROOT_OFFSET: MemoryOffset = 4;

/// The memory address at which the account vault root is stored in the native account.
pub const NATIVE_ACCT_VAULT_ROOT_PTR: MemoryAddress =
    NATIVE_ACCOUNT_DATA_PTR + ACCT_VAULT_ROOT_OFFSET;

/// The offset at which the account storage commitment is stored relative to the start of the
/// account data segment.
pub const ACCT_STORAGE_COMMITMENT_OFFSET: MemoryOffset = 8;

/// The memory address at which the account storage commitment is stored in the native account.
pub const NATIVE_ACCT_STORAGE_COMMITMENT_PTR: MemoryAddress =
    NATIVE_ACCOUNT_DATA_PTR + ACCT_STORAGE_COMMITMENT_OFFSET;

/// The offset at which the account code commitment is stored relative to the start of the account
/// data segment.
pub const ACCT_CODE_COMMITMENT_OFFSET: MemoryOffset = 12;

/// The memory address at which the account code commitment is stored in the native account.
pub const NATIVE_ACCT_CODE_COMMITMENT_PTR: MemoryAddress =
    NATIVE_ACCOUNT_DATA_PTR + ACCT_CODE_COMMITMENT_OFFSET;

/// The offset at which the number of procedures contained in the account code is stored relative to
/// the start of the account data segment.
pub const ACCT_NUM_PROCEDURES_OFFSET: MemoryAddress = 28;

/// The memory address at which the number of procedures contained in the account code is stored in
/// the native account.
pub const NATIVE_NUM_ACCT_PROCEDURES_PTR: MemoryAddress =
    NATIVE_ACCOUNT_DATA_PTR + ACCT_NUM_PROCEDURES_OFFSET;

/// The offset at which the account procedures section begins relative to the start of the account
/// data segment.
pub const ACCT_PROCEDURES_SECTION_OFFSET: MemoryAddress = 32;

/// The memory address at which the account procedures section begins in the native account.
pub const NATIVE_ACCT_PROCEDURES_SECTION_PTR: MemoryAddress =
    NATIVE_ACCOUNT_DATA_PTR + ACCT_PROCEDURES_SECTION_OFFSET;

/// The offset at which the account procedures call tracking section begins relative to the start of
/// the account data segment.
pub const ACCT_PROCEDURES_CALL_TRACKING_OFFSET: MemoryAddress = 1060;

/// The memory address at which the account procedures call tracking section begins in the native
/// account.
pub const NATIVE_ACCT_PROCEDURES_CALL_TRACKING_PTR: MemoryAddress =
    NATIVE_ACCOUNT_DATA_PTR + ACCT_PROCEDURES_CALL_TRACKING_OFFSET;

/// The offset at which the number of storage slots contained in the account storage is stored
/// relative to the start of the account data segment.
pub const ACCT_NUM_STORAGE_SLOTS_OFFSET: MemoryAddress = 1316;

/// The memory address at which number of storage slots contained in the account storage is stored
/// in the native account.
pub const NATIVE_NUM_ACCT_STORAGE_SLOTS_PTR: MemoryAddress =
    NATIVE_ACCOUNT_DATA_PTR + ACCT_NUM_STORAGE_SLOTS_OFFSET;

/// The number of elements that each storage slot takes up in memory.
pub const ACCT_STORAGE_SLOT_NUM_ELEMENTS: u8 = 8;

/// The offset of the slot type in the storage slot.
pub const ACCT_STORAGE_SLOT_TYPE_OFFSET: u8 = 1;

/// The offset of the slot's ID suffix in the storage slot.
pub const ACCT_STORAGE_SLOT_ID_SUFFIX_OFFSET: u8 = 2;

/// The offset of the slot's ID prefix in the storage slot.
pub const ACCT_STORAGE_SLOT_ID_PREFIX_OFFSET: u8 = 3;

/// The offset of the slot value in the storage slot.
pub const ACCT_STORAGE_SLOT_VALUE_OFFSET: u8 = 4;

/// The offset at which the account's active storage slots section begins relative to the start of
/// the account data segment.
///
/// This section contains the current values of the account storage slots.
pub const ACCT_ACTIVE_STORAGE_SLOTS_SECTION_OFFSET: MemoryAddress = 3360;

/// The memory address at which the account's active storage slots section begins in the native
/// account.
pub const NATIVE_ACCT_STORAGE_SLOTS_SECTION_PTR: MemoryAddress =
    NATIVE_ACCOUNT_DATA_PTR + ACCT_ACTIVE_STORAGE_SLOTS_SECTION_OFFSET;

// UPGRADE COMMITMENTS
// ------------------------------------------------------------------------------------------------

/// The memory address at which the native account code upgrade commitment is stored.
pub const CODE_UPGRADE_COMMITMENT_PTR: MemoryAddress = 532_744;

/// The memory address at which the native account storage upgrade commitment is stored.
pub const STORAGE_UPGRADE_COMMITMENT_PTR: MemoryAddress = 532_748;

// NOTES DATA
// ================================================================================================

/// The size of the memory segment allocated to each note.
pub const NOTE_MEM_SIZE: MemoryAddress = 1024;

#[allow(clippy::empty_line_after_outer_attr)]
#[rustfmt::skip]
// INPUT NOTES DATA
// ------------------------------------------------------------------------------------------------
// Inputs note section contains data of all notes consumed by a transaction. The section starts at
// memory offset 4_194_304 with a word containing the total number of input notes and is followed
// by note nullifiers and note data like so:
//
// ┌──────────┬───────────┬───────────┬─────┬────────────────┬─────────┬──────────┬────────┬───────┬────────┐
// │    NUM   │  NOTE 0   │  NOTE 1   │ ... │     NOTE n     │ PADDING │  NOTE 0  │ NOTE 1 │  ...  │ NOTE n │
// │   NOTES  │ NULLIFIER │ NULLIFIER │     │    NULLIFIER   │         │   DATA   │  DATA  │       │  DATA  │
// ├──────────┼───────────┼───────────┼─────┼────────────────┼─────────┼──────────┼────────┼───────┼────────┤
// 4_194_304  4_194_308   4_194_312         4_194_304+4(n+1)           4_259_840  +1024    +2048   +1024n
//
// Here `n` represents number of input notes.
//
// Each nullifier occupies a single word. A data section for each note consists of exactly 1024
// elements and is laid out like so:
//
// ┌──────────────┬────────┬────────┬────────────┬────────────┬──────────┬─────────────┬───────────┬──────┬
// │ NOTE DETAILS │ SERIAL │ SCRIPT │  STORAGE   │   ASSETS   │ METADATA │ ATTACHMENTS │ RECIPIENT │ NOTE │
// │  COMMITMENT  │  NUM   │  ROOT  │ COMMITMENT │ COMMITMENT │          │  COMMITMENT │           │  ID  │
// ├──────────────┼────────┼────────┼────────────┼────────────┼──────────┼─────────────┼───────────┼──────┼
// 0              4        8        12           16           20         24            28          32
//
// ┬───────┬─────────┬────────┬───────┬─────────┬─────┬────────┬─────────┬─────────┐
// │ NOTE  │ STORAGE │  NUM   │ ASSET │  ASSET  │ ... │ ASSET  │  ASSET  │ PADDING │
// │ ARGS  │ LENGTH  │ ASSETS │ KEY 0 │ VALUE 0 │     │ KEY n  │ VALUE n │         │
// ┼───────┼─────────┼────────┼───────┼─────────┼─────┼────────┼─────────┼─────────┘
// 36      40        44       48      52              48 + 8n  52 + 8n
//
// - NUM_STORAGE_ITEMS is encoded as [num_storage_items, 0, 0, 0].
// - NUM_ASSETS is encoded as [num_assets, 0, 0, 0].
// - NOTE ID is computed and cached by the transaction prologue; asset removals only mutate the
//   assets region and do not invalidate it.
// - STORAGE_COMMITMENT is the key to look up note storage in the advice map.
// - ASSETS_COMMITMENT is the key to look up note assets in the advice map.
//
// Notice that note storage item are not loaded to the memory, only their length. In order to obtain
// the storage values the advice map should be used: they are stored there as
// `STORAGE_COMMITMENT -> STORAGE`.
//
// As opposed to the asset values, storage items are never used in kernel memory, so their presence
// there is unnecessary.

/// The memory address at which the input note section begins.
pub const INPUT_NOTE_SECTION_PTR: MemoryAddress = 4_194_304;

/// The memory address at which the nullifier section of the input notes begins.
pub const INPUT_NOTE_NULLIFIER_SECTION_PTR: MemoryAddress = 4_194_308;

/// The memory address at which the input note data section begins.
pub const INPUT_NOTE_DATA_SECTION_OFFSET: MemoryAddress = 4_259_840;

/// The memory address at which the number of input notes is stored.
pub const NUM_INPUT_NOTES_PTR: MemoryAddress = INPUT_NOTE_SECTION_PTR;

/// The offsets at which data of an input note is stored relative to the start of its data segment.
pub const INPUT_NOTE_DETAILS_COMMITMENT_OFFSET: MemoryOffset = 0;
pub const INPUT_NOTE_SERIAL_NUM_OFFSET: MemoryOffset = 4;
pub const INPUT_NOTE_SCRIPT_ROOT_OFFSET: MemoryOffset = 8;
pub const INPUT_NOTE_STORAGE_COMMITMENT_OFFSET: MemoryOffset = 12;
pub const INPUT_NOTE_ASSETS_COMMITMENT_OFFSET: MemoryOffset = 16;
pub const INPUT_NOTE_METADATA_OFFSET: MemoryOffset = 20;
pub const INPUT_NOTE_ATTACHMENTS_COMMITMENT_OFFSET: MemoryOffset = 24;
pub const INPUT_NOTE_RECIPIENT_OFFSET: MemoryOffset = 28;
pub const INPUT_NOTE_ID_OFFSET: MemoryOffset = 32;
pub const INPUT_NOTE_ARGS_OFFSET: MemoryOffset = 36;
pub const INPUT_NOTE_NUM_STORAGE_ITEMS_OFFSET: MemoryOffset = 40;
pub const INPUT_NOTE_NUM_ASSETS_OFFSET: MemoryOffset = 44;
pub const INPUT_NOTE_ASSETS_OFFSET: MemoryOffset = 48;

#[allow(clippy::empty_line_after_outer_attr)]
#[rustfmt::skip]
// OUTPUT NOTES DATA
// ------------------------------------------------------------------------------------------------
// Output notes section contains data of all notes produced by a transaction. The section starts at
// memory offset 16_777_216 with each note data laid out one after another in 1024 elements chunks.
//
//     ┌─────────────┬─────────────┬───────────────┬─────────────┐
//     │ NOTE 0 DATA │ NOTE 1 DATA │      ...      │ NOTE n DATA │
//     └─────────────┴─────────────┴───────────────┴─────────────┘
// 16_777_216      +1024         +2048           +1024n
//
// The total number of output notes for a transaction is stored in the bookkeeping section of the
// memory. Data section of each note is laid out like so:
//
// | Offset  | Section                                                  |
// | ------- | -------------------------------------------------------- |
// | 0       | NOTE DETAILS COMMITMENT                                  |
// | 4       | METADATA                                                 |
// | 8       | RECIPIENT                                                |
// | 12      | [dirty_flag, sealed_flag, 0, 0]                          |
// | 16      | [num_assets, num_attachments, total_attachment_words, 0] |
// | 20      | ATTACHMENT 0                                             |
// | 24      | ATTACHMENT 1                                             |
// | 28      | ATTACHMENT 2                                             |
// | 32      | ATTACHMENT 3                                             |
// | 36      | ASSETS COMMITMENT                                        |
// | 40 + 8i | ASSET KEY i                                              |
// | 44 + 8i | ASSET VALUE i                                            |
// | 40 + 8n | PADDING                                                  |
//
// Offsets are measured in field elements, where n = num_assets and 0 <= i < n.
//
// The sealed flag starts at zero. Once set to one, asset and attachment mutations are rejected; it is
// excluded from note commitments and serialization.
//
// The DIRTY_FLAG is the binary flag which specifies whether the assets commitment stored in this
// note is outdated. It holds 1 if some changes were made to the note assets since the last
// re-computation, and 0 otherwise.
// It is set to 0 after every recomputation of the assets commitment in the
// `miden::tx_kernel_core::note::compute_output_note_assets_commitment` procedure. It is set to 1 in the
// `miden::tx_kernel_core::output_note::add_asset` procedure after any change was made to the assets data.

/// The memory address at which the output notes section begins.
pub const OUTPUT_NOTE_SECTION_OFFSET: MemoryOffset = 16_777_216;

/// The offsets at which data of an output note is stored relative to the start of its data segment.
pub const OUTPUT_NOTE_DETAILS_COMMITMENT_OFFSET: MemoryOffset = 0;
pub const OUTPUT_NOTE_METADATA_OFFSET: MemoryOffset = 4;
pub const OUTPUT_NOTE_RECIPIENT_OFFSET: MemoryOffset = 8;
pub const OUTPUT_NOTE_DIRTY_FLAG_OFFSET: MemoryOffset = 12;
pub const OUTPUT_NOTE_SEALED_FLAG_OFFSET: MemoryOffset = 13;
pub const OUTPUT_NOTE_NUM_ASSETS_OFFSET: MemoryOffset = 16;
pub const OUTPUT_NOTE_NUM_ATTACHMENTS_OFFSET: MemoryOffset = 17;
pub const OUTPUT_NOTE_TOTAL_ATTACHMENT_WORDS_OFFSET: MemoryOffset = 18;
pub const OUTPUT_NOTE_ATTACHMENT_0_OFFSET: MemoryOffset = 20;
pub const OUTPUT_NOTE_ATTACHMENT_1_OFFSET: MemoryOffset = 24;
pub const OUTPUT_NOTE_ATTACHMENT_2_OFFSET: MemoryOffset = 28;
pub const OUTPUT_NOTE_ATTACHMENT_3_OFFSET: MemoryOffset = 32;
pub const OUTPUT_NOTE_ASSETS_COMMITMENT_OFFSET: MemoryOffset = 36;
pub const OUTPUT_NOTE_ASSETS_OFFSET: MemoryOffset = 40;

// ASSETS
// ------------------------------------------------------------------------------------------------

/// The size of an asset's memory representation.
#[cfg(any(feature = "testing", test))]
pub const ASSET_SIZE: MemoryOffset = 8;

/// The offset of the asset value in an asset's memory representation.
#[cfg(any(feature = "testing", test))]
pub const ASSET_VALUE_OFFSET: MemoryOffset = 4;

// LINK MAP
// ------------------------------------------------------------------------------------------------

/// The inclusive start of the link map dynamic memory region.
pub const LINK_MAP_REGION_START_PTR: MemoryAddress = 33_554_448;

/// The non-inclusive end of the link map dynamic memory region.
pub const LINK_MAP_REGION_END_PTR: MemoryAddress = 67_108_864;

/// [`LINK_MAP_REGION_START_PTR`] + the currently used size stored at this pointer defines the next
/// entry pointer that will be allocated.
pub const LINK_MAP_USED_MEMORY_SIZE: MemoryAddress = 33_554_432;

/// The size of each map entry, i.e. four words.
pub const LINK_MAP_ENTRY_SIZE: MemoryOffset = 16;

const _: () = assert!(
    LINK_MAP_REGION_START_PTR.is_multiple_of(LINK_MAP_ENTRY_SIZE),
    "link map region start ptr should be aligned to entry size"
);

const _: () = assert!(
    (LINK_MAP_REGION_END_PTR - LINK_MAP_REGION_START_PTR).is_multiple_of(LINK_MAP_ENTRY_SIZE),
    "the link map memory range should cleanly contain a multiple of the entry size"
);