@openzeppelin/miden-multisig-client 0.13.1 → 0.13.3

package/dist/multisig.js

@@ -1,49 +1,85 @@
-import { AccountInspector } from './inspector.js';
-import { Account, AccountId, } from '@miden-sdk/miden-sdk';
-import { executeForSummary, buildUpdateSignersTransactionRequest, buildUpdatePsmTransactionRequest, buildConsumeNotesTransactionRequest, buildP2idTransactionRequest, } from './transaction.js';
+/**
+ * Multisig class representing a created or loaded multisig account.
+ *
+ * This class wraps a Miden SDK Account and provides GUARDIAN integration
+ * for proposal management.
+ */
+import { GuardianHttpClient } from '@openzeppelin/guardian-client';
+import { Account, AccountId, AdviceMap, Endpoint, FeltArray, RpcClient, Signature, TransactionSummary, Word, } from '@miden-sdk/miden-sdk';
+import { executeForSummary, buildUpdateSignersTransactionRequest, buildUpdateProcedureThresholdTransactionRequest, buildUpdateGuardianTransactionRequest, buildConsumeNotesTransactionRequest, buildP2idTransactionRequest, } from './transaction.js';
 import { base64ToUint8Array, uint8ArrayToBase64, normalizeHexWord, } from './utils/encoding.js';
+import { buildSignatureAdviceEntry, normalizeSignerCommitment, signatureHexToBytes, tryComputeEcdsaCommitmentHex, } from './utils/signature.js';
 import { computeCommitmentFromTxSummary, accountIdToHex } from './multisig/helpers.js';
