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

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);
 }

package/src/transaction/summary.ts

@@ -6,22 +6,48 @@ import type {
 } 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';
+import { base64ToUint8Array, normalizeHexWord, uint8ArrayToBase64 } from '../utils/encoding.js';
 
 /**
- * Index of the first user param carrying the auth args. 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`.
+ * Layout of the six user params a multisig auth component binds into the
+ * transaction summary since protocol 0.17: the approval expiration block (or
+ * zero for an approval that never expires), a zero, then the four salt felts.
  */
-const AUTH_ARG_USER_PARAM_OFFSET = 3;
+const APPROVAL_EXPIRATION_USER_PARAM_INDEX = 0;
+const SALT_USER_PARAM_OFFSET = 2;
+
+/**
+ * The summary binds the block the request's auth args name, and the anchor
+ * the store's sync height at capture. A sync landing between the build and the
+ * capture leaves them one block apart, and every cosigner's anchor check would
+ * then fail on a proposal nothing else is wrong with. Caught here, before the
+ * proposal is pushed, so the proposer rebuilds instead.
+ */
+export class SummaryAnchorMismatchError extends Error {
+  readonly retryable = true;
+
+  constructor(details: { anchorCommitmentHex: string; summaryBlockCommitmentHex: string }) {
+    super(
+      `the transaction summary binds block commitment ${details.summaryBlockCommitmentHex} but ` +
+        `the captured chain anchor is ${details.anchorCommitmentHex}; a sync landed between ` +
+        'building the request and capturing its anchor, so rebuild the request and retry',
+    );
+    this.name = 'SummaryAnchorMismatchError';
+  }
+}
 
 /**
  * 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.
+ * the summary with {@link executeForSummaryAt} regardless of their own sync
+ * height.
+ *
+ * The request's auth args bind the block its summary commits to, and this
+ * package pins that block to the anchor: a proposer builds at the sync height
+ * the anchor is captured at, and a rebuild passes the anchor's block number.
+ * The check below is what makes the first half hold.
  */
 export function executeForSummary(
   client: MidenClient,
@@ -44,13 +70,30 @@ export async function executeForSummary(
   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);
+  let summary: TransactionSummary;
+  try {
+    summary = await rawClient.executeForSummaryAt(acc, txRequest, anchor);
+  } catch (error) {
+    anchor.free();
+    throw error;
+  }
+
+  const anchorCommitment = anchor.commitment();
+  const summaryBlockCommitment = summary.blockCommitment();
+  const anchorCommitmentHex = normalizeHexWord(anchorCommitment.toHex());
+  const summaryBlockCommitmentHex = normalizeHexWord(summaryBlockCommitment.toHex());
+  anchorCommitment.free?.();
+  summaryBlockCommitment.free?.();
+  if (anchorCommitmentHex !== summaryBlockCommitmentHex) {
+    anchor.free();
+    throw new SummaryAnchorMismatchError({ anchorCommitmentHex, summaryBlockCommitmentHex });
+  }
   return { summary, anchor };
 }
 
 /**
  * Executes a transaction at the given `ChainAnchor`'s reference block to
- * obtain the summary awaiting authorization — the anchored counterpart of
+ * obtain the summary awaiting authorization: the anchored counterpart of
  * {@link executeForSummary} for cosigners and executors holding a proposal's
  * anchor.
  */
