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

package/src/multisig.ts

@@ -13,13 +13,13 @@ import type {
   NoteAsset,
   Proposal,
   ProposalMetadata,
+  ProposalSignatureEntry,
   ProposalType,
 } from './types.js';
 import type { ProcedureName } from './procedures.js';
 import type {
   MidenClient,
   TransactionProver,
-  TransactionRequest,
   WasmWebClient,
 } from '@miden-sdk/miden-sdk';
 import {
@@ -28,8 +28,10 @@ import {
   AdviceMap,
   Endpoint,
   FeltArray,
+  Note,
   RpcClient,
   Signature,
+  TransactionRequest,
   TransactionSummary,
   Word,
 } from '@miden-sdk/miden-sdk';
@@ -41,6 +43,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,
@@ -83,6 +98,32 @@ export interface AccountStateVerificationResult {
 /**
  * Represents a multisig account with GUARDIAN integration.
  */
+const BUILTIN_PROPOSAL_TYPES = new Set<string>([
+  'add_signer',
+  'remove_signer',
+  'change_threshold',
+  'update_procedure_threshold',
+  'switch_guardian',
+  'consume_notes',
+  'p2id',
+  // Reserved: the SDK's internal bucket name for unmodeled types. A producer
+  // must not use it as a custom label, or it would collide with the bucket.
+  'custom',
+]);
+
+/**
+ * Deserialize producer-supplied transaction request bytes, wrapping any failure
+ * in a stable message that mirrors the Rust SDK's `deserialize_transaction_request`.
+ */
+function deserializeTransactionRequest(bytes: Uint8Array): TransactionRequest {
+  try {
+    return TransactionRequest.deserialize(bytes);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`failed to decode transaction request: ${detail}`);
+  }
+}
+
 export class Multisig {
   account: Account;
   threshold: number;
@@ -728,7 +769,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 +790,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);
   }
 
@@ -939,6 +1004,220 @@ export class Multisig {
     proposal.status = 'finalized';
   }
 
