@openzeppelin/miden-multisig-client 0.16.2 → 0.17.0-rc.2

package/src/transaction/summary.ts

@@ -4,28 +4,107 @@ import type {
   TransactionSummary,
   WasmWebClient,
 } from '@miden-sdk/miden-sdk';
-import { AccountId } from '@miden-sdk/miden-sdk';
+import { AccountId, ChainAnchor, Word } from '@miden-sdk/miden-sdk';
 import { getRawMidenClient } from '../raw-client.js';
+import { base64ToUint8Array, uint8ArrayToBase64 } from '../utils/encoding.js';
 
+/**
+ * Index of the first user param carrying the auth-arg salt. The guarded-multisig
+ * auth component zeroes user params 0-2 and fills 3-6 with the auth args, matching
+ * `push.0.0.0` ahead of `multisig::auth_tx` in `guarded_multisig.masm`.
+ */
+const SALT_USER_PARAM_OFFSET = 3;
+
+/**
+ * Captures a `ChainAnchor` for the request at the current sync height and
+ * executes the transaction against it to obtain the summary awaiting
+ * authorization. The anchor is returned alongside the summary so the proposer
+ * can ship it with the signed data; cosigners and the executor then reproduce
+ * the summary — which binds the reference block commitment since protocol
+ * 0.16 — with {@link executeForSummaryAt} regardless of their own sync height.
+ */
 export function executeForSummary(
   client: MidenClient,
   accountId: string,
   txRequest: TransactionRequest,
   midenRpcEndpoint: string,
-): Promise<TransactionSummary>;
+): Promise<{ summary: TransactionSummary; anchor: ChainAnchor }>;
 export function executeForSummary(
   client: WasmWebClient,
   accountId: string,
   txRequest: TransactionRequest,
   midenRpcEndpoint?: string,
-): Promise<TransactionSummary>;
+): Promise<{ summary: TransactionSummary; anchor: ChainAnchor }>;
 export async function executeForSummary(
   client: MidenClient | WasmWebClient,
   accountId: string,
   txRequest: TransactionRequest,
   midenRpcEndpoint?: string,
+): Promise<{ summary: TransactionSummary; anchor: ChainAnchor }> {
+  const acc = AccountId.fromHex(accountId);
+  const rawClient = await getRawMidenClient(client, midenRpcEndpoint);
+  const anchor = await rawClient.chainAnchorForRequest(txRequest);
+  const summary = await rawClient.executeForSummaryAt(acc, txRequest, anchor);
+  return { summary, anchor };
+}
+
+/**
+ * Executes a transaction at the given `ChainAnchor`'s reference block to
+ * obtain the summary awaiting authorization — the anchored counterpart of
+ * {@link executeForSummary} for cosigners and executors holding a proposal's
+ * anchor.
+ */
+export function executeForSummaryAt(
+  client: MidenClient,
+  accountId: string,
+  txRequest: TransactionRequest,
+  anchor: ChainAnchor,
+  midenRpcEndpoint: string,
+): Promise<TransactionSummary>;
+export function executeForSummaryAt(
+  client: WasmWebClient,
+  accountId: string,
+  txRequest: TransactionRequest,
+  anchor: ChainAnchor,
+  midenRpcEndpoint?: string,
+): Promise<TransactionSummary>;
+export async function executeForSummaryAt(
+  client: MidenClient | WasmWebClient,
+  accountId: string,
+  txRequest: TransactionRequest,
+  anchor: ChainAnchor,
+  midenRpcEndpoint?: string,
 ): Promise<TransactionSummary> {
   const acc = AccountId.fromHex(accountId);
   const rawClient = await getRawMidenClient(client, midenRpcEndpoint);
-  return rawClient.executeForSummary(acc, txRequest);
+  return rawClient.executeForSummaryAt(acc, txRequest, anchor);
+}
+
+/**
+ * Serializes a `ChainAnchor` to base64 for the proposal wire payload.
+ */
+export function chainAnchorToBase64(anchor: ChainAnchor): string {
+  return uint8ArrayToBase64(anchor.serialize());
+}
+
+/**
+ * Deserializes a `ChainAnchor` from its base64 wire form. `ChainAnchor`
+ * deserialization validates the header/chain consistency internally, so a
+ * decoded anchor only needs its block commitment checked against the signed
+ * transaction summary before it is safe to execute against.
+ */
+export function chainAnchorFromBase64(anchorBase64: string): ChainAnchor {
+  return ChainAnchor.deserialize(base64ToUint8Array(anchorBase64));
+}
+
+/**
+ * Reads the auth-arg salt back out of a transaction summary.
+ *
+ * Since miden-protocol 0.16-rc the summary binds seven user-defined elements
+ * instead of a dedicated salt word. The guarded-multisig auth component zeroes
+ * the leading three and passes the auth args as the trailing four, so the salt
+ * is the tail of `userParams()`.
+ */
+export function summarySalt(summary: TransactionSummary): Word {
+  return Word.newFromFelts(summary.userParams().slice(SALT_USER_PARAM_OFFSET));
 }