@@ -98,19 +141,40 @@ export function chainAnchorFromBase64(anchorBase64: string): ChainAnchor {
 }
 
 /**
- * Reads the auth args 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 auth
- * args are the tail of `userParams()`.
+ * The block a proposal's `chainAnchor` names, which is the block its summary
+ * binds: a custom producer rebuilds its request at this block. Decodes the
+ * anchor for the one number and frees it.
+ */
+export function chainAnchorBlockNum(anchorBase64: string): number {
+  const anchor = chainAnchorFromBase64(anchorBase64);
+  try {
+    return anchor.blockNum();
+  } finally {
+    anchor.free();
+  }
+}
+
+/**
+ * Reads the salt a multisig transaction summary binds.
  *
- * This is the auth-arg word, *not* the proposal salt. When the request declares
- * a fee conversion salt, miden-client uses it to commit the native conversion
- * info under `hash(CONVERSION_INFO || SALT)`. That commitment is not invertible
- * to the salt. Keep the salt alongside the proposal — `ProposalMetadata.saltHex`
- * — rather than trying to recover it from the summary.
+ * Since protocol 0.17 the multisig auth components bind the salt itself into
+ * the summary's user params rather than a commitment derived from it, so the
+ * value cosigners signed over is readable again. A proposal still carries the
+ * salt in its metadata, because a request has to be rebuilt before any summary
+ * exists; this reader is the cross-check that the two agree.
+ */
+export function summarySalt(summary: TransactionSummary): Word {
+  return Word.newFromFelts(
+    summary.userParams().slice(SALT_USER_PARAM_OFFSET, SALT_USER_PARAM_OFFSET + 4),
+  );
+}
+
+/**
+ * Reads the block at which the approvers' signatures stop authorizing the
+ * transaction, or `undefined` for an approval that never expires, which is
+ * what this package's builders produce.
  */
