@openzeppelin/miden-multisig-client 0.14.6 → 0.14.8

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

package/src/types/proposal.ts

@@ -49,9 +49,27 @@ export interface UpdateProcedureThresholdProposalMetadata extends BaseProposalMe
   targetThreshold: number;
 }
 
+/** `consume_notes` metadata version. Absence on the wire => v1 (issue #229). */
+export const CONSUME_NOTES_METADATA_VERSION_V2 = 2 as const;
+
+/** Max serialized v2 metadata, enforced at creation (FR-011). */
+export const MAX_CONSUME_NOTES_METADATA_BYTES = 256 * 1024;
+
 export interface ConsumeNotesProposalMetadata extends BaseProposalMetadata {
   proposalType: 'consume_notes';
   noteIds: string[];
+  /** Absent or `1` => v1 (legacy), `2` => v2 (issue #229). */
+  metadataVersion?: 1 | 2;
+  /** v2: base64-encoded `note.serialize()` output, index-aligned with `noteIds`. */
+  notes?: string[];
+}
+
+export function isConsumeNotesV2(md: ConsumeNotesProposalMetadata): boolean {
+  return md.metadataVersion === CONSUME_NOTES_METADATA_VERSION_V2;
+}
+
+export function isConsumeNotesV1(md: ConsumeNotesProposalMetadata): boolean {
+  return md.metadataVersion === undefined || md.metadataVersion === 1;
 }
 
 export interface P2IdProposalMetadata extends BaseProposalMetadata {

package/src/utils/encoding.ts

@@ -40,6 +40,19 @@ export function uint8ArrayToBase64(bytes: Uint8Array): string {
   throw new Error('No base64 encoder available in this environment');
 }
 
+/** Serialize a Miden `Note` to base64 (v2 `consume_notes` metadata, issue #229). */
+export function noteToBase64(note: { serialize(): Uint8Array }): string {
+  return uint8ArrayToBase64(note.serialize());
+}
+
+/** Decode a base64 note. `noteCtor` is `Note` from `@miden-sdk/miden-sdk`. */
+export function noteFromBase64<TNote>(
+  base64: string,
+  noteCtor: { deserialize(bytes: Uint8Array): TNote },
+): TNote {
+  return noteCtor.deserialize(base64ToUint8Array(base64));
+}
+
 export function base64ToUint8Array(base64: string): Uint8Array {
   const binary =
     typeof atob === 'function'