@aztec/pxe 0.0.1-commit.a5db02d → 0.0.1-commit.aa0c64f

package/src/contract_function_simulator/oracle/oracle_type_mappings.ts

@@ -19,9 +19,9 @@ import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { FieldReader } from '@aztec/foundation/serialize';
 import { MembershipWitness, type SiblingPath } from '@aztec/foundation/trees';
-import { type ACVMField, fromUintArray } from '@aztec/simulator/client';
+import type { ACVMField } from '@aztec/simulator/client';
 import { FunctionSelector, NoteSelector } from '@aztec/stdlib/abi';
-import { PublicDataWrite, RevertCode } from '@aztec/stdlib/avm';
+import { PublicDataWrite } from '@aztec/stdlib/avm';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { BlockHash } from '@aztec/stdlib/block';
 import type { ContractInstancePreimage, PartialAddress } from '@aztec/stdlib/contract';
@@ -52,7 +52,12 @@ import {
   TxHash,
 } from '@aztec/stdlib/tx';
 
-import type { OriginBlock, RetractableFactOrigin } from '../../storage/fact_store/index.js';
+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';
@@ -118,6 +123,23 @@ export type SlotShape = 'scalar' | { len: number } | 'variable' | { lenFrom: (si
  * 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[])[];
@@ -154,78 +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() },
-  shape: ['scalar'],
-};
+});
 
-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() },
-  shape: ['scalar'],
-};
+});
 
-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);
-    },
-  },
-  shape: ['scalar'],
-};
+  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()) },
-  shape: ['scalar'],
-};
+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]) => {
-      const value = reader.readField().toBigInt();
-      if (value > 0xffn) {
-        throw new Error(`BYTE overflow: value ${value} exceeds u8 max (255)`);
-      }
-      return Number(value);
-    },
-  },
-  shape: ['scalar'],
-};
+  deserialization: { fn: ([reader]) => Number(uintFromField(reader.readField(), 8)) },
+});
 
 // Noir passes `MessageDelivery` onchain variants here.
-export const DELIVERY_MODE: TypeMapping<AppTaggingSecretKind> = {
+export const DELIVERY_MODE: TypeMapping<AppTaggingSecretKind> = SCALAR({
+  kind: 'onchain-delivery-mode',
   deserialization: {
-    fn: readers => appTaggingSecretKindFromDeliveryMode(BYTE.deserialization!.fn(readers)),
+    fn: readers => appTaggingSecretKindFromDeliveryMode(U8.deserialization!.fn(readers)),
   },
-  shape: BYTE.shape,
-};
+});
 
-export const RESOLVED_TAGGING_STRATEGY: TypeMapping<ResolvedTaggingStrategy> = {
+export const RESOLVED_TAGGING_STRATEGY: TypeMapping<ResolvedTaggingStrategy> = LEAF({
+  kind: 'resolved-tagging-strategy',
   serialization: { fn: resolved => resolvedTaggingStrategyToFields(resolved) },
   deserialization: {
     fn: ([kindReader, secretReader]) =>
       resolvedTaggingStrategyFromFields(kindReader.readField().toNumber(), secretReader.readField()),
   },
   shape: ['scalar', 'scalar'],
-};
+});
 
-export const BIGINT: 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() },
-  shape: ['scalar'],
-};
+  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]) => {
@@ -237,69 +272,64 @@ export const STR: TypeMapping<string> = {
     },
   },
   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.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()) },
-  shape: ['scalar'],
-};
+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()) },
-  shape: ['scalar'],
-};
+});
 
-export const NOTE_SELECTOR: TypeMapping<NoteSelector> = {
-  serialization: { fn: v => [v.toField()] },
-  deserialization: { fn: ([reader]) => NoteSelector.fromField(reader.readField()) },
-  shape: ['scalar'],
-};
+export const NOTE_SELECTOR: TypeMapping<NoteSelector> = ALIAS(FIELD, {
+  wrap: f => NoteSelector.fromField(f),
+  unwrap: v => v.toField(),
+});
 
-export const TX_HASH: TypeMapping<TxHash> = {
-  serialization: { fn: v => [v.hash] },
-  deserialization: { fn: ([reader]) => TxHash.fromField(reader.readField()) },
-  shape: ['scalar'],
-};
+export const TX_HASH: TypeMapping<TxHash> = ALIAS(FIELD, {
+  wrap: f => TxHash.fromField(f),
+  unwrap: v => v.hash,
+});
 
-const TAG: TypeMapping<Tag> = {
-  serialization: { fn: v => [v.value] },
-  deserialization: { fn: ([reader]) => new Tag(reader.readField()) },
-  shape: ['scalar'],
-};
+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> = {
+const LOG_SOURCE: TypeMapping<LogSource> = SCALAR({
+  kind: 'log-source',
   serialization: { fn: v => [new Fr(v)] },
   deserialization: { fn: ([reader]) => logSourceFromField(reader.readField()) },
-  shape: ['scalar'],
-};
+});
 
