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

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,96 @@ 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 { type ACVMField, fromUintArray } from '@aztec/simulator/client';
+import { MembershipWitness, type SiblingPath } from '@aztec/foundation/trees';
+import type { ACVMField } from '@aztec/simulator/client';
 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 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,
+  type OriginBlockState,
+  type RetractableFactOrigin,
+  originBlockStateFromNumber,
+} 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,28 +106,57 @@ 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`.
  */
 export interface TypeMapping<T = any> {
+  /**
+   * Discriminant for this mapping's shape: which scalar or combinator it is. The `is*Mapping` guards switch on it, and
+   * the combinators tag it (`'array'`, `'option'`, `'struct'`, ...). For a scalar it also names the Noir-declared type
+   * (`'field'`, `'u32'`), which is then its {@link label}.
+   */
+  kind: string;
+  /**
+   * The wire-structural Noir type string the oracle interface hash is computed from:
+   * - a scalar's is its bare `kind` (`'field'`);
+   * - a combinator's is built from its inner mappings' labels (`'array(field,4)'`, `'option(u32)'`);
+   * - a struct's is a nameless `'{field,u32}'`, with nested struct labels spliced into the parent.
+   *
+   * The label encodes exactly what the wire does, so anything the wire tolerates (field names, struct-in-struct
+   * nesting, a TS wrapper over a Noir primitive like `TX_HASH` over `Field`) shares a label — and mappings sharing a
+   * label must be wire-equivalent.
+   */
+  label: string;
   serialization?: {
     /** Convert a typed value to ACVM output slot(s). */
     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>;
@@ -99,65 +176,91 @@ export function assertReadersConsumed(readers: FieldReader[]): void {
 
 // ─── Scalar Type Mappings ────────────────────────────────────────────────────
 
-export const FIELD: TypeMapping<Fr> = {
+/**
+ * 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<T>(mapping: Omit<TypeMapping<T>, 'label'>): TypeMapping<T> {
+  return { ...mapping, label: mapping.kind };
+}
+
+/** A {@link LEAF} occupying a single `'scalar'` wire slot, so callers omit the shape. */
+export function SCALAR<T>(mapping: Omit<TypeMapping<T>, 'label' | 'shape'>): TypeMapping<T> {
+  return LEAF({ ...mapping, shape: ['scalar'] });
+}
+
+export const FIELD: TypeMapping<Fr> = SCALAR({
+  kind: 'field',
   serialization: { fn: v => [v] },
-  deserialization: { fn: ([reader]) => reader.readField(), slots: 1 },
-};
+  deserialization: { fn: ([reader]) => reader.readField() },
+});
 
-export const BOOL: TypeMapping<boolean> = {
+export const BOOL: TypeMapping<boolean> = SCALAR({
+  kind: 'bool',
   serialization: { fn: v => [new Fr(v ? 1n : 0n)] },
-  deserialization: { fn: ([reader]) => !reader.readField().isZero(), slots: 1 },
-};
+  deserialization: { fn: ([reader]) => !reader.readField().isZero() },
+});
 
-export const U32: TypeMapping<number> = {
+export const U32: TypeMapping<number> = 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,
-  },
-};
+  deserialization: { fn: ([reader]) => Number(uintFromField(reader.readField(), 32)) },
+});
 
-export const BLOCK_NUMBER: TypeMapping<BlockNumber> = {
-  serialization: { fn: v => [new Fr(v)] },
-  deserialization: { fn: ([reader]) => BlockNumber(reader.readField().toNumber()), slots: 1 },
-};
+export const BLOCK_NUMBER: TypeMapping<BlockNumber> = ALIAS(U32, {
+  wrap: v => BlockNumber(v),
+  unwrap: v => v,
+});
 
-/** A u8 byte: serializes to a single Fr; deserializes from a single Fr to a number in [0, 255]. */
-export const BYTE: TypeMapping<number> = {
+export const U8: TypeMapping<number> = SCALAR({
+  kind: 'u8',
   serialization: { fn: byte => [new Fr(byte)] },
+  deserialization: { fn: ([reader]) => Number(uintFromField(reader.readField(), 8)) },
+});
+
+// Noir passes `MessageDelivery` onchain variants here.
+export const DELIVERY_MODE: TypeMapping<AppTaggingSecretKind> = SCALAR({
+  kind: 'onchain-delivery-mode',
   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: readers => appTaggingSecretKindFromDeliveryMode(U8.deserialization!.fn(readers)),
   },
-};
+});
 
-// Noir passes `MessageDelivery` onchain variants here.
-export const DELIVERY_MODE: TypeMapping<AppTaggingSecretKind> = {
+export const RESOLVED_TAGGING_STRATEGY: TypeMapping<ResolvedTaggingStrategy> = LEAF({
+  kind: 'resolved-tagging-strategy',
+  serialization: { fn: resolved => resolvedTaggingStrategyToFields(resolved) },
   deserialization: {
-    fn: readers => appTaggingSecretKindFromDeliveryMode(BYTE.deserialization!.fn(readers)),
-    slots: BYTE.deserialization!.slots,
+    fn: ([kindReader, secretReader]) =>
+      resolvedTaggingStrategyFromFields(kindReader.readField().toNumber(), secretReader.readField()),
   },
-};
+  shape: ['scalar', 'scalar'],
+});
 
-export const BIGINT: TypeMapping<bigint> = {
+export const BIGINT: TypeMapping<bigint> = ALIAS(FIELD, {
+  wrap: f => f.toBigInt(),
+  unwrap: v => new Fr(v),
+});
+
+export const U64: TypeMapping<bigint> = SCALAR({
+  kind: 'u64',
   serialization: { fn: v => [new Fr(v)] },
-  deserialization: { fn: ([reader]) => reader.readField().toBigInt(), slots: 1 },
-};
+  deserialization: { fn: ([reader]) => uintFromField(reader.readField(), 64) },
+});
+
+export const U128: TypeMapping<bigint> = SCALAR({
+  kind: 'u128',
+  serialization: { fn: v => [new Fr(v)] },
+  deserialization: { fn: ([reader]) => uintFromField(reader.readField(), 128) },
+});
+
+export const LEAF_INDEX: TypeMapping<number> = 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: TypeMapping<string> = {
+export const STR: TypeMapping<string> = LEAF({
+  kind: 'str',
   serialization: { fn: str => [Array.from(Buffer.from(str, 'utf-8')).map(b => new Fr(b))] },
   deserialization: {
     fn: ([reader]) => {
@@ -167,165 +270,234 @@ export const STR: TypeMapping<string> = {
       }
       return chars.join('');
     },
-    slots: 1,
   },
-};
+  shape: ['variable'],
+});
 
-export const AZTEC_ADDRESS: TypeMapping<AztecAddress> = {
+export const AZTEC_ADDRESS: TypeMapping<AztecAddress> = SCALAR({
+  kind: 'aztec-address',
   serialization: { fn: v => [v.toField()] },
-  deserialization: { fn: ([reader]) => AztecAddress.fromField(reader.readField()), slots: 1 },
-};
+  deserialization: { fn: ([reader]) => AztecAddress.fromFieldUnsafe(reader.readField()) },
+});
 
-export const BLOCK_HASH: TypeMapping<BlockHash> = {
-  serialization: { fn: v => [new Fr(v.toBuffer())] },
-  deserialization: { fn: ([reader]) => new BlockHash(reader.readField()), slots: 1 },
-};
+export const BLOCK_HASH: TypeMapping<BlockHash> = ALIAS(FIELD, {
+  wrap: f => new BlockHash(f),
+  unwrap: v => new Fr(v.toBuffer()),
+});
 
-export const FUNCTION_SELECTOR: TypeMapping<FunctionSelector> = {
+export const FUNCTION_SELECTOR: TypeMapping<FunctionSelector> = SCALAR({
+  kind: 'function-selector',
   serialization: { fn: v => [v.toField()] },
-  deserialization: { fn: ([reader]) => FunctionSelector.fromField(reader.readField()), slots: 1 },
-};
+  deserialization: { fn: ([reader]) => FunctionSelector.fromField(reader.readField()) },
+});
+
+export const NOTE_SELECTOR: TypeMapping<NoteSelector> = ALIAS(FIELD, {
+  wrap: f => NoteSelector.fromField(f),
+  unwrap: v => v.toField(),
+});
+
+export const TX_HASH: TypeMapping<TxHash> = ALIAS(FIELD, {
+  wrap: f => TxHash.fromField(f),
+  unwrap: v => v.hash,
+});
 
-export const NOTE_SELECTOR: TypeMapping<NoteSelector> = {
+const TAG: TypeMapping<Tag> = ALIAS(FIELD, {
+  wrap: f => new Tag(f),
+  unwrap: v => v.value,
+});
+
+export const POINT: TypeMapping<EmbeddedCurvePoint> = STRUCT([
+  { name: 'x', type: FIELD },
+  { name: 'y', type: FIELD },
+]);
+
+const LOG_SOURCE: TypeMapping<LogSource> = SCALAR({
+  kind: 'log-source',
+  serialization: { fn: v => [new Fr(v)] },
+  deserialization: { fn: ([reader]) => logSourceFromField(reader.readField()) },
+});
+
+export const ETH_ADDRESS: TypeMapping<EthAddress> = SCALAR({
+  kind: 'eth-address',
   serialization: { fn: v => [v.toField()] },
-  deserialization: { fn: ([reader]) => NoteSelector.fromField(reader.readField()), slots: 1 },
-};
+  deserialization: { fn: ([reader]) => EthAddress.fromField(reader.readField()) },
+});
 
-export const TX_HASH: TypeMapping<TxHash> = {
-  serialization: { fn: v => [v.hash] },
-  deserialization: { fn: ([reader]) => TxHash.fromField(reader.readField()), slots: 1 },
-};
+export const SLOT_NUMBER: TypeMapping<SlotNumber> = ALIAS(FIELD, {
+  unwrap: v => new Fr(v),
+});
 
-export const TAG: TypeMapping<Tag> = {
-  serialization: { fn: v => [v.value] },
-  deserialization: { fn: ([reader]) => new Tag(reader.readField()), slots: 1 },
-};
+const APPEND_ONLY_TREE_SNAPSHOT: TypeMapping<AppendOnlyTreeSnapshot> = STRUCT<AppendOnlyTreeSnapshot>([
+  { name: 'root', type: FIELD },
+  { name: 'nextAvailableLeafIndex', type: LEAF_INDEX },
+]);
 
-export const POINT: TypeMapping<Point> = {
-  serialization: { fn: p => [p.toFields()] },
-  deserialization: {
-    fn: ([reader]) => Point.fromFields([reader.readField(), reader.readField()]),
-    slots: 1,
-  },
-};
+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 },
+]);
 
-// ─── Struct Type Mappings ────────────────────────────────────────────────────
+const STATE_REFERENCE: TypeMapping<StateReference> = STRUCT<StateReference>([
+  { name: 'l1ToL2MessageTree', type: APPEND_ONLY_TREE_SNAPSHOT },
+  { name: 'partial', type: PARTIAL_STATE_REFERENCE },
+]);
 
-export const BLOCK_HEADER: TypeMapping<BlockHeader> = {
-  serialization: { fn: v => v.toFields() },
-  deserialization: { fn: ([reader]) => BlockHeader.fromFields(reader.readFieldArray(BLOCK_HEADER_LENGTH)), slots: 1 },
-};
+const GAS_FEES: TypeMapping<GasFees> = STRUCT<GasFees>([
+  { name: 'feePerDaGas', type: U128 },
+  { name: 'feePerL2Gas', type: U128 },
+]);
 
-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,
-  },
-};
+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: U64 },
+  { name: 'coinbase', type: ETH_ADDRESS },
+  { name: 'feeRecipient', type: AZTEC_ADDRESS },
+  { name: 'gasFees', type: GAS_FEES },
+]);
 
-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 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 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 KEY_VALIDATION_REQUEST: TypeMapping<KeyValidationRequest> = STRUCT<KeyValidationRequest>([
+  { name: 'pkMHash', type: FIELD },
+  { name: 'skApp', type: FIELD },
+]);
 
-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))),
-  },
-};
+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 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))),
-  },
-};
+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 },
+]);
 
-export const UTILITY_CONTEXT: TypeMapping<UtilityContext> = {
-  serialization: {
-    fn: (ctx: UtilityContext) => [...ctx.blockHeader.toFields(), ctx.contractAddress.toField()],
-  },
-};
+const NULLIFIER_LEAF: TypeMapping<NullifierLeaf> = STRUCT<NullifierLeaf>([{ name: 'nullifier', type: FIELD }]);
 
-export const CALL_PRIVATE_RESULT: TypeMapping<{ endSideEffectCounter: Fr; returnsHash: Fr }> = {
-  serialization: { fn: v => [[v.endSideEffectCounter, v.returnsHash]] },
-};
+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]],
-  },
-};
+}> = STRUCT([
+  { name: 'publicKeys', type: PUBLIC_KEYS },
+  { name: 'partialAddress', type: FIELD },
+]);
 
-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 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 },
+]);
 
-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[])[];
-    },
-  },
-};
+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 NOTE: TypeMapping<NoteData> = {
+export const TX_EFFECT: TypeMapping<TxEffectData> = STRUCT<TxEffectData>([
+  { 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: TypeMapping<NoteData> = LEAF({
+  kind: 'note',
   serialization: {
     fn: noteData =>
       packAsHintedNote({
@@ -338,77 +510,168 @@ 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> = {
+export const NOTE_VALIDATION_REQUEST: TypeMapping<NoteValidationRequest> = LEAF({
+  kind: 'note-validation-request',
   deserialization: {
     fn: ([reader]) => NoteValidationRequest.fromFields(reader),
-    slots: 1,
   },
-};
+  shape: ['variable'],
+});
 
-export const EVENT_VALIDATION_REQUEST: TypeMapping<EventValidationRequest> = {
+export const EVENT_VALIDATION_REQUEST: TypeMapping<EventValidationRequest> = LEAF({
+  kind: 'event-validation-request',
   deserialization: {
     fn: ([reader]) => EventValidationRequest.fromFields(reader),
-    slots: 1,
   },
-};
+  shape: ['variable'],
+});
 
-export const LOG_RETRIEVAL_REQUEST: TypeMapping<LogRetrievalRequest> = {
-  serialization: { fn: req => [req.toFields()] },
-  deserialization: {
-    fn: ([reader]) => LogRetrievalRequest.fromFields(reader),
-    slots: 1,
-  },
-};
+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> = {
-  serialization: { fn: resp => [resp.toFields()] },
-};
+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: U64 },
+  { name: 'blockHash', type: BLOCK_HASH },
+]);
 
-export const MESSAGE_CONTEXT: TypeMapping<MessageContext> = {
-  serialization: { fn: mc => [mc.toFields()] },
-};
+export const RESOLVED_TX: TypeMapping<ResolvedTx> = 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 PROVIDED_SECRET: TypeMapping<ProvidedSecret> = {
-  deserialization: {
-    fn: ([reader]) => ProvidedSecret.fromFields(reader),
-    slots: 1,
-  },
-};
+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> = STRUCT([
+  { name: 'blockNumber', type: U32 },
+  { name: 'blockHash', type: FIELD },
+]);
+
+const ORIGIN_BLOCK_STATE: TypeMapping<OriginBlockState> = SCALAR({
+  kind: 'origin-block-state',
+  serialization: { fn: v => [new Fr(v)] },
+  deserialization: { fn: ([reader]) => originBlockStateFromNumber(reader.readField().toNumber()) },
+});
+
+/** Read-side origin of a retractable fact, carrying the chain state of its origin block. */
+export const RETRACTABLE_FACT_ORIGIN: TypeMapping<RetractableFactOrigin> = STRUCT([
+  { name: 'blockNumber', type: U32 },
+  { name: 'blockHash', type: FIELD },
+  { name: 'blockState', type: ORIGIN_BLOCK_STATE },
+]);
+
+export const FACT: TypeMapping<Fact> = STRUCT([
+  { name: 'factTypeId', type: FIELD },
+  { name: 'payload', type: EPHEMERAL_ARRAY(FIELD) },
+  { name: 'originBlock', type: OPTION(RETRACTABLE_FACT_ORIGIN) },
+]);
+
+export const FACT_COLLECTION: TypeMapping<FactCollection> = 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: TypeMapping<ProvidedSecret> = 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<N extends number>(_height: N): TypeMapping<MembershipWitness<N>> {
+/**
+ * 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<B, T>(
+  base: TypeMapping<B>,
+  conversions: { wrap?: (value: B) => T; unwrap?: (value: T) => B },
+): TypeMapping<T> {
+  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<N extends number>(height: N): TypeMapping<SiblingPath<N>> {
+  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: 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>): ArrayMapping<T> {
   return {
-    serialization: {
-      fn: (witness: MembershipWitness<N>) => [new Fr(witness.leafIndex), [...witness.siblingPath]],
-    },
+    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: { 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): FixedArrayMapping<T> {
+  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())] }
+      ? { 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 }],
   };
 }
 
@@ -419,135 +682,371 @@ export function ARRAY<T>(element: TypeMapping<T>): TypeMapping<T[]> {
  *
  * 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<T>(element: TypeMapping<T>): TypeMapping<BoundedVec<T>> {
+export function BOUNDED_VEC<T>(inner: TypeMapping<T>): BoundedVecMapping<T> {
   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());
-            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'],
   };
 }
 
 /**
- * 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.
+ * 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): FixedBoundedVecMapping<T> {
+  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>`, adding a leading discriminant slot.
+ *
+ * For the `None` case, the inner's slots must still be present on the wire as zero-padding (so `Some` and `None` have
+ * identical size). That padding is derived entirely from `inner.shape`.
  *
