{"id":30029353,"url":"https://github.com/volumefi/token-purchaser-cw","last_synced_at":"2025-10-06T11:22:45.366Z","repository":{"id":303440770,"uuid":"936652300","full_name":"VolumeFi/token-purchaser-cw","owner":"VolumeFi","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-07T16:01:36.000Z","size":677,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-08-06T17:21:33.152Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VolumeFi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-21T13:01:47.000Z","updated_at":"2025-07-07T16:01:36.000Z","dependencies_parsed_at":"2025-07-07T17:36:34.872Z","dependency_job_id":null,"html_url":"https://github.com/VolumeFi/token-purchaser-cw","commit_stats":null,"previous_names":["volumefi/token-purchaser-cw"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/VolumeFi/token-purchaser-cw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2Ftoken-purchaser-cw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2Ftoken-purchaser-cw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2Ftoken-purchaser-cw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2Ftoken-purchaser-cw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VolumeFi","download_url":"https://codeload.github.com/VolumeFi/token-purchaser-cw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2Ftoken-purchaser-cw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278599590,"owners_count":26013511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-06T17:02:59.722Z","updated_at":"2025-10-06T11:22:45.346Z","avatar_url":"https://github.com/VolumeFi.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Token Purchaser CW\n\nA CosmWasm-based token purchasing system consisting of two smart contracts: **Collector** and **Manager**. These contracts facilitate cross-chain token operations, DEX exchanges, and PUSD (Paloma USD) management.\n\n## Overview\n\nThis project contains two main contracts:\n\n1. **Collector Contract** (`contracts/collector/`) - Handles token exchanges, cross-chain transfers, and PUSD operations\n2. **Manager Contract** (`contracts/manager/`) - Manages cross-chain deployments, token transfers, and configuration settings\n\n## Contract Architecture\n\n### Collector Contract\n\nThe Collector contract is responsible for:\n- Executing DEX swaps via external routers\n- Managing PUSD withdrawals and cross-chain transfers\n- Handling cross-chain transactions via Paloma's Skyway\n- Owner management for administrative functions\n\n### Manager Contract\n\nThe Manager contract is responsible for:\n- Deploying Paloma ERC20 tokens on external chains\n- Managing cross-chain token transfers\n- Configuring chain-specific settings\n- Updating contract parameters on external chains\n\n## Function Documentation\n\n### Collector Contract Functions\n\n#### `instantiate`\n**Purpose**: Initializes the Collector contract with owner addresses.\n\n**Parameters**:\n- `owners: Vec\u003cString\u003e` - List of owner addresses who can execute privileged functions\n\n**Security**: Only callable during contract deployment.\n\n**Example**:\n```json\n{\n  \"owners\": [\"paloma1abc...\", \"paloma1def...\"]\n}\n```\n\n#### `migrate`\n**Purpose**: Handles contract migrations and version updates.\n\n**Parameters**: None (uses default `MigrateMsg`)\n\n**Security**: Only callable by contract admin.\n\n#### `execute` - Exchange\n**Purpose**: Executes token swaps via external DEX routers.\n\n**Parameters**:\n- `dex_router: Addr` - Address of the DEX router contract\n- `operations: Vec\u003cSwapOperation\u003e` - List of swap operations to execute\n- `minimum_receive: Option\u003cUint128\u003e` - Minimum amount to receive (slippage protection)\n- `to: Option\u003cString\u003e` - Recipient address for swapped tokens\n- `max_spread: Option\u003cDecimal\u003e` - Maximum allowed spread percentage\n- `funds: Vec\u003cCoin\u003e` - Tokens to swap\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"exchange\": {\n    \"dex_router\": \"paloma1router...\",\n    \"operations\": [\n      {\n        \"astro_swap\": {\n          \"offer_asset_info\": {\n            \"native_token\": {\"denom\": \"uluna\"}\n          },\n          \"ask_asset_info\": {\n            \"token\": {\"contract_addr\": \"paloma1token...\"}\n          }\n        }\n      }\n    ],\n    \"minimum_receive\": \"1000000\",\n    \"to\": \"paloma1recipient...\",\n    \"max_spread\": \"0.05\",\n    \"funds\": [{\"denom\": \"uluna\", \"amount\": \"1000000\"}]\n  }\n}\n```\n\n#### `execute` - SendToEvm\n**Purpose**: Sends tokens to an EVM-compatible chain via Paloma's Skyway.\n\n**Parameters**:\n- `recipient: String` - EVM address to receive tokens\n- `amount: String` - Amount of tokens to send\n- `chain_reference_id: String` - Target chain identifier\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"send_to_evm\": {\n    \"recipient\": \"0x1234567890abcdef...\",\n    \"amount\": \"1000000000000000000\",\n    \"chain_reference_id\": \"ethereum\"\n  }\n}\n```\n\n#### `execute` - CancelTx\n**Purpose**: Cancels a pending cross-chain transaction.\n\n**Parameters**:\n- `transaction_id: u64` - ID of the transaction to cancel\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"cancel_tx\": {\n    \"transaction_id\": 12345\n  }\n}\n```\n\n#### `execute` - WithdrawPusd\n**Purpose**: Withdraws PUSD tokens to an external chain.\n\n**Parameters**:\n- `pusd_manager: Addr` - Address of the PUSD manager contract\n- `chain_id: String` - Target chain identifier\n- `recipient: String` - EVM address to receive PUSD\n- `amount: Uint128` - Amount of PUSD to withdraw\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"withdraw_pusd\": {\n    \"pusd_manager\": \"paloma1pusdmanager...\",\n    \"chain_id\": \"ethereum\",\n    \"recipient\": \"0x1234567890abcdef...\",\n    \"amount\": \"1000000000\"\n  }\n}\n```\n\n#### `execute` - ReWithdrawPusd\n**Purpose**: Re-executes a failed PUSD withdrawal using the same nonce.\n\n**Parameters**:\n- `pusd_manager: Addr` - Address of the PUSD manager contract\n- `nonce: u64` - Nonce of the original withdrawal\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"re_withdraw_pusd\": {\n    \"pusd_manager\": \"paloma1pusdmanager...\",\n    \"nonce\": 12345\n  }\n}\n```\n\n#### `execute` - CancelWithdrawPusd\n**Purpose**: Cancels a pending PUSD withdrawal.\n\n**Parameters**:\n- `pusd_manager: Addr` - Address of the PUSD manager contract\n- `nonce: u64` - Nonce of the withdrawal to cancel\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"cancel_withdraw_pusd\": {\n    \"pusd_manager\": \"paloma1pusdmanager...\",\n    \"nonce\": 12345\n  }\n}\n```\n\n#### `execute` - AddOwner\n**Purpose**: Adds a new owner to the contract.\n\n**Parameters**:\n- `owner: String` - Address of the new owner\n\n**Security**: Only callable by existing owners. Prevents duplicate owners.\n\n**Example**:\n```json\n{\n  \"add_owner\": {\n    \"owner\": \"paloma1newowner...\"\n  }\n}\n```\n\n#### `execute` - RemoveOwner\n**Purpose**: Removes an owner from the contract.\n\n**Parameters**:\n- `owner: String` - Address of the owner to remove\n\n**Security**: Only callable by existing owners. Ensures owner exists before removal.\n\n**Example**:\n```json\n{\n  \"remove_owner\": {\n    \"owner\": \"paloma1oldowner...\"\n  }\n}\n```\n\n#### `query` - GetState\n**Purpose**: Retrieves the current contract state.\n\n**Parameters**: None\n\n**Returns**: Contract state including owner addresses.\n\n**Example**:\n```json\n{\n  \"get_state\": {}\n}\n```\n\n### Manager Contract Functions\n\n#### `instantiate`\n**Purpose**: Initializes the Manager contract with owner addresses and retry delay.\n\n**Parameters**:\n- `retry_delay: u64` - Delay between retry attempts for failed operations\n- `owners: Vec\u003cString\u003e` - List of owner addresses\n\n**Security**: Only callable during contract deployment.\n\n**Example**:\n```json\n{\n  \"retry_delay\": 3600,\n  \"owners\": [\"paloma1abc...\", \"paloma1def...\"]\n}\n```\n\n#### `execute` - DeployPalomaErc20\n**Purpose**: Deploys a new Paloma ERC20 token on an external chain.\n\n**Parameters**:\n- `chain_id: String` - Target chain identifier\n- `paloma_denom: String` - Paloma denomination (e.g., \"uluna\")\n- `name: String` - Token name\n- `symbol: String` - Token symbol\n- `decimals: u8` - Token decimal places\n- `blueprint: String` - EVM address of the token blueprint contract\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"deploy_paloma_erc20\": {\n    \"chain_id\": \"ethereum\",\n    \"paloma_denom\": \"uluna\",\n    \"name\": \"Luna Token\",\n    \"symbol\": \"LUNA\",\n    \"decimals\": 18,\n    \"blueprint\": \"0x1234567890abcdef...\"\n  }\n}\n```\n\n#### `execute` - Exchange\n**Purpose**: Executes token swaps via external DEX routers (same as Collector).\n\n**Parameters**: Same as Collector's Exchange function.\n\n**Security**: Only callable by contract owners.\n\n#### `execute` - SendToken\n**Purpose**: Sends tokens to an external chain.\n\n**Parameters**:\n- `chain_id: String` - Target chain identifier\n- `token: String` - EVM address of the token contract\n- `to: String` - EVM address of the recipient\n- `amount: Uint128` - Amount of tokens to send\n- `nonce: Uint128` - Unique nonce for the transaction\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"send_token\": {\n    \"chain_id\": \"ethereum\",\n    \"token\": \"0x1234567890abcdef...\",\n    \"to\": \"0xabcdef1234567890...\",\n    \"amount\": \"1000000000000000000\",\n    \"nonce\": \"12345\"\n  }\n}\n```\n\n#### `execute` - SetChainSetting\n**Purpose**: Configures chain-specific job IDs for cross-chain operations.\n\n**Parameters**:\n- `chain_id: String` - Chain identifier\n- `compass_job_id: String` - Job ID for compass operations\n- `main_job_id: String` - Job ID for main operations\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"set_chain_setting\": {\n    \"chain_id\": \"ethereum\",\n    \"compass_job_id\": \"compass_eth_001\",\n    \"main_job_id\": \"main_eth_001\"\n  }\n}\n```\n\n#### `execute` - SetPaloma\n**Purpose**: Sets the Paloma configuration on an external chain.\n\n**Parameters**:\n- `chain_id: String` - Target chain identifier\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"set_paloma\": {\n    \"chain_id\": \"ethereum\"\n  }\n}\n```\n\n#### `execute` - UpdateCompass\n**Purpose**: Updates the compass contract address on an external chain.\n\n**Parameters**:\n- `chain_id: String` - Target chain identifier\n- `new_compass: String` - New compass contract address\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"update_compass\": {\n    \"chain_id\": \"ethereum\",\n    \"new_compass\": \"0x1234567890abcdef...\"\n  }\n}\n```\n\n#### `execute` - UpdateRefundWallet\n**Purpose**: Updates the refund wallet address on an external chain.\n\n**Parameters**:\n- `chain_id: String` - Target chain identifier\n- `new_refund_wallet: String` - New refund wallet address\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"update_refund_wallet\": {\n    \"chain_id\": \"ethereum\",\n    \"new_refund_wallet\": \"0x1234567890abcdef...\"\n  }\n}\n```\n\n#### `execute` - UpdateGasFee\n**Purpose**: Updates the gas fee configuration on an external chain.\n\n**Parameters**:\n- `chain_id: String` - Target chain identifier\n- `new_gas_fee: Uint256` - New gas fee amount\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"update_gas_fee\": {\n    \"chain_id\": \"ethereum\",\n    \"new_gas_fee\": \"20000000000000000\"\n  }\n}\n```\n\n#### `execute` - UpdateServiceFeeCollector\n**Purpose**: Updates the service fee collector address on an external chain.\n\n**Parameters**:\n- `chain_id: String` - Target chain identifier\n- `new_service_fee_collector: String` - New service fee collector address\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"update_service_fee_collector\": {\n    \"chain_id\": \"ethereum\",\n    \"new_service_fee_collector\": \"0x1234567890abcdef...\"\n  }\n}\n```\n\n#### `execute` - UpdateServiceFee\n**Purpose**: Updates the service fee amount on an external chain.\n\n**Parameters**:\n- `chain_id: String` - Target chain identifier\n- `new_service_fee: Uint256` - New service fee amount\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"update_service_fee\": {\n    \"chain_id\": \"ethereum\",\n    \"new_service_fee\": \"1000000000000000\"\n  }\n}\n```\n\n#### `execute` - UpdateConfig\n**Purpose**: Updates the contract configuration.\n\n**Parameters**:\n- `retry_delay: Option\u003cu64\u003e` - New retry delay (optional)\n\n**Security**: Only callable by contract owners.\n\n**Example**:\n```json\n{\n  \"update_config\": {\n    \"retry_delay\": 7200\n  }\n}\n```\n\n#### `execute` - AddOwner / RemoveOwner\n**Purpose**: Same as Collector contract's owner management functions.\n\n**Parameters**: Same as Collector contract.\n\n**Security**: Same as Collector contract.\n\n#### `query` - GetState\n**Purpose**: Retrieves the current contract state.\n\n**Parameters**: None\n\n**Returns**: Contract state including owner addresses and retry delay.\n\n#### `query` - GetChainSetting\n**Purpose**: Retrieves chain-specific settings.\n\n**Parameters**:\n- `chain_id: String` - Chain identifier\n\n**Returns**: Chain settings including job IDs.\n\n**Example**:\n```json\n{\n  \"get_chain_setting\": {\n    \"chain_id\": \"ethereum\"\n  }\n}\n```\n\n## Security Considerations\n\n### Access Control\n- All privileged functions require owner authentication\n- Owner management functions prevent duplicate owners and ensure existence before removal\n- No public functions that could be exploited by unauthorized users\n\n### Input Validation\n- Address validation using `deps.api.addr_validate()`\n- Nonce-based transaction management to prevent replay attacks\n- Slippage protection through `minimum_receive` and `max_spread` parameters\n\n### Cross-Chain Security\n- Chain-specific job IDs ensure operations target correct chains\n- Nonce-based transaction tracking prevents duplicate operations\n- Cancellation mechanisms for failed or stuck transactions\n\n### State Management\n- Immutable state storage using CosmWasm's storage patterns\n- Proper error handling and rollback mechanisms\n- Version tracking for contract migrations\n\n## Testing\n\n### Prerequisites\n- Rust 1.70+ and Cargo\n- Docker (for optimized builds)\n\n### Running Tests\n\nCurrently, the test modules are empty. To add and run tests:\n\n1. **Unit Tests**: Add test functions within the `#[cfg(test)]` modules in each contract\n2. **Integration Tests**: Create test files in `tests/` directory\n3. **Run Tests**: Execute the following commands:\n\n```bash\n# Run all tests\ncargo test\n\n# Run tests for specific contract\ncargo test -p collector\ncargo test -p manager\n\n# Run tests with output\ncargo test -- --nocapture\n```\n\n### Example Test Structure\n\n```rust\n#[cfg(test)]\nmod tests {\n    use super::*;\n    use cosmwasm_std::testing::{mock_dependencies, mock_env, mock_info};\n    use cosmwasm_std::{coins, Addr};\n\n    #[test]\n    fn test_instantiate() {\n        let mut deps = mock_dependencies();\n        let env = mock_env();\n        let info = mock_info(\"creator\", \u0026coins(1000, \"earth\"));\n        \n        let msg = InstantiateMsg {\n            owners: vec![\"owner1\".to_string(), \"owner2\".to_string()],\n        };\n        \n        let res = instantiate(deps.as_mut(), env, info, msg).unwrap();\n        assert_eq!(0, res.messages.len());\n    }\n\n    #[test]\n    fn test_unauthorized_access() {\n        // Test that non-owners cannot execute privileged functions\n    }\n\n    #[test]\n    fn test_owner_management() {\n        // Test adding and removing owners\n    }\n}\n```\n\n### Building Contracts\n\n```bash\n# Build all contracts\ncargo build --release\n\n# Build specific contract\ncargo build --release -p collector\ncargo build --release -p manager\n\n# Build optimized WASM (requires Docker)\n./scripts/release_build.sh\n```\n\n## Deployment\n\n### Contract Addresses\nAfter deployment, the compiled WASM files will be available in the `artifacts/` directory:\n- `collector.wasm` - Collector contract binary\n- `manager.wasm` - Manager contract binary\n\n### Deployment Order\n1. Deploy the Manager contract first\n2. Deploy the Collector contract\n3. Configure chain settings in the Manager contract\n4. Set up owner permissions\n\n## Dependencies\n\n- **cosmwasm-std**: Core CosmWasm standard library\n- **cosmwasm-schema**: Schema generation for messages\n- **cw-storage-plus**: Enhanced storage utilities\n- **ethabi**: Ethereum ABI encoding/decoding\n- **cw-multi-test**: Testing framework\n\n## License\n\nThis project is licensed under the terms specified in the LICENSE file.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolumefi%2Ftoken-purchaser-cw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvolumefi%2Ftoken-purchaser-cw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolumefi%2Ftoken-purchaser-cw/lists"}