@aztec/pxe 0.0.1-commit.b9865e97 → 0.0.1-commit.be03c316

package/dest/contract_function_simulator/oracle/oracle_type_mappings.js

@@ -1,23 +1,22 @@
-import { BLOCK_HEADER_LENGTH, KEY_VALIDATION_REQUEST_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 } from '@aztec/constants';
+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 { Point } from '@aztec/foundation/curves/grumpkin';
-import { fromUintArray } from '@aztec/simulator/client';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { FieldReader } from '@aztec/foundation/serialize';
 import { FunctionSelector, NoteSelector } from '@aztec/stdlib/abi';
-import { PublicDataWrite } from '@aztec/stdlib/avm';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { BlockHash } from '@aztec/stdlib/block';
-import { KeyValidationRequest } from '@aztec/stdlib/kernel';
-import { ContractClassLog, ContractClassLogFields, FlatPublicLogs, PrivateLog, Tag, appTaggingSecretKindFromDeliveryMode } from '@aztec/stdlib/logs';
-import { BlockHeader, TxHash } from '@aztec/stdlib/tx';
+import { Tag, appTaggingSecretKindFromDeliveryMode } from '@aztec/stdlib/logs';
+import { TxHash } from '@aztec/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 { LogRetrievalRequest } from '../noir-structs/log_retrieval_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 { ProvidedSecret } from '../noir-structs/provided_secret.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.
@@ -29,92 +28,123 @@ import { packAsHintedNote } from './note_packing_utils.js';
     });
 }
 // ─── Scalar Type Mappings ────────────────────────────────────────────────────
-export const FIELD = {
+/**
+ * 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(),
-        slots: 1
+        fn: ([reader])=>reader.readField()
     }
-};
-export const BOOL = {
+});
+export const BOOL = SCALAR({
+    kind: 'bool',
     serialization: {
         fn: (v)=>[
                 new Fr(v ? 1n : 0n)
             ]
     },
     deserialization: {
-        fn: ([reader])=>!reader.readField().isZero(),
-        slots: 1
+        fn: ([reader])=>!reader.readField().isZero()
     }
-};
-export const U32 = {
+});
+export const U32 = SCALAR({
+    kind: '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);
-        },
-        slots: 1
+        fn: ([reader])=>Number(uintFromField(reader.readField(), 32))
     }
-};
-export const BLOCK_NUMBER = {
-    serialization: {
-        fn: (v)=>[
-                new Fr(v)
-            ]
-    },
-    deserialization: {
-        fn: ([reader])=>BlockNumber(reader.readField().toNumber()),
-        slots: 1
-    }
-};
-/** A u8 byte: serializes to a single Fr; deserializes from a single Fr to a number in [0, 255]. */ export const BYTE = {
+});
+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])=>{
-            const value = reader.readField().toBigInt();
-            if (value > 0xffn) {
-                throw new Error(`BYTE overflow: value ${value} exceeds u8 max (255)`);
-            }
-            return Number(value);
-        },
-        slots: 1
+        fn: ([reader])=>Number(uintFromField(reader.readField(), 8))
     }
-};
+});
 // Noir passes `MessageDelivery` onchain variants here.
-export const DELIVERY_MODE = {
+export const DELIVERY_MODE = SCALAR({
+    kind: 'onchain-delivery-mode',
     deserialization: {
-        fn: (readers)=>appTaggingSecretKindFromDeliveryMode(BYTE.deserialization.fn(readers)),
-        slots: BYTE.deserialization.slots
+        fn: (readers)=>appTaggingSecretKindFromDeliveryMode(U8.deserialization.fn(readers))
     }
-};
-export const BIGINT = {
+});
+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])=>reader.readField().toBigInt(),
-        slots: 1
+        fn: ([reader])=>uintFromField(reader.readField(), 64)
     }
-};
-/** Reads every field in the slot as a UTF-8 character code. */ export const STR = {
+});
+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))
@@ -127,203 +157,471 @@ export const BIGINT = {
                 chars.push(String.fromCharCode(reader.readField().toNumber()));
             }
             return chars.join('');
-        },
-        slots: 1
-    }
-};
-export const AZTEC_ADDRESS = {
+        }
+    },
+    shape: [
+        'variable'
+    ]
+});
+export const AZTEC_ADDRESS = SCALAR({
+    kind: 'aztec-address',
     serialization: {
         fn: (v)=>[
                 v.toField()
             ]
     },
     deserialization: {
-        fn: ([reader])=>AztecAddress.fromField(reader.readField()),
-        slots: 1
+        fn: ([reader])=>AztecAddress.fromFieldUnsafe(reader.readField())
     }
-};
-export const BLOCK_HASH = {
+});
+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)=>[
-                new Fr(v.toBuffer())
+                v.toField()
             ]
     },
     deserialization: {
-        fn: ([reader])=>new BlockHash(reader.readField()),
-        slots: 1
+        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
     }
