refactor: change brand to imua (#150)

* feat: add bech32 precompile interface * refactor: rebrand exo -> imua * fix: respond to AI comments * chore(lint): remove unused import * fix build * fix: replace strings with errors * fix(ci): attempt to temp fix storage layout ci * Revert the last commit. This reverts commit a6cc2eb. Even if extraction works, the layout code is running from the base branch so it will complain anyway * fix: remove Solana config in handler * fix(ci): use the correct contracts * update create3 factory with address use imua fork * remove blank lines * add deterministic library * deploy bootstrap proxy using create3 * chore: forge fmt * update deployment on sepolia holesky is down * fix comment in src/storage * fix(ci): correct comment * fix(config): remove library from test config * feat: deploy imua gateway with salt * use correct (create2-derived) addr of create3 * add imua deployment addrs * doc: remove old exo links * remove old chain-id from comment
imua-xyz · Feb 27, 2025 · 308cd8c · 308cd8c
1 parent 992a94a
commit 308cd8c
Show file tree

Hide file tree

Showing 121 changed files with 1,919 additions and 1,759 deletions.
diff --git a/.env.example b/.env.example
@@ -1,21 +1,21 @@
 # anvil --port 8646 or via docker compose up in eth-pos-devnet
 CLIENT_CHAIN_RPC=http://localhost:8646
-EXOCORE_TESTNET_RPC=http://localhost:8545
-EXOCORE_LOCAL_RPC=http://localhost:8545
+IMUACHAIN_TESTNET_RPC=http://localhost:8545
+IMUACHAIN_LOCALNET_RPC=http://localhost:8545
 # The following are default Anvil keys - not real keys!
 TEST_ACCOUNT_ONE_PRIVATE_KEY=0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d
 TEST_ACCOUNT_THREE_PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
 TEST_ACCOUNT_FOUR_PRIVATE_KEY=0x7c852118294e51e653712a81e05800f419141751be58f605c371e15141b007a6
 
-# Use 'exocored keys unsafe-export-eth-key "dev0" --home ~/.tmp-exocored' to get the privatekey
-EXOCORE_GENESIS_PRIVATE_KEY=0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a
+# Use 'imuad keys unsafe-export-eth-key "dev0" --home ~/.tmp-imuad' to get the privatekey
+IMUACHAIN_GENESIS_PRIVATE_KEY=0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a
 
 USE_ENDPOINT_MOCK=false
-USE_EXOCORE_PRECOMPILE_MOCK=false
+USE_IMUACHAIN_PRECOMPILE_MOCK=false
 
 # For contract verification
 ETHERSCAN_API_KEY=
-EXOCORE_TESTNET_EXPLORER=
+IMUACHAIN_TESTNET_EXPLORER=
 
 # These are used for integration testing the Bootstrap contract, in addition to
 # CLIENT_CHAIN_RPC and BEACON_CHAIN_ENDPOINT above.

diff --git a/.github/workflows/forge-ci.yml b/.github/workflows/forge-ci.yml
@@ -196,21 +196,25 @@ jobs:
           # however, we cannot do that in the PR context without leaking the
           # Etherscan API key.
 
-          # Note that the keys of the json dict below are case sensitive and
-          # must match the keys `x.deployed.json` defined in `compareLayouts.js`
-          # exactly.
+          # Note that
+          # (0) we use the logic addresses to match the comparison code: eg. Bootstrap is
+          #     compared against BootstrapLogic instead of Bootstrap because Bootstrap is
+          #     a proxy contract that points to the logic contract.
+          # (1) keys of the input json dict below are sourced from `deployedContracts.json`
+          # (2) keys of the output json dict below are case sensitive and must match the
+          #     keys `x.deployed.json` defined in `compareLayouts.js` exactly.
           jq -n \
-            --arg bootstrap "$bootstrap" \
-            --arg clientGateway "$clientGateway" \
-            --arg vault "$vault" \
-            --arg rewardVault "$rewardVault" \
-            --arg capsule "$capsule" \
+            --arg bootstrap "$bootstrapLogic" \
+            --arg clientGateway "$clientGatewayLogic" \
+            --arg vault "$vaultImplementation" \
+            --arg rewardVault "$rewardVaultImplementation" \
+            --arg capsule "$capsuleImplementation" \
             '{
               Bootstrap: $bootstrap,
               ClientChainGateway: $clientGateway,
               Vault: $vault,
               RewardVault: $rewardVault,
-              ExoCapsule: $capsule
+              ImuaCapsule: $capsule
             }' > validatedContracts.json
 
           echo "Validation passed: All fields are non-empty and valid Ethereum checksum addresses"
