@openzeppelin/miden-multisig-client 0.14.9-rc.0 → 0.15.0-rc.0

package/src/multisig.test.ts

@@ -44,6 +44,9 @@ vi.mock('@miden-sdk/miden-sdk', () => ({
       toPreparedSignature: () => [1, 2, 3],
     }),
   },
+  TransactionRequest: {
+    deserialize: vi.fn().mockReturnValue({}),
+  },
   AdviceMap: vi.fn().mockImplementation(() => ({
     insert: vi.fn(),
   })),
@@ -1297,6 +1300,24 @@ describe('Multisig', () => {
         ok: true,
         json: async () => ({ commitment: newGuardianPubkey }),
       });
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          delta: {
+            account_id: multisig.accountId,
+            nonce: 1,
+            prev_commitment: '0x' + 'b'.repeat(64),
+            delta_payload: { tx_summary: { data: 'AQID' }, signatures: [] },
+            status: {
+              status: 'pending',
+              timestamp: '2024-01-01T00:00:00Z',
+              proposer_id: '0x' + 'c'.repeat(64),
+              cosigner_sigs: [],
+            },
+          },
+          commitment: '0x' + 'c'.repeat(64),
+        }),
+      });
 
       const proposal = await multisig.createSwitchGuardianProposal('http://new-guardian.com', newGuardianPubkey);
 
@@ -1358,6 +1379,24 @@ describe('Multisig', () => {
         ok: true,
         json: async () => ({ commitment: newGuardianCommitment }),
       });
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          delta: {
+            account_id: multisig.accountId,
+            nonce: 1,
+            prev_commitment: '0x' + 'b'.repeat(64),
+            delta_payload: { tx_summary: { data: 'AQID' }, signatures: [] },
+            status: {
+              status: 'pending',
+              timestamp: '2024-01-01T00:00:00Z',
+              proposer_id: '0x' + 'c'.repeat(64),
+              cosigner_sigs: [],
+            },
+          },
+          commitment: '0x' + 'c'.repeat(64),
+        }),
+      });
 
       await multisig.createSwitchGuardianProposal('http://new-guardian.com', newGuardianCommitment);
 
