@sig-net/midnight 0.24.0-rc.1 → 0.24.0-rc.10

package/README.md

@@ -35,7 +35,7 @@ The protocol and integration documentation lives in the [sig-net/midnight-integr
 
 - [Sign Bidirectional Flow](https://github.com/sig-net/midnight-integration/blob/main/README.md#sign-bidirectional-protocol-flow): the 5-step protocol this package speaks, with diagram, failure handling and output recovery.
 - [Derived keys](https://github.com/sig-net/midnight-integration/blob/main/README.md#derived-keys): the request signing key and the response key, and how the MPC derives them.
-- [Handling Failure](https://github.com/sig-net/midnight-integration/blob/main/README.md#handling-failure): the fixed 5-byte failure payload the MPC attests for a failed foreign transaction, how a contract tells it apart from a success, and which respond schemas cannot.
+- [Handling Failure](https://github.com/sig-net/midnight-integration/blob/main/README.md#handling-failure): the empty output and failure output kind the MPC attests for a failed foreign transaction, and how a contract routes on the verified kind.
 - [Integrator Guide](https://github.com/sig-net/midnight-integration/blob/main/README.md#integrator-guide): the once-off setup and the per-request runtime steps, built on this package's exports.
 - [EVM Type 2 transactions and ABI calldata words](https://github.com/sig-net/midnight-integration/blob/main/README.md#evm-type-2-transactions-and-abi-calldata-words): building calldata words in-circuit and deserialising respond payloads.
 
@@ -51,11 +51,12 @@ What your contract imports with `import "@sig-net/midnight/src/Signet"`:
 
 | Task | Exports |
 |---|---|
-| Declare the protocol ledger state (setup step 3) | `SignBidirectionalEventMap` (the request map the MPC reads) and `SignetSigner` (the Signet singleton's cross-contract-call interface, pinned at deploy). |
-| Build and store a signature request (runtime step 1) | `constructSignBidirectionalEvent` and `calculateRequestId`, over the request structs `EvmType2TxParams`, `EvmCalldata` and `EvmAccessListEntry`. |
+| Declare the protocol ledger state (setup step 3) | `SignBidirectionalEventMapV1` (the request map the MPC reads) and `SignetSigner` (the Signet singleton's cross-contract-call interface, pinned at deploy). |
+| Build and store a signature request (runtime step 1) | `constructSignBidirectionalEventV1` and `calculateEvmType2RequestIdV1`, over the request structs `EvmType2TxParams`, `EvmCalldata` and `EvmAccessListEntry`. The id hashes `calculateEvmType2TxParamsDigestV1`, a digest over the transaction's used entries only, so it ignores your struct's capacities and unused slots. |
 | Notify the MPC of the request (runtime step 1) | `constructSignBidirectionalEventNotificationV1`: packs your contract's address and the request map's ledger-tree path. |
+| Narrow an attested `uint256` in-circuit | `checkedTruncationU128`: the `Bytes<32>` the MPC attests (little-endian) to a `Uint<128>`, aborting unless the high 16 bytes are zero (see [Output Recovery and Serialisation](https://github.com/sig-net/midnight-integration/blob/main/README.md#output-recovery-and-serialisation)). |
 | Build and read calldata words in-circuit | The builders `evmAddressAbiWord`, `numericAbiWord` and `boolAbiWord`, and the readers `abiWordToUint128` and `abiWordToBool` (see [EVM Type 2 transactions and ABI calldata words](https://github.com/sig-net/midnight-integration/blob/main/README.md#evm-type-2-transactions-and-abi-calldata-words)). |
-| Verify the execution attestation (runtime step 5) | `verifyRespondBidirectionalEvent`: recomputes the attestation digest from the output bytes and checks the MPC's signature against your pinned response key. |
+| Verify the execution attestation (runtime step 5) | `verifyRespondBidirectionalEventV1`: recomputes the attestation digest from the output bytes and the posted request id, output kind and block height, and checks the MPC's signature against your pinned response key. |
 
 ### TypeScript library
 
@@ -69,12 +70,16 @@ What clients import from `@sig-net/midnight`:
 | Derive the response key your deploy pins | `deriveMidnightResponseKey`: the key `initialise` stores (setup step 4), derived from your contract's address. |
 | Look up published counterparty values | `MidnightNetwork`, `getMpcRootPublicKey` and `getSignetContractAddress`: the fixed per-network values (see the notes in [Runtime](https://github.com/sig-net/midnight-integration/blob/main/README.md#runtime)). |
 | Accept an MPC public key in any published spelling | `parseSecp256k1PublicKey` (to a Compact `Secp256k1Point`) and `normaliseSecp256k1PublicKey` (to the canonical `0x04…` uncompressed SEC1 hex): both take SEC1 hex, compressed or uncompressed with an optional `0x`, and NEAR's `secp256k1:<base58>`. |
-| Read a text field of a request record | `asciiUnpadded`: the inverse of `asciiPadded`, for the zero-padded text fields (`caip2Id`, the two schemas). |
+| Read a text field of a request record | `asciiUnpadded`: the inverse of `asciiPadded`, for the zero-padded text fields (`executionDest`, `outputDeserializationSchema`). |
 | Compute a request id off chain | `calculateRequestId`: the TS twin of the on-chain circuit, plus `requestIdHex` and `parseRequestIdHex` for the hex form. |
 | Compose expected calldata words off chain (UIs, expected-record builders, tests) | The builders `numericAbiWord`, `evmAddressAbiWord` and `boolAbiWord`, and the readers `abiWordToUint128` and `abiWordToBool`: TS twins of the circuits under identical names. |
-| Convert a foreign execution output into respond bytes | `deserializeEvmOutput` (raw EVM return data to named values) and `serializeRespondOutput` (named values to the packed respond payload the MPC attests): together they rebuild the `serializedOutput` of steps 4 and 5. |
-| Recognise a failed remote execution | `MPC_FAILURE_OUTPUT` and `isMpcFailureOutput`: the MPC's fixed 5-byte failure payload for reverted or replaced transactions (see [Handling Failure](https://github.com/sig-net/midnight-integration/blob/main/README.md#handling-failure)). |
-| Read the attested output from the MPC's output cache | `MpcOutputCacheReader` (`fetchAttestedOutput` returns the block height and the output; `encodeAttestedOutput` / `decodeAttestedOutput` are the object format): one reader per network and Signet singleton pair, over the public bucket an MPC configured with output storage writes each request's exact attested bytes to before posting, defaulting to the bucket `getMpcOutputCacheUrl` publishes for the network. `fetchSerializedOutput` yields the bytes step 5 verifies, `undefined` while the object is not written yet. |
+| Digest a transaction decomposition off chain | `calculateEvmType2TxParamsDigest`: the TS twin of the circuit, what `calculateRequestId` hashes in place of the parameters. |
+| Rebuild the respond bytes the MPC attests for an executed EVM transaction | `executedEvmRespondOutput`: the request's `outputDeserializationSchema`, whether the transaction was a contract call (`isEvmContractCall` over its calldata) and its traced return data (`EvmTraceOutput`, read off a `debug_traceTransaction` callTracer frame by `evmTraceOutputFromCallFrame`) give the exact `serializedOutput` of steps 4 and 5, empty for an empty output schema. |
+| Convert a foreign execution output into respond bytes | `deserializeEvmOutput` (raw EVM return data to named values) and `serializeRespondOutput` (named values to the attested Borsh bytes): the two conversions `executedEvmRespondOutput` runs on a contract call's return data. |
+| Know what an output schema attests to | `deriveRespondSchema` (the Borsh struct the MPC serialises with), `respondOutputWidth` (the `Bytes<N>` width a settle circuit declares) and `unsupportedEvmOutputFields` (the fields that make the MPC drop a request, without throwing). |
+| Recognise a failed remote execution | `OutputKind` on the verified `RespondBidirectionalEvent`: `failed` or `unviable` beside an empty output (see [Handling Failure](https://github.com/sig-net/midnight-integration/blob/main/README.md#handling-failure)). |
+| Read the attested output bytes from the MPC's output cache | `MpcOutputCacheReader`: one reader per network and Signet singleton pair, over the public bucket an MPC configured with output storage writes each request's exact attested bytes to before posting, defaulting to the bucket `getMpcOutputCacheUrl` publishes for the network. `fetchSerializedOutput` yields the bytes step 5 verifies, `undefined` while the object is not written yet. |
+| Hand a verified attestation to your verify circuit (runtime step 5) | `respondBidirectionalEventToCircuitInput`: flips the wire event's big-endian `bigR.x` and `s` into the little-endian record `verifyRespondBidirectionalEventV1` reads. |
 | Verify attestations without the reader | `verifyRespondBidirectionalSignature`: the check the reader runs internally, exposed for custom pipelines. |
 | Mint attestations in your contract's unit tests | The `@sig-net/midnight/testing` entry point, see [Testing entry point](#testing-entry-point). |
 | Discover requests MPC-side (responders, background workers) | The discovery primitives: decode the signet contract's emitted notification events with `decodeSignetEventNamed(event, SignetEventName.SignBidirectionalEvent)` (or every kind at once with `decodeSignetEvent`, which throws on an undecodable payload anyone can emit, or its non-throwing sibling `tryDecodeSignetEvent`), then resolve each pointer against the named caller's own request map with `lookupSignetRequestAt` (the authenticated read). The polling loop belongs to the responder. |
@@ -96,23 +101,16 @@ stack and no MPC:
 
 ```ts
 import { verifyRespondBidirectionalSignature } from "@sig-net/midnight"; // runtime
-import {
-  calculateSignetAttestationDigest,
-  ecdsaSignatureToMpcSignature,
-  secp256k1PublicKeyOf,
-  signAttestationDigest,
-} from "@sig-net/midnight/testing"; // tests only
-
-// A real RespondBidirectionalEvent for (requestId, output), signed by secretKey.
-// It verifies, in-circuit and off chain, against secp256k1PublicKeyOf(secretKey).
-const event = {
-  signature: ecdsaSignatureToMpcSignature(
-    signAttestationDigest(
-      calculateSignetAttestationDigest(requestId, serializedOutput),
-      secretKey,
-    ),
-  ),
-};
+import { attestRespondBidirectional, secp256k1PublicKeyOf } from "@sig-net/midnight/testing"; // tests only
+
+// A real RespondBidirectionalEvent for (requestId, blockHeight, outputKind,
+// serializedOutput), signed by secretKey: the request id, block height, kind,
+// output width, attestation digest and signature the MPC would post. It
+// verifies, in-circuit and off chain, against secp256k1PublicKeyOf(secretKey).
+const event = attestRespondBidirectional(
+  { requestId, blockHeight, outputKind, serializedOutput },
+  secretKey,
+);
 ```
 
 ## Related packages
@@ -121,3 +119,33 @@ const event = {
 - [`@sig-net/midnight-contract-deploy`](https://www.npmjs.com/package/@sig-net/midnight-contract-deploy): deploy tooling for that contract plus generic Midnight deploy/wallet plumbing.
 
 Developed in [sig-net/midnight-integration](https://github.com/sig-net/midnight-integration).
+
+## Protocol hash domains
+
+`HashDomain` is the shared append-only enum exported by the Compact module
+and the TypeScript SDK. Its indices are `requestId = 0`,
+`attestationDigest = 1`, `evmType2TxHeader = 2`, `evmType2TxWord = 3`,
+`evmType2TxAccessEntry = 4` and `evmType2TxStorageKey = 5`. Each protocol
+hash input starts with its domain tag. Off-chain recomputation must use
+the same tags and field order as the circuits.
+
+`constructSignBidirectionalEventV1` rejects a `signatureDest` other than
+`MPCDestination.unused` and any non-zero byte in `params`. Both fields
+are reserved and remain outside the request id.
+
+## EVM output and Borsh responses
+
+`outputDeserializationSchema` is an ethers-compatible ABI field array whose field names are unique Solidity identifiers (`[A-Za-z_$][A-Za-z0-9_$]*`, never `__proto__`) and whose types are ABI type strings `ethers.ParamType` accepts, matched literally against the table below (`uint256`, never `uint`). Its on-chain bytes are canonical: `canonicalSchemaText(fields)` (`JSON.stringify` of `{name, type}` per field in order, no whitespace) followed by NUL padding only, with `[]` or an all-NUL field for the empty schema. Every reader in this module refuses text or bytes in any other form. It is the only schema a request carries: `respondSerializationSchema` is reserved, pinned to `Bytes<0>` by `constructSignBidirectionalEventV1`. The MPC derives the Borsh schema of the attested bytes from the output schema, one struct member per field in schema order, under a closed mapping:
+
+| ABI type | Borsh | Compact | Width |
+| --- | --- | --- | --- |
+| `bool` | `bool` | `Boolean` | 1 |
+| `uint256` | `[u8; 32]`, little-endian | `Bytes<32>`, narrowed in-circuit with `checkedTruncationU128` | 32 |
+| `address` | `[u8; 20]` | `Bytes<20>` | 20 |
+| `bytes1` to `bytes32` | `[u8; N]` | `Bytes<N>` | N |
+
+Every other ABI type is unsupported. `unsupportedEvmOutputFields` names the offending fields without throwing (the MPC drops such a request), and `deriveRespondSchema`, `respondOutputWidth` and `serializeRespondOutput` throw on them. For example, `[{"name":"success","type":"bool"},{"name":"amount","type":"uint256"}]` derives `{"struct":{"success":"bool","amount":{"array":{"type":"u8","len":32}}}}`, 33 bytes.
+
+`serializeRespondOutput` converts the decoded values (ethers' bigint, boolean and hex forms, plus plain numbers and decimal strings for `uint256`) into that struct and calls `@sig-net/midnight-serde`. A `uint256` is carried whole as 32 little-endian bytes, the byte order of every Borsh and Compact integer and the ABI wire word reversed: nothing is narrowed off chain, and a value outside `0 <= v < 2^256` is rejected. `executedEvmRespondOutput` requires the output schema and the return data to agree: an empty schema with no return data (a plain transfer, or a call that returned nothing) attests an EMPTY output, a non-empty schema with return data runs the two conversions, and either mismatch throws. The return data must be canonical ABI (whole words, a `bool` word of 0 or 1, zero high bytes on an `address`, zero padding after a `bytesN`), checked before the lenient ABI decode. Words past the declared fields are ignored. The schema's types are checked on every path, a plain transfer included.
+
+Output schema JSON accepts text or UTF-8 bytes and trims NUL padding in either form. Blank text is the empty schema, and malformed JSON fails with schema context.

package/dist/abi-serde.d.ts

@@ -1,46 +1,23 @@
+import { type Schema } from "@sig-net/midnight-serde";
 import { ethers } from "ethers";
-/** Fixed-width schema types: the byte size follows entirely from the type. */
-export type AbiFixedType = "bool" | "address" | "field" | `uint${number}` | `bytes${number}`;
-/** A fixed-width schema field: its byte size follows entirely from its type. */
-export interface AbiFixedField {
-    name: string;
-    type: AbiFixedType;
-}
-/** A dynamic string/bytes field. `maxBytes` is the fixed Compact buffer capacity. */
-export interface AbiDynamicField {
-    name: string;
-    type: "string" | "bytes";
-    maxBytes: number;
-}
-/** A dynamic array field. `maxItems` is the fixed Compact vector capacity. */
-export interface AbiArrayField {
-    name: string;
-    type: `${AbiFixedType}[]`;
-    maxItems: number;
-}
-/** One respond-schema field: fixed-width, dynamic string/bytes, or array. */
-export type AbiSchemaField = AbiFixedField | AbiDynamicField | AbiArrayField;
-/** An ABI-style schema exactly as carried on chain (JSON array of fields). */
-export type AbiSchema = AbiSchemaField[];
-/** Any form a respond schema arrives in: parsed, JSON text, or NUL-padded raw bytes. */
-export type AbiSchemaInput = AbiSchema | string | Uint8Array;
 /**
- * A decode-side schema field: `type` is ANY type string the ABI library
- * accepts. The restricted {@link AbiSchemaField} vocabulary is a respond-side
- * concern only, and is assignable to this shape.
+ * One field of an outputDeserializationSchema: `type` is an ABI type string
+ * `ethers.ParamType` accepts. {@link deserializeEvmOutput} decodes every
+ * such type, while the respond side ({@link deriveRespondSchema}) accepts
+ * only the {@link EvmOutputTypeKind} subset, matched on the raw string.
  */
 export interface EvmSchemaField {
     name: string;
     type: string;
 }
-/** Any form a decode schema arrives in: parsed, JSON text, or NUL-padded raw bytes. */
+/** Any form an outputDeserializationSchema arrives in: parsed, JSON text, or NUL-padded raw bytes. */
 export type EvmSchemaInput = readonly EvmSchemaField[] | string | Uint8Array;
 /**
  * Decoded output values, keyed by schema field name. Numerics are bigint,
  * bools boolean, address/bytesN/bytes/string are the forms ethers produces
  * (hex or text strings) or Uint8Array, arrays are plain arrays.
- * `serializeRespondOutput` accepts all of these (plus plain numbers and
- * numeric strings, the forms indexer JSON typically yields).
+ * {@link serializeRespondOutput} additionally accepts plain numbers and
+ * numeric strings for `uint256`, the forms indexer JSON typically yields.
  */
 export type AbiDecodedValue = bigint | boolean | number | string | Uint8Array | AbiDecodedValue[];
 /** Decoded output values keyed by schema field name (see {@link AbiDecodedValue}). */
@@ -50,10 +27,10 @@ export type AbiDecodedOutput = Record<string, AbiDecodedValue>;
  * into named values, driven by the request's outputDeserializationSchema.
  * The decode-side counterpart of {@link serializeRespondOutput}. Type
  * validation is FULLY delegated to ethers: this function checks the schema's
- * shape only. An empty schema decodes to an empty object (a plain transfer
- * has no output), matching the MPC's empty-schema handling. Returns a plain
- * object (never an ethers `Result`), so it survives JSON round-trips and
- * structural comparison.
+ * shape only, so it decodes ABI types the respond side refuses. An empty
+ * schema decodes to an empty object. Returns a plain object (never an
+ * ethers `Result`), so it survives JSON round-trips and structural
+ * comparison.
  *
  * @param schema - The outputDeserializationSchema: parsed, JSON text, or the raw NUL-padded on-chain bytes.
  * @param callResult - The ABI-encoded return data (hex string or bytes).
@@ -61,31 +38,195 @@ export type AbiDecodedOutput = Record<string, AbiDecodedValue>;
  */
 export declare function deserializeEvmOutput(schema: EvmSchemaInput, callResult: ethers.BytesLike): AbiDecodedOutput;
 /**
- * Ceiling on a respond schema's total packed byte width. Schemas are
- * requester-authored on-chain data, so unbounded maxBytes/maxItems would let
- * a hostile request demand giant allocations from the responder. A real
- * respond payload must fit its consumer contract's fixed `deserialize<T, N>`
- * width, orders of magnitude below this.
+ * The ABI output types the MPC attests, and what each maps to. The respond
+ * bytes are the Borsh serialisation of a struct with one member per output
+ * field, in schema order, typed by this mapping:
+ *
+ * - {@link EvmOutputTypeKind.Bool}: ABI `bool`, Borsh `bool`, Compact `Boolean` (1 byte).
+ * - {@link EvmOutputTypeKind.Uint256}: ABI `uint256`, Borsh `[u8; 32]`
+ *   holding the value LITTLE-endian, the byte order of every Borsh and
+ *   Compact integer, Compact `Bytes<32>` (32 bytes). A circuit that wants a
+ *   number narrows it with `checkedTruncationU128`, which aborts above
+ *   2^128 - 1. The ABI wire word is big-endian: the MPC reverses it once,
+ *   here, so no circuit has to.
+ * - {@link EvmOutputTypeKind.Address}: ABI `address`, Borsh `[u8; 20]`
+ *   holding the address bytes, Compact `Bytes<20>` (20 bytes).
+ * - {@link EvmOutputTypeKind.FixedBytes}: ABI `bytes1` to `bytes32`, Borsh
+ *   `[u8; N]`, Compact `Bytes<N>` (N bytes).
+ *
+ * Every other ABI type is unsupported: the MPC drops a request whose output
+ * schema names one, and {@link deriveRespondSchema} throws on it.
+ */
+export declare enum EvmOutputTypeKind {
+    Bool = "bool",
+    Uint256 = "uint256",
+    Address = "address",
+    FixedBytes = "bytesN"
+}
+/**
+ * The fields of an outputDeserializationSchema whose ABI type is outside the
+ * supported subset ({@link EvmOutputTypeKind}). The check itself never
+ * throws on an unsupported type: an empty result means the MPC attests the
+ * request, a non-empty one means it drops it.
+ *
+ * @param schema - The outputDeserializationSchema: parsed, JSON text, or the raw NUL-padded on-chain bytes.
+ * @returns The unsupported fields in schema order, empty when every field is supported.
+ * @throws {Error} If the schema is not an array of uniquely named fields (its shape, not its types).
+ */
+export declare function unsupportedEvmOutputFields(schema: EvmSchemaInput): EvmSchemaField[];
+/**
+ * The Borsh schema the respond bytes of an executed call are serialised
+ * with: a struct with one member per output field, in schema order, each
+ * typed by {@link EvmOutputTypeKind}. An empty output schema derives an
+ * empty struct, which serialises to zero bytes. Borsh writes struct members
+ * in the struct object's key order, which equals schema order because field
+ * names are Solidity identifiers (see {@link parseSchemaShape}).
+ *
+ * @param schema - The outputDeserializationSchema: parsed, JSON text, or the raw NUL-padded on-chain bytes.
+ * @returns The derived Borsh struct schema.
+ * @throws {Error} If the schema is malformed or names an unsupported ABI type.
  */
-export declare const MAX_RESPOND_PACKED_BYTES = 65536;
+export declare function deriveRespondSchema(schema: EvmSchemaInput): Schema;
 /**
- * Encode decoded output values into the respond payload, driven by the
- * request's respondSerializationSchema: the bytes a consumer contract reads
- * with `deserialize<T, N>` and the MPC attests. The respond-side counterpart
- * of {@link deserializeEvmOutput}.
+ * The byte width of the respond bytes an output schema derives: the sum of
+ * its fields' widths under {@link EvmOutputTypeKind}, what a settle circuit
+ * declares as its `Bytes<N>` output argument.
  *
- * The result is the PACKED value, unpadded and unbounded: its length follows
- * entirely from the schema, and padding to a fixed container width is the
- * caller's concern. Strict: values are range-checked, dynamic payloads must
- * fit their capacity with no silent truncation, and signed integer types are
- * rejected.
+ * @param schema - The outputDeserializationSchema: parsed, JSON text, or the raw NUL-padded on-chain bytes.
+ * @returns The exact serialised width, 0 for an empty schema.
+ * @throws {Error} If the schema is malformed or names an unsupported ABI type.
+ */
+export declare function respondOutputWidth(schema: EvmSchemaInput): number;
+/**
+ * Serialise ABI-decoded output into the respond bytes the MPC attests: the
+ * Borsh encoding of {@link deriveRespondSchema}'s struct over the output's
+ * values. A `uint256` is carried whole as 32 little-endian bytes, so no
+ * value is narrowed off chain: a circuit that wants a number narrows the
+ * `Bytes<32>` with `checkedTruncationU128`.
+ *
+ * @param schema - The outputDeserializationSchema: parsed, JSON text, or the raw NUL-padded on-chain bytes.
+ * @param output - The decoded values keyed by field name, as {@link deserializeEvmOutput} returns them.
+ * @returns The unpadded respond bytes, {@link respondOutputWidth} long.
+ * @throws {Error} If the schema is malformed or names an unsupported type, a
+ *   field is missing from `output`, or a value is outside its type.
+ */
+export declare function serializeRespondOutput(schema: EvmSchemaInput, output: AbiDecodedOutput): Uint8Array;
+/**
+ * Whether an EVM transaction is a contract call, decided over its input
+ * bytes exactly as the MPC decides it (`is_contract_call` in its
+ * `chain-ethereum/src/event_parsing.rs`): more than two bytes of input, so a
+ * one- or two-byte input is NOT a contract call. The answer selects the
+ * branch of {@link executedEvmRespondOutput}.
+ *
+ * Pass the signed transaction's `data`, or, from the request record alone,
+ * `assembleCalldata(request.txParams.calldata)`, which yields the same bytes
+ * (`"0x"` for a request without calldata).
+ *
+ * @param input - The transaction's input bytes (hex string or bytes).
+ * @returns True when the MPC treats the transaction as a contract call.
+ * @throws {Error} If `input` is neither bytes nor valid 0x hex.
+ */
+export declare function isEvmContractCall(input: ethers.BytesLike): boolean;
+/**
+ * How a `debug_traceTransaction` (callTracer) read of a transaction's top
+ * call frame came back: the MPC's `TraceOutput`. Carried by
+ * {@link EvmTraceOutput}.
+ */
+export declare enum EvmTraceOutputKind {
+    /** The transaction was not traced: the MPC traces contract calls only. */
+    NotTraced = "NotTraced",
+    /** The top call frame carries a string `output` field: the return data, possibly empty (`0x`). */
+    Output = "Output",
+    /** The top call frame carries no string `output` field. */
+    NoReturnData = "NoReturnData"
+}
+/**
+ * The traced return data of an EVM transaction, as the MPC models it: a top
+ * call frame's string `output` field (even `0x`) is
+ * {@link EvmTraceOutputKind.Output}, an absent or non-string one is
+ * {@link EvmTraceOutputKind.NoReturnData}. {@link evmTraceOutputFromCallFrame}
+ * reads it off a frame.
+ */
+export type EvmTraceOutput = {
+    /** The frame carried an `output` field. */
+    readonly kind: EvmTraceOutputKind.Output;
+    /** The frame's `output`: the ABI-encoded return data (hex string or bytes). */
+    readonly returnData: ethers.BytesLike;
+} | {
+    /** The frame carried no `output` field. */
+    readonly kind: EvmTraceOutputKind.NoReturnData;
+} | {
+    /** No trace was taken. */
+    readonly kind: EvmTraceOutputKind.NotTraced;
+};
+/**
+ * The exact respond output the MPC attests for an EVM transaction that
+ * executed (the payload of an `OutputKind.executed` attestation), derived
+ * from the request's outputDeserializationSchema alone. The schema and the
+ * execution's return data MUST agree: an empty schema declares that the
+ * execution returns nothing, a non-empty schema that it returns data.
+ *
+ * - Not a contract call (a plain transfer): there is no return data, so the
+ *   schema must be empty and the output is EMPTY.
+ * - A contract call whose trace carries no return data, or empty return
+ *   data (`0x`): the schema must be empty and the output is EMPTY.
+ * - A contract call that returned data: the schema must be non-empty, and
+ *   the output is the return data decoded by {@link deserializeEvmOutput}
+ *   and serialised by {@link serializeRespondOutput}.
+ *
+ * The schema's types are checked on every path, a plain transfer included,
+ * so a request the MPC should have dropped never attests anything. A failed
+ * or unviable execution is attested over an empty output instead, which
+ * needs no call. An empty output under `executed` is therefore ordinary for
+ * an empty schema: its settle circuit verifies at width 0 and must route on
+ * the verified `outputKind`, never on the width.
+ *
+ * @param schema - The request's outputDeserializationSchema (a request record's field satisfies this).
+ * @param isContractCall - Whether the transaction is a contract call, as {@link isEvmContractCall} decides it.
+ * @param trace - The transaction's traced return data (`NotTraced` for an untraced plain transfer).
+ * @returns The respond bytes, unpadded, empty for an empty schema.
+ * @throws {Error} Exactly where the MPC refuses to attest an execution: a
+ *   malformed schema or an unsupported output type, a contract call not
+ *   traced, return data under an empty schema, no or empty return data
+ *   under a non-empty schema, return data that is not canonical ABI
+ *   ({@link checkCanonicalReturnData}) or that the schema cannot decode, and
+ *   every {@link serializeRespondOutput} rejection.
+ */
+export declare function executedEvmRespondOutput(schema: EvmSchemaInput, isContractCall: boolean, trace: EvmTraceOutput): Uint8Array;
+/** A parsed JSON object. */
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+/** Any parsed JSON value: the shape of a JSON-RPC `result`. */
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | JsonObject;
+/**
+ * The {@link EvmTraceOutput} of a `debug_traceTransaction` callTracer top
+ * call frame, read exactly as the MPC reads it (`trace_output_to_bytes` in
+ * its `chain-ethereum/src/rpc.rs`):
+ *
+ * - The frame must be a JSON object with a `type` field (of any value).
+ * - A non-empty string `error` refuses the frame, naming a non-empty string
+ *   `revertReason` beside it. Any other `error` is ignored.
+ * - A string `output` is {@link EvmTraceOutputKind.Output}, its hex decoded
+ *   after one optional lowercase `0x` prefix (`0x` and `""` are empty return
+ *   data). An absent or non-string `output` is
+ *   {@link EvmTraceOutputKind.NoReturnData}.
+ *
+ * @param frame - The JSON-RPC `result` of `debug_traceTransaction` with the callTracer.
+ * @returns The frame's traced return data, for {@link executedEvmRespondOutput}.
+ * @throws {Error} If the frame is not an object, has no `type`, reports an
+ *   `error`, or carries an `output` that is not even-length hex.
+ */
+export declare function evmTraceOutputFromCallFrame(frame: JsonValue): EvmTraceOutput;
+/**
+ * The canonical text of an output schema: `JSON.stringify` of its fields
+ * reduced to `{name, type}` in schema order, with no whitespace. A schema's
+ * on-chain bytes must be exactly this text followed by NUL padding, so one
+ * schema has exactly one byte form. Write a contract's schema literal with
+ * this function's output.
  *
- * @param schema - The respondSerializationSchema: parsed, JSON text, or the raw NUL-padded on-chain bytes.
- * @param output - Decoded values keyed by field name (from {@link deserializeEvmOutput} or any source using the same forms).
- * @returns The packed respond bytes.
- * @throws {Error} If the schema is empty or malformed, packs to more than
- *   {@link MAX_RESPOND_PACKED_BYTES} bytes, a value falls outside its declared
- *   range, or a dynamic payload exceeds its capacity.
+ * @param fields - The schema's fields in order.
+ * @returns The canonical JSON text, `[]` for an empty schema.
  */
-export declare function serializeRespondOutput(schema: AbiSchemaInput, output: AbiDecodedOutput): Uint8Array;
+export declare function canonicalSchemaText(fields: readonly EvmSchemaField[]): string;
 //# sourceMappingURL=abi-serde.d.ts.map

package/dist/abi-serde.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"abi-serde.d.ts","sourceRoot":"","sources":["../src/abi-serde.ts"],"names":[],"mappings":"AAyDA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAMhC,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,MAAM,EAAE,GAAG,QAAQ,MAAM,EAAE,CAAC;AAE7F,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,GAAG,YAAY,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,eAAe,GAAG,aAAa,CAAC;AAE7E,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG,cAAc,EAAE,CAAC;AAEzC,wFAAwF;AACxF,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,uFAAuF;AACvF,MAAM,MAAM,cAAc,GAAG,SAAS,cAAc,EAAE,GAAG,MAAM,GAAG,UAAU,CAAC;AAM7E;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,eAAe,EAAE,CAAC;AAElG,sFAAsF;AACtF,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAM/D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,MAAM,CAAC,SAAS,GAC3B,gBAAgB,CAclB;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAE9C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,gBAAgB,GACvB,UAAU,CAqBZ"}
+{"version":3,"file":"abi-serde.d.ts","sourceRoot":"","sources":["../src/abi-serde.ts"],"names":[],"mappings":"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"}