@openzeppelin/miden-multisig-client 0.13.0 → 0.13.2

package/masm/{multisig.masm → auth/multisig.masm}

@@ -1,14 +1,11 @@
-# Multi-Signature RPO Falcon 512 Authentication Component
+# Multi-Signature RPO Falcon 512 Authentication Core Library
 #
-# This component provides multi-signature authentication for accounts.
-# It integrates with the PSM component for optional PSM signature verification.
+# This library provides the reusable multisig procedures used by account wrappers.
 
-use miden::active_account
-use miden::native_account
-use miden::auth
-use openzeppelin::psm
+use miden::protocol::active_account
+use miden::protocol::native_account
+use miden::standards::auth
 
-# Type definitions for v0.12 syntax
 type BeWord = struct @bigendian { a: felt, b: felt, c: felt, d: felt }
 
 # CONSTANTS
@@ -17,7 +14,7 @@ type BeWord = struct @bigendian { a: felt, b: felt, c: felt, d: felt }
 # Auth Request Constants
 
 # The event emitted when a signature is not found for a required signer.
-const AUTH_UNAUTHORIZED_EVENT = event("miden::auth::unauthorized")
+const AUTH_UNAUTHORIZED_EVENT=event("miden::auth::unauthorized")
 
 # Storage Layout Constants
 #
@@ -32,29 +29,35 @@ const AUTH_UNAUTHORIZED_EVENT = event("miden::auth::unauthorized")
 # number of approvers are stored as:
 # [default_threshold, num_approvers, 0, 0].
 # The threshold is guaranteed to be less than or equal to num_approvers.
-const THRESHOLD_CONFIG_SLOT = 0
+const THRESHOLD_CONFIG_SLOT=word("openzeppelin::multisig::threshold_config")
 
 # The slot in this component's storage layout where the public keys map is stored.
 # Map entries: [key_index, 0, 0, 0] => APPROVER_PUBLIC_KEY
-const PUBLIC_KEYS_MAP_SLOT = 1
+const PUBLIC_KEYS_MAP_SLOT=word("openzeppelin::multisig::signer_public_keys")
 
 # The slot in this component's storage layout where executed transactions are stored.
 # Map entries: transaction_message => [is_executed, 0, 0, 0]
-const EXECUTED_TXS_SLOT = 2
+const EXECUTED_TXS_SLOT=word("openzeppelin::multisig::executed_transactions")
 
 # The slot in this component's storage layout where procedure thresholds are stored.
 # Map entries: PROC_ROOT => [proc_threshold, 0, 0, 0]
-const PROC_THRESHOLD_ROOTS_SLOT = 3
+const PROC_THRESHOLD_ROOTS_SLOT=word("openzeppelin::multisig::procedure_thresholds")
 
 # Executed Transaction Flag Constant
-const IS_EXECUTED_FLAG = [1, 0, 0, 0]
+const IS_EXECUTED_FLAG=[1, 0, 0, 0]
 
 # ERRORS
-const ERR_TX_ALREADY_EXECUTED = "failed to approve multisig transaction as it was already executed"
+const ERR_TX_ALREADY_EXECUTED="failed to approve multisig transaction as it was already executed"
 
-const ERR_MALFORMED_MULTISIG_CONFIG = "number of approvers must be equal to or greater than threshold"
+const ERR_MALFORMED_MULTISIG_CONFIG="number of approvers must be equal to or greater than threshold"
 
-const ERR_ZERO_IN_MULTISIG_CONFIG = "number of approvers or threshold must not be zero"
+const ERR_ZERO_IN_MULTISIG_CONFIG="number of approvers or threshold must not be zero"
+
+const ERR_PROC_THRESHOLD_NOT_U32="procedure threshold must be a u32 value"
+
+const ERR_NUM_APPROVERS_OR_PROC_THRESHOLD_NOT_U32="number of approvers and procedure threshold must be u32"
+
+const ERR_PROC_THRESHOLD_EXCEEDS_NUM_APPROVERS="procedure threshold exceeds number of approvers"
 
 # MULTISIG PROCEDURES
 # =================================================================================================
@@ -66,21 +69,21 @@ const ERR_ZERO_IN_MULTISIG_CONFIG = "number of approvers or threshold must not b
 #!
 #! Panics if:
 #! - the same transaction has already been executed
