@aztec/pxe 0.0.1-commit.3100065 → 0.0.1-commit.330febf

package/dest/contract_function_simulator/oracle/oracle_type_mappings.js

@@ -4,12 +4,12 @@ import { padArrayEnd } from '@aztec/foundation/collection';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { FieldReader } from '@aztec/foundation/serialize';
-import { fromUintArray } from '@aztec/simulator/client';
 import { FunctionSelector, NoteSelector } from '@aztec/stdlib/abi';
 import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import { BlockHash } from '@aztec/stdlib/block';
 import { Tag, appTaggingSecretKindFromDeliveryMode } from '@aztec/stdlib/logs';
 import { TxHash } from '@aztec/stdlib/tx';
+import { originBlockStateFromNumber } from '../../storage/fact_store/index.js';
 import { BoundedVec } from '../noir-structs/bounded_vec.js';
 import { EphemeralArray } from '../noir-structs/ephemeral_array.js';
 import { EventValidationRequest } from '../noir-structs/event_validation_request.js';
@@ -28,7 +28,25 @@ import { packAsHintedNote } from './note_packing_utils.js';
     });
 }
 // ─── Scalar Type Mappings ────────────────────────────────────────────────────
-export const FIELD = {
+/**
+ * A leaf mapping whose {@link TypeMapping.label} is just its bare {@link TypeMapping.kind}. Its wire shape is arbitrary
+ * (several fields, or a variable-width run); a single-field scalar uses the shorter {@link SCALAR} instead.
+ */ export function LEAF(mapping) {
+    return {
+        ...mapping,
+        label: mapping.kind
+    };
+}
+/** A {@link LEAF} occupying a single `'scalar'` wire slot, so callers omit the shape. */ export function SCALAR(mapping) {
+    return LEAF({
+        ...mapping,
+        shape: [
+            'scalar'
+        ]
+    });
+}
+export const FIELD = SCALAR({
+    kind: 'field',
     serialization: {
         fn: (v)=>[
                 v
@@ -36,12 +54,10 @@ export const FIELD = {
     },
     deserialization: {
         fn: ([reader])=>reader.readField()
-    },
-    shape: [
-        'scalar'
-    ]
-};
-export const BOOL = {
+    }
+});
+export const BOOL = SCALAR({
+    kind: 'bool',
     serialization: {
         fn: (v)=>[
                 new Fr(v ? 1n : 0n)
@@ -49,70 +65,43 @@ export const BOOL = {
     },
     deserialization: {
         fn: ([reader])=>!reader.readField().isZero()
-    },
-    shape: [
-        'scalar'
-    ]
-};
-export const 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'
-    ]
-};
-export const BLOCK_NUMBER = {
+    }
+});
+export const U32 = SCALAR({
+    kind: 'u32',
     serialization: {
         fn: (v)=>[
                 new Fr(v)
             ]
     },
     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]. */ export const BYTE = {
+        fn: ([reader])=>Number(uintFromField(reader.readField(), 32))
+    }
+});
+export const BLOCK_NUMBER = ALIAS(U32, {
+    wrap: (v)=>BlockNumber(v),
+    unwrap: (v)=>v
+});
+export const U8 = SCALAR({
+    kind: 'u8',
     serialization: {
         fn: (byte)=>[
                 new Fr(byte)
             ]
     },
     deserialization: {
-        fn: ([reader])=>{
-            const value = reader.readField().toBigInt();
-            if (value > 0xffn) {
-                throw new Error(`BYTE overflow: value ${value} exceeds u8 max (255)`);
-            }
-            return Number(value);
-        }
-    },
-    shape: [
-        'scalar'
-    ]
-};
+        fn: ([reader])=>Number(uintFromField(reader.readField(), 8))
+    }
+});
 // Noir passes `MessageDelivery` onchain variants here.
