@sig-net/midnight 0.0.9 → 0.11.0

package/README.md

@@ -2,146 +2,288 @@
 
 The client-agnostic [Sig Network](https://sig.network) protocol library for the [Midnight blockchain](https://midnight.network), and the seed of a future signet.js Midnight adapter. It carries everything a Midnight contract or off-chain client needs to speak the signet protocol (the MPC's [sign bidirectional flow](https://docs.sig.network/architecture/sign-bidirectional)) without binding to any particular contract.
 
+> ## 🚧 Under Construction 🚧
+>
+> This Sig Network Midnight integration is still under construction.
+> Use at your own risk and expect rapid iteration.
+
 ## What is in it
 
 - **Shared Compact modules**: the package ships its `.compact` sources, so contracts import them directly:
   ```compact
   import "@sig-net/midnight/src/Signet";
   ```
-- **Compiled pure circuits** (`pureCircuits`): the executable reference implementation of the client-agnostic circuits (path/identity checks, the attestation message, the sign-bidirectional notification packer, the Schnorr challenge). Off-chain code calls these compiled artefacts instead of re-porting the algorithms, so it always agrees with what the contracts prove.
+- **Compiled pure circuits** (`pureCircuits`): the executable reference implementation of the client-agnostic circuits (the attestation digest, response verification, the deploy-time key pin, the notification packer, the ABI word builders and readers). Off-chain code calls these compiled artefacts instead of re-porting the algorithms, so it always agrees with what the contracts prove.
 - **TypeScript twins of the wire structs** and signet request-id computation.
 - **State readers, request feed and resolver**: poll the signet contract for pending requests and their signature / remote-execution responses.
-- **Crypto helpers**: epsilon derivation and Jubjub Schnorr response verification.
+- **Crypto helpers**: epsilon derivation and ECDSA attestation verification.
+
+Where signet.js already covers something (for example EVM transaction preparation or address derivation), import it from there. Only what is Midnight-specific lives here.
+
+## Install
+
+```sh
+npm install @sig-net/midnight
+```
+
+## Sign bidirectional flow
+
+The flow comprises 5 steps:
 
-Where signet.js already covers something (for example EVM transaction preparation or address derivation), import it from there; only what is Midnight-specific lives here.
+1. Client calls a contract on Midnight which requests a signature for a transaction destined for a foreign chain. The signature is made with a key derived for the requesting contract (see [Derived keys](#derived-keys)).
+2. The Sig Network MPC honours the request, generating the transaction signature and posting it back to Midnight.
+3. Client extracts the signature, using it to submit the signed transaction to the foreign chain.
+4. The Sig Network MPC observes the foreign transaction and posts the output of the execution (signed) back to Midnight.
+5. Client extracts the signed foreign execution output and submits it back to the Midnight contract, which verifies the MPC's signature over it in-circuit against the contract's own response key (see [Derived keys](#derived-keys)), completing the foreign transaction execution.
 
 ## Derived keys
 
-Every key the MPC signs with is scoped by the requesting contract:
+Every key the MPC uses is derived for the requesting contract and a path. There are two kinds: the request signing key, whose path each contract chooses, and the response signing key, whose path is fixed by the protocol. Both key derivations are **scoped by the address** of the requesting contract.
 
-`derivedSigningKey = f(mpcRootKey[keyVersion], contractAddress, path)`
+### Request signing key
 
-The path is 32 opaque bytes of the contract's choosing (a fixed literal for a contract-owned account, a hash of a caller's secret for per-user accounts). There are no format requirements. The contract address is always part of the derivation, so no contract can reach another contract's derived keys.
+The key the MPC signs requested foreign transactions with:
 
-## Install
+`requestSigningKey = f(mpcRootKey[keyVersion], contractAddress, path)`
 
-```sh
-npm install @sig-net/midnight
+The path is 32 opaque bytes of the contract's choosing (e.g. a fixed literal for a contract-owned account like "vault", or a hash of a caller's secret for per-user accounts). There are no format requirements. The contract address is always part of the derivation, so no contract can reach another contract's derived keys.
+
+### Response key
+
+The key the MPC signs foreign execution outputs with when posting them back to Midnight:
+
+`responseKey = f(mpcRootKey[keyVersion], contractAddress, "midnight response key")`
+
+The same derivation, but with the path fixed to the literal `"midnight response key"`, giving each contract one well-known response key. A contract pins its own response key in its ledger after deploy and verifies every response against it in-circuit (step 5 of the flow above).
+
+## Integrator guide
+
+A signet-compliant client contract does four things: it stores its requests in a public `SignBidirectionalEventMap` in its own ledger, it pins its counterparties (the Signet singleton contract and its own MPC response key), it submits signature requests, and it verifies execution responses in-circuit. Concretely, the integration consists of:
+
+- 3 once-off **setup** steps
+- 5 per-request **runtime** steps that drive the full sign bidirectional flow
+
+### Setup
+
+Set up your contract for integration with the Sig Network MPC's sign bidirectional flow:
+
+1. Import the Signet module at the top of your contract (resolved through `node_modules` via `COMPACT_PATH`):
+
+   ```compact
+   import "@sig-net/midnight/src/Signet";
+   ```
+
+   Then tell the compact compiler about the npm packages with its `COMPACT_PATH` environment variable at compile time:
+
+   ```sh
+   COMPACT_PATH=node_modules compact compile --feature-zkir-v3 src/my-contract.compact src/managed/my-contract
+   ```
+
+   Compile with the pinned toolchain (currently `compact update 0.33.0-rc.2`) and always pass `--feature-zkir-v3`: compiled output without it is not compatible with the ledger-9 matched stack (node, indexer, proof server).
+
+2. Declare the required Sig Network protocol state in your ledger (plus recommended deployer identity and initialisation state). The event map can sit at ANY ledger field: each notification your contract registers names the field position holding it (runtime step 1), and the MPC reads the authenticated request from there.
+
+   ```compact
+   // Required: Map of SignBidirectionalEvent signature requests, configured by transaction type.
+   // Configured and sized here for an EVM Type 2 transaction with
+   // <1 calldata word, 0 access-list entries, 0 storage keys> and
+   // 34-byte serialisation schemas.
+   export ledger signBidirectionalEventMap: SignBidirectionalEventMap<EvmType2TxParams<1, 0, 0>, 34, 34>;
+
+   // Required: The Signet singleton signer interface, set at deploy.
+   // Used to notify the MPC of events you add to your signBidirectionalEventMap.
+   sealed ledger signetSigner: SignetSigner;
+
+   // Required: This contract's MPC response key, set in step 3.
+   // Used to verify RespondBidirectionalEvents containing the serialised output of foreign chain execution.
+   export ledger mpcResponseKey: Secp256k1Point;
+
+   // Recommended: contract-local source of request nonces, so identical
+   // requests hash to distinct request ids. Nothing off-chain reads it.
+   export ledger signetRequestNonce: Counter;
+
+   // Recommended: used in step 3 to ensure initialisation runs only once.
+   export ledger initialised: Counter;
+
+   // Recommended: set on deploy, used in step 3 to ensure only the deployer may set the mpcResponseKey.
+   sealed ledger deployer: Bytes<32>;
+
+   // Recommended: supplies the deployer's identity secret from private state
+   // off-chain; only its commitment (below) ever reaches the ledger.
+   witness witnessDeployerSecretKey(): Bytes<32>;
+
+   // Recommended: the deployer identity commitment scheme. Exported so deploy
+   // tooling can compute the constructor argument by calling the compiled circuit.
+   export pure circuit calculateDeployerCommitment(sk: Bytes<32>): Bytes<32> {
+     return persistentHash<Vector<2, Bytes<32>>>([pad(32, "my-contract:deployer:"), sk]);
+   }
+
+   // Required: set signet contract and (recommended) deployer commitment on deployment.
+   constructor(signetContract: SignetSigner, deployerCommitment: Bytes<32>) {
+     signetSigner = disclose(signetContract);
+     deployer = disclose(deployerCommitment);
+   }
+   ```
+
+3. Set the contract's MPC response key once, right after deploy. Deriving this key requires the address of the contract, which only exists after deploy (see [Response key](#response-key)):
+
+   ```compact
+   export circuit initialise(responseKey: Secp256k1Point): [] {
+     // Recommended: confirm that only the deployer may initialise, and only once:
+     assert(deployer == calculateDeployerCommitment(witnessDeployerSecretKey()), "Not the deployer");
+     assert(initialised == 0, "Already initialised");
+     initialised.increment(1);
+
+     // Required: set MPC response key for verification of RespondBidirectionalEvents
+     mpcResponseKey = disclose(responseKey);
+   }
+   ```
+
+### Runtime
+
+Each interaction with your contract that executes a transaction on a foreign chain runs these 5 steps.
+
+Steps 1 and 5 are circuits on your contract, and steps 2 to 4 are off-chain client code built on the utilities in `@sig-net/midnight`.
+
+The off-chain steps share one `SignetRequestResponseReader` over your contract / Signet singleton pair, and the expected signer of the requested transaction (the key the MPC derives for your contract and the request's path, see [Derived keys](#derived-keys)):
+
+```ts
+import { indexerPublicDataProvider } from "@midnight-ntwrk/midnight-js-indexer-public-data-provider";
+import { deriveEvmAddress, SignetRequestResponseReader } from "@sig-net/midnight";
+
+// SignetRequestResponseReader to poll for Signed Transactions and Signed RespondBidirectionalEvents
+const reader = new SignetRequestResponseReader({
+   // Address of YOUR deployed contract
+   requesterContractAddress: myContractAddress,
+
+   // signBidirectionalEventMap's field position (Setup step 2)
+   requesterRequestsIndexField: 0,
+
+   // Address of the Signet singleton contract
+   signetContractAddress,
+
+   // Provider to index Midnight Blockchain
+   publicDataProvider: indexerPublicDataProvider({
+      queryURL: indexerUrl,
+      subscriptionURL: indexerWsUrl
+   }),
+});
+
+const expectedSigner = deriveEvmAddress(mpcRootPublicKey, myContractAddress, "my-path");
+```
+
+1. Store a signature request and notify the MPC via cross contract call. Build (or overwrite) every part of the transaction your contract enforces in-circuit, calldata above all (see [EVM Type 2 transactions and ABI calldata words](#evm-type-2-transactions-and-abi-calldata-words)); never pass caller input through unchecked:
+
+   ```compact
+   // Construct SignBidirectionalEvent signature request and calculate its RequestId
+   const request = constructSignBidirectionalEvent<EvmType2TxParams<1, 0, 0>, 34, 34>(/* ... */);
+   const requestId = disclose(calculateRequestId<EvmType2TxParams<1, 0, 0>, 34, 34>(request));
+
+   // Store the signature request in your signBidirectionalEventMap for MPC to discover
+   signetRequestNonce.increment(1);
+   signBidirectionalEventMap.insert(requestId, disclose(request));
+
+   // Notify the MPC of the SignBidirectionalEvent and the location of your signBidirectionalEventMap.
+   // The location is 0 here based on the position of the declaration in Setup step 2.
+   signetSigner.signBidirectional(
+      requestId,
+      constructSignBidirectionalEventNotificationV1(kernel.self(), 0 as Uint<8>),
+   );
+   ```
+
+   **NOTE:** `requestId` should be returned from the above circuit call so that it may be used in subsequent steps (or compute it off-chain with the `calculateRequestId` TS twin).
+
+2. Poll the Signet singleton for the MPC's signature response. The response log is unauthenticated (anyone can post), so use the verifying getter: it only returns a post whose signature recovers to `expectedSigner` over the requested transaction's signing hash:
+
+   ```ts
+   const { verified } = await reader.getVerifiedSignatureRespondedEvent(requestId, expectedSigner);
+   // verified === undefined: no valid response posted yet, poll again.
+   ```
+
+3. Construct the signed transaction and submit it to the foreign chain. The reader rebuilds the transaction from the request record on your ledger and attaches the verified MPC signature:
+
+   ```ts
+   import { JsonRpcProvider } from "ethers";
+
+   const signedTx = await reader.getSignedEvmTransaction(requestId, expectedSigner);
+   await new JsonRpcProvider(foreignChainRpcUrl).broadcastTransaction(signedTx.serialized);
+   ```
+
+4. Poll the Signet singleton for the MPC's signed remote execution output (posted once the MPC observes the transaction execute on the foreign chain). Posts are stored unverified, so treat them as candidates: the authoritative check is your contract's verify circuit in step 5:
+
+   ```ts
+   const [respondBidirectionalEvent] = await reader.getRespondBidirectionalEvents(requestId);
+   // Empty array: not posted yet, poll again.
+   ```
+
+5. Deliver the response to your contract, which verifies it in-circuit against the response key pinned in Setup step 3 and consumes the request:
+
+   ```compact
+   assert(
+      verifyRespondBidirectionalEvent(requestId, respondBidirectionalEvent, mpcResponseKey),
+      "Invalid attestation signature"
+   );
+   signBidirectionalEventMap.remove(requestId);
+   ```
+
+## EVM Type 2 transactions and ABI calldata words
+
+An `EvmType2TxParams` request decomposes the EVM transaction into typed fields your contract can enforce field by field in-circuit. Its optional `calldata` is an `EvmCalldata<maxWords>`: the 4-byte function selector plus a list of 32-byte ABI words, per the [Solidity ABI spec](https://docs.soliditylang.org/en/latest/abi-spec.html). Slots past `noWords` are unused capacity and never reach the transaction.
+
+Every word must be stored in canonical ABI form (big-endian). The MPC signs a transaction whose calldata is exactly `selector || words[0..noWords]`, byte for byte, so a word stored in any other form becomes a signed transaction calling the foreign contract with garbage arguments. Compact's integer casts are little-endian, so do not hand-roll the byte order: build every word with the module's helper circuits, and read words back with the matching readers.
+
+| Solidity type | Build with | Read back with |
+|---|---|---|
+| `address` | `evmAddressAbiWord(addr: Bytes<20>)` | |
+| unsigned integers up to `uint128` (amounts, ids) | `numericAbiWord(value: Uint<128>)` | `abiWordToUint128(word)` |
+| `bool` | `boolAbiWord(value: Boolean)` | `abiWordToBool(word)` |
+
+### Example: an ERC20 transfer
+
+`transfer(address,uint256)`, selector `0xa9059cbb`, takes an address word and a numeric word:
+
+```compact
+const calldata = EvmCalldata<2> {
+  selector: Bytes[0xa9, 0x05, 0x9c, 0xbb],
+  noWords: 2 as Uint<16>,
+  words: [
+    evmAddressAbiWord(recipient),  // address argument (Bytes<20>)
+    numericAbiWord(amount)         // uint256 argument (from a Uint<128>)
+  ]
+};
 ```
 
-## How a client contract integrates
+### Example: a bool argument, and decoding a bool result
 
-A signet-compliant client contract does four things:
+`setApprovalForAll(address,bool)`, selector `0xa22cb465`:
 
-1. **Stores requests in a public index**: a `SignBidirectionalRequestIndex` map in its ledger. The index can sit at ANY ledger field: each notification the contract registers names the field position holding it, and the MPC reads the authenticated request from there. A contract-local `SignetNonce` counter is a convenient source of request nonces (identical requests must hash to distinct ids); nothing off-chain reads it.
-2. **Pins its counterparties at deploy time**: the central signet contract it notifies, and the MPC attestation key its verify circuit accepts.
-3. **Submits signature requests**: builds the transaction decomposition in-circuit, constructs the canonical request record, stores it in its own index under the request id, and registers a notification in the central registry (which the MPC polls; the MPC then reads the authenticated request back from the ledger field the notification names).
-4. **Verifies the execution response**: checks the attestation key, verifies the MPC's Schnorr attestation in-circuit over (request id, output), and consumes the request.
+```compact
+const calldata = EvmCalldata<2> {
+  selector: Bytes[0xa2, 0x2c, 0xb4, 0x65],
+  noWords: 2 as Uint<16>,
+  words: [
+    evmAddressAbiWord(operator),
+    boolAbiWord(true)
+  ]
+};
+```
+
+The readers run the same rules in the other direction, rejecting any non-canonical word instead of silently truncating or coercing it. A `RespondBidirectionalEvent`'s `serializedOutput` is the ABI-encoded return data of the remote call, so a settle circuit can decode an ERC20 `transfer`'s `bool` return from the first output word:
 
 ```compact
-pragma language_version >= 0.25;
-
-import CompactStandardLibrary;
-import "@sig-net/midnight/src/Signet";
-
-// (1) The request index: the public map the MPC reads requests back from.
-// It can sit at any ledger field; the notification in submitSignatureRequest
-// names its position (0 in this contract). The counter is contract-local
-// (it sources each request's nonce so identical requests get distinct ids);
-// the MPC never reads it. The generic size parameters cap the EVM calldata
-// words, access list entries and storage keys your requests may carry.
-export ledger signetRequestsIndex: SignBidirectionalRequestIndex<EVMType2TxParams<1, 0, 0>>;
-export ledger signetNonce: SignetNonce;
-
-// (2) Pinned at deploy time.
-export sealed ledger mpcPubKeyHash: Bytes<32>;
-sealed ledger signetNotifier: SignetNotifier;
-
-constructor(mpcPk: JubjubPoint, signetContract: SignetNotifier) {
-  mpcPubKeyHash = disclose(persistentHash<JubjubPoint>(mpcPk));
-  signetNotifier = disclose(signetContract);
-}
-
-// (3) Construct, store and announce a signature request.
-export circuit submitSignatureRequest(evmNonce: Uint<64>, keyVersion: Uint<32>): [] {
-  // Decompose the EVM transaction to be signed. Build (or overwrite) every
-  // part your contract enforces in-circuit, calldata above all; never pass
-  // caller input through unchecked.
-  const txParams = EVMType2TxParams<1, 0, 0> {
-    to: pad(20, "recipient"),
-    chainId: 31337 as Uint<64>,
-    nonce: evmNonce,
-    gasLimit: 100000 as Uint<64>,
-    maxFeePerGas: 30000000000 as Uint<128>,
-    maxPriorityFeePerGas: 1000000000 as Uint<128>,
-    value: 0 as Uint<128>,
-    accessListEntryCount: 0,
-    accessList: [],
-    calldata: none<EVMCalldata<1>>()
-  };
-
-  // The canonical request record. This variant signs with the CONTRACT's own
-  // derived account (a path literal the contract fixes); use
-  // constructSignBidirectionalRequest instead for caller-identity requests,
-  // where the path is bound to the caller's identity commitment.
-  const schema = pad(128, "[{\"name\":\"success\",\"type\":\"bool\"}]");
-  const request = constructContractPathSignBidirectionalRequest<EVMType2TxParams<1, 0, 0>>(
-    signetNonce as Uint<64>,      // contract-local request nonce
-    TxParamType.evmType2,
-    txParams,
-    pad(32, "eip155:31337"),      // target chain (CAIP-2)
-    keyVersion,                    // MPC root-key version (>= 1)
-    pad(256, "my-treasury"),      // contract-owned derivation path
-    pad(32, "ecdsa"),
-    pad(32, "ethereum"),
-    pad(64, ""),
-    schema,
-    schema
-  );
-
-  // Store the request in YOUR ledger under its id, then register the
-  // notification in the central signet contract's registry. The final
-  // argument is the ledger field position of signetRequestsIndex, which is
-  // how the MPC finds the index to read the request back from.
-  const requestId = disclose(calculateRequestId<EVMType2TxParams<1, 0, 0>>(request));
-  assert(!signetRequestsIndex.member(requestId), "Request already exists");
-  signetNonce.increment(1);
-  signetRequestsIndex.insert(requestId, disclose(request));
-  signetNotifier.notifyBidirectionalSignatureRequest(requestId,
-    constructSignBidirectionalNotificationV1(kernel.self(), requestId as Bytes<32>, 0 as Uint<8>));
-}
-
-// (4) Verify the MPC's Schnorr-signed attestation of the remote execution
-// and consume the request (double-verify protection).
-export circuit verifyResponse(requestId: RequestId, respondBidirectional: RespondBidirectional): [] {
-  const rid = disclose(requestId);
-  assert(
-    persistentHash<JubjubPoint>(respondBidirectional.pk) == mpcPubKeyHash,
-    "Unauthorized: attestation pk is not the MPC key"
-  );
-  assert(
-    jubjubSchnorrVerify<4>(
-      signetAttestationMessage(rid, respondBidirectional.serializedOutput, respondBidirectional.outputLen),
-      JubjubSchnorrSignature {
-        announcement: respondBidirectional.announcement,
-        response: respondBidirectional.response,
-      },
-      respondBidirectional.pk
-    ),
-    "Invalid attestation signature"
-  );
-  assert(signetRequestsIndex.member(rid), "Request not found");
-  signetRequestsIndex.remove(rid);
-}
+const success = abiWordToBool(slice<32>(respondBidirectionalEvent.serializedOutput, 0));
+assert(success, "Remote transfer failed");
 ```
 
-Between the two circuits sit the off-chain steps, which this package also covers: poll the central signet contract with `SignetRequestResponseReader` (configured with both contract addresses and the ledger field position of your request index) to collect and verify the MPC's secp256k1 signature (then broadcast the signed transaction to the destination chain), and later the Schnorr-attested execution output to feed back into `verifyResponse`.
+The same builders and readers exist as TypeScript twins under identical names, for composing expected words off-chain (UIs, expected-record builders, tests). They are kept in lockstep with the compiled circuits by this package's test suite.
+
+## More examples
 
-The [signet-caller contract](https://github.com/sig-net/midnight-integration/blob/main/packages/caller-contract/src/signet-caller.compact) is the complete, runnable version of this skeleton, exercised end to end by the repository's integration suite; a fuller application (an ERC20 cross-chain vault) lives in [sig-net/midnight-examples](https://github.com/sig-net/midnight-examples).
+For full integration examples (such as an ERC20 cross chain vault) see the [`sig-net/midnight-examples`](https://github.com/sig-net/midnight-examples) repository.
 
 ## Related packages
 
 - [`@sig-net/midnight-contract`](https://www.npmjs.com/package/@sig-net/midnight-contract): the central signet contract this library reads from.
 - [`@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); example applications live in [sig-net/midnight-examples](https://github.com/sig-net/midnight-examples).
+Developed in [sig-net/midnight-integration](https://github.com/sig-net/midnight-integration).

package/dist/constants.d.ts

@@ -2,7 +2,7 @@
 export declare const CAIP2_ID_BYTES = 32;
 /** Width of `SignBidirectionalEvent.params` (`Bytes<64>`). */
 export declare const MPC_PARAMS_BYTES = 64;
-/** Width of `EVMCalldata.selector` (`Bytes<4>`) — the literal first 4 calldata bytes. */
+/** Width of `EvmCalldata.selector` (`Bytes<4>`) — the literal first 4 calldata bytes. */
 export declare const SELECTOR_BYTES = 4;
 /** Width of `RespondBidirectionalEvent.serializedOutput` (`Bytes<128>`). */
 export declare const SERIALIZED_OUTPUT_BYTES = 128;

package/dist/constants.js

@@ -11,7 +11,7 @@
 export const CAIP2_ID_BYTES = 32;
 /** Width of `SignBidirectionalEvent.params` (`Bytes<64>`). */
 export const MPC_PARAMS_BYTES = 64;
-/** Width of `EVMCalldata.selector` (`Bytes<4>`) — the literal first 4 calldata bytes. */
+/** Width of `EvmCalldata.selector` (`Bytes<4>`) — the literal first 4 calldata bytes. */
 export const SELECTOR_BYTES = 4;
 /** Width of `RespondBidirectionalEvent.serializedOutput` (`Bytes<128>`). */
 export const SERIALIZED_OUTPUT_BYTES = 128;

package/dist/ecdsa-attestation.d.ts

@@ -1,4 +1,5 @@
 import type { Secp256k1Point } from "@midnight-ntwrk/compact-runtime";
+import type { MpcSignature } from "./signet-contract-state-reader.ts";
 export type { Secp256k1Point } from "@midnight-ntwrk/compact-runtime";
 /** secp256k1 curve (group) order n. */
 export declare const SECP256K1_ORDER: bigint;
@@ -23,11 +24,30 @@ export declare function bytesToBigint(bytes: Uint8Array): bigint;
  * @returns The 32-byte little-endian encoding.
  */
 export declare function bigintToBytes32(n: bigint): Uint8Array;
+/**
+ * Convert big-endian bytes to a bigint (SEC1 coordinate order, the byte
+ * order the respond events' stored signature uses).
+ *
+ * @param bytes - Big-endian byte array.
+ * @returns The decoded non-negative integer.
+ */
+export declare function bytesToBigintBE(bytes: Uint8Array): bigint;
+/**
+ * Convert a bigint to exactly 32 BIG-endian bytes (SEC1 scalar/coordinate
+ * order, also the ABI word encoding) — the big-endian counterpart of
+ * {@link bigintToBytes32} and the inverse of {@link bytesToBigintBE}.
+ *
+ * @param value - The non-negative integer to encode.
+ * @returns The 32-byte big-endian encoding.
+ * @throws Error if the value is negative or does not fit 32 bytes.
+ */
+export declare function bigintToBytes32BE(value: bigint): Uint8Array;
 /**
  * An ECDSA signature over the attestation digest, in the MPC's canonical
  * `Signature { big_r, s, recovery_id }` spirit with `r` already reduced to
  * the scalar `big_r.x mod n` — the form Compact's `Secp256k1EcdsaSignature`
- * takes.
+ * takes. Build the stored form for posting in a respond event with
+ * {@link ecdsaSignatureToMpcSignature}.
  */
 export interface EcdsaSignature {
     /** Signature scalar r (= R.x mod n). */
@@ -49,6 +69,38 @@ export interface EcdsaSignature {
  * @returns The signature with its recovery id.
  */
 export declare function signAttestationDigest(digest: Uint8Array, secretKey: Uint8Array): EcdsaSignature;
+/**
+ * Build the stored-form signature both respond events carry from a
+ * scalar-form one: R is reconstructed by decompressing the curve point with
+ * x = `r` and the parity `recoveryId` names — undoing the compression an
+ * `r || s || v` signature performs. For MPC-side posters (the fakenet
+ * signer, tests). The negligible caveat: an R.x that overflowed the curve
+ * order cannot be told apart from its reduced twin, so reconstruction picks
+ * the x equal to `r` itself.
+ *
+ * @param signature - The scalar-form signature (the signer's output shape).
+ * @returns The stored-form signature: R as a full point, big-endian bytes.
+ * @throws Error if the recovery id is not 0 or 1, or `r` is not the x
+ *   coordinate of a secp256k1 point.
+ */
+export declare function ecdsaSignatureToMpcSignature(signature: EcdsaSignature): MpcSignature;
+/**
+ * Read a stored-form signature back into scalar form — the inverse of
+ * {@link ecdsaSignatureToMpcSignature}, for off-chain consumers building a
+ * transaction from the response. In-circuit verification does not need this:
+ * `verifyRespondBidirectionalEvent` takes the stored record as-is. `r` comes
+ * out as `bigR.x` reduced mod the curve order. Rejects records that do not
+ * even hold the shape, since posts are unauthenticated and a malformed
+ * record is garbage, not a signature. `bigR.y` is NOT checked against the
+ * curve or the recovery id: signature verification is the authority, not
+ * this decoder.
+ *
+ * @param signature - The stored-form signature as posted.
+ * @returns The scalar-form signature.
+ * @throws Error if a component has the wrong byte length or the recovery id
+ *   is not 0 or 1.
+ */
+export declare function mpcSignatureToEcdsaSignature(signature: MpcSignature): EcdsaSignature;
 /**
  * Parse a secp256k1 public key from SEC1 hex (compressed or uncompressed,
  * optional `0x` prefix) into the Compact runtime's `Secp256k1Point` shape —

package/dist/ecdsa-attestation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ecdsa-attestation.d.ts","sourceRoot":"","sources":["../src/ecdsa-attestation.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAItE,YAAY,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE,uCAAuC;AACvC,eAAO,MAAM,eAAe,QAA2B,CAAC;AAExD,uEAAuE;AACvE,eAAO,MAAM,SAAS,iFAAiF,CAAC;AAExG;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAMvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAQrD;AAWD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,CAAC,EAAE,MAAM,CAAC;IACV,2DAA2D;IAC3D,CAAC,EAAE,MAAM,CAAC;IACV,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,UAAU,GACpB,cAAc,CAiBhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAcrE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAGtE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,UAAU,GAAG,cAAc,CAO1E"}
+{"version":3,"file":"ecdsa-attestation.d.ts","sourceRoot":"","sources":["../src/ecdsa-attestation.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAItE,YAAY,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE,uCAAuC;AACvC,eAAO,MAAM,eAAe,QAA2B,CAAC;AAExD,uEAAuE;AACvE,eAAO,MAAM,SAAS,iFAAiF,CAAC;AAExG;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAMvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAQrD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAMzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAW3D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,CAAC,EAAE,MAAM,CAAC;IACV,2DAA2D;IAC3D,CAAC,EAAE,MAAM,CAAC;IACV,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,UAAU,GACpB,cAAc,CAiBhB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,cAAc,GAAG,YAAY,CAmBpF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,YAAY,GAAG,cAAc,CAapF;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAcrE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAGtE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,UAAU,GAAG,cAAc,CAO1E"}

package/dist/ecdsa-attestation.js

@@ -1,8 +1,8 @@
 // secp256k1 ECDSA helpers: the TS side of the respond-bidirectional
 // attestation flow in Signet.compact — SIGNING (which needs the secret
 // scalar, so it cannot be a circuit), key parsing/formatting, and the
-// byte-order conversions between noble's bigints and the ledger-stored
-// little-endian scalar bytes. Everything provable stays in Compact: the
+// byte-order conversions between noble's bigints and the little-endian
+// scalar bytes Compact's casts read. Everything provable stays in Compact: the
 // attestation digest is the COMPILED `pureCircuits.signetAttestationDigest`,
 // verification is `pureCircuits.verifyRespondBidirectionalEvent` (the same
 // check client contracts run in-circuit), and the deploy-time key pin is
@@ -48,14 +48,41 @@ export function bigintToBytes32(n) {
     }
     return buf;
 }
-/** Convert big-endian bytes to a bigint (SEC1 coordinate order). */
-function bytesToBigintBE(bytes) {
+/**
+ * Convert big-endian bytes to a bigint (SEC1 coordinate order, the byte
+ * order the respond events' stored signature uses).
+ *
+ * @param bytes - Big-endian byte array.
+ * @returns The decoded non-negative integer.
+ */
+export function bytesToBigintBE(bytes) {
     let value = 0n;
     for (const byte of bytes) {
         value = (value << 8n) | BigInt(byte);
     }
     return value;
 }
+/**
+ * Convert a bigint to exactly 32 BIG-endian bytes (SEC1 scalar/coordinate
+ * order, also the ABI word encoding) — the big-endian counterpart of
+ * {@link bigintToBytes32} and the inverse of {@link bytesToBigintBE}.
+ *
+ * @param value - The non-negative integer to encode.
+ * @returns The 32-byte big-endian encoding.
+ * @throws Error if the value is negative or does not fit 32 bytes.
+ */
+export function bigintToBytes32BE(value) {
+    if (value < 0n || value >= 1n << 256n) {
+        throw new Error(`value does not fit 32 big-endian bytes: ${value}`);
+    }
+    const out = new Uint8Array(32);
+    let v = value;
+    for (let i = 31; i >= 0; i--) {
+        out[i] = Number(v & 0xffn);
+        v >>= 8n;
+    }
+    return out;
+}
 /**
  * ECDSA-sign a 32-byte digest with a secp256k1 secret key, exactly as the
  * MPC signs the attestation digest: RFC 6979 deterministic, low-s, the digest
@@ -85,6 +112,71 @@ export function signAttestationDigest(digest, secretKey) {
     /* v8 ignore next: unreachable for a signature this function just produced */
     throw new Error("signature does not recover to its own public key");
 }
+/**
+ * Build the stored-form signature both respond events carry from a
+ * scalar-form one: R is reconstructed by decompressing the curve point with
+ * x = `r` and the parity `recoveryId` names — undoing the compression an
+ * `r || s || v` signature performs. For MPC-side posters (the fakenet
+ * signer, tests). The negligible caveat: an R.x that overflowed the curve
+ * order cannot be told apart from its reduced twin, so reconstruction picks
+ * the x equal to `r` itself.
+ *
+ * @param signature - The scalar-form signature (the signer's output shape).
+ * @returns The stored-form signature: R as a full point, big-endian bytes.
+ * @throws Error if the recovery id is not 0 or 1, or `r` is not the x
+ *   coordinate of a secp256k1 point.
+ */
+export function ecdsaSignatureToMpcSignature(signature) {
+    if (signature.recoveryId !== 0 && signature.recoveryId !== 1) {
+        throw new Error(`expected a recovery id of 0 or 1, got ${signature.recoveryId}`);
+    }
+    // SEC1 compressed form: parity prefix (02 even, 03 odd) || x big-endian.
+    const parityPrefix = signature.recoveryId === 0 ? "02" : "03";
+    const xHex = signature.r.toString(16).padStart(64, "0");
+    let point;
+    try {
+        point = secp256k1.Point.fromHex(`${parityPrefix}${xHex}`);
+    }
+    catch (error) {
+        throw new Error(`signature r is not the x coordinate of a secp256k1 point (${String(error)})`);
+    }
+    const uncompressed = point.toBytes(false); // 0x04 || x || y
+    return {
+        bigR: { x: uncompressed.slice(1, 33), y: uncompressed.slice(33, 65) },
+        s: bigintToBytes32BE(signature.s),
+        recoveryId: BigInt(signature.recoveryId),
+    };
+}
+/**
+ * Read a stored-form signature back into scalar form — the inverse of
+ * {@link ecdsaSignatureToMpcSignature}, for off-chain consumers building a
+ * transaction from the response. In-circuit verification does not need this:
+ * `verifyRespondBidirectionalEvent` takes the stored record as-is. `r` comes
+ * out as `bigR.x` reduced mod the curve order. Rejects records that do not
+ * even hold the shape, since posts are unauthenticated and a malformed
+ * record is garbage, not a signature. `bigR.y` is NOT checked against the
+ * curve or the recovery id: signature verification is the authority, not
+ * this decoder.
+ *
+ * @param signature - The stored-form signature as posted.
+ * @returns The scalar-form signature.
+ * @throws Error if a component has the wrong byte length or the recovery id
+ *   is not 0 or 1.
+ */
+export function mpcSignatureToEcdsaSignature(signature) {
+    const { bigR, s, recoveryId } = signature;
+    if (bigR.x.length !== 32 || bigR.y.length !== 32 || s.length !== 32) {
+        throw new Error("expected 32-byte bigR.x/bigR.y/s in a stored signature");
+    }
+    if (recoveryId !== 0n && recoveryId !== 1n) {
+        throw new Error(`expected a recovery id of 0 or 1, got ${recoveryId}`);
+    }
+    return {
+        r: bytesToBigintBE(bigR.x) % SECP256K1_ORDER,
+        s: bytesToBigintBE(s),
+        recoveryId: Number(recoveryId),
+    };
+}
 /**
  * Parse a secp256k1 public key from SEC1 hex (compressed or uncompressed,
  * optional `0x` prefix) into the Compact runtime's `Secp256k1Point` shape —