feat: CW Union Transfer library

Cargo.toml

@@ -88,6 +88,7 @@ valence-drop-liquid-staker           = { path = "contracts/libraries/drop-liquid
 valence-drop-liquid-unstaker         = { path = "contracts/libraries/drop-liquid-unstaker", features = ["library"] }
 valence-ica-cctp-transfer            = { path = "contracts/libraries/ica-cctp-transfer", features = ["library"] }
 valence-ica-ibc-transfer             = { path = "contracts/libraries/ica-ibc-transfer", features = ["library"] }
+valence-union-transfer               = { path = "contracts/libraries/union-transfer", features = ["library"] }
 
 # middleware
 valence-middleware-osmosis = { path = "contracts/middleware/type-registries/osmosis/osmo-26-0-0", features = [

contracts/libraries/union-transfer/.cargo/config.toml

@@ -0,0 +1,3 @@
+[alias]
+wasm   = "build --release --lib --target wasm32-unknown-unknown"
+schema = "run --bin schema"

contracts/libraries/union-transfer/Cargo.toml

@@ -0,0 +1,36 @@
+[package]
+name       = "valence-union-transfer"
+authors    = { workspace = true }
+edition    = { workspace = true }
+license    = { workspace = true }
+version    = { workspace = true }
+repository = { workspace = true }
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[features]
+# use library feature to disable all instantiate/execute/query exports
+library = []
+
+[dependencies]
+cosmwasm-schema       = { workspace = true }
+cosmwasm-std          = { workspace = true }
+cw-ownable            = { workspace = true }
+cw-storage-plus       = { workspace = true }
+cw-utils              = { workspace = true }
+cw20                  = { workspace = true }
+schemars              = { workspace = true }
+serde                 = { workspace = true }
+thiserror             = { workspace = true }
+valence-macros        = { workspace = true }
+valence-library-utils = { workspace = true }
+valence-library-base  = { workspace = true }
+alloy-sol-types       = "0.7.7"
+alloy-primitives      = "0.7.7"
+sha2                  = { workspace = true }
+
+[dev-dependencies]
+cw-multi-test         = { workspace = true }
+valence-account-utils = { workspace = true }
+valence-library-utils = { workspace = true, features = ["testing"] }

contracts/libraries/union-transfer/README.md

@@ -0,0 +1,81 @@
+# Valence Union Transfer library
+
+The **Valence Union Transfer** library allows to transfer funds over [Union](https://union.build/) from an **input account** on a source chain to an **output account** on a destination chain. It is typically used as part of a **Valence Program**. In that context, a **Processor** contract will be the main contract interacting with the Forwarder library.
+
+
+## High-level flow
+
+```mermaid
+---
+title: Union Transfer Library
+---
+graph LR
+  IA((Input Account))
+  ZG((zkGM))
+  R((Recipient))
+  P[Processor]
+  U[Union Transfer
+   Library]
+  UTM[Union Token
+   Protocol]
+  subgraph EVM[ EVM Chain ]
+    UTM -- 6/Send tokens --> R
+  end
+  subgraph CW[ CosmWasm Domain ]
+    P -- 1/Call
+    transfer(quote_amount) --> U
+    U -- 2/Query CW20/Native
+     token balance --> IA
+    U -- 3/Call approve (if applies) and send --> IA
+    IA -- 4/Approve CW20 (if applies) --> ZG
+    IA -- 5/Call send with instructions --> ZG
+  end
+  CW --- EVM
+```
+
+## Configuration
+
+The library is configured on instantiation via the `LibraryConfig` type.
+
+```rust
+pub struct LibraryConfig {
+    pub input_addr: LibraryAccountType,
+    pub output_addr: LibraryAccountType,
+    pub denom: UncheckedUnionDenomConfig,
+    pub amount: TransferAmount,
+    // Information about the asset to be transferred.
+    pub input_asset_name: String,
+    pub input_asset_symbol: String,
+    pub input_asset_decimals: u8,
+    pub input_asset_token_path: Uint256,
+    // Information about the asset to be received.
+    pub quote_token: String,
+    pub quote_amount: Uint256,
+    // Information about the remote chain.
+    pub channel_id: u64,
+    pub transfer_timeout: Option<u64>, // If not provided, a default 3 days will be used (259200 seconds).
+    // Information about the protocol
+    pub zkgm_contract: String, // The address of the ZKGM contract that we will interact with
+    // They are using a batch operation with a transfer (FungibleAssetOrder) operation inside, so we need the version for both instructions.
+    // If not provided, we will use the versions currently used by the protocol, but this is meant to be used for future upgrades.
+    pub batch_instruction_version: Option<u8>, // The version of the batch instruction to be used. If not provided, the current default version will be used.
+    pub transfer_instruction_version: Option<u8>, // The version of the transfer instruction to be used. If not provided, the current default version will be used.
+}
+
+pub enum UncheckedUnionDenomConfig {
+    /// A native (bank module) asset.
+    Native(String),
+    /// A cw20 asset along with the token minter address that needs to be approved for spending during transfers.
+    Cw20(UncheckedUnionCw20Config),
+}
+
+pub struct UncheckedUnionCw20Config {
+    pub token: String,
+    pub minter: String,
+}
+
+pub enum TransferAmount {
+    FullAmount,
+    FixedAmount(Uint128),
+}
+```