@aztec/pxe 5.0.0-rc.1 → 5.0.0

package/src/contract_function_simulator/oracle/oracle_type_mappings.ts

@@ -1,6 +1,6 @@
 import {
-  BLOCK_HEADER_LENGTH,
-  KEY_VALIDATION_REQUEST_LENGTH,
+  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,
@@ -8,48 +8,91 @@ import {
   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 { BlockNumber, type SlotNumber } 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 { EthAddress } from '@aztec/foundation/eth-address';
 import { FieldReader } from '@aztec/foundation/serialize';
-import { MembershipWitness } from '@aztec/foundation/trees';
+import { MembershipWitness, type SiblingPath } from '@aztec/foundation/trees';
 import { type ACVMField, fromUintArray } from '@aztec/simulator/client';
 import { FunctionSelector, NoteSelector } from '@aztec/stdlib/abi';
-import { PublicDataWrite } from '@aztec/stdlib/avm';
+import { PublicDataWrite, RevertCode } from '@aztec/stdlib/avm';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { BlockHash } from '@aztec/stdlib/block';
-import type { ContractInstance, PartialAddress } from '@aztec/stdlib/contract';
+import type { ContractInstancePreimage, PartialAddress } from '@aztec/stdlib/contract';
+import type { GasFees } from '@aztec/stdlib/gas';
 import { KeyValidationRequest } from '@aztec/stdlib/kernel';
 import type { PublicKeys } from '@aztec/stdlib/keys';
 import {
   type AppTaggingSecretKind,
-  ContractClassLog,
-  ContractClassLogFields,
-  FlatPublicLogs,
-  MessageContext,
-  PendingTaggedLog,
+  type FlatPublicLogs,
   PrivateLog,
   Tag,
   appTaggingSecretKindFromDeliveryMode,
 } from '@aztec/stdlib/logs';
-import { NullifierMembershipWitness, PublicDataWitness } from '@aztec/stdlib/trees';
-import { BlockHeader, TxEffect, TxHash } from '@aztec/stdlib/tx';
-
+import {
+  type AppendOnlyTreeSnapshot,
+  type NullifierLeaf,
+  type NullifierLeafPreimage,
+  NullifierMembershipWitness,
+  type PublicDataTreeLeaf,
+  type PublicDataTreeLeafPreimage,
+  PublicDataWitness,
+} from '@aztec/stdlib/trees';
+import {
+  BlockHeader,
+  type GlobalVariables,
+  type PartialStateReference,
+  type StateReference,
+  TxHash,
+} from '@aztec/stdlib/tx';
+
+import type { OriginBlock, RetractableFactOrigin } from '../../storage/fact_store/index.js';
 import { BoundedVec } from '../noir-structs/bounded_vec.js';
+import type { ContractClassLogData } from '../noir-structs/contract_class_log_data.js';
+import type { EmbeddedCurvePoint } from '../noir-structs/embedded_curve_point.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 { LogRetrievalResponse } from '../noir-structs/log_retrieval_response.js';
+import type { Fact } from '../noir-structs/fact.js';
+import type { FactCollection } from '../noir-structs/fact_collection.js';
+import { type LogRetrievalRequest, type LogSource, logSourceFromField } from '../noir-structs/log_retrieval_request.js';
+import type { LogRetrievalResponse } from '../noir-structs/log_retrieval_response.js';
 import type { NoteData } from '../noir-structs/note_data.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 { UtilityContext } from '../noir-structs/utility_context.js';
-import { MessageLoadOracleInputs } from './message_load_oracle_inputs.js';
+import type { PendingTaggedLog } from '../noir-structs/pending_tagged_log.js';
+import type { ProvidedSecret } from '../noir-structs/provided_secret.js';
+import {
+  type ResolvedTaggingStrategy,
+  resolvedTaggingStrategyFromFields,
+  resolvedTaggingStrategyToFields,
+} from '../noir-structs/resolved_tagging_strategy.js';
+import type { ResolvedTx } from '../noir-structs/resolved_tx.js';
+import type { TxEffectData } from '../noir-structs/tx_effect_data.js';
+import type { UtilityContext } from '../noir-structs/utility_context.js';
+import type { MessageLoadOracleInputs } from './message_load_oracle_inputs.js';
 import { packAsHintedNote } from './note_packing_utils.js';
 
+// `ORACLE_REGISTRY` infers its entry signatures from these mappings, so its emitted declaration (and the oracle
+// interfaces derived from it) names the protocol types below. Re-exporting them gives tsc a portable path to each
+// type instead of falling back to a deep node_modules path that breaks .d.ts portability (TS2742).
+export type {
+  AppTaggingSecretKind,
+  BlockHash,
+  BlockHeader,
+  ContractInstancePreimage,
+  MembershipWitness,
+  NullifierMembershipWitness,
+  PendingTaggedLog,
+  PublicDataWitness,
+  TxHash,
+};
+
 // ─── Core Types ──────────────────────────────────────────────────────────────
 
 /** One ACVM input slot: an array of hex-encoded field strings. */
@@ -58,6 +101,18 @@ export type InputSlot = ACVMField[];
 /** One ACVM output slot: a scalar hex string or an array of hex strings. */
 export type OutputSlot = ACVMField | ACVMField[];
 
+/**
+ * Wire layout of a single slot:
+ * - `'scalar'` — a bare field (one `Fr`); on the ACVM/Noir wire a `Field`.
+ * - `{ len }`  — an array of exactly `len` fields (`Fr[]`); a `[Field; len]`.
+ * - `'variable'` — a slot whose field count is not statically known and cannot be sized on demand (a string, a
+ *   length-prefixed struct). It contributes to the slot count but can never be zero-filled.
+ * - `{ lenFrom: fn }` — like `'variable'`, but its field count can be resolved from a runtime size descriptor. The
+ *   descriptor's shape is type-specific (e.g. `{ length }`, `{ maxLength }`), so `size` is typed `any`: a single union
+ *   can't type each mapping's distinct `lenFrom` under parameter contravariance.
+ */
+export type SlotShape = 'scalar' | { len: number } | 'variable' | { lenFrom: (size: any) => number };
+
 /**
  * Describes how to serialize and/or deserialize a single typed value to/from ACVM wire format.
  * Either side is optional — output-only types omit `deserialization`, input-only types omit `serialization`.
@@ -68,18 +123,18 @@ export interface TypeMapping<T = any> {
     fn: (value: T) => (Fr | Fr[])[];
   };
   deserialization?: {
-    /** Read a typed value from one FieldReader per consumed slot. */
+    /** Read a typed value from its slots — one {@link FieldReader} per slot, as laid out by {@link shape}. */
     fn: (readers: FieldReader[]) => T;
-    /**
-     * Number of InputSlots this type reads from. `deserialization.fn` receives one FieldReader per slot in `readers`.
-     *
-     * Examples:
-     * - `FIELD`, `U32`, `AZTEC_ADDRESS` — single slot         → `slots: 1`
-     * - `OPTION(T)` — discriminant + inner slots              → `slots: T.slots + 1`
-     * - `CONTRACT_CLASS_LOG_INPUT` — [addr], [fields], [len]  → `slots: 3`
-     */
-    slots: number;
   };
+  /**
+   * The type's wire layout, one entry per slot.
+   *
+   * Examples:
+   * - `FIELD` → `['scalar']` // single slot
+   * - `OPTION(T)` → `['scalar', ...T.shape]` // [discriminant], [...inner.shape]
+   * - `CONTRACT_CLASS_LOG` → `['scalar', { len: N }, 'scalar']` // [addr], [fields], [len]
+   */
+  shape: SlotShape[];
 }
 
 export type MaybePromise<T> = T | Promise<T>;
