@aztec/pxe 5.0.0-private.20260319 → 5.0.0-rc.2

package/dest/contract_function_simulator/oracle/oracle_type_mappings.js

@@ -0,0 +1,1222 @@
+import { CONTRACT_CLASS_LOG_SIZE_IN_FIELDS, FLAT_PUBLIC_LOGS_PAYLOAD_LENGTH, L1_TO_L2_MSG_TREE_HEIGHT, MAX_CONTRACT_CLASS_LOGS_PER_TX, MAX_L2_TO_L1_MSGS_PER_TX, MAX_NOTE_HASHES_PER_TX, MAX_NULLIFIERS_PER_TX, MAX_PRIVATE_LOGS_PER_TX, MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX, NULLIFIER_TREE_HEIGHT, PRIVATE_LOG_CIPHERTEXT_LEN, PRIVATE_LOG_SIZE_IN_FIELDS, PUBLIC_DATA_TREE_HEIGHT } from '@aztec/constants';
+import { BlockNumber } from '@aztec/foundation/branded-types';
+import { padArrayEnd } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { FieldReader } from '@aztec/foundation/serialize';
+import { fromUintArray } from '@aztec/simulator/client';
+import { FunctionSelector, NoteSelector } from '@aztec/stdlib/abi';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { BlockHash } from '@aztec/stdlib/block';
+import { Tag, appTaggingSecretKindFromDeliveryMode } from '@aztec/stdlib/logs';
+import { TxHash } from '@aztec/stdlib/tx';
+import { BoundedVec } from '../noir-structs/bounded_vec.js';
+import { EphemeralArray } from '../noir-structs/ephemeral_array.js';
+import { EventValidationRequest } from '../noir-structs/event_validation_request.js';
+import { logSourceFromField } from '../noir-structs/log_retrieval_request.js';
+import { NoteValidationRequest } from '../noir-structs/note_validation_request.js';
+import { Option } from '../noir-structs/option.js';
+import { resolvedTaggingStrategyFromFields, resolvedTaggingStrategyToFields } from '../noir-structs/resolved_tagging_strategy.js';
+import { packAsHintedNote } from './note_packing_utils.js';
+/**
+ * Asserts that every reader was fully consumed by a deserialization, throwing on leftover fields.
+ */ export function assertReadersConsumed(readers) {
+    readers.forEach((reader, slot)=>{
+        if (!reader.isFinished()) {
+            throw new Error(`Malformed oracle input: ${reader.remainingFields()} unexpected trailing field(s) in slot ${slot}`);
+        }
+    });
+}
+// ─── Scalar Type Mappings ────────────────────────────────────────────────────
+export const FIELD = {
+    serialization: {
+        fn: (v)=>[
+                v
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>reader.readField()
+    },
+    shape: [
+        'scalar'
+    ]
+};
+export const BOOL = {
+    serialization: {
+        fn: (v)=>[
+                new Fr(v ? 1n : 0n)
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>!reader.readField().isZero()
+    },
+    shape: [
+        'scalar'
+    ]
+};
+export const U32 = {
+    serialization: {
+        fn: (v)=>[
+                new Fr(v)
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>{
+            const value = reader.readField().toBigInt();
+            if (value > 0xffffffffn) {
+                throw new Error(`U32 overflow: value ${value} exceeds u32 max (${0xffffffffn})`);
+            }
+            return Number(value);
+        }
+    },
+    shape: [
+        'scalar'
+    ]
+};
+export const BLOCK_NUMBER = {
+    serialization: {
+        fn: (v)=>[
+                new Fr(v)
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>BlockNumber(reader.readField().toNumber())
+    },
+    shape: [
+        'scalar'
+    ]
+};
+/** A u8 byte: serializes to a single Fr; deserializes from a single Fr to a number in [0, 255]. */ export const BYTE = {
+    serialization: {
+        fn: (byte)=>[
+                new Fr(byte)
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>{
+            const value = reader.readField().toBigInt();
+            if (value > 0xffn) {
+                throw new Error(`BYTE overflow: value ${value} exceeds u8 max (255)`);
+            }
+            return Number(value);
+        }
+    },
+    shape: [
+        'scalar'
+    ]
+};
+// Noir passes `MessageDelivery` onchain variants here.
+export const DELIVERY_MODE = {
+    deserialization: {
+        fn: (readers)=>appTaggingSecretKindFromDeliveryMode(BYTE.deserialization.fn(readers))
+    },
+    shape: BYTE.shape
+};
+export const RESOLVED_TAGGING_STRATEGY = {
+    serialization: {
+        fn: (resolved)=>resolvedTaggingStrategyToFields(resolved)
+    },
+    deserialization: {
+        fn: ([kindReader, secretReader])=>resolvedTaggingStrategyFromFields(kindReader.readField().toNumber(), secretReader.readField())
+    },
+    shape: [
+        'scalar',
+        'scalar'
+    ]
+};
+export const BIGINT = {
+    serialization: {
+        fn: (v)=>[
+                new Fr(v)
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>reader.readField().toBigInt()
+    },
+    shape: [
+        'scalar'
+    ]
+};
+/** Reads every field in the slot as a UTF-8 character code. */ export const STR = {
+    serialization: {
+        fn: (str)=>[
+                Array.from(Buffer.from(str, 'utf-8')).map((b)=>new Fr(b))
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>{
+            const chars = [];
+            while(!reader.isFinished()){
+                chars.push(String.fromCharCode(reader.readField().toNumber()));
+            }
+            return chars.join('');
+        }
+    },
+    shape: [
+        'variable'
+    ]
+};
+export const AZTEC_ADDRESS = {
+    serialization: {
+        fn: (v)=>[
+                v.toField()
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>AztecAddress.fromFieldUnsafe(reader.readField())
+    },
+    shape: [
+        'scalar'
+    ]
+};
+export const BLOCK_HASH = {
+    serialization: {
+        fn: (v)=>[
+                new Fr(v.toBuffer())
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>new BlockHash(reader.readField())
+    },
+    shape: [
+        'scalar'
+    ]
+};
+export const FUNCTION_SELECTOR = {
+    serialization: {
+        fn: (v)=>[
+                v.toField()
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>FunctionSelector.fromField(reader.readField())
+    },
+    shape: [
+        'scalar'
+    ]
+};
+export const NOTE_SELECTOR = {
+    serialization: {
+        fn: (v)=>[
+                v.toField()
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>NoteSelector.fromField(reader.readField())
+    },
+    shape: [
+        'scalar'
+    ]
+};
+export const TX_HASH = {
+    serialization: {
+        fn: (v)=>[
+                v.hash
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>TxHash.fromField(reader.readField())
+    },
+    shape: [
+        'scalar'
+    ]
+};
+const TAG = {
+    serialization: {
+        fn: (v)=>[
+                v.value
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>new Tag(reader.readField())
+    },
+    shape: [
+        'scalar'
+    ]
+};
+export const POINT = STRUCT([
+    {
+        name: 'x',
+        type: FIELD
+    },
+    {
+        name: 'y',
+        type: FIELD
+    }
+]);
+const LOG_SOURCE = {
+    serialization: {
+        fn: (v)=>[
+                new Fr(v)
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>logSourceFromField(reader.readField())
+    },
+    shape: [
+        'scalar'
+    ]
+};
+export const ETH_ADDRESS = {
+    serialization: {
+        fn: (v)=>[
+                v.toField()
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>EthAddress.fromField(reader.readField())
+    },
+    shape: [
+        'scalar'
+    ]
+};
+const SLOT_NUMBER = {
+    serialization: {
+        fn: (v)=>[
+                new Fr(v)
+            ]
+    },
+    shape: [
+        'scalar'
+    ]
+};
+const APPEND_ONLY_TREE_SNAPSHOT = STRUCT([
+    {
+        name: 'root',
+        type: FIELD
+    },
+    {
+        name: 'nextAvailableLeafIndex',
+        type: U32
+    }
+]);
+const PARTIAL_STATE_REFERENCE = STRUCT([
+    {
+        name: 'noteHashTree',
+        type: APPEND_ONLY_TREE_SNAPSHOT
+    },
+    {
+        name: 'nullifierTree',
+        type: APPEND_ONLY_TREE_SNAPSHOT
+    },
+    {
+        name: 'publicDataTree',
+        type: APPEND_ONLY_TREE_SNAPSHOT
+    }
+]);
+const STATE_REFERENCE = STRUCT([
+    {
+        name: 'l1ToL2MessageTree',
+        type: APPEND_ONLY_TREE_SNAPSHOT
+    },
+    {
+        name: 'partial',
+        type: PARTIAL_STATE_REFERENCE
+    }
+]);
+const GAS_FEES = STRUCT([
+    {
+        name: 'feePerDaGas',
+        type: BIGINT
+    },
+    {
+        name: 'feePerL2Gas',
+        type: BIGINT
+    }
+]);
+const GLOBAL_VARIABLES = STRUCT([
+    {
+        name: 'chainId',
+        type: FIELD
+    },
+    {
+        name: 'version',
+        type: FIELD
+    },
+    {
+        name: 'blockNumber',
+        type: BLOCK_NUMBER
+    },
+    {
+        name: 'slotNumber',
+        type: SLOT_NUMBER
+    },
+    {
+        name: 'timestamp',
+        type: BIGINT
+    },
+    {
+        name: 'coinbase',
+        type: ETH_ADDRESS
+    },
+    {
+        name: 'feeRecipient',
+        type: AZTEC_ADDRESS
+    },
+    {
+        name: 'gasFees',
+        type: GAS_FEES
+    }
+]);
+export const BLOCK_HEADER = STRUCT([
+    {
+        name: 'lastArchive',
+        type: APPEND_ONLY_TREE_SNAPSHOT
+    },
+    {
+        name: 'state',
+        type: STATE_REFERENCE
+    },
+    {
+        name: 'spongeBlobHash',
+        type: FIELD
+    },
+    {
+        name: 'globalVariables',
+        type: GLOBAL_VARIABLES
+    },
+    {
+        name: 'totalFees',
+        type: FIELD
+    },
+    {
+        name: 'totalManaUsed',
+        type: FIELD
+    }
+]);
+export const KEY_VALIDATION_REQUEST = STRUCT([
+    {
+        name: 'pkMHash',
+        type: FIELD
+    },
+    {
+        name: 'skApp',
+        type: FIELD
+    }
+]);
+const PUBLIC_KEYS = STRUCT([
+    {
+        name: 'npkMHash',
+        type: FIELD
+    },
+    {
+        name: 'ivpkM',
+        type: POINT
+    },
+    {
+        name: 'ovpkMHash',
+        type: FIELD
+    },
+    {
+        name: 'tpkMHash',
+        type: FIELD
+    },
+    {
+        name: 'mspkMHash',
+        type: FIELD
+    },
+    {
+        name: 'fbpkMHash',
+        type: FIELD
+    }
+]);
+export const CONTRACT_INSTANCE = STRUCT([
+    {
+        name: 'salt',
+        type: FIELD
+    },
+    {
+        name: 'deployer',
+        type: AZTEC_ADDRESS
+    },
+    // Note that the nr side of this struct does not contain the current class, only original
+    {
+        name: 'originalContractClassId',
+        type: FIELD
+    },
+    {
+        name: 'initializationHash',
+        type: FIELD
+    },
+    {
+        name: 'immutablesHash',
+        type: FIELD
+    },
+    {
+        name: 'publicKeys',
+        type: PUBLIC_KEYS
+    }
+]);
+const NULLIFIER_LEAF = STRUCT([
+    {
+        name: 'nullifier',
+        type: FIELD
+    }
+]);
+const NULLIFIER_LEAF_PREIMAGE = STRUCT([
+    {
+        name: 'leaf',
+        type: NULLIFIER_LEAF
+    },
+    {
+        name: 'nextKey',
+        type: FIELD
+    },
+    {
+        name: 'nextIndex',
+        type: BIGINT
+    }
+]);
+export const NULLIFIER_MEMBERSHIP_WITNESS = STRUCT([
+    {
+        name: 'leafPreimage',
+        type: NULLIFIER_LEAF_PREIMAGE
+    },
+    {
+        name: 'index',
+        type: BIGINT
+    },
+    {
+        name: 'siblingPath',
+        type: SIBLING_PATH(NULLIFIER_TREE_HEIGHT)
+    }
+]);
+const PUBLIC_DATA_LEAF = STRUCT([
+    {
+        name: 'slot',
+        type: FIELD
+    },
+    {
+        name: 'value',
+        type: FIELD
+    }
+]);
+const PUBLIC_DATA_LEAF_PREIMAGE = STRUCT([
+    {
+        name: 'leaf',
+        type: PUBLIC_DATA_LEAF
+    },
+    {
+        name: 'nextKey',
+        type: FIELD
+    },
+    {
+        name: 'nextIndex',
+        type: BIGINT
+    }
+]);
+export const PUBLIC_DATA_WITNESS = STRUCT([
+    {
+        name: 'index',
+        type: BIGINT
+    },
+    {
+        name: 'leafPreimage',
+        type: PUBLIC_DATA_LEAF_PREIMAGE
+    },
+    {
+        name: 'siblingPath',
+        type: SIBLING_PATH(PUBLIC_DATA_TREE_HEIGHT)
+    }
+]);
+export const MESSAGE_LOAD_ORACLE_INPUTS = STRUCT([
+    {
+        name: 'index',
+        type: BIGINT
+    },
+    {
+        name: 'siblingPath',
+        type: SIBLING_PATH(L1_TO_L2_MSG_TREE_HEIGHT)
+    }
+]);
+export const UTILITY_CONTEXT = STRUCT([
+    {
+        name: 'blockHeader',
+        type: BLOCK_HEADER
+    },
+    {
+        name: 'contractAddress',
+        type: AZTEC_ADDRESS
+    },
+    {
+        name: 'msgSender',
+        type: AZTEC_ADDRESS
+    }
+]);
+export const CALL_PRIVATE_RESULT = STRUCT([
+    {
+        name: 'endSideEffectCounter',
+        type: FIELD
+    },
+    {
+        name: 'returnsHash',
+        type: FIELD
+    }
+]);
+export const PUBLIC_KEYS_AND_PARTIAL_ADDRESS = STRUCT([
+    {
+        name: 'publicKeys',
+        type: PUBLIC_KEYS
+    },
+    {
+        name: 'partialAddress',
+        type: FIELD
+    }
+]);
+export const CONTRACT_CLASS_LOG = STRUCT([
+    {
+        name: 'contractAddress',
+        type: AZTEC_ADDRESS
+    },
+    {
+        name: 'fields',
+        type: FIXED_ARRAY(FIELD, CONTRACT_CLASS_LOG_SIZE_IN_FIELDS)
+    },
+    {
+        name: 'emittedLength',
+        type: U32
+    }
+]);
+const REVERT_CODE = {
+    serialization: {
+        fn: (rc)=>[
+                rc.toField()
+            ]
+    },
+    shape: [
+        'scalar'
+    ]
+};
+const PUBLIC_DATA_WRITE = STRUCT([
+    {
+        name: 'leafSlot',
+        type: FIELD
+    },
+    {
+        name: 'value',
+        type: FIELD
+    }
+]);
+const PRIVATE_LOG = STRUCT([
+    {
+        name: 'fields',
+        type: FIXED_ARRAY(FIELD, PRIVATE_LOG_SIZE_IN_FIELDS)
+    },
+    {
+        name: 'emittedLength',
+        type: U32
+    }
+]);
+const FLAT_PUBLIC_LOGS = STRUCT([
+    {
+        name: 'length',
+        type: U32
+    },
+    {
+        name: 'payload',
+        type: FIXED_ARRAY(FIELD, FLAT_PUBLIC_LOGS_PAYLOAD_LENGTH)
+    }
+]);
+const CONTRACT_CLASS_LOG_ENTRY = STRUCT([
+    {
+        name: 'fields',
+        type: FIXED_ARRAY(FIELD, CONTRACT_CLASS_LOG_SIZE_IN_FIELDS)
+    },
+    {
+        name: 'emittedLength',
+        type: U32
+    },
+    {
+        name: 'contractAddress',
+        type: AZTEC_ADDRESS
+    }
+]);
+const CONTRACT_CLASS_LOGS = FIXED_ARRAY(CONTRACT_CLASS_LOG_ENTRY, MAX_CONTRACT_CLASS_LOGS_PER_TX);
+export const TX_EFFECT = STRUCT([
+    {
+        name: 'revertCode',
+        type: REVERT_CODE
+    },
+    {
+        name: 'txHash',
+        type: TX_HASH
+    },
+    {
+        name: 'transactionFee',
+        type: FIELD
+    },
+    {
+        name: 'noteHashes',
+        type: FIXED_ARRAY(FIELD, MAX_NOTE_HASHES_PER_TX)
+    },
+    {
+        name: 'nullifiers',
+        type: FIXED_ARRAY(FIELD, MAX_NULLIFIERS_PER_TX)
+    },
+    {
+        name: 'l2ToL1Msgs',
+        type: FIXED_ARRAY(FIELD, MAX_L2_TO_L1_MSGS_PER_TX)
+    },
+    {
+        name: 'publicDataWrites',
+        type: FIXED_ARRAY(PUBLIC_DATA_WRITE, MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX)
+    },
+    {
+        name: 'privateLogs',
+        type: FIXED_ARRAY(PRIVATE_LOG, MAX_PRIVATE_LOGS_PER_TX)
+    },
+    {
+        name: 'publicLogs',
+        type: FLAT_PUBLIC_LOGS
+    },
+    {
+        name: 'contractClassLogs',
+        type: CONTRACT_CLASS_LOGS
+    }
+]);
+export const NOTE = {
+    serialization: {
+        fn: (noteData)=>packAsHintedNote({
+                contractAddress: noteData.contractAddress,
+                owner: noteData.owner,
+                randomness: noteData.randomness,
+                storageSlot: noteData.storageSlot,
+                noteNonce: noteData.noteNonce,
+                isPending: noteData.isPending,
+                note: noteData.note
+            })
+    },
+    // A packed note is the note's (variable-count) field items followed by 6 metadata scalars, emitted as one field
+    // output per element. Its length depends on the note, so it is described as a single variable-width run.
+    shape: [
+        'variable'
+    ]
+};
+export const NOTE_VALIDATION_REQUEST = {
+    deserialization: {
+        fn: ([reader])=>NoteValidationRequest.fromFields(reader)
+    },
+    shape: [
+        'variable'
+    ]
+};
+export const EVENT_VALIDATION_REQUEST = {
+    deserialization: {
+        fn: ([reader])=>EventValidationRequest.fromFields(reader)
+    },
+    shape: [
+        'variable'
+    ]
+};
+export const LOG_RETRIEVAL_REQUEST = STRUCT([
+    {
+        name: 'contractAddress',
+        type: AZTEC_ADDRESS
+    },
+    {
+        name: 'tag',
+        type: TAG
+    },
+    {
+        name: 'source',
+        type: LOG_SOURCE
+    },
+    {
+        name: 'fromBlock',
+        type: OPTION(BLOCK_NUMBER)
+    },
+    {
+        name: 'toBlock',
+        type: OPTION(BLOCK_NUMBER)
+    }
+]);
+export const LOG_RETRIEVAL_RESPONSE = STRUCT([
+    {
+        name: 'logPayload',
+        type: FIXED_BOUNDED_VEC(FIELD, PRIVATE_LOG_CIPHERTEXT_LEN)
+    },
+    {
+        name: 'txHash',
+        type: TX_HASH
+    },
+    {
+        name: 'uniqueNoteHashesInTx',
+        type: FIXED_BOUNDED_VEC(FIELD, MAX_NOTE_HASHES_PER_TX)
+    },
+    {
+        name: 'firstNullifierInTx',
+        type: FIELD
+    }
+]);
+export const MESSAGE_CONTEXT = STRUCT([
+    {
+        name: 'txHash',
+        type: TX_HASH
+    },
+    {
+        name: 'uniqueNoteHashesInTx',
+        type: FIXED_BOUNDED_VEC(FIELD, MAX_NOTE_HASHES_PER_TX)
+    },
+    {
+        name: 'firstNullifierInTx',
+        type: FIELD
+    }
+]);
+export const PENDING_TAGGED_LOG = STRUCT([
+    {
+        name: 'log',
+        type: FIXED_BOUNDED_VEC(FIELD, PRIVATE_LOG_SIZE_IN_FIELDS)
+    },
+    {
+        name: 'context',
+        type: MESSAGE_CONTEXT
+    }
+]);
+// `ResolvedTx.toFields()` packs the whole struct into a single slot: txHash, the uniqueNoteHashesInTx BoundedVec
+// (MAX_NOTE_HASHES_PER_TX storage fields + length), firstNullifierInTx, blockNumber and blockHash.
+export const RESOLVED_TX = {
+    serialization: {
+        fn: (resolved)=>[
+                resolved.toFields()
+            ]
+    },
+    shape: [
+        {
+            len: MAX_NOTE_HASHES_PER_TX + 5
+        }
+    ]
+};
+export const ORIGIN_BLOCK = {
+    serialization: {
+        fn: (ob)=>[
+                new Fr(ob.blockNumber),
+                ob.blockHash
+            ]
+    },
+    deserialization: {
+        fn: ([blockNumberReader, blockHashReader])=>({
+                blockNumber: blockNumberReader.readField().toNumber(),
+                blockHash: blockHashReader.readField()
+            })
+    },
+    shape: [
+        'scalar',
+        'scalar'
+    ]
+};
+// `facts` and `payload` each materialize to a single service-slot id, so a Fact occupies: factTypeId, the payload
+// array slot, and `OPTION(ORIGIN_BLOCK)` (its discriminant plus ORIGIN_BLOCK's two slots).
+export const FACT = {
+    serialization: {
+        fn: (f)=>[
+                f.factTypeId,
+                f.payload.materializeSlot((v)=>FIELD.serialization.fn(v).flat()),
+                ...OPTION(ORIGIN_BLOCK).serialization.fn(f.originBlock)
+            ]
+    },
+    shape: [
+        'scalar',
+        'scalar',
+        'scalar',
+        'scalar',
+        'scalar'
+    ]
+};
+export const FACT_COLLECTION = {
+    serialization: {
+        fn: (c)=>[
+                c.contractAddress.toField(),
+                c.scope.toField(),
+                c.factCollectionTypeId,
+                c.factCollectionId,
+                c.facts.materializeSlot((v)=>FACT.serialization.fn(v).flat())
+            ]
+    },
+    shape: [
+        'scalar',
+        'scalar',
+        'scalar',
+        'scalar',
+        'scalar'
+    ]
+};
+export const PROVIDED_SECRET = {
+    deserialization: {
+        fn: ([reader])=>({
+                secret: reader.readField(),
+                mode: appTaggingSecretKindFromDeliveryMode(BYTE.deserialization.fn([
+                    reader
+                ]))
+            })
+    },
+    shape: [
+        {
+            len: 2
+        }
+    ]
+};
+// ─── Combinator Type Mappings ────────────────────────────────────────────────
+function SIBLING_PATH(height) {
+    return {
+        serialization: {
+            fn: (sp)=>[
+                    sp.toFields()
+                ]
+        },
+        shape: [
+            {
+                len: height
+            }
+        ]
+    };
+}
+export function MEMBERSHIP_WITNESS(height) {
+    return STRUCT([
+        {
+            name: 'leafIndex',
+            type: BIGINT
+        },
+        {
+            name: 'siblingPath',
+            type: FIXED_ARRAY(FIELD, height)
+        }
+    ]);
+}
+export function ARRAY(inner) {
+    return {
+        kind: 'array',
+        inner,
+        serialization: inner.serialization ? {
+            fn: (values)=>[
+                    packElements(inner, values)
+                ]
+        } : undefined,
+        deserialization: inner.deserialization ? {
+            // The whole slot is the array, so read as many elements as its fields hold.
+            fn: ([reader])=>unpackElements(inner, reader, reader.remainingFields() / fieldWidth(inner.shape))
+        } : undefined,
+        // One slot of variable length (all elements flattened into it).
+        shape: [
+            {
+                lenFrom: (size)=>size.length * fieldWidth(inner.shape)
+            }
+        ]
+    };
+}
+/**
+ * Noir's fixed-length array `[T; maxLength]` in one slot: serializes `values` (each flattened via `element`)
+ * zero-padded to exactly `maxLength * elementWidth` fields, and deserializes all `maxLength` elements back. An absent
+ * element is the zero encoding, so the padding is derived from the shape.
+ */ function FIXED_ARRAY(element, maxLength) {
+    const elementWidth = fieldWidth(element.shape);
+    return {
+        serialization: element.serialization ? {
+            fn: (values)=>[
+                    padArrayEnd(packElements(element, values), Fr.ZERO, maxLength * elementWidth)
+                ]
+        } : undefined,
+        deserialization: element.deserialization ? {
+            fn: ([reader])=>unpackElements(element, reader, maxLength)
+        } : undefined,
+        shape: [
+            {
+                len: maxLength * elementWidth
+            }
+        ]
+    };
+}
+/**
+ * Maps Noir's `BoundedVec<T, MaxLen>` ↔ TS `BoundedVec<T>` over 2 slots:
+ *   slot 0 — flat storage, padded/parsed as `maxLength * elementSize` fields
+ *   slot 1 — length scalar (count of actual items)
+ *
+ * Both directions are derived from `element`: bidirectional iff `element` has both serialization and deserialization.
+ *
+ * @example Serializing `BoundedVec.from({ data: [0x41, 0x42], maxLength: 4 })` with `BOUNDED_VEC(BYTE)`:
+ * ```
+ * slot 0: [Fr(0x41), Fr(0x42), Fr(0), Fr(0)]     // data padded to maxLength
+ * slot 1: Fr(2)                                  // actual length
+ * ```
+ */ export function BOUNDED_VEC(inner) {
+    return {
+        kind: 'bounded-vec',
+        inner,
+        serialization: inner.serialization ? {
+            fn: (bv)=>{
+                if (bv.data.length > bv.maxLength) {
+                    throw new Error(`Got ${bv.data.length} items, but maxLength is ${bv.maxLength}`);
+                }
+                // Fixed-width elements take their width from the shape (consistent with deserialization); only a
+                // variable-width element (e.g. a packed note) falls back to the runtime `elementSize` the value carries.
+                const elementWidth = tryFieldWidth(inner.shape) ?? bv.elementSize;
+                const flat = padArrayEnd(packElements(inner, bv.data), Fr.ZERO, bv.maxLength * elementWidth);
+                return [
+                    flat,
+                    new Fr(bv.data.length)
+                ];
+            }
+        } : undefined,
+        deserialization: inner.deserialization ? {
+            fn: ([storageReader, lengthReader])=>{
+                // slot 0 is the padded storage, slot 1 the actual length. Parse only the first `length` elements out of
+                // storage, then drain the trailing zero-padding so the storage reader is fully consumed.
+                const maxLength = storageReader.remainingFields() / fieldWidth(inner.shape);
+                const length = lengthReader.readField().toNumber();
+                const elements = unpackElements(inner, storageReader, length);
+                storageReader.skip(storageReader.remainingFields());
+                return BoundedVec.from({
+                    data: elements,
+                    maxLength
+                });
+            }
+        } : undefined,
+        // slot 0: variable-length storage; slot 1: the length scalar.
+        shape: [
+            {
+                lenFrom: (size)=>size.maxLength * fieldWidth(inner.shape)
+            },
+            'scalar'
+        ]
+    };
+}
+/**
+ * Noir's `BoundedVec<T, MaxLen>` in its padded form (one fixed-width slot): `maxLength * elementWidth` storage fields
+ * (zero-padded) followed by the actual length, with no length prefix, so the width is statically known. Serialize-only.
+ * Throws if the input exceeds `maxLength`.
+ */ function FIXED_BOUNDED_VEC(element, maxLength) {
+    const width = fieldWidth(element.shape);
+    return {
+        serialization: element.serialization ? {
+            fn: (values)=>{
+                if (values.length > maxLength) {
+                    throw new Error(`Got ${values.length} items, but maxLength is ${maxLength}`);
+                }
+                const flat = padArrayEnd(packElements(element, values), Fr.ZERO, maxLength * width);
+                return [
+                    [
+                        ...flat,
+                        new Fr(values.length)
+                    ]
+                ];
+            }
+        } : undefined,
+        shape: [
+            {
+                len: maxLength * width + 1
+            }
+        ]
+    };
+}
+/**
+ * Wraps an inner TypeMapping in Noir-style `Option<T>`, adding a leading discriminant slot.
+ *
+ * For the `None` case, the inner's slots must still be present on the wire as zero-padding (so `Some` and `None` have
+ * identical size). That padding is derived entirely from `inner.shape`.
+ *
+ * @example Serializing `Option.some(AztecAddress.fromFieldUnsafe(Fr(42)))` with `OPTION(AZTEC_ADDRESS)`:
+ * ```
+ * slot 0: Fr(1)    // discriminant: Some
+ * slot 1: Fr(42)   // inner value
+ * ```
+ *
+ * @example Serializing `Option.none()` with `OPTION(AZTEC_ADDRESS)`:
+ * ```
+ * slot 0: Fr(0)    // discriminant: None
+ * slot 1: Fr(0)    // zero-filled from AZTEC_ADDRESS.shape
+ * ```
+ */ export function OPTION(inner) {
+    return {
+        kind: 'option',
+        inner,
+        serialization: inner.serialization ? {
+            fn: (opt)=>opt.isSome() ? [
+                    Fr.ONE,
+                    ...inner.serialization.fn(opt.value)
+                ] : [
+                    Fr.ZERO,
+                    ...zeroSlotsFromShape(inner.shape, opt.size)
+                ]
+        } : undefined,
+        deserialization: inner.deserialization ? {
+            fn: ([discriminant, ...innerReaders])=>{
+                if (discriminant.readField().isZero()) {
+                    // None still carries the inner's zero-padded slots; consume them without parsing, since an inner that
+                    // validates its fields would reject the zeros.
+                    innerReaders.forEach((reader)=>reader.skip(reader.remainingFields()));
+                    return Option.none();
+                }
+                return Option.some(inner.deserialization.fn(innerReaders));
+            }
+        } : undefined,
+        // A leading discriminant slot followed by the inner's slots.
+        shape: [
+            'scalar',
+            ...inner.shape
+        ]
+    };
+}
+/**
+ * A fixed packed uint buffer (Noir `[u8; length]` at `bitSize` 8): one slot of `length` packed uint values ↔ `Buffer`.
+ * `length` is the field count, which equals the byte count at `bitSize` 8.
+ */ export function BUFFER(bitSize, length) {
+    return {
+        serialization: {
+            fn: (buf)=>[
+                    Array.from(buf).map((b)=>new Fr(b))
+                ]
+        },
+        deserialization: {
+            fn: ([reader])=>fromUintArray(reader.readFieldArray(length).map((f)=>f.toString()), bitSize)
+        },
+        shape: [
+            {
+                len: length
+            }
+        ]
+    };
+}
+export function EPHEMERAL_ARRAY(element) {
+    // EphemeralArray.readAll hands each row's flat fields in as a single reader; reconstruct the element's per-slot
+    // readers from its shape, deserialize, and assert the row was fully consumed so a row with trailing fields is
+    // rejected.
+    const rowElement = element.deserialization ? {
+        deserialization: {
+            fn: ([rowReader])=>deserializeElement(element, rowReader.readFieldArray(rowReader.remainingFields()))
+        },
+        // `fn` reads the whole row from one reader, so this is one variable-width slot, not the element's multi-slot
+        // shape.
+        shape: [
+            'variable'
+        ]
+    } : undefined;
+    return {
+        serialization: element.serialization ? {
+            fn: (ea)=>[
+                    ea.materializeSlot((v)=>serializeElement(element, v))
+                ]
+        } : undefined,
+        deserialization: rowElement ? {
+            fn: ([reader])=>EphemeralArray.fromSlot(reader.readField(), rowElement)
+        } : undefined,
+        // A single slot carrying the array's service-slot id.
+        shape: [
+            'scalar'
+        ]
+    };
+}
+/**
+ * A Noir struct: its `shape` and (de)serialization are the concatenation of its fields', so callers never hand-write a
+ * `shape`. `T` is the struct's TS value type and must match the field layout — serialization reads each field by name
+ * off the value, deserialization returns the decoded bag as `T`; convert in the handler, not here, when `T` differs.
+ */ function STRUCT(fields) {
+    return {
+        serialization: fields.every((f)=>f.type.serialization) ? {
+            fn: (value)=>{
+                const props = value;
+                return fields.flatMap((f)=>f.type.serialization.fn(props[f.name]));
+            }
+        } : undefined,
+        deserialization: fields.every((f)=>f.type.deserialization) ? {
+            fn: (readers)=>{
+                const props = {};
+                let slot = 0;
+                for (const f of fields){
+                    const slotCount = f.type.shape.length;
+                    props[f.name] = f.type.deserialization.fn(readers.slice(slot, slot + slotCount));
+                    slot += slotCount;
+                }
+                return props;
+            }
+        } : undefined,
+        shape: fields.flatMap((f)=>f.type.shape)
+    };
+}
+/** Number of InputSlots a deserializable type spans, derived from its {@link TypeMapping.shape}. */ export function slotsOf(mapping) {
+    return mapping.shape.length;
+}
+/** Number of fields a fully-static shape occupies, or `undefined` if any slot is variable-width. */ function tryFieldWidth(shape) {
+    let total = 0;
+    for (const slot of shape){
+        if (slot === 'scalar') {
+            total += 1;
+        } else if (typeof slot === 'object' && 'len' in slot) {
+            total += slot.len;
+        } else {
+            return undefined;
+        }
+    }
+    return total;
+}
+/** Number of fields a fully-static shape occupies. Throws on a variable-width shape, whose field count isn't known. */ function fieldWidth(shape) {
+    const width = tryFieldWidth(shape);
+    if (width === undefined) {
+        throw new Error('Cannot compute a fixed field width for a variable-width shape');
+    }
+    return width;
+}
+/** Reconstructs a value's per-slot readers from a flat run of fields, using its shape (inverse of slot-flattening). */ function splitByShape(fields, shape) {
+    const readers = [];
+    let cursor = 0;
+    shape.forEach((slot, i)=>{
+        if (slot === 'scalar' || typeof slot === 'object' && 'len' in slot) {
+            const width = slot === 'scalar' ? 1 : slot.len;
+            if (cursor + width > fields.length) {
+                throw new Error(`Not enough fields to reconstruct shape: needed ${width}, had ${fields.length - cursor}`);
+            }
+            readers.push(new FieldReader(fields.slice(cursor, cursor + width)));
+            cursor += width;
+        } else {
+            // A variable slot (sized or not) takes whatever remains, so it must be last.
+            if (i !== shape.length - 1) {
+                throw new Error('A variable-width slot must be last to be reconstructed from a flat field array');
+            }
+            readers.push(new FieldReader(fields.slice(cursor)));
+            cursor = fields.length;
+        }
+    });
+    if (cursor !== fields.length) {
+        throw new Error(`Malformed flattened value: ${fields.length - cursor} unexpected trailing field(s)`);
+    }
+    return readers;
+}
+/** Serializes one element to its flat fields. Element must be serializable. */ function serializeElement(element, value) {
+    return element.serialization.fn(value).flat();
+}
+/**
+ * Deserializes one element from its exact flat fields, reconstructing its per-slot readers from its shape and asserting
+ * they are fully consumed (so trailing fields are rejected). Element must be deserializable.
+ */ function deserializeElement(element, fields) {
+    const readers = splitByShape(fields, element.shape);
+    const value = element.deserialization.fn(readers);
+    assertReadersConsumed(readers);
+    return value;
+}
+/** Flattens `values` into one contiguous run of fields by serializing each element. Element must be serializable. */ function packElements(element, values) {
+    return values.flatMap((v)=>serializeElement(element, v));
+}
+/**
+ * Reads `count` fixed-width elements out of a packed run (the inverse of {@link packElements}). Element must be
+ * deserializable.
+ */ function unpackElements(element, reader, count) {
+    const elementWidth = fieldWidth(element.shape);
+    return Array.from({
+        length: count
+    }, ()=>deserializeElement(element, reader.readFieldArray(elementWidth)));
+}
+/** Builds the zero-filled slots for a `None`, matching a `Some`'s wire shape (variable slots sized from `size`). */ function zeroSlotsFromShape(shape, size) {
+    return shape.map((slot)=>{
+        if (slot === 'scalar') {
+            return Fr.ZERO;
+        }
+        if (slot === 'variable') {
+            throw new Error('Cannot zero-fill an unsized variable-width slot');
+        }
+        if ('len' in slot) {
+            return Array(slot.len).fill(Fr.ZERO);
+        }
+        if (size === undefined) {
+            throw new Error('Serializing Option.none() over a variable-size inner needs a size, e.g. Option.none({ length: n })');
+        }
+        return Array(slot.lenFrom(size)).fill(Fr.ZERO);
+    });
+}