{"id":25626975,"url":"https://github.com/volumefi/pusd-manager-vyper","last_synced_at":"2026-02-09T17:02:43.497Z","repository":{"id":278403970,"uuid":"914445153","full_name":"VolumeFi/pusd-manager-vyper","owner":"VolumeFi","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-04T21:26:09.000Z","size":60,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-26T22:18:04.433Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Vyper","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-01-09T15:59:32.000Z","updated_at":"2025-07-04T21:26:12.000Z","dependencies_parsed_at":"2025-02-19T16:24:29.975Z","dependency_job_id":"6ef97409-b774-421e-967e-3e6bf68352fa","html_url":"https://github.com/VolumeFi/pusd-manager-vyper","commit_stats":null,"previous_names":["volumefi/pusd-manager-vyper"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/VolumeFi/pusd-manager-vyper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2Fpusd-manager-vyper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2Fpusd-manager-vyper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2Fpusd-manager-vyper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2Fpusd-manager-vyper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VolumeFi","download_url":"https://codeload.github.com/VolumeFi/pusd-manager-vyper/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolumeFi%2Fpusd-manager-vyper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29273139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T13:47:44.167Z","status":"ssl_error","status_checked_at":"2026-02-09T13:47:43.721Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-02-22T17:32:06.712Z","updated_at":"2026-02-09T17:02:43.482Z","avatar_url":"https://github.com/VolumeFi.png","language":"Vyper","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pUSD Manager Vyper\n\nThe pUSD Manager Vyper is a smart contract system implemented in Vyper for managing pUSD, a stablecoin in the VolumeFi ecosystem. This contract facilitates the minting, burning, and overall management of pUSD tokens, ensuring stability and security within the decentralized finance (DeFi) space.\n\n## Overview\n\nThis repository contains the Vyper implementation of the pUSD Manager contract system, consisting of four main contracts:\n\n1. **`pusd_manager.vy`** - Main pUSD manager contract for Ethereum mainnet\n2. **`pusd_manager_xdai.vy`** - pUSD manager contract for xDai network\n3. **`pusd_connector.vy`** - Connector contract for cross-chain operations\n4. **`purchaser.vy`** - Bonding curve trader contract\n\n## Contract Architecture\n\n### Core Contracts\n\n#### 1. pUSD Manager (`pusd_manager.vy`)\n\nThe main contract responsible for managing pUSD token operations on Ethereum mainnet.\n\n**Key State Variables:**\n- `ASSET`: The underlying asset address (e.g., WETH)\n- `Pool`: AAVE Pool V3 address for yield generation\n- `GOV`: Governance address for fee collection\n- `compass_evm`: Cross-chain bridge contract address\n- `redemption_fee`: Fee charged on withdrawals (in basis points)\n- `total_supply`: Total amount of underlying asset deposited\n\n**Functions:**\n\n##### `__init__(_compass_evm: address, _initial_asset: address, _pool: address, _aggregator: address, _exponent: uint256, _governance: address, _refund_wallet: address, _router02: address, _redepmtion_fee: uint256)`\n- **Purpose**: Constructor function that initializes the contract\n- **Parameters**:\n  - `_compass_evm`: Cross-chain bridge contract address\n  - `_initial_asset`: Underlying asset token address\n  - `_pool`: AAVE Pool V3 address\n  - `_aggregator`: Chainlink price aggregator address\n  - `_exponent`: Price exponent for gas calculations\n  - `_governance`: Governance address for fee collection\n  - `_refund_wallet`: Wallet to receive gas fee refunds\n  - `_router02`: Uniswap V3 router address\n  - `_redepmtion_fee`: Redemption fee in basis points\n- **Security**: Validates redemption fee is less than 100% (DENOMINATOR)\n- **Example Usage**:\n```vyper\n# Deploy with WETH as underlying asset\npusd_manager = PusdManager.deploy(\n    compass_evm=0x...,\n    _initial_asset=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2,  # WETH\n    _pool=0x...,\n    _aggregator=0x...,\n    _exponent=8,\n    _governance=0x...,\n    _refund_wallet=0x...,\n    _router02=0x...,\n    _redepmtion_fee=100  # 1% fee\n)\n```\n\n##### `deposit(recipient: bytes32, amount: uint256, path: Bytes[204] = b\"\", min_amount: uint256 = 0) -\u003e uint256`\n- **Purpose**: Deposits underlying asset and mints pUSD tokens\n- **Parameters**:\n  - `recipient`: Cross-chain recipient address (bytes32)\n  - `amount`: Amount of underlying asset to deposit\n  - `path`: Uniswap V3 swap path (optional)\n  - `min_amount`: Minimum output amount for swaps (optional)\n- **Returns**: Amount of pUSD tokens minted\n- **Security Features**:\n  - Non-reentrant protection\n  - Validates amount \u003e 0\n  - Handles both direct deposits and swaps\n  - Supports ETH/WETH conversion\n- **Example Usage**:\n```vyper\n# Direct WETH deposit\npusd_amount = pusd_manager.deposit(\n    recipient=0x1234...,\n    amount=1000000000000000000,  # 1 WETH\n    value=1000000000000000000\n)\n\n# Swap USDC to WETH then deposit\npusd_amount = pusd_manager.deposit(\n    recipient=0x1234...,\n    amount=1000000,  # 1 USDC\n    path=encode_path(USDC, WETH),\n    min_amount=990000000000000000  # 0.99 WETH minimum\n)\n```\n\n##### `withdraw(sender: bytes32, recipient: address, amount: uint256, nonce: uint256)`\n- **Purpose**: Withdraws underlying asset by burning pUSD tokens\n- **Parameters**:\n  - `sender`: Cross-chain sender address (bytes32)\n  - `recipient`: Ethereum address to receive withdrawn assets\n  - `amount`: Amount of pUSD tokens to burn\n  - `nonce`: Unique withdrawal nonce to prevent replay attacks\n- **Security Features**:\n  - Paloma bridge authentication\n  - Nonce replay protection\n  - Redemption fee calculation\n  - Gas fee deduction\n  - Validates recipient != compass_evm\n- **Example Usage**:\n```vyper\n# Called by compass bridge\npusd_manager.withdraw(\n    sender=0x1234...,\n    recipient=0xabcd...,\n    amount=1000000000000000000,  # 1 pUSD\n    nonce=12345\n)\n```\n\n##### `update_compass(new_compass: address)`\n- **Purpose**: Updates the compass bridge contract address\n- **Parameters**:\n  - `new_compass`: New compass contract address\n- **Security**: Only callable by current compass contract when SLC is unavailable\n- **Example Usage**:\n```vyper\npusd_manager.update_compass(0xnew_compass_address)\n```\n\n##### `update_refund_wallet(_new_refund_wallet: address)`\n- **Purpose**: Updates the refund wallet address\n- **Parameters**:\n  - `_new_refund_wallet`: New refund wallet address\n- **Security**: Requires paloma bridge authentication\n- **Example Usage**:\n```vyper\npusd_manager.update_refund_wallet(0xnew_refund_wallet)\n```\n\n##### `update_redemption_fee(_new_redemption_fee: uint256)`\n- **Purpose**: Updates the redemption fee percentage\n- **Parameters**:\n  - `_new_redemption_fee`: New redemption fee in basis points\n- **Security**: \n  - Requires paloma bridge authentication\n  - Validates fee \u003c 100% (DENOMINATOR)\n- **Example Usage**:\n```vyper\npusd_manager.update_redemption_fee(200)  # 2% fee\n```\n\n##### `set_paloma()`\n- **Purpose**: Sets the paloma identifier for cross-chain operations\n- **Security**: \n  - Only callable by compass contract\n  - Can only be set once (paloma must be empty)\n  - Requires specific message data length\n- **Example Usage**:\n```vyper\npusd_manager.set_paloma()  # Called by compass with paloma data\n```\n\n#### 2. pUSD Manager xDai (`pusd_manager_xdai.vy`)\n\nSimilar to the main pUSD manager but optimized for xDai network without price oracle dependencies.\n\n**Key Differences:**\n- No Chainlink price aggregator integration\n- Simplified gas fee calculation (no price conversion)\n- Direct WXDAI handling\n\n**Functions:** Same as main pUSD manager except for simplified gas calculations in `withdraw()`.\n\n#### 3. pUSD Connector (`pusd_connector.vy`)\n\nConnector contract that handles cross-chain pUSD operations and fee collection.\n\n**Key State Variables:**\n- `pusd_manager`: Address of the pUSD manager contract\n- `pusd`: pUSD token address\n- `withdraw_limit`: Minimum withdrawal amount\n- `gas_fee`: Gas fee in ETH\n- `service_fee`: Service fee percentage\n\n**Functions:**\n\n##### `__init__(_compass: address, _pusd_manager: address, _pusd: address, _withdraw_limit: uint256, _weth9: address, _refund_wallet: address, _gas_fee: uint256, _service_fee_collector: address, _service_fee: uint256)`\n- **Purpose**: Constructor for connector contract\n- **Parameters**:\n  - `_compass`: Cross-chain bridge address\n  - `_pusd_manager`: pUSD manager contract address\n  - `_pusd`: pUSD token address\n  - `_withdraw_limit`: Minimum withdrawal amount\n  - `_weth9`: WETH token address\n  - `_refund_wallet`: Gas fee refund wallet\n  - `_gas_fee`: Gas fee amount\n  - `_service_fee_collector`: Service fee collector address\n  - `_service_fee`: Service fee percentage\n- **Example Usage**:\n```vyper\nconnector = PusdConnector.deploy(\n    _compass=0x...,\n    _pusd_manager=pusd_manager.address,\n    _pusd=pusd_token.address,\n    _withdraw_limit=1000000000000000000,  # 1 pUSD\n    _weth9=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2,\n    _refund_wallet=0x...,\n    _gas_fee=10000000000000000,  # 0.01 ETH\n    _service_fee_collector=0x...,\n    _service_fee=50000000000000000  # 5%\n)\n```\n\n##### `purchase(path: Bytes[204], amount: uint256, min_amount: uint256 = 0)`\n- **Purpose**: Purchases pUSD tokens with any supported asset\n- **Parameters**:\n  - `path`: Uniswap V3 swap path\n  - `amount`: Amount of input token\n  - `min_amount`: Minimum output amount for swaps\n- **Security Features**:\n  - Non-reentrant protection\n  - Gas fee deduction\n  - Service fee collection\n  - Supports ETH/WETH conversion\n- **Example Usage**:\n```vyper\n# Purchase pUSD with USDC\nconnector.purchase(\n    path=encode_path(USDC, WETH),\n    amount=1000000,  # 1 USDC\n    min_amount=990000000000000000,  # 0.99 WETH minimum\n    value=10000000000000000  # 0.01 ETH gas fee\n)\n```\n\n##### `withdraw(amount: uint256)`\n- **Purpose**: Initiates cross-chain withdrawal of pUSD tokens\n- **Parameters**:\n  - `amount`: Amount of pUSD to withdraw\n- **Security Features**:\n  - Validates withdrawal limit\n  - Checks total supply availability\n  - Gas and service fee handling\n- **Example Usage**:\n```vyper\nconnector.withdraw(\n    amount=1000000000000000000,  # 1 pUSD\n    value=10000000000000000  # 0.01 ETH gas fee\n)\n```\n\n#### 4. Purchaser (`purchaser.vy`)\n\nBonding curve trader contract for pUSD token trading.\n\n**Functions:**\n\n##### `purchase(to_token: address, path: Bytes[204], amount: uint256, min_amount: uint256 = 0)`\n- **Purpose**: Purchases pUSD and sends to specified token on another chain\n- **Parameters**:\n  - `to_token`: Token address on destination chain\n  - `path`: Swap path for input token\n  - `amount`: Amount of input token\n  - `min_amount`: Minimum output amount\n- **Example Usage**:\n```vyper\npurchaser.purchase(\n    to_token=0x...,\n    path=encode_path(USDC, WETH),\n    amount=1000000,\n    min_amount=990000000000000000,\n    value=10000000000000000\n)\n```\n\n##### `sell(from_token: address, amount: uint256)`\n- **Purpose**: Sells tokens and sends pUSD to another chain\n- **Parameters**:\n  - `from_token`: Token to sell\n  - `amount`: Amount to sell\n- **Example Usage**:\n```vyper\npurchaser.sell(\n    from_token=0x...,\n    amount=1000000000000000000,\n    value=10000000000000000\n)\n```\n\n##### `purchase_by_pusd(to_token: address, pusd: address, amount: uint256)`\n- **Purpose**: Purchases tokens using existing pUSD balance\n- **Parameters**:\n  - `to_token`: Token address on destination chain\n  - `pusd`: pUSD token address\n  - `amount`: Amount of pUSD to use\n- **Example Usage**:\n```vyper\npurchaser.purchase_by_pusd(\n    to_token=0x...,\n    pusd=pusd_token.address,\n    amount=1000000000000000000,\n    value=10000000000000000\n)\n```\n\n## Security Considerations\n\n### Access Control\n- **Governance**: Only governance address can receive fees\n- **Compass Bridge**: Cross-chain operations require compass authentication\n- **Paloma Verification**: All cross-chain calls verify paloma identifier\n\n### Reentrancy Protection\n- All external functions use `@nonreentrant` decorator\n- State changes occur before external calls where possible\n\n### Input Validation\n- Amount validation (must be \u003e 0)\n- Address validation (recipient != compass_evm)\n- Fee validation (redemption_fee \u003c 100%)\n- Nonce replay protection\n\n### Gas Optimization\n- Efficient storage usage with immutable variables\n- Minimal external calls\n- Optimized math operations\n\n## Testing\n\n### Prerequisites\n\nTo run tests, ensure you have the following installed:\n\n- [Python 3.8+](https://www.python.org/downloads/)\n- [Ape Framework](https://docs.apeworx.io/ape/stable/userguides/quickstart.html)\n- [Vyper Compiler](https://vyper.readthedocs.io/en/stable/installing-vyper.html)\n\n### Installation\n\n1. **Clone the Repository**:\n   ```bash\n   git clone https://github.com/VolumeFi/pusd-manager-vyper.git\n   cd pusd-manager-vyper\n   ```\n\n2. **Set Up Virtual Environment**:\n   ```bash\n   python3 -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n\n3. **Install Ape Framework**:\n   ```bash\n   pip install eth-ape\n   ```\n\n### Running Tests\n\n1. **Compile Contracts**:\n   ```bash\n   ape compile\n   ```\n\n2. **Run All Tests**:\n   ```bash\n   ape test\n   ```\n\n3. **Run Tests with Verbose Output**:\n   ```bash\n   ape test -v\n   ```\n\n4. **Run Specific Test File**:\n   ```bash\n   ape test tests/test_pusd_manager.py\n   ```\n\n5. **Run Tests with Coverage**:\n   ```bash\n   ape test --coverage\n   ```\n\n6. **Run Tests on Specific Network**:\n   ```bash\n   ape test --network ethereum:mainnet:alchemy\n   ```\n\n### Test Structure\n\nCreate a `tests/` directory with the following structure:\n\n```\ntests/\n├── conftest.py          # Test fixtures and setup\n├── test_pusd_manager.py # Main pUSD manager tests\n├── test_connector.py    # Connector contract tests\n└── test_purchaser.py    # Purchaser contract tests\n```\n\n### Example Test File\n\n```python\n# tests/test_pusd_manager.py\nimport pytest\nfrom ape import accounts, Contract\n\n@pytest.fixture\ndef owner(accounts):\n    return accounts[0]\n\n@pytest.fixture\ndef user(accounts):\n    return accounts[1]\n\n@pytest.fixture\ndef pusd_manager(owner, project):\n    return owner.deploy(project.PusdManager, \n                       _compass_evm=\"0x...\",\n                       _initial_asset=\"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2\",\n                       _pool=\"0x...\",\n                       _aggregator=\"0x...\",\n                       _exponent=8,\n                       _governance=owner.address,\n                       _refund_wallet=\"0x...\",\n                       _router02=\"0x...\",\n                       _redepmtion_fee=100)\n\ndef test_deposit(pusd_manager, user):\n    \"\"\"Test pUSD deposit functionality\"\"\"\n    amount = 1000000000000000000  # 1 WETH\n    \n    # User deposits WETH\n    tx = pusd_manager.deposit(\n        recipient=b\"0x1234\",\n        amount=amount,\n        sender=user,\n        value=amount\n    )\n    \n    # Verify deposit event\n    assert tx.events[0].sender == user.address\n    assert tx.events[0].amount == amount\n\ndef test_withdraw(pusd_manager, owner):\n    \"\"\"Test pUSD withdrawal functionality\"\"\"\n    # Mock compass call\n    pusd_manager.withdraw(\n        sender=b\"0x1234\",\n        recipient=owner.address,\n        amount=1000000000000000000,\n        nonce=1,\n        sender=owner\n    )\n```\n\n## Deployment\n\n### Mainnet Deployment\n\n1. **Configure Environment**:\n   ```bash\n   export PRIVATE_KEY=\"your_private_key\"\n   export ALCHEMY_API_KEY=\"your_alchemy_key\"\n   ```\n\n2. **Deploy Contracts**:\n   ```bash\n   ape run scripts/deploy.py --network ethereum:mainnet:alchemy\n   ```\n\n### Testnet Deployment\n\n```bash\nape run scripts/deploy.py --network ethereum:goerli:alchemy\n```\n\n## Contributing\n\nWe welcome contributions to enhance the pUSD Manager Vyper contract. To contribute:\n\n1. **Fork the Repository**: Click on the 'Fork' button at the top right corner of this page.\n2. **Create a New Branch**: Use a descriptive name for your branch.\n3. **Make Your Changes**: Implement your feature or fix.\n4. **Add Tests**: Ensure all new functionality has corresponding tests.\n5. **Submit a Pull Request**: Provide a clear description of your changes and the problem they solve.\n\nPlease ensure that your contributions adhere to our coding standards and include appropriate tests.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Acknowledgements\n\nWe extend our gratitude to the VolumeFi community and all contributors who have supported the development of the pUSD Manager Vyper contract.\n\n---\n\nThis README provides comprehensive documentation for security auditors, including detailed function descriptions, security considerations, usage examples, and testing instructions. For more detailed information about specific implementations, please refer to the contract source code. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolumefi%2Fpusd-manager-vyper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvolumefi%2Fpusd-manager-vyper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolumefi%2Fpusd-manager-vyper/lists"}