feat(zkgm): evm: introduce fungible asset order v2 (#4617)

## Features
FungibleAssetOrderV2 introduces a flexible metadata architecture
replacing fixed metadata fields with a dynamic type system. Key
improvements include three-tier metadata types (IMAGE, PREIMAGE,
IMAGE_UNWRAP), enhanced token addressing with metadata images, dual
balance tracking for backward compatibility.
## Data Structure Evolution
V1 uses explicit metadata fields (baseTokenSymbol, baseTokenName,
baseTokenDecimals, baseTokenPath) while V2 replaces these with
metadataType and metadata bytes for flexible
handling. The evolution enables dynamic metadata strategies rather than
fixed validation patterns. Example: create my own wrapper with a custom
erc20 implementation/admin on the destination chain.
## Metadata Type System
**FUNGIBLE_ASSET_METADATA_TYPE_IMAGE (0x00)**: Contains 32-byte metadata
hash for existing tokens, enabling deterministic prediction without full
metadata transmission. Triggers escrow-and-mint flow.
**FUNGIBLE_ASSET_METADATA_TYPE_PREIMAGE (0x01)**: Contains full
FungibleAssetMetadata struct for new token deployment. Triggers
escrow-and-mint flow.
**FUNGIBLE_ASSET_METADATA_TYPE_IMAGE_UNWRAP (0x02)**: Signals unwrapping
operations with metadata hash validation, triggering burn-and-unescrow
flow.
## Token Addressing Changes
V1 uses simple deterministic addressing based on path, channel, and
token hash. V2 enhances this by incorporating metadata images into salt
calculation while maintaining V1
compatibility through FUNGIBLE_ASSET_METADATA_IMAGE_PREDICT_V1 magic
constant detection.
## Balance Tracking
V1 implements single-tier tracking with channelBalance mapping. V2
introduces dual-tier tracking maintaining both legacy V1 balance
tracking and enhanced V2 tracking that includes
metadata image in key structure, enabling precise balance management for
tokens with identical addresses but different metadata.
## Compatibility
### Backward Compatibility Mechanisms
Magic image support via FUNGIBLE_ASSET_METADATA_IMAGE_PREDICT_V1 enables
seamless V1 handling. Dual balance systems maintain both V1 and V2
tracking. Legacy acknowledgments preserve
V1-style market maker payments. Fallback prediction enables V1 logic for
magic metadata images.

Author: hussein-aitlahcen

Cargo.lock

@@ -91,6 +91,43 @@ pub fn execute(
 
     let response = match msg {
         ExecuteMsg::Wrapped(msg) => match msg {
+            WrappedTokenMsg::CreateDenomV2 {
+                subdenom,
+                path,
+                channel_id,
+                token,
+                implementation,
+                initializer,
+            } => {
+                let (admin, code_id) =
+                    <(String, u64)>::abi_decode_params_validate(implementation.as_ref()).unwrap();
+                let metadata_image = calculate_metadata_image(implementation, initializer.clone());
+                Response::new()
+                    .add_message(WasmMsg::Instantiate2 {
+                        admin: Some(env.contract.address.to_string()),
+                        code_id: config.dummy_code_id,
+                        label: subdenom.clone(),
+                        msg: to_json_binary(&cosmwasm_std::Empty {})?,
+                        funds: vec![],
+                        salt: Binary::new(calculate_salt_v2(
+                            U256::from_be_bytes::<{ U256::BYTES }>(
+                                path.as_slice().try_into().expect("correctly encoded; qed"),
+                            ),
+                            channel_id,
+                            token.to_vec(),
+                            metadata_image,
+                        )),
+                    })
+                    .add_message(WasmMsg::Migrate {
+                        contract_addr: subdenom.clone(),
+                        new_code_id: code_id,
+                        msg: initializer,
+                    })
+                    .add_message(WasmMsg::UpdateAdmin {
+                        contract_addr: subdenom,
+                        admin,
+                    })
+            }
             WrappedTokenMsg::CreateDenom {
                 metadata,
                 subdenom,
@@ -283,6 +320,29 @@ pub fn query(deps: Deps, env: Env, msg: QueryMsg) -> Result<Binary, Error> {
                 wrapped_token: deps.api.addr_humanize(&token_addr)?.to_string(),
             })?)
         }
+        QueryMsg::PredictWrappedTokenV2 {
+            path,
+            channel_id,
+            token,
+            metadata_image,
+        } => {
+            let Config { dummy_code_id, .. } = CONFIG.load(deps.storage)?;
+            let code_hash = get_code_hash(deps, dummy_code_id)?;
+            let token_addr = instantiate2_address(
+                &code_hash.into_bytes(),
+                &deps.api.addr_canonicalize(env.contract.address.as_str())?,
+                &calculate_salt_v2(
+                    path.parse::<U256>().map_err(Error::U256Parse)?,
+                    channel_id,
+                    token.to_vec(),
+                    metadata_image,
+                ),
+            )?;
+
+            Ok(to_json_binary(&PredictWrappedTokenResponse {
+                wrapped_token: deps.api.addr_humanize(&token_addr)?.to_string(),
+            })?)
+        }
         QueryMsg::Metadata { denom } => match query_token_info(deps, &denom) {
             Ok(TokenInfoResponse {
                 name,
@@ -348,6 +408,29 @@ fn calculate_salt(path: U256, channel_id: ChannelId, token: Vec<u8>) -> Vec<u8>
         .to_vec()
 }
 
+fn calculate_salt_v2(
+    path: U256,
+    channel_id: ChannelId,
+    token: Vec<u8>,
+    metadata_image: H256,
+) -> Vec<u8> {
+    keccak256(
+        (
+            path,
+            channel_id.raw(),
+            token.to_vec(),
+            U256::from_be_bytes(*metadata_image.get()),
+        )
+            .abi_encode_params(),
+    )
+    .into_bytes()
+    .to_vec()
+}
+
+fn calculate_metadata_image(implementation: Binary, initializer: Binary) -> H256 {
+    keccak256((implementation.to_vec(), initializer.to_vec()).abi_encode_params())
+}
+
 fn restrict_name(name: String) -> String {
     if name.len() > 50 {
         let name = &name[(name.len() - 50)..];

cosmwasm/cw20-token-minter/src/contract.rs

@@ -1,7 +1,9 @@
 use alloy_primitives::U256;
+use unionlabs::primitives::H256;
 
 pub const INSTR_VERSION_0: u8 = 0x00;
 pub const INSTR_VERSION_1: u8 = 0x01;
+pub const INSTR_VERSION_2: u8 = 0x02;
 
 pub const OP_FORWARD: u8 = 0x00;
 pub const OP_MULTIPLEX: u8 = 0x01;
@@ -21,6 +23,15 @@ pub const TAG_ACK_SUCCESS: U256 = U256::from_be_slice(&[1]);
 pub const FILL_TYPE_PROTOCOL: U256 = U256::from_be_slice(&[0xB0, 0xCA, 0xD0]);
 pub const FILL_TYPE_MARKETMAKER: U256 = U256::from_be_slice(&[0xD1, 0xCE, 0xC4, 0x5E]);
 
+pub const FUNGIBLE_ASSET_METADATA_TYPE_IMAGE: u8 = 0x00;
+pub const FUNGIBLE_ASSET_METADATA_TYPE_PREIMAGE: u8 = 0x01;
+pub const FUNGIBLE_ASSET_METADATA_TYPE_IMAGE_UNWRAP: u8 = 0x02;
+
+pub const FUNGIBLE_ASSET_METADATA_IMAGE_PREDICT_V1: H256 = H256::new([
+    0xC0, 0xDE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE,
+    0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE, 0xEE,
+]);
+
 pub const FORWARD_SALT_MAGIC: U256 = U256::from_be_slice(&[
     0xC0, 0xDE, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
     0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xBA, 0xBE,
@@ -73,6 +84,24 @@ alloy_sol_types::sol! {
         uint256 quote_amount;
     }
 
+    #[derive(Debug, PartialEq)]
+    struct FungibleAssetOrderV2 {
+        bytes sender;
+        bytes receiver;
+        bytes base_token;
+        uint256 base_amount;
+        uint8 metadata_type;
+        bytes metadata;
+        bytes quote_token;
+        uint256 quote_amount;
+    }
+
+    #[derive(Debug, PartialEq)]
+    struct FungibleAssetMetadata {
+        bytes implementation;
+        bytes initializer;
+    }
+
     #[derive(Debug, PartialEq)]
     struct Stake {
         uint256 token_id;