@@ -231,7 +235,7 @@ jobs:
     strategy:
       matrix:
         include:
-          - contract: ExocoreGateway
+          - contract: ImuachainGateway
             base: true
           - contract: Bootstrap
             base: false
@@ -241,9 +245,9 @@ jobs:
             base: false
           - contract: Vault
             base: false
-          - contract: ExocoreGateway
+          - contract: ImuachainGateway
             base: false
-          - contract: ExoCapsule
+          - contract: ImuaCapsule
             base: false
     steps:
       - name: Restore cached Foundry toolchain

diff --git a/.gitmodules b/.gitmodules
@@ -27,4 +27,4 @@
 	url = https://github.com/safe-global/safe-smart-account
 [submodule "lib/create3-factory"]
 	path = lib/create3-factory
-	url = https://github.com/zeframlou/create3-factory
+	url = https://github.com/imua-xyz/create3-factory
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
-# Exocore Contracts
+# Imua Contracts
 
-The Exocore contracts repository contains a set of smart contracts deployed on both Exocore and the target client chains, which facilitate assets deposit and withdrawal, cross-chain communication, and restaking operations for native assets and liquid staking tokens (LSTs), ensuring secure interactions and efficient management of restaked assets.
+The imua-contracts repository contains a set of smart contracts deployed on both Imuachain and the target client chains, which facilitate assets deposit and withdrawal, cross-chain communication, and restaking operations for native assets and liquid staking tokens (LSTs), ensuring secure interactions and efficient management of restaked assets.
 
 ## Getting Started
 
@@ -12,7 +12,7 @@ The Exocore contracts repository contains a set of smart contracts deployed on b
 
 ### Basics
 