-import { buildPsmMetadata, deltaToProposal, resolveMetadata, signatureRequirementForProposal, } from './multisig/proposal/parser.js';
-import { toPsmSignature, buildPsmSignatureFromSigner, } from './multisig/signing.js';
-import { createTransactionProposalRequest, executeProposalWorkflow } from './multisig/proposal/execution.js';
+import { buildGuardianSignatureFromSigner } from './multisig/signing.js';
+import { AccountInspector } from './inspector.js';
+import { ProposalFactory } from './proposal/factory.js';
+import { ProposalMetadataCodec } from './proposal/metadata.js';
+import { ProposalSignatures } from './proposal/signatures.js';
+/**
+ * Represents a multisig account with GUARDIAN integration.
+ */
 export class Multisig {
     account;
     threshold;
     signerCommitments;
-    psmCommitment;
-    psmPublicKey;
+    guardianCommitment;
     procedureThresholds;
-    signatureScheme;
-    psm;
+    guardianPublicKey;
+    guardian;
     signer;
     webClient;
     _accountId;
+    midenRpcEndpoint;
     proposals = new Map();
-    constructor(account, config, psm, signer, webClient, accountId) {
-        if (config.signatureScheme && config.signatureScheme !== signer.scheme) {
-            throw new Error(`signature scheme mismatch: config=${config.signatureScheme} signer=${signer.scheme}`);
-        }
+    constructor(account, config, guardian, signer, webClient, accountId, midenRpcEndpoint) {
         this.account = account;
         this.threshold = config.threshold;
         this.signerCommitments = config.signerCommitments;
-        this.psmCommitment = config.psmCommitment;
-        this.psmPublicKey = config.psmPublicKey;
-        this.signatureScheme = config.signatureScheme ?? signer.scheme;
+        this.guardianCommitment = config.guardianCommitment;
+        this.guardianPublicKey = config.guardianPublicKey;
         this.procedureThresholds = new Map((config.procedureThresholds ?? []).map((pt) => [pt.procedure, pt.threshold]));
-        this.psm = psm;
+        this.guardian = guardian;
         this.signer = signer;
         this.webClient = webClient;
         this._accountId = accountId ?? (account ? accountIdToHex(account) : '');
+        this.midenRpcEndpoint = midenRpcEndpoint;
     }
+    getMidenRpcEndpoint() {
+        if (!this.midenRpcEndpoint) {
+            throw new Error('Missing Miden RPC endpoint in MultisigClient configuration');
+        }
+        return this.midenRpcEndpoint;
+    }
+    proposalFactory() {
+        return new ProposalFactory({
+            accountId: this._accountId,
+            signerCommitments: this.signerCommitments,
+            resolveRequiredSignatures: (proposalType) => this.getEffectiveThreshold(proposalType),
+        });
+    }
+    async verifyGuardianEndpointCommitment(endpoint, expectedCommitment) {
+        if (!endpoint) {
+            throw new Error('Switch GUARDIAN proposal missing newGuardianEndpoint');
+        }
+        const endpointClient = new GuardianHttpClient(endpoint);
+        const fetchedPubkey = await endpointClient.getPubkey(this.signer.scheme);
+        const endpointCommitment = normalizeHexWord(fetchedPubkey.commitment);
+        const normalizedExpected = normalizeHexWord(expectedCommitment);
+        if (endpointCommitment !== normalizedExpected) {
+            throw new Error(`Refusing to use GUARDIAN endpoint ${endpoint}: endpoint pubkey commitment ${endpointCommitment} does not match expected ${normalizedExpected}`);
+        }
+    }
+    /** The account ID as a string */
     get accountId() {
         return this._accountId;
     }
+    /** The signer's commitment */
     get signerCommitment() {
         return this.signer.commitment;
     }
-    setPsmPublicKey(pubkey) {
-        this.psmPublicKey = pubkey;
-    }
+    /**
+     * Maps a proposal type to the procedure that determines its threshold.
+     */
     getProposalProcedure(proposalType) {
         switch (proposalType) {
             case 'p2id':
@@ -54,12 +90,21 @@ export class Multisig {
             case 'remove_signer':
             case 'change_threshold':
                 return 'update_signers';
-            case 'switch_psm':
-                return 'update_psm';
+            case 'update_procedure_threshold':
+                return 'update_procedure_threshold';
+            case 'switch_guardian':
+                return 'update_guardian';
             default:
                 return null;
         }
     }
+    /**
+     * Get the effective threshold for a given proposal type.
+     * Returns the procedure-specific threshold if configured, otherwise the default threshold.
+     *
+     * @param proposalType - The type of proposal
+     * @returns The threshold that applies to this proposal type
+     */
     getEffectiveThreshold(proposalType) {
         if (this.procedureThresholds.size === 0) {
             return this.threshold;
@@ -70,293 +115,431 @@ export class Multisig {
         }
         return this.procedureThresholds.get(procedure) ?? this.threshold;
     }
-    setPsmClient(psmClient) {
-        this.psm = psmClient;
-        this.psm.setSigner(this.signer);
+    /**
+     * Update the GUARDIAN client used by this Multisig instance.
+     *
+     * @param guardianClient - The new GUARDIAN HTTP client
+     */
+    setGuardianClient(guardianClient) {
+        this.guardian = guardianClient;
+        this.guardian.setSigner(this.signer);
     }
+    /**
+     * Fetch the current account state from GUARDIAN.
+     *
+     * @returns The account state including commitment and serialized data
+     */
     async fetchState() {
-        const state = await this.psm.getState(this._accountId);
+        const state = await this.guardian.getState(this._accountId);
         return {
             accountId: state.accountId,
             commitment: state.commitment,
             stateDataBase64: state.stateJson.data,
             createdAt: state.createdAt,
             updatedAt: state.updatedAt,
-            authScheme: state.authScheme,
         };
     }
+    /**
+     * Sync account state from GUARDIAN into the local WebClient store.
+     *
+     * If the GUARDIAN commitment differs from the local commitment (or the account
+     * is missing locally), the local store is overwritten with the GUARDIAN state.
+     */
     async syncState() {
         const state = await this.fetchState();
         const accountId = AccountId.fromHex(this._accountId);
         const localAccount = await this.webClient.getAccount(accountId);
-        const psmCommitment = normalizeHexWord(state.commitment);
+        let accountForConfigRefresh = localAccount ?? null;
+        const guardianCommitment = normalizeHexWord(state.commitment);
         const localCommitment = localAccount
             ? normalizeHexWord(localAccount.commitment().toHex())
             : null;
-        if (!localAccount || localCommitment !== psmCommitment) {
+        if (!localAccount || localCommitment !== guardianCommitment) {
             const accountBytes = base64ToUint8Array(state.stateDataBase64);
-            const account = Account.deserialize(accountBytes);
-            await this.webClient.newAccount(account, true);
+            const incomingAccount = Account.deserialize(accountBytes);
+            await this.ensureSafeToOverwriteLocalState(incomingAccount, localAccount);
+            await this.webClient.newAccount(incomingAccount, true);
+            accountForConfigRefresh = incomingAccount;
         }
+        this.refreshConfigFromAccount(accountForConfigRefresh);
         return state;
     }
-    async registerOnPsm(initialStateBase64) {
-        if (!this.account && !initialStateBase64) {
-            throw new Error('Cannot register on PSM: no account available and no initial state provided');
+    async verifyStateCommitment() {
+        const accountId = AccountId.fromHex(this._accountId);
+        const localAccount = await this.webClient.getAccount(accountId);
+        if (!localAccount) {
+            throw new Error(`Local account state not found for account ${this._accountId}. Sync the account before verifying.`);
         }
-        let stateData;
-        if (initialStateBase64) {
-            stateData = initialStateBase64;
+        const localCommitment = normalizeHexWord(localAccount.commitment().toHex());
+        const onChainCommitment = await this.getOnChainCommitment(accountId);
+        if (!onChainCommitment) {
+            throw new Error(`On-chain account details not found for account ${this._accountId}`);
         }
-        else {
-            const accountBytes = this.account.serialize();
-            stateData = uint8ArrayToBase64(accountBytes);
+        if (localCommitment !== onChainCommitment) {
+            throw new Error(`Local account commitment does not match on-chain commitment for account ${this._accountId}`);
         }
-        const auth = this.signer.scheme === 'ecdsa'
-            ? { MidenEcdsa: { cosigner_commitments: this.signerCommitments } }
-            : { MidenFalconRpo: { cosigner_commitments: this.signerCommitments } };
-        const response = await this.psm.configure({
+        return {
             accountId: this._accountId,
-            auth,
-            initialState: { data: stateData, accountId: this._accountId },
-        });
-        if (!response.success) {
-            throw new Error(`Failed to register on PSM: ${response.message}`);
-        }
-        if (response.ackCommitment && this.psmCommitment) {
-            const onChain = normalizeHexWord(this.psmCommitment);
-            const server = normalizeHexWord(response.ackCommitment);
-            if (onChain !== server) {
-                throw new Error(`PSM commitment mismatch: on-chain=${onChain}, server=${server}`);
+            localCommitment,
+            onChainCommitment,
+        };
+    }
+    async ensureSafeToOverwriteLocalState(incomingAccount, localAccount) {
+        if (localAccount) {
+            const localNonce = localAccount.nonce().asInt();
+            const incomingNonce = incomingAccount.nonce().asInt();
+            if (incomingNonce <= localNonce) {
+                throw new Error(`Refusing to overwrite local state: incoming nonce ${incomingNonce.toString()} is not greater than local nonce ${localNonce.toString()} for account ${this._accountId}`);
             }
         }
-    }
-    async syncAll() {
-        const proposals = await this.syncTransactionProposals();
-        const state = await this.syncState();
-        const notes = await this.getConsumableNotes();
-        const config = AccountInspector.fromBase64(state.stateDataBase64, this.signatureScheme);
-        this.threshold = config.threshold;
-        this.signerCommitments = config.signerCommitments;
-        if (config.psmCommitment) {
-            this.psmCommitment = config.psmCommitment;
+        const accountId = AccountId.fromHex(this._accountId);
+        const onChainCommitment = await this.getOnChainCommitment(accountId);
+        if (!onChainCommitment) {
+            return;
+        }
+        const incomingCommitment = normalizeHexWord(incomingAccount.commitment().toHex());
+        if (incomingCommitment !== onChainCommitment) {
+            throw new Error(`Refusing to overwrite local state: incoming commitment does not match on-chain commitment for account ${this._accountId}`);
         }
-        this.procedureThresholds = config.procedureThresholds;
-        return { proposals, state, notes, config };
     }
-    async getAccountConfig() {
-        const state = await this.syncState();
-        return AccountInspector.fromBase64(state.stateDataBase64, this.signatureScheme);
+    async getOnChainCommitment(accountId) {
+        const rpcClient = new RpcClient(new Endpoint(this.getMidenRpcEndpoint()));
+        try {
+            const accountDetails = await rpcClient.getAccountDetails(accountId);
+            // If the account is not found or its commitment is zero, means that the account is not deployed yet
+            if (!accountDetails) {
+                return null;
+            }
+            const commitment = normalizeHexWord(accountDetails.commitment().toHex());
+            const zeroCommitment = `0x${'0'.repeat(64)}`;
+            if (commitment === zeroCommitment) {
+                return null;
+            }
+            return commitment;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes('null pointer passed to rust') ||
+                message.includes('No account header record found for given ID') ||
+                message.toLowerCase().includes('not found')) {
+                return null;
+            }
+            throw error;
+        }
     }
-    async switchPsm(psmClient) {
-        const accountId = AccountId.fromHex(this._accountId);
-        const localAccount = await this.webClient.getAccount(accountId);
-        if (localAccount) {
-            this.account = localAccount;
-            const config = AccountInspector.fromAccount(localAccount, this.signatureScheme);
-            if (config.psmCommitment) {
-                this.psmCommitment = config.psmCommitment;
+    refreshConfigFromAccount(account) {
+        if (!account) {
+            return;
+        }
+        try {
+            const detected = AccountInspector.fromAccount(account);
+            this.account = account;
+            this.threshold = detected.threshold;
+            this.signerCommitments = detected.signerCommitments;
+            if (detected.guardianCommitment) {
+                this.guardianCommitment = detected.guardianCommitment;
             }
-            this.threshold = config.threshold;
-            this.signerCommitments = config.signerCommitments;
-            this.procedureThresholds = config.procedureThresholds;
+            this.procedureThresholds = new Map(detected.procedureThresholds);
         }
-        this.setPsmClient(psmClient);
-        const accountBytes = this.account.serialize();
-        const stateData = uint8ArrayToBase64(accountBytes);
+        catch (error) {
+            console.warn('Failed to refresh multisig config from account state', error);
+        }
+    }
+    /**
+     * Register this multisig account on the GUARDIAN server.
+     *
+     * The initial state must be the serialized Account bytes (base64-encoded).
+     * If not provided, the account's serialize() method is used.
+     *
+     * @param initialStateBase64 - Optional base64-encoded serialized Account.¡
+     */
+    async registerOnGuardian(initialStateBase64) {
+        // Serialize the account to bytes and base64-encode
+        const stateData = initialStateBase64 ?? uint8ArrayToBase64(this.account.serialize());
         const auth = this.signer.scheme === 'ecdsa'
-            ? { MidenEcdsa: { cosigner_commitments: this.signerCommitments } }
-            : { MidenFalconRpo: { cosigner_commitments: this.signerCommitments } };
-        const response = await this.psm.configure({
+            ? {
+                MidenEcdsa: {
+                    cosigner_commitments: this.signerCommitments,
+                },
+            }
+            : {
+                MidenFalconRpo: {
+                    cosigner_commitments: this.signerCommitments,
+                },
+            };
+        const response = await this.guardian.configure({
             accountId: this._accountId,
             auth,
             initialState: { data: stateData, accountId: this._accountId },
         });
         if (!response.success) {
-            throw new Error(`Failed to register on PSM: ${response.message}`);
-        }
-        if (response.ackCommitment) {
-            this.psmCommitment = normalizeHexWord(response.ackCommitment);
-        }
-        if (response.ackPubkey) {
-            this.psmPublicKey = response.ackPubkey;
+            throw new Error(`Failed to register on GUARDIAN: ${response.message}`);
         }
     }
-    async syncTransactionProposals() {
-        const deltas = await this.psm.getDeltaProposals(this._accountId);
-        const serverProposalIds = new Set();
+    /**
+     * Sync proposals from the GUARDIAN server.
+     */
+    async syncProposals() {
+        const deltas = await this.guardian.getDeltaProposals(this._accountId);
+        const factory = this.proposalFactory();
         for (const delta of deltas) {
-            const proposalId = computeCommitmentFromTxSummary(delta.deltaPayload.txSummary.data);
-            serverProposalIds.add(proposalId);
+            const proposalId = normalizeHexWord(computeCommitmentFromTxSummary(delta.deltaPayload.txSummary.data));
             const existingProposal = this.proposals.get(proposalId);
-            const resolvedMetadata = resolveMetadata(delta, existingProposal?.metadata);
-            if (!resolvedMetadata) {
-                throw new Error('Missing proposal metadata from PSM');
-            }
-            const proposal = deltaToProposal({
-                delta,
-                proposalId,
-                metadata: resolvedMetadata,
-                signaturesRequired: signatureRequirementForProposal(resolvedMetadata, this.threshold, (proposalType) => this.getEffectiveThreshold(proposalType)),
-                existingSignatures: existingProposal?.signatures,
-            });
+            const proposal = factory.fromDelta(delta, proposalId, existingProposal?.metadata, existingProposal?.signatures ?? []);
+            await this.verifyProposalMetadataBinding(proposal);
             this.proposals.set(proposal.id, proposal);
         }
-        for (const [id, proposal] of this.proposals) {
-            if (serverProposalIds.has(id))
-                continue;
-            const isLocalOnly = proposal.metadata?.proposalType === 'switch_psm' && proposal.status.type !== 'finalized';
-            if (!isLocalOnly) {
-                this.proposals.delete(id);
-            }
-        }
         return Array.from(this.proposals.values());
     }
-    listTransactionProposals() {
+    /**
+     * List all known proposals
+     */
+    listProposals() {
         return Array.from(this.proposals.values());
     }
+    /**
+     * Create a new proposal.
+     *
+     * @param nonce - The nonce for this transaction
+     * @param txSummaryBase64 - Base64-encoded transaction summary
+     * @param metadata - Optional metadata for execution (target config, salt, etc.)
+     */
     async createProposal(nonce, txSummaryBase64, metadata) {
-        const psmMetadata = buildPsmMetadata(metadata);
-        const response = await this.psm.pushDeltaProposal({
+        const guardianMetadata = ProposalMetadataCodec.toGuardian(metadata);
+        const response = await this.guardian.pushDeltaProposal({
             accountId: this._accountId,
             nonce,
             deltaPayload: {
                 txSummary: { data: txSummaryBase64 },
                 signatures: [],
-                metadata: psmMetadata,
+                metadata: guardianMetadata,
             },
         });
-        const proposal = deltaToProposal({
-            delta: response.delta,
-            proposalId: response.commitment,
-            metadata,
-            signaturesRequired: signatureRequirementForProposal(metadata, this.threshold, (proposalType) => this.getEffectiveThreshold(proposalType)),
-        });
+        const proposal = this.proposalFactory().fromDelta(response.delta, response.commitment, metadata);
+        await this.verifyProposalMetadataBinding(proposal);
         this.proposals.set(proposal.id, proposal);
         return proposal;
     }
-    async createAddSignerProposal(newCommitment, options) {
-        const targetThreshold = options?.newThreshold ?? this.threshold;
+    /**
+     * Create an "add signer" proposal.
+     *
+     * @param newCommitment - Commitment of the new signer (hex)
+     * @param nonce - Optional proposal nonce (defaults to Date.now())
+     * @param newThreshold - Optional new threshold (defaults to current threshold)
+     */
+    async createAddSignerProposal(newCommitment, nonce, newThreshold) {
+        const targetThreshold = newThreshold ?? this.threshold;
         const targetSignerCommitments = [...this.signerCommitments, newCommitment];
-        const { request, salt } = await buildUpdateSignersTransactionRequest(this.webClient, targetThreshold, targetSignerCommitments, { signatureScheme: this.signatureScheme });
+        const { request, salt } = await buildUpdateSignersTransactionRequest(this.webClient, targetThreshold, targetSignerCommitments, { signatureScheme: this.signer.scheme });
+        const summary = await executeForSummary(this.webClient, this._accountId, request);
+        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+        const proposalNonce = nonce ?? Date.now();
         const metadata = {
             proposalType: 'add_signer',
             targetThreshold,
             targetSignerCommitments,
             saltHex: salt.toHex(),
+            requiredSignatures: this.getEffectiveThreshold('add_signer'),
             description: `Add signer ${newCommitment.slice(0, 10)}...`,
         };
-        return this.createAndSyncFromRequest(request, metadata, options?.nonce);
+        return this.createProposal(proposalNonce, summaryBase64, metadata);
     }
-    async createRemoveSignerProposal(signerToRemove, options) {
+    /**
+     * Create a "remove signer" proposal by executing the update_signers script to summary.
+     *
+     * @param signerToRemove - Commitment of the signer to remove (hex)
+     * @param nonce - Optional proposal nonce (defaults to Date.now())
+     * @param newThreshold - Optional new threshold (defaults to min of current threshold and new signer count)
+     */
+    async createRemoveSignerProposal(signerToRemove, nonce, newThreshold) {
         const normalizedRemove = signerToRemove.toLowerCase();
-        const signerExists = this.signerCommitments.some((c) => c.toLowerCase() === normalizedRemove);
-        if (!signerExists) {
+        const targetSignerCommitments = this.signerCommitments.filter((c) => c.toLowerCase() !== normalizedRemove);
+        if (targetSignerCommitments.length === this.signerCommitments.length) {
             throw new Error(`Signer ${signerToRemove} is not in the current signer list`);
         }
-        const targetSignerCommitments = this.signerCommitments.filter((c) => c.toLowerCase() !== normalizedRemove);
         if (targetSignerCommitments.length === 0) {
             throw new Error('Cannot remove the last signer');
         }
-        const targetThreshold = options?.newThreshold ?? Math.min(this.threshold, targetSignerCommitments.length);
+        const targetThreshold = newThreshold ?? Math.min(this.threshold, targetSignerCommitments.length);
         if (targetThreshold < 1 || targetThreshold > targetSignerCommitments.length) {
             throw new Error(`Invalid threshold ${targetThreshold}. Must be between 1 and ${targetSignerCommitments.length}`);
         }
-        const { request, salt } = await buildUpdateSignersTransactionRequest(this.webClient, targetThreshold, targetSignerCommitments, { signatureScheme: this.signatureScheme });
+        const { request, salt } = await buildUpdateSignersTransactionRequest(this.webClient, targetThreshold, targetSignerCommitments, { signatureScheme: this.signer.scheme });
+        const summary = await executeForSummary(this.webClient, this._accountId, request);
+        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+        const proposalNonce = nonce ?? Date.now();
         const metadata = {
             proposalType: 'remove_signer',
             targetThreshold,
             targetSignerCommitments,
             saltHex: salt.toHex(),
+            requiredSignatures: this.getEffectiveThreshold('remove_signer'),
             description: `Remove signer ${signerToRemove.slice(0, 10)}...`,
         };
-        return this.createAndSyncFromRequest(request, metadata, options?.nonce);
+        return this.createProposal(proposalNonce, summaryBase64, metadata);
     }
-    async createChangeThresholdProposal(newThreshold, options) {
+    /**
+     * Create a "change threshold" proposal.
+     *
+     * @param newThreshold - The new threshold value
+     * @param nonce - Optional proposal nonce (defaults to Date.now())
+     */
+    async createChangeThresholdProposal(newThreshold, nonce) {
         if (newThreshold < 1 || newThreshold > this.signerCommitments.length) {
             throw new Error(`Invalid threshold ${newThreshold}. Must be between 1 and ${this.signerCommitments.length}`);
         }
         if (newThreshold === this.threshold) {
             throw new Error('New threshold is the same as current threshold');
         }
-        const { request, salt } = await buildUpdateSignersTransactionRequest(this.webClient, newThreshold, this.signerCommitments, { signatureScheme: this.signatureScheme });
+        const { request, salt } = await buildUpdateSignersTransactionRequest(this.webClient, newThreshold, this.signerCommitments, { signatureScheme: this.signer.scheme });
+        const summary = await executeForSummary(this.webClient, this._accountId, request);
+        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+        const proposalNonce = nonce ?? Date.now();
         const metadata = {
             proposalType: 'change_threshold',
             targetThreshold: newThreshold,
             targetSignerCommitments: this.signerCommitments,
             saltHex: salt.toHex(),
+            requiredSignatures: this.getEffectiveThreshold('change_threshold'),
             description: `Change threshold from ${this.threshold} to ${newThreshold}`,
         };
-        return this.createAndSyncFromRequest(request, metadata, options?.nonce);
+        return this.createProposal(proposalNonce, summaryBase64, metadata);
     }
-    async createSwitchPsmProposal(newPsmEndpoint, newPsmPubkey, options) {
-        const { request, salt } = await buildUpdatePsmTransactionRequest(this.webClient, newPsmPubkey, { signatureScheme: this.signatureScheme });
+    async createUpdateProcedureThresholdProposal(targetProcedure, targetThreshold, nonce) {
+        if (targetThreshold < 0 || targetThreshold > this.signerCommitments.length) {
+            throw new Error(`Invalid threshold ${targetThreshold}. Must be between 0 and ${this.signerCommitments.length}`);
+        }
+        const currentOverride = this.procedureThresholds.get(targetProcedure);
+        if (targetThreshold === 0 && currentOverride === undefined) {
+            throw new Error(`Procedure ${targetProcedure} does not have an override to clear`);
+        }
+        if (currentOverride !== undefined && currentOverride === targetThreshold) {
+            throw new Error(`Procedure ${targetProcedure} already has threshold override ${targetThreshold}`);
+        }
+        const { request, salt } = await buildUpdateProcedureThresholdTransactionRequest(this.webClient, targetProcedure, targetThreshold, { signatureScheme: this.signer.scheme });
         const summary = await executeForSummary(this.webClient, this._accountId, request);
         const summaryBase64 = uint8ArrayToBase64(summary.serialize());
-        const proposalNonce = options?.nonce ?? Date.now();
+        const proposalNonce = nonce ?? Date.now();
+        const action = targetThreshold === 0
+            ? `Clear threshold override for ${targetProcedure}`
+            : `Set ${targetProcedure} threshold override to ${targetThreshold}`;
         const metadata = {
-            proposalType: 'switch_psm',
+            proposalType: 'update_procedure_threshold',
+            targetProcedure,
+            targetThreshold,
             saltHex: salt.toHex(),
-            newPsmPubkey,
-            newPsmEndpoint,
-            description: `Switch PSM to ${newPsmEndpoint}`,
+            requiredSignatures: this.getEffectiveThreshold('update_procedure_threshold'),
+            description: action,
+        };
+        return this.createProposal(proposalNonce, summaryBase64, metadata);
+    }
+    /**
+     * Create a "switch GUARDIAN" proposal to change the GUARDIAN provider.
+     *
+     * @param newGuardianEndpoint - The new GUARDIAN server endpoint URL
+     * @param newGuardianPubkey - The new GUARDIAN server's public key commitment (hex)
+     * @param nonce - Optional proposal nonce (defaults to Date.now())
+     */
+    async createSwitchGuardianProposal(newGuardianEndpoint, newGuardianPubkey, nonce) {
+        await this.verifyGuardianEndpointCommitment(newGuardianEndpoint, newGuardianPubkey);
+        const { request, salt } = await buildUpdateGuardianTransactionRequest(this.webClient, newGuardianPubkey, { signatureScheme: this.signer.scheme });
+        const summary = await executeForSummary(this.webClient, this._accountId, request);
+        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+        const proposalNonce = nonce ?? Date.now();
+        const metadata = {
+            proposalType: 'switch_guardian',
+            saltHex: salt.toHex(),
+            requiredSignatures: this.getEffectiveThreshold('switch_guardian'),
+            newGuardianPubkey,
+            newGuardianEndpoint,
+            description: `Switch GUARDIAN to ${newGuardianEndpoint}`,
         };
         const proposalId = computeCommitmentFromTxSummary(summaryBase64);
         const proposal = {
             id: proposalId,
-            commitment: proposalId,
             accountId: this._accountId,
             nonce: proposalNonce,
-            status: { type: 'pending', signaturesCollected: 0, signaturesRequired: this.threshold, signers: [] },
+            status: 'pending',
             txSummary: summaryBase64,
             signatures: [],
             metadata,
         };
         this.proposals.set(proposal.id, proposal);
-        const proposals = this.listTransactionProposals();
-        return { proposal, proposals };
+        return proposal;
     }
-    async createConsumeNotesProposal(noteIds, options) {
+    /**
+     * Create a "consume notes" proposal to consume notes sent to the multisig account.
+     *
+     * @param noteIds - IDs of the notes to consume (hex strings)
+     * @param nonce - Optional proposal nonce (defaults to Date.now())
+     */
+    async createConsumeNotesProposal(noteIds, nonce) {
         if (noteIds.length === 0) {
             throw new Error('At least one note ID is required');
         }
         const { request, salt } = await buildConsumeNotesTransactionRequest(this.webClient, noteIds);
+        const summary = await executeForSummary(this.webClient, this._accountId, request);
+        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+        const proposalNonce = nonce ?? Date.now();
         const metadata = {
             proposalType: 'consume_notes',
             noteIds,
             saltHex: salt.toHex(),
+            requiredSignatures: this.getEffectiveThreshold('consume_notes'),
             description: `Consume ${noteIds.length} note(s)`,
         };
-        return this.createAndSyncFromRequest(request, metadata, options?.nonce);
+        return this.createProposal(proposalNonce, summaryBase64, metadata);
     }
-    async createSendProposal(recipientId, faucetId, amount, options) {
+    /**
+     * Create a P2ID proposal to send funds to another account.
+     *
+     * @param recipientId - Account ID of the recipient (hex string)
+     * @param faucetId - Faucet/token account ID (hex string)
+     * @param amount - Amount to send
+     * @param nonce - Optional proposal nonce (defaults to Date.now())
+     */
+    async createP2idProposal(recipientId, faucetId, amount, nonce) {
         if (amount <= 0n) {
             throw new Error('Amount must be greater than 0');
         }
         const { request, salt } = buildP2idTransactionRequest(this._accountId, recipientId, faucetId, amount);
+        const summary = await executeForSummary(this.webClient, this._accountId, request);
+        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
+        const proposalNonce = nonce ?? Date.now();
         const metadata = {
             proposalType: 'p2id',
             saltHex: salt.toHex(),
+            requiredSignatures: this.getEffectiveThreshold('p2id'),
             recipientId,
             faucetId,
             amount: amount.toString(),
-            description: `Send ${amount} to ${recipientId.slice(0, 10)}...`,
+            description: `Send ${amount} of asset ${faucetId.slice(0, 10)}... to ${recipientId.slice(0, 10)}...`,
         };
-        return this.createAndSyncFromRequest(request, metadata, options?.nonce);
+        return this.createProposal(proposalNonce, summaryBase64, metadata);
     }
+    /**
+     * Get notes that can be consumed by this multisig account.
+     *
+     * Returns a list of notes that are committed on-chain and can be consumed
+     * immediately by the multisig account.
+     */
     async getConsumableNotes() {
         const accountId = AccountId.fromHex(this._accountId);
+        // Get consumable notes for this account
         const consumableRecords = await this.webClient.getConsumableNotes(accountId);
+        // Convert to our simplified ConsumableNote type
         const notes = [];
         for (const record of consumableRecords) {
             const inputNote = record.inputNoteRecord();
             const consumability = record.noteConsumability();
+            // Only include notes that can be consumed now (consumableAfterBlock is undefined/null)
             const canConsumeNow = consumability.some((c) => c.accountId().toString().toLowerCase() === this._accountId.toLowerCase() &&
                 c.consumptionStatus().consumableAfterBlock() === undefined);
             if (canConsumeNow) {
                 const noteId = inputNote.id().toString();
                 const details = inputNote.details();
                 const fungibleAssets = details.assets().fungibleAssets();
+                // Extract assets
                 const assets = [];
                 for (const asset of fungibleAssets) {
                     assets.push({
@@ -369,75 +552,216 @@ export class Multisig {
         }
         return notes;
     }
-    async signTransactionProposal(commitment) {
-        const existingProposal = this.proposals.get(commitment);
-        const signature = await buildPsmSignatureFromSigner(this.signer, commitment);
-        const delta = await this.psm.signDeltaProposal({
-            accountId: this._accountId,
-            commitment,
-            signature,
-        });
-        const resolvedMetadata = resolveMetadata(delta, existingProposal?.metadata);
-        if (!resolvedMetadata) {
-            throw new Error('Missing proposal metadata');
-        }
-        const proposal = deltaToProposal({
-            delta,
-            proposalId: commitment,
-            metadata: resolvedMetadata,
-            signaturesRequired: signatureRequirementForProposal(resolvedMetadata, this.threshold, (proposalType) => this.getEffectiveThreshold(proposalType)),
-            existingSignatures: existingProposal?.signatures,
-        });
-        this.proposals.set(proposal.id, proposal);
-        return this.listTransactionProposals();
-    }
-    async signTransactionProposalExternal(params) {
-        const { commitment, signature: signatureHex, publicKey, scheme } = params;
-        const resolvedScheme = scheme ?? this.signatureScheme;
-        const existingProposal = this.proposals.get(commitment);
-        const signature = toPsmSignature(resolvedScheme, signatureHex, publicKey);
-        const delta = await this.psm.signDeltaProposal({
+    /**
+     * Sign a proposal.
+     *
+     * The proposalId is the tx_summary commitment hex, which is what gets signed.
+     * This matches the Rust client behavior where proposal.id == tx_summary.to_commitment().
+     *
+    * @param proposalId - The proposal commitment/ID (this is also what gets signed)
+    */
+    async signProposal(proposalId) {
+        const normalizedProposalId = normalizeHexWord(proposalId);
+        const existingProposal = await this.getProposalForSigning(proposalId, normalizedProposalId);
+        if (!existingProposal) {
+            throw new Error(`Proposal not found: ${proposalId}`);
+        }
+        this.proposalFactory().assertAccountId(existingProposal.accountId);
+        const factory = this.proposalFactory();
+        const proposal = existingProposal;
+        const commitmentToSign = await this.verifyProposalMetadataBinding(proposal);
+        const signature = await buildGuardianSignatureFromSigner(this.signer, commitmentToSign);
+        const signedDelta = await this.guardian.signDeltaProposal({
             accountId: this._accountId,
-            commitment,
+            commitment: normalizedProposalId,
             signature,
         });
-        const resolvedMetadata = resolveMetadata(delta, existingProposal?.metadata);
-        if (!resolvedMetadata) {
-            throw new Error('Missing proposal metadata');
-        }
-        const proposal = deltaToProposal({
-            delta,
-            proposalId: commitment,
-            metadata: resolvedMetadata,
-            signaturesRequired: signatureRequirementForProposal(resolvedMetadata, this.threshold, (proposalType) => this.getEffectiveThreshold(proposalType)),
-            existingSignatures: existingProposal?.signatures,
-        });
-        this.proposals.set(proposal.id, proposal);
-        return this.listTransactionProposals();
+        const signedProposal = factory.fromDelta(signedDelta, normalizedProposalId, proposal.metadata, proposal.signatures);
+        await this.verifyProposalMetadataBinding(signedProposal);
+        this.proposals.set(signedProposal.id, signedProposal);
+        return signedProposal;
     }
-    async executeTransactionProposal(commitment) {
-        const proposal = this.proposals.get(commitment);
+    async getProposalForSigning(proposalId, normalizedProposalId) {
+        const cachedProposal = this.proposals.get(proposalId);
+        if (cachedProposal) {
+            return cachedProposal;
+        }
+        await this.syncProposals();
+        return this.proposals.get(proposalId) ?? this.proposals.get(normalizedProposalId);
+    }
+    /**
+     * Execute a proposal that has enough signatures.
+     *
+     * @param proposalId - The proposal commitment/ID
+     */
+    async executeProposal(proposalId) {
+        const proposal = this.proposals.get(proposalId);
         if (!proposal) {
-            throw new Error(`Proposal not found: ${commitment}`);
+            throw new Error(`Proposal not found: ${proposalId}`);
         }
-        await executeProposalWorkflow({
-            proposal,
-            accountId: this._accountId,
-            threshold: this.threshold,
-            signerCommitments: this.signerCommitments,
-            psmCommitment: this.psmCommitment,
-            psmPublicKey: this.psmPublicKey,
-            signatureScheme: this.signatureScheme,
-            getEffectiveThreshold: (proposalType) => this.getEffectiveThreshold(proposalType),
-            psm: this.psm,
-            webClient: this.webClient,
-        });
-        proposal.status = { type: 'finalized' };
+        await this.verifyProposalMetadataBinding(proposal);
+        const proposalType = proposal.metadata?.proposalType;
+        const effectiveThreshold = proposalType
+            ? this.getEffectiveThreshold(proposalType)
+            : this.threshold;
+        const signatureContext = `Invalid proposal signatures for ${proposalId}`;
+        const signaturesForExecution = new ProposalSignatures(proposal.signatures, this.signerCommitments, signatureContext).entries();
+        if (signaturesForExecution.length < effectiveThreshold) {
+            throw new Error('Proposal is not ready for execution. Still pending signatures.');
+        }
+        const isSwitchGuardian = proposalType === 'switch_guardian';
+        let txSummaryBase64;
+        let delta;
+        if (isSwitchGuardian) {
+            txSummaryBase64 = proposal.txSummary;
+        }
+        else {
+            delta = await this.guardian.getDeltaProposal(this._accountId, proposalId);
+            txSummaryBase64 = delta.deltaPayload.txSummary.data;
+        }
+        const txSummaryBytes = base64ToUint8Array(txSummaryBase64);
+        const txSummary = TransactionSummary.deserialize(txSummaryBytes);
+        const saltHex = txSummary.salt().toHex();
+        const txCommitmentHex = txSummary.toCommitment().toHex();
+        const normalizedSignerCommitments = new Set(this.signerCommitments.map((commitment) => normalizeHexWord(commitment)));
+        const adviceMap = new AdviceMap();
+        const adviceMapKeys = new Set();
+        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 txCommitment = Word.fromHex(normalizeHexWord(txCommitmentHex));
+            const { key, values } = buildSignatureAdviceEntry(signerCommitment, txCommitment, 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));
+        }
+        if (!isSwitchGuardian && delta) {
+            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 || 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 txCommitmentForAck = Word.fromHex(normalizeHexWord(txCommitmentHex));
+            const { key: ackKey, values: ackValues } = buildSignatureAdviceEntry(guardianCommitment, txCommitmentForAck, 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));
+        }
+        const metadata = proposal.metadata;
+        if (!metadata) {
+            throw new Error('Proposal missing metadata');
+        }
+        if (metadata.proposalType === 'switch_guardian') {
+            await this.verifyGuardianEndpointCommitment(metadata.newGuardianEndpoint, metadata.newGuardianPubkey);
+        }
+        const executionSalt = Word.fromHex(normalizeHexWord(saltHex));
+        const finalRequest = await this.buildTransactionRequestFromMetadata(metadata, executionSalt, adviceMap);
+        const accountId = AccountId.fromHex(this._accountId);
+        const result = await this.webClient.executeTransaction(accountId, finalRequest);
+        const proven = await this.webClient.proveTransaction(result, null);
+        const submissionHeight = await this.webClient.submitProvenTransaction(proven, result);
+        await this.webClient.applyTransaction(result, submissionHeight);
+        if (metadata.proposalType === 'switch_guardian') {
+            if (!metadata.newGuardianEndpoint || !metadata.newGuardianPubkey) {
+                throw new Error('Switch GUARDIAN proposal metadata is incomplete after execution');
+            }
+            try {
+                await this.webClient.syncState();
+                const updatedAccount = await this.webClient.getAccount(accountId);
+                if (!updatedAccount) {
+                    throw new Error(`Updated account ${this._accountId} is missing from local client`);
+                }
+                const updatedStateBase64 = uint8ArrayToBase64(updatedAccount.serialize());
+                const nextGuardian = new GuardianHttpClient(metadata.newGuardianEndpoint);
+                this.setGuardianClient(nextGuardian);
+                this.guardianPublicKey = metadata.newGuardianPubkey;
+                await this.registerOnGuardian(updatedStateBase64);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`Transaction executed successfully but failed to register on new GUARDIAN: ${message}`);
+            }
+        }
+        proposal.status = 'finalized';
     }
-    exportTransactionProposalToJson(commitment) {
-        const proposal = this.proposals.get(commitment);
+    /**
+     * Export a proposal for offline signing
+     */
+    async exportProposal(proposalId) {
+        const delta = await this.guardian.getDeltaProposal(this._accountId, proposalId);
+        const existingProposal = this.proposals.get(proposalId);
+        const proposal = this.proposalFactory().fromDelta(delta, proposalId, existingProposal?.metadata, existingProposal?.signatures ?? []);
+        const signatures = delta.status.status === 'pending'
+            ? delta.status.cosignerSigs.map((s) => ({
+                commitment: s.signerId,
+                signatureHex: s.signature.signature,
+                scheme: s.signature.scheme,
+                publicKey: s.signature.scheme === 'ecdsa' ? s.signature.publicKey : undefined,
+                timestamp: s.timestamp,
+            }))
+            : [];
+        return {
+            accountId: delta.accountId,
+            nonce: delta.nonce,
+            commitment: proposalId,
+            txSummaryBase64: delta.deltaPayload.txSummary.data,
+            signatures,
+            metadata: proposal.metadata,
+        };
+    }
+    /**
+     * Export a proposal to JSON for side-channel sharing.
+     *
+     * @param proposalId - The proposal commitment/ID
+     * @returns JSON string that can be shared and imported by other signers
+     */
+    exportProposalToJson(proposalId) {
+        const proposal = this.proposals.get(proposalId);
         if (!proposal) {
-            throw new Error(`Proposal not found in local cache: ${commitment}`);
+            throw new Error(`Proposal not found in local cache: ${proposalId}`);
         }
         const exported = {
             accountId: proposal.accountId,
@@ -447,115 +771,133 @@ export class Multisig {
             signatures: proposal.signatures.map((s) => ({
                 commitment: s.signerId,
                 signatureHex: s.signature.signature,
+                scheme: s.signature.scheme,
+                publicKey: s.signature.scheme === 'ecdsa' ? s.signature.publicKey : undefined,
                 timestamp: s.timestamp,
             })),
             metadata: proposal.metadata,
         };
         return JSON.stringify(exported, null, 2);
     }
-    async createTransactionProposalRequest(commitment) {
-        const proposal = this.proposals.get(commitment);
-        if (!proposal) {
-            throw new Error(`Proposal not found: ${commitment}`);
-        }
-        const request = await createTransactionProposalRequest({
-            proposal,
-            accountId: this._accountId,
-            threshold: this.threshold,
-            signerCommitments: this.signerCommitments,
-            psmCommitment: this.psmCommitment,
-            psmPublicKey: this.psmPublicKey,
-            signatureScheme: this.signatureScheme,
-            getEffectiveThreshold: (proposalType) => this.getEffectiveThreshold(proposalType),
-            psm: this.psm,
-            webClient: this.webClient,
-        });
-        return request;
-    }
-    importTransactionProposal(json) {
+    /**
+     * Import a proposal from JSON (exported via exportProposalToJson).
+     *
+     * @param json - JSON string from exportProposalToJson
+     * @returns The imported proposal
+     */
+    async importProposal(json) {
         const exported = JSON.parse(json);
-        if (!exported.accountId || !exported.txSummaryBase64 || !exported.commitment) {
+        if (!exported.accountId || !exported.txSummaryBase64 || !exported.commitment || !exported.metadata) {
             throw new Error('Invalid proposal JSON: missing required fields');
         }
-        if (exported.accountId.toLowerCase() !== this._accountId.toLowerCase()) {
-            throw new Error(`Proposal is for a different account: ${exported.accountId}`);
-        }
-        const computedCommitment = computeCommitmentFromTxSummary(exported.txSummaryBase64);
-        if (computedCommitment !== exported.commitment) {
-            throw new Error('Invalid proposal: commitment does not match tx_summary');
-        }
-        const metadata = exported.metadata ?? {
-            proposalType: 'unknown',
-            description: '',
-        };
-        const signaturesCollected = exported.signatures.length;
-        const signaturesRequired = this.getEffectiveThreshold(metadata.proposalType);
-        const status = signaturesCollected >= signaturesRequired
-            ? { type: 'ready' }
-            : {
-                type: 'pending',
-                signaturesCollected,
-                signaturesRequired,
-                signers: exported.signatures.map((s) => s.commitment),
-            };
-        const proposal = {
-            id: exported.commitment,
-            commitment: exported.commitment,
-            accountId: exported.accountId,
-            nonce: exported.nonce,
-            status,
-            txSummary: exported.txSummaryBase64,
-            signatures: exported.signatures.map((s) => ({
-                signerId: s.commitment,
-                signature: { scheme: this.signer.scheme, signature: s.signatureHex },
-                timestamp: s.timestamp || new Date().toISOString(),
-            })),
-            metadata,
-        };
+        const proposal = this.proposalFactory().fromExported(exported);
+        await this.verifyProposalMetadataBinding(proposal);
         this.proposals.set(proposal.id, proposal);
-        const proposals = this.listTransactionProposals();
-        return { proposal, proposals };
+        return proposal;
     }
-    async signTransactionProposalOffline(commitment) {
-        const proposal = this.proposals.get(commitment);
+    /**
+     * Sign an imported proposal and return updated JSON for sharing..
+     *
+     * @param proposalId - The proposal commitment/ID
+     * @returns Updated JSON string with the new signature included
+     */
+    async signProposalOffline(proposalId) {
+        const normalizedProposalId = normalizeHexWord(proposalId);
+        const proposal = this.proposals.get(proposalId) ?? this.proposals.get(normalizedProposalId);
         if (!proposal) {
-            throw new Error(`Proposal not found: ${commitment}`);
+            throw new Error(`Proposal not found: ${proposalId}`);
+        }
+        this.proposalFactory().assertAccountId(proposal.accountId);
+        const localSignatureContext = `Invalid local proposal signatures for ${proposalId}`;
+        const existingSignatures = new ProposalSignatures(proposal.signatures, this.signerCommitments, localSignatureContext);
+        let signerCommitment;
+        try {
+            signerCommitment = normalizeSignerCommitment(this.signer.commitment);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid local signer commitment: ${message}`);
         }
-        const alreadySigned = proposal.signatures.some((s) => s.signerId.toLowerCase() === this.signer.commitment.toLowerCase());
+        // Check if already signed
+        const alreadySigned = existingSignatures.hasSigner(signerCommitment);
         if (alreadySigned) {
             throw new Error('You have already signed this proposal');
         }
-        const signatureHex = await this.signer.signCommitment(commitment);
-        const sigEntry = toPsmSignature(this.signer.scheme, signatureHex, this.signer.publicKey);
-        proposal.signatures.push({
-            signerId: this.signer.commitment,
-            signature: sigEntry,
-            timestamp: new Date().toISOString(),
-        });
-        const signaturesCollected = proposal.signatures.length;
+        const commitmentToSign = await this.verifyProposalMetadataBinding(proposal);
+        // Sign the commitment
+        const signature = await buildGuardianSignatureFromSigner(this.signer, commitmentToSign);
+        // Add signature to local proposal
+        const signatures = [
+            ...existingSignatures.entries(),
+            {
+                signerId: signerCommitment,
+                signature,
+                timestamp: new Date().toISOString(),
+            },
+        ];
+        const canonicalizedSignatures = new ProposalSignatures(signatures, this.signerCommitments, localSignatureContext).entries();
+        proposal.signatures = canonicalizedSignatures;
+        // Update status
         const proposalType = proposal.metadata?.proposalType;
-        const effectiveThreshold = proposalType
+        const signaturesRequired = proposalType
             ? this.getEffectiveThreshold(proposalType)
             : this.threshold;
-        if (signaturesCollected >= effectiveThreshold) {
-            proposal.status = { type: 'ready' };
-        }
-        else if (proposal.status.type === 'pending') {
-            proposal.status = {
-                type: 'pending',
-                signaturesCollected,
-                signaturesRequired: effectiveThreshold,
-                signers: proposal.signatures.map((s) => s.signerId),
-            };
+        proposal.status = proposal.signatures.length >= signaturesRequired ? 'ready' : 'pending';
+        // Return updated JSON
+        return this.exportProposalToJson(proposal.id);
+    }
+    ensureProposalCommitmentMatchesSummary(proposal) {
+        const proposalId = normalizeHexWord(proposal.id);
+        const txSummaryCommitment = normalizeHexWord(computeCommitmentFromTxSummary(proposal.txSummary));
+        if (proposalId !== txSummaryCommitment) {
+            throw new Error(`Invalid proposal: id ${proposal.id} does not match tx_summary commitment ${txSummaryCommitment}`);
         }
-        return this.exportTransactionProposalToJson(commitment);
+        return txSummaryCommitment;
     }
-    async createAndSyncFromRequest(request, metadata, nonce) {
-        const summary = await executeForSummary(this.webClient, this._accountId, request);
-        const summaryBase64 = uint8ArrayToBase64(summary.serialize());
-        const proposalNonce = nonce ?? Date.now();
-        const proposal = await this.createProposal(proposalNonce, summaryBase64, metadata);
-        return { proposal, proposals: this.listTransactionProposals() };
+    async verifyProposalMetadataBinding(proposal) {
+        const txSummaryCommitment = this.ensureProposalCommitmentMatchesSummary(proposal);
+        if (proposal.metadata.proposalType === 'unknown') {
+            throw new Error(`Cannot verify proposal metadata for unknown proposal type: ${proposal.id}`);
+        }
+        const summary = TransactionSummary.deserialize(base64ToUint8Array(proposal.txSummary));
+        const salt = proposal.metadata.saltHex
+            ? Word.fromHex(normalizeHexWord(proposal.metadata.saltHex))
+            : summary.salt();
+        const request = await this.buildTransactionRequestFromMetadata(proposal.metadata, salt);
+        const reconstructed = await executeForSummary(this.webClient, this._accountId, request);
+        const reconstructedCommitment = normalizeHexWord(reconstructed.toCommitment().toHex());
+        if (reconstructedCommitment !== txSummaryCommitment) {
+            throw new Error(`Invalid proposal: metadata does not match tx_summary for ${proposal.id}`);
+        }
+        return txSummaryCommitment;
+    }
+    async buildTransactionRequestFromMetadata(metadata, salt, signatureAdviceMap) {
+        switch (metadata.proposalType) {
+            case 'add_signer':
+            case 'remove_signer':
+            case 'change_threshold': {
+                const { request } = await buildUpdateSignersTransactionRequest(this.webClient, metadata.targetThreshold, metadata.targetSignerCommitments, { salt, signatureAdviceMap, signatureScheme: this.signer.scheme });
+                return request;
+            }
+            case 'switch_guardian': {
+                const { request } = await buildUpdateGuardianTransactionRequest(this.webClient, metadata.newGuardianPubkey, { salt, signatureAdviceMap, signatureScheme: this.signer.scheme });
+                return request;
+            }
+            case 'update_procedure_threshold': {
+                const { request } = await buildUpdateProcedureThresholdTransactionRequest(this.webClient, metadata.targetProcedure, metadata.targetThreshold, { salt, signatureAdviceMap, signatureScheme: this.signer.scheme });
+                return request;
+            }
+            case 'consume_notes': {
+                const { request } = await buildConsumeNotesTransactionRequest(this.webClient, metadata.noteIds, { salt, signatureAdviceMap });
+                return request;
+            }
+            case 'p2id': {
+                const { request } = buildP2idTransactionRequest(this._accountId, metadata.recipientId, metadata.faucetId, BigInt(metadata.amount), { salt, signatureAdviceMap });
+                return request;
+            }
+            case 'unknown':
+                throw new Error('Unsupported proposal type: unknown');
+        }
     }
 }
 //# sourceMappingURL=multisig.js.map