package/src/transaction/updateGuardian.ts

@@ -1,6 +1,4 @@
 import {
-  AdviceMap,
-  FeltArray,
   type MidenClient,
   TransactionRequest,
   TransactionRequestBuilder,
@@ -9,37 +7,38 @@ import {
   Word,
   Word as WordType,
 } from '@miden-sdk/miden-sdk';
-import { GUARDIAN_ECDSA_MASM, GUARDIAN_MASM } from '../account/masm/auth.js';
 import { compileTxScript } from '../raw-client.js';
 import { normalizeHexWord } from '../utils/encoding.js';
 import { randomWord } from '../utils/random.js';
+import { authSchemeId } from '../utils/signature.js';
 import type { MidenClientSignatureOptions, SignatureOptions } from './options.js';
 import type { SignatureScheme } from '../types.js';
 
 async function buildUpdateGuardianScript(
   client: MidenClient | WasmWebClient,
+  newGuardianPubkey: string,
   signatureScheme: SignatureScheme,
   midenRpcEndpoint?: string,
 ): Promise<TransactionScript> {
-  const guardianLibraryPath = 'oz_guardian::guardian';
-  const guardianMasm = signatureScheme === 'ecdsa' ? GUARDIAN_ECDSA_MASM : GUARDIAN_MASM;
+  // A word literal preserves the key's element order on the operand stack.
+  const keyLiteral = normalizeHexWord(newGuardianPubkey);
+  const schemeId = authSchemeId(signatureScheme);
 
+  // Calling the origin procedure yields the same MAST root as its component re-export.
   const scriptSource = `
-use oz_guardian::guardian
+use miden::standards::auth::guardian
 
-begin
-    adv.push_mapval
-    dropw
+@transaction_script
+pub proc main
+    push.${keyLiteral}
+    push.${schemeId}
     call.guardian::update_guardian_public_key
+    drop
+    dropw
 end
   `;
 
-  return compileTxScript(
-    client,
-    scriptSource,
-    [{ namespace: guardianLibraryPath, code: guardianMasm }],
-    midenRpcEndpoint,
-  );
+  return compileTxScript(client, scriptSource, [], midenRpcEndpoint);
 }
 
 export function buildUpdateGuardianTransactionRequest(
@@ -60,25 +59,16 @@ export async function buildUpdateGuardianTransactionRequest(
   const signatureScheme = options.signatureScheme ?? 'falcon';
   const script = await buildUpdateGuardianScript(
     client,
+    newGuardianPubkey,
     signatureScheme,
     options.midenRpcEndpoint,
   );
 
   const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
-
-  const pubkeyWordForAdvice = WordType.fromHex(normalizeHexWord(newGuardianPubkey));
-  const pubkeyWordForFelts = WordType.fromHex(normalizeHexWord(newGuardianPubkey));
-  const pubkeyWordForScript = WordType.fromHex(normalizeHexWord(newGuardianPubkey));
-
-  const advice = new AdviceMap();
-  advice.insert(pubkeyWordForAdvice, new FeltArray(pubkeyWordForFelts.toFelts()));
-
   const authSaltForBuilder = WordType.fromHex(normalizeHexWord(authSaltHex));
 
   let txBuilder = new TransactionRequestBuilder();
   txBuilder = txBuilder.withCustomScript(script);
-  txBuilder = txBuilder.withScriptArg(pubkeyWordForScript);
-  txBuilder = txBuilder.extendAdviceMap(advice);
   txBuilder = txBuilder.withAuthArg(authSaltForBuilder);
 
   if (options.signatureAdviceMap) {

package/src/transaction/updateProcedureThreshold.ts

@@ -10,16 +10,11 @@ import {
   Word,
   Word as WordType,
 } from '@miden-sdk/miden-sdk';
-import {
-  MULTISIG_ECDSA_MASM,
-  MULTISIG_MASM,
-} from '../account/masm/auth.js';
 import { getProcedureRoot, type ProcedureName } from '../procedures.js';
 import { compileTxScript } from '../raw-client.js';
 import { normalizeHexWord } from '../utils/encoding.js';
 import { randomWord } from '../utils/random.js';
 import type { MidenClientSignatureOptions, SignatureOptions } from './options.js';
-import type { SignatureScheme } from '../types.js';
 
 function buildProcedureThresholdFelts(procedure: ProcedureName, threshold: number): Felt[] {
   const procedureRoot = WordType.fromHex(normalizeHexWord(getProcedureRoot(procedure)));
@@ -32,48 +27,39 @@ function buildProcedureThresholdFelts(procedure: ProcedureName, threshold: numbe
   ];
 }
 
-function buildProcedureThresholdAdvice(
-  procedure: ProcedureName,
-  threshold: number,
-): { configHash: Word; payload: FeltArray } {
-  // `Poseidon2.hashElements` consumes (frees) its `FeltArray` by value, so the
-  // advice payload must be a freshly built one — reusing the hashed array
-  // surfaces as "null pointer passed to rust" at the later `advice.insert`.
-  const configHash = Poseidon2.hashElements(
+/**
+ * `set_procedure_threshold` reads its `[proc_threshold, PROC_ROOT]` inputs from the operand stack
+ * (pushed by the script), so no advice-map entry is attached; this hash is returned only for
+ * caller bookkeeping.
+ */
+function buildProcedureThresholdConfigHash(procedure: ProcedureName, threshold: number): Word {
+  return Poseidon2.hashElements(
     new FeltArray(buildProcedureThresholdFelts(procedure, threshold)),
   );
-  const payload = new FeltArray(buildProcedureThresholdFelts(procedure, threshold));
-  return { configHash, payload };
 }
 
 async function buildUpdateProcedureThresholdScript(
   client: MidenClient | WasmWebClient,
   procedure: ProcedureName,
   threshold: number,
-  signatureScheme: SignatureScheme,
   midenRpcEndpoint?: string,
 ): Promise<TransactionScript> {
-  const multisigMasm = signatureScheme === 'ecdsa' ? MULTISIG_ECDSA_MASM : MULTISIG_MASM;
   const procedureRoot = normalizeHexWord(getProcedureRoot(procedure));
 
   const scriptSource = `
-use oz_multisig::multisig
+use miden::standards::auth::multisig
 
-begin
+@transaction_script
+pub proc main
     push.${procedureRoot}
     push.${threshold}
-    call.multisig::update_procedure_threshold
+    call.multisig::set_procedure_threshold
     dropw
     drop
 end
   `;
 
-  return compileTxScript(
-    client,
-    scriptSource,
-    [{ namespace: 'oz_multisig::multisig', code: multisigMasm }],
-    midenRpcEndpoint,
-  );
+  return compileTxScript(client, scriptSource, [], midenRpcEndpoint);
 }
 
 export function buildUpdateProcedureThresholdTransactionRequest(
@@ -94,14 +80,12 @@ export async function buildUpdateProcedureThresholdTransactionRequest(
   threshold: number,
   options: SignatureOptions = {},
 ): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }> {
-  const signatureScheme = options.signatureScheme ?? 'falcon';
-  const { configHash } = buildProcedureThresholdAdvice(procedure, threshold);
+  const configHash = buildProcedureThresholdConfigHash(procedure, threshold);
 
   const script = await buildUpdateProcedureThresholdScript(
     client,
     procedure,
     threshold,
-    signatureScheme,
     options.midenRpcEndpoint,
   );
   const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();

package/src/transaction/updateSigners.ts

@@ -11,66 +11,66 @@ import {
   Word,
   Word as WordType,
 } from '@miden-sdk/miden-sdk';
-import {
-  MULTISIG_ECDSA_MASM,
-  MULTISIG_MASM,
-} from '../account/masm/auth.js';
 import { compileTxScript } from '../raw-client.js';
 import { normalizeHexWord } from '../utils/encoding.js';
 import { randomWord } from '../utils/random.js';
+import { authSchemeId } from '../utils/signature.js';
 import type { MidenClientSignatureOptions, SignatureOptions } from './options.js';
 import type { SignatureScheme } from '../types.js';
 
-function buildMultisigConfigFelts(threshold: number, signerCommitments: string[]): Felt[] {
+function buildMultisigConfigFelts(
+  threshold: number,
+  signerCommitments: string[],
+  signatureScheme: SignatureScheme,
+): Felt[] {
   const numApprovers = signerCommitments.length;
+  const schemeId = authSchemeId(signatureScheme);
   const felts: Felt[] = [
     new Felt(BigInt(threshold)),
     new Felt(BigInt(numApprovers)),
     new Felt(0n),
     new Felt(0n),
   ];
+  // Interleave [PUB_KEY, SCHEME_ID] per approver, in reverse index order.
   for (const commitment of [...signerCommitments].reverse()) {
     const word = WordType.fromHex(normalizeHexWord(commitment));
     felts.push(...word.toFelts());
+    felts.push(new Felt(BigInt(schemeId)), new Felt(0n), new Felt(0n), new Felt(0n));
   }
   return felts;
 }
 
-function buildMultisigConfigAdvice(
+export function buildMultisigConfigAdvice(
   threshold: number,
   signerCommitments: string[],
+  signatureScheme: SignatureScheme,
 ): { configHash: Word; payload: FeltArray } {
-  // `Poseidon2.hashElements` consumes (frees) its `FeltArray` by value, so the
-  // advice payload must be a freshly built one — reusing the hashed array
-  // surfaces as "null pointer passed to rust" at the later `advice.insert`.
+  // `Poseidon2.hashElements` consumes (frees) its `FeltArray` by value, so the advice payload
+  // must be a separately built array — reusing the hashed array surfaces as "null pointer
+  // passed to rust" at the later `advice.insert`.
   const configHash = Poseidon2.hashElements(
-    new FeltArray(buildMultisigConfigFelts(threshold, signerCommitments)),
+    new FeltArray(buildMultisigConfigFelts(threshold, signerCommitments, signatureScheme)),
+  );
+  const payload = new FeltArray(
+    buildMultisigConfigFelts(threshold, signerCommitments, signatureScheme),
   );
-  const payload = new FeltArray(buildMultisigConfigFelts(threshold, signerCommitments));
   return { configHash, payload };
 }
 
 async function buildUpdateSignersScript(
   client: MidenClient | WasmWebClient,
-  signatureScheme: SignatureScheme,
   midenRpcEndpoint?: string,
 ): Promise<TransactionScript> {
-  const multisigMasm = signatureScheme === 'ecdsa' ? MULTISIG_ECDSA_MASM : MULTISIG_MASM;
-
   const scriptSource = `
-use oz_multisig::multisig
+use miden::standards::auth::multisig
 
-begin
+@transaction_script
+pub proc main
     call.multisig::update_signers_and_threshold
 end
   `;
 
-  return compileTxScript(
-    client,
-    scriptSource,
-    [{ namespace: 'oz_multisig::multisig', code: multisigMasm }],
-    midenRpcEndpoint,
-  );
+  return compileTxScript(client, scriptSource, [], midenRpcEndpoint);
 }
 
 export function buildUpdateSignersTransactionRequest(
@@ -92,20 +92,28 @@ export async function buildUpdateSignersTransactionRequest(
   options: SignatureOptions = {},
 ): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }> {
   const signatureScheme = options.signatureScheme ?? 'falcon';
-  const { configHash: configHashForAdvice, payload } = buildMultisigConfigAdvice(threshold, signerCommitments);
+  const { configHash: configHashForAdvice, payload } = buildMultisigConfigAdvice(
+    threshold,
+    signerCommitments,
+    signatureScheme,
+  );
 
-  const { configHash: configHashForScript } = buildMultisigConfigAdvice(threshold, signerCommitments);
+  const { configHash: configHashForScript } = buildMultisigConfigAdvice(
+    threshold,
+    signerCommitments,
+    signatureScheme,
+  );
 
-  const { configHash: configHashForReturn } = buildMultisigConfigAdvice(threshold, signerCommitments);
+  const { configHash: configHashForReturn } = buildMultisigConfigAdvice(
+    threshold,
+    signerCommitments,
+    signatureScheme,
+  );
 
   const advice = new AdviceMap();
   advice.insert(configHashForAdvice, payload);
 
-  const script = await buildUpdateSignersScript(
-    client,
-    signatureScheme,
-    options.midenRpcEndpoint,
-  );
+  const script = await buildUpdateSignersScript(client, options.midenRpcEndpoint);
 
   const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
 

package/src/transaction.ts

@@ -1,13 +1,20 @@
 export {
   buildConsumeNotesTransactionRequest,
 } from './transaction/consumeNotes.js';
-export { executeForSummary } from './transaction/summary.js';
+export {
+  chainAnchorFromBase64,
+  chainAnchorToBase64,
+  executeForSummary,
+  executeForSummaryAt,
+  summarySalt,
+} from './transaction/summary.js';
 export {
   buildP2idNoteFromMetadata,
   buildP2idTransactionRequest,
   parseP2idNoteType,
   p2idNoteTypeToMetadata,
   type P2idTransactionOptions,
+  type P2ideHeightOptions,
 } from './transaction/p2id.js';
 export {
   buildUpdateGuardianTransactionRequest,

package/src/types/proposal.ts

@@ -37,6 +37,14 @@ interface BaseProposalMetadata {
   description: string;
   saltHex?: string;
   requiredSignatures?: number;
+  /**
+   * Base64-serialized Miden `ChainAnchor` pinning the reference block the
+   * proposal's transaction summary was built at. Required to verify or
+   * execute the proposal: since protocol 0.16 the signed summary binds the
+   * reference block commitment, so it only reproduces when re-executed at
+   * that block.
+   */
+  chainAnchor?: string;
 }
 
 export interface UpdateSignersProposalMetadata extends BaseProposalMetadata {
@@ -89,6 +97,31 @@ export function isP2idNoteVisibility(value: string): value is P2idNoteVisibility
   return value === 'public' || value === 'private';
 }
 
+/** Maximum P2IDE block height: heights are `u32` on-chain (`BlockNumber`). */
+export const MAX_P2IDE_BLOCK_HEIGHT = 0xffff_ffff;
+
+/**
+ * Validates a P2IDE reclaim/timelock height (issue #366). Heights are `u32`
+ * block numbers; `0` is rejected because it is the on-chain encoding for "no
+ * constraint", so accepting it would silently build an unconstrained note.
+ * An invalid value throws rather than being dropped, which would rebuild a
+ * note that could never match the signed tx_summary commitment.
+ */
+export function parseP2ideHeight(
+  field: 'reclaimHeight' | 'timelockHeight',
+  value: number | undefined,
+): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Number.isInteger(value) || value < 1 || value > MAX_P2IDE_BLOCK_HEIGHT) {
+    throw new Error(
+      `unsupported ${field} '${value}': expected an integer between 1 and ${MAX_P2IDE_BLOCK_HEIGHT}`,
+    );
+  }
+  return value;
+}
+
 export interface P2IdProposalMetadata extends BaseProposalMetadata {
   proposalType: 'p2id';
   recipientId: string;
@@ -96,14 +129,20 @@ export interface P2IdProposalMetadata extends BaseProposalMetadata {
   amount: string;
   /** Visibility of the created note. Absent on the wire => 'public' (pre-#322 proposals). */
   noteType?: P2idNoteVisibility;
+  /**
+   * Absolute block height at which the sender may reclaim the note (issue
+   * #366). Presence of either height means the proposal creates a P2IDE note
+   * instead of a plain P2ID note; both absent => plain P2ID (pre-#366
+   * proposals).
+   */
+  reclaimHeight?: number;
+  /** Absolute block height before which the note cannot be consumed. */
+  timelockHeight?: number;
 }
 
 export interface CustomProposalMetadata extends BaseProposalMetadata {
   proposalType: 'custom';
-  /** Original server-defined proposal label, e.g. "b2agg" (issue #266). Mirrors
-   * Rust `ProposalMetadata.proposal_type`; it is what lets a custom proposal
-   * round-trip back to GUARDIAN/export, so it is required in the domain model.
-   * Any wire-level optionality is resolved in the parser/codec boundary. */
+  /** Original server-defined proposal label, preserved during round trips. */
   rawProposalType: string;
 }
 

package/src/types.ts

@@ -80,7 +80,6 @@ export interface MultisigConfig {
   signerCommitments: string[];
   guardianCommitment: string;
   guardianPublicKey?: string;
-  guardianEnabled?: boolean;
   storageMode?: 'private' | 'public';
   procedureThresholds?: ProcedureThreshold[];
   signatureScheme?: SignatureScheme;

package/src/utils/signature.ts

@@ -1,12 +1,13 @@
 import { AdviceMap, Felt, FeltArray, Poseidon2, Signature, Word } from '@miden-sdk/miden-sdk';
 import * as midenSdk from '@miden-sdk/miden-sdk';
+import { EcdsaFormat } from './ecdsa.js';
 import { hexToBytes, normalizeHexWord } from './encoding.js';
 import type { ProposalSignatureEntry, SignatureScheme } from '../types.js';
 
 export const ECDSA_AUTH_SCHEME_ID = 1;
 export const FALCON_AUTH_SCHEME_ID = 2;
 
-function authSchemeId(scheme: SignatureScheme): number {
+export function authSchemeId(scheme: SignatureScheme): number {
   return scheme === 'ecdsa' ? ECDSA_AUTH_SCHEME_ID : FALCON_AUTH_SCHEME_ID;
 }
 
@@ -21,31 +22,17 @@ export function signatureHexToBytes(
   return withPrefix;
 }
 
-function bytesToPackedU32Felts(bytes: Uint8Array): Felt[] {
-  const felts: Felt[] = [];
-  for (let i = 0; i < bytes.length; i += 4) {
-    let packed = 0;
-    for (let j = 0; j < 4 && i + j < bytes.length; j += 1) {
-      packed |= bytes[i + j] << (j * 8);
-    }
-    felts.push(new Felt(BigInt(packed >>> 0)));
-  }
-  return felts;
-}
-
-function encodeEcdsaSignatureFelts(pubkeyBytes: Uint8Array, sigBytes: Uint8Array): Felt[] {
-  const pkFelts = bytesToPackedU32Felts(pubkeyBytes);
-  const sigFelts = bytesToPackedU32Felts(sigBytes);
-  return [...pkFelts, ...sigFelts];
-  
-}
-
+/**
+ * `toPreparedSignature` is the SDK binding for the Rust
+ * `Signature::to_encoded_signature`, so both Falcon and ECDSA advice payloads
+ * come from upstream rather than being packed here. For ECDSA it emits
+ * `QX[8] || QY[8] || SIG_R[8] || SIG_S[8]` and recovers the public key from the
+ * message, which is why the signature must carry its recovery byte.
+ */
 export function buildSignatureAdviceEntry(
   pubkeyCommitment: Word,
   message: Word,
   signature: Signature,
-  ecdsaPubkeyHex?: string,
-  ecdsaSigHex?: string,
 ): { key: Word; values: Felt[] } {
   const elements = new FeltArray([
     ...pubkeyCommitment.toFelts(),
@@ -53,16 +40,31 @@ export function buildSignatureAdviceEntry(
   ]);
   const key = Poseidon2.hashElements(elements);
 
-  let values: Felt[];
-  if (ecdsaPubkeyHex && ecdsaSigHex) {
-    const pkBytes = hexToBytes(ecdsaPubkeyHex);
-    const sigBytes = hexToBytes(ecdsaSigHex);
-    values = encodeEcdsaSignatureFelts(pkBytes, sigBytes);
-  } else {
-    values = signature.toPreparedSignature(message);
+  return { key, values: signature.toPreparedSignature(message) };
+}
+
+/** Rejects unrecoverable ECDSA signatures before entering WASM. */
+export function assertEcdsaSignatureRecoverable(
+  signatureHex: string,
+  messageHex: string,
+  expectedPublicKeyHex: string,
+): void {
+  let recovered: string;
+  try {
+    recovered = EcdsaFormat.recoverCompressedPublicKeyHex(
+      hexToBytes(messageHex),
+      hexToBytes(signatureHex),
+    );
+  } catch (error) {
+    throw new Error(`ECDSA signature does not recover a public key: ${String(error)}`);
   }
 
-  return { key, values };
+  const expected = EcdsaFormat.compressPublicKey(expectedPublicKeyHex);
+  if (recovered.toLowerCase() !== expected.toLowerCase()) {
+    throw new Error(
+      `ECDSA signature recovers public key ${recovered}, which does not match the expected ${expected}`,
+    );
+  }
 }
 
 export function tryComputeEcdsaCommitmentHex(pubkeyHex: string): string | null {
@@ -87,41 +89,6 @@ export function tryComputeCommitmentHex(
   }
 }
 
-export function verifyEcdsaCommitment(
-  pubkeyHex: string,
-  expectedCommitmentHex: string,
-): { match: boolean; computedHex: string; packedFelts: string[]; error?: string } {
-  try {
-    const bytes = hexToBytes(pubkeyHex);
-    const packedU32Values: number[] = [];
-    for (let i = 0; i < bytes.length; i += 4) {
-      let packed = 0;
-      for (let j = 0; j < 4 && i + j < bytes.length; j += 1) {
-        packed |= bytes[i + j] << (j * 8);
-      }
-      packedU32Values.push(packed >>> 0);
-    }
-
-    const packedFelts = bytesToPackedU32Felts(bytes);
-    const feltArray = new FeltArray(packedFelts);
-    const computed = Poseidon2.hashElements(feltArray);
-    const computedHex = normalizeHexWord(computed.toHex());
-    const expectedNorm = normalizeHexWord(expectedCommitmentHex);
-    return {
-      match: computedHex === expectedNorm,
-      computedHex,
-      packedFelts: packedU32Values.map((value) => value.toString()),
-    };
-  } catch (error) {
-    return {
-      match: false,
-      computedHex: `ERROR: ${error}`,
-      packedFelts: [],
-      error: String(error),
-    };
-  }
-}
-
 export function mergeSignatureAdviceMaps(
   advice: AdviceMap,
   entries: Array<{ key: Word; values: Felt[] }>,

package/src/utils/word.ts

@@ -15,6 +15,23 @@ export function wordElementToBigInt(word: Word, index: number): bigint {
   return index < elements.length ? elements[index] : 0n;
 }
 
+/**
+ * True when every element of the word is zero. The SDK's storage-map reads
+ * return `Word::empty()` for a key with no entry (`StorageMap::get` is
+ * `unwrap_or_default()` in miden-protocol), so readers use this to detect
+ * absent entries.
+ */
+export function isEmptyWord(word: Word): boolean {
+  const elements: BigUint64Array | bigint[] =
+    typeof word.toU64s === 'function' ? word.toU64s() : word.toFelts().map(f => f.asInt());
+  for (const element of elements) {
+    if (element !== 0n) {
+      return false;
+    }
+  }
+  return true;
+}
+
 export function wordToBytes(word: { toFelts: () => Array<{ asInt: () => bigint }> }): Uint8Array {
   const felts = word.toFelts();
   const buf = new Uint8Array(32);