- * @example Serializing `Option.some(AztecAddress.fromField(Fr(42)))` with `OPTION(AZTEC_ADDRESS)`:
+ * @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>): OptionMapping<T> {
   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 [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> {
-  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,
-    },
-  };
-}
-
-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.
+export function EPHEMERAL_ARRAY<T>(element: TypeMapping<T>): EphemeralArrayMapping<T> {
+  // 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
     ? {
+        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() 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[]): StructMapping<T> {
+  return {
+    kind: 'struct',
+    label: `{${structFieldLabels(fields)}}`,
+    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),
+  };
+}
+
+/**
+ * The composite `TypeMapping`s (`ARRAY`/`BOUNDED_VEC`/`OPTION`/`STRUCT`/`FIXED_ARRAY`/`FIXED_BOUNDED_VEC`/
+ * `EPHEMERAL_ARRAY`), discriminated by `kind`. The combinators attach `kind` plus the inner mapping(s) at construction;
+ * the registry erases params to the base `TypeMapping`, so the guards below recover the structure for recursion.
+ */
+export type ArrayMapping<T = any> = TypeMapping<T[]> & { kind: 'array'; inner: TypeMapping<T> };
+export type BoundedVecMapping<T = any> = TypeMapping<BoundedVec<T>> & { kind: 'bounded-vec'; inner: TypeMapping<T> };
+export type OptionMapping<T = any> = TypeMapping<Option<T>> & { kind: 'option'; inner: TypeMapping<T> };
+export type StructMapping<T = any> = TypeMapping<T> & { kind: 'struct'; fields: readonly StructField[] };
+export type FixedArrayMapping<T = any> = TypeMapping<T[]> & {
+  kind: 'fixed-array';
+  inner: TypeMapping<T>;
+  length: number;
+};
+export type FixedBoundedVecMapping<T = any> = TypeMapping<T[]> & {
+  kind: 'fixed-bounded-vec';
+  inner: TypeMapping<T>;
+  maxLength: number;
+};
+export type EphemeralArrayMapping<T = any> = TypeMapping<EphemeralArray<T>> & {
+  kind: 'ephemeral-array';
+  inner: TypeMapping<T>;
+};
+export type CompositeMapping =
+  | ArrayMapping
+  | BoundedVecMapping
+  | OptionMapping
+  | StructMapping
+  | FixedArrayMapping
+  | FixedBoundedVecMapping
+  | EphemeralArrayMapping;
+
+export function isArrayMapping(type: TypeMapping<any>): type is ArrayMapping {
+  return type.kind === 'array';
+}
+export function isBoundedVecMapping(type: TypeMapping<any>): type is BoundedVecMapping {
+  return type.kind === 'bounded-vec';
+}
+export function isOptionMapping(type: TypeMapping<any>): type is OptionMapping {
+  return type.kind === 'option';
+}
+export function isStructMapping(type: TypeMapping<any>): type is StructMapping {
+  return type.kind === 'struct';
+}
+export function isFixedArrayMapping(type: TypeMapping<any>): type is FixedArrayMapping {
+  return type.kind === 'fixed-array';
+}
+export function isFixedBoundedVecMapping(type: TypeMapping<any>): type is FixedBoundedVecMapping {
+  return type.kind === 'fixed-bounded-vec';
+}
+export function isEphemeralArrayMapping(type: TypeMapping<any>): type is EphemeralArrayMapping {
+  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: readonly StructField[]): string {
+  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: Fr, bits: number): bigint {
+  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: 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);
+  });
+}