@openzeppelin/miden-multisig-client 0.14.5 → 0.14.8

package/src/multisig/consumeNotesErrors.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import {
+  ConsumeNotesMetadataOversizeError,
+  LegacyConsumeNotesNoteMissingError,
+  NoteBindingMismatchError,
+  UnsupportedMetadataVersionError,
+} from './consumeNotesErrors.js';
+
+describe('consume_notes error taxonomy (issue #229)', () => {
+  it('pins stable codes identical to the Rust SDK', () => {
+    expect(new NoteBindingMismatchError('x').code).toBe('consume_notes_note_binding_mismatch');
+    expect(new UnsupportedMetadataVersionError(99).code).toBe(
+      'consume_notes_unsupported_metadata_version',
+    );
+    expect(new ConsumeNotesMetadataOversizeError(1, 2).code).toBe(
+      'consume_notes_metadata_oversize',
+    );
+    expect(new LegacyConsumeNotesNoteMissingError('0xabc').code).toBe(
+      'consume_notes_legacy_note_missing',
+    );
+  });
+
+  it('preserves structured error fields for programmatic branching', () => {
+    const oversize = new ConsumeNotesMetadataOversizeError(262_144, 300_000);
+    expect(oversize.limit).toBe(262_144);
+    expect(oversize.actual).toBe(300_000);
+
+    const missing = new LegacyConsumeNotesNoteMissingError('0xnoteid');
+    expect(missing.noteId).toBe('0xnoteid');
+
+    const unsupported = new UnsupportedMetadataVersionError(99);
+    expect(unsupported.found).toBe(99);
+    const absent = new UnsupportedMetadataVersionError(undefined);
+    expect(absent.found).toBeUndefined();
+  });
+
+  it('extends Error so instanceof Error and instanceof <subclass> both work', () => {
+    const err = new NoteBindingMismatchError('boom');
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(NoteBindingMismatchError);
+    expect(err.name).toBe('NoteBindingMismatchError');
+  });
+});

package/src/multisig/consumeNotesErrors.ts

@@ -0,0 +1,74 @@
+/**
+ * Stable error identifiers for the `consume_notes` v2 metadata flow
+ * (issue #229). These string codes are pinned identical to the Rust
+ * SDK's `MultisigError::code()` values per spec FR-021 / FR-022, so
+ * cross-SDK tests and operator diagnostics share one taxonomy.
+ */
+export type ConsumeNotesErrorCode =
+  | 'consume_notes_note_binding_mismatch'
+  | 'consume_notes_unsupported_metadata_version'
+  | 'consume_notes_metadata_oversize'
+  | 'consume_notes_legacy_note_missing';
+
+/**
+ * v2 metadata's embedded `notes` array did not match its declared
+ * `noteIds` — either a length mismatch, or an embedded note whose
+ * `note.id()` did not match the corresponding `noteIds[i]`. Spec FR-007.
+ */
+export class NoteBindingMismatchError extends Error {
+  readonly code: ConsumeNotesErrorCode = 'consume_notes_note_binding_mismatch';
+  constructor(message: string) {
+    super(message);
+    this.name = 'NoteBindingMismatchError';
+  }
+}
+
+/**
+ * `metadataVersion` is a value the client does not support — either a
+ * legacy (v1) proposal on a cut-over client, or an unrecognized future
+ * version. Spec FR-009 / FR-019.
+ */
+export class UnsupportedMetadataVersionError extends Error {
+  readonly code: ConsumeNotesErrorCode = 'consume_notes_unsupported_metadata_version';
+  readonly found: number | undefined;
+  constructor(found: number | undefined, message?: string) {
+    super(
+      message ??
+        `unsupported consume_notes metadata version: ${found === undefined ? 'absent' : String(found)}`,
+    );
+    this.name = 'UnsupportedMetadataVersionError';
+    this.found = found;
+  }
+}
+
+/**
+ * Serialized v2 metadata exceeded the per-proposal cap
+ * (`MAX_CONSUME_NOTES_METADATA_BYTES`, 256 KiB). Raised at proposal-
+ * creation time before any signature collection begins. Spec FR-011.
+ */
+export class ConsumeNotesMetadataOversizeError extends Error {
+  readonly code: ConsumeNotesErrorCode = 'consume_notes_metadata_oversize';
+  readonly limit: number;
+  readonly actual: number;
+  constructor(limit: number, actual: number) {
+    super(`consume_notes metadata exceeds size limit: limit=${limit} bytes, actual=${actual} bytes`);
+    this.name = 'ConsumeNotesMetadataOversizeError';
+    this.limit = limit;
+    this.actual = actual;
+  }
+}
+
+/**
+ * v1 (legacy) verification path: the cosigner's local Miden store did
+ * not contain the referenced note. This is the exact failure issue #229
+ * exists to eliminate; on v2 proposals it is not reachable.
+ */
+export class LegacyConsumeNotesNoteMissingError extends Error {
+  readonly code: ConsumeNotesErrorCode = 'consume_notes_legacy_note_missing';
+  readonly noteId: string;
+  constructor(noteId: string) {
+    super(`consume_notes legacy verification: note not found in local store: ${noteId}`);
+    this.name = 'LegacyConsumeNotesNoteMissingError';
+    this.noteId = noteId;
+  }
+}

