@aztec-labs/pxe 6.0.0-nightly.20260829

package/dest/contract_function_simulator/oracle/oracle_type_mappings.js

@@ -0,0 +1,1258 @@
+import { CONTRACT_CLASS_LOG_SIZE_IN_FIELDS, FLAT_PUBLIC_LOGS_PAYLOAD_LENGTH, 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-labs/constants';
+import { BlockNumber } from '@aztec-labs/foundation/branded-types';
+import { padArrayEnd } from '@aztec-labs/foundation/collection';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { FieldReader } from '@aztec-labs/foundation/serialize';
+import { FunctionSelector, NoteSelector } from '@aztec-labs/stdlib/abi';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { BlockHash } from '@aztec-labs/stdlib/block';
+import { Tag, appTaggingSecretKindFromDeliveryMode } from '@aztec-labs/stdlib/logs';
+import { TxHash } from '@aztec-labs/stdlib/tx';
+import { originBlockStateFromNumber } from '../../storage/fact_store/index.js';
+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 ────────────────────────────────────────────────────
+/**
+ * A leaf mapping whose {@link TypeMapping.label} is just its bare {@link TypeMapping.kind}. Its wire shape is arbitrary
+ * (several fields, or a variable-width run); a single-field scalar uses the shorter {@link SCALAR} instead.
+ */ export function LEAF(mapping) {
+    return {
+        ...mapping,
+        label: mapping.kind
+    };
+}
+/** A {@link LEAF} occupying a single `'scalar'` wire slot, so callers omit the shape. */ export function SCALAR(mapping) {
+    return LEAF({
+        ...mapping,
+        shape: [
+            'scalar'
+        ]
+    });
+}
+export const FIELD = SCALAR({
+    kind: 'field',
+    serialization: {
+        fn: (v)=>[
+                v
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>reader.readField()
+    }
+});
+export const BOOL = SCALAR({
+    kind: 'bool',
+    serialization: {
+        fn: (v)=>[
+                new Fr(v ? 1n : 0n)
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>!reader.readField().isZero()
+    }
+});
+export const U32 = SCALAR({
+    kind: 'u32',
+    serialization: {
+        fn: (v)=>[
+                new Fr(v)
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>Number(uintFromField(reader.readField(), 32))
+    }
+});
+export const BLOCK_NUMBER = ALIAS(U32, {
+    wrap: (v)=>BlockNumber(v),
+    unwrap: (v)=>v
+});
+export const U8 = SCALAR({
+    kind: 'u8',
+    serialization: {
+        fn: (byte)=>[
+                new Fr(byte)
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>Number(uintFromField(reader.readField(), 8))
+    }
+});
+// Noir passes `MessageDelivery` onchain variants here.
+export const DELIVERY_MODE = SCALAR({
+    kind: 'onchain-delivery-mode',
+    deserialization: {
+        fn: (readers)=>appTaggingSecretKindFromDeliveryMode(U8.deserialization.fn(readers))
+    }
+});
+export const RESOLVED_TAGGING_STRATEGY = LEAF({
+    kind: 'resolved-tagging-strategy',
+    serialization: {
+        fn: (resolved)=>resolvedTaggingStrategyToFields(resolved)
+    },
+    deserialization: {
+        fn: ([kindReader, secretReader])=>resolvedTaggingStrategyFromFields(kindReader.readField().toNumber(), secretReader.readField())
+    },
+    shape: [
+        'scalar',
+        'scalar'
+    ]
+});
+export const BIGINT = ALIAS(FIELD, {
+    wrap: (f)=>f.toBigInt(),
+    unwrap: (v)=>new Fr(v)
+});
+export const U64 = SCALAR({
+    kind: 'u64',
+    serialization: {
+        fn: (v)=>[
+                new Fr(v)
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>uintFromField(reader.readField(), 64)
+    }
+});
+export const U128 = SCALAR({
+    kind: 'u128',
+    serialization: {
+        fn: (v)=>[
+                new Fr(v)
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>uintFromField(reader.readField(), 128)
+    }
+});
+export const LEAF_INDEX = ALIAS(FIELD, {
+    wrap: (f)=>f.toNumber(),
+    unwrap: (v)=>new Fr(v)
+});
+/** Reads every field in the slot as a UTF-8 character code. */ export const STR = LEAF({
+    kind: '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 = SCALAR({
+    kind: 'aztec-address',
+    serialization: {
+        fn: (v)=>[
+                v.toField()
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>AztecAddress.fromFieldUnsafe(reader.readField())
+    }
+});
+export const BLOCK_HASH = ALIAS(FIELD, {
+    wrap: (f)=>new BlockHash(f),
+    unwrap: (v)=>new Fr(v.toBuffer())
+});
+export const FUNCTION_SELECTOR = SCALAR({
+    kind: 'function-selector',
+    serialization: {
+        fn: (v)=>[
+                v.toField()
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>FunctionSelector.fromField(reader.readField())
+    }
+});
+export const NOTE_SELECTOR = ALIAS(FIELD, {
+    wrap: (f)=>NoteSelector.fromField(f),
+    unwrap: (v)=>v.toField()
+});
+export const TX_HASH = ALIAS(FIELD, {
+    wrap: (f)=>TxHash.fromField(f),
+    unwrap: (v)=>v.hash
+});
+const TAG = ALIAS(FIELD, {
+    wrap: (f)=>new Tag(f),
+    unwrap: (v)=>v.value
+});
+export const POINT = STRUCT([
+    {
+        name: 'x',
+        type: FIELD
+    },
+    {
+        name: 'y',
+        type: FIELD
+    }
+]);
+const LOG_SOURCE = SCALAR({
+    kind: 'log-source',
+    serialization: {
+        fn: (v)=>[
+                new Fr(v)
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>logSourceFromField(reader.readField())
+    }
+});
+export const ETH_ADDRESS = SCALAR({
+    kind: 'eth-address',
+    serialization: {
+        fn: (v)=>[
+                v.toField()
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>EthAddress.fromField(reader.readField())
+    }
+});
+export const SLOT_NUMBER = ALIAS(FIELD, {
+    unwrap: (v)=>new Fr(v)
+});
+const APPEND_ONLY_TREE_SNAPSHOT = STRUCT([
+    {
+        name: 'root',
+        type: FIELD
+    },
+    {
+        name: 'nextAvailableLeafIndex',
+        type: LEAF_INDEX
+    }
+]);
+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
+    }
+]);
+export const GAS_FEES = STRUCT([
+    {
+        name: 'feePerDaGas',
+        type: U128
+    },
+    {
+        name: 'feePerL2Gas',
+        type: U128
+    }
+]);
+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: U64
+    },
+    {
+        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
+    }
+]);
+export 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: 'witness',
+        type: MEMBERSHIP_WITNESS(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: FIXED_ARRAY(FIELD, PUBLIC_DATA_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
+    }
+]);
+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: U8
+    },
+    {
+        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 = LEAF({
+    kind: '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 = LEAF({
+    kind: 'note-validation-request',
+    deserialization: {
+        fn: ([reader])=>NoteValidationRequest.fromFields(reader)
+    },
+    shape: [
+        'variable'
+    ]
+});
+export const EVENT_VALIDATION_REQUEST = LEAF({
+    kind: '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
+    },
+    {
+        name: 'blockNumber',
+        type: BLOCK_NUMBER
+    },
+    {
+        name: 'blockTimestamp',
+        type: U64
+    },
+    {
+        name: 'blockHash',
+        type: BLOCK_HASH
+    }
+]);
+export const RESOLVED_TX = STRUCT([
+    {
+        name: 'txHash',
+        type: TX_HASH
+    },
+    {
+        name: 'uniqueNoteHashesInTx',
+        type: FIXED_BOUNDED_VEC(FIELD, MAX_NOTE_HASHES_PER_TX)
+    },
+    {
+        name: 'firstNullifierInTx',
+        type: FIELD
+    },
+    {
+        name: 'blockNumber',
+        type: U32
+    },
+    {
+        name: 'blockHash',
+        type: FIELD
+    }
+]);
+export const PENDING_TAGGED_LOG = STRUCT([
+    {
+        name: 'log',
+        type: FIXED_BOUNDED_VEC(FIELD, PRIVATE_LOG_SIZE_IN_FIELDS)
+    },
+    {
+        name: 'context',
+        type: RESOLVED_TX
+    }
+]);
+export const ORIGIN_BLOCK = STRUCT([
+    {
+        name: 'blockNumber',
+        type: U32
+    },
+    {
+        name: 'blockHash',
+        type: FIELD
+    }
+]);
+const ORIGIN_BLOCK_STATE = SCALAR({
+    kind: 'origin-block-state',
+    serialization: {
+        fn: (v)=>[
+                new Fr(v)
+            ]
+    },
+    deserialization: {
+        fn: ([reader])=>originBlockStateFromNumber(reader.readField().toNumber())
+    }
+});
+/** Read-side origin of a retractable fact, carrying the chain state of its origin block. */ export const RETRACTABLE_FACT_ORIGIN = STRUCT([
+    {
+        name: 'blockNumber',
+        type: U32
+    },
+    {
+        name: 'blockHash',
+        type: FIELD
+    },
+    {
+        name: 'blockState',
+        type: ORIGIN_BLOCK_STATE
+    }
+]);
+export const FACT = STRUCT([
+    {
+        name: 'factTypeId',
+        type: FIELD
+    },
+    {
+        name: 'payload',
+        type: EPHEMERAL_ARRAY(FIELD)
+    },
+    {
+        name: 'originBlock',
+        type: OPTION(RETRACTABLE_FACT_ORIGIN)
+    }
+]);
+export const FACT_COLLECTION = STRUCT([
+    {
+        name: 'contractAddress',
+        type: AZTEC_ADDRESS
+    },
+    {
+        name: 'scope',
+        type: AZTEC_ADDRESS
+    },
+    {
+        name: 'factCollectionTypeId',
+        type: FIELD
+    },
+    {
+        name: 'factCollectionId',
+        type: FIELD
+    },
+    {
+        name: 'facts',
+        type: EPHEMERAL_ARRAY(FACT)
+    }
+]);
+export const PROVIDED_SECRET = STRUCT([
+    {
+        name: 'secret',
+        type: FIELD
+    },
+    {
+        name: 'mode',
+        type: DELIVERY_MODE
+    }
+]);
+// ─── Combinator Type Mappings ────────────────────────────────────────────────
+/**
+ * A TS-side alias of `base`: the same Noir type on the wire (it inherits `base`'s `kind`, `label`, and `shape`) but a
+ * richer TS value. `wrap` maps a base value to the alias, `unwrap` back; a serialize-only alias passes only `unwrap`.
+ */ export function ALIAS(base, conversions) {
+    const { wrap, unwrap } = conversions;
+    return {
+        kind: base.kind,
+        label: base.label,
+        serialization: base.serialization && unwrap ? {
+            fn: (value)=>base.serialization.fn(unwrap(value))
+        } : undefined,
+        deserialization: base.deserialization && wrap ? {
+            fn: (readers)=>wrap(base.deserialization.fn(readers))
+        } : undefined,
+        shape: base.shape
+    };
+}
+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',
+        label: `array(${inner.label})`,
+        inner,
+        serialization: inner.serialization ? {
+            fn: (values)=>[
+                    packElements(inner, values)
+                ]
+        } : undefined,
+        deserialization: inner.deserialization ? {
+            fn: ([reader])=>{
+                // The whole slot is the array, so read as many elements as its fields hold.
+                const elementWidth = fieldWidth(inner.shape);
+                return unpackElements(inner, reader, reader.remainingFields() / elementWidth, elementWidth);
+            }
+        } : 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; length]` in one slot: serializes `values` (each flattened via `element`)
+ * zero-padded to exactly `length * elementWidth` fields, and deserializes all `length` elements back. An absent
+ * element is the zero encoding, so the padding is derived from the shape.
+ */ export function FIXED_ARRAY(element, length) {
+    const elementWidth = fieldWidth(element.shape);
+    return {
+        kind: 'fixed-array',
+        label: `array(${element.label},${length})`,
+        inner: element,
+        length,
+        serialization: element.serialization ? {
+            fn: (values)=>[
+                    padArrayEnd(packElements(element, values), Fr.ZERO, length * elementWidth)
+                ]
+        } : undefined,
+        deserialization: element.deserialization ? {
+            fn: ([reader])=>unpackElements(element, reader, length, elementWidth)
+        } : undefined,
+        shape: [
+            {
+                len: length * 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(U8)`:
+ * ```
+ * 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',
+        label: `bounded-vec(${inner.label})`,
+        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 elementWidth = fieldWidth(inner.shape);
+                const storageFields = storageReader.remainingFields();
+                if (storageFields % elementWidth !== 0) {
+                    throw new Error(`Malformed BoundedVec: storage array holds ${storageFields} field(s), which is not a whole number of ` + `${elementWidth}-field elements`);
+                }
+                // The BoundedVec's maximum length is determined by the size of the storage array, so its length is bounded
+                // by it.
+                const maxLength = storageFields / elementWidth;
+                const length = lengthReader.readField().toNumber();
+                if (length > maxLength) {
+                    throw new Error(`Malformed BoundedVec: length ${length} exceeds the ${maxLength} element(s) its storage array holds`);
+                }
+                const elements = unpackElements(inner, storageReader, length, elementWidth);
+                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>` with the capacity fixed at construction.
+ *
+ * Two slots (zero-padded storage, then the length) whose widths are statically known from the fixed capacity.
+ *
+ * Throws if the input exceeds `maxLength`.
+ */ export function FIXED_BOUNDED_VEC(element, maxLength) {
+    const width = fieldWidth(element.shape);
+    return {
+        kind: 'fixed-bounded-vec',
+        label: `bounded-vec(${element.label},${maxLength})`,
+        inner: element,
+        maxLength,
+        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
+            },
+            'scalar'
+        ]
+    };
+}
+/**
+ * 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',
+        label: `option(${inner.label})`,
+        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
+        ]
+    };
+}
+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 ? {
+        kind: element.kind,
+        label: element.label,
+        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 {
+        kind: 'ephemeral-array',
+        label: `ephemeral-array(${element.label})`,
+        inner: element,
+        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.
+ */ export function STRUCT(fields) {
+    return {
+        kind: 'struct',
+        label: `{${structFieldLabels(fields)}}`,
+        fields,
+        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)
+    };
+}
+/**
+ * Maps Noir's `[T]` ↔ TS `T[]` over 2 slots:
+ *   slot 0 — length scalar (count of elements)
+ *   slot 1 — the elements' fields, laid end to end
+ *
+ * @example Serializing `[{ x: 1, y: 2 }, { x: 3, y: 4 }]` with `VECTOR(POINT)`:
+ * ```
+ * slot 0: Fr(2)                          // element count, not field count
+ * slot 1: [Fr(1), Fr(2), Fr(3), Fr(4)]   // each element's fields end to end
+ * ```
+ */ export function VECTOR(inner) {
+    return {
+        kind: 'vector',
+        label: `vector(${inner.label})`,
+        inner,
+        serialization: inner.serialization ? {
+            fn: (values)=>[
+                    new Fr(values.length),
+                    packElements(inner, values)
+                ]
+        } : undefined,
+        deserialization: inner.deserialization ? {
+            fn: ([lengthReader, contentsReader])=>{
+                const length = lengthReader.readField().toNumber();
+                // If the shape does not fix a width, every element shares one unknown width, so dividing the contents by
+                // the count recovers it.
+                const elementWidth = tryFieldWidth(inner.shape) ?? contentsReader.remainingFields() / length;
+                return unpackElements(inner, contentsReader, length, elementWidth);
+            }
+        } : undefined,
+        // slot 0: the length scalar; slot 1: the contents, sized by that length.
+        shape: [
+            'scalar',
+            {
+                lenFrom: (size)=>size.length * fieldWidth(inner.shape)
+            }
+        ]
+    };
+}
+export function isArrayMapping(type) {
+    return type.kind === 'array';
+}
+export function isVectorMapping(type) {
+    return type.kind === 'vector';
+}
+export function isBoundedVecMapping(type) {
+    return type.kind === 'bounded-vec';
+}
+export function isOptionMapping(type) {
+    return type.kind === 'option';
+}
+export function isStructMapping(type) {
+    return type.kind === 'struct';
+}
+export function isFixedArrayMapping(type) {
+    return type.kind === 'fixed-array';
+}
+export function isFixedBoundedVecMapping(type) {
+    return type.kind === 'fixed-bounded-vec';
+}
+export function isEphemeralArrayMapping(type) {
+    return type.kind === 'ephemeral-array';
+}
+/**
+ * The comma-joined labels of a struct's fields, with nested struct labels spliced into the parent: nesting affects
+ * neither the wire (struct slots concatenate) nor the interface, so the label treats nested and flat declarations as
+ * the same type.
+ */ function structFieldLabels(fields) {
+    return fields.map((f)=>isStructMapping(f.type) ? structFieldLabels(f.type.fields) : f.type.label).join(',');
+}
+/** The field's value as a bigint, asserted to fit a `bits`-wide uint. */ function uintFromField(field, bits) {
+    const max = 2n ** BigInt(bits) - 1n;
+    const value = field.toBigInt();
+    if (value > max) {
+        throw new Error(`u${bits} overflow: value ${value} exceeds max (${max})`);
+    }
+    return value;
+}
+/** 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. */ export 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` `elementWidth`-field elements out of a packed run (the inverse of {@link packElements}). Element must
+ * be deserializable. When the element's shape fixes no width, `elementWidth` comes from the run's own size, and such an
+ * element must occupy a single slot, since nothing records how many of a chunk's fields belong to each slot.
+ */ function unpackElements(element, reader, count, elementWidth) {
+    if (tryFieldWidth(element.shape) === undefined && element.shape.length !== 1) {
+        throw new Error(`Cannot unpack ${element.label} elements: their width is not fixed by the type, so we can't tell how many ` + `fields each of their ${element.shape.length} slots holds`);
+    }
+    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);
+    });
+}