+  /**
+   * Submit an integration-built transaction (advice already injected). Mirrors
+   * the Rust `submit_transaction`; used by the custom proposal producer flow
+   * 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);
+  }
+
+  /**
+   * Create a proposal from a producer-built transaction the SDK does not model
+   * (issue #266 producer API). `transactionRequestBytes` is a serialized TransactionRequest;
+   * `proposalType` is a free-form, non-empty label that must not collide with a
+   * built-in type. The integration keeps its own recipe to execute later via
+   * `prepareCustomExecution`.
+   */
+  async createCustomProposal(
+    transactionRequestBytes: Uint8Array,
+    proposalType: string,
+    nonce?: number,
+  ): Promise<Proposal> {
+    const label = proposalType.trim().toLowerCase();
+    if (label.length === 0) {
+      throw new Error('proposalType must not be empty');
+    }
+    if (!/^[a-z0-9_]+$/.test(label)) {
+      throw new Error(
+        `proposalType '${label}' must be lowercase snake_case ([a-z0-9_]): no spaces, hyphens, or other characters`,
+      );
+    }
+    if (BUILTIN_PROPOSAL_TYPES.has(label)) {
+      throw new Error(
+        `'${label}' is a built-in proposal type; use the typed proposal API instead`,
+      );
+    }
+
+    const webClient = await this.getRawClient();
+    const request = deserializeTransactionRequest(transactionRequestBytes);
+    const summary = await executeForSummary(webClient, this._accountId, request);
+    const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+    const proposalNonce = nonce ?? Date.now();
+
+    const metadata: ProposalMetadata = {
+      proposalType: 'custom',
+      description: '',
+      rawProposalType: label,
+      requiredSignatures: this.getEffectiveThreshold('custom'),
+    };
+
+    return this.createProposal(proposalNonce, summaryBase64, metadata);
+  }
+
+  /**
+   * Assemble the validated execution advice (cosigner signatures + GUARDIAN
+   * acknowledgment) for a ready custom proposal, so an integration can rebuild
+   * its transaction with its own recipe and submit (issue #266 producer API).
+   *
+   * `transactionRequestBytes` is the serialized transaction request; it is used only to verify
+   * (binding check) that it reproduces the signed commitment, before the
+   * acknowledgment is requested. Returns the advice the integration folds into
+   * its rebuilt transaction (`builder.extendAdviceMap(advice)`).
+   */
+  async prepareCustomExecution(
+    proposalId: string,
+    transactionRequestBytes: Uint8Array,
+  ): Promise<AdviceMap> {
+    const normalizedProposalId = normalizeHexWord(proposalId);
+    const delta = await this.guardian.getDeltaProposal(this._accountId, normalizedProposalId);
+    const existing = this.getLocalProposal(proposalId);
+    const proposal = this.proposalFactory().fromDelta(
+      delta,
+      normalizedProposalId,
+      existing?.metadata,
+      existing?.signatures ?? [],
+    );
+
+    if (proposal.metadata.proposalType !== 'custom') {
+      throw new Error(
+        'prepareCustomExecution is only for custom proposals; use executeProposal for built-in types',
+      );
+    }
+
+    const effectiveThreshold = this.getEffectiveThreshold('custom');
+    const signaturesForExecution = new ProposalSignatures(
+      proposal.signatures,
+      this.signerCommitments,
+      `Invalid proposal signatures for ${proposalId}`,
+    ).entries();
+    if (signaturesForExecution.length < effectiveThreshold) {
+      throw new Error(
+        `Proposal is not ready for execution: have ${signaturesForExecution.length} of ${effectiveThreshold} required signatures.`,
+      );
+    }
+
+    const txSummary = TransactionSummary.deserialize(
+      base64ToUint8Array(delta.deltaPayload.txSummary.data),
+    );
+    const signedCommitmentHex = normalizeHexWord(txSummary.toCommitment().toHex());
+
+    const bindingRequest = deserializeTransactionRequest(transactionRequestBytes);
+
+    const webClient = await this.getRawClient();
+    const derived = await executeForSummary(webClient, this._accountId, bindingRequest);
+    const derivedCommitmentHex = normalizeHexWord(derived.toCommitment().toHex());
+    if (derivedCommitmentHex !== signedCommitmentHex) {
+      throw new Error(
+        `Custom proposal binding mismatch: expected ${signedCommitmentHex}, got ${derivedCommitmentHex}`,
+      );
+    }
+
+    return this.assembleCustomAdvice(
+      proposalId,
+      signaturesForExecution,
+      signedCommitmentHex,
+      delta,
+    );
+  }
+
+  private async assembleCustomAdvice(
+    proposalId: string,
+    signaturesForExecution: ProposalSignatureEntry[],
+    normalizedTxCommitmentHex: string,
+    delta: DeltaObject,
+  ): Promise<AdviceMap> {
+    const normalizedSignerCommitments = new Set(
+      this.signerCommitments.map((commitment) => normalizeHexWord(commitment)),
+    );
+    const adviceMap = new AdviceMap();
+    const adviceMapKeys = new Set<string>();
+    const createTxCommitmentWord = (): Word => Word.fromHex(normalizedTxCommitmentHex);
+
+    for (const cosignerSig of signaturesForExecution) {
+      let signerCommitmentHex = normalizeHexWord(cosignerSig.signerId);
+      const ecdsaPublicKey =
+        cosignerSig.signature.scheme === 'ecdsa' ? cosignerSig.signature.publicKey : undefined;
+
+      if (cosignerSig.signature.scheme === 'ecdsa') {
+        if (!ecdsaPublicKey) {
+          throw new Error(
+            `ECDSA proposal signature for ${signerCommitmentHex} is missing publicKey`,
+          );
+        }
+        const derivedCommitment = tryComputeEcdsaCommitmentHex(ecdsaPublicKey);
+        if (derivedCommitment && derivedCommitment !== signerCommitmentHex) {
+          if (!normalizedSignerCommitments.has(derivedCommitment)) {
+            throw new Error(
+              `ECDSA public key commitment mismatch: derived commitment ${derivedCommitment} is not in signerCommitments.`,
+            );
+          }
+          signerCommitmentHex = derivedCommitment;
+        }
+      }
+
+      const signerCommitment = Word.fromHex(signerCommitmentHex);
+      const sigBytes = signatureHexToBytes(
+        cosignerSig.signature.signature,
+        cosignerSig.signature.scheme,
+      );
+      const signature = Signature.deserialize(sigBytes);
+      const { key, values } = buildSignatureAdviceEntry(
+        signerCommitment,
+        createTxCommitmentWord(),
+        signature,
+        ecdsaPublicKey,
+        cosignerSig.signature.scheme === 'ecdsa' ? cosignerSig.signature.signature : undefined,
+      );
+      const keyHex = normalizeHexWord(key.toHex());
+      if (adviceMapKeys.has(keyHex)) {
+        throw new Error(`Duplicate advice-map key detected for proposal ${proposalId}`);
+      }
+      adviceMapKeys.add(keyHex);
+      adviceMap.insert(key, new FeltArray(values));
+    }
+
+    const executionDelta = { ...delta, deltaPayload: delta.deltaPayload.txSummary };
+    const pushResult = await this.guardian.pushDelta(executionDelta);
+    const ackSigHex = pushResult.ackSig;
+    if (!ackSigHex) {
+      throw new Error('GUARDIAN did not return acknowledgment signature');
+    }
+
+    const guardianCommitment = Word.fromHex(normalizeHexWord(this.guardianCommitment));
+    const ackScheme = (pushResult.ackScheme as 'ecdsa' | 'falcon') || this.signer.scheme;
+    const ackPubkey = pushResult.ackPubkey || this.guardianPublicKey;
+    if (ackScheme === 'ecdsa' && !ackPubkey) {
+      throw new Error('GUARDIAN acknowledgment is missing ECDSA public key');
+    }
+    if (ackScheme === 'ecdsa' && ackPubkey) {
+      const derivedCommitment = tryComputeEcdsaCommitmentHex(ackPubkey);
+      if (derivedCommitment && derivedCommitment !== normalizeHexWord(this.guardianCommitment)) {
+        throw new Error('GUARDIAN public key commitment mismatch');
+      }
+    }
+    const ackSigBytes = signatureHexToBytes(ackSigHex, ackScheme);
+    const ackSignature = Signature.deserialize(ackSigBytes);
+    const { key: ackKey, values: ackValues } = buildSignatureAdviceEntry(
+      guardianCommitment,
+      createTxCommitmentWord(),
+      ackSignature,
+      ackScheme === 'ecdsa' ? ackPubkey : undefined,
+      ackScheme === 'ecdsa' ? ackSigHex : undefined,
+    );
+    const ackKeyHex = normalizeHexWord(ackKey.toHex());
+    if (adviceMapKeys.has(ackKeyHex)) {
+      throw new Error(
+        `Duplicate advice-map key detected for GUARDIAN acknowledgment in proposal ${proposalId}`,
+      );
+    }
+    adviceMapKeys.add(ackKeyHex);
+    adviceMap.insert(ackKey, new FeltArray(ackValues));
+
+    return adviceMap;
+  }
+
   private getLocalProposal(proposalId: string): Proposal | undefined {
     const normalizedProposalId = normalizeHexWord(proposalId);
     return this.proposals.get(proposalId) ?? this.proposals.get(normalizedProposalId);
@@ -956,6 +1235,15 @@ export class Multisig {
     await this.verifyProposalMetadataBinding(proposal);
 
     const metadata = proposal.metadata;
+    // Reject custom proposals before any advice assembly or GUARDIAN ack push:
+    // the SDK cannot rebuild an opaque custom transaction, and the rejection
+    // must stay side-effect free (mirrors the Rust early guard in execute_proposal).
+    if (metadata.proposalType === 'custom') {
+      throw new Error(
+        'Cannot execute a custom proposal via executeProposal; use prepareCustomExecution to ' +
+          'get the cosigner + GUARDIAN advice, then submitTransaction with your rebuilt request (issue #266).',
+      );
+    }
     const effectiveThreshold = this.getEffectiveThreshold(metadata.proposalType);
     const signatureContext = `Invalid proposal signatures for ${proposalId}`;
     const signaturesForExecution = new ProposalSignatures(
@@ -1261,8 +1549,11 @@ export class Multisig {
 
   private async verifyProposalMetadataBinding(proposal: Proposal): Promise<string> {
     const txSummaryCommitment = this.ensureProposalCommitmentMatchesSummary(proposal);
-    if (proposal.metadata.proposalType === 'unknown') {
-      throw new Error(`Cannot verify proposal metadata for unknown proposal type: ${proposal.id}`);
+    if (proposal.metadata.proposalType === 'custom') {
+      // Custom proposals (issue #266) have no per-type reconstruction recipe;
+      // the id ↔ tx_summary commitment match above is the only available
+      // integrity guarantee for an opaque proposal.
+      return txSummaryCommitment;
     }
 
     const summary = TransactionSummary.deserialize(base64ToUint8Array(proposal.txSummary));
@@ -1319,12 +1610,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(
@@ -1336,8 +1663,10 @@ export class Multisig {
         );
         return request;
       }
-      case 'unknown':
-        throw new Error('Unsupported proposal type: unknown');
+      case 'custom':
+        throw new Error(
+          `Cannot build a transaction for a custom proposal type: ${metadata.rawProposalType ?? 'custom'}`,
+        );
     }
   }
 

package/src/proposal/metadata.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest';
+import type { ProposalMetadata as GuardianProposalMetadata } from '@openzeppelin/guardian-client';
+import { ProposalMetadataCodec } from './metadata.js';
+import type {
+  ConsumeNotesProposalMetadata,
+  CustomProposalMetadata,
+} 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();
+  });
+});
+
+describe('ProposalMetadataCodec custom proposal types (issue #266)', () => {
+  it('fromGuardian collapses an unmodeled type to the custom bucket, keeping the raw label', () => {
+    const wire: GuardianProposalMetadata = {
+      proposalType: 'b2agg',
+      description: 'agglayer bridge note',
+    };
+    const md = ProposalMetadataCodec.fromGuardian(wire) as CustomProposalMetadata;
+    expect(md.proposalType).toBe('custom');
+    expect(md.rawProposalType).toBe('b2agg');
+  });
+
+  it('toGuardian round-trips the raw label, not the custom bucket', () => {
+    const md: CustomProposalMetadata = {
+      proposalType: 'custom',
+      description: 'agglayer bridge note',
+      rawProposalType: 'b2agg',
+    };
+    const wire = ProposalMetadataCodec.toGuardian(md);
+    expect(wire.proposalType).toBe('b2agg');
+
+    const back = ProposalMetadataCodec.fromGuardian(wire) as CustomProposalMetadata;
+    expect(back.proposalType).toBe('custom');
+    expect(back.rawProposalType).toBe('b2agg');
+  });
+
+  it('validate accepts a custom proposal', () => {
+    const md: CustomProposalMetadata = {
+      proposalType: 'custom',
+      description: 'opaque',
+      rawProposalType: 'b2agg',
+    };
+    expect(ProposalMetadataCodec.validate(md)).toBe(md);
+  });
+
+  it('round-trips update_procedure_threshold through the codec', () => {
+    const wire: GuardianProposalMetadata = {
+      proposalType: 'update_procedure_threshold',
+      targetProcedure: 'send_asset',
+      targetThreshold: 2,
+    };
+    const md = ProposalMetadataCodec.fromGuardian(wire);
+    expect(md.proposalType).toBe('update_procedure_threshold');
+    const back = ProposalMetadataCodec.toGuardian(md);
+    expect(back.proposalType).toBe('update_procedure_threshold');
+    expect(back.targetProcedure).toBe('send_asset');
+    expect(back.targetThreshold).toBe(2);
+  });
+});

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 {
@@ -46,8 +48,9 @@ export class ProposalMetadataCodec {
           targetThreshold: metadata.targetThreshold,
           signerCommitments: metadata.targetSignerCommitments,
         };
-      case 'unknown':
-        return base;
+      case 'custom':
+        // Round-trip the original server label rather than the 'custom' bucket.
+        return { ...base, proposalType: metadata.rawProposalType };
     }
   }
 
@@ -82,6 +85,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) {
@@ -116,12 +121,18 @@ export class ProposalMetadataCodec {
         }
         return {
           ...base,
-          proposalType: guardian.proposalType,
+          proposalType: guardian.proposalType as 'add_signer' | 'remove_signer' | 'change_threshold',
           targetThreshold: guardian.targetThreshold,
           targetSignerCommitments: guardian.signerCommitments,
         };
       default:
-        throw new Error(`Unsupported proposal type: ${guardian.proposalType as string}`);
+        // Any proposal type the SDK does not model collapses to the 'custom'
+        // bucket while preserving the original label (issue #266).
+        return {
+          ...base,
+          proposalType: 'custom',
+          rawProposalType: guardian.proposalType,
+        };
     }
   }
 
@@ -158,8 +169,10 @@ export class ProposalMetadataCodec {
           throw new Error('p2id proposal metadata is incomplete');
         }
         return metadata;
-      case 'unknown':
-        throw new Error('unknown proposal type is not supported');
+      case 'custom':
+        // Custom proposals are opaque to the SDK; nothing to validate beyond
+        // the base fields. They can be listed/signed/exported, not built here.
+        return metadata;
     }
   }
 }

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