@openzeppelin/miden-multisig-client 0.15.2 → 0.16.0

package/src/multisig.ts

@@ -5,7 +5,7 @@
  * for proposal management.
  */
 
-import { GuardianHttpClient, type DeltaObject, type ProposalSignature, type Signer, type AuthConfig, type StateObject } from '@openzeppelin/guardian-client';
+import { GuardianHttpClient, type AbandonCandidateResponse, type AbandonStatus, type DeltaObject, type ProposalSignature, type Signer, type AuthConfig, type StateObject } from '@openzeppelin/guardian-client';
 import type {
   ConsumableNote,
   ExportedProposal,
@@ -29,6 +29,7 @@ import {
   Endpoint,
   FeltArray,
   Note,
+  NoteType,
   RpcClient,
   Signature,
   TransactionRequest,
@@ -42,6 +43,8 @@ import {
   buildUpdateGuardianTransactionRequest,
   buildConsumeNotesTransactionRequest,
   buildP2idTransactionRequest,
+  parseP2idNoteType,
+  p2idNoteTypeToMetadata,
 } from './transaction.js';
 import { buildConsumeNotesTransactionRequestFromNotes } from './transaction/consumeNotes.js';
 import {
@@ -73,7 +76,11 @@ import { AccountInspector } from './inspector.js';
 import { ProposalFactory } from './proposal/factory.js';
 import { ProposalMetadataCodec } from './proposal/metadata.js';
 import { ProposalSignatures } from './proposal/signatures.js';
-import { getRawMidenClient, getTransactionProver } from './raw-client.js';
+import {
+  getRawMidenClient,
+  getTransactionProver,
+  requireMidenRpcEndpoint,
+} from './raw-client.js';
 
 /**
  * Result of fetching account state from GUARDIAN.
@@ -138,7 +145,7 @@ export class Multisig {
   private readonly rawClientPromise: Promise<WasmWebClient>;
   private readonly transactionProver: TransactionProver | null;
   private readonly _accountId: string;
-  private readonly midenRpcEndpoint?: string;
+  private readonly midenRpcEndpoint: string;
   private proposals: Map<string, Proposal> = new Map();
 
   constructor(
@@ -147,8 +154,8 @@ export class Multisig {
     guardian: GuardianHttpClient,
     signer: Signer,
     midenClient: MidenClient,
-    accountId?: string,
-    midenRpcEndpoint?: string
+    accountId: string | undefined,
+    midenRpcEndpoint: string
   ) {
     this.account = account;
     this.threshold = config.threshold;
@@ -162,15 +169,12 @@ export class Multisig {
     this.signer = signer;
     this.midenClient = midenClient;
     this._accountId = accountId ?? (account ? accountIdToHex(account) : '');
-    this.midenRpcEndpoint = midenRpcEndpoint;
-    this.rawClientPromise = getRawMidenClient(midenClient, midenRpcEndpoint);
+    this.midenRpcEndpoint = requireMidenRpcEndpoint(midenRpcEndpoint);
     this.transactionProver = getTransactionProver(midenClient);
+    this.rawClientPromise = getRawMidenClient(midenClient, this.midenRpcEndpoint);
   }
 
   private getMidenRpcEndpoint(): string {
-    if (!this.midenRpcEndpoint) {
-      throw new Error('Missing Miden RPC endpoint in MultisigClient configuration');
-    }
     return this.midenRpcEndpoint;
   }
 
@@ -213,6 +217,19 @@ export class Multisig {
     return this.signer.commitment;
   }
 
+  /**
+   * Resolve the account from the web client's store, falling back to the
+   * `account` snapshot when the store has no record.
+   *
+   * Transaction execution reads the store, and other flows (e.g. consume-notes
+   * finalize) update it without refreshing the snapshot, so vault lookups must
+   * source from the store to see the same state execution will.
+   */
+  async getStoreAccount(): Promise<Account> {
+    const webClient = await this.getRawClient();
+    return (await webClient.getAccount(AccountId.fromHex(this._accountId))) ?? this.account;
+  }
+
   /**
    * Maps a proposal type to the procedure that determines its threshold.
    */
@@ -286,7 +303,13 @@ export class Multisig {
    * Sync account state from GUARDIAN into the local Miden client store.
    *
    * If the GUARDIAN commitment differs from the local commitment (or the account
-   * is missing locally), the local store is overwritten with the GUARDIAN state.
+   * is missing locally) and the GUARDIAN state is safe to import, the local store
+   * is overwritten with the GUARDIAN state. When the GUARDIAN is merely *behind*
+   * local — e.g. the pushed execution delta has not been canonicalized yet
+   * (see OpenZeppelin/guardian#316) — the local state is already ahead and
+   * on-chain-verifiable, so it is kept as authoritative. Either way, config is
+   * refreshed from the resulting account so callers reading `Multisig.account`
+   * (e.g. the UI) observe the current state instead of a stale snapshot.
    */
   async syncState(): Promise<AccountState> {
     const state = await this.fetchState();
@@ -303,9 +326,10 @@ export class Multisig {
     if (!localAccount || localCommitment !== guardianCommitment) {
       const accountBytes = base64ToUint8Array(state.stateDataBase64);
       const incomingAccount = Account.deserialize(accountBytes);
-      await this.ensureSafeToOverwriteLocalState(incomingAccount, localAccount);
-      await webClient.newAccount(incomingAccount, true);
-      accountForConfigRefresh = incomingAccount;
+      if (await this.isSafeToOverwriteLocalState(incomingAccount, localAccount)) {
+        await webClient.newAccount(incomingAccount, true);
+        accountForConfigRefresh = incomingAccount;
+      }
     }
 
     this.refreshConfigFromAccount(accountForConfigRefresh);
@@ -344,17 +368,37 @@ export class Multisig {
     };
   }
 
-  private async ensureSafeToOverwriteLocalState(
+  /**
+   * Decide whether GUARDIAN-provided state may overwrite the local store.
+   *
+   * Returns `false` — rather than throwing — when the GUARDIAN state is simply
+   * *behind* local (lower nonce). That happens whenever the execution delta the
+   * client pushed has not been canonicalized by the GUARDIAN's background worker
+   * yet (see OpenZeppelin/guardian#316), or permanently if that candidate was
+   * discarded (#312 / #319). In that case the local account is already ahead and
+   * is independently verifiable against chain (`verifyStateCommitment`), so it is
+   * authoritative and must be kept, not clobbered; the caller keeps local and
+   * refreshes config from it.
+   *
+   * Still throws for genuine divergence: an incoming state at the *same* nonce as
+   * local but a different commitment, or an incoming state whose commitment does
+   * not match the on-chain commitment.
+   */
+  private async isSafeToOverwriteLocalState(
     incomingAccount: Account,
     localAccount?: Account,
-  ): Promise<void> {
+  ): Promise<boolean> {
     if (localAccount) {
       const localNonce = localAccount.nonce().asInt();
       const incomingNonce = incomingAccount.nonce().asInt();
 
-      if (incomingNonce <= localNonce) {
+      if (incomingNonce < localNonce) {
+        return false;
+      }
+
+      if (incomingNonce === localNonce) {
         throw new Error(
-          `Refusing to overwrite local state: incoming nonce ${incomingNonce.toString()} is not greater than local nonce ${localNonce.toString()} for account ${this._accountId}`
+          `Refusing to overwrite local state: incoming nonce ${incomingNonce.toString()} equals local nonce ${localNonce.toString()} but commitments differ for account ${this._accountId}`
         );
       }
     }
@@ -362,7 +406,7 @@ export class Multisig {
     const accountId = AccountId.fromHex(this._accountId);
     const onChainCommitment = await this.getOnChainCommitment(accountId);
     if (!onChainCommitment) {
-      return;
+      return true;
     }
 
     const incomingCommitment = normalizeHexWord(incomingAccount.to_commitment().toHex());
@@ -371,6 +415,8 @@ export class Multisig {
         `Refusing to overwrite local state: incoming commitment does not match on-chain commitment for account ${this._accountId}`
       );
     }
+
+    return true;
   }
 
   private async getOnChainCommitment(accountId: AccountId): Promise<string | null> {
@@ -807,23 +853,30 @@ export class Multisig {
    * @param faucetId - Faucet/token account ID (hex string)
    * @param amount - Amount to send
    * @param nonce - Optional proposal nonce (defaults to Date.now())
+   * @param options - Optional settings; `noteType` selects the created note's
+   *   visibility (defaults to `NoteType.Public`, issue #322)
    */
   async createP2idProposal(
     recipientId: string,
     faucetId: string,
     amount: bigint,
     nonce?: number,
+    options: { noteType?: NoteType } = {},
   ): Promise<Proposal> {
     const webClient = await this.getRawClient();
     if (amount <= 0n) {
       throw new Error('Amount must be greater than 0');
     }
 
+    const account = await this.getStoreAccount();
+
     const { request, salt } = buildP2idTransactionRequest(
       this._accountId,
       recipientId,
       faucetId,
       amount,
+      account,
+      { noteType: options.noteType },
     );
 
     const summary = await executeForSummary(webClient, this._accountId, request);
@@ -837,6 +890,8 @@ export class Multisig {
       recipientId,
       faucetId,
       amount: amount.toString(),
+      // Omitted for public notes so the wire shape matches pre-#322 proposals.
+      noteType: p2idNoteTypeToMetadata(options.noteType),
       description: `Send ${amount} of asset ${faucetId.slice(0, 10)}... to ${recipientId.slice(0, 10)}...`,
     };
 
@@ -902,6 +957,38 @@ export class Multisig {
    *
   * @param proposalId - The proposal commitment/ID (this is also what gets signed)
   */
+  /**
+   * Request abandonment of a pending canonicalization candidate whose
+   * transaction will never land on-chain (issue #319) — e.g. after an
+   * approved transaction died client-side (RPC submit failure, prover
+   * timeout, crash).
+   *
+   * Records an abandon *intent* on GUARDIAN: the account stays locked
+   * until the guardian's canonicalization worker confirms over a short
+   * quarantine (typically well under a minute) that the transaction did
+   * not land, then releases the account. Poll {@link abandonStatus} for
+   * the resolution.
+   *
+   * `nonce` pins the exact candidate to release; it is the nonce the
+   * proposal was pushed with. Retries are idempotent and preserve the
+   * original request timestamp. Refused with `GUARDIAN_CANDIDATE_LANDED`
+   * (409) when the transaction actually landed.
+   */
+  async abandonCandidate(nonce: number): Promise<AbandonCandidateResponse> {
+    return this.guardian.abandonCandidate(this._accountId, nonce);
+  }
+
+  /**
+   * Poll the resolution of an abandon request made with
+   * {@link abandonCandidate}: `'waiting'` while the quarantine runs,
+   * `'landed'` if the transaction landed after all, `'abandoned'` once
+   * the account is released, `'unexpected'` for any state no abandon
+   * flow produces.
+   */
+  async abandonStatus(nonce: number): Promise<AbandonStatus> {
+    return this.guardian.abandonStatus(this._accountId, nonce);
+  }
+
   async signProposal(proposalId: string): Promise<Proposal> {
     const normalizedProposalId = normalizeHexWord(proposalId);
     const existingProposal = await this.getProposalForSigning(proposalId, normalizedProposalId);
@@ -1678,12 +1765,14 @@ export class Multisig {
         throw new UnsupportedMetadataVersionError(version);
       }
       case 'p2id': {
+        const account = await this.getStoreAccount();
         const { request } = buildP2idTransactionRequest(
           this._accountId,
           metadata.recipientId,
           metadata.faucetId,
           BigInt(metadata.amount),
-          { salt, signatureAdviceMap }
+          account,
+          { salt, signatureAdviceMap, noteType: parseP2idNoteType(metadata.noteType) }
         );
         return request;
       }

package/src/proposal/metadata.test.ts

@@ -4,6 +4,7 @@ import { ProposalMetadataCodec } from './metadata.js';
 import type {
   ConsumeNotesProposalMetadata,
   CustomProposalMetadata,
+  P2IdProposalMetadata,
 } from '../types/proposal.js';
 
 describe('ProposalMetadataCodec consume_notes v2 round-trip (issue #229)', () => {
@@ -97,3 +98,62 @@ describe('ProposalMetadataCodec custom proposal types (issue #266)', () => {
     expect(back.targetThreshold).toBe(2);
   });
 });
+
+describe('ProposalMetadataCodec p2id noteType (issue #322)', () => {
+  const baseWire: GuardianProposalMetadata = {
+    proposalType: 'p2id',
+    recipientId: '0xrecipient',
+    faucetId: '0xfaucet',
+    amount: '1000',
+  };
+
+  it('round-trips a private noteType through the codec', () => {
+    const md = ProposalMetadataCodec.fromGuardian({
+      ...baseWire,
+      noteType: 'private',
+    }) as P2IdProposalMetadata;
+    expect(md.noteType).toBe('private');
+
+    const wire = ProposalMetadataCodec.toGuardian(md);
+    expect(wire.noteType).toBe('private');
+  });
+
+  it('leaves noteType absent for legacy proposals (=> public)', () => {
+    const md = ProposalMetadataCodec.fromGuardian(baseWire) as P2IdProposalMetadata;
+    expect(md.noteType).toBeUndefined();
+    expect(ProposalMetadataCodec.toGuardian(md).noteType).toBeUndefined();
+  });
+
+  it('canonicalizes an explicit public noteType to absent on encode', () => {
+    const md = {
+      proposalType: 'p2id',
+      description: '',
+      recipientId: '0xrecipient',
+      faucetId: '0xfaucet',
+      amount: '1000',
+      noteType: 'public',
+    } as P2IdProposalMetadata;
+
+    // toGuardian omits the field so a public note keeps the pre-#322 wire
+    // shape and matches the Rust encoder, even if handed an explicit 'public'.
+    expect(ProposalMetadataCodec.toGuardian(md).noteType).toBeUndefined();
+  });
+
+  it('fromGuardian rejects an unsupported noteType', () => {
+    expect(() =>
+      ProposalMetadataCodec.fromGuardian({ ...baseWire, noteType: 'encrypted' }),
+    ).toThrow(/unsupported noteType/);
+  });
+
+  it('validate rejects an unsupported noteType', () => {
+    const md = {
+      proposalType: 'p2id',
+      description: '',
+      recipientId: '0xrecipient',
+      faucetId: '0xfaucet',
+      amount: '1000',
+      noteType: 'encrypted',
+    } as unknown as P2IdProposalMetadata;
+    expect(() => ProposalMetadataCodec.validate(md)).toThrow(/unsupported noteType/);
+  });
+});

package/src/proposal/metadata.ts

@@ -1,6 +1,7 @@
 import type { ProposalMetadata as GuardianProposalMetadata } from '@openzeppelin/guardian-client';
 import type { ProposalMetadata } from '../types.js';
 import { isProcedureName } from '../procedures.js';
+import { isP2idNoteVisibility } from '../types/proposal.js';
 
 export class ProposalMetadataCodec {
   static toGuardian(metadata: ProposalMetadata): GuardianProposalMetadata {
@@ -25,6 +26,10 @@ export class ProposalMetadataCodec {
           recipientId: metadata.recipientId,
           faucetId: metadata.faucetId,
           amount: metadata.amount,
+          // Canonicalize: emit note_type only when private, so a public note
+          // keeps the pre-#322 wire shape and matches the Rust encoder (which
+          // round-trips through the NoteType enum). Absent => public.
+          noteType: metadata.noteType === 'private' ? 'private' : undefined,
         };
       case 'switch_guardian':
         return {
@@ -70,12 +75,18 @@ export class ProposalMetadataCodec {
         if (!guardian.recipientId || !guardian.faucetId || !guardian.amount) {
           throw new Error('p2id proposal is missing required metadata fields');
         }
+        if (guardian.noteType !== undefined && !isP2idNoteVisibility(guardian.noteType)) {
+          throw new Error(
+            `p2id proposal has unsupported noteType '${guardian.noteType}': expected 'public' or 'private'`,
+          );
+        }
         return {
           ...base,
           proposalType: 'p2id',
           recipientId: guardian.recipientId,
           faucetId: guardian.faucetId,
           amount: guardian.amount,
+          noteType: guardian.noteType,
         };
       case 'consume_notes':
         if (!guardian.noteIds || guardian.noteIds.length === 0) {
@@ -168,6 +179,9 @@ export class ProposalMetadataCodec {
         if (!metadata.recipientId || !metadata.faucetId || !metadata.amount) {
           throw new Error('p2id proposal metadata is incomplete');
         }
+        if (metadata.noteType !== undefined && !isP2idNoteVisibility(metadata.noteType)) {
+          throw new Error(`p2id proposal has unsupported noteType '${metadata.noteType}'`);
+        }
         return metadata;
       case 'custom':
         // Custom proposals are opaque to the SDK; nothing to validate beyond

package/src/raw-client.test.ts

@@ -14,7 +14,7 @@ import {
   compileTxScript,
   getRawMidenClient,
   getTransactionProver,
-  resolveMidenRpcEndpoint,
+  requireConfigValue,
 } from './raw-client.js';
 
 describe('raw-client', () => {
@@ -22,8 +22,46 @@ describe('raw-client', () => {
     mockCreateClient.mockReset();
   });
 
-  it('defaults RPC endpoint resolution to devnet', () => {
-    expect(resolveMidenRpcEndpoint()).toBe('https://rpc.devnet.miden.io');
+  it.each([undefined, null, 42, {}, []])(
+    'rejects non-string configuration value %j consistently',
+    (value) => {
+      expect(() => requireConfigValue('guardianEndpoint', value)).toThrow(
+        'missing required configuration: guardianEndpoint',
+      );
+    },
+  );
+
+  it('trims surrounding whitespace from configuration values', () => {
+    expect(requireConfigValue('guardianEndpoint', '  http://localhost:3000\n')).toBe(
+      'http://localhost:3000',
+    );
+  });
+
+  it('rejects shadow client creation without an RPC endpoint', async () => {
+    const client = {
+      accounts: {},
+      sync: vi.fn(),
+      defaultProver: null,
+      storeIdentifier: vi.fn(() => 'browser-db'),
+    };
+
+    await expect(getRawMidenClient(client as any)).rejects.toThrow(
+      'missing required configuration: midenRpcEndpoint',
+    );
+    await expect(getRawMidenClient(client as any, '   ')).rejects.toThrow(
+      'missing required configuration: midenRpcEndpoint',
+    );
+    expect(mockCreateClient).not.toHaveBeenCalled();
+  });
+
+  it('returns an injected raw web client without needing an endpoint', async () => {
+    const rawClient = {
+      executeTransaction: vi.fn(),
+      proveTransaction: vi.fn(),
+    };
+
+    await expect(getRawMidenClient(rawClient as any)).resolves.toBe(rawClient);
+    expect(mockCreateClient).not.toHaveBeenCalled();
   });
 
   it('returns the default prover from a public MidenClient', () => {

package/src/raw-client.ts

@@ -5,8 +5,6 @@ import {
   WasmWebClient,
 } from '@miden-sdk/miden-sdk';
 
-export const DEFAULT_MIDEN_RPC_URL = 'https://rpc.devnet.miden.io';
-
 export type RawClientSource = MidenClient | WasmWebClient;
 export interface ScriptLibrarySource {
   namespace: string;
@@ -16,8 +14,19 @@ export interface ScriptLibrarySource {
 
 const rawClientCache = new WeakMap<MidenClient, Promise<WasmWebClient>>();
 
-export function resolveMidenRpcEndpoint(endpoint?: string): string {
-  return endpoint ?? DEFAULT_MIDEN_RPC_URL;
+export function requireConfigValue(field: string, value?: unknown): string {
+  if (typeof value !== 'string') {
+    throw new Error(`missing required configuration: ${field}`);
+  }
+  const normalizedValue = value.trim();
+  if (normalizedValue === '') {
+    throw new Error(`missing required configuration: ${field}`);
+  }
+  return normalizedValue;
+}
+
+export function requireMidenRpcEndpoint(endpoint?: string): string {
+  return requireConfigValue('midenRpcEndpoint', endpoint);
 }
 
 function isPublicMidenClient(client: RawClientSource): client is MidenClient {
@@ -37,8 +46,9 @@ export async function getRawMidenClient(
     return cached;
   }
 
+  const endpoint = requireMidenRpcEndpoint(rpcUrl);
   const rawClient = WasmWebClient.createClient(
-    resolveMidenRpcEndpoint(rpcUrl),
+    endpoint,
     undefined,
     undefined,
     await client.storeIdentifier(),

package/src/transaction/consumeNotes.ts

@@ -15,7 +15,7 @@ import { LegacyConsumeNotesNoteMissingError } from '../multisig/consumeNotesErro
 import { getRawMidenClient } from '../raw-client.js';
 import { normalizeHexWord } from '../utils/encoding.js';
 import { randomWord } from '../utils/random.js';
-import type { SignatureOptions } from './options.js';
+import type { MidenClientSignatureOptions, SignatureOptions } from './options.js';
 
 /**
  * Build a consume-notes request from loaded `Note` objects (no local-store
@@ -57,6 +57,16 @@ export function buildConsumeNotesTransactionRequestFromNotes(
  * Legacy/creation adapter: fetches notes from the local store and delegates
  * to the from-notes variant. v2 verification MUST NOT call this.
  */
+export function buildConsumeNotesTransactionRequest(
+  client: MidenClient,
+  noteIds: string[],
+  options: MidenClientSignatureOptions,
+): Promise<{ request: TransactionRequest; salt: Word }>;
+export function buildConsumeNotesTransactionRequest(
+  client: WasmWebClient,
+  noteIds: string[],
+  options?: SignatureOptions,
+): Promise<{ request: TransactionRequest; salt: Word }>;
 export async function buildConsumeNotesTransactionRequest(
   client: MidenClient | WasmWebClient,
   noteIds: string[],

package/src/transaction/options.ts

@@ -7,3 +7,7 @@ export interface SignatureOptions {
   signatureScheme?: SignatureScheme;
   midenRpcEndpoint?: string;
 }
+
+export interface MidenClientSignatureOptions extends SignatureOptions {
+  midenRpcEndpoint: string;
+}