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

package/src/transaction/consumeNotes.ts

@@ -5,26 +5,31 @@ import type {
   WasmWebClient,
   Word,
 } from '@miden-sdk/miden-sdk';
-import {
-  NoteAndArgs,
-  NoteAndArgsArray,
-  TransactionRequestBuilder,
-  Word as WordType,
-} from '@miden-sdk/miden-sdk';
+import { NoteAndArgs, NoteAndArgsArray } from '@miden-sdk/miden-sdk';
 import { LegacyConsumeNotesNoteMissingError } from '../multisig/consumeNotesErrors.js';
 import { getRawMidenClient } from '../raw-client.js';
-import { normalizeHexWord } from '../utils/encoding.js';
-import { randomWord } from '../utils/random.js';
-import type { MidenClientSignatureOptions, SignatureOptions } from './options.js';
+import { buildMultisigRequest, multisigRequestBuilder } from './authArgs.js';
+import type { MidenClientMultisigRequestOptions, MultisigRequestOptions } from './options.js';
 
 /**
  * Build a consume-notes request from loaded `Note` objects (no local-store
  * read). v2 verification path for issue #229.
  */
 export function buildConsumeNotesTransactionRequestFromNotes(
+  client: MidenClient,
+  notes: Note[],
+  options: MidenClientMultisigRequestOptions,
+): Promise<{ request: TransactionRequest; salt: Word }>;
+export function buildConsumeNotesTransactionRequestFromNotes(
+  client: WasmWebClient,
   notes: Note[],
-  options: SignatureOptions = {},
-): { request: TransactionRequest; salt: Word } {
+  options: MultisigRequestOptions,
+): Promise<{ request: TransactionRequest; salt: Word }>;
+export async function buildConsumeNotesTransactionRequestFromNotes(
+  client: MidenClient | WasmWebClient,
+  notes: Note[],
+  options: MultisigRequestOptions,
+): Promise<{ request: TransactionRequest; salt: Word }> {
   if (notes.length === 0) {
     throw new Error('At least one note is required');
   }
@@ -34,26 +39,14 @@ export function buildConsumeNotesTransactionRequestFromNotes(
     noteAndArgsArray.push(new NoteAndArgs(note, null));
   }
 
-  const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
-  const authSaltForBuilder = WordType.fromHex(normalizeHexWord(authSaltHex));
-
-  let txBuilder = new TransactionRequestBuilder();
-  txBuilder = txBuilder.withInputNotes(noteAndArgsArray);
-  txBuilder = txBuilder.withFeeConversionSalt(authSaltForBuilder);
-  // Borrows rather than consumes: the glue passes `__wbg_ptr` without taking it,
-  // so the handle stays ours to release once the builder has read it.
-  authSaltForBuilder.free?.();
+  const { builder, saltHex } = await multisigRequestBuilder(client, options);
+  let txBuilder = builder.withInputNotes(noteAndArgsArray);
 
   if (options.signatureAdviceMap) {
     txBuilder = txBuilder.extendAdviceMap(options.signatureAdviceMap);
   }
 
-  const authSaltForReturn = WordType.fromHex(normalizeHexWord(authSaltHex));
-
-  return {
-    request: txBuilder.build(),
-    salt: authSaltForReturn,
-  };
+  return buildMultisigRequest(txBuilder, saltHex, options.accountId);
 }
 
 /**
@@ -63,17 +56,17 @@ export function buildConsumeNotesTransactionRequestFromNotes(
 export function buildConsumeNotesTransactionRequest(
   client: MidenClient,
   noteIds: string[],
-  options: MidenClientSignatureOptions,
+  options: MidenClientMultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word }>;
 export function buildConsumeNotesTransactionRequest(
   client: WasmWebClient,
   noteIds: string[],
-  options?: SignatureOptions,
+  options: MultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word }>;
 export async function buildConsumeNotesTransactionRequest(
   client: MidenClient | WasmWebClient,
   noteIds: string[],
-  options: SignatureOptions = {},
+  options: MultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word }> {
   if (noteIds.length === 0) {
     throw new Error('At least one note ID is required');
@@ -89,5 +82,5 @@ export async function buildConsumeNotesTransactionRequest(
     notes.push(inputNoteRecord.toNote());
   }
 
-  return buildConsumeNotesTransactionRequestFromNotes(notes, options);
+  return buildConsumeNotesTransactionRequestFromNotes(rawClient, notes, options);
 }

package/src/transaction/noteAuthentication.ts

@@ -0,0 +1,136 @@
+/**
+ * Canonical consumption mode for `consume_notes` proposals: authenticated.
+ *
+ * miden-client decides per input note, at execution time and from the local
+ * store alone, whether it is consumed as *authenticated* (the store holds
+ * its inclusion proof) or *unauthenticated* (anything else). The two modes
+ * commit differently into the transaction summary,
+ * `hash(nullifier || note_id_or_ZERO)`, so the proposer and every verifier
+ * must be in the same mode or the summary commitment, and with it the
+ * proposal id, differs. That was issue #409's live shape: a cosigner whose
+ * fresh store had never seen the notes failed with "metadata does not match
+ * tx_summary". Proposal creation and every rebuild call
+ * {@link ensureNotesAuthenticated} first, so the executed transaction is the
+ * one the cosigners signed regardless of what each store held before.
+ */
+import { Endpoint, type Note, type NoteInclusionProof, RpcClient } from '@miden-sdk/miden-sdk';
+
+import { ConsumeNoteNotAuthenticatedError } from '../multisig/consumeNotesErrors.js';
+import type { RawClientSource } from '../raw-client.js';
+import { getRawMidenClient } from '../raw-client.js';
+import { importNoteWithProof } from '../recovery/proposalNoteImport.js';
+import { resolveRpcConfig, type RpcConfig } from '../rpc/config.js';
+import { retryRpcRead } from '../rpc/retry.js';
+import { normalizeHexWord } from '../utils/encoding.js';
+
+export interface EnsureNotesAuthenticatedOptions {
+  /** Miden node RPC endpoint the inclusion proofs are fetched from. */
+  midenRpcEndpoint: string;
+  /** Retry policy for the proof fetch; defaults to the SDK's RPC defaults. */
+  rpc?: RpcConfig;
+}
+
+/**
+ * Makes every note in `notes` an authenticated input note in the client's
+ * local store: present, with its on-chain inclusion proof and block header.
+ *
+ * Notes already authenticated locally are left alone. For the rest the
+ * inclusion proofs come from the node in one round trip (the node serves
+ * proofs for private notes too) and each note is imported as committed,
+ * which also upgrades a proof-less record the store already tracked.
+ *
+ * @throws {ConsumeNoteNotAuthenticatedError} when a note is not committed on
+ *   chain yet, the node does not serve its proof, the import fails, or the
+ *   record still lacks authentication after a sync.
+ */
+export async function ensureNotesAuthenticated(
+  midenClient: RawClientSource,
+  notes: readonly Note[],
+  options: EnsureNotesAuthenticatedOptions,
+): Promise<void> {
+  const webClient = await getRawMidenClient(midenClient, options.midenRpcEndpoint);
+  const pending = await unauthenticatedNotes(webClient, notes);
+  if (pending.length === 0) {
+    return;
+  }
+
+  const proofs = new Map<string, NoteInclusionProof>();
+  try {
+    const rpcClient = new RpcClient(new Endpoint(options.midenRpcEndpoint));
+    const fetched = await retryRpcRead(
+      () => rpcClient.getNotesById(pending.map((note) => note.id())),
+      resolveRpcConfig(options.rpc),
+    );
+    for (const entry of fetched) {
+      proofs.set(normalizeHexWord(entry.noteId.toString()), entry.inclusionProof);
+    }
+  } catch (error) {
+    throw new ConsumeNoteNotAuthenticatedError(
+      noteIdHex(pending[0]),
+      `failed to fetch inclusion proofs from the node: ${errorDetail(error)}`,
+    );
+  }
+
+  for (const note of pending) {
+    const idHex = noteIdHex(note);
+    const proof = proofs.get(idHex);
+    if (!proof) {
+      throw new ConsumeNoteNotAuthenticatedError(
+        idHex,
+        'the node has no inclusion proof for it (not committed on chain yet)',
+      );
+    }
+    const { outcome, wasImported } = await importNoteWithProof(
+      webClient,
+      'proposal',
+      idHex,
+      note,
+      proof,
+    );
+    if (!wasImported) {
+      throw new ConsumeNoteNotAuthenticatedError(
+        idHex,
+        `failed to import it with its inclusion proof: ${outcome.reason ?? 'unknown error'}`,
+      );
+    }
+  }
+
+  // The import authenticates a note committed at or below the client's sync
+  // height; a newer one lands unverified until a sync fetches its block
+  // header. A cosigner that just loaded the account is typically behind the
+  // note's block, so sync once and re-check before failing.
+  if ((await unauthenticatedNotes(webClient, notes)).length > 0) {
+    await webClient.syncState();
+  }
+  const still = await unauthenticatedNotes(webClient, notes);
+  if (still.length > 0) {
+    throw new ConsumeNoteNotAuthenticatedError(
+      noteIdHex(still[0]),
+      'its inclusion proof was imported but the local store could not verify it ' +
+        'against the chain even after a sync',
+    );
+  }
+}
+
+/** The subset of `notes` whose local record is missing or carries no proof. */
+async function unauthenticatedNotes(
+  webClient: Awaited<ReturnType<typeof getRawMidenClient>>,
+  notes: readonly Note[],
+): Promise<Note[]> {
+  const pending: Note[] = [];
+  for (const note of notes) {
+    const record = await webClient.getInputNote(noteIdHex(note));
+    if (!record || !record.isAuthenticated()) {
+      pending.push(note);
+    }
+  }
+  return pending;
+}
+
+function noteIdHex(note: Note): string {
+  return normalizeHexWord(note.id().toString());
+}
+
+function errorDetail(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/transaction/options.ts

@@ -6,8 +6,35 @@ export interface SignatureOptions {
   signatureAdviceMap?: AdviceMap;
   signatureScheme?: SignatureScheme;
   midenRpcEndpoint?: string;
+  /**
+   * The block the transaction summary binds. Omitted, the store's sync height,
+   * which is right for the party creating a proposal. A cosigner or executor
+   * rebuilding a proposal pins it to the proposal's anchor block, or the rebuilt
+   * summary can never match the signed one.
+   */
+  boundBlockNum?: number;
+  /**
+   * Blocks after the bound block at which the approvers' signatures stop
+   * authorizing the transaction, so it must be included by then. Bound by the
+   * summary, so a rebuild must pass the same value. At most 65535 blocks, the
+   * furthest a transaction can expire after its reference block; omitted, the
+   * approval never expires, which is the upstream default.
+   */
+  approvalExpirationDelta?: number;
 }
 
 export interface MidenClientSignatureOptions extends SignatureOptions {
   midenRpcEndpoint: string;
 }
+
+/**
+ * Options for a request a multisig account executes. The account decides the
+ * auth args the request has to carry, so every multisig builder needs it.
+ */
+export interface MultisigRequestOptions extends SignatureOptions {
+  accountId: string;
+}
+
+export interface MidenClientMultisigRequestOptions extends MultisigRequestOptions {
+  midenRpcEndpoint: string;
+}

package/src/transaction/p2id.ts

@@ -14,10 +14,10 @@ import {
   NoteTag,
   NoteType,
   Poseidon2,
-  TransactionRequestBuilder,
   Word as WordType,
 } from '@miden-sdk/miden-sdk';
-import { randomWord } from '../utils/random.js';
+import type { RawClientSource } from '../raw-client.js';
+import { buildMultisigRequest, multisigRequestBuilder } from './authArgs.js';
 import { normalizeHexWord } from '../utils/encoding.js';
 import type { SignatureOptions } from './options.js';
 import type { P2idNoteVisibility } from '../types/proposal.js';
@@ -74,6 +74,36 @@ export function deriveP2idSerialNumber(salt: Word): Word {
   ]));
 }
 