package/src/multisig.ts

@@ -28,6 +28,7 @@ import {
   AdviceMap,
   Endpoint,
   FeltArray,
+  Note,
   RpcClient,
   Signature,
   TransactionSummary,
@@ -41,6 +42,19 @@ import {
   buildConsumeNotesTransactionRequest,
   buildP2idTransactionRequest,
 } from './transaction.js';
+import { buildConsumeNotesTransactionRequestFromNotes } from './transaction/consumeNotes.js';
+import {
+  CONSUME_NOTES_METADATA_VERSION_V2,
+  MAX_CONSUME_NOTES_METADATA_BYTES,
+} from './types/proposal.js';
+import { LEGACY_CONSUME_NOTES_ENABLED } from './multisig/config.js';
+import {
+  ConsumeNotesMetadataOversizeError,
+  LegacyConsumeNotesNoteMissingError,
+  NoteBindingMismatchError,
+  UnsupportedMetadataVersionError,
+} from './multisig/consumeNotesErrors.js';
+import { noteFromBase64, noteToBase64 } from './utils/encoding.js';
 import {
   base64ToUint8Array,
   uint8ArrayToBase64,
@@ -728,7 +742,19 @@ export class Multisig {
       throw new Error('At least one note ID is required');
     }
 
-    const { request, salt } = await buildConsumeNotesTransactionRequest(webClient, noteIds);
+    // Fetch notes locally (proposer has them per FR-012); embed for v2 verification.
+    const rawClient = await getRawMidenClient(webClient);
+    const fetchedNotes: Note[] = [];
+    for (const noteIdHex of noteIds) {
+      const inputNoteRecord = await rawClient.getInputNote(noteIdHex);
+      if (!inputNoteRecord) {
+        throw new LegacyConsumeNotesNoteMissingError(noteIdHex);
+      }
+      fetchedNotes.push(inputNoteRecord.toNote());
+    }
+    const embeddedNotes = fetchedNotes.map((n) => noteToBase64(n));
+
+    const { request, salt } = buildConsumeNotesTransactionRequestFromNotes(fetchedNotes);
 
     const summary = await executeForSummary(webClient, this._accountId, request);
     const summaryBase64 = uint8ArrayToBase64(summary.serialize());
@@ -737,11 +763,23 @@ export class Multisig {
     const metadata: ProposalMetadata = {
       proposalType: 'consume_notes',
       noteIds,
+      metadataVersion: CONSUME_NOTES_METADATA_VERSION_V2,
+      notes: embeddedNotes,
       saltHex: salt.toHex(),
       requiredSignatures: this.getEffectiveThreshold('consume_notes'),
       description: `Consume ${noteIds.length} note(s)`,
     };
 
+    // FR-011: enforce metadata size cap on the wire-encoded form (what GUARDIAN
+    // actually persists), matching the Rust side which measures
+    // `ProposalMetadataPayload`. Sizing the local in-memory `metadata` would
+    // miss codec divergence.
+    const encoded = ProposalMetadataCodec.toGuardian(metadata);
+    const metadataSize = new TextEncoder().encode(JSON.stringify(encoded)).length;
+    if (metadataSize > MAX_CONSUME_NOTES_METADATA_BYTES) {
+      throw new ConsumeNotesMetadataOversizeError(MAX_CONSUME_NOTES_METADATA_BYTES, metadataSize);
+    }
+
     return this.createProposal(proposalNonce, summaryBase64, metadata);
   }
 
@@ -1319,12 +1357,48 @@ export class Multisig {
         return request;
       }
       case 'consume_notes': {
-        const { request } = await buildConsumeNotesTransactionRequest(
-          webClient,
-          metadata.noteIds,
-          { salt, signatureAdviceMap }
-        );
-        return request;
+        // v1/v2 dispatch for issue #229 / FR-009.
+        const version = metadata.metadataVersion;
+        if (version === CONSUME_NOTES_METADATA_VERSION_V2) {
+          const embedded = metadata.notes ?? [];
+          if (embedded.length !== metadata.noteIds.length) {
+            throw new NoteBindingMismatchError(
+              `consume_notes v2: notes.length=${embedded.length} does not match noteIds.length=${metadata.noteIds.length}`,
+            );
+          }
+          const decoded: Note[] = [];
+          for (let i = 0; i < embedded.length; i++) {
+            const note = noteFromBase64(embedded[i], Note);
+            // Normalize both sides; matches the file's other hex comparisons.
+            const embeddedId = normalizeHexWord(note.id().toString());
+            const declaredId = normalizeHexWord(metadata.noteIds[i]);
+            if (embeddedId !== declaredId) {
+              throw new NoteBindingMismatchError(
+                `consume_notes v2: notes[${i}] id ${embeddedId} != noteIds[${i}] ${declaredId}`,
+              );
+            }
+            decoded.push(note);
+          }
+          const { request } = buildConsumeNotesTransactionRequestFromNotes(decoded, {
+            salt,
+            signatureAdviceMap,
+          });
+          return request;
+        }
+        if (version === undefined || version === 1) {
+          if (!LEGACY_CONSUME_NOTES_ENABLED) {
+            // Preserve explicit `1` vs absent so the error tells the
+            // operator which legacy shape was rejected.
+            throw new UnsupportedMetadataVersionError(version);
+          }
+          const { request } = await buildConsumeNotesTransactionRequest(
+            webClient,
+            metadata.noteIds,
+            { salt, signatureAdviceMap },
+          );
+          return request;
+        }
+        throw new UnsupportedMetadataVersionError(version);
       }
       case 'p2id': {
         const { request } = buildP2idTransactionRequest(

package/src/proposal/metadata.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import type { ProposalMetadata as GuardianProposalMetadata } from '@openzeppelin/guardian-client';
+import { ProposalMetadataCodec } from './metadata.js';
+import type { ConsumeNotesProposalMetadata } from '../types/proposal.js';
+
+describe('ProposalMetadataCodec consume_notes v2 round-trip (issue #229)', () => {
+  it('toGuardian threads metadataVersion and notes to the wire', () => {
+    const md: ConsumeNotesProposalMetadata = {
+      proposalType: 'consume_notes',
+      description: 'consume one note',
+      noteIds: ['0xabc'],
+      metadataVersion: 2,
+      notes: ['YmFzZTY0Tm90ZQ=='],
+    };
+    const wire = ProposalMetadataCodec.toGuardian(md);
+    expect(wire.noteIds).toEqual(['0xabc']);
+    expect(wire.consumeNotesMetadataVersion).toBe(2);
+    expect(wire.consumeNotesNotes).toEqual(['YmFzZTY0Tm90ZQ==']);
+  });
+
+  it('fromGuardian reconstructs the v2 fields', () => {
+    const wire: GuardianProposalMetadata = {
+      proposalType: 'consume_notes',
+      noteIds: ['0xabc'],
+      consumeNotesMetadataVersion: 2,
+      consumeNotesNotes: ['YmFzZTY0Tm90ZQ=='],
+    };
+    const md = ProposalMetadataCodec.fromGuardian(wire) as ConsumeNotesProposalMetadata;
+    expect(md.proposalType).toBe('consume_notes');
+    expect(md.metadataVersion).toBe(2);
+    expect(md.notes).toEqual(['YmFzZTY0Tm90ZQ==']);
+  });
+
+  it('round-trips a v1 (legacy) proposal without spurious v2 fields', () => {
+    const md: ConsumeNotesProposalMetadata = {
+      proposalType: 'consume_notes',
+      description: 'legacy',
+      noteIds: ['0xabc'],
+    };
+    const wire = ProposalMetadataCodec.toGuardian(md);
+    expect(wire.consumeNotesMetadataVersion).toBeUndefined();
+    expect(wire.consumeNotesNotes).toBeUndefined();
+    const back = ProposalMetadataCodec.fromGuardian(wire) as ConsumeNotesProposalMetadata;
+    expect(back.metadataVersion).toBeUndefined();
+    expect(back.notes).toBeUndefined();
+  });
+});

package/src/proposal/metadata.ts

@@ -16,6 +16,8 @@ export class ProposalMetadataCodec {
         return {
           ...base,
           noteIds: metadata.noteIds,
+          consumeNotesMetadataVersion: metadata.metadataVersion,
+          consumeNotesNotes: metadata.notes,
         };
       case 'p2id':
         return {
@@ -82,6 +84,8 @@ export class ProposalMetadataCodec {
           ...base,
           proposalType: 'consume_notes',
           noteIds: guardian.noteIds,
+          metadataVersion: guardian.consumeNotesMetadataVersion as 1 | 2 | undefined,
+          notes: guardian.consumeNotesNotes,
         };
       case 'switch_guardian':
         if (!guardian.newGuardianPubkey || !guardian.newGuardianEndpoint) {

package/src/signers/ecdsa.ts

@@ -3,6 +3,7 @@ import { AccountId, AuthSecretKey, type MidenClient, type Word } from '@miden-sd
 import type { Signer, SignatureScheme } from '../types.js';
 import { bytesToHex, normalizeHexWord } from '../utils/encoding.js';
 import { AuthDigest } from '../utils/digest.js';
+import { lookupAuthDigest } from '../lookupAuth.js';
 
 export class EcdsaSigner implements Signer {
   readonly commitment: string;
@@ -39,6 +40,15 @@ export class EcdsaSigner implements Signer {
     return this.signWord(word);
   }
 
+  /**
+   * Sign a `LookupAuthMessage` digest for the `/state/lookup` endpoint.
+   * Account-less; used directly by `recoverByKey`.
+   */
+  async signLookupMessage(keyCommitmentHex: string, timestampMs: number): Promise<string> {
+    const digest = lookupAuthDigest(timestampMs, keyCommitmentHex);
+    return this.signWord(digest);
+  }
+
   async bindAccountKey(midenClient: MidenClient, accountId: string): Promise<void> {
     const targetAccountId = AccountId.fromHex(accountId);
     const existingAccountId = await midenClient.keystore.getAccountId(this.publicKeyCommitment);

package/src/signers/falcon.ts

@@ -3,6 +3,7 @@ import { AccountId, AuthSecretKey, type MidenClient, type Word } from '@miden-sd
 import type { Signer, SignatureScheme } from '../types.js';
 import { bytesToHex } from '../utils/encoding.js';
 import { AuthDigest } from '../utils/digest.js';
+import { lookupAuthDigest } from '../lookupAuth.js';
 
 export class FalconSigner implements Signer {
   readonly commitment: string;
@@ -40,6 +41,15 @@ export class FalconSigner implements Signer {
     return this.signWord(word);
   }
 
+  /**
+   * Sign a `LookupAuthMessage` digest for the `/state/lookup` endpoint.
+   * Account-less; used directly by `recoverByKey`.
+   */
+  async signLookupMessage(keyCommitmentHex: string, timestampMs: number): Promise<string> {
+    const digest = lookupAuthDigest(timestampMs, keyCommitmentHex);
+    return this.signWord(digest);
+  }
+
   async bindAccountKey(midenClient: MidenClient, accountId: string): Promise<void> {
     const targetAccountId = AccountId.fromHex(accountId);
     const existingAccountId = await midenClient.keystore.getAccountId(this.publicKeyCommitment);

package/src/signers/miden-wallet.test.ts

@@ -153,6 +153,54 @@ describe('MidenWalletSigner', () => {
     });
   });
 
+  describe('signLookupMessage', () => {
+    it('delegates to localAuthSigner when present', async () => {
+      const localSigner: Signer = {
+        commitment: '0xlocal',
+        publicKey: '0xlocalpubkey',
+        scheme: 'ecdsa',
+        signAccountIdWithTimestamp: vi.fn(),
+        signCommitment: vi.fn(),
+        signLookupMessage: vi.fn().mockResolvedValue('0xlocallookupsig'),
+      };
+      const signer = new MidenWalletSigner(mockWallet, '0xcommitment', 'ecdsa', localSigner);
+
+      const result = await signer.signLookupMessage('0x' + 'cc'.repeat(32), 1700000000);
+
+      expect(result).toBe('0xlocallookupsig');
+      expect(localSigner.signLookupMessage).toHaveBeenCalledWith(
+        '0x' + 'cc'.repeat(32),
+        1700000000,
+      );
+      expect(mockWallet.signBytes).not.toHaveBeenCalled();
+    });
+
+    it('uses wallet signing over the LookupAuthMessage digest when no localAuthSigner', async () => {
+      const signer = new MidenWalletSigner(mockWallet, '0xcommitment', 'falcon');
+
+      const result = await signer.signLookupMessage('0x' + 'cc'.repeat(32), 1700000000);
+
+      expect(mockWallet.signBytes).toHaveBeenCalledTimes(1);
+      expect(mockWallet.signBytes).toHaveBeenCalledWith(expect.any(Uint8Array), 'word');
+      expect(result).toMatch(/^0x/);
+    });
+
+    it('falls back to wallet signing when localAuthSigner does not implement signLookupMessage', async () => {
+      const localSigner: Signer = {
+        commitment: '0xlocal',
+        publicKey: '0xlocalpubkey',
+        scheme: 'ecdsa',
+        signAccountIdWithTimestamp: vi.fn(),
+        signCommitment: vi.fn(),
+      };
+      const signer = new MidenWalletSigner(mockWallet, '0xcommitment', 'ecdsa', localSigner);
+
+      await signer.signLookupMessage('0x' + 'cc'.repeat(32), 1700000000);
+
+      expect(mockWallet.signBytes).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe('signature byte stripping', () => {
     it('should strip the first byte from wallet signature response', async () => {
       (mockWallet.signBytes as ReturnType<typeof vi.fn>).mockResolvedValue(

package/src/signers/miden-wallet.ts

@@ -2,6 +2,7 @@ import type { RequestAuthPayload } from '@openzeppelin/guardian-client';
 import type { Signer, SignatureScheme } from '../types.js';
 import { AuthDigest } from '../utils/digest.js';
 import { bytesToHex } from '../utils/encoding.js';
+import { lookupAuthDigest } from '../lookupAuth.js';
 import { wordToBytes } from '../utils/word.js';
 
 export interface WalletSigningContext {
@@ -57,6 +58,18 @@ export class MidenWalletSigner implements Signer {
     return this.signWord(word);
   }
 
+  /**
+   * Sign a `LookupAuthMessage` digest for the `/state/lookup` endpoint.
+   * Account-less; used directly by `recoverByKey`.
+   */
+  async signLookupMessage(keyCommitmentHex: string, timestampMs: number): Promise<string> {
+    if (this.localAuthSigner?.signLookupMessage) {
+      return this.localAuthSigner.signLookupMessage(keyCommitmentHex, timestampMs);
+    }
+    const digest = lookupAuthDigest(timestampMs, keyCommitmentHex);
+    return this.signWord(digest);
+  }
+
   private async signWord(word: { toFelts: () => Array<{ asInt: () => bigint }> }): Promise<string> {
     const bytes = wordToBytes(word);
     const signatureBytes = await this.wallet.signBytes(bytes, 'word');

package/src/signers/para.test.ts

@@ -148,6 +148,32 @@ describe('ParaSigner', () => {
     });
   });
 
+  describe('signLookupMessage', () => {
+    it('hashes the LookupAuthMessage digest word bytes before signing', async () => {
+      const signer = new ParaSigner(mockPara, 'wallet-1', '0xcommitment', validCompressedKey);
+      await signer.signLookupMessage('0x' + 'cc'.repeat(32), 1700000000);
+
+      const expectedDigestBytes = keccak_256(
+        wordToBytes({
+          toFelts: () => [
+            { asInt: () => 10n },
+            { asInt: () => 20n },
+            { asInt: () => 30n },
+            { asInt: () => 40n },
+          ],
+        }),
+      );
+      const expectedBase64 = uint8ArrayToBase64(expectedDigestBytes);
+
+      expect(mockPara.signMessage).toHaveBeenCalledWith(
+        expect.objectContaining({
+          walletId: 'wallet-1',
+          messageBase64: expectedBase64,
+        }),
+      );
+    });
+  });
+
   describe('signing denial', () => {
     it('should throw when para returns no signature', async () => {
       (mockPara.signMessage as ReturnType<typeof vi.fn>).mockResolvedValue({ signature: undefined });

package/src/signers/para.ts

@@ -3,6 +3,7 @@ import type { Signer, SignatureScheme } from '../types.js';
 import { AuthDigest } from '../utils/digest.js';
 import { EcdsaFormat } from '../utils/ecdsa.js';
 import { hexToBytes, uint8ArrayToBase64 } from '../utils/encoding.js';
+import { lookupAuthDigest } from '../lookupAuth.js';
 import { wordToBytes } from '../utils/word.js';
 
 export interface ParaSigningContext {
@@ -59,6 +60,15 @@ export class ParaSigner implements Signer {
     return this.signWord(word);
   }
 
+  /**
+   * Sign a `LookupAuthMessage` digest for the `/state/lookup` endpoint.
+   * Account-less; used directly by `recoverByKey`.
+   */
+  async signLookupMessage(keyCommitmentHex: string, timestampMs: number): Promise<string> {
+    const digest = lookupAuthDigest(timestampMs, keyCommitmentHex);
+    return this.signWord(digest);
+  }
+
   private async signWord(word: { toHex: () => string; toFelts: () => Array<{ asInt: () => bigint }> }): Promise<string> {
     const messageBase64 = uint8ArrayToBase64(
       hexToBytes(EcdsaFormat.keccakDigestHex(wordToBytes(word))),

package/src/transaction/consumeNotes.ts

@@ -1,5 +1,6 @@
 import type {
   MidenClient,
+  Note,
   TransactionRequest,
   WasmWebClient,
   Word,
@@ -10,34 +11,30 @@ import {
   TransactionRequestBuilder,
   Word as WordType,
 } from '@miden-sdk/miden-sdk';
+import { LegacyConsumeNotesNoteMissingError } from '../multisig/consumeNotesErrors.js';
 import { getRawMidenClient } from '../raw-client.js';
-import { randomWord } from '../utils/random.js';
 import { normalizeHexWord } from '../utils/encoding.js';
+import { randomWord } from '../utils/random.js';
 import type { SignatureOptions } from './options.js';
 
-export async function buildConsumeNotesTransactionRequest(
-  client: MidenClient | WasmWebClient,
-  noteIds: string[],
+/**
+ * Build a consume-notes request from loaded `Note` objects (no local-store
+ * read). v2 verification path for issue #229.
+ */
+export function buildConsumeNotesTransactionRequestFromNotes(
+  notes: Note[],
   options: SignatureOptions = {},
-): Promise<{ request: TransactionRequest; salt: Word }> {
-  if (noteIds.length === 0) {
-    throw new Error('At least one note ID is required');
+): { request: TransactionRequest; salt: Word } {
+  if (notes.length === 0) {
+    throw new Error('At least one note is required');
   }
 
-  const rawClient = await getRawMidenClient(client, options.midenRpcEndpoint);
   const noteAndArgsArray = new NoteAndArgsArray();
-  for (const noteIdHex of noteIds) {
-    const inputNoteRecord = await rawClient.getInputNote(noteIdHex);
-    if (!inputNoteRecord) {
-      throw new Error(`Note not found in local store: ${noteIdHex}`);
-    }
-    const note = inputNoteRecord.toNote();
-    const noteAndArgs = new NoteAndArgs(note, null);
-    noteAndArgsArray.push(noteAndArgs);
+  for (const note of notes) {
+    noteAndArgsArray.push(new NoteAndArgs(note, null));
   }
 
   const authSaltHex = options.salt ? options.salt.toHex() : randomWord().toHex();
-
   const authSaltForBuilder = WordType.fromHex(normalizeHexWord(authSaltHex));
 
   let txBuilder = new TransactionRequestBuilder();
@@ -55,3 +52,29 @@ export async function buildConsumeNotesTransactionRequest(
     salt: authSaltForReturn,
   };
 }
+
+/**
+ * Legacy/creation adapter: fetches notes from the local store and delegates
+ * to the from-notes variant. v2 verification MUST NOT call this.
+ */
+export async function buildConsumeNotesTransactionRequest(
+  client: MidenClient | WasmWebClient,
+  noteIds: string[],
+  options: SignatureOptions = {},
+): Promise<{ request: TransactionRequest; salt: Word }> {
+  if (noteIds.length === 0) {
+    throw new Error('At least one note ID is required');
+  }
+
+  const rawClient = await getRawMidenClient(client, options.midenRpcEndpoint);
+  const notes: Note[] = [];
+  for (const noteIdHex of noteIds) {
+    const inputNoteRecord = await rawClient.getInputNote(noteIdHex);
+    if (!inputNoteRecord) {
+      throw new LegacyConsumeNotesNoteMissingError(noteIdHex);
+    }
+    notes.push(inputNoteRecord.toNote());
+  }
+
+  return buildConsumeNotesTransactionRequestFromNotes(notes, options);
+}

package/src/types/proposal.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import {
+  CONSUME_NOTES_METADATA_VERSION_V2,
+  type ConsumeNotesProposalMetadata,
+  MAX_CONSUME_NOTES_METADATA_BYTES,
+  isConsumeNotesV1,
+  isConsumeNotesV2,
+} from './proposal.js';
+
+describe('consume_notes metadata v1/v2 discriminator (issue #229)', () => {
+  it('v1 metadata omits metadataVersion and notes on the wire', () => {
+    const md: ConsumeNotesProposalMetadata = {
+      proposalType: 'consume_notes',
+      description: '',
+      noteIds: ['0xabc', '0xdef'],
+    };
+
+    const json = JSON.parse(JSON.stringify(md));
+    expect(json.metadataVersion).toBeUndefined();
+    expect(json.notes).toBeUndefined();
+    expect(isConsumeNotesV1(md)).toBe(true);
+    expect(isConsumeNotesV2(md)).toBe(false);
+  });
+
+  it('v2 metadata round-trips with discriminator and embedded notes', () => {
+    const md: ConsumeNotesProposalMetadata = {
+      proposalType: 'consume_notes',
+      description: '',
+      noteIds: ['0xabc'],
+      metadataVersion: CONSUME_NOTES_METADATA_VERSION_V2,
+      notes: ['YmFzZTY0Tm90ZQ=='],
+    };
+
+    const json = JSON.stringify(md);
+    const parsed = JSON.parse(json) as ConsumeNotesProposalMetadata;
+    expect(parsed.metadataVersion).toBe(2);
+    expect(parsed.notes).toEqual(['YmFzZTY0Tm90ZQ==']);
+    expect(isConsumeNotesV2(parsed)).toBe(true);
+    expect(isConsumeNotesV1(parsed)).toBe(false);
+  });
+
+  it('explicit metadataVersion === 1 is treated as v1', () => {
+    const md = {
+      proposalType: 'consume_notes',
+      description: '',
+      noteIds: ['0xabc'],
+      metadataVersion: 1 as unknown as 2, // legacy explicit-v1 case
+    } as ConsumeNotesProposalMetadata;
+    expect(isConsumeNotesV1(md)).toBe(true);
+    expect(isConsumeNotesV2(md)).toBe(false);
+  });
+
+  it('unknown future version is neither v1 nor v2; dispatch handles rejection', () => {
+    const md = {
+      proposalType: 'consume_notes',
+      description: '',
+      noteIds: ['0xabc'],
+      metadataVersion: 99 as unknown as 2,
+    } as ConsumeNotesProposalMetadata;
+    expect(isConsumeNotesV1(md)).toBe(false);
+    expect(isConsumeNotesV2(md)).toBe(false);
+  });
+
+  it('pins MAX_CONSUME_NOTES_METADATA_BYTES at 256 KiB', () => {
+    expect(MAX_CONSUME_NOTES_METADATA_BYTES).toBe(256 * 1024);
+    expect(MAX_CONSUME_NOTES_METADATA_BYTES).toBe(262_144);
+  });
+});