@@ -2191,11 +2230,9 @@ describe('Multisig', () => {
       const newGuardianPubkey = '0x' + '1'.repeat(64);
       const finalRequest = { kind: 'final-switch-guardian-request' };
 
+      // switch_guardian is exempt from binding re-execution, so only the single
+      // final-request build happens here.
       vi.mocked(buildUpdateGuardianTransactionRequest)
-        .mockResolvedValueOnce({
-          request: { kind: 'verify-switch-guardian-request' },
-          salt: { toHex: () => '0x' + 'd'.repeat(64) },
-        } as any)
         .mockResolvedValueOnce({
           request: finalRequest,
           salt: { toHex: () => '0x' + 'd'.repeat(64) },
@@ -2995,6 +3032,91 @@ describe('Multisig', () => {
         ok: true,
         json: async () => ({ commitment: newGuardianPubkey }),
       });
+      // Pre-switch canonicalization push: getDeltaProposal then pushDelta.
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          account_id: multisig.accountId,
+          nonce: 1,
+          prev_commitment: '0x' + 'b'.repeat(64),
+          delta_payload: {
+            tx_summary: { data: 'AQID' },
+            signatures: [],
+            metadata: {
+              proposal_type: 'switch_guardian',
+              new_guardian_pubkey: newGuardianPubkey,
+              new_guardian_endpoint: 'http://new-guardian.com',
+            },
+          },
+          status: {
+            status: 'pending',
+            timestamp: '2024-01-01T00:00:00Z',
+            proposer_id: '0x' + 'a'.repeat(64),
+            cosigner_sigs: [],
+          },
+        }),
+      });
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          account_id: multisig.accountId,
+          nonce: 1,
+          ack_sig: '0x' + '6'.repeat(130),
+          ack_pubkey: '0x' + 'f'.repeat(64),
+          ack_scheme: 'falcon',
+        }),
+      });
+      mockWebClient.getAccount.mockResolvedValueOnce({
+        serialize: () => new Uint8Array([1, 2, 3]),
+      });
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ success: true, message: 'ok', ack_pubkey: '0x' + 'f'.repeat(64) }),
+      });
+      mockWebClient.transactions.submit.mockResolvedValueOnce({});
+
+      await expect(multisig.executeProposal(proposalId)).resolves.toBeUndefined();
+      expect(mockWebClient.transactions.submit).toHaveBeenCalledTimes(1);
+    });
+
+    it('should still switch GUARDIAN when the pre-switch canonicalization push fails', async () => {
+      const config = {
+        threshold: 1,
+        signerCommitments: ['0x' + 'a'.repeat(64)],
+        guardianCommitment: '0x' + 'c'.repeat(64),
+      };
+
+      const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+      const proposalId = '0x' + 'c'.repeat(64);
+      const newGuardianPubkey = '0x' + '1'.repeat(64);
+
+      (multisig as any).proposals.set(proposalId, {
+        id: proposalId,
+        accountId: multisig.accountId,
+        nonce: 1,
+        status: 'ready',
+        txSummary: 'AQID',
+        signatures: [
+          {
+            signerId: '0x' + 'a'.repeat(64),
+            signature: { scheme: 'falcon', signature: '0x' + 'b'.repeat(128) },
+            timestamp: '2024-01-01T00:00:00Z',
+          },
+        ],
+        metadata: {
+          proposalType: 'switch_guardian',
+          newGuardianPubkey,
+          newGuardianEndpoint: 'http://new-guardian.com',
+          description: '',
+        },
+      });
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ commitment: newGuardianPubkey }),
+      });
+      // getDeltaProposal against the old GUARDIAN fails — must be swallowed.
+      mockFetch.mockRejectedValueOnce(new Error('pre-switch GUARDIAN unreachable'));
       mockWebClient.getAccount.mockResolvedValueOnce({
         serialize: () => new Uint8Array([1, 2, 3]),
       });
@@ -3144,6 +3266,142 @@ describe('Multisig', () => {
     });
   });
 