-export const ETH_ADDRESS: TypeMapping<EthAddress> = {
+export const ETH_ADDRESS: TypeMapping<EthAddress> = SCALAR({
+  kind: 'eth-address',
   serialization: { fn: v => [v.toField()] },
   deserialization: { fn: ([reader]) => EthAddress.fromField(reader.readField()) },
-  shape: ['scalar'],
-};
+});
 
-export const SLOT_NUMBER: TypeMapping<SlotNumber> = {
-  serialization: { fn: v => [new Fr(v)] },
-  shape: ['scalar'],
-};
+export const SLOT_NUMBER: TypeMapping<SlotNumber> = ALIAS(FIELD, {
+  unwrap: v => new Fr(v),
+});
 
 const APPEND_ONLY_TREE_SNAPSHOT: TypeMapping<AppendOnlyTreeSnapshot> = STRUCT<AppendOnlyTreeSnapshot>([
   { name: 'root', type: FIELD },
-  { name: 'nextAvailableLeafIndex', type: U32 },
+  { name: 'nextAvailableLeafIndex', type: LEAF_INDEX },
 ]);
 
 const PARTIAL_STATE_REFERENCE: TypeMapping<PartialStateReference> = STRUCT<PartialStateReference>([
@@ -314,8 +344,8 @@ const STATE_REFERENCE: TypeMapping<StateReference> = STRUCT<StateReference>([
 ]);
 
 const GAS_FEES: TypeMapping<GasFees> = STRUCT<GasFees>([
-  { name: 'feePerDaGas', type: BIGINT },
-  { name: 'feePerL2Gas', type: BIGINT },
+  { name: 'feePerDaGas', type: U128 },
+  { name: 'feePerL2Gas', type: U128 },
 ]);
 
 const GLOBAL_VARIABLES: TypeMapping<GlobalVariables> = STRUCT<GlobalVariables>([
@@ -323,7 +353,7 @@ const GLOBAL_VARIABLES: TypeMapping<GlobalVariables> = STRUCT<GlobalVariables>([
   { name: 'version', type: FIELD },
   { name: 'blockNumber', type: BLOCK_NUMBER },
   { name: 'slotNumber', type: SLOT_NUMBER },
-  { name: 'timestamp', type: BIGINT },
+  { name: 'timestamp', type: U64 },
   { name: 'coinbase', type: ETH_ADDRESS },
   { name: 'feeRecipient', type: AZTEC_ADDRESS },
   { name: 'gasFees', type: GAS_FEES },
@@ -427,11 +457,6 @@ export const CONTRACT_CLASS_LOG: TypeMapping<ContractClassLogData> = STRUCT([
   { 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 },
@@ -459,7 +484,7 @@ const CONTRACT_CLASS_LOGS: TypeMapping<ContractClassLogData[]> = FIXED_ARRAY(
 );
 
 export const TX_EFFECT: TypeMapping<TxEffectData> = STRUCT<TxEffectData>([
-  { name: 'revertCode', type: REVERT_CODE },
+  { name: 'revertCode', type: U8 },
   { name: 'txHash', type: TX_HASH },
   { name: 'transactionFee', type: FIELD },
   { name: 'noteHashes', type: FIXED_ARRAY(FIELD, MAX_NOTE_HASHES_PER_TX) },
@@ -471,7 +496,8 @@ export const TX_EFFECT: TypeMapping<TxEffectData> = STRUCT<TxEffectData>([
   { name: 'contractClassLogs', type: CONTRACT_CLASS_LOGS },
 ]);
 
-export const NOTE: TypeMapping<NoteData> = {
+export const NOTE: TypeMapping<NoteData> = LEAF({
+  kind: 'note',
   serialization: {
     fn: noteData =>
       packAsHintedNote({
@@ -487,21 +513,23 @@ export const NOTE: TypeMapping<NoteData> = {
   // 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),
   },
   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),
   },
   shape: ['variable'],
-};
+});
 
 export const LOG_RETRIEVAL_REQUEST: TypeMapping<LogRetrievalRequest> = STRUCT<LogRetrievalRequest>([
   { name: 'contractAddress', type: AZTEC_ADDRESS },
@@ -517,82 +545,88 @@ export const LOG_RETRIEVAL_RESPONSE: TypeMapping<LogRetrievalResponse> = STRUCT<
   { 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: 'blockTimestamp', type: U64 },
   { 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 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 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: ([blockNumberReader, blockHashReader]) => ({
-      blockNumber: blockNumberReader.readField().toNumber(),
-      blockHash: blockHashReader.readField(),
-    }),
-  },
-  shape: ['scalar', 'scalar'],
-};
+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> = {
-  serialization: { fn: o => [new Fr(o.blockNumber), o.blockHash, new Fr(o.blockState)] },
-  shape: ['scalar', 'scalar', 'scalar'],
-};
+export const RETRACTABLE_FACT_ORIGIN: TypeMapping<RetractableFactOrigin> = STRUCT([
+  { name: 'blockNumber', type: U32 },
+  { name: 'blockHash', type: FIELD },
+  { name: 'blockState', type: ORIGIN_BLOCK_STATE },
+]);
 
-// `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 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> = {
-  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 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> = {
-  deserialization: {
-    fn: ([reader]) => ({
-      secret: reader.readField(),
-      mode: appTaggingSecretKindFromDeliveryMode(BYTE.deserialization!.fn([reader])),
-    }),
-  },
-  shape: [{ len: 2 }],
-};
+export const PROVIDED_SECRET: TypeMapping<ProvidedSecret> = STRUCT([
+  { name: 'secret', type: FIELD },
+  { name: 'mode', type: DELIVERY_MODE },
+]);
 
 // ─── Combinator Type Mappings ────────────────────────────────────────────────
 
-function SIBLING_PATH<N extends number>(height: N): TypeMapping<SiblingPath<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>> {
@@ -602,9 +636,10 @@ export function MEMBERSHIP_WITNESS<N extends number>(height: N): TypeMapping<Mem
   ]);
 }
 
-export function ARRAY<T>(inner: TypeMapping<T>): TypeMapping<T[]> & { kind: 'array'; inner: TypeMapping<T> } {
+export function ARRAY<T>(inner: TypeMapping<T>): ArrayMapping<T> {
   return {
     kind: 'array',
+    label: `array(${inner.label})`,
     inner,
     serialization: inner.serialization ? { fn: values => [packElements(inner, values)] } : undefined,
     deserialization: inner.deserialization
@@ -623,13 +658,11 @@ export function ARRAY<T>(inner: TypeMapping<T>): TypeMapping<T[]> & { kind: 'arr
  * 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 } {
+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
@@ -649,17 +682,16 @@ export function FIXED_ARRAY<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>(
-  inner: TypeMapping<T>,
-): TypeMapping<BoundedVec<T>> & { kind: 'bounded-vec'; inner: TypeMapping<T> } {
+export function BOUNDED_VEC<T>(inner: TypeMapping<T>): BoundedVecMapping<T> {
   return {
     kind: 'bounded-vec',
+    label: `bounded-vec(${inner.label})`,
     inner,
     serialization: inner.serialization
       ? {
@@ -698,13 +730,11 @@ export function BOUNDED_VEC<T>(
  * (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 } {
+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
@@ -740,9 +770,10 @@ export function FIXED_BOUNDED_VEC<T>(
  * slot 1: Fr(0)    // zero-filled from AZTEC_ADDRESS.shape
  * ```
  */
-export function OPTION<T>(inner: TypeMapping<T>): TypeMapping<Option<T>> & { kind: 'option'; inner: TypeMapping<T> } {
+export function OPTION<T>(inner: TypeMapping<T>): OptionMapping<T> {
   return {
     kind: 'option',
+    label: `option(${inner.label})`,
     inner,
     serialization: inner.serialization
       ? {
@@ -770,32 +801,14 @@ export function OPTION<T>(inner: TypeMapping<T>): TypeMapping<Option<T>> & { kin
   };
 }
 
-/**
- * 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]) =>
-        fromUintArray(
-          reader.readFieldArray(length).map(f => f.toString()),
-          bitSize,
-        ),
-    },
-    shape: [{ len: length }],
-  };
-}
-
-export function EPHEMERAL_ARRAY<T>(element: TypeMapping<T>): TypeMapping<EphemeralArray<T>> {
+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: ([rowReader]) => deserializeElement(element, rowReader.readFieldArray(rowReader.remainingFields())),
         },
@@ -805,6 +818,9 @@ export function EPHEMERAL_ARRAY<T>(element: TypeMapping<T>): TypeMapping<Ephemer
       }
     : undefined;
   return {
+    kind: 'ephemeral-array',
+    label: `ephemeral-array(${element.label})`,
+    inner: element,
     serialization: element.serialization
       ? { fn: ea => [ea.materializeSlot(v => serializeElement(element, v))] }
       : undefined,
@@ -824,11 +840,10 @@ export type StructField<TName extends string = string, T = any> = { name: TName;
  * `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[] } {
+export function STRUCT<T>(fields: readonly StructField[]): StructMapping<T> {
   return {
     kind: 'struct',
+    label: `{${structFieldLabels(fields)}}`,
     fields,
     serialization: fields.every(f => f.type.serialization)
       ? {
@@ -856,6 +871,79 @@ export function STRUCT<T>(
   };
 }
 
+/**
+ * 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;