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

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';
 
@@ -79,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 =
@@ -89,7 +104,7 @@ export type ProposalMetadata =
   | UpdateProcedureThresholdProposalMetadata
   | ConsumeNotesProposalMetadata
   | P2IdProposalMetadata
-  | UnknownProposalMetadata;
+  | CustomProposalMetadata;
 
 export interface Proposal {
   id: string;

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

package/src/multisig/proposal/parser.ts

@@ -1,191 +0,0 @@
-import type {
-  DeltaObject,
-  DeltaStatus,
-  ProposalMetadata as GuardianProposalMetadata,
-} from '@openzeppelin/guardian-client';
-import type {
-  ProposalMetadata,
-  ProposalType,
-  TransactionProposal,
-  TransactionProposalSignature,
-  TransactionProposalStatus,
-} from '../../types.js';
-
-export function buildGuardianMetadata(metadata: ProposalMetadata): GuardianProposalMetadata {
-  const base: GuardianProposalMetadata = {
-    proposalType: metadata.proposalType,
-    description: metadata.description,
-    salt: metadata.saltHex,
-  };
-
-  switch (metadata.proposalType) {
-    case 'consume_notes':
-      return {
-        ...base,
-        noteIds: metadata.noteIds,
-      };
-    case 'p2id':
-      return {
-        ...base,
-        recipientId: metadata.recipientId,
-        faucetId: metadata.faucetId,
-        amount: metadata.amount,
-      };
-    case 'switch_guardian':
-      return {
-        ...base,
-        targetThreshold: metadata.targetThreshold,
-        signerCommitments: metadata.targetSignerCommitments,
-        newGuardianPubkey: metadata.newGuardianPubkey,
-        newGuardianEndpoint: metadata.newGuardianEndpoint,
-      };
-    case 'add_signer':
-    case 'remove_signer':
-    case 'change_threshold':
-      return {
-        ...base,
-        targetThreshold: metadata.targetThreshold,
-        signerCommitments: metadata.targetSignerCommitments,
-      };
-    case 'unknown':
-      return base;
-    default:
-      return base;
-  }
-}
-
-export function fromGuardianMetadata(guardian: GuardianProposalMetadata): ProposalMetadata | undefined {
-  if (!guardian.proposalType) return undefined;
-
-  const base = {
-    description: guardian.description ?? '',
-    saltHex: guardian.salt,
-  };
-
-  switch (guardian.proposalType) {
-    case 'p2id':
-      return {
-        ...base,
-        proposalType: 'p2id',
-        recipientId: guardian.recipientId ?? '',
-        faucetId: guardian.faucetId ?? '',
-        amount: guardian.amount ?? '0',
-      };
-    case 'consume_notes':
-      return {
-        ...base,
-        proposalType: 'consume_notes',
-        noteIds: guardian.noteIds ?? [],
-      };
-    case 'switch_guardian':
-      return {
-        ...base,
-        proposalType: 'switch_guardian',
-        newGuardianPubkey: guardian.newGuardianPubkey ?? '',
-        newGuardianEndpoint: guardian.newGuardianEndpoint,
-        targetThreshold: guardian.targetThreshold,
-        targetSignerCommitments: guardian.signerCommitments,
-      };
-    case 'add_signer':
-    case 'remove_signer':
-    case 'change_threshold':
-      return {
-        ...base,
-        proposalType: guardian.proposalType,
-        targetThreshold: guardian.targetThreshold ?? 0,
-        targetSignerCommitments: guardian.signerCommitments ?? [],
-      };
-    default:
-      return undefined;
-  }
-}
-
-export function deltaStatusToProposalStatus(
-  status: DeltaStatus,
-  signaturesRequired: number,
-): TransactionProposalStatus {
-  switch (status.status) {
-    case 'pending': {
-      const signaturesCollected = status.cosignerSigs.length;
-      if (signaturesCollected >= signaturesRequired) {
-        return { type: 'ready' };
-      }
-      return {
-        type: 'pending',
-        signaturesCollected,
-        signaturesRequired,
-        signers: status.cosignerSigs.map((s) => s.signerId),
-      };
-    }
-    case 'candidate':
-      return { type: 'ready' };
-    case 'canonical':
-    case 'discarded':
-      return { type: 'finalized' };
-  }
-}
-
-interface DeltaToProposalParams {
-  delta: DeltaObject;
-  proposalId: string;
-  metadata: ProposalMetadata;
-  signaturesRequired: number;
-  existingSignatures?: TransactionProposalSignature[];
-}
-
-export function deltaToProposal({
-  delta,
-  proposalId,
-  metadata,
-  signaturesRequired,
-  existingSignatures,
-}: DeltaToProposalParams): TransactionProposal {
-  const status = deltaStatusToProposalStatus(delta.status, signaturesRequired);
-
-  const signaturesFromStatus =
-    delta.status.status === 'pending'
-      ? delta.status.cosignerSigs.map((s) => ({
-          signerId: s.signerId,
-          signature: s.signature,
-          timestamp: s.timestamp,
-        }))
-      : [];
-
-  const signaturesMap = new Map<string, TransactionProposalSignature>();
-  for (const sig of existingSignatures ?? []) {
-    signaturesMap.set(sig.signerId, sig);
-  }
-  for (const sig of signaturesFromStatus) {
-    signaturesMap.set(sig.signerId, sig);
-  }
-  const signatures = Array.from(signaturesMap.values());
-
-  return {
-    id: proposalId,
-    commitment: proposalId,
-    accountId: delta.accountId,
-    nonce: delta.nonce,
-    status,
-    txSummary: delta.deltaPayload.txSummary.data,
-    signatures,
-    metadata,
-  };
-}
-
-export function resolveMetadata(
-  delta: DeltaObject,
-  existingMetadata?: ProposalMetadata,
-): ProposalMetadata | undefined {
-  if (existingMetadata) return existingMetadata;
-  if (!delta.deltaPayload.metadata) return undefined;
-  return fromGuardianMetadata(delta.deltaPayload.metadata);
-}
-
-export function signatureRequirementForProposal(
-  metadata: ProposalMetadata,
-  defaultThreshold: number,
-  getEffectiveThreshold: (proposalType: ProposalType) => number,
-): number {
-  if (metadata.proposalType === 'unknown') return defaultThreshold;
-  return getEffectiveThreshold(metadata.proposalType);
-}