-export function summaryAuthArg(summary: TransactionSummary): Word {
-  return Word.newFromFelts(summary.userParams().slice(AUTH_ARG_USER_PARAM_OFFSET));
+export function summaryApprovalExpirationBlockNum(summary: TransactionSummary): number | undefined {
+  const value = summary.userParams()[APPROVAL_EXPIRATION_USER_PARAM_INDEX].asInt();
+  return value === 0n ? undefined : Number(value);
 }

package/src/transaction/updateGuardian.ts

@@ -1,17 +1,15 @@
 import {
   type MidenClient,
   TransactionRequest,
-  TransactionRequestBuilder,
   TransactionScript,
   type WasmWebClient,
   Word,
-  Word as WordType,
 } from '@miden-sdk/miden-sdk';
 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 { buildMultisigRequest, multisigRequestBuilder } from './authArgs.js';
+import type { MidenClientMultisigRequestOptions, MultisigRequestOptions } from './options.js';
 import type { SignatureScheme } from '../types.js';
 
 async function buildUpdateGuardianScript(
@@ -44,17 +42,17 @@ end
 export function buildUpdateGuardianTransactionRequest(
   client: MidenClient,
   newGuardianPubkey: string,
-  options: MidenClientSignatureOptions,
+  options: MidenClientMultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word }>;
 export function buildUpdateGuardianTransactionRequest(
   client: WasmWebClient,
   newGuardianPubkey: string,
-  options?: SignatureOptions,
+  options: MultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word }>;
 export async function buildUpdateGuardianTransactionRequest(
   client: MidenClient | WasmWebClient,
   newGuardianPubkey: string,
-  options: SignatureOptions = {},
+  options: MultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word }> {
   const signatureScheme = options.signatureScheme ?? 'falcon';
   const script = await buildUpdateGuardianScript(
@@ -64,24 +62,12 @@ export async function buildUpdateGuardianTransactionRequest(
     options.midenRpcEndpoint,
   );
 
-  const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
-  const authSaltForBuilder = WordType.fromHex(normalizeHexWord(authSaltHex));
-
-  let txBuilder = new TransactionRequestBuilder();
-  txBuilder = txBuilder.withCustomScript(script);
-  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.withCustomScript(script);
 
   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);
 }

package/src/transaction/updateProcedureThreshold.ts

@@ -4,7 +4,6 @@ import {
   type MidenClient,
   Poseidon2,
   TransactionRequest,
-  TransactionRequestBuilder,
   TransactionScript,
   type WasmWebClient,
   Word,
@@ -13,8 +12,8 @@ import {
 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 { buildMultisigRequest, multisigRequestBuilder } from './authArgs.js';
+import type { MidenClientMultisigRequestOptions, MultisigRequestOptions } from './options.js';
 
 function buildProcedureThresholdFelts(procedure: ProcedureName, threshold: number): Felt[] {
   const procedureRoot = WordType.fromHex(normalizeHexWord(getProcedureRoot(procedure)));
@@ -66,19 +65,19 @@ export function buildUpdateProcedureThresholdTransactionRequest(
   client: MidenClient,
   procedure: ProcedureName,
   threshold: number,
-  options: MidenClientSignatureOptions,
+  options: MidenClientMultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }>;
 export function buildUpdateProcedureThresholdTransactionRequest(
   client: WasmWebClient,
   procedure: ProcedureName,
   threshold: number,
-  options?: SignatureOptions,
+  options: MultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }>;
 export async function buildUpdateProcedureThresholdTransactionRequest(
   client: MidenClient | WasmWebClient,
   procedure: ProcedureName,
   threshold: number,
-  options: SignatureOptions = {},
+  options: MultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }> {
   const configHash = buildProcedureThresholdConfigHash(procedure, threshold);
 
@@ -88,23 +87,12 @@ export async function buildUpdateProcedureThresholdTransactionRequest(
     threshold,
     options.midenRpcEndpoint,
   );
-  const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
-  const authSalt = WordType.fromHex(normalizeHexWord(authSaltHex));
-
-  let txBuilder = new TransactionRequestBuilder();
-  txBuilder = txBuilder.withCustomScript(script);
-  txBuilder = txBuilder.withFeeConversionSalt(authSalt);
-  // 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.
-  authSalt.free?.();
+  const { builder, saltHex } = await multisigRequestBuilder(client, options);
+  let txBuilder = builder.withCustomScript(script);
 
   if (options.signatureAdviceMap) {
     txBuilder = txBuilder.extendAdviceMap(options.signatureAdviceMap);
   }
 
-  return {
-    request: txBuilder.build(),
-    salt: WordType.fromHex(normalizeHexWord(authSaltHex)),
-    configHash,
-  };
+  return { ...buildMultisigRequest(txBuilder, saltHex, options.accountId), configHash };
 }

package/src/transaction/updateSigners.ts

@@ -5,7 +5,6 @@ import {
   type MidenClient,
   Poseidon2,
   TransactionRequest,
-  TransactionRequestBuilder,
   TransactionScript,
   type WasmWebClient,
   Word,
@@ -13,9 +12,9 @@ import {
 } from '@miden-sdk/miden-sdk';
 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 { buildMultisigRequest, multisigRequestBuilder } from './authArgs.js';
+import type { MidenClientMultisigRequestOptions, MultisigRequestOptions } from './options.js';
 import type { SignatureScheme } from '../types.js';
 
 function buildMultisigConfigFelts(
@@ -77,19 +76,19 @@ export function buildUpdateSignersTransactionRequest(
   client: MidenClient,
   threshold: number,
   signerCommitments: string[],
-  options: MidenClientSignatureOptions,
+  options: MidenClientMultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }>;
 export function buildUpdateSignersTransactionRequest(
   client: WasmWebClient,
   threshold: number,
   signerCommitments: string[],
-  options?: SignatureOptions,
+  options: MultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }>;
 export async function buildUpdateSignersTransactionRequest(
   client: MidenClient | WasmWebClient,
   threshold: number,
   signerCommitments: string[],
-  options: SignatureOptions = {},
+  options: MultisigRequestOptions,
 ): Promise<{ request: TransactionRequest; salt: Word; configHash: Word }> {
   const signatureScheme = options.signatureScheme ?? 'falcon';
   const { configHash: configHashForAdvice, payload } = buildMultisigConfigAdvice(
@@ -115,28 +114,18 @@ export async function buildUpdateSignersTransactionRequest(
 
   const script = await buildUpdateSignersScript(client, options.midenRpcEndpoint);
 
-  const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
-
-  const authSaltForBuilder = WordType.fromHex(normalizeHexWord(authSaltHex));
-
-  let txBuilder = new TransactionRequestBuilder();
-  txBuilder = txBuilder.withCustomScript(script);
-  txBuilder = txBuilder.withScriptArg(configHashForScript);
-  txBuilder = txBuilder.extendAdviceMap(advice);
-  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
+    .withCustomScript(script)
+    .withScriptArg(configHashForScript)
+    .extendAdviceMap(advice);
 
   if (options.signatureAdviceMap) {
     txBuilder = txBuilder.extendAdviceMap(options.signatureAdviceMap);
   }
 
-  const authSaltForReturn = WordType.fromHex(normalizeHexWord(authSaltHex));
-
   return {
-    request: txBuilder.build(),
-    salt: authSaltForReturn,
+    ...buildMultisigRequest(txBuilder, saltHex, options.accountId),
     configHash: configHashForReturn,
   };
 }