-Our docs site is [here](https://docs.exocore.network/components/smart-contracts). It contains tutorials, explainers, and smart contract documentation. If you'd like to view these docs on github instead, check out [the docs](/docs) repo:
+Our docs site is [here](https://docs.imua.xyz/components/smart-contracts). It contains tutorials, explainers, and smart contract documentation. If you'd like to view these docs on github instead, check out [the docs](/docs) repo:
 
 - [Contracts summary](./docs/summary.md)
 - [Architecture diagrams](/docs/architecture.svg)
@@ -31,7 +31,7 @@ This repository utilizes Foundry. For more information on installation and usage
 ```
 foundryup
 
-git clone --recurse-submodules git@github.com:ExocoreNetwork/exocore-contracts.git && cd exocore-contracts
+git clone --recurse-submodules git@github.com:imua-xyz/imua-contracts.git && cd imua-contracts
 
 forge build
 
@@ -69,14 +69,8 @@ Deposit & Withdraw e2e test:
 
 ### Current Testnet Deployment
 
-The current main deployment is our v1.0.0 release. You can view the deployed contract addresses below, or check out the code itself on the [`main`](https://github.com/ExocoreNetwork/exocore-contracts/tree/main) branch.
+You can view the deployed contract addresses below, or check out the code itself on the [`main`](https://github.com/imua-xyz/imua-contracts/tree/main) branch.
 
-###### Core
+#### Core
 
-| Name | Proxy | Implementation | Notes |
-| -------- | -------- | -------- | -------- |
-| [`ClientChainGateway`](https://github.com/ExocoreNetwork/exocore-contracts/blob/main/src/contracts/core/ClientChainGateway.sol) | [`0xe9591d5b1ea9733ad36834cd0bde40ce0028ae33`](https://sepolia.etherscan.io/address/0xe9591d5b1ea9733ad36834cd0bde40ce0028ae33) | [`0xdC51F6d62ce78EfF7c98f3BD59227B4D0785C6ef`](https://sepolia.etherscan.io/address/0xdC51F6d62ce78EfF7c98f3BD59227B4D0785C6ef) | Proxy: [`TUP@4.7.1`](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v4.7.1/contracts/proxy/transparent/TransparentUpgradeableProxy.sol) |
-| [`ExocoreGateway`](https://github.com/ExocoreNetwork/exocore-contracts/blob/main/src/contracts/core/ExocoreGateway.sol) | [`0xe13Ef2fE9B4bC1A3bBB62Df6bB19d6aD79525036`](https://exoscan.org/address/0xe13Ef2fE9B4bC1A3bBB62Df6bB19d6aD79525036) | [`0xe13Ef2fE9B4bC1A3bBB62Df6bB19d6aD79525036`](https://exoscan.org/address/0xe13Ef2fE9B4bC1A3bBB62Df6bB19d6aD79525036) | Proxy: - |
-| [`TokenVault`](https://github.com/ExocoreNetwork/exocore-contracts/blob/main/src/contracts/core/Vault.sol) | [`0x0F4760CCab936a8fb0C9459dba2a739B22059b5f`](https://sepolia.etherscan.io/address/0x0F4760CCab936a8fb0C9459dba2a739B22059b5f) | [`0xF22097E6799DF7D8b25CCeF6E64DA3CB9133012D`](https://sepolia.etherscan.io/address/0xF22097E6799DF7D8b25CCeF6E64DA3CB9133012D) | Proxy: [`TUP@4.7.1`](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v4.7.1/contracts/proxy/transparent/TransparentUpgradeableProxy.sol) |
-| [`Bootstrap`](https://github.com/ExocoreNetwork/exocore-contracts/blob/main/src/contracts/core/Bootstrap.sol) | [`0x53E91EB5105ec8C1c22055F790616cB8F82c664e`](https://sepolia.etherscan.io/address/0x53E91EB5105ec8C1c22055F790616cB8F82c664e) | [`0x417CaBa1E4a63D1202dCc6E19F7c3eC79b31EC45`](https://sepolia.etherscan.io/address/0x417CaBa1E4a63D1202dCc6E19F7c3eC79b31EC45) | Proxy: [`TUP@4.7.1`](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v4.7.1/contracts/proxy/transparent/TransparentUpgradeableProxy.sol) |
-| [`LzEndpoint`](https://github.com/ExocoreNetwork/exocore-contracts/blob/main/src/contracts/core/Bootstrap.sol) | [`0x6EDCE65403992e310A62460808c4b910D972f10f`](https://sepolia.etherscan.io/address/0x6EDCE65403992e310A62460808c4b910D972f10f) | [`0x6EDCE65403992e310A62460808c4b910D972f10f`](https://sepolia.etherscan.io/address/0x6EDCE65403992e310A62460808c4b910D972f10f) | Proxy: [`TUP@4.7.1`](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v4.7.1/contracts/proxy/transparent/TransparentUpgradeableProxy.sol) |
+For the latest deployment addresses, see [script/deployments/deployedContracts.json](./script/deployments/deployedContracts.json).
diff --git a/docs/ClientChainGateway.md b/docs/ClientChainGateway.md
@@ -1,6 +1,6 @@
 # ClientChainGateway Documentation
 
-The ClientChainGateway serves as the primary interface for stakers to interact with the Exocore network. It functions as a LayerZero application capable of cross-chain messaging and manages both Vault and Capsule contracts.
+The ClientChainGateway serves as the primary interface for stakers to interact with Imua. It functions as a LayerZero application capable of cross-chain messaging and manages both Vault and Capsule contracts.
 
 ## Overview
 
@@ -12,10 +12,10 @@ ClientChainGateway implements two types of restaking:
 
 ### Deposit Operations
 - `deposit(address token, uint256 amount)`
-  - Deposits whitelisted tokens into Exocore
+  - Deposits whitelisted tokens into Imua
   - Locks tokens in a Vault contract
-  - Sends cross-chain message to Exocore for accounting
-  - Always considered successful on Exocore side
+  - Sends cross-chain message to Imuachain for accounting
+  - Always considered successful on Imuachain
   - Requires relay fee in ETH for cross-chain message
 
 - `depositThenDelegateTo(address token, uint256 amount, string operator)`
@@ -29,36 +29,36 @@ ClientChainGateway implements two types of restaking:
 - `delegateTo(string operator, address token, uint256 amount)`
   - Delegates previously deposited tokens to an operator
   - Requires prior deposit
-  - Sends cross-chain message to Exocore
-  - Updates delegation accounting on Exocore
+  - Sends cross-chain message to Imuachain
+  - Updates delegation accounting on Imuachain
   - Requires relay fee in ETH for cross-chain message
 
 - `undelegateFrom(string operator, address token, uint256 amount)`
   - Undelegates tokens from an operator
   - Requires prior delegation
-  - Sends cross-chain message to Exocore
+  - Sends cross-chain message to Imuachain
   - Initiates unbonding period
   - Requires relay fee in ETH for cross-chain message
 
 ### Withdrawal Operations
-- `claimPrincipalFromExocore(address token, uint256 principalAmount)`
-  - Initiates withdrawal process from Exocore
-  - Sends cross-chain message to Exocore
+- `claimPrincipalFromImuachain(address token, uint256 principalAmount)`
+  - Initiates withdrawal process from Imuachain
+  - Sends cross-chain message to Imuachain
   - Awaits response to unlock balance in Vault
   - Does not transfer tokens to user
   - Requires relay fee in ETH for cross-chain message
 
 - `withdrawPrincipal(address token, uint256 amount, address recipient)`
   - Transfers unlocked tokens from Vault to recipient
-  - Must be called after successful `claimPrincipalFromExocore`
+  - Must be called after successful `claimPrincipalFromImuachain`
   - No cross-chain message required
   - Direct transfer from Vault
   - No relay fee needed
 
 ## NST Restaking Functions
 
 ### Setup Operations
-- `createExoCapsule()`
+- `createImuaCapsule()`
   - Creates Capsule contract for staker
   - Used as withdrawal credentials
   - Required before staking to beacon chain
@@ -67,25 +67,25 @@ ClientChainGateway implements two types of restaking:
 
 - `stake(bytes pubkey, bytes signature, bytes32 depositDataRoot)`
   - Stakes ETH to Ethereum beacon chain
-  - Creates validator with ExoCapsule as withdrawal credentials
+  - Creates validator with ImuaCapsule as withdrawal credentials
   - Preparation step for NST restaking
   - Payable function accepting exactly 32 ETH for beacon chain staking
   - No relay fee needed
 
 ### Deposit Operations
 - `verifyAndDepositNativeStake(bytes32[] validatorContainer, BeaconChainProofs.ValidatorContainerProof proof)`
   - Verifies beacon chain proof of withdrawal credentials
-  - Confirms validator is using correct ExoCapsule
-  - Sends message to Exocore to account for validator balance
+  - Confirms validator is using correct ImuaCapsule
+  - Sends message to Imuachain to account for validator balance
   - Required for NST restaking activation
   - Requires relay fee in ETH for cross-chain message
 
 ### Withdrawal Operations
 - `processBeaconChainWithdrawal(bytes32[] validatorContainer, BeaconChainProofs.ValidatorContainerProof validatorProof, bytes32[] withdrawalContainer, BeaconChainProofs.WithdrawalProof withdrawalProof)`
   - Processes beacon chain withdrawals
   - Verifies withdrawal proofs
-  - Sends message to Exocore to unlock ETH in Capsule
-  - Similar to `claimPrincipalFromExocore` for LSTs
+  - Sends message to Imuachain to unlock ETH in Capsule
+  - Similar to `claimPrincipalFromImuachain` for LSTs
   - Requires relay fee in ETH for cross-chain message
 
 - `withdrawNonBeaconChainETHFromCapsule(address payable recipient, uint256 amountToWithdraw)`
@@ -100,18 +100,18 @@ ClientChainGateway implements two types of restaking:
 1. Call `deposit` or `depositThenDelegateTo`
 2. If using separate calls, wait for deposit confirmation
 3. Call `delegateTo` if needed
-4. Tokens are now staked and delegated on Exocore
+4. Tokens are now staked and delegated on Imua
 
 ### LST Withdrawal
-1. Call `claimPrincipalFromExocore`
+1. Call `claimPrincipalFromImuachain`
 2. Wait for cross-chain message confirmation
 3. Call `withdrawPrincipal` to receive tokens
 
 ### NST Restaking
-1. Call `createExoCapsule`
+1. Call `createImuaCapsule`
 2. Call `stake` to become validator
 3. Call `verifyAndDepositNativeStake` with proofs
-4. ETH is now restaked on Exocore
+4. ETH is now restaked on Imua
 
 ### NST Withdrawal
 1. Initiate withdrawal on beacon chain
@@ -124,4 +124,4 @@ ClientChainGateway implements two types of restaking:
 - `stake` function requires exactly 32 ETH for beacon chain staking
 - Other payable functions only accept ETH for relay fees
 - NST operations require valid beacon chain proofs
-- Delegation requires registered operators on Exocore
+- Delegation requires registered operators on Imuachain
diff --git a/docs/architecture.svg b/docs/architecture.svg
diff --git a/docs/btc-staking-e2e-testing.md b/docs/btc-staking-e2e-testing.md
@@ -16,7 +16,7 @@ This guide walks through setting up and testing the BTC staking functionality in
 1. First, clone and set up the Esplora explorer:
 
 ```bash
-git clone https://github.com/ExocoreNetwork/esplora.git
+git clone https://github.com/imua-xyz/esplora.git
 cd esplora
 ```
 
@@ -32,7 +32,7 @@ Arguments:
   amount_btc                 Amount of BTC to send to faucet (default: 100)
   mining_interval_seconds    Block mining interval in seconds (default: 30)
 
-Faucet Information(only for regtest):
+Faucet Information (only for regtest):
   Private Key: 0xee01cfc3f08cdb020064f31ff1a993aa9ecc1d38e684665742faa705685532a6
   Address:     bcrt1qvj7e5av2eqrhhvle56f9aqtjpxgywwnt5tem5y
 
@@ -42,14 +42,14 @@ Example:
 
 NOTICE: Some amount of test BTC would be sent to the faucet address with known private key
 
-### Start Exocore Node
+### Start Imuachain Node
 
-1. Set up and start the Exocore node:
+1. Set up and start the Imuachain node:
 
 ```bash
 # Clone the repository
-git clone https://github.com/ExocoreNetwork/exocore.git
-cd exocore
+git clone https://github.com/imua-xyz/imuachain.git
+cd imuachain
 
 # Switch to develop branch
 git checkout develop
@@ -63,19 +63,19 @@ git checkout develop
 1. Clone repo and set up the UTXO gateway contract:
 
 ```bash
-git clone https://github.com/ExocoreNetwork/exocore-contracts.git
-cd exocore-contracts
+git clone https://github.com/imua-xyz/imua-contracts.git
+cd imua-contracts
 npm run deploy:utxogateway
 ```
 
-Before running the deployment command, please replace the URL path of `exocore_localnet` in `hardhat.config.js` with the URL path of your set up Exocore node, and also set the private key of the Exocore account in `hardhat.config.js` in your local `.env` file. We need at least 3 accounts (`deployer` == `faucet`, `owner` and `witness1`) to execute the deployment script.
+Before running the deployment command, please replace the URL path of `imuachain_localnet` in `hardhat.config.js` with the URL path of your set up Imuachain node, and also set the private key of the Imuachain account in `hardhat.config.js` in your local `.env` file. We need at least 3 accounts (`deployer` == `faucet`, `owner` and `witness1`) to execute the deployment script.
 
 ```javascript
-exocore_localnet: {
+imuachain_localnet: {
       url: "http://127.0.0.1:8545",
       chainId: 232,
       accounts: [
-        process.env.LOCAL_EXOCORE_FUNDED_ACCOUNT_PRIVATE_KEY, // Deployer/Faucet: Requires minimum 3 eth balance
+        process.env.LOCAL_IMUACHAIN_FUNDED_ACCOUNT_PRIVATE_KEY, // Deployer/Faucet: Requires minimum 3 eth balance
         process.env.TEST_ACCOUNT_ONE_PRIVATE_KEY, // Owner: the owner of the UTXOGateway contract
         process.env.TEST_ACCOUNT_TWO_PRIVATE_KEY, // Witness1: the only witness for current implementation, also needed by bridge
         process.env.TEST_ACCOUNT_THREE_PRIVATE_KEY,
@@ -86,7 +86,7 @@ exocore_localnet: {
     }
 ```
 
-This would deploy UTXOGateway contract on exocore node and setup it:
+This would deploy UTXOGateway contract on Imuachain node and set it up:
 
 - set deployed contract as authorized gateway
 - set required proofs count
@@ -101,7 +101,8 @@ The final output would be stored under `script/deployments/utxogateway.json`
 
 ```bash
 # Clone the repository
-git clone https://github.com/ExocoreNetwork/utxo-restaking.git
+# TODO: transfer out to imua-xyz after upgrading the org plan
+git clone https://github.com/imua-xyz/utxo-restaking.git
 cd utxo-restaking
 git checkout btc-restaking-v2
 ```
@@ -117,7 +118,7 @@ cp .env.example .env
 BITCOIN_RPC // URL of the esplora API
 VAULT_ADDRESS // Address of the BTC vault
 MIN_CONFIRMATIONS // Minimum number of confirmations for a Bitcoin transaction
-EXOCORE_RPC // URL of the Exocore node
+EXOCORE_RPC // URL of the Imuachain node
 CONTRACT_ADDRESS // Address of the UTXOGateway contract
 WITNESS_ADDRESS // Address of the witness
 WALLET_PRIV_KEY // Private key of the signing wallet, should be the same as the witness for current implementation
@@ -134,7 +135,7 @@ docker-compose up
 
 ### Run E2E Tests
 
-1. Go back to the exocore-contracts directory and run the BTC staking E2E test:
+1. Go back to the imua-contracts directory and run the BTC staking E2E test:
 
 ```bash
 npx hardhat test test/integration/btc-staking-e2e.test.js
@@ -150,4 +151,4 @@ BITCOIN_TX_FEE // Transaction fee for BTC deposit
 DUST_THRESHOLD // Dust threshold for BTC deposit
 ```
 
-This test would simulate the process of building a valid Bitcoin deposit transaction, broadcasting it to the Bitcoin network and waiting for it to be confirmed, and finally checking staker's balance on Exocore.
+This test would simulate the process of building a valid Bitcoin deposit transaction, broadcasting it to the Bitcoin network and waiting for it to be confirmed, and finally checking staker's balance on Imuachain.