-};
-export const FUNCTION_SELECTOR = {
+]);
+const LOG_SOURCE = SCALAR({
+    kind: 'log-source',
     serialization: {
         fn: (v)=>[
-                v.toField()
+                new Fr(v)
             ]
     },
     deserialization: {
-        fn: ([reader])=>FunctionSelector.fromField(reader.readField()),
-        slots: 1
+        fn: ([reader])=>logSourceFromField(reader.readField())
     }
-};
-export const NOTE_SELECTOR = {
+});
+export const ETH_ADDRESS = SCALAR({
+    kind: 'eth-address',
     serialization: {
         fn: (v)=>[
                 v.toField()
             ]
     },
     deserialization: {
-        fn: ([reader])=>NoteSelector.fromField(reader.readField()),
-        slots: 1
+        fn: ([reader])=>EthAddress.fromField(reader.readField())
     }
-};
-export const TX_HASH = {
-    serialization: {
-        fn: (v)=>[
-                v.hash
-            ]
+});
+export const SLOT_NUMBER = ALIAS(FIELD, {
+    unwrap: (v)=>new Fr(v)
+});
+const APPEND_ONLY_TREE_SNAPSHOT = STRUCT([
+    {
+        name: 'root',
+        type: FIELD
     },
-    deserialization: {
-        fn: ([reader])=>TxHash.fromField(reader.readField()),
-        slots: 1
+    {
+        name: 'nextAvailableLeafIndex',
+        type: LEAF_INDEX
     }
-};
-export const TAG = {
-    serialization: {
-        fn: (v)=>[
-                v.value
-            ]
+]);
+const PARTIAL_STATE_REFERENCE = STRUCT([
+    {
+        name: 'noteHashTree',
+        type: APPEND_ONLY_TREE_SNAPSHOT
     },
-    deserialization: {
-        fn: ([reader])=>new Tag(reader.readField()),
-        slots: 1
+    {
+        name: 'nullifierTree',
+        type: APPEND_ONLY_TREE_SNAPSHOT
+    },
+    {
+        name: 'publicDataTree',
+        type: APPEND_ONLY_TREE_SNAPSHOT
     }
-};
-export const POINT = {
-    serialization: {
-        fn: (p)=>[
-                p.toFields()
-            ]
+]);
+const STATE_REFERENCE = STRUCT([
+    {
+        name: 'l1ToL2MessageTree',
+        type: APPEND_ONLY_TREE_SNAPSHOT
     },
-    deserialization: {
-        fn: ([reader])=>Point.fromFields([
-                reader.readField(),
-                reader.readField()
-            ]),
-        slots: 1
-    }
-};
-// ─── Struct Type Mappings ────────────────────────────────────────────────────
-export const BLOCK_HEADER = {
-    serialization: {
-        fn: (v)=>v.toFields()
+    {
+        name: 'partial',
+        type: PARTIAL_STATE_REFERENCE
+    }
+]);
+const GAS_FEES = STRUCT([
+    {
+        name: 'feePerDaGas',
+        type: U128
     },
-    deserialization: {
-        fn: ([reader])=>BlockHeader.fromFields(reader.readFieldArray(BLOCK_HEADER_LENGTH)),
-        slots: 1
+    {
+        name: 'feePerL2Gas',
+        type: U128
     }
-};
-export const KEY_VALIDATION_REQUEST = {
-    serialization: {
-        fn: (v)=>v.toFields()
+]);
+const GLOBAL_VARIABLES = STRUCT([
+    {
+        name: 'chainId',
+        type: FIELD
     },
-    deserialization: {
-        fn: ([reader])=>KeyValidationRequest.fromFields(reader.readFieldArray(KEY_VALIDATION_REQUEST_LENGTH)),
-        slots: 1
+    {
+        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 CONTRACT_INSTANCE = {
-    serialization: {
-        fn: (v)=>[
-                v.salt,
-                v.deployer.toField(),
-                v.currentContractClassId,
-                v.initializationHash,
-                v.immutablesHash,
-                ...v.publicKeys.toFields()
-            ]
+]);
+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 NULLIFIER_MEMBERSHIP_WITNESS = {
-    serialization: {
-        fn: (w)=>w.toNoirRepresentation().map((slot)=>Array.isArray(slot) ? slot.map((s)=>Fr.fromString(s)) : Fr.fromString(slot))
+]);
+export const KEY_VALIDATION_REQUEST = STRUCT([
+    {
+        name: 'pkMHash',
+        type: FIELD
+    },
+    {
+        name: 'skApp',
+        type: FIELD
     }
-};
-export const PUBLIC_DATA_WITNESS = {
-    serialization: {
-        fn: (w)=>w.toNoirRepresentation().map((slot)=>Array.isArray(slot) ? slot.map((s)=>Fr.fromString(s)) : Fr.fromString(slot))
+]);
+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 MESSAGE_LOAD_ORACLE_INPUTS = {
-    serialization: {
-        fn: (m)=>m.toNoirRepresentation().map((slot)=>Array.isArray(slot) ? slot.map((s)=>Fr.fromString(s)) : Fr.fromString(slot))
+]);
+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
     }
-};
-export const UTILITY_CONTEXT = {
-    serialization: {
-        fn: (ctx)=>[
-                ...ctx.blockHeader.toFields(),
-                ctx.contractAddress.toField()
-            ]
+]);
+const NULLIFIER_LEAF = STRUCT([
+    {
+        name: 'nullifier',
+        type: FIELD
     }
-};
-export const CALL_PRIVATE_RESULT = {
-    serialization: {
-        fn: (v)=>[
-                [
-                    v.endSideEffectCounter,
-                    v.returnsHash
-                ]
-            ]
+]);
+const NULLIFIER_LEAF_PREIMAGE = STRUCT([
+    {
+        name: 'leaf',
+        type: NULLIFIER_LEAF
+    },
+    {
+        name: 'nextKey',
+        type: FIELD
+    },
+    {
+        name: 'nextIndex',
+        type: BIGINT
     }
-};
-export const PUBLIC_KEYS_AND_PARTIAL_ADDRESS = {
-    serialization: {
-        fn: (v)=>[
-                [
-                    ...v.publicKeys.toFields(),
-                    v.partialAddress
-                ]
-            ]
+]);
+export const NULLIFIER_MEMBERSHIP_WITNESS = STRUCT([
+    {
+        name: 'leafPreimage',
+        type: NULLIFIER_LEAF_PREIMAGE
+    },
+    {
+        name: 'index',
+        type: BIGINT
+    },
+    {
+        name: 'siblingPath',
+        type: SIBLING_PATH(NULLIFIER_TREE_HEIGHT)
     }
-};
-export const CONTRACT_CLASS_LOG_INPUT = {
-    deserialization: {
-        fn: ([addrReader, fieldsReader, lengthReader])=>{
-            const addr = AztecAddress.fromField(addrReader.readField());
-            const fields = new ContractClassLogFields([
-                ...fieldsReader.readFieldArray(fieldsReader.remainingFields())
-            ]);
-            const length = lengthReader.readField().toNumber();
-            return new ContractClassLog(addr, fields, length);
-        },
-        // ContractClassLog input occupies 3 ACVM slots: [contractAddress], [message fields...], [length].
-        slots: 3
+]);
+const PUBLIC_DATA_LEAF = STRUCT([
+    {
+        name: 'slot',
+        type: FIELD
+    },
+    {
+        name: 'value',
+        type: FIELD
     }
-};
-export const TX_EFFECT = {
-    serialization: {
-        fn: (effect)=>{
-            const flatPublicLogs = FlatPublicLogs.fromLogs(effect.publicLogs);
-            return [
-                effect.revertCode.toField(),
-                effect.txHash.hash,
-                effect.transactionFee,
-                padArrayEnd(effect.noteHashes, Fr.ZERO, MAX_NOTE_HASHES_PER_TX),
-                padArrayEnd(effect.nullifiers, Fr.ZERO, MAX_NULLIFIERS_PER_TX),
-                padArrayEnd(effect.l2ToL1Msgs, Fr.ZERO, MAX_L2_TO_L1_MSGS_PER_TX),
-                padArrayEnd(effect.publicDataWrites, PublicDataWrite.empty(), MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX).flatMap((w)=>w.toFields()),
-                padArrayEnd(effect.privateLogs, PrivateLog.empty(), MAX_PRIVATE_LOGS_PER_TX).flatMap((l)=>l.toFields()),
-                new Fr(flatPublicLogs.length),
-                flatPublicLogs.payload,
-                padArrayEnd(effect.contractClassLogs, ContractClassLog.empty(), MAX_CONTRACT_CLASS_LOGS_PER_TX).flatMap((l)=>[
-                        ...l.fields.toFields(),
-                        new Fr(l.emittedLength),
-                        l.contractAddress.toField()
-                    ])
-            ];
-        }
+]);
+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 PUBLIC_DATA_WRITE = STRUCT([
+    {
+        name: 'leafSlot',
+        type: FIELD
+    },
+    {
+        name: 'value',
+        type: FIELD
     }
-};
-export const NOTE = {
+]);
+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,
@@ -334,90 +632,288 @@ export const NOTE = {
                 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 PENDING_TAGGED_LOG = {
-    serialization: {
-        fn: (log)=>[
-                log.toFields()
-            ]
+]);
+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 NOTE_VALIDATION_REQUEST = {
-    deserialization: {
-        fn: ([reader])=>NoteValidationRequest.fromFields(reader),
-        slots: 1
+]);
+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 EVENT_VALIDATION_REQUEST = {
-    deserialization: {
-        fn: ([reader])=>EventValidationRequest.fromFields(reader),
-        slots: 1
+]);
+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 LOG_RETRIEVAL_REQUEST = {
+]);
+export const ORIGIN_BLOCK = STRUCT([
+    {
+        name: 'blockNumber',
+        type: U32
+    },
+    {
+        name: 'blockHash',
+        type: FIELD
+    }
+]);
+const ORIGIN_BLOCK_STATE = SCALAR({
+    kind: 'origin-block-state',
     serialization: {
-        fn: (req)=>[
-                req.toFields()
+        fn: (v)=>[
+                new Fr(v)
             ]
     },
     deserialization: {
-        fn: ([reader])=>LogRetrievalRequest.fromFields(reader),
-        slots: 1
+        fn: ([reader])=>originBlockStateFromNumber(reader.readField().toNumber())
     }
-};
-export const LOG_RETRIEVAL_RESPONSE = {
-    serialization: {
-        fn: (resp)=>[
-                resp.toFields()
-            ]
+});
+/** 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 MESSAGE_CONTEXT = {
-    serialization: {
-        fn: (mc)=>[
-                mc.toFields()
-            ]
+]);
+export const FACT = STRUCT([
+    {
+        name: 'factTypeId',
+        type: FIELD
+    },
+    {
+        name: 'payload',
+        type: EPHEMERAL_ARRAY(FIELD)
+    },
+    {
+        name: 'originBlock',
+        type: OPTION(RETRACTABLE_FACT_ORIGIN)
     }
-};
-export const PROVIDED_SECRET = {
-    deserialization: {
-        fn: ([reader])=>ProvidedSecret.fromFields(reader),
-        slots: 1
+]);
+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 ────────────────────────────────────────────────
-/** `_height` is unused at runtime but lets TypeScript infer the exact `N` for `MembershipWitness<N>`. */ export function MEMBERSHIP_WITNESS(_height) {
+/**
+ * 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
+    };
+}
+function SIBLING_PATH(height) {
+    return LEAF({
+        // On the wire (and in Noir) a sibling path is a plain `[Field; height]`, so it shares the fixed-array kind.
+        kind: `array(field,${height})`,
         serialization: {
-            fn: (witness)=>[
-                    new Fr(witness.leafIndex),
-                    [
-                        ...witness.siblingPath
-                    ]
+            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',
+        label: `array(${inner.label})`,
+        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)
+            }
+        ]
     };
 }
-export function ARRAY(element) {
+/**
+ * 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)=>[
-                    values.flatMap((v)=>element.serialization.fn(v).flat())
+                    padArrayEnd(packElements(element, values), Fr.ZERO, length * elementWidth)
                 ]
         } : undefined,
         deserialization: element.deserialization ? {
-            fn: ([reader])=>{
-                const result = [];
-                while(!reader.isFinished()){
-                    result.push(element.deserialization.fn([
-                        reader
-                    ]));
-                }
-                return result;
-            },
-            slots: 1
-        } : undefined
+            fn: ([reader])=>unpackElements(element, reader, length)
+        } : undefined,
+        shape: [
+            {
+                len: length * elementWidth
+            }
+        ]
     };
 }
 /**
@@ -427,134 +923,321 @@ export function ARRAY(element) {
  *
  * 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)`:
+ * @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(element) {
+ */ export function BOUNDED_VEC(inner) {
     return {
-        serialization: element.serialization ? {
+        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}`);
                 }
-                const flat = bv.data.flatMap((item)=>element.serialization.fn(item).flat());
+                // 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 [
-                    padArrayEnd(flat, Fr.ZERO, bv.maxLength * bv.elementSize),
+                    flat,
                     new Fr(bv.data.length)
                 ];
             }
         } : undefined,
-        deserialization: element.deserialization ? {
+        deserialization: inner.deserialization ? {
             fn: ([storageReader, lengthReader])=>{
-                const maxLength = storageReader.remainingFields();
+                // 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 = [];
-                for(let i = 0; i < length; i++){
-                    elements.push(element.deserialization.fn([
-                        storageReader
-                    ]));
-                }
-                // Drain the trailing zero-padding (maxLength - length unused element slots) so the storage reader is
-                // fully consumed.
+                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)
             },
-            slots: 2
-        } : undefined
+            '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`.
+ */ 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 + 1
+            }
+        ]
     };
 }
 /**
- * Wraps an inner TypeMapping in Noir-style `Option<T>`. Adds a discriminant slot and uses the handler-provided
- * `Option.none(shape)` template to produce a correctly-sized zero-filled output for the None case.
+ * Wraps an inner TypeMapping in Noir-style `Option<T>`, adding a leading discriminant slot.
  *
- * @example Serializing `Option.some(AztecAddress.fromField(Fr(42)))` with `OPTION(AZTEC_ADDRESS)`:
+ * 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.empty(AztecAddress.ZERO)` with `OPTION(AZTEC_ADDRESS)`:
+ * @example Serializing `Option.none()` with `OPTION(AZTEC_ADDRESS)`:
  * ```
  * slot 0: Fr(0)    // discriminant: None
- * slot 1: Fr(0)    // zero-filled using shape
+ * 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)=>{
-                if (opt.isSome()) {
-                    return [
-                        Fr.ONE,
-                        ...inner.serialization.fn(opt.value)
-                    ];
-                }
-                if (opt.template === undefined) {
-                    throw new Error('Cannot serialize Option.empty() without an emptyTemplate — provide one via Option.empty(emptyTemplate)');
-                }
-                const zeroSlots = inner.serialization.fn(opt.template).map((s)=>Array.isArray(s) ? Array(s.length).fill(Fr.ZERO) : Fr.ZERO);
-                return [
+            fn: (opt)=>opt.isSome() ? [
+                    Fr.ONE,
+                    ...inner.serialization.fn(opt.value)
+                ] : [
                     Fr.ZERO,
-                    ...zeroSlots
-                ];
-            }
+                    ...zeroSlotsFromShape(inner.shape, opt.size)
+                ]
         } : undefined,
         deserialization: inner.deserialization ? {
             fn: ([discriminant, ...innerReaders])=>{
                 if (discriminant.readField().isZero()) {
-                    // None still carries zero-filled inner slots on the wire; drain them so the inner readers are fully
-                    // consumed.
+                    // 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(undefined);
+                    return Option.none();
                 }
                 return Option.some(inner.deserialization.fn(innerReaders));
-            },
-            slots: inner.deserialization.slots + 1
-        } : undefined
-    };
-}
-/** A packed uint buffer (e.g. `[u8; N]` in Noir): 1 slot of packed uint values ↔ `Buffer`. */ export function BUFFER(bitSize) {
-    return {
-        serialization: {
-            fn: (buf)=>[
-                    Array.from(buf).map((b)=>new Fr(b))
-                ]
-        },
-        deserialization: {
-            fn: ([reader])=>{
-                const fields = reader.readFieldArray(reader.remainingFields()).map((f)=>f.toString());
-                return fromUintArray(fields, bitSize);
-            },
-            slots: 1
-        }
+            }
+        } : undefined,
+        // A leading discriminant slot followed by the inner's slots.
+        shape: [
+            'scalar',
+            ...inner.shape
+        ]
     };
 }
 export function EPHEMERAL_ARRAY(element) {
-    // An EphemeralArray param is a single slot; the per-param assert covers that slot but never sees the
-    // per-row readers materialized in readAll(). Assert full consumption per row here.
+    // 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: (readers)=>{
-                const value = element.deserialization.fn(readers);
-                assertReadersConsumed(readers);
-                return value;
-            },
-            slots: element.deserialization.slots
-        }
+            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)=>element.serialization.fn(v).flat())
+                    ea.materializeSlot((v)=>serializeElement(element, v))
                 ]
         } : undefined,
         deserialization: rowElement ? {
-            fn: ([reader])=>EphemeralArray.fromSlot(reader.readField(), rowElement),
-            slots: 1
-        } : undefined
+            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)
     };
 }
+export function isArrayMapping(type) {
+    return type.kind === 'array';
+}
+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` 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);
+    });
+}