@@ -101,12 +156,14 @@ export function assertReadersConsumed(readers: FieldReader[]): void {
 
 export const FIELD: TypeMapping<Fr> = {
   serialization: { fn: v => [v] },
-  deserialization: { fn: ([reader]) => reader.readField(), slots: 1 },
+  deserialization: { fn: ([reader]) => reader.readField() },
+  shape: ['scalar'],
 };
 
 export const BOOL: TypeMapping<boolean> = {
   serialization: { fn: v => [new Fr(v ? 1n : 0n)] },
-  deserialization: { fn: ([reader]) => !reader.readField().isZero(), slots: 1 },
+  deserialization: { fn: ([reader]) => !reader.readField().isZero() },
+  shape: ['scalar'],
 };
 
 export const U32: TypeMapping<number> = {
@@ -119,13 +176,14 @@ export const U32: TypeMapping<number> = {
       }
       return Number(value);
     },
-    slots: 1,
   },
+  shape: ['scalar'],
 };
 
 export const BLOCK_NUMBER: TypeMapping<BlockNumber> = {
   serialization: { fn: v => [new Fr(v)] },
-  deserialization: { fn: ([reader]) => BlockNumber(reader.readField().toNumber()), slots: 1 },
+  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]. */
@@ -139,21 +197,31 @@ export const BYTE: TypeMapping<number> = {
       }
       return Number(value);
     },
-    slots: 1,
   },
