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

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

@@ -1,11 +1,21 @@
-import type {
-  ProposalSignature,
-  ProposalType as GuardianProposalType,
-  SignatureScheme,
-} from '@openzeppelin/guardian-client';
+import type { ProposalSignature, SignatureScheme } from '@openzeppelin/guardian-client';
 import type { ProcedureName } from '../procedures.js';
 
-export type ProposalType = Exclude<GuardianProposalType, 'custom'>;
+/**
+ * Closed set of proposal types the multisig SDK models behaviorally, plus the
+ * `'custom'` bucket for any server-defined type the SDK does not model (issue
+ * #266). Defined explicitly (not derived from the now-arbitrary guardian-client
+ * wire union) so the exhaustive switches in the metadata codec stay sound.
+ */
+export type ProposalType =
+  | 'add_signer'
+  | 'remove_signer'
+  | 'change_threshold'
+  | 'update_procedure_threshold'
+  | 'switch_guardian'
+  | 'consume_notes'
+  | 'p2id'
+  | 'custom';
 
 export type ProposalStatus = 'pending' | 'ready' | 'finalized';
 
@@ -49,9 +59,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 {
@@ -61,8 +89,13 @@ export interface P2IdProposalMetadata extends BaseProposalMetadata {
   amount: string;
 }
 
-export interface UnknownProposalMetadata extends BaseProposalMetadata {
-  proposalType: 'unknown';
+export interface CustomProposalMetadata extends BaseProposalMetadata {
+  proposalType: 'custom';
+  /** Original server-defined proposal label, e.g. "b2agg" (issue #266). Mirrors
+   * Rust `ProposalMetadata.proposal_type`; it is what lets a custom proposal
+   * round-trip back to GUARDIAN/export, so it is required in the domain model.
+   * Any wire-level optionality is resolved in the parser/codec boundary. */
+  rawProposalType: string;
 }
 
 export type ProposalMetadata =
@@ -71,7 +104,7 @@ export type ProposalMetadata =
   | UpdateProcedureThresholdProposalMetadata
   | ConsumeNotesProposalMetadata
   | P2IdProposalMetadata
-  | UnknownProposalMetadata;
+  | CustomProposalMetadata;
 
 export interface Proposal {
   id: string;

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'

package/src/multisig/proposal/execution.ts

@@ -1,385 +0,0 @@
-import { type DeltaObject, type GuardianHttpClient } from '@openzeppelin/guardian-client';
-import type {
-  MidenClient,
-  TransactionProver,
-  TransactionRequest,
-} from '@miden-sdk/miden-sdk';
-import {
-  AdviceMap,
-  FeltArray,
-  Signature,
-  TransactionSummary,
-  Word,
-} from '@miden-sdk/miden-sdk';
-import type { ProposalType, TransactionProposal } from '../../types.js';
-import {
-  buildConsumeNotesTransactionRequest,
-  buildP2idTransactionRequest,
-  buildUpdateGuardianTransactionRequest,
-  buildUpdateProcedureThresholdTransactionRequest,
-  buildUpdateSignersTransactionRequest,
-} from '../../transaction.js';
-import { base64ToUint8Array, normalizeHexWord } from '../../utils/encoding.js';
-import {
-  buildSignatureAdviceEntry,
-  signatureHexToBytes,
-  tryComputeEcdsaCommitmentHex,
-} from '../../utils/signature.js';
-import { computeCommitmentFromTxSummary } from '../helpers.js';
-
-interface ResolveExecutionSourceResult {
-  delta?: DeltaObject;
-  txSummaryBase64: string;
-}
-
-interface PrepareExecutionResult {
-  txSummary: TransactionSummary;
-  saltHex: string;
-  txCommitmentHex: string;
-}
-
-interface ExecuteProposalWorkflowParams {
-  proposal: TransactionProposal;
-  accountId: string;
-  threshold: number;
-  signerCommitments: string[];
-  guardianCommitment: string;
-  guardianPublicKey?: string;
-  signatureScheme: 'falcon' | 'ecdsa';
-  getEffectiveThreshold: (proposalType: ProposalType) => number;
-  guardian: GuardianHttpClient;
-  midenClient: MidenClient;
-  transactionProver?: TransactionProver | null;
-}
-
-export async function executeProposalWorkflow(
-  params: ExecuteProposalWorkflowParams,
-): Promise<void> {
-  ensureProposalReady(
-    params.proposal,
-    params.threshold,
-    params.getEffectiveThreshold,
-  );
-
-  const isSwitchGuardian = params.proposal.metadata.proposalType === 'switch_guardian';
-  const executionSource = await resolveExecutionSource(
-    params.guardian,
-    params.accountId,
-    params.proposal,
-    isSwitchGuardian,
-  );
-  const executionData = prepareExecutionData(executionSource.txSummaryBase64);
-
-  const adviceMap = buildCosignerAdviceMap(
-    params.proposal,
-    params.signerCommitments,
-    executionData.txCommitmentHex,
-  );
-
-  if (!isSwitchGuardian && executionSource.delta) {
-    await appendGuardianAckAdvice(
-      params.guardian,
-      executionSource.delta,
-      params.guardianCommitment,
-      params.guardianPublicKey,
-      params.signatureScheme,
-      executionData.txCommitmentHex,
-      adviceMap,
-    );
-  }
-
-  const finalRequest = await buildFinalRequest(
-    params,
-    executionData.saltHex,
-    adviceMap,
-  );
-  await submitTransaction(
-    params.midenClient,
-    params.accountId,
-    finalRequest,
-  );
-}
-
-
-export async function createTransactionProposalRequest(
-  params: ExecuteProposalWorkflowParams,
-): Promise<TransactionRequest> {
-  ensureProposalReady(
-    params.proposal,
-    params.threshold,
-    params.getEffectiveThreshold,
-  );
-
-  const isSwitchGuardian = params.proposal.metadata.proposalType === 'switch_guardian';
-  const executionSource = await resolveExecutionSource(
-    params.guardian,
-    params.accountId,
-    params.proposal,
-    isSwitchGuardian,
-  );
-  const executionData = prepareExecutionData(executionSource.txSummaryBase64);
-
-  const adviceMap = buildCosignerAdviceMap(
-    params.proposal,
-    params.signerCommitments,
-    executionData.txCommitmentHex,
-  );
-
-  if (!isSwitchGuardian && executionSource.delta) {
-    await appendGuardianAckAdvice(
-      params.guardian,
-      executionSource.delta,
-      params.guardianCommitment,
-      params.guardianPublicKey,
-      params.signatureScheme,
-      executionData.txCommitmentHex,
-      adviceMap,
-    );
-  }
-
-  return await buildFinalRequest(
-    params,
-    executionData.saltHex,
-    adviceMap,
-  );
-}
-
-function ensureProposalReady(
-  proposal: TransactionProposal,
-  defaultThreshold: number,
-  getEffectiveThreshold: (proposalType: ProposalType) => number,
-): void {
-  const proposalType = proposal.metadata?.proposalType;
-  const effectiveThreshold = proposalType
-    ? getEffectiveThreshold(proposalType)
-    : defaultThreshold;
-
-  if (proposal.signatures.length < effectiveThreshold) {
-    throw new Error('Proposal is not ready for execution. Still pending signatures.');
-  }
-}
-
-async function resolveExecutionSource(
-  guardian: GuardianHttpClient,
-  accountId: string,
-  proposal: TransactionProposal,
-  isSwitchGuardian: boolean,
-): Promise<ResolveExecutionSourceResult> {
-  if (isSwitchGuardian) {
-    return { txSummaryBase64: proposal.txSummary };
-  }
-
-  const deltas = await guardian.getDeltaProposals(accountId);
-  const delta = deltas.find(
-    (d) => computeCommitmentFromTxSummary(d.deltaPayload.txSummary.data) === proposal.commitment,
-  );
-
-  if (!delta) {
-    throw new Error(`Proposal not found on server: ${proposal.commitment}`);
-  }
-
-  return {
-    delta,
-    txSummaryBase64: delta.deltaPayload.txSummary.data,
-  };
-}
-
-function prepareExecutionData(txSummaryBase64: string): PrepareExecutionResult {
-  const txSummaryBytes = base64ToUint8Array(txSummaryBase64);
-  const txSummary = TransactionSummary.deserialize(txSummaryBytes);
-  const saltHex = txSummary.salt().toHex();
-  const txCommitmentHex = txSummary.toCommitment().toHex();
-  return { txSummary, saltHex, txCommitmentHex };
-}
-
-function buildCosignerAdviceMap(
-  proposal: TransactionProposal,
-  signerCommitments: string[],
-  txCommitmentHex: string,
-): AdviceMap {
-  const adviceMap = new AdviceMap();
-  const normalizedSignerCommitments = new Set(
-    signerCommitments.map((c) => normalizeHexWord(c)),
-  );
-
-  for (const cosignerSig of proposal.signatures) {
-    let signerCommitmentHex = normalizeHexWord(cosignerSig.signerId);
-    if (cosignerSig.signature.scheme === 'ecdsa' && cosignerSig.signature.publicKey) {
-      const derived = tryComputeEcdsaCommitmentHex(cosignerSig.signature.publicKey);
-      if (derived && derived !== signerCommitmentHex) {
-        if (!normalizedSignerCommitments.has(derived)) {
-          throw new Error(
-            `ECDSA public key commitment mismatch: derived commitment ${derived} is not in signerCommitments.`,
-          );
-        }
-        signerCommitmentHex = derived;
-      }
-    }
-
-    const signerCommitment = Word.fromHex(signerCommitmentHex);
-    const sigBytes = signatureHexToBytes(
-      cosignerSig.signature.signature,
-      cosignerSig.signature.scheme,
-    );
-    const signature = Signature.deserialize(sigBytes);
-    const txCommitment = Word.fromHex(normalizeHexWord(txCommitmentHex));
-    const ecdsaPublicKey =
-      cosignerSig.signature.scheme === 'ecdsa'
-        ? cosignerSig.signature.publicKey
-        : undefined;
-    const isEcdsa = cosignerSig.signature.scheme === 'ecdsa' && Boolean(ecdsaPublicKey);
-
-    const { key, values } = buildSignatureAdviceEntry(
-      signerCommitment,
-      txCommitment,
-      signature,
-      ecdsaPublicKey,
-      isEcdsa ? cosignerSig.signature.signature : undefined,
-    );
-    adviceMap.insert(key, new FeltArray(values));
-  }
-
-  return adviceMap;
-}
-
-async function appendGuardianAckAdvice(
-  guardian: GuardianHttpClient,
-  delta: DeltaObject,
-  guardianCommitmentHex: string,
-  guardianPublicKey: string | undefined,
-  defaultAckScheme: 'falcon' | 'ecdsa',
-  txCommitmentHex: string,
-  adviceMap: AdviceMap,
-): Promise<void> {
-  const executionDelta = {
-    ...delta,
-    deltaPayload: delta.deltaPayload.txSummary,
-  };
-
-  const pushResult = await guardian.pushDelta(executionDelta);
-  const ackSigHex = pushResult.ackSig;
-  if (!ackSigHex) {
-    throw new Error('GUARDIAN did not return acknowledgment signature');
-  }
-
-  const guardianAckScheme: 'ecdsa' | 'falcon' =
-    (pushResult.ackScheme as 'ecdsa' | 'falcon') || defaultAckScheme;
-  const ackPubkey = pushResult.ackPubkey || guardianPublicKey;
-  const normalizedGuardianCommitment = normalizeHexWord(guardianCommitmentHex);
-
-  if (guardianAckScheme === 'ecdsa' && ackPubkey) {
-    const derived = tryComputeEcdsaCommitmentHex(ackPubkey);
-    if (derived && derived !== normalizedGuardianCommitment) {
-      throw new Error('GUARDIAN public key commitment mismatch');
-    }
-  }
-
-  const guardianCommitment = Word.fromHex(normalizedGuardianCommitment);
-  const ackSigBytes = signatureHexToBytes(ackSigHex, guardianAckScheme);
-  const ackSignature = Signature.deserialize(ackSigBytes);
-  const txCommitment = Word.fromHex(normalizeHexWord(txCommitmentHex));
-  const isAckEcdsa = guardianAckScheme === 'ecdsa' && ackPubkey;
-  const { key, values } = buildSignatureAdviceEntry(
-    guardianCommitment,
-    txCommitment,
-    ackSignature,
-    isAckEcdsa ? ackPubkey : undefined,
-    isAckEcdsa ? ackSigHex : undefined,
-  );
-  adviceMap.insert(key, new FeltArray(values));
-}
-
-async function buildFinalRequest(
-  params: ExecuteProposalWorkflowParams,
-  saltHex: string,
-  adviceMap: AdviceMap,
-): Promise<TransactionRequest> {
-  const metadata = params.proposal.metadata;
-  const normalizedSalt = Word.fromHex(normalizeHexWord(saltHex));
-
-  switch (metadata.proposalType) {
-    case 'consume_notes': {
-      if (!metadata.noteIds || metadata.noteIds.length === 0) {
-        throw new Error(
-          'Proposal missing noteIds. Was it created with createConsumeNotesProposal?',
-        );
-      }
-      const { request } = await buildConsumeNotesTransactionRequest(
-        params.midenClient,
-        metadata.noteIds,
-        { salt: normalizedSalt, signatureAdviceMap: adviceMap },
-      );
-      return request;
-    }
-    case 'switch_guardian': {
-      if (!metadata.newGuardianPubkey) {
-        throw new Error(
-          'Proposal missing newGuardianPubkey. Was it created with createSwitchGuardianProposal?',
-        );
-      }
-      const { request } = await buildUpdateGuardianTransactionRequest(
-        params.midenClient,
-        metadata.newGuardianPubkey,
-        {
-          salt: normalizedSalt,
-          signatureAdviceMap: adviceMap,
-          signatureScheme: params.signatureScheme,
-        },
-      );
-      return request;
-    }
-    case 'update_procedure_threshold': {
-      const { request } = await buildUpdateProcedureThresholdTransactionRequest(
-        params.midenClient,
-        metadata.targetProcedure,
-        metadata.targetThreshold,
-        {
-          salt: normalizedSalt,
-          signatureAdviceMap: adviceMap,
-          signatureScheme: params.signatureScheme,
-        },
-      );
-      return request;
-    }
-    case 'p2id': {
-      if (!metadata.recipientId || !metadata.faucetId || !metadata.amount) {
-        throw new Error(
-          'Proposal missing P2ID metadata (recipientId, faucetId, amount). Was it created with createP2idProposal?',
-        );
-      }
-      const { request } = buildP2idTransactionRequest(
-        params.accountId,
-        metadata.recipientId,
-        metadata.faucetId,
-        BigInt(metadata.amount),
-        { salt: normalizedSalt, signatureAdviceMap: adviceMap },
-      );
-      return request;
-    }
-    case 'unknown':
-      throw new Error(
-        'Cannot execute proposal with unknown type. The proposal must have been imported without proper metadata.',
-      );
-    default: {
-      const { request } = await buildUpdateSignersTransactionRequest(
-        params.midenClient,
-        metadata.targetThreshold,
-        metadata.targetSignerCommitments,
-        {
-          salt: normalizedSalt,
-          signatureAdviceMap: adviceMap,
-          signatureScheme: params.signatureScheme,
-        },
-      );
-      return request;
-    }
-  }
-}
-
-async function submitTransaction(
-  midenClient: MidenClient,
-  accountIdHex: string,
-  request: TransactionRequest,
-): Promise<void> {
-  await midenClient.transactions.submit(accountIdHex, request);
-}