+/**
+ * P2ID storage since protocol 0.17 rc.5: target account, then a two-felt salt.
+ * Zero salt is the upstream default. A secret salt hides the target from
+ * guesses against the storage commitment; this builder keeps the note
+ * deterministic in the proposal salt, which already derives the serial number.
+ */
+function p2idStorage(recipient: AccountId): Felt[] {
+  return [recipient.suffix(), recipient.prefix(), new Felt(0n), new Felt(0n)];
+}
+
+/**
+ * P2IDE storage: reclaimer (the sender), target, then reclaim and timelock
+ * heights. Zero encodes an unset height. The script requires all six items.
+ */
+function p2ideStorage(
+  sender: AccountId,
+  recipient: AccountId,
+  reclaimHeight: number,
+  timelockHeight: number,
+): Felt[] {
+  return [
+    sender.suffix(),
+    sender.prefix(),
+    recipient.suffix(),
+    recipient.prefix(),
+    new Felt(BigInt(reclaimHeight)),
+    new Felt(BigInt(timelockHeight)),
+  ];
+}
+
 function buildP2idNote(
   sender: AccountId,
   recipient: AccountId,
@@ -89,19 +119,10 @@ function buildP2idNote(
   const timelockHeight = parseP2ideHeight('timelockHeight', heights.timelockHeight);
   const isP2ide = reclaimHeight !== undefined || timelockHeight !== undefined;
 
-  // P2IDE storage layout (miden-standards `P2ideNoteStorage`): the P2ID
-  // storage plus reclaim/timelock heights as felts, 0 encoding "unset".
   const noteScript = isP2ide ? NoteScript.p2ide() : NoteScript.p2id();
-  const storageFelts = [
-    recipient.suffix(),
-    recipient.prefix(),
-  ];
-  if (isP2ide) {
-    storageFelts.push(
-      new Felt(BigInt(reclaimHeight ?? 0)),
-      new Felt(BigInt(timelockHeight ?? 0)),
-    );
-  }
+  const storageFelts = isP2ide
+    ? p2ideStorage(sender, recipient, reclaimHeight ?? 0, timelockHeight ?? 0)
+    : p2idStorage(recipient);
   const noteStorage = new NoteStorage(new FeltArray(storageFelts));
 
   const noteRecipient = new NoteRecipient(serialNum, noteScript, noteStorage);
@@ -141,14 +162,18 @@ export function buildP2idNoteFromMetadata(
   return buildP2idNote(sender, recipient, noteAssets, noteType, saltHex, heights);
 }
 
-export function buildP2idTransactionRequest(
+export async function buildP2idTransactionRequest(
+  client: RawClientSource,
   senderId: string,
   recipientId: string,
   faucetId: string,
   amount: bigint,
   options: P2idTransactionOptions = {},
-): { request: TransactionRequest; salt: Word } {
-  const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
+): Promise<{ request: TransactionRequest; salt: Word }> {
+  const { builder, saltHex } = await multisigRequestBuilder(client, {
+    ...options,
+    accountId: senderId,
+  });
 
   const note = buildP2idNoteFromMetadata(
     senderId,
@@ -156,29 +181,15 @@ export function buildP2idTransactionRequest(
     faucetId,
     amount,
     options.noteType ?? NoteType.Public,
-    authSaltHex,
+    saltHex,
     { reclaimHeight: options.reclaimHeight, timelockHeight: options.timelockHeight },
   );
 
-  const outputNotes = new MidenArrays.NoteArray([note]);
-
-  const authSaltForBuilder = WordType.fromHex(normalizeHexWord(authSaltHex));
-
-  let txBuilder = new TransactionRequestBuilder();
-  txBuilder = txBuilder.withOwnOutputNotes(outputNotes);
-  txBuilder = txBuilder.withFeeConversionSalt(authSaltForBuilder);
-  // Borrows rather than consumes: the glue passes `__wbg_ptr` without taking it,
-  // so the handle stays ours to release once the builder has read it.
-  authSaltForBuilder.free?.();
+  let txBuilder = builder.withOwnOutputNotes(new MidenArrays.NoteArray([note]));
 
   if (options.signatureAdviceMap) {
     txBuilder = txBuilder.extendAdviceMap(options.signatureAdviceMap);
   }
 
-  const authSaltForReturn = WordType.fromHex(normalizeHexWord(authSaltHex));
-
-  return {
-    request: txBuilder.build(),
-    salt: authSaltForReturn,
-  };
+  return buildMultisigRequest(txBuilder, saltHex, senderId);
 }