-proc assert_new_tx(msg: BeWord)
+pub proc assert_new_tx(msg: BeWord)
     push.IS_EXECUTED_FLAG
     # => [[0, 0, 0, is_executed], MSG]
 
     swapw
     # => [MSG, IS_EXECUTED_FLAG]
 
-    push.EXECUTED_TXS_SLOT
-    # => [index, MSG, IS_EXECUTED_FLAG]
+    push.EXECUTED_TXS_SLOT[0..2]
+    # => [txs_slot_prefix, txs_slot_suffix, MSG, IS_EXECUTED_FLAG]
 
     # Set the key value pair in the map to mark transaction as executed
     exec.native_account::set_map_item
-    # => [OLD_MAP_ROOT, [0, 0, 0, is_executed]]
+    # => [[0, 0, 0, is_executed]]
 
-    dropw drop drop drop
+    drop drop drop
     # => [is_executed]
 
     assertz.err=ERR_TX_ALREADY_EXECUTED
@@ -119,13 +122,13 @@ proc cleanup_pubkey_mapping(init_num_of_approvers: u32, new_num_of_approvers: u3
         padw swapw
         # => [[0, 0, 0, i-1], EMPTY_WORD, i-1, new_num_of_approvers]
 
-        push.PUBLIC_KEYS_MAP_SLOT
-        # => [pub_key_slot_idx, [0, 0, 0, i-1], EMPTY_WORD, i-1, new_num_of_approvers]
+        push.PUBLIC_KEYS_MAP_SLOT[0..2]
+        # => [pub_key_slot_prefix, pub_key_slot_suffix, [0, 0, 0, i-1], EMPTY_WORD, i-1, new_num_of_approvers]
 
         exec.native_account::set_map_item
-        # => [OLD_MAP_ROOT, OLD_MAP_VALUE, i-1, new_num_of_approvers]
+        # => [OLD_MAP_VALUE, i-1, new_num_of_approvers]
 
-        dropw dropw
+        dropw
         # => [i-1, new_num_of_approvers]
 
         dup.1 dup.1
@@ -137,6 +140,85 @@ proc cleanup_pubkey_mapping(init_num_of_approvers: u32, new_num_of_approvers: u3
     # => []
 end
 
+proc get_threshold_and_num_approvers
+    push.THRESHOLD_CONFIG_SLOT[0..2]
+    exec.active_account::get_initial_item
+    # => [0, 0, num_approvers, threshold]
+
+    drop drop
+    # => [num_approvers, threshold]
+
+    swap
+    # => [threshold, num_approvers]
+end
+
+proc assert_proc_thresholds_lte_num_approvers(num_approvers: u32)
+    exec.active_account::get_num_procedures
+    # => [num_procedures, num_approvers]
+
+    dup neq.0
+    # => [should_continue, num_procedures, num_approvers]
+    while.true
+        sub.1 dup
+        # => [proc_index, proc_index, num_approvers]
+
+        exec.active_account::get_procedure_root
+        # => [PROC_ROOT, proc_index, num_approvers]
+
+        push.PROC_THRESHOLD_ROOTS_SLOT[0..2]
+        # => [proc_roots_slot_prefix, proc_roots_slot_suffix, PROC_ROOT, proc_index, num_approvers]
+
+        exec.active_account::get_initial_map_item
+        # => [[0, 0, 0, proc_threshold], proc_index, num_approvers]
+
+        drop drop drop
+        # => [proc_threshold, proc_index, num_approvers]
+
+        dup.2
+        # => [num_approvers, proc_threshold, proc_index, num_approvers]
+
+        u32assert2.err=ERR_PROC_THRESHOLD_NOT_U32
+        u32gt assertz.err=ERR_PROC_THRESHOLD_EXCEEDS_NUM_APPROVERS
+        # => [proc_index, num_approvers]
+
+        dup neq.0
+        # => [should_continue, proc_index, num_approvers]
+    end
+
+    drop drop
+    # => []
+end
+
+# Internal storage helper used by the public `update_procedure_threshold`
+# entrypoint after it receives direct stack arguments.
+proc set_procedure_threshold(proc_threshold: u32, proc_root: BeWord)
+    exec.get_threshold_and_num_approvers
+    # => [threshold, num_approvers, proc_threshold, PROC_ROOT]
+
+    drop
+    # => [num_approvers, proc_threshold, PROC_ROOT]
+
+    dup.1 swap
+    # => [num_approvers, proc_threshold, proc_threshold, PROC_ROOT]
+
+    u32assert2.err=ERR_NUM_APPROVERS_OR_PROC_THRESHOLD_NOT_U32
+    u32gt assertz.err=ERR_PROC_THRESHOLD_EXCEEDS_NUM_APPROVERS
+    # => [proc_threshold, PROC_ROOT]
+
+    push.0.0.0
+    swapw
+    # => [PROC_ROOT, PROC_THRESHOLD_WORD]
+
+    push.PROC_THRESHOLD_ROOTS_SLOT[0..2]
+    # => [proc_roots_slot_prefix, proc_roots_slot_suffix, PROC_ROOT, PROC_THRESHOLD_WORD]
+
+    exec.native_account::set_map_item
+    # => [OLD_VALUE]
+
+    dropw
+    # => []
+end
+
 #! Update threshold config and add / remove approvers
 #!
 #! Inputs:
@@ -145,7 +227,7 @@ end
 #!     MULTISIG_CONFIG_HASH => [CONFIG, PUB_KEY_N, PUB_KEY_N-1, ..., PUB_KEY_0]
 #!   }
 #! Outputs:
-#!   Operand stack: []
+#!   Operand stack: [TX_SUMMARY_COMMITMENT]
 #!
 #! Where:
 #! - MULTISIG_CONFIG_HASH is the hash of the threshold and new public key vector
@@ -155,7 +237,8 @@ end
 #! Locals:
 #! 0: new_num_of_approvers
 #! 1: init_num_of_approvers
-pub proc update_signers_and_threshold.2(multisig_config_hash: BeWord)
+@locals(2)
+pub proc update_signers_and_threshold(multisig_config_hash: BeWord)
     adv.push_mapval
     # => [MULTISIG_CONFIG_HASH, pad(12)]
 
@@ -182,8 +265,14 @@ pub proc update_signers_and_threshold.2(multisig_config_hash: BeWord)
     eq.0 assertz.err=ERR_ZERO_IN_MULTISIG_CONFIG
     # => [MULTISIG_CONFIG, pad(12)]
 
-    push.THRESHOLD_CONFIG_SLOT
-    # => [slot, MULTISIG_CONFIG, pad(12)]
+    loc_load.0
+    # => [num_approvers, MULTISIG_CONFIG, pad(12)]
+
+    exec.assert_proc_thresholds_lte_num_approvers
+    # => [MULTISIG_CONFIG, pad(12)]
+
+    push.THRESHOLD_CONFIG_SLOT[0..2]
+    # => [config_slot_prefix, config_slot_suffix, MULTISIG_CONFIG, pad(12)]
 
     exec.native_account::set_item
     # => [OLD_THRESHOLD_CONFIG, pad(12)]
@@ -209,13 +298,13 @@ pub proc update_signers_and_threshold.2(multisig_config_hash: BeWord)
         swapw
         # => [[0, 0, 0, i-1], PUB_KEY, i-1, pad(12)]
 
-        push.PUBLIC_KEYS_MAP_SLOT
-        # => [pub_key_slot_idx, [0, 0, 0, i-1], PUB_KEY, i-1, pad(12)]
+        push.PUBLIC_KEYS_MAP_SLOT[0..2]
+        # => [pub_key_slot_prefix, pub_key_slot_suffix, [0, 0, 0, i-1], PUB_KEY, i-1, pad(12)]
 
         exec.native_account::set_map_item
-        # => [OLD_MAP_ROOT, OLD_MAP_VALUE, i-1, pad(12)]
+        # => [OLD_VALUE, i-1, pad(12)]
 
-        dropw dropw
+        dropw
         # => [i-1, pad(12)]
 
         dup neq.0
@@ -236,13 +325,25 @@ pub proc update_signers_and_threshold.2(multisig_config_hash: BeWord)
     # => [pad(12)]
 end
 
+#! Update or clear the threshold override for a specific procedure.
+#!
+#! Inputs:
+#!   Operand stack: [proc_threshold, PROC_ROOT]
+#! Outputs:
+#!   Operand stack: []
+#! Invocation: call
+pub proc update_procedure_threshold(proc_threshold: u32, proc_root: BeWord)
+    exec.set_procedure_threshold
+end
+
 # Computes the effective transaction threshold based on called procedures and per-procedure
 # overrides stored in PROC_THRESHOLD_ROOTS_SLOT. Falls back to default_threshold if no
 # overrides apply.
 #
 #! Inputs:  [default_threshold]
 #! Outputs: [transaction_threshold]
-proc compute_transaction_threshold.1(default_threshold: u32) -> u32
+@locals(1)
+proc compute_transaction_threshold(default_threshold: u32) -> u32
     # 1. initialize transaction_threshold = 0
     # 2. iterate through all account procedures
     #   a. check if the procedure was called during the transaction
@@ -281,8 +382,8 @@ proc compute_transaction_threshold.1(default_threshold: u32) -> u32
         if.true
             # => [PROC_ROOT, num_procedures-1, transaction_threshold]
 
-            push.PROC_THRESHOLD_ROOTS_SLOT
-            # => [PROC_THRESHOLD_ROOTS_SLOT, PROC_ROOT, num_procedures-1, transaction_threshold]
+            push.PROC_THRESHOLD_ROOTS_SLOT[0..2]
+            # => [PROC_THRESHOLD_ROOTS_SLOT_prefix, PROC_THRESHOLD_ROOTS_SLOT_suffix, PROC_ROOT, num_procedures-1, transaction_threshold]
 
             # 2b. get the override proc_threshold of that procedure
             # if the procedure has no override threshold, the returned map item will be [0, 0, 0, 0]
@@ -332,8 +433,7 @@ end
 #! 1. Computing the transaction summary message that needs to be signed
 #! 2. Verifying signatures from multiple required signers against their public keys
 #! 3. Ensuring the minimum threshold of valid signatures is met
-#! 4. Implementing replay protection by tracking executed transactions
-#! 5. Verifying PSM signature if PSM selector is enabled (via PSM component)
+#! 4. Returning the transaction summary commitment for higher-level wrappers.
 #!
 #! Inputs:
 #!   Operand stack: [SALT]
@@ -355,11 +455,11 @@ end
 #!
 #! Panics if:
 #! - insufficient number of valid signatures (below threshold).
-#! - the same transaction has already been executed (replay protection).
-#! - PSM signature verification fails (if PSM is enabled).
+#! - insufficient number of valid signatures (below threshold).
 #!
-#! Invocation: call
-pub proc auth_tx_rpo_falcon512_multisig.1(salt: BeWord)
+#! Invocation: exec
+@locals(1)
+pub proc auth_tx(salt: BeWord) -> BeWord
     exec.native_account::incr_nonce drop
     # => [SALT]
 
@@ -378,8 +478,8 @@ pub proc auth_tx_rpo_falcon512_multisig.1(salt: BeWord)
 
     # ------ Verifying approver signatures ------
 
-    push.THRESHOLD_CONFIG_SLOT
-    # => [index, TX_SUMMARY_COMMITMENT]
+    push.THRESHOLD_CONFIG_SLOT[0..2]
+    # => [config_slot_prefix, config_slot_suffix, TX_SUMMARY_COMMITMENT]
 
     exec.active_account::get_initial_item
     # => [0, 0, num_of_approvers, default_threshold, TX_SUMMARY_COMMITMENT]
@@ -390,10 +490,10 @@ pub proc auth_tx_rpo_falcon512_multisig.1(salt: BeWord)
     swap movdn.5
     # => [num_of_approvers, TX_SUMMARY_COMMITMENT, default_threshold]
 
-    push.PUBLIC_KEYS_MAP_SLOT
-    # => [pub_key_slot_idx, num_of_approvers, TX_SUMMARY_COMMITMENT, default_threshold]
+    push.PUBLIC_KEYS_MAP_SLOT[0..2]
+    # => [pub_key_slot_prefix, pub_key_slot_suffix, num_of_approvers, TX_SUMMARY_COMMITMENT, default_threshold]
 
-    exec.::miden::auth::rpo_falcon512::verify_signatures
+    exec.::miden::standards::auth::falcon512_rpo::verify_signatures
     # => [num_verified_signatures, TX_SUMMARY_COMMITMENT, default_threshold]
 
     # ------ Checking threshold is >= num_verified_signatures ------
@@ -413,11 +513,5 @@ pub proc auth_tx_rpo_falcon512_multisig.1(salt: BeWord)
         push.0 assert.err="insufficient number of signatures"
     end
 
-    # ------ Verifying PSM Signature ------
     # => [TX_SUMMARY_COMMITMENT]
-    call.psm::verify_psm_signature
-
-    # ------ Writing executed transaction MSG to map ------
-    # => [TX_SUMMARY_COMMITMENT]
-    exec.assert_new_tx
-end
+end