masm: add error codes (#492)

miden-lib/asm/kernels/transaction/api.masm

@@ -5,6 +5,15 @@ use.miden::kernels::tx::memory
 use.miden::kernels::tx::note
 use.miden::kernels::tx::tx
 
+# ERRORS
+# =================================================================================================
+
+# For faucets the slot FAUCET_STORAGE_DATA_SLOT is reserved and can not be used with set_account_item
+const.ERR_FAUCET_RESERVED_DATA_SLOT=0x00020000
+
+# Procedure can only be called for faucet accounts
+const.ERR_ACCT_MUST_BE_A_FAUCET=0x00020001
+
 # EVENTS
 # =================================================================================================
 
@@ -153,7 +162,7 @@ export.set_account_item
     # index != FAUCET_STORAGE_DATA_SLOT (reserved slot)
     dup exec.account::get_faucet_storage_data_slot eq
     exec.account::get_id exec.account::is_faucet
-    and assertz
+    and assertz.err=ERR_FAUCET_RESERVED_DATA_SLOT
     # => [index, V', 0, 0, 0]
 
     # authenticate that the procedure invocation originates from the account context
@@ -508,7 +517,7 @@ end
 #!   against.
 export.get_fungible_faucet_total_issuance
     # assert that we are executing a transaction against a fungible faucet (access checks)
-    exec.account::get_id exec.account::is_fungible_faucet assert
+    exec.account::get_id exec.account::is_fungible_faucet assert.err=ERR_ACCT_MUST_BE_A_FAUCET
     # => [0]
 
     # get the total issuance

miden-lib/asm/miden/asset.masm

@@ -2,6 +2,18 @@ use.miden::kernels::tx::account->internal_account
 use.miden::kernels::tx::asset
 use.miden::account
 
+# ERRORS
+# =================================================================================================
+
+# Can not build the fungible asset because provided id is not a fungible id
+const.ERR_ASSET_NOT_FUNGIBLE_ID=0x00020041
+
+# Can not build the asset because amount exceeds the maximum
+const.ERR_ASSET_INVALID_AMOUNT=0x00020042
+
+# Can not build the non-fungible asset because provided id is not a non-fungible id
+const.ERR_ASSET_NOT_NON_FUNGIBLE_ID=0x00020043
+
 # CONSTANTS
 # =================================================================================================
 
@@ -21,11 +33,11 @@ const.TWO_POW_32=4294967296
 #! - ASSET is the built fungible asset.
 export.build_fungible_asset
     # assert the faucet is a fungible faucet
-    dup exec.internal_account::is_fungible_faucet assert
+    dup exec.internal_account::is_fungible_faucet assert.err=ERR_ASSET_NOT_FUNGIBLE_ID
     # => [faucet_id, amount]
 
     # assert the amount is valid
-    dup.1 exec.asset::get_fungible_asset_max_amount lte assert
+    dup.1 exec.asset::get_fungible_asset_max_amount lte assert.err=ERR_ASSET_INVALID_AMOUNT
     # => [faucet_id, amount]
 
     # create the asset
@@ -60,7 +72,7 @@ end
 #! - ASSET is the built non-fungible asset.
 export.build_non_fungible_asset
     # assert the faucet is a non-fungible faucet
-    dup exec.internal_account::is_non_fungible_faucet assert
+    dup exec.internal_account::is_non_fungible_faucet assert.err=ERR_ASSET_NOT_NON_FUNGIBLE_ID
     # => [faucet_id, DATA_HASH]
 
     # build the asset

miden-lib/asm/miden/contracts/faucets/basic_fungible.masm

@@ -13,6 +13,12 @@ use.miden::faucet
 use.miden::tx
 use.miden::contracts::auth::basic
 
+# ERRORS
+# =================================================================================================
+
+# Distribute would cause the max supply to be exceeded
+const.ERR_BASIC_FUNGIBLE_MAX_SUPPLY_OVERFLOW=0x00020021
+
 # CONSTANTS
 # =================================================================================================
 
@@ -51,7 +57,7 @@ export.distribute
     # => [max_supply - total_issuance, amount, tag, RECIPIENT, ...]
 
     # check that amount =< max_supply - total_issuance, fails if otherwise
-    dup.1 gte assert
+    dup.1 gte assert.err=ERR_BASIC_FUNGIBLE_MAX_SUPPLY_OVERFLOW
     # => [asset, tag, RECIPIENT, ...]
 
     # creating the asset

miden-lib/asm/miden/kernels/tx/account.masm

@@ -1,6 +1,24 @@
 use.miden::kernels::tx::constants
 use.miden::kernels::tx::memory
 
+# ERRORS
+# =================================================================================================
+
+# The nonce increase must be a u32
+const.ERR_ACCOUNT_NONCE_INCR_MUST_BE_U32=0x0002003B
+
+# Account id format is invalid, insufficient ones
+const.ERR_ACCOUNT_INSUFFICIENT_ONES=0x0002003C
+
+# Account must be updatable for it to be possible to update its code
+const.ERR_ACCOUNT_SET_CODE_ACCOUNT_MUST_BE_UPDATABLE=0x0002003D
+
+# Account seed digest mismatch
+const.ERR_ACCOUNT_SEED_DIGEST_MISMATCH=0x0002003E
+
+# Account pow is insufficient
+const.ERR_ACCOUNT_INVALID_POW=0x0002003F
+
 # CONSTANTS
 # =================================================================================================
 
@@ -120,7 +138,7 @@ export.incr_nonce
     # emit event to signal that account nonce is being incremented
     emit.ACCOUNT_INCREMENT_NONCE_EVENT
 
-    u32assert
+    u32assert.err=ERR_ACCOUNT_NONCE_INCR_MUST_BE_U32
     exec.memory::get_acct_nonce add
     exec.memory::set_acct_nonce
 end
@@ -280,7 +298,7 @@ export.validate_id
     # => [ones]
 
     # check if the number of ones is at least MIN_ACCOUNT_ONES ones.
-    push.MIN_ACCOUNT_ONES u32gte assert
+    push.MIN_ACCOUNT_ONES u32gte assert.err=ERR_ACCOUNT_INSUFFICIENT_ONES
 end
 
 #! Sets the code of the account the transaction is being executed against. This procedure can only
@@ -296,7 +314,7 @@ export.set_code
     # => [acct_id, CODE_ROOT]
 
     # assert the account is an updatable regular account
-    exec.is_updatable_account assert
+    exec.is_updatable_account assert.err=ERR_ACCOUNT_SET_CODE_ACCOUNT_MUST_BE_UPDATABLE
     # => [CODE_ROOT]
 
     # set the code root
@@ -431,7 +449,7 @@ export.validate_seed
 
         # assert the account id matches the account id of the new account and extract pow
         # element
-        movdn.3 drop drop exec.memory::get_acct_id eq assert
+        movdn.3 drop drop exec.memory::get_acct_id eq assert.err=ERR_ACCOUNT_SEED_DIGEST_MISMATCH
         # => [pow]
 
         # get acct and facuet modulus to check the min number of trailing zeros required in the pow
@@ -449,6 +467,6 @@ export.validate_seed
         # => [pow, modulus]
 
         # assert that the pow is valid
-        u32split drop swap u32divmod assertz drop
+        u32split drop swap u32divmod assertz.err=ERR_ACCOUNT_INVALID_POW drop
         # => []
 end

miden-lib/asm/miden/kernels/tx/asset.masm

@@ -1,5 +1,32 @@
 use.miden::kernels::tx::account
 
+# ERRORS
+# =================================================================================================
+
+# The felt at position 1 must be zero
+const.ERR_FUNGIBLE_ASSET_FORMAT_POSITION_ONE_MUST_BE_ZERO=0x00020033
+
+# The felt at position 2 must be zero
+const.ERR_ASSET_FORMAT_POSITION_TWO_MUST_BE_ZERO=0x00020034
+
+# The felt at position 3 must correspond to a fungible
+const.ERR_FUNGIBLE_ASSET_FORMAT_POSITION_THREE_MUST_BE_ZERO=0x00020035
+
+# The felt at position 0 must be within limit
+const.ERR_FUNGIBLE_ASSET_FORMAT_POSITION_ZERO_MUST_BE_ZERO=0x00020036
+
+# The felt at position 1 must be zero
+const.ERR_NON_FUNGIBLE_ASSET_FORMAT_POSITION_ONE_MUST_FUNGIBLE=0x00020037
+
+# The felt at position 3 must be zero
+const.ERR_NON_FUNGIBLE_ASSET_FORMAT_POSITION_THREE_HAS_HIGH_BIT_SET=0x00020038
+
+# Fungible asset origin validation failed
+const.ERR_FUNGIBLE_ASSET_MISMATCH=0x00020039
+
+# Fungible asset origin validation failed
+const.ERR_NON_FUNGIBLE_ASSET_MISMATCH=0x0002003A
+
 # CONSTANTS
 # =================================================================================================
 
@@ -27,23 +54,23 @@ end
 #! ASSET is the asset to validate.
 export.validate_fungible_asset
     # assert that ASSET[1] == ZERO
-    dup.1 not assert
+    dup.1 not assert.err=ERR_FUNGIBLE_ASSET_FORMAT_POSITION_ONE_MUST_BE_ZERO
     # => [ASSET]
 
     # assert that ASSET[2] == ZERO
-    dup.2 not assert
+    dup.2 not assert.err=ERR_ASSET_FORMAT_POSITION_TWO_MUST_BE_ZERO
     # => [ASSET]
 
     # assert that ASSET[3] is a valid account id
     dup exec.account::validate_id
     # => [ASSET]
 
     # assert that ASSET[3] is a fungible faucet
-    dup exec.account::is_fungible_faucet assert
+    dup exec.account::is_fungible_faucet assert.err=ERR_FUNGIBLE_ASSET_FORMAT_POSITION_THREE_MUST_BE_ZERO
     # => [ASSET]
 
     # assert that the max amount (ASSET[0]) of a fungible asset is not exceeded
-    dup.3 push.FUNGIBLE_ASSET_MAX_AMOUNT lte assert
+    dup.3 push.FUNGIBLE_ASSET_MAX_AMOUNT lte assert.err=ERR_FUNGIBLE_ASSET_FORMAT_POSITION_ZERO_MUST_BE_ZERO
     # => [ASSET]
 end
 
@@ -74,11 +101,14 @@ export.validate_non_fungible_asset
     # => [ASSET]
 
     # assert that ASSET[1] is a fungible faucet
-    dup.2 exec.account::is_non_fungible_faucet assert
+    dup.2 exec.account::is_non_fungible_faucet assert.err=ERR_NON_FUNGIBLE_ASSET_FORMAT_POSITION_ONE_MUST_FUNGIBLE
     # => [ASSET]
 
     # assert the most significant bit of the most significant element (ASSET[3]) is 0
-    dup u32split swap drop u32assert u32shr.31 not assert
+    dup u32split swap drop
+    u32assert.err=ERR_NON_FUNGIBLE_ASSET_FORMAT_POSITION_THREE_HAS_HIGH_BIT_SET
+    u32shr.31 not
+    assert.err=ERR_NON_FUNGIBLE_ASSET_FORMAT_POSITION_THREE_HAS_HIGH_BIT_SET
     # => [ASSET]
 end
 
@@ -127,7 +157,7 @@ end
 #! - ASSET is the asset to validate.
 export.validate_fungible_asset_origin
     # assert the origin of the asset is the faucet_id provided via the stack
-    dup.1 assert_eq
+    dup.1 assert_eq.err=ERR_FUNGIBLE_ASSET_MISMATCH
     # => [ASSET]
 
     # assert the fungible asset is valid
@@ -144,7 +174,7 @@ end
 #! - ASSET is the asset to validate.
 export.validate_non_fungible_asset_origin
     # assert the origin of the asset is the faucet_id provided via the stack
-    dup.3 assert_eq
+    dup.3 assert_eq.err=ERR_NON_FUNGIBLE_ASSET_MISMATCH
     # => [ASSET]
 
     # assert the non-fungible asset is valid

miden-lib/asm/miden/kernels/tx/asset_vault.masm

@@ -4,6 +4,33 @@ use.miden::kernels::tx::account
 use.miden::kernels::tx::asset
 use.miden::kernels::tx::memory
 
+# ERRORS
+# =================================================================================================
+
+# The get_balance procedure can be called only with a fungible faucet
+const.ERR_VAULT_GET_BALANCE_WRONG_ASSET_TYPE=0x0002002B
+
+# The has_non_fungible_asset procedure can be called only with a non-fungible faucet
+const.ERR_VAULT_HAS_NON_FUNGIBLE_WRONG_ACCOUNT_TYPE=0x0002002C
+
+# Adding the fungible asset would exceed the max_amount
+const.ERR_VAULT_FUNGIBLE_MAX_AMOUNT_EXCEEDED=0x0002002D
+
+# Decorator value did not match the assert commitment
+const.ERR_VAULT_ADD_FUNGIBLE_ASSET_MISMATCH=0x0002002E
+
+# The non-fungible asset already existed, can not be added again.
+const.ERR_VAULT_NON_FUNGIBLE_ALREADY_EXISTED=0x0002002F
+
+# Removing the fungible asset would have current amount being negative
+const.ERR_VAULT_FUNGIBLE_AMOUNT_UNDERFLOW=0x00020030
+
+# Data provided via decorator did not match the commitment
+const.ERR_VAULT_REMOVE_FUNGIBLE_ASSET_MISMATCH=0x00020031
+
+# Removing inexisting non-fungible asset
+const.ERR_VAULT_NON_FUNGIBLE_MISSING_ASSET=0x00020032
+
 # ACCESSORS
 # =================================================================================================
 
@@ -18,7 +45,7 @@ use.miden::kernels::tx::memory
 #! - balance is the vault balance of the fungible asset.
 export.get_balance
     # assert that the faucet id is a fungible faucet
-    dup exec.account::is_fungible_faucet assert
+    dup exec.account::is_fungible_faucet assert.err=ERR_VAULT_GET_BALANCE_WRONG_ASSET_TYPE
     # => [faucet_id, vault_root_ptr]
 
     # get the asset vault root
@@ -49,7 +76,7 @@ end
 #! - has_asset is a boolean indicating whether the account vault has the asset of interest
 export.has_non_fungible_asset
     # check if the asset is a non-fungible asset
-    exec.asset::is_non_fungible_asset assert
+    exec.asset::is_non_fungible_asset assert.err=ERR_VAULT_HAS_NON_FUNGIBLE_WRONG_ACCOUNT_TYPE
     # => [ASSET, vault_root_ptr]
 
     # prepare the stack to read non-fungible asset from vault
@@ -103,7 +130,7 @@ export.add_fungible_asset
     # => [(max_amount - cur_amount), amount, amount, cur_amount, faucet_id, 0, 0, VAULT_ROOT, CUR_VAULT_VALUE, vault_root_ptr]
 
     # assert amount + cur_amount < max_amount
-    lte assert
+    lte assert.err=ERR_VAULT_FUNGIBLE_MAX_AMOUNT_EXCEEDED
     # => [amount, cur_amount, faucet_id, 0, 0, VAULT_ROOT, CUR_VAULT_VALUE, vault_root_ptr]
 
     # add asset amounts
@@ -116,7 +143,7 @@ export.add_fungible_asset
 
     # update asset in vault and assert the old value is equivalent to the value provided via the
     # decorator
-    exec.smt::set movupw.2 assert_eqw
+    exec.smt::set movupw.2 assert_eqw.err=ERR_VAULT_ADD_FUNGIBLE_ASSET_MISMATCH
     # => [VAULT_ROOT', ASSET', vault_root_ptr]
 
     # update the vault root
@@ -144,7 +171,7 @@ export.add_non_fungible_asset
     # => [OLD_VAL, VAULT_ROOT', ASSET, vault_root_ptr]
 
     # Assert old value was empty
-    padw assert_eqw
+    padw assert_eqw.err=ERR_VAULT_NON_FUNGIBLE_ALREADY_EXISTED
     # => [VAULT_ROOT', ASSET, vault_root_ptr]
 
     # update the vault root
@@ -219,7 +246,7 @@ export.remove_fungible_asset
     # => [cur_amount, amount, amount, cur_amount, faucet_id, 0, 0, VAULT_ROOT, CUR_VAULT_VALUE, ASSET, vault_root_ptr]
 
     # assert amount <= cur_amount
-    lte assert
+    lte assert.err=ERR_VAULT_FUNGIBLE_AMOUNT_UNDERFLOW
     # => [amount, cur_amount, faucet_id, 0, 0, VAULT_ROOT, CUR_VAULT_VALUE, ASSET, vault_root_ptr]
 
     # asset amount + cur_amount < max_amount
@@ -242,7 +269,7 @@ export.remove_fungible_asset
 
     # update asset in vault and assert the old value is equivalent to the value provided via the
     # decorator
-    exec.smt::set movupw.2 assert_eqw
+    exec.smt::set movupw.2 assert_eqw.err=ERR_VAULT_REMOVE_FUNGIBLE_ASSET_MISMATCH
     # => [VAULT_ROOT', ASSET, vault_root_ptr]
 
     # update the vault root
@@ -271,7 +298,7 @@ export.remove_non_fungible_asset
     # => [OLD_VAL, VAULT_ROOT', ASSET, vault_root_ptr]
 
     # Assert old value was not empty (we only need to check ASSET[1] which is the faucet id)
-    drop drop eq.0 assertz drop
+    drop drop eq.0 assertz.err=ERR_VAULT_NON_FUNGIBLE_MISSING_ASSET drop
     # => [VAULT_ROOT', ASSET, vault_root_ptr]
 
     # update the vault root