chore: refactor miden::protocol from ASSET to ASSET_KEY and ASSET_VALUE

[PhilippGackstatter]

Changes miden::protocol asset APIs to take ASSET_KEY and ASSET_VALUE instead of just ASSET to adapt to the kernel changes from #2396.

This PR, like #2396, also keeps the key and value layout of assets unchanged and only deals with expanding assets from one to two words for simplicity.

Migration

• SWAP note storage previously stored just REQUESTED_ASSET. Now it stores REQUESTED_ASSET_KEY and REQUESTED_ASSET_VALUE.
• miden::standards::wallets::basic::move_asset_to_note no longer returns parameters (motivated by add_asset_to_note procedure results overhead when calling from Rust #1717).
• Rename miden::protocol::asset::build_(non_)fungible_asset -> miden::protocol::asset::create_(non_)fungible_asset, for consistency with the miden::protocol::faucet procedures of the same name.
  • We generally use create_ and build_ interchangeably in APIs and it would be nice to be more consistent there.
• The following procedures now take or return an asset vault key in addition to the asset value:
  • miden::protocol::faucet::create_fungible_asset
  • miden::protocol::faucet::create_non_fungible_asset
  • miden::protocol::faucet::mint
  • miden::protocol::faucet::burn
  • miden::protocol::asset::create_fungible_asset
  • miden::protocol::asset::create_non_fungible_asset
  • miden::protocol::native_account::add_asset
  • miden::protocol::native_account::remove_asset
  • miden::protocol::output_note::add_asset
  • miden::standards::wallets::basic::move_asset_to_note

Notable Changes

• bridge_out.masm needed a bigger update:
  • keccak hashing includes asset key and value
  • burn note serial derivation takes asset key for now - maybe it should take the whole asset? But, this could also be changed separately.
• Moves the asset vault key build procedures to shared utils for access in both miden::protocol. This logic will change when the layout changes, but some procedure to create a vault key will probably remain at least until generalized assets and maybe beyond.
• Moves mock::util library to miden-standards to be able to provide exec-wrappers for basic::wallet::move_asset_to_note.
• Unifies the asset preservation test in test_epilogue since one of the tests was testing the wrong condition and needed fixing anyway.

part of #2328

[igamigo]

Not a full review yet but leaving some comments, overall looks great.

[mmagician]

review TBC

[mmagician]

not for this PR, but I do wonder if there are better ways to name these constants. I ran into the issue of defining memory locals for similar (w.r.t. function) constants in different procedures, only to find that names get unnecessarily long.

[PhilippGackstatter]

Yep, agreed. My favorite thing would be constants that can be defined in a procedure body to make them scoped and accessible in only that body, e.g.:

@locals(9)
proc create_burn_note
    const ASSET_KEY_LOC = 0
    const ASSET_VALUE_LOC = ASSET_KEY_LOC + ASSET_VALUE_MEMORY_OFFSET

    loc_storew_be.ASSET_KEY_LOC
    swapw
    # => [ASSET_VALUE, ASSET_KEY]

    loc_storew_be.ASSET_VALUE_LOC
    dropw dupw
    # => [ASSET_KEY, ASSET_KEY]
end

Alternatively, we could define these in the @locals attribute:

@locals(
    ASSET_KEY = 0,
    ASSET_VALUE = ASSET_KEY + ASSET_VALUE_MEMORY_OFFSET,
)
proc create_burn_note
    loc_storew_be.ASSET_KEY
    # ...
end

The assembler could translate these into globally defined constants under the hood to not require a new MASM feature, though this may be a bit too much magic for an assembly language.

cc @bitwalker in case you have thoughts for how difficult this would be to add

[mmagician]

great suggestion!

[Copilot]

@mmagician I've opened a new pull request, #2498, to work on those changes. Once the pull request is ready, I'll request review from you.

[mmagician]

LGTM

[bobbinth]

Looks good! Thank you! Not a full review yet, but I left a few small comments inline.