+  shape: ['scalar'],
 };
 
 // Noir passes `MessageDelivery` onchain variants here.
 export const DELIVERY_MODE: TypeMapping<AppTaggingSecretKind> = {
   deserialization: {
     fn: readers => appTaggingSecretKindFromDeliveryMode(BYTE.deserialization!.fn(readers)),
-    slots: BYTE.deserialization!.slots,
   },
+  shape: BYTE.shape,
+};
+
+export const RESOLVED_TAGGING_STRATEGY: TypeMapping<ResolvedTaggingStrategy> = {
+  serialization: { fn: resolved => resolvedTaggingStrategyToFields(resolved) },
+  deserialization: {
+    fn: ([kindReader, secretReader]) =>
+      resolvedTaggingStrategyFromFields(kindReader.readField().toNumber(), secretReader.readField()),
+  },
+  shape: ['scalar', 'scalar'],
 };
 
 export const BIGINT: TypeMapping<bigint> = {
   serialization: { fn: v => [new Fr(v)] },
-  deserialization: { fn: ([reader]) => reader.readField().toBigInt(), slots: 1 },
+  deserialization: { fn: ([reader]) => reader.readField().toBigInt() },
+  shape: ['scalar'],
 };
 
 /** Reads every field in the slot as a UTF-8 character code. */
@@ -167,163 +235,241 @@ export const STR: TypeMapping<string> = {
       }
       return chars.join('');
     },
-    slots: 1,
   },
+  shape: ['variable'],
 };
 
 export const AZTEC_ADDRESS: TypeMapping<AztecAddress> = {
   serialization: { fn: v => [v.toField()] },
-  deserialization: { fn: ([reader]) => AztecAddress.fromField(reader.readField()), slots: 1 },
+  deserialization: { fn: ([reader]) => AztecAddress.fromFieldUnsafe(reader.readField()) },
+  shape: ['scalar'],
 };
 
 export const BLOCK_HASH: TypeMapping<BlockHash> = {
   serialization: { fn: v => [new Fr(v.toBuffer())] },
-  deserialization: { fn: ([reader]) => new BlockHash(reader.readField()), slots: 1 },
+  deserialization: { fn: ([reader]) => new BlockHash(reader.readField()) },
+  shape: ['scalar'],
 };
 
 export const FUNCTION_SELECTOR: TypeMapping<FunctionSelector> = {
   serialization: { fn: v => [v.toField()] },
-  deserialization: { fn: ([reader]) => FunctionSelector.fromField(reader.readField()), slots: 1 },
+  deserialization: { fn: ([reader]) => FunctionSelector.fromField(reader.readField()) },
+  shape: ['scalar'],
 };
 
 export const NOTE_SELECTOR: TypeMapping<NoteSelector> = {
   serialization: { fn: v => [v.toField()] },
-  deserialization: { fn: ([reader]) => NoteSelector.fromField(reader.readField()), slots: 1 },
+  deserialization: { fn: ([reader]) => NoteSelector.fromField(reader.readField()) },
+  shape: ['scalar'],
 };
 
 export const TX_HASH: TypeMapping<TxHash> = {
   serialization: { fn: v => [v.hash] },
-  deserialization: { fn: ([reader]) => TxHash.fromField(reader.readField()), slots: 1 },
+  deserialization: { fn: ([reader]) => TxHash.fromField(reader.readField()) },
+  shape: ['scalar'],
 };
 
