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

package/src/Signet.compact

@@ -26,13 +26,13 @@
 //  - SignBidirectionalEventNotification: the notification delivered through that call, versioned by
 //    the version byte it carries.
 //  - SignatureRespondedEventV1: the MPC's posted signature answering a request.
-//  - RespondBidirectionalEventV1: the MPC's posted attestation that the foreign chain executed the
-//    signed transaction.
+//  - RespondBidirectionalEventV1: the MPC's posted attestation of the signed transaction's outcome
+//    (executed, failed or unviable).
 //
 //  The V1 suffix marks the wire and hash-domain artefacts of protocol version 1 (the structs the
-//  ledger stores and the singleton emits, and the circuits that hash or verify them). Vocabulary
-//  shared across versions (RequestId, OutputKind, Signature, the enums, the transaction parameter
-//  structs, which TxParamType tags) and the version-tagged notification carry no suffix.
+//  ledger stores and the singleton emits, and the circuits that hash, verify or construct them).
+//  Vocabulary shared across versions (RequestId, OutputKind, Signature, the enums, the transaction
+//  parameter structs, which TxParamType tags) and the version-tagged notification carry no suffix.
 //
 // These key types are best understood within the sign bidirectional flow that they enable:
 // 1. Client contract stores a SignBidirectionalEvent in a SignBidirectionalEventMap in its own ledger
@@ -45,18 +45,21 @@
 //    signature) through the Signet singleton, which emits it as a contract event.
 // 3. Client polls the Signet singleton contract's SignatureRespondedEvent events, identifying the response
 //    associated with their request by RequestId. Clients validate the signature is correct by checking with
-//    the requested signing key. Then it broadcasts the signed txn to the destination chain.
-// 4. MPC observes txn execution on destination chain and posts a RespondBidirectionalEvent attestation
-//    through the Signet singleton, which emits it as a contract event beside the request id.
+//    the requested signing key. Then it broadcasts the signed txn to the target chain.
+// 4. MPC observes the txn's outcome in a final block on the target chain (executed, failed,
+//    or unviable when another request's transaction took its nonce) and posts a
+//    RespondBidirectionalEvent attestation through the Signet singleton, which emits it as a
+//    contract event beside the request id.
 //    The client polls its request's posts and takes the first one that verifies over the request id,
 //    block height, output kind and output. The client obtains the execution output off chain (for EVM: the mined
-//    call's return data via debug_traceTransaction, or the exact attested bytes from the
-//    MPC's output cache) and hands output plus attestation to its verify circuit. See
-//    "Output Recovery" in the repository README.
+//    call's return data via debug_traceTransaction, re-serialised exactly as the MPC did with
+//    executedEvmRespondOutput, or the exact attested bytes from the MPC's output cache) and hands the
+//    serialised output plus attestation to its verify circuit. See
+//    "Output Recovery and Serialisation" in the repository README.
 //
 // Read more:
-//   - The sign bidirectional flow and key derivation: this package's README
-//     ("Sign bidirectional flow", "Derived keys").
+//   - The sign bidirectional flow and key derivation: the repository README
+//     ("Sign Bidirectional Protocol Flow", "Derived Keys").
 //   - For full integration examples (such as an ERC20 cross chain vault example) see
 //     the Midnight Examples repository at: https://github.com/sig-net/midnight-examples.
 //   - Compact language reference (modules, types):
@@ -73,6 +76,7 @@ module Signet {
     evmType2TxWord,
     evmType2TxAccessEntry,
     evmType2TxStorageKey,
+    attestedOutput,
   }
 
   // ---- SignBidirectionalEvent ------------------------------------------------------------------------
