stellar_token_utils/
interface.rs

1use stellar_axelar_std::{Address, Bytes, Env};
2
3pub trait TokenUtilsInterface {
4    /// Create Stellar Asset Contract
5    ///
6    /// This function takes an asset's XDR representation and creates the corresponding
7    /// Stellar Asset Contract. The function is idempotent - if the contract is already
8    /// deployed, it returns the existing contract address without attempting redeployment.
9    /// This prevents failures from frontrunning and ensures consistent behavior.
10    ///
11    /// The function first calculates the deterministic contract address for the given asset,
12    /// then checks if a contract already exists at that address by calling `try_decimals()`.
13    /// If the contract exists and responds successfully, the existing address is returned.
14    /// Otherwise, the contract is deployed and the new address is returned.
15    ///
16    /// This utility is specifically designed for Stellar Classic tokens (native Stellar assets),
17    /// not for Soroban custom tokens. The asset XDR must contain a valid Stellar asset
18    /// representation with both the asset code and issuer information.
19    ///
20    /// # Arguments
21    /// * `asset_xdr` - Bytes representing the XDR encoding of a Stellar asset
22    ///   - Must be at least 40 bytes to accommodate:
23    ///     - Asset type discriminant (4 bytes)
24    ///     - Asset code (4 bytes for AlphaNum4, 12 bytes for AlphaNum12)
25    ///     - Issuer Ed25519 public key (32 bytes)
26    ///
27    /// # Returns
28    /// * `Address` - The Stellar Asset Contract address (existing or newly created)
29    ///
30    /// # Panics
31    /// * If the asset XDR is invalid or malformed
32    /// * If the asset XDR is too short (less than required bytes)
33    /// * If deployment fails for reasons other than the contract already existing
34    ///
35    /// # Usage
36    /// This function is used to create a new Stellar Asset Contract for a specific asset.
37    /// It takes the XDR representation of a Stellar asset (code and issuer) and creates
38    /// a new contract instance for that asset, or returns the existing one if already created.
39    ///
40    /// To obtain the asset XDR:
41    /// 1. Use stellar-sdk to create an Asset object with code and issuer
42    /// 2. Convert the Asset to XDR bytes
43    /// 3. Pass the XDR bytes to this function
44    ///
45    /// Example with stellar-sdk (JavaScript):
46    /// ```javascript
47    /// const asset = new Asset('USDC', 'ISSUER_ADDRESS');
48    /// const xdr = asset.toXDRObject().toXDR('base64');
49    /// // Convert base64 to bytes for contract input
50    /// ```
51    fn create_stellar_asset_contract(env: Env, asset_xdr: Bytes) -> Address;
52}
stellar_token_utils/interface.rs

stellar_token_utils/
interface.rs