-export const TAG: TypeMapping<Tag> = {
+const TAG: TypeMapping<Tag> = {
   serialization: { fn: v => [v.value] },
-  deserialization: { fn: ([reader]) => new Tag(reader.readField()), slots: 1 },
-};
-
-export const POINT: TypeMapping<Point> = {
-  serialization: { fn: p => [p.toFields()] },
-  deserialization: {
-    fn: ([reader]) => Point.fromFields([reader.readField(), reader.readField()]),
-    slots: 1,
-  },
-};
-
-// ─── Struct Type Mappings ────────────────────────────────────────────────────
-
-export const BLOCK_HEADER: TypeMapping<BlockHeader> = {
-  serialization: { fn: v => v.toFields() },
-  deserialization: { fn: ([reader]) => BlockHeader.fromFields(reader.readFieldArray(BLOCK_HEADER_LENGTH)), slots: 1 },
+  deserialization: { fn: ([reader]) => new Tag(reader.readField()) },
+  shape: ['scalar'],
 };
 
-export const KEY_VALIDATION_REQUEST: TypeMapping<KeyValidationRequest> = {
-  serialization: { fn: v => v.toFields() },
-  deserialization: {
-    fn: ([reader]) => KeyValidationRequest.fromFields(reader.readFieldArray(KEY_VALIDATION_REQUEST_LENGTH)),
-    slots: 1,
-  },
-};
+export const POINT: TypeMapping<EmbeddedCurvePoint> = STRUCT([
+  { name: 'x', type: FIELD },
+  { name: 'y', type: FIELD },
+]);
 
-export const CONTRACT_INSTANCE: TypeMapping<ContractInstance> = {
-  serialization: {
-    fn: v => [
-      v.salt,
-      v.deployer.toField(),
-      v.currentContractClassId,
-      v.initializationHash,
-      v.immutablesHash,
-      ...v.publicKeys.toFields(),
-    ],
-  },
-};
-
-export const NULLIFIER_MEMBERSHIP_WITNESS: TypeMapping<NullifierMembershipWitness> = {
-  serialization: {
-    fn: (w: NullifierMembershipWitness) =>
-      w
-        .toNoirRepresentation()
-        .map(slot => (Array.isArray(slot) ? slot.map(s => Fr.fromString(s)) : Fr.fromString(slot as string))),
-  },
-};
-
-export const PUBLIC_DATA_WITNESS: TypeMapping<PublicDataWitness> = {
-  serialization: {
-    fn: (w: PublicDataWitness) =>
-      w
-        .toNoirRepresentation()
-        .map(slot => (Array.isArray(slot) ? slot.map(s => Fr.fromString(s)) : Fr.fromString(slot as string))),
-  },
-};
-
-export const MESSAGE_LOAD_ORACLE_INPUTS: TypeMapping<MessageLoadOracleInputs<typeof L1_TO_L2_MSG_TREE_HEIGHT>> = {
-  serialization: {
-    fn: (m: MessageLoadOracleInputs<typeof L1_TO_L2_MSG_TREE_HEIGHT>) =>
-      m
-        .toNoirRepresentation()
-        .map(slot => (Array.isArray(slot) ? slot.map(s => Fr.fromString(s)) : Fr.fromString(slot as string))),
-  },
+const LOG_SOURCE: TypeMapping<LogSource> = {
+  serialization: { fn: v => [new Fr(v)] },
+  deserialization: { fn: ([reader]) => logSourceFromField(reader.readField()) },
+  shape: ['scalar'],
 };
 
-export const UTILITY_CONTEXT: TypeMapping<UtilityContext> = {
-  serialization: {
-    fn: (ctx: UtilityContext) => [...ctx.blockHeader.toFields(), ctx.contractAddress.toField()],
-  },
+export const ETH_ADDRESS: TypeMapping<EthAddress> = {
+  serialization: { fn: v => [v.toField()] },
+  deserialization: { fn: ([reader]) => EthAddress.fromField(reader.readField()) },
+  shape: ['scalar'],
 };
 
-export const CALL_PRIVATE_RESULT: TypeMapping<{ endSideEffectCounter: Fr; returnsHash: Fr }> = {
-  serialization: { fn: v => [[v.endSideEffectCounter, v.returnsHash]] },
-};
+export const SLOT_NUMBER: TypeMapping<SlotNumber> = {
+  serialization: { fn: v => [new Fr(v)] },
+  shape: ['scalar'],
+};
+
+const APPEND_ONLY_TREE_SNAPSHOT: TypeMapping<AppendOnlyTreeSnapshot> = STRUCT<AppendOnlyTreeSnapshot>([
+  { name: 'root', type: FIELD },
+  { name: 'nextAvailableLeafIndex', type: U32 },
+]);
+
+const PARTIAL_STATE_REFERENCE: TypeMapping<PartialStateReference> = STRUCT<PartialStateReference>([
+  { name: 'noteHashTree', type: APPEND_ONLY_TREE_SNAPSHOT },
+  { name: 'nullifierTree', type: APPEND_ONLY_TREE_SNAPSHOT },
+  { name: 'publicDataTree', type: APPEND_ONLY_TREE_SNAPSHOT },
+]);
+
+const STATE_REFERENCE: TypeMapping<StateReference> = STRUCT<StateReference>([
+  { name: 'l1ToL2MessageTree', type: APPEND_ONLY_TREE_SNAPSHOT },
+  { name: 'partial', type: PARTIAL_STATE_REFERENCE },
+]);
+
+const GAS_FEES: TypeMapping<GasFees> = STRUCT<GasFees>([
+  { name: 'feePerDaGas', type: BIGINT },
+  { name: 'feePerL2Gas', type: BIGINT },
+]);
+
+const GLOBAL_VARIABLES: TypeMapping<GlobalVariables> = STRUCT<GlobalVariables>([
+  { 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: TypeMapping<BlockHeader> = STRUCT<BlockHeader>([
+  { 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: TypeMapping<KeyValidationRequest> = STRUCT<KeyValidationRequest>([
+  { name: 'pkMHash', type: FIELD },
+  { name: 'skApp', type: FIELD },
+]);
+
+const PUBLIC_KEYS: TypeMapping<PublicKeys> = STRUCT<PublicKeys>([
+  { 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: TypeMapping<ContractInstancePreimage> = STRUCT<ContractInstancePreimage>([
+  { 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: TypeMapping<NullifierLeaf> = STRUCT<NullifierLeaf>([{ name: 'nullifier', type: FIELD }]);
+
+const NULLIFIER_LEAF_PREIMAGE: TypeMapping<NullifierLeafPreimage> = STRUCT<NullifierLeafPreimage>([
+  { name: 'leaf', type: NULLIFIER_LEAF },
+  { name: 'nextKey', type: FIELD },
+  { name: 'nextIndex', type: BIGINT },
+]);
+
+export const NULLIFIER_MEMBERSHIP_WITNESS: TypeMapping<NullifierMembershipWitness> = STRUCT<NullifierMembershipWitness>(
+  [
+    { name: 'leafPreimage', type: NULLIFIER_LEAF_PREIMAGE },
+    { name: 'index', type: BIGINT },
+    { name: 'siblingPath', type: SIBLING_PATH(NULLIFIER_TREE_HEIGHT) },
+  ],
+);
+
+const PUBLIC_DATA_LEAF: TypeMapping<PublicDataTreeLeaf> = STRUCT<PublicDataTreeLeaf>([
+  { name: 'slot', type: FIELD },
+  { name: 'value', type: FIELD },
+]);
+
+const PUBLIC_DATA_LEAF_PREIMAGE: TypeMapping<PublicDataTreeLeafPreimage> = STRUCT<PublicDataTreeLeafPreimage>([
+  { name: 'leaf', type: PUBLIC_DATA_LEAF },
+  { name: 'nextKey', type: FIELD },
+  { name: 'nextIndex', type: BIGINT },
+]);
+
+export const PUBLIC_DATA_WITNESS: TypeMapping<PublicDataWitness> = STRUCT<PublicDataWitness>([
+  { 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: TypeMapping<MessageLoadOracleInputs<typeof L1_TO_L2_MSG_TREE_HEIGHT>> = STRUCT<
+  MessageLoadOracleInputs<typeof L1_TO_L2_MSG_TREE_HEIGHT>
+>([
+  { name: 'index', type: BIGINT },
+  { name: 'siblingPath', type: SIBLING_PATH(L1_TO_L2_MSG_TREE_HEIGHT) },
+]);
+
+export const UTILITY_CONTEXT: TypeMapping<UtilityContext> = STRUCT<UtilityContext>([
+  { name: 'blockHeader', type: BLOCK_HEADER },
+  { name: 'contractAddress', type: AZTEC_ADDRESS },
+  { name: 'msgSender', type: AZTEC_ADDRESS },
+]);
+
+export const CALL_PRIVATE_RESULT: TypeMapping<{ endSideEffectCounter: Fr; returnsHash: Fr }> = STRUCT([
+  { name: 'endSideEffectCounter', type: FIELD },
+  { name: 'returnsHash', type: FIELD },
+]);
 
 export const PUBLIC_KEYS_AND_PARTIAL_ADDRESS: TypeMapping<{
   publicKeys: PublicKeys;
   partialAddress: PartialAddress;
-}> = {
-  serialization: {
-    fn: v => [[...v.publicKeys.toFields(), v.partialAddress]],
-  },
-};
-
-export const CONTRACT_CLASS_LOG_INPUT: TypeMapping<ContractClassLog> = {
-  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,
-  },
-};
-
-export const TX_EFFECT: TypeMapping<TxEffect> = {
-  serialization: {
-    fn: (effect: TxEffect) => {
-      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(),
-        ]),
-      ] as (Fr | Fr[])[];
-    },
-  },
-};
+}> = STRUCT([
+  { name: 'publicKeys', type: PUBLIC_KEYS },
+  { name: 'partialAddress', type: FIELD },
+]);
+
+export const CONTRACT_CLASS_LOG: TypeMapping<ContractClassLogData> = 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: TypeMapping<RevertCode> = {
+  serialization: { fn: rc => [rc.toField()] },
+  shape: ['scalar'],
+};
+
+const PUBLIC_DATA_WRITE: TypeMapping<PublicDataWrite> = STRUCT<PublicDataWrite>([
+  { name: 'leafSlot', type: FIELD },
+  { name: 'value', type: FIELD },
+]);
+
+const PRIVATE_LOG: TypeMapping<PrivateLog> = STRUCT<PrivateLog>([
+  { name: 'fields', type: FIXED_ARRAY(FIELD, PRIVATE_LOG_SIZE_IN_FIELDS) },
+  { name: 'emittedLength', type: U32 },
+]);
+
+const FLAT_PUBLIC_LOGS: TypeMapping<FlatPublicLogs> = STRUCT<FlatPublicLogs>([
+  { name: 'length', type: U32 },
+  { name: 'payload', type: FIXED_ARRAY(FIELD, FLAT_PUBLIC_LOGS_PAYLOAD_LENGTH) },
+]);
+
+const CONTRACT_CLASS_LOG_ENTRY: TypeMapping<ContractClassLogData> = STRUCT<ContractClassLogData>([
+  { 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: TypeMapping<ContractClassLogData[]> = FIXED_ARRAY(
+  CONTRACT_CLASS_LOG_ENTRY,
+  MAX_CONTRACT_CLASS_LOGS_PER_TX,
+);
+
+export const TX_EFFECT: TypeMapping<TxEffectData> = STRUCT<TxEffectData>([
+  { 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: TypeMapping<NoteData> = {
   serialization: {
@@ -338,77 +484,161 @@ export const NOTE: TypeMapping<NoteData> = {
         note: noteData.note,
       }),
   },
-};
-
-export const PENDING_TAGGED_LOG: TypeMapping<PendingTaggedLog> = {
-  serialization: { fn: log => [log.toFields()] },
+  // 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: TypeMapping<NoteValidationRequest> = {
   deserialization: {
     fn: ([reader]) => NoteValidationRequest.fromFields(reader),
-    slots: 1,
   },
+  shape: ['variable'],
 };
 
 export const EVENT_VALIDATION_REQUEST: TypeMapping<EventValidationRequest> = {
   deserialization: {
     fn: ([reader]) => EventValidationRequest.fromFields(reader),
-    slots: 1,
   },
-};
-
-export const LOG_RETRIEVAL_REQUEST: TypeMapping<LogRetrievalRequest> = {
-  serialization: { fn: req => [req.toFields()] },
+  shape: ['variable'],
+};
+
+export const LOG_RETRIEVAL_REQUEST: TypeMapping<LogRetrievalRequest> = STRUCT<LogRetrievalRequest>([
+  { 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: TypeMapping<LogRetrievalResponse> = STRUCT<LogRetrievalResponse>([
+  { 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: BIGINT },
+  { name: 'blockHash', type: BLOCK_HASH },
+]);
+
+// `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: TypeMapping<ResolvedTx> = {
+  serialization: { fn: resolved => [resolved.toFields()] },
+  shape: [{ len: MAX_NOTE_HASHES_PER_TX + 5 }],
+};
+
+export const PENDING_TAGGED_LOG: TypeMapping<PendingTaggedLog> = STRUCT([
+  { name: 'log', type: FIXED_BOUNDED_VEC(FIELD, PRIVATE_LOG_SIZE_IN_FIELDS) },
+  { name: 'context', type: RESOLVED_TX },
+]);
+
+export const ORIGIN_BLOCK: TypeMapping<OriginBlock> = {
+  serialization: { fn: ob => [new Fr(ob.blockNumber), ob.blockHash] },
   deserialization: {
-    fn: ([reader]) => LogRetrievalRequest.fromFields(reader),
-    slots: 1,
+    fn: ([blockNumberReader, blockHashReader]) => ({
+      blockNumber: blockNumberReader.readField().toNumber(),
+      blockHash: blockHashReader.readField(),
+    }),
   },
+  shape: ['scalar', 'scalar'],
+};
+
+/** Read-side origin of a retractable fact, carrying the chain state of its origin block. */
+export const RETRACTABLE_FACT_ORIGIN: TypeMapping<RetractableFactOrigin> = {
+  serialization: { fn: o => [new Fr(o.blockNumber), o.blockHash, new Fr(o.blockState)] },
+  shape: ['scalar', 'scalar', 'scalar'],
 };
 
-export const LOG_RETRIEVAL_RESPONSE: TypeMapping<LogRetrievalResponse> = {
-  serialization: { fn: resp => [resp.toFields()] },
+// `facts` and `payload` each materialize to a single service-slot id, so a Fact occupies: factTypeId, the payload
+// array slot, and `OPTION(RETRACTABLE_FACT_ORIGIN)` (its discriminant plus RETRACTABLE_FACT_ORIGIN's three slots).
+export const FACT: TypeMapping<Fact> = {
+  serialization: {
+    fn: f => [
+      f.factTypeId,
+      f.payload.materializeSlot(v => FIELD.serialization!.fn(v).flat() as Fr[]),
+      ...OPTION(RETRACTABLE_FACT_ORIGIN).serialization!.fn(f.originBlock),
+    ],
+  },
+  shape: ['scalar', 'scalar', 'scalar', 'scalar', 'scalar', 'scalar'],
 };
 
-export const MESSAGE_CONTEXT: TypeMapping<MessageContext> = {
-  serialization: { fn: mc => [mc.toFields()] },
+export const FACT_COLLECTION: TypeMapping<FactCollection> = {
+  serialization: {
+    fn: c => [
+      c.contractAddress.toField(),
+      c.scope.toField(),
+      c.factCollectionTypeId,
+      c.factCollectionId,
+      c.facts.materializeSlot(v => FACT.serialization!.fn(v).flat() as Fr[]),
+    ],
+  },
+  shape: ['scalar', 'scalar', 'scalar', 'scalar', 'scalar'],
 };
 
 export const PROVIDED_SECRET: TypeMapping<ProvidedSecret> = {
   deserialization: {
-    fn: ([reader]) => ProvidedSecret.fromFields(reader),
-    slots: 1,
+    fn: ([reader]) => ({
+      secret: reader.readField(),
+      mode: appTaggingSecretKindFromDeliveryMode(BYTE.deserialization!.fn([reader])),
+    }),
   },
+  shape: [{ len: 2 }],
 };
 
 // ─── Combinator Type Mappings ────────────────────────────────────────────────
 
-/** `_height` is unused at runtime but lets TypeScript infer the exact `N` for `MembershipWitness<N>`. */
-export function MEMBERSHIP_WITNESS<N extends number>(_height: N): TypeMapping<MembershipWitness<N>> {
+function SIBLING_PATH<N extends number>(height: N): TypeMapping<SiblingPath<N>> {
   return {
-    serialization: {
-      fn: (witness: MembershipWitness<N>) => [new Fr(witness.leafIndex), [...witness.siblingPath]],
-    },
+    serialization: { fn: sp => [sp.toFields()] },
+    shape: [{ len: height }],
+  };
+}
+
+export function MEMBERSHIP_WITNESS<N extends number>(height: N): TypeMapping<MembershipWitness<N>> {
+  return STRUCT<MembershipWitness<N>>([
+    { name: 'leafIndex', type: BIGINT },
+    { name: 'siblingPath', type: FIXED_ARRAY(FIELD, height) },
+  ]);
+}
+
+export function ARRAY<T>(inner: TypeMapping<T>): TypeMapping<T[]> & { kind: 'array'; inner: TypeMapping<T> } {
+  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: { length: number }) => size.length * fieldWidth(inner.shape) }],
   };
 }
 
-export function ARRAY<T>(element: TypeMapping<T>): TypeMapping<T[]> {
+/**
+ * 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<T>(
+  element: TypeMapping<T>,
+  length: number,
+): TypeMapping<T[]> & { kind: 'fixed-array'; inner: TypeMapping<T>; length: number } {
+  const elementWidth = fieldWidth(element.shape);
   return {
+    kind: 'fixed-array',
+    inner: element,
+    length,
     serialization: element.serialization
-      ? { fn: values => [values.flatMap(v => element.serialization!.fn(v).flat())] }
+      ? { fn: values => [padArrayEnd(packElements(element, values), Fr.ZERO, length * elementWidth)] }
       : undefined,
     deserialization: element.deserialization
-      ? {
-          fn: ([reader]) => {
-            const result: T[] = [];
-            while (!reader.isFinished()) {
-              result.push(element.deserialization!.fn([reader]));
-            }
-            return result;
-          },
-          slots: 1,
-        }
+      ? { fn: ([reader]) => unpackElements(element, reader, length) }
       : undefined,
+    shape: [{ len: length * elementWidth }],
   };
 }
 
@@ -425,129 +655,310 @@ export function ARRAY<T>(element: TypeMapping<T>): TypeMapping<T[]> {
  * slot 1: Fr(2)                                  // actual length
  * ```
  */
-export function BOUNDED_VEC<T>(element: TypeMapping<T>): TypeMapping<BoundedVec<T>> {
+export function BOUNDED_VEC<T>(
+  inner: TypeMapping<T>,
+): TypeMapping<BoundedVec<T>> & { kind: 'bounded-vec'; inner: TypeMapping<T> } {
   return {
-    serialization: element.serialization
+    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}`);
             }
-            const flat = bv.data.flatMap(item => element.serialization!.fn(item).flat());
-            return [padArrayEnd(flat, Fr.ZERO, bv.maxLength * bv.elementSize), new Fr(bv.data.length)];
+            // 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: 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: T[] = [];
-            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<T>({ data: elements, maxLength });
           },
-          slots: 2,
         }
       : undefined,
+    // slot 0: variable-length storage; slot 1: the length scalar.
+    shape: [{ lenFrom: (size: { maxLength: number }) => 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`.
+ */
+export function FIXED_BOUNDED_VEC<T>(
+  element: TypeMapping<T>,
+  maxLength: number,
+): TypeMapping<T[]> & { kind: 'fixed-bounded-vec'; inner: TypeMapping<T>; maxLength: number } {
+  const width = fieldWidth(element.shape);
+  return {
+    kind: 'fixed-bounded-vec',
+    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<T>(inner: TypeMapping<T>): TypeMapping<Option<T>> {
+export function OPTION<T>(inner: TypeMapping<T>): TypeMapping<Option<T>> & { kind: 'option'; inner: TypeMapping<T> } {
   return {
+    kind: 'option',
+    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 [Fr.ZERO, ...zeroSlots];
-          },
+          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 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<T>(undefined as unknown as T);
+              return Option.none<T>();
             }
             return Option.some(inner.deserialization!.fn(innerReaders));
           },
-          slots: inner.deserialization.slots + 1,
         }
       : undefined,
+    // A leading discriminant slot followed by the inner's slots.
+    shape: ['scalar', ...inner.shape],
   };
 }
 
-/** A packed uint buffer (e.g. `[u8; N]` in Noir): 1 slot of packed uint values ↔ `Buffer`. */
-export function BUFFER(bitSize: number): TypeMapping<Buffer> {
+/**
+ * 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: number, length: number): TypeMapping<Buffer> {
   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,
+      fn: ([reader]) =>
+        fromUintArray(
+          reader.readFieldArray(length).map(f => f.toString()),
+          bitSize,
+        ),
     },
+    shape: [{ len: length }],
   };
 }
 
 export function EPHEMERAL_ARRAY<T>(element: TypeMapping<T>): TypeMapping<EphemeralArray<T>> {
-  // 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: TypeMapping<T> | undefined = element.deserialization
     ? {
         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 {
     serialization: element.serialization
-      ? { fn: ea => [ea.materializeSlot(v => element.serialization!.fn(v).flat() as Fr[])] }
+      ? { fn: ea => [ea.materializeSlot(v => serializeElement(element, v))] }
       : undefined,
     deserialization: rowElement
-      ? { fn: ([reader]) => EphemeralArray.fromSlot(reader.readField(), rowElement), slots: 1 }
+      ? { fn: ([reader]) => EphemeralArray.fromSlot(reader.readField(), rowElement) }
       : undefined,
+    // A single slot carrying the array's service-slot id.
+    shape: ['scalar'],
   };
 }
+
+/** A named field within a {@link STRUCT}: it owns however many wire slots its {@link TypeMapping} declares. */
+export type StructField<TName extends string = string, T = any> = { name: TName; type: TypeMapping<T> };
+
+/**
+ * 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<T>(
+  fields: readonly StructField[],
+): TypeMapping<T> & { kind: 'struct'; fields: readonly StructField[] } {
+  return {
+    kind: 'struct',
+    fields,
+    serialization: fields.every(f => f.type.serialization)
+      ? {
+          fn: (value: T) => {
+            const props = value as any;
+            return fields.flatMap(f => f.type.serialization!.fn(props[f.name]));
+          },
+        }
+      : undefined,
+    deserialization: fields.every(f => f.type.deserialization)
+      ? {
+          fn: readers => {
+            const props: Record<string, unknown> = {};
+            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 as T;
+          },
+        }
+      : 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: TypeMapping): number {
+  return mapping.shape.length;
+}
+
+/** Number of fields a fully-static shape occupies, or `undefined` if any slot is variable-width. */
+export function tryFieldWidth(shape: SlotShape[]): number | undefined {
+  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: SlotShape[]): number {
+  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: Fr[], shape: SlotShape[]): FieldReader[] {
+  const readers: FieldReader[] = [];
+  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<T>(element: TypeMapping<T>, value: T): Fr[] {
+  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<T>(element: TypeMapping<T>, fields: Fr[]): T {
+  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<T>(element: TypeMapping<T>, values: T[]): Fr[] {
+  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<T>(element: TypeMapping<T>, reader: FieldReader, count: number): T[] {
+  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: SlotShape[], size: unknown): (Fr | Fr[])[] {
+  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<Fr>(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<Fr>(slot.lenFrom(size)).fill(Fr.ZERO);
+  });
+}