-export const DELIVERY_MODE = {
+export const DELIVERY_MODE = SCALAR({
+    kind: 'onchain-delivery-mode',
     deserialization: {
-        fn: (readers)=>appTaggingSecretKindFromDeliveryMode(BYTE.deserialization.fn(readers))
-    },
-    shape: BYTE.shape
-};
-export const RESOLVED_TAGGING_STRATEGY = {
+        fn: (readers)=>appTaggingSecretKindFromDeliveryMode(U8.deserialization.fn(readers))
+    }
+});
+export const RESOLVED_TAGGING_STRATEGY = LEAF({
+    kind: 'resolved-tagging-strategy',
     serialization: {
         fn: (resolved)=>resolvedTaggingStrategyToFields(resolved)
     },
@@ -123,21 +112,39 @@ export const RESOLVED_TAGGING_STRATEGY = {
         'scalar',
         'scalar'
     ]
-};
-export const BIGINT = {
+});
+export const BIGINT = ALIAS(FIELD, {
+    wrap: (f)=>f.toBigInt(),
+    unwrap: (v)=>new Fr(v)
+});
+export const U64 = SCALAR({
+    kind: 'u64',
     serialization: {
         fn: (v)=>[
                 new Fr(v)
             ]
     },
     deserialization: {
-        fn: ([reader])=>reader.readField().toBigInt()
+        fn: ([reader])=>uintFromField(reader.readField(), 64)
+    }
+});
+export const U128 = SCALAR({
+    kind: 'u128',
+    serialization: {
+        fn: (v)=>[
+                new Fr(v)
+            ]
     },
-    shape: [
-        'scalar'
-    ]
-};
-/** Reads every field in the slot as a UTF-8 character code. */ export const STR = {
+    deserialization: {
+        fn: ([reader])=>uintFromField(reader.readField(), 128)
+    }
+});
+export const LEAF_INDEX = ALIAS(FIELD, {
+    wrap: (f)=>f.toNumber(),
+    unwrap: (v)=>new Fr(v)
+});
+/** Reads every field in the slot as a UTF-8 character code. */ export const STR = LEAF({
+    kind: 'str',
     serialization: {
         fn: (str)=>[
                 Array.from(Buffer.from(str, 'utf-8')).map((b)=>new Fr(b))
@@ -155,8 +162,9 @@ export const BIGINT = {
     shape: [
         'variable'
     ]
-};
-export const AZTEC_ADDRESS = {
+});
+export const AZTEC_ADDRESS = SCALAR({
+    kind: 'aztec-address',
     serialization: {
         fn: (v)=>[
                 v.toField()
@@ -164,25 +172,14 @@ export const AZTEC_ADDRESS = {
     },
     deserialization: {
         fn: ([reader])=>AztecAddress.fromFieldUnsafe(reader.readField())
-    },
-    shape: [
-        'scalar'
-    ]
-};
-export const BLOCK_HASH = {
-    serialization: {
-        fn: (v)=>[
-                new Fr(v.toBuffer())
-            ]
-    },
-    deserialization: {
-        fn: ([reader])=>new BlockHash(reader.readField())
-    },
-    shape: [
-        'scalar'
-    ]
-};
-export const FUNCTION_SELECTOR = {
+    }
+});
+export const BLOCK_HASH = ALIAS(FIELD, {
+    wrap: (f)=>new BlockHash(f),
+    unwrap: (v)=>new Fr(v.toBuffer())
+});
+export const FUNCTION_SELECTOR = SCALAR({
+    kind: 'function-selector',
     serialization: {
         fn: (v)=>[
                 v.toField()
@@ -190,50 +187,20 @@ export const FUNCTION_SELECTOR = {
     },
     deserialization: {
         fn: ([reader])=>FunctionSelector.fromField(reader.readField())
-    },
-    shape: [
-        'scalar'
-    ]
-};
-export const NOTE_SELECTOR = {
-    serialization: {
-        fn: (v)=>[
-                v.toField()
-            ]
-    },
-    deserialization: {
-        fn: ([reader])=>NoteSelector.fromField(reader.readField())
-    },
-    shape: [
-        'scalar'
-    ]
-};
-export const TX_HASH = {
-    serialization: {
-        fn: (v)=>[
-                v.hash
-            ]
-    },
-    deserialization: {
-        fn: ([reader])=>TxHash.fromField(reader.readField())
-    },
-    shape: [
-        'scalar'
-    ]
-};
-const TAG = {
-    serialization: {
-        fn: (v)=>[
-                v.value
-            ]
-    },
-    deserialization: {
-        fn: ([reader])=>new Tag(reader.readField())
-    },
-    shape: [
-        'scalar'
-    ]
-};
+    }
+});
+export const NOTE_SELECTOR = ALIAS(FIELD, {
+    wrap: (f)=>NoteSelector.fromField(f),
+    unwrap: (v)=>v.toField()
+});
+export const TX_HASH = ALIAS(FIELD, {
+    wrap: (f)=>TxHash.fromField(f),
+    unwrap: (v)=>v.hash
+});
+const TAG = ALIAS(FIELD, {
+    wrap: (f)=>new Tag(f),
+    unwrap: (v)=>v.value
+});
 export const POINT = STRUCT([
     {
         name: 'x',
@@ -244,7 +211,8 @@ export const POINT = STRUCT([
         type: FIELD
     }
 ]);
-const LOG_SOURCE = {
+const LOG_SOURCE = SCALAR({
+    kind: 'log-source',
     serialization: {
         fn: (v)=>[
                 new Fr(v)
@@ -252,12 +220,10 @@ const LOG_SOURCE = {
     },
     deserialization: {
         fn: ([reader])=>logSourceFromField(reader.readField())
-    },
-    shape: [
-        'scalar'
-    ]
-};
-export const ETH_ADDRESS = {
+    }
+});
+export const ETH_ADDRESS = SCALAR({
+    kind: 'eth-address',
     serialization: {
         fn: (v)=>[
                 v.toField()
@@ -265,21 +231,11 @@ export const ETH_ADDRESS = {
     },
     deserialization: {
         fn: ([reader])=>EthAddress.fromField(reader.readField())
-    },
-    shape: [
-        'scalar'
-    ]
-};
-export const SLOT_NUMBER = {
-    serialization: {
-        fn: (v)=>[
-                new Fr(v)
-            ]
-    },
-    shape: [
-        'scalar'
-    ]
-};
+    }
+});
+export const SLOT_NUMBER = ALIAS(FIELD, {
+    unwrap: (v)=>new Fr(v)
+});
 const APPEND_ONLY_TREE_SNAPSHOT = STRUCT([
     {
         name: 'root',
@@ -287,7 +243,7 @@ const APPEND_ONLY_TREE_SNAPSHOT = STRUCT([
     },
     {
         name: 'nextAvailableLeafIndex',
-        type: U32
+        type: LEAF_INDEX
     }
 ]);
 const PARTIAL_STATE_REFERENCE = STRUCT([
@@ -317,11 +273,11 @@ const STATE_REFERENCE = STRUCT([
 const GAS_FEES = STRUCT([
     {
         name: 'feePerDaGas',
-        type: BIGINT
+        type: U128
     },
     {
         name: 'feePerL2Gas',
-        type: BIGINT
+        type: U128
     }
 ]);
 const GLOBAL_VARIABLES = STRUCT([
@@ -343,7 +299,7 @@ const GLOBAL_VARIABLES = STRUCT([
     },
     {
         name: 'timestamp',
-        type: BIGINT
+        type: U64
     },
     {
         name: 'coinbase',
@@ -577,16 +533,6 @@ export const CONTRACT_CLASS_LOG = STRUCT([
         type: U32
     }
 ]);
-const REVERT_CODE = {
-    serialization: {
-        fn: (rc)=>[
-                rc.toField()
-            ]
-    },
-    shape: [
-        'scalar'
-    ]
-};
 const PUBLIC_DATA_WRITE = STRUCT([
     {
         name: 'leafSlot',
@@ -635,7 +581,7 @@ const CONTRACT_CLASS_LOGS = FIXED_ARRAY(CONTRACT_CLASS_LOG_ENTRY, MAX_CONTRACT_C
 export const TX_EFFECT = STRUCT([
     {
         name: 'revertCode',
-        type: REVERT_CODE
+        type: U8
     },
     {
         name: 'txHash',
@@ -674,7 +620,8 @@ export const TX_EFFECT = STRUCT([
         type: CONTRACT_CLASS_LOGS
     }
 ]);
-export const NOTE = {
+export const NOTE = LEAF({
+    kind: 'note',
     serialization: {
         fn: (noteData)=>packAsHintedNote({
                 contractAddress: noteData.contractAddress,
@@ -691,23 +638,25 @@ export const NOTE = {
     shape: [
         'variable'
     ]
-};
-export const NOTE_VALIDATION_REQUEST = {
+});
+export const NOTE_VALIDATION_REQUEST = LEAF({
+    kind: 'note-validation-request',
     deserialization: {
         fn: ([reader])=>NoteValidationRequest.fromFields(reader)
     },
     shape: [
         'variable'
     ]
-};
-export const EVENT_VALIDATION_REQUEST = {
+});
+export const EVENT_VALIDATION_REQUEST = LEAF({
+    kind: 'event-validation-request',
     deserialization: {
         fn: ([reader])=>EventValidationRequest.fromFields(reader)
     },
     shape: [
         'variable'
     ]
-};
+});
 export const LOG_RETRIEVAL_REQUEST = STRUCT([
     {
         name: 'contractAddress',
@@ -753,27 +702,35 @@ export const LOG_RETRIEVAL_RESPONSE = STRUCT([
     },
     {
         name: 'blockTimestamp',
-        type: BIGINT
+        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 = {
-    serialization: {
-        fn: (resolved)=>[
-                resolved.toFields()
-            ]
+export const RESOLVED_TX = STRUCT([
+    {
+        name: 'txHash',
+        type: TX_HASH
     },
-    shape: [
-        {
-            len: MAX_NOTE_HASHES_PER_TX + 5
-        }
-    ]
-};
+    {
+        name: 'uniqueNoteHashesInTx',
+        type: FIXED_BOUNDED_VEC(FIELD, MAX_NOTE_HASHES_PER_TX)
+    },
+    {
+        name: 'firstNullifierInTx',
+        type: FIELD
+    },
+    {
+        name: 'blockNumber',
+        type: U32
+    },
+    {
+        name: 'blockHash',
+        type: FIELD
+    }
+]);
 export const PENDING_TAGGED_LOG = STRUCT([
     {
         name: 'log',
@@ -784,93 +741,109 @@ export const PENDING_TAGGED_LOG = STRUCT([
         type: RESOLVED_TX
     }
 ]);
-export const ORIGIN_BLOCK = {
+export const ORIGIN_BLOCK = STRUCT([
+    {
+        name: 'blockNumber',
+        type: U32
+    },
+    {
+        name: 'blockHash',
+        type: FIELD
+    }
+]);
+const ORIGIN_BLOCK_STATE = SCALAR({
+    kind: 'origin-block-state',
     serialization: {
-        fn: (ob)=>[
-                new Fr(ob.blockNumber),
-                ob.blockHash
+        fn: (v)=>[
+                new Fr(v)
             ]
     },
     deserialization: {
-        fn: ([blockNumberReader, blockHashReader])=>({
-                blockNumber: blockNumberReader.readField().toNumber(),
-                blockHash: blockHashReader.readField()
-            })
+        fn: ([reader])=>originBlockStateFromNumber(reader.readField().toNumber())
+    }
+});
+/** Read-side origin of a retractable fact, carrying the chain state of its origin block. */ export const RETRACTABLE_FACT_ORIGIN = STRUCT([
+    {
+        name: 'blockNumber',
+        type: U32
     },
-    shape: [
-        'scalar',
-        'scalar'
-    ]
-};
-/** Read-side origin of a retractable fact, carrying the chain state of its origin block. */ export const RETRACTABLE_FACT_ORIGIN = {
-    serialization: {
-        fn: (o)=>[
-                new Fr(o.blockNumber),
-                o.blockHash,
-                new Fr(o.blockState)
-            ]
+    {
+        name: 'blockHash',
+        type: FIELD
     },
-    shape: [
-        'scalar',
-        'scalar',
-        'scalar'
-    ]
-};
-// `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 = {
-    serialization: {
-        fn: (f)=>[
-                f.factTypeId,
-                f.payload.materializeSlot((v)=>FIELD.serialization.fn(v).flat()),
-                ...OPTION(RETRACTABLE_FACT_ORIGIN).serialization.fn(f.originBlock)
-            ]
+    {
+        name: 'blockState',
+        type: ORIGIN_BLOCK_STATE
+    }
+]);
+export const FACT = STRUCT([
+    {
+        name: 'factTypeId',
+        type: FIELD
     },
-    shape: [
-        'scalar',
-        'scalar',
-        'scalar',
-        'scalar',
-        'scalar',
-        'scalar'
-    ]
-};
-export const FACT_COLLECTION = {
-    serialization: {
-        fn: (c)=>[
-                c.contractAddress.toField(),
-                c.scope.toField(),
-                c.factCollectionTypeId,
-                c.factCollectionId,
-                c.facts.materializeSlot((v)=>FACT.serialization.fn(v).flat())
-            ]
+    {
+        name: 'payload',
+        type: EPHEMERAL_ARRAY(FIELD)
     },
-    shape: [
-        'scalar',
-        'scalar',
-        'scalar',
-        'scalar',
-        'scalar'
-    ]
-};
-export const PROVIDED_SECRET = {
-    deserialization: {
-        fn: ([reader])=>({
-                secret: reader.readField(),
-                mode: appTaggingSecretKindFromDeliveryMode(BYTE.deserialization.fn([
-                    reader
-                ]))
-            })
+    {
+        name: 'originBlock',
+        type: OPTION(RETRACTABLE_FACT_ORIGIN)
+    }
+]);
+export const FACT_COLLECTION = STRUCT([
+    {
+        name: 'contractAddress',
+        type: AZTEC_ADDRESS
     },
-    shape: [
-        {
-            len: 2
-        }
-    ]
-};
+    {
+        name: 'scope',
+        type: AZTEC_ADDRESS
+    },
+    {
+        name: 'factCollectionTypeId',
+        type: FIELD
+    },
+    {
+        name: 'factCollectionId',
+        type: FIELD
+    },
+    {
+        name: 'facts',
+        type: EPHEMERAL_ARRAY(FACT)
+    }
+]);
+export const PROVIDED_SECRET = STRUCT([
+    {
+        name: 'secret',
+        type: FIELD
+    },
+    {
+        name: 'mode',
+        type: DELIVERY_MODE
+    }
+]);
 // ─── Combinator Type Mappings ────────────────────────────────────────────────
-function SIBLING_PATH(height) {
+/**
+ * A TS-side alias of `base`: the same Noir type on the wire (it inherits `base`'s `kind`, `label`, and `shape`) but a
+ * richer TS value. `wrap` maps a base value to the alias, `unwrap` back; a serialize-only alias passes only `unwrap`.
+ */ export function ALIAS(base, conversions) {
+    const { wrap, unwrap } = conversions;
     return {
+        kind: base.kind,
+        label: base.label,
+        serialization: base.serialization && unwrap ? {
+            fn: (value)=>base.serialization.fn(unwrap(value))
+        } : undefined,
+        deserialization: base.deserialization && wrap ? {
+            fn: (readers)=>wrap(base.deserialization.fn(readers))
+        } : undefined,
+        shape: base.shape
+    };
+}
+function SIBLING_PATH(height) {
+    return LEAF({
+        // On the wire (and in Noir) a sibling path is a plain `[Field; height]`, so it shares the fixed-array kind.
+        kind: `array(field,${height})`,
         serialization: {
             fn: (sp)=>[
                     sp.toFields()
@@ -881,7 +854,7 @@ function SIBLING_PATH(height) {
                 len: height
             }
         ]
-    };
+    });
 }
 export function MEMBERSHIP_WITNESS(height) {
     return STRUCT([
@@ -898,6 +871,7 @@ export function MEMBERSHIP_WITNESS(height) {
 export function ARRAY(inner) {
     return {
         kind: 'array',
+        label: `array(${inner.label})`,
         inner,
         serialization: inner.serialization ? {
             fn: (values)=>[
@@ -924,6 +898,7 @@ export function ARRAY(inner) {
     const elementWidth = fieldWidth(element.shape);
     return {
         kind: 'fixed-array',
+        label: `array(${element.label},${length})`,
         inner: element,
         length,
         serialization: element.serialization ? {
@@ -948,7 +923,7 @@ export function ARRAY(inner) {
  *
  * 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
@@ -956,6 +931,7 @@ export function ARRAY(inner) {
  */ export function BOUNDED_VEC(inner) {
     return {
         kind: 'bounded-vec',
+        label: `bounded-vec(${inner.label})`,
         inner,
         serialization: inner.serialization ? {
             fn: (bv)=>{
@@ -976,8 +952,18 @@ export function ARRAY(inner) {
             fn: ([storageReader, lengthReader])=>{
                 // slot 0 is the padded storage, slot 1 the actual length. Parse only the first `length` elements out of
                 // storage, then drain the trailing zero-padding so the storage reader is fully consumed.
-                const maxLength = storageReader.remainingFields() / fieldWidth(inner.shape);
+                const elementWidth = fieldWidth(inner.shape);
+                const storageFields = storageReader.remainingFields();
+                if (storageFields % elementWidth !== 0) {
+                    throw new Error(`Malformed BoundedVec: storage array holds ${storageFields} field(s), which is not a whole number of ` + `${elementWidth}-field elements`);
+                }
+                // The BoundedVec's maximum length is determined by the size of the storage array, so its length is bounded
+                // by it.
+                const maxLength = storageFields / elementWidth;
                 const length = lengthReader.readField().toNumber();
+                if (length > maxLength) {
+                    throw new Error(`Malformed BoundedVec: length ${length} exceeds the ${maxLength} element(s) its storage array holds`);
+                }
                 const elements = unpackElements(inner, storageReader, length);
                 storageReader.skip(storageReader.remainingFields());
                 return BoundedVec.from({
@@ -1003,6 +989,7 @@ export function ARRAY(inner) {
     const width = fieldWidth(element.shape);
     return {
         kind: 'fixed-bounded-vec',
+        label: `bounded-vec(${element.label},${maxLength})`,
         inner: element,
         maxLength,
         serialization: element.serialization ? {
@@ -1046,6 +1033,7 @@ export function ARRAY(inner) {
  */ export function OPTION(inner) {
     return {
         kind: 'option',
+        label: `option(${inner.label})`,
         inner,
         serialization: inner.serialization ? {
             fn: (opt)=>opt.isSome() ? [
@@ -1074,31 +1062,13 @@ export function ARRAY(inner) {
         ]
     };
 }
-/**
- * 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, length) {
-    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(element) {
     // EphemeralArray.readAll hands each row's flat fields in as a single reader; reconstruct the element's per-slot
     // readers from its shape, deserialize, and assert the row was fully consumed so a row with trailing fields is
     // rejected.
     const rowElement = element.deserialization ? {
+        kind: element.kind,
+        label: element.label,
         deserialization: {
             fn: ([rowReader])=>deserializeElement(element, rowReader.readFieldArray(rowReader.remainingFields()))
         },
@@ -1109,6 +1079,9 @@ export function EPHEMERAL_ARRAY(element) {
         ]
     } : undefined;
     return {
+        kind: 'ephemeral-array',
+        label: `ephemeral-array(${element.label})`,
+        inner: element,
         serialization: element.serialization ? {
             fn: (ea)=>[
                     ea.materializeSlot((v)=>serializeElement(element, v))
@@ -1130,6 +1103,7 @@ export function EPHEMERAL_ARRAY(element) {
  */ export function STRUCT(fields) {
     return {
         kind: 'struct',
+        label: `{${structFieldLabels(fields)}}`,
         fields,
         serialization: fields.every((f)=>f.type.serialization) ? {
             fn: (value)=>{
@@ -1152,6 +1126,42 @@ export function EPHEMERAL_ARRAY(element) {
         shape: fields.flatMap((f)=>f.type.shape)
     };
 }
+export function isArrayMapping(type) {
+    return type.kind === 'array';
+}
+export function isBoundedVecMapping(type) {
+    return type.kind === 'bounded-vec';
+}
+export function isOptionMapping(type) {
+    return type.kind === 'option';
+}
+export function isStructMapping(type) {
+    return type.kind === 'struct';
+}
+export function isFixedArrayMapping(type) {
+    return type.kind === 'fixed-array';
+}
+export function isFixedBoundedVecMapping(type) {
+    return type.kind === 'fixed-bounded-vec';
+}
+export function isEphemeralArrayMapping(type) {
+    return type.kind === 'ephemeral-array';
+}
+/**
+ * The comma-joined labels of a struct's fields, with nested struct labels spliced into the parent: nesting affects
+ * neither the wire (struct slots concatenate) nor the interface, so the label treats nested and flat declarations as
+ * the same type.
+ */ function structFieldLabels(fields) {
+    return fields.map((f)=>isStructMapping(f.type) ? structFieldLabels(f.type.fields) : f.type.label).join(',');
+}
+/** The field's value as a bigint, asserted to fit a `bits`-wide uint. */ function uintFromField(field, bits) {
+    const max = 2n ** BigInt(bits) - 1n;
+    const value = field.toBigInt();
+    if (value > max) {
+        throw new Error(`u${bits} overflow: value ${value} exceeds max (${max})`);
+    }
+    return value;
+}
 /** Number of InputSlots a deserializable type spans, derived from its {@link TypeMapping.shape}. */ export function slotsOf(mapping) {
     return mapping.shape.length;
 }