{"id":51892065,"url":"https://github.com/circlefin/evm-xreserve-contracts","last_synced_at":"2026-07-26T05:01:43.672Z","repository":{"id":365788818,"uuid":"1096491043","full_name":"circlefin/evm-xreserve-contracts","owner":"circlefin","description":"Official repository for all EVM-compatible smart contracts used by Circle XReserve","archived":false,"fork":false,"pushed_at":"2026-06-18T21:31:03.000Z","size":1427,"stargazers_count":2,"open_issues_count":4,"forks_count":12,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-18T23:19:26.776Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Solidity","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/circlefin.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-14T14:01:38.000Z","updated_at":"2026-06-18T21:31:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/circlefin/evm-xreserve-contracts","commit_stats":null,"previous_names":["circlefin/evm-xreserve-contracts"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/circlefin/evm-xreserve-contracts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circlefin%2Fevm-xreserve-contracts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circlefin%2Fevm-xreserve-contracts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circlefin%2Fevm-xreserve-contracts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circlefin%2Fevm-xreserve-contracts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/circlefin","download_url":"https://codeload.github.com/circlefin/evm-xreserve-contracts/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circlefin%2Fevm-xreserve-contracts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35901460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-26T02:00:06.503Z","response_time":89,"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":"2026-07-26T05:01:43.600Z","updated_at":"2026-07-26T05:01:43.666Z","avatar_url":"https://github.com/circlefin.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Circle xReserve Contracts\n\n## Overview\n\n**xReserve** is an interoperability infrastructure that lets blockchain teams deploy USDC-backed tokens on their own chains. It is powered by programmatic attestations and Circle-deployed smart contracts that hold USDC in reserve on source chains such as Ethereum. USDC-backed tokens deployed through xReserve are interoperable with each other and with the broader USDC network.\n\n### Key Features\n\n- **Cross-Domain Deposits**: Users deposit assets into the xReserve contract to initiate cross-domain transfers\n- **Attestation-Based Minting**: xReserve's off-chain systems observe deposits and generate cryptographic attestations that authorize token minting on remote domains\n- **Secure Withdrawals**: Users can burn reserved tokens on remote domains and withdraw the underlying assets from the reserve using multi-party attestations\n- **Multi-Protocol Integration**: Seamlessly integrates with Circle's existing infrastructure including Gateway Minter, Gateway Wallet, and CCTP Token Messenger\n- **Upgradeable Architecture**: Built using UUPS upgradeable proxy pattern for future extensibility\n\nThis repository contains the complete smart contract codebase for xReserve, including deployment scripts, comprehensive test suites, and development tooling.\n\n## 🚀 Getting Started\n\n### 1. Clone the repo and initialize submodules\n\n```bash\ngit clone \u003cyour-repo-url\u003e\ncd evm-xreserve-contracts\n```\n\n### 2. Install dependencies\n\n```bash\nyarn install \u0026\u0026 yarn postinstall\n```\n\n\u003e Ensure you're using Yarn **v4.7.0** or higher (`yarn --version`)\n\n### 3. Install Foundry (if not already)\n\n```bash\ncurl -L https://foundry.paradigm.xyz | bash\nfoundryup --install 1.0.0\n```\n\n## 🛠 Build \u0026 Test\n\n```bash\nyarn build     # Compiles all contracts\nyarn test      # Runs Foundry tests locally\nyarn test:all  # Runs Foundry tests locally and on forked networks\nyarn test:gas  # Includes gas reporting\n```\n\n## 🧹 Lint \u0026 Format\n\n```bash\nyarn lint         # Lint Solidity sources with Solhint\nyarn lint:fix     # Auto-fix fixable lint issues\nyarn format       # Check formatting using forge fmt\nyarn format:fix   # Format all contracts\n```\n\n## 🗂 Repository Structure\n\n### src/\nPrimary source code directory containing all smart contract implementations, interfaces, and libraries.\n\n### test/\nContains all unit and integration tests, written using Foundry's testing framework.\n\n### deploy-contracts/\nDeployment and utility scripts for deploying and verifying contracts.\n\n## Mining CREATE2 Salts for xReserve Proxy\n\nTo produce vanity prefixes for the xReserve proxy address, you can simulate deployments to obtain the proxy initCodeHash, then mine a `reserveProxySalt` that yields the desired prefix.\n\n### Prefixes\n\n| Environment | Network Type | xReserve Proxy Prefix | Notes |\n|:------------------------:|:------------------------:|:------------------------:|:------------------------:|\n| Production | Mainnet | 0x8888888 |  |\n| Production | Testnet | 0x0088888 | Add zero byte to mainnet addresses |\n| Staging | Testnet | 0x5588888 | 5 = \"S\" for Staging |\n\n### Step 1: Simulate to obtain initCodeHash\n\nSet `ENV` and `RPC_URL` (and `LOCAL_CREATE2_FACTORY_ADDRESS` if using LOCAL). Use any values for other environment variables; they do not affect the init code hash.\n\nRun the deployment script in simulation mode (no broadcast) and capture the init code hash printed when the proxy bytecode is prepared:\n\n```bash\nENV=$ENV forge script script/001_DeployXReserve.sol --rpc-url $RPC_URL -vv\n```\n\nLook for a log like \"initCodeHash for proxy address ... below:\" followed by a `bytes32` value. Copy that value and export it:\n\n```bash\nexport XRESERVE_PROXY_INIT_CODE_HASH=\u003cbytes32 from logs\u003e\n```\n\nAlso export the factory used for mining (use the value from `000_Constants.sol` for your environment, or `LOCAL_CREATE2_FACTORY_ADDRESS` when LOCAL):\n\n```bash\nexport SALT_MINE_CREATE2_FACTORY_ADDRESS=\u003cfactory address\u003e\n```\n\nEnsure `ENV` is set as well (see `.env`):\n\n```bash\nexport ENV=\u003cMAINNET_PROD|TESTNET_PROD|TESTNET_STAGING|LOCAL\u003e\n```\n\n### Step 2: Mine the salt\n\nRun the script to mine a salt that yields the environment-specific prefix:\n\n```bash\nyarn mine-salts\n```\n\nThe command prints candidate salts. Pick one and update the corresponding constant in `script/000_Constants.sol`:\n\n- `TESTNET_STAGING_RESERVE_PROXY_SALT`\n- `TESTNET_PROD_RESERVE_PROXY_SALT`\n- `MAINNET_PROD_RESERVE_PROXY_SALT`\n\n### Step 3: Verify the prefix\n\nRe-run the simulation to confirm that the xReserve proxy address matches the desired prefix for your environment.\n\nNote: For verification, only ENV and RPC_URL (and LOCAL_CREATE2_FACTORY_ADDRESS/LOCAL_DEPLOYER_ADDRESS if ENV=LOCAL) will matter for the proxy's address. The other variables can be set to any value.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirclefin%2Fevm-xreserve-contracts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcirclefin%2Fevm-xreserve-contracts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirclefin%2Fevm-xreserve-contracts/lists"}