+  describe('prepareCustomExecution', () => {
+    const requestBytes = new Uint8Array([9, 8, 7]);
+
+    function customDelta(
+      proposalType: string,
+      cosignerSigs: any[],
+    ): any {
+      return {
+        account_id: '0x' + 'a'.repeat(30),
+        nonce: 1,
+        prev_commitment: '0x' + 'b'.repeat(64),
+        delta_payload: {
+          tx_summary: { data: 'AQID' },
+          signatures: [],
+          metadata: {
+            proposal_type: proposalType,
+            description: '',
+          },
+        },
+        status: {
+          status: 'pending',
+          timestamp: '2024-01-01T00:00:00Z',
+          proposer_id: '0x' + 'c'.repeat(64),
+          cosigner_sigs: cosignerSigs,
+        },
+      };
+    }
+
+    function falconSig(signerId: string): any {
+      return {
+        signer_id: signerId,
+        signature: { scheme: 'falcon', signature: '0x' + 'e'.repeat(128) },
+        timestamp: '2024-01-01T00:00:00Z',
+      };
+    }
+
+    it('rejects a built-in proposal type', async () => {
+      const config = {
+        threshold: 1,
+        signerCommitments: ['0x' + 'a'.repeat(64)],
+        guardianCommitment: '0x' + 'c'.repeat(64),
+      };
+      const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+
+      const builtinDelta = {
+        ...customDelta('change_threshold', [falconSig('0x' + 'a'.repeat(64))]),
+      };
+      builtinDelta.delta_payload.metadata = {
+        proposal_type: 'change_threshold',
+        description: '',
+        target_threshold: 1,
+        signer_commitments: ['0x' + 'a'.repeat(64)],
+      } as any;
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => builtinDelta,
+      });
+
+      await expect(
+        multisig.prepareCustomExecution('0x' + 'c'.repeat(64), requestBytes),
+      ).rejects.toThrow('prepareCustomExecution is only for custom proposals');
+    });
+
+    it('rejects a proposal that is below its signature threshold', async () => {
+      const config = {
+        threshold: 2,
+        signerCommitments: ['0x' + 'a'.repeat(64), '0x' + 'b'.repeat(64)],
+        guardianCommitment: '0x' + 'c'.repeat(64),
+      };
+      const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => customDelta('b2agg', [falconSig('0x' + 'a'.repeat(64))]),
+      });
+
+      await expect(
+        multisig.prepareCustomExecution('0x' + 'c'.repeat(64), requestBytes),
+      ).rejects.toThrow('have 1 of 2 required signatures');
+    });
+
+    it('rejects when the rebuilt request does not reproduce the signed commitment', async () => {
+      const config = {
+        threshold: 1,
+        signerCommitments: ['0x' + 'a'.repeat(64)],
+        guardianCommitment: '0x' + 'c'.repeat(64),
+      };
+      const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+
+      // Signed commitment comes from TransactionSummary.deserialize -> 'c' * 64.
+      // Make the binding request derive a different commitment so the check fails.
+      vi.mocked(executeForSummary).mockResolvedValueOnce({
+        toCommitment: () => ({
+          toHex: () => '0x' + '9'.repeat(64),
+        }),
+        serialize: () => new Uint8Array([1, 2, 3]),
+      } as any);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => customDelta('b2agg', [falconSig('0x' + 'a'.repeat(64))]),
+      });
+
+      await expect(
+        multisig.prepareCustomExecution('0x' + 'c'.repeat(64), requestBytes),
+      ).rejects.toThrow('Custom proposal binding mismatch');
+    });
+
+    it('fails when GUARDIAN does not return an acknowledgment signature', async () => {
+      const config = {
+        threshold: 1,
+        signerCommitments: ['0x' + 'a'.repeat(64)],
+        guardianCommitment: '0x' + 'c'.repeat(64),
+      };
+      const multisig = new Multisig(mockAccount, config, guardian, mockSigner, mockWebClient);
+
+      const ready = customDelta('b2agg', [falconSig('0x' + 'a'.repeat(64))]);
+
+      // getDeltaProposal
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ready,
+      });
+      // pushDelta returns no ack_sig
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ ...ready, ack_sig: null }),
+      });
+
+      await expect(
+        multisig.prepareCustomExecution('0x' + 'c'.repeat(64), requestBytes),
+      ).rejects.toThrow('GUARDIAN did not return acknowledgment signature');
+    });
+  });
+
   describe('proposal metadata preservation', () => {
     it('should preserve local metadata when syncing proposals', async () => {
       const config = {

package/src/multisig.ts

@@ -739,19 +739,9 @@ export class Multisig {
       description: `Switch GUARDIAN to ${newGuardianEndpoint}`,
     };
 
-    const proposalId = computeCommitmentFromTxSummary(summaryBase64);
-    const proposal: Proposal = {
-      id: proposalId,
-      accountId: this._accountId,
-      nonce: proposalNonce,
-      status: 'pending',
-      txSummary: summaryBase64,
-      signatures: [],
-      metadata,
-    };
-
-    this.proposals.set(proposal.id, proposal);
-    return proposal;
+    // SwitchGuardian is a regular delta proposal; push it to GUARDIAN so
+    // sign/execute (which fetch from GUARDIAN) can find it.
+    return this.createProposal(proposalNonce, summaryBase64, metadata);
   }
 
   /**
@@ -879,7 +869,12 @@ export class Multisig {
       );
 
       if (canConsumeNow) {
-        const noteId = inputNote.id().toString();
+        // Miden 0.15: InputNoteRecord.id() is `NoteId | undefined`; skip id-less records.
+        const id = inputNote.id();
+        if (id === undefined) {
+          continue;
+        }
+        const noteId = id.toString();
         const details = inputNote.details();
         const fungibleAssets = details.assets().fungibleAssets();
 
@@ -976,6 +971,24 @@ export class Multisig {
         throw new Error('Switch GUARDIAN proposal metadata is incomplete after execution');
       }
 
+      // Canonicalize the executed delta on the pre-switch GUARDIAN (clears the
+      // pending proposal). Must run before `this.guardian` is repointed below.
+      // Best-effort: an unreachable old GUARDIAN must not block the switch, so
+      // errors are swallowed (mirrors the Rust execute path).
+      try {
+        const normalizedProposalId = normalizeHexWord(proposal.id);
+        const switchDelta = await this.guardian.getDeltaProposal(
+          this._accountId,
+          normalizedProposalId,
+        );
+        await this.guardian.pushDelta({
+          ...switchDelta,
+          deltaPayload: switchDelta.deltaPayload.txSummary,
+        });
+      } catch {
+        // best-effort; see above
+      }
+
       try {
         const webClient = await this.getRawClient();
         await webClient.syncState();
@@ -1556,6 +1569,17 @@ export class Multisig {
       return txSummaryCommitment;
     }
 
+    if (proposal.metadata.proposalType === 'switch_guardian') {
+      // Exempt from binding re-execution (mirrors the `custom` exemption above).
+      // The WASM `executeForSummary` leaves the guardian-disabling side effect
+      // applied to the in-session account, so re-execution reconstructs a smaller
+      // delta and falsely rejects with "metadata does not match tx_summary". The
+      // native Rust client does not mutate, so this is an intentional divergence.
+      // The id ↔ tx_summary match above plus `verifyGuardianEndpointCommitment`
+      // at propose/execute time still bind the proposal.
+      return txSummaryCommitment;
+    }
+
     const summary = TransactionSummary.deserialize(base64ToUint8Array(proposal.txSummary));
     const salt = proposal.metadata.saltHex
       ? Word.fromHex(normalizeHexWord(proposal.metadata.saltHex))

package/src/procedures.ts

@@ -11,13 +11,13 @@
  * human-readable encoding and should not be copied into this table.
  */
 export const PROCEDURE_ROOTS = {
-  update_signers: '0x3d382ad461f9914c487c6fe908991d088eb54ecbd4aa8560ef79c66c3746bf19',
-  update_procedure_threshold: '0x1f43e9d56ceff5d547ffdcb89896fb38cae0be1b74d9235ed2b4aa525df85f8d',
-  auth_tx: '0x415530d7169f849d7219e810065f9119bba9af2c55070de0bf4f082a1c0aea5c',
-  update_guardian: '0xc8ea876f1837e5cd1d6031becdbd40ce262ecd55930d65400f6890a37149d80c',
-  verify_guardian: '0x9bc6e7b25c8dbaa29d6ad41e354a545dd0a4bac7f3a521bb5195ba101f0213cc',
-  send_asset: '0x6d30df4312a2c44ec842db1bee227cc045396ca91e2c47d756dcb607f2bf5f89',
-  receive_asset: '0x75f638c65584d058542bcf4674b066ae394183021bc9b44dc2fdd97d52f9bcfb',
+  update_signers: '0x34963b067dbba634e57b416bc2f2a9a8d4ac24147f40b2900148c9ba44774274',
+  update_procedure_threshold: '0xec74c4b96ce593c11017ae54dec9c0ae5e0d242e8b3074eb3908d961300aed67',
+  auth_tx: '0x0708020dce7b91b61116e3eb27e5d686e129a83df3c540e0a7693b4523814e72',
+  update_guardian: '0xeceb1f2c2d7d20312dbaf091e9a27a2b63f9fcba120948043069793a5715bc96',
+  verify_guardian: '0xe6a8a62d37117f55a79b5345aa3d263ab16e973d486bac9a1612663dfdecf82d',
+  send_asset: '0xfb1c73d10de1954e9e8948964e3e77cf4e33759d2e012cb00eb10c50f2974eb4',
+  receive_asset: '0x6170fd6d682d91777b551fd866258f43cc657f1291f8f071500f4e56e9c153da',
 } as const;
 
 /**

package/src/raw-client.ts

@@ -24,12 +24,12 @@ function isPublicMidenClient(client: RawClientSource): client is MidenClient {
   return 'accounts' in client && 'sync' in client;
 }
 
-export function getRawMidenClient(
+export async function getRawMidenClient(
   client: RawClientSource,
   rpcUrl?: string,
 ): Promise<WasmWebClient> {
   if (!isPublicMidenClient(client)) {
-    return Promise.resolve(client);
+    return client;
   }
 
   const cached = rawClientCache.get(client);
@@ -41,7 +41,7 @@ export function getRawMidenClient(
     resolveMidenRpcEndpoint(rpcUrl),
     undefined,
     undefined,
-    client.storeIdentifier(),
+    await client.storeIdentifier(),
   );
   rawClientCache.set(client, rawClient);
   return rawClient;
@@ -62,7 +62,7 @@ export async function compileTxScript(
   }
 
   const rawClient = await getRawMidenClient(client, rpcUrl);
-  const builder = rawClient.createCodeBuilder();
+  const builder = await rawClient.createCodeBuilder();
   for (const library of libraries) {
     const builtLibrary = builder.buildLibrary(library.namespace, library.code);
     if (library.linking === 'static') {

package/src/transaction/updateProcedureThreshold.ts

@@ -21,19 +21,28 @@ import { randomWord } from '../utils/random.js';
 import type { SignatureOptions } from './options.js';
 import type { SignatureScheme } from '../types.js';
 
-function buildProcedureThresholdAdvice(
-  procedure: ProcedureName,
-  threshold: number,
-): { configHash: Word; payload: FeltArray } {
+function buildProcedureThresholdFelts(procedure: ProcedureName, threshold: number): Felt[] {
   const procedureRoot = WordType.fromHex(normalizeHexWord(getProcedureRoot(procedure)));
-  const payload = new FeltArray([
+  return [
     ...procedureRoot.toFelts(),
     new Felt(BigInt(threshold)),
     new Felt(0n),
     new Felt(0n),
     new Felt(0n),
-  ]);
-  const configHash = Poseidon2.hashElements(payload);
+  ];
+}
+
+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(
+    new FeltArray(buildProcedureThresholdFelts(procedure, threshold)),
+  );
+  const payload = new FeltArray(buildProcedureThresholdFelts(procedure, threshold));
   return { configHash, payload };
 }
 

package/src/transaction/updateSigners.ts

@@ -21,10 +21,7 @@ import { randomWord } from '../utils/random.js';
 import type { SignatureOptions } from './options.js';
 import type { SignatureScheme } from '../types.js';
 
-function buildMultisigConfigAdvice(
-  threshold: number,
-  signerCommitments: string[],
-): { configHash: Word; payload: FeltArray } {
+function buildMultisigConfigFelts(threshold: number, signerCommitments: string[]): Felt[] {
   const numApprovers = signerCommitments.length;
   const felts: Felt[] = [
     new Felt(BigInt(threshold)),
@@ -36,8 +33,20 @@ function buildMultisigConfigAdvice(
     const word = WordType.fromHex(normalizeHexWord(commitment));
     felts.push(...word.toFelts());
   }
-  const payload = new FeltArray(felts);
-  const configHash = Poseidon2.hashElements(payload);
+  return felts;
+}
+
+function buildMultisigConfigAdvice(
+  threshold: number,
+  signerCommitments: string[],
+): { 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(
+    new FeltArray(buildMultisigConfigFelts(threshold, signerCommitments)),
+  );
+  const payload = new FeltArray(buildMultisigConfigFelts(threshold, signerCommitments));
   return { configHash, payload };
 }
 

package/src/utils/digest.ts

@@ -1,5 +1,6 @@
 import type { RequestAuthPayload } from '@openzeppelin/guardian-client';
 import { AccountId, Felt, FeltArray, Rpo256, Word } from '@miden-sdk/miden-sdk';
+import { feltFromU64Reduced } from './felt.js';
 
 export class AuthDigest {
   static fromAccountIdWithTimestamp(accountId: string, timestamp: number): Word {
@@ -11,7 +12,7 @@ export class AuthDigest {
     const feltArray = new FeltArray([
       prefix,
       suffix,
-      new Felt(BigInt(timestamp)),
+      feltFromU64Reduced(BigInt(timestamp)),
       new Felt(0n),
     ]);
 
@@ -39,7 +40,7 @@ export class AuthDigest {
     const feltArray = new FeltArray([
       prefix,
       suffix,
-      new Felt(BigInt(timestamp)),
+      feltFromU64Reduced(BigInt(timestamp)),
       ...payloadWord.toFelts(),
     ]);
 
@@ -67,7 +68,7 @@ export class AuthDigest {
       for (let j = 0; j < 8 && i + j < bytes.length; j += 1) {
         packed |= BigInt(bytes[i + j]) << (8n * BigInt(j));
       }
-      payloadElements.push(new Felt(packed));
+      payloadElements.push(feltFromU64Reduced(packed));
     }
 
     return Rpo256.hashElements(new FeltArray(payloadElements));

package/src/utils/felt.ts

@@ -0,0 +1,20 @@
+import { Felt } from '@miden-sdk/miden-sdk';
+
+/**
+ * Goldilocks field order (`2^64 - 2^32 + 1`), matching `Felt::ORDER` in
+ * `miden-protocol`.
+ */
+const FELT_ORDER = 18446744069414584321n;
+
+/**
+ * Maps an arbitrary `u64` onto a canonical field element by reducing modulo the
+ * field order, mirroring `guardian_shared::felt::felt_from_u64_reduced`.
+ *
+ * Miden 0.15's `Felt` constructor rejects non-canonical inputs (values
+ * `>= FELT_ORDER`), whereas 0.14 reduced silently. Byte-packed digest inputs are
+ * arbitrary `u64`s, so reducing here preserves the original digest layout, keeps
+ * construction infallible, and stays byte-identical to server-side signing.
+ */
+export function feltFromU64Reduced(value: bigint): Felt {
+  return new Felt(BigInt.asUintN(64, value) % FELT_ORDER);
+}

package/src/utils/index.ts

@@ -1,4 +1,5 @@
 export * from './encoding.js';
+export * from './felt.js';
 export * from './random.js';
 export * from './signature.js';
 export * from './word.js';

package/src/utils/word.ts

@@ -5,8 +5,14 @@ export function wordToHex(word: Word): string {
 }
 
 export function wordElementToBigInt(word: Word, index: number): bigint {
-  const elements = word.toU64s();
-  return index >= 0 && index < elements.length ? elements[index] : 0n;
+  if (index < 0 || index > 3) {
+    return 0n;
+  }
+  // The wallet-embedded 0.15 SDK lacks `toU64s()` on storage-read Words; fall
+  // back to `toFelts()`, which has the same element order.
+  const elements: BigUint64Array | bigint[] =
+    typeof word.toU64s === 'function' ? word.toU64s() : word.toFelts().map(f => f.asInt());
+  return index < elements.length ? elements[index] : 0n;
 }
 
 export function wordToBytes(word: { toFelts: () => Array<{ asInt: () => bigint }> }): Uint8Array {