@openzeppelin/miden-multisig-client 0.15.2 → 0.16.1

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,
@@ -19,7 +19,6 @@ import type {
 import type { ProcedureName } from './procedures.js';
 import type {
   MidenClient,
-  TransactionProver,
   WasmWebClient,
 } from '@miden-sdk/miden-sdk';
 import {
@@ -29,6 +28,9 @@ import {
   Endpoint,
   FeltArray,
   Note,
+  NoteExportFormat,
+  NoteFile,
+  NoteType,
   RpcClient,
   Signature,
   TransactionRequest,
@@ -41,7 +43,10 @@ import {
   buildUpdateProcedureThresholdTransactionRequest,
   buildUpdateGuardianTransactionRequest,
   buildConsumeNotesTransactionRequest,
+  buildP2idNoteFromMetadata,
   buildP2idTransactionRequest,
+  parseP2idNoteType,
+  p2idNoteTypeToMetadata,
 } from './transaction.js';
 import { buildConsumeNotesTransactionRequestFromNotes } from './transaction/consumeNotes.js';
 import {
@@ -73,7 +78,16 @@ 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';
+import {
+  resolveProverConfig,
+  type ResolvedProverConfig,
+} from './prover/config.js';
+import { ProverWorkflow } from './prover/workflow.js';
 
 /**
  * Result of fetching account state from GUARDIAN.
@@ -136,9 +150,9 @@ export class Multisig {
   private readonly signer: Signer;
   private readonly midenClient: MidenClient;
   private readonly rawClientPromise: Promise<WasmWebClient>;
-  private readonly transactionProver: TransactionProver | null;
+  private readonly proverWorkflow: ProverWorkflow;
   private readonly _accountId: string;
-  private readonly midenRpcEndpoint?: string;
+  private readonly midenRpcEndpoint: string;
   private proposals: Map<string, Proposal> = new Map();
 
   constructor(
@@ -147,8 +161,9 @@ export class Multisig {
     guardian: GuardianHttpClient,
     signer: Signer,
     midenClient: MidenClient,
-    accountId?: string,
-    midenRpcEndpoint?: string
+    accountId: string | undefined,
+    midenRpcEndpoint: string,
+    proverConfig?: ResolvedProverConfig,
   ) {
     this.account = account;
     this.threshold = config.threshold;
@@ -162,15 +177,15 @@ export class Multisig {
     this.signer = signer;
     this.midenClient = midenClient;
     this._accountId = accountId ?? (account ? accountIdToHex(account) : '');
-    this.midenRpcEndpoint = midenRpcEndpoint;
-    this.rawClientPromise = getRawMidenClient(midenClient, midenRpcEndpoint);
-    this.transactionProver = getTransactionProver(midenClient);
+    this.midenRpcEndpoint = requireMidenRpcEndpoint(midenRpcEndpoint);
+    this.rawClientPromise = getRawMidenClient(midenClient, this.midenRpcEndpoint);
+    this.proverWorkflow = new ProverWorkflow(
+      this.midenClient,
+      proverConfig ?? resolveProverConfig(undefined, getTransactionProver(midenClient)),
+    );
   }
 
   private getMidenRpcEndpoint(): string {
-    if (!this.midenRpcEndpoint) {
-      throw new Error('Missing Miden RPC endpoint in MultisigClient configuration');
-    }
     return this.midenRpcEndpoint;
   }
 
@@ -213,6 +228,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 +314,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 +337,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 +379,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 +417,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 +426,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 +864,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 +901,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)}...`,
     };
 
@@ -894,6 +960,151 @@ export class Multisig {
     return notes;
   }
 
+  /**
+   * Export a note created by this multisig account as serialized note-file
+   * bytes for out-of-band delivery (issue #356).
+   *
+   * A private note publishes only its commitment on chain, so the recipient
+   * can never learn its contents via sync; the sender must hand them the
+   * bytes produced here, which they load with {@link importNoteFromBytes}.
+   *
+   * The note must be an output note of this client (created by a transaction
+   * this client executed). When the note's on-chain inclusion proof is
+   * already known (after a post-commit sync) the full note with proof is
+   * exported; otherwise the note details are exported and the importer's
+   * client tracks the note until it commits on chain.
+   *
+   * @param noteId - ID of the note to export (hex string)
+   * @returns Serialized note file bytes
+   */
+  async exportNoteToBytes(noteId: string): Promise<Uint8Array> {
+    const webClient = await this.getRawClient();
+    const trimmedNoteId = noteId.trim();
+
+    let record;
+    try {
+      record = await webClient.getOutputNote(trimmedNoteId);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `Output note ${trimmedNoteId} not found in the local store; only notes created by this client can be exported: ${detail}`,
+      );
+    }
+    if (!record) {
+      throw new Error(
+        `Output note ${trimmedNoteId} not found in the local store; only notes created by this client can be exported`,
+      );
+    }
+
+    const format = record.inclusionProof()
+      ? NoteExportFormat.Full
+      : NoteExportFormat.Details;
+    const noteFile = await webClient.exportNoteFile(trimmedNoteId, format);
+    return noteFile.serialize();
+  }
+
+  /**
+   * Export a note created by this multisig account as a note file downloaded
+   * by the browser (issue #356). Browser-only convenience over
+   * {@link exportNoteToBytes}; use that method directly in non-DOM
+   * environments.
+   *
+   * @param noteId - ID of the note to export (hex string)
+   * @param filename - Download filename; defaults to `note_<id>.mno`
+   */
+  async exportNoteToFile(noteId: string, filename?: string): Promise<void> {
+    if (typeof document === 'undefined') {
+      throw new Error('exportNoteToFile requires a browser environment; use exportNoteToBytes instead');
+    }
+
+    const trimmedNoteId = noteId.trim();
+    const noteBytes = await this.exportNoteToBytes(trimmedNoteId);
+
+    const blob = new Blob([noteBytes as BlobPart], { type: 'application/octet-stream' });
+    const url = URL.createObjectURL(blob);
+    try {
+      const anchor = document.createElement('a');
+      anchor.href = url;
+      anchor.download = filename ?? `note_${trimmedNoteId}.mno`;
+      anchor.click();
+    } finally {
+      URL.revokeObjectURL(url);
+    }
+  }
+
+  /**
+   * Import a note file received out-of-band (issue #356) so the note can be
+   * consumed by this multisig account.
+   *
+   * Sync the Miden client with the network afterwards so the note's on-chain
+   * commitment is tracked and the note shows up in {@link getConsumableNotes};
+   * it can then be consumed via {@link createConsumeNotesProposal}.
+   *
+   * @param noteBytes - Serialized note file bytes produced by
+   *   {@link exportNoteToBytes}
+   * @returns The note ID when the file carries one, or the note's details
+   *   commitment for a details-only file
+   */
+  async importNoteFromBytes(noteBytes: Uint8Array): Promise<string> {
+    const webClient = await this.getRawClient();
+
+    let noteFile: NoteFile;
+    try {
+      noteFile = NoteFile.deserialize(noteBytes);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(`failed to decode note file: ${detail}`);
+    }
+
+    return webClient.importNoteFile(noteFile);
+  }
+
+  /**
+   * Import a note file received out-of-band (issue #356) from a browser
+   * `File`/`Blob` (e.g. a file-input selection). See
+   * {@link importNoteFromBytes} for the returned identifier semantics.
+   */
+  async importNoteFromFile(file: Blob): Promise<string> {
+    const noteBytes = new Uint8Array(await file.arrayBuffer());
+    return this.importNoteFromBytes(noteBytes);
+  }
+
+  /**
+   * Compute the ID of the note a P2ID proposal will create when executed.
+   *
+   * The P2ID note is rebuilt deterministically from the proposal salt, so the
+   * ID is known ahead of execution. For a private P2ID this is the ID to pass
+   * to {@link exportNoteToBytes} after executing, so the note file can be delivered
+   * to the recipient out-of-band (issue #356).
+   *
+   * Call this before executing the proposal: the asset is derived from the
+   * current vault state, which execution itself changes.
+   */
+  async getP2idNoteId(proposal: Proposal): Promise<string> {
+    const metadata = proposal.metadata;
+    if (
+      metadata.proposalType !== 'p2id' ||
+      !metadata.recipientId ||
+      !metadata.faucetId ||
+      !metadata.amount ||
+      !metadata.saltHex
+    ) {
+      throw new Error('getP2idNoteId requires a P2ID proposal with recipient, faucet, amount, and salt metadata');
+    }
+
+    const account = await this.getStoreAccount();
+    const note = buildP2idNoteFromMetadata(
+      this._accountId,
+      metadata.recipientId,
+      metadata.faucetId,
+      BigInt(metadata.amount),
+      account,
+      parseP2idNoteType(metadata.noteType),
+      metadata.saltHex,
+    );
+    return note.id().toString();
+  }
+
   /**
    * Sign a proposal.
    *
@@ -902,6 +1113,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);
@@ -964,7 +1207,7 @@ export class Multisig {
     const { metadata, finalRequest, proposal } = await this.prepareProposalExecution(proposalId);
 
     const accountId = AccountId.fromHex(this._accountId);
-    await this.midenClient.transactions.submit(accountId, finalRequest);
+    await this.proverWorkflow.submit(accountId, finalRequest);
 
     if (metadata.proposalType === 'switch_guardian') {
       if (!metadata.newGuardianEndpoint || !metadata.newGuardianPubkey) {
@@ -1023,7 +1266,7 @@ export class Multisig {
    * after `prepareCustomExecution` rebuilds its request with the returned advice.
    */
   async submitTransaction(request: TransactionRequest): Promise<void> {
-    await this.midenClient.transactions.submit(AccountId.fromHex(this._accountId), request);
+    await this.proverWorkflow.submit(AccountId.fromHex(this._accountId), request);
   }
 
   /**
@@ -1678,12 +1921,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/factory.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import type { DeltaStatus } from '@openzeppelin/guardian-client';
+import { ProposalFactory } from './factory.js';
+
+describe('ProposalFactory.toStatus', () => {
+  const factory = new ProposalFactory({
+    accountId: '0x' + 'a'.repeat(30),
+    signerCommitments: [],
+    resolveRequiredSignatures: () => 2,
+  });
+  // TS `private` is compile-time only; the mapping is worth pinning
+  // without dragging a full tx summary through `fromDelta`.
+  const toStatus = (status: DeltaStatus) =>
+    (factory as unknown as { toStatus: (s: DeltaStatus, t: string, sigs: unknown[]) => string })
+      .toStatus(status, 'p2id', []);
+
+  it('maps every terminal delta status to finalized (issue #345)', () => {
+    // A retained delta left the active candidate path: no longer
+    // signable, so finalized here — whether it landed is resolved by
+    // background reconciliation via the delta status, not the proposal
+    // list.
+    expect(toStatus({ status: 'canonical', timestamp: 't' })).toBe('finalized');
+    // Cast until the published guardian-client types include `retained`.
+    expect(
+      toStatus({
+        status: 'retained',
+        timestamp: 't',
+        reason: 'retry_exhausted',
+      } as unknown as DeltaStatus),
+    ).toBe('finalized');
+    expect(toStatus({ status: 'discarded', timestamp: 't' })).toBe('finalized');
+  });
+
+  it('maps active statuses to pending/ready', () => {
+    expect(toStatus({ status: 'candidate', timestamp: 't' })).toBe('ready');
+    expect(
+      toStatus({ status: 'pending', timestamp: 't', proposerId: 'p', cosignerSigs: [] }),
+    ).toBe('pending');
+  });
+});

package/src/proposal/factory.ts

@@ -156,7 +156,11 @@ export class ProposalFactory {
     proposalType: ProposalType,
     signatures: ProposalSignatureEntry[],
   ): ProposalStatus {
-    switch (status.status) {
+    // The explicit widening keeps this compiling against published
+    // @openzeppelin/guardian-client types that predate the `retained`
+    // status (issue #345); it becomes redundant — but stays correct —
+    // once the lockfile picks up a release that includes it.
+    switch (status.status as DeltaStatus['status'] | 'retained') {
       case 'pending': {
         const signaturesRequired = this.options.resolveRequiredSignatures(proposalType);
         return signatures.length >= signaturesRequired ? 'ready' : 'pending';
@@ -164,6 +168,12 @@ export class ProposalFactory {
       case 'candidate':
         return 'ready';
       case 'canonical':
+      // A retained delta left the active candidate path (issue #345):
+      // no longer signable or submittable, so it is finalized from the
+      // proposal list's point of view. Whether its transaction landed is
+      // resolved by background reconciliation, surfaced via the delta
+      // status, not here.
+      case 'retained':
       case 'discarded':
         return 'finalized';
     }

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