@@ -92,7 +96,8 @@ module Signet {
     // variant for requests made from Midnight contracts), not this record's target
     // executionDest. The path is 32 opaque bytes of the client contract's choosing (e.g. a
     // fixed literal for a contract-owned account or a hash of a caller's secret for
-    // per-user accounts): no format is enforced, any 32 bytes are valid.
+    // per-user accounts): no format is enforced, and any 32 bytes are valid except
+    // pad(32, "midnight response key"), which is reserved for the MPC response key and refused.
     // CRITICAL: the MPC renders the path as hex::encode(path) for key derivation (lowercase hex
     // of the full 32 bytes, no trimming, no 0x prefix). The sender is always part
     // of the derivation, so no contract can reach another contract's derived keys.
@@ -104,11 +109,12 @@ module Signet {
     // MPC Parameters.
     algo: MPCSignatureAlgorithm;    // Signature algorithm scheme, e.g. ecdsa
 
-    // Specific destination chain Transaction parameters.
+    // Target chain transaction parameters.
     txParamType: TxParamType;  // Off-chain tag indicating what type txParams is set to.
     txParams: TxParams;        // The generic transaction-param payload
-    executionDest: Bytes<32>;  // The MPC's routing key for the target chain, in CAIP-2 form
-                               // (https://chainagnostic.org/CAIPs/caip-2). An Ethereum target
+    executionDest: Bytes<64>;  // The MPC's routing key for the target chain, in CAIP-2 form
+                               // (https://chainagnostic.org/CAIPs/caip-2), zero-padded: 64 bytes
+                               // hold any CAIP-2 id (at most 41). An Ethereum target
                                // (mainnet, Sepolia or a local anvil) uses ethereumCaip2Id():
                                // the network itself is txParams' chainId.
 
@@ -119,8 +125,8 @@ module Signet {
 
     // ---- Serialisation Schemas ----
     
-    // outputDeserializationSchema tells the MPC how to decode the destination chain's
-    // execution output (destination chain -> MPC).
+    // outputDeserializationSchema tells the MPC how to decode the target chain's
+    // execution output (target chain -> MPC).
     // The value is execution chain specific and sized per client contract: 
     // - Ethereum: an ABI JSON schema string (see https://docs.soliditylang.org/en/v0.8.30/abi-spec.html#json)
     //   in canonical form: `[{"name":"<identifier>","type":"<abi type>"},...]` with no
@@ -165,7 +171,7 @@ module Signet {
     algo: MPCSignatureAlgorithm,
     txParamType: TxParamType,
     txParams: TxParams,
-    executionDest: Bytes<32>,
+    executionDest: Bytes<64>,
     signatureDest: MPCDestination,
     params: Bytes<64>,
     outputDeserializationSchema: Bytes<LenOutputDeserialization>,
@@ -217,7 +223,7 @@ module Signet {
     algo: MPCSignatureAlgorithm;
     txParamType: TxParamType;
     txParamsDigest: Bytes<32>;
-    executionDest: Bytes<32>;
+    executionDest: Bytes<64>;
   }
 
   // Off-chain recomputation must prefix the preimage with HashDomain.requestId
@@ -329,7 +335,8 @@ module Signet {
   // RespondBidirectionalEvent: the MPC's attestation of a foreign execution, the
   // final step of the sign bidirectional flow.
   //
-  //    attestationDigest = calculateSignetAttestationDigestV1(requestId, blockHeight, outputKind, serializedOutput)
+  //    outputHash = calculateAttestedOutputHashV1(serializedOutput)
+  //    attestationDigest = calculateSignetAttestationDigestV1(requestId, blockHeight, outputKind, serializedOutputLength, outputHash)
   //    signature = signSECP256k1(mpcResponseKey, attestationDigest)
   //
   // mpcResponseKey is derived like request signing keys, with the path set to the
@@ -337,28 +344,34 @@ module Signet {
   // verbatim, unlike a request's hex-encoded 32 path bytes):
   //  mpcResponseKey = f(mpcRootKey[keyVersion], caip2ChainId, sender, "midnight response key")
   //
-  // The output travels off chain and the digest is recomputed at verification
-  // time (verifyRespondBidirectionalEventV1). The signature is the ONLY thing that
-  // distinguishes a genuine post from garbage: the singleton emits every post
-  // unverified.
+  // The output travels off chain. The event carries everything the digest is
+  // computed from, so its signature checks without the output
+  // (verifyRespondBidirectionalAttestationV1), and the output checks against the
+  // event's length and hash (verifyAttestedOutputV1). The signature
+  // is the ONLY thing that distinguishes a genuine post from garbage: the
+  // singleton emits every post unverified.
   export struct RespondBidirectionalEventV1 {
     // The request this attestation answers. Signed into the digest: a verified
     // post settles exactly the request it names, so a client consumes this id
     // and never one taken from elsewhere.
     requestId: RequestId;
-    // Height of the finalised destination block holding the transaction the
-    // attestation describes, in the destination chain's own numbering (a slot
+    // Height of the finalised target-chain block holding the transaction the
+    // attestation describes, in the target chain's own numbering (a slot
     // on Solana). Signed into the digest.
     blockHeight: Uint<64>;
     // The MPC's verdict on the execution, signed into the digest.
     outputKind: OutputKind;
-    // Byte width of the serialised output the digest commits to (0 for a failed
-    // or unviable execution), so a client holding no output yet knows which
-    // width to settle at.
+    // Byte width of the serialised output (0 for a failed or unviable
+    // execution), signed into the digest. The output hash does not commit to
+    // the width, so this does: a verifier checks it against the width of the
+    // output it was handed.
     serializedOutputLength: Uint<64>;
+    // calculateAttestedOutputHashV1 of the serialised output, signed into the
+    // digest.
+    outputHash: Bytes<32>;
     // The attestation digest the signature is over (calculateSignetAttestationDigestV1),
-    // so a reader holding no output can check the signature. The verifying
-    // circuit recomputes it from the output and never reads this copy.
+    // for off-chain readers. The verifying circuits recompute it from the
+    // fields above and never read this copy.
     digest: Bytes<32>;
     // The MPC's ECDSA signature over the attestation digest.
     signature: Signature;
@@ -366,56 +379,71 @@ module Signet {
 
   // OutputKind is the MPC's verdict on a request's execution, the kind half of
   // the protocol's outcome (kind, data). The block height the attestation
-  // commits to is the finalised destination block that settled the verdict.
+  // commits to is the finalised target-chain block that settled the verdict.
   export enum OutputKind {
     executed, // finalised and succeeded: the attested output is the decoded return data, Borsh-serialised by the MPC (empty when the call returns nothing)
     failed,   // finalised and reverted: the attested output is empty (Bytes<0>)
-    unviable, // a finalised transaction carrying other bytes took the nonce: the attested output is empty (Bytes<0>)
+    unviable, // a finalised transaction of another request from the same account took the nonce: the attested output is empty (Bytes<0>)
   }
 
-  // The 32-byte attestation digest of a remote execution output:
-  //    attestationDigest = upgradeFromTransient(transientHash([HashDomain.attestationDigest, requestId, blockHeight, outputKind, serializedOutputLength, serializedOutput]))
-  // blockHeight is the height of the finalised destination block holding the
-  // transaction the attestation describes, in the destination chain's own
-  // numbering (a slot on Solana).
-  // Off-chain code uses the TypeScript twin:
-  //    import { calculateSignetAttestationDigest } from "@sig-net/midnight/testing";
-  export pure circuit calculateSignetAttestationDigestV1<#serializedOutputLength>(
+  // The 32-byte hash of a serialised execution output that the attestation
+  // digest commits to:
+  //    outputHash = upgradeFromTransient(transientHash([HashDomain.attestedOutput, serializedOutput]))
+  // The hash packs the bytes into field elements without their width, so
+  // outputs that differ only in trailing zero bytes hash alike: the width is
+  // committed separately, as serializedOutputLength. Off-chain code uses the
+  // TypeScript twin:
+  //    import { calculateAttestedOutputHash } from "@sig-net/midnight";
+  export pure circuit calculateAttestedOutputHashV1<#serializedOutputLength>(
+    serializedOutput: Bytes<serializedOutputLength>,
+  ): Bytes<32> {
+    return upgradeFromTransient(transientHash<[HashDomain, Bytes<serializedOutputLength>]>([HashDomain.attestedOutput, serializedOutput]));
+  }
+
+  // The 32-byte attestation digest the MPC signs:
+  //    attestationDigest = upgradeFromTransient(transientHash([HashDomain.attestationDigest, requestId, blockHeight, outputKind, serializedOutputLength, outputHash]))
+  // blockHeight is the height of the finalised target-chain block holding the
+  // transaction the attestation describes, in the target chain's own
+  // numbering (a slot on Solana). Every input is fixed-width, so the digest of
+  // any output is computed by this one circuit.
+  export pure circuit calculateSignetAttestationDigestV1(
     requestId: RequestId,
     blockHeight: Uint<64>,
     outputKind: OutputKind,
-    serializedOutput: Bytes<serializedOutputLength>,
+    serializedOutputLength: Uint<64>,
+    outputHash: Bytes<32>,
   ): Bytes<32> {
-    return upgradeFromTransient(transientHash<[HashDomain, RequestId, Uint<64>, OutputKind, Uint<64>, Bytes<serializedOutputLength>]>([HashDomain.attestationDigest, requestId, blockHeight, outputKind, serializedOutputLength, serializedOutput]));
+    return upgradeFromTransient(transientHash<[HashDomain, RequestId, Uint<64>, OutputKind, Uint<64>, Bytes<32>]>([HashDomain.attestationDigest, requestId, blockHeight, outputKind, serializedOutputLength, outputHash]));
   }
 
-  // Verifies a RespondBidirectionalEvent against its execution output and MPC
-  // response key: recomputes the digest over the request id, block height,
-  // output kind, output length and caller's output, then verifies its signature. Client
-  // contracts run this before consuming outputs, as the singleton emits
-  // responses unverified. The caller supplies
-  // serializedOutput at its exact unpadded width, and the event record with
-  // signature.bigR.x and signature.s byte-reversed into LITTLE-endian: the
-  // scalar casts below read little-endian bytes, and the wire/ledger records
-  // are big-endian, so the reversal happens off-chain where it costs nothing
-  // (the TS SDK's respondBidirectionalEventToCircuitInput does it). A wrong
-  // byte order fails verification, never a false accept. Of the event, requestId,
-  // blockHeight, outputKind, signature.bigR.x and signature.s enter verification:
-  // serializedOutputLength and digest serve off-chain readers. The digest binds
-  // the event's requestId, so a client MUST consume that request and no other. An s
-  // that reduces to 0 mod the curve order aborts the
-  // circuit rather than returning false, so sift candidate posts off chain
-  // first (verifyRespondBidirectionalSignature).
-  export pure circuit verifyRespondBidirectionalEventV1<#serializedOutputLength>(
-    serializedOutput: Bytes<serializedOutputLength>,
+  // Verifies a RespondBidirectionalEvent's signature against the MPC response
+  // key, without the output: recomputes the digest from the event's request
+  // id, block height, output kind, output length and output hash. The event's
+  // digest field is never read. A true result proves the MPC attested this
+  // outcome for this request, and an output the event carries only as its
+  // length and hash: a client that consumes output bytes checks them against
+  // that length and hash with verifyAttestedOutputV1, or verifies with
+  // verifyRespondBidirectionalEventV1, which does both.
+  // The caller supplies the event record with signature.bigR.x and
+  // signature.s byte-reversed into LITTLE-endian: the scalar casts below read
+  // little-endian bytes, and the wire/ledger records are big-endian, so the
+  // reversal happens off-chain where it costs nothing (the TS SDK's
+  // respondBidirectionalEventToCircuitInput does it). A wrong byte order fails
+  // verification, never a false accept. The digest binds the event's
+  // requestId, so a client MUST consume that request and no other. An s that
+  // reduces to 0 mod the curve order aborts the circuit rather than returning
+  // false, so sift candidate posts off chain first
+  // (verifyRespondBidirectionalAttestation).
+  export pure circuit verifyRespondBidirectionalAttestationV1(
     respondBidirectionalEvent: RespondBidirectionalEventV1,
     mpcResponseKey: Secp256k1Point
   ): Boolean {
-    const digest = calculateSignetAttestationDigestV1<serializedOutputLength>(
+    const digest = calculateSignetAttestationDigestV1(
       respondBidirectionalEvent.requestId,
       respondBidirectionalEvent.blockHeight,
       respondBidirectionalEvent.outputKind,
-      serializedOutput,
+      respondBidirectionalEvent.serializedOutputLength,
+      respondBidirectionalEvent.outputHash,
     );
 
     return secp256k1EcdsaVerify(
@@ -428,17 +456,57 @@ module Signet {
     );
   }
 
+  // Whether serializedOutput is the output an attestation declares: its width
+  // is attestedOutputLength and its hash attestedOutputHash. Both checks are
+  // needed, as the hash alone does not commit to the width (see
+  // calculateAttestedOutputHashV1). Proves nothing about the attestation
+  // itself: the length and hash must come from a RespondBidirectionalEvent that
+  // passed verifyRespondBidirectionalAttestationV1, read from the event or
+  // from a copy the contract stored when it verified the event.
+  export pure circuit verifyAttestedOutputV1<#serializedOutputLength>(
+    serializedOutput: Bytes<serializedOutputLength>,
+    attestedOutputLength: Uint<64>,
+    attestedOutputHash: Bytes<32>
+  ): Boolean {
+    const lengthMatches = attestedOutputLength == serializedOutputLength;
+    const hashMatches = attestedOutputHash == calculateAttestedOutputHashV1<serializedOutputLength>(serializedOutput);
+    return lengthMatches && hashMatches;
+  }
+
+  // Verifies a RespondBidirectionalEvent against its execution output and MPC
+  // response key: the output is the one the event attests (verifyAttestedOutputV1
+  // against the event's length and hash) and the event's signature verifies
+  // (verifyRespondBidirectionalAttestationV1, whose byte-order and abort
+  // contract applies here too). Client contracts run this before consuming
+  // outputs, as the singleton emits responses unverified. The caller supplies
+  // serializedOutput at its exact unpadded width.
+  export pure circuit verifyRespondBidirectionalEventV1<#serializedOutputLength>(
+    serializedOutput: Bytes<serializedOutputLength>,
+    respondBidirectionalEvent: RespondBidirectionalEventV1,
+    mpcResponseKey: Secp256k1Point
+  ): Boolean {
+    // Both checks run unconditionally: the signature check's scalar casts
+    // cannot sit in the short-circuited operand of &&.
+    const outputMatches = verifyAttestedOutputV1<serializedOutputLength>(
+      serializedOutput,
+      respondBidirectionalEvent.serializedOutputLength,
+      respondBidirectionalEvent.outputHash
+    );
+    const attested = verifyRespondBidirectionalAttestationV1(respondBidirectionalEvent, mpcResponseKey);
+    return outputMatches && attested;
+  }
+
   // ---- EVM Type2 Transaction Parameters --------------------------------------------------------------
 
   // The caip2Id of every request targeting Ethereum, whichever Ethereum network the
-  // MPC node watches (mainnet, Sepolia or a local anvil: node configuration picks it).
+  // MPC deployment watches (mainnet, Sepolia or a local anvil: set per deployment).
   // The MPC routes on this exact string (Chain::Ethereum in sig-net/mpc
   // signet-primitives/src/chain.rs) and rejects the request for any other value,
   // the network's own CAIP-2 id included. EvmType2TxParams.chainId is what binds
   // the signed transaction to one network. Ethereum only: another EVM chain, such as
   // BNB Smart Chain, is a separate chain to the MPC, never one of Ethereum's networks.
-  export pure circuit ethereumCaip2Id(): Bytes<32> {
-    return pad(32, "eip155:1");
+  export pure circuit ethereumCaip2Id(): Bytes<64> {
+    return pad(64, "eip155:1");
   }
 
   // The EVM transaction to be signed, decomposed into typed fields
@@ -462,7 +530,7 @@ module Signet {
     maxPriorityFeePerGas: Uint<128>; // wei
     maxFeePerGas: Uint<128>;         // wei
     gasLimit: Uint<64>;              // gas ceiling for the call
-    to: Bytes<20>;                   // call target (e.g. the ERC20 contract)
+    to: Bytes<20>;                   // recipient (e.g. the ERC20 contract)
     value: Uint<128>;                // ETH sent with the call, in wei
     calldata: Maybe<EvmCalldata<maxCalldataWords>>; // none = plain ETH transfer ("0x" data)
     accessListEntryCount: Uint<8>;   // how many leading accessList entries are real

package/src/circuits.compact

@@ -12,6 +12,8 @@ export {
   HashDomain,
   OutputKind,
   calculateRequestIdV1,
+  calculateSignetAttestationDigestV1,
+  verifyRespondBidirectionalAttestationV1,
   constructSignBidirectionalEventNotificationV1,
   ethereumCaip2Id,
   evmAddressAbiWord,
@@ -22,56 +24,62 @@ export {
   checkedTruncationU128
 };
 
-// ---- Fixed-width attestation oracles (tests only) --------------------------
-// The size-generic digest and verify circuits cannot appear in the export
-// list above. These fixed-width instantiations exist solely to pin the TS
-// twin in ecdsa-attestation.ts against the compiled circuits (widths 0, 1, 2,
-// 32 and 100, where 0 is the empty output of a failed or unviable execution).
-// Client contracts instantiate the generic circuits at their own width.
-
-export pure circuit calculateSignetAttestationDigest0(
-  requestId: RequestId,
-  blockHeight: Uint<64>,
-  outputKind: OutputKind,
+// ---- Fixed-width output hash oracles (tests only) --------------------------
+// The size-generic output hash and verify circuits cannot appear in the
+// export list above. These fixed-width instantiations exist solely to pin
+// the TS twin in ecdsa-attestation.ts against the compiled circuits (widths
+// 0, 1, 2, 32 and 100, where 0 is the empty output of a failed or unviable
+// execution). Client contracts instantiate the generic circuits at their own
+// width.
+
+export pure circuit calculateAttestedOutputHash0(
   serializedOutput: Bytes<0>
 ): Bytes<32> {
-  return calculateSignetAttestationDigestV1<0>(requestId, blockHeight, outputKind, serializedOutput);
+  return calculateAttestedOutputHashV1<0>(serializedOutput);
 }
 
-export pure circuit calculateSignetAttestationDigest1(
-  requestId: RequestId,
-  blockHeight: Uint<64>,
-  outputKind: OutputKind,
+export pure circuit calculateAttestedOutputHash1(
   serializedOutput: Bytes<1>
 ): Bytes<32> {
-  return calculateSignetAttestationDigestV1<1>(requestId, blockHeight, outputKind, serializedOutput);
+  return calculateAttestedOutputHashV1<1>(serializedOutput);
 }
 
-export pure circuit calculateSignetAttestationDigest2(
-  requestId: RequestId,
-  blockHeight: Uint<64>,
-  outputKind: OutputKind,
+export pure circuit calculateAttestedOutputHash2(
   serializedOutput: Bytes<2>
 ): Bytes<32> {
-  return calculateSignetAttestationDigestV1<2>(requestId, blockHeight, outputKind, serializedOutput);
+  return calculateAttestedOutputHashV1<2>(serializedOutput);
 }
 
-export pure circuit calculateSignetAttestationDigest32(
-  requestId: RequestId,
-  blockHeight: Uint<64>,
-  outputKind: OutputKind,
+export pure circuit calculateAttestedOutputHash32(
   serializedOutput: Bytes<32>
 ): Bytes<32> {
-  return calculateSignetAttestationDigestV1<32>(requestId, blockHeight, outputKind, serializedOutput);
+  return calculateAttestedOutputHashV1<32>(serializedOutput);
 }
 
-export pure circuit calculateSignetAttestationDigest100(
-  requestId: RequestId,
-  blockHeight: Uint<64>,
-  outputKind: OutputKind,
+export pure circuit calculateAttestedOutputHash100(
   serializedOutput: Bytes<100>
 ): Bytes<32> {
-  return calculateSignetAttestationDigestV1<100>(requestId, blockHeight, outputKind, serializedOutput);
+  return calculateAttestedOutputHashV1<100>(serializedOutput);
+}
+
+// Fixed-width instantiations of verifyAttestedOutputV1, pinning its TS twin
+// verifyAttestedOutput, including the trailing-zero case the length check
+// exists for (a 2-byte output against a 1-byte attestation).
+
+export pure circuit verifyAttestedOutput1(
+  serializedOutput: Bytes<1>,
+  attestedOutputLength: Uint<64>,
+  attestedOutputHash: Bytes<32>
+): Boolean {
+  return verifyAttestedOutputV1<1>(serializedOutput, attestedOutputLength, attestedOutputHash);
+}
+
+export pure circuit verifyAttestedOutput2(
+  serializedOutput: Bytes<2>,
+  attestedOutputLength: Uint<64>,
+  attestedOutputHash: Bytes<32>
+): Boolean {
+  return verifyAttestedOutputV1<2>(serializedOutput, attestedOutputLength, attestedOutputHash);
 }
 
 // ---- Fixed-width transaction digest oracles (tests only) --------------------