| type | reference |
|---|
After applying a change here, sync your declared source of truth (the project store) and reconcile it against live with
make doctor CHAIN=<chain>: see Applying config and reconciling with doctor.
Deploy the token pool that CCIP burns, mints, locks, or releases through. Scripts under
script/deploy/. Primitive pages:
DeployBurnMintTokenPool,
DeployLockReleaseTokenPool,
DeployERC20LockBox,
DeploySiloedLockReleaseTokenPool,
GetLockBox. For the per-version support matrix see
Pool versions.
A broadcast deploy records the pool (and lockbox) address in the project store, so later scripts
resolve it automatically with no export. See Deployed addresses. To
override for one session, export ETHEREUM_SEPOLIA_TOKEN_POOL=0x... or pass TOKEN_POOL=0x... inline.
Tokens are burned on the source chain and minted on the destination.
Golden path:
make deploy-pool CHAIN=ethereum-testnet-sepolia VERIFY=1
make deploy-pool CHAIN=ethereum-testnet-sepolia-mantle-1 VERIFY=1Raw forge script:
# Deploy pool on Ethereum Sepolia
forge script \
script/deploy/DeployBurnMintTokenPool.s.sol \
--rpc-url \
$ETHEREUM_SEPOLIA_RPC_URL \
--account \
$KEYSTORE_NAME \
--broadcast \
--verify
# Deploy pool on Mantle Sepolia
forge script \
script/deploy/DeployBurnMintTokenPool.s.sol \
--rpc-url \
$MANTLE_SEPOLIA_RPC_URL \
--account \
$KEYSTORE_NAME \
--broadcast \
--verifyThe address is saved to history/token-pools/{selectorName}/{timestamp}-{SYMBOL}-BurnMintTokenPool.json
(keys {CHAIN_NAME_IDENTIFIER}_TOKEN_POOL and {CHAIN_NAME_IDENTIFIER}_TOKEN).
Set POOL_HOOKS=0x... to attach an AdvancedPoolHooks contract at deploy time. The pool's decimals
value comes from the token's decimals() when it answers; decimals() is optional in ERC20, so for a
token without it set DECIMALS=<n> explicitly - the pool takes the value as a constructor argument by
design and treats an on-chain read only as a cross-check. When both sources exist they must agree, and
when neither does the deploy stops: the value is immutable and scales every amount the pool moves, so
it is never guessed. The script also attempts grantMintAndBurnRoles on the token to grant the pool
mint and burn rights; if the token does not implement it, the script prints instructions to grant the
roles manually.
Use this when you do not have burn and mint rights on the source chain token (for example, it was
issued by a third party). The LockReleaseTokenPool requires an ERC20LockBox at deploy time, and the
lockbox must authorize the pool before it can deposit or withdraw tokens. The deployment order is always
lockbox, then pool, then authorize the pool on the lockbox.
LOCK_BOX is required and must be the address of a deployed ERC20LockBox for the token. Set
POOL_HOOKS=0x... to attach an already-deployed AdvancedPoolHooks contract. Decimals resolve the same
way as for the BurnMint pool above: read from the token when decimals() answers, DECIMALS=<n> for a
token without the optional getter, agreement required when both exist, refusal when neither. When
deploying the lockbox, optionally set AUTHORIZED_CALLERS (CSV or JSON array) to authorize addresses
immediately, useful for letting the deployer or token issuer deposit and withdraw initial liquidity.
The golden-path targets make deploy-lockbox CHAIN=<name> VERIFY=1 and
make deploy-lockrelease-pool CHAIN=<name> VERIFY=1 resolve the token and lock box from the registry;
the raw sequences below spell out the addresses explicitly.
The token was originally issued on one chain; you control the token on the destination and can grant
mint rights. The ERC20LockBox is only needed on the chain where tokens are locked. The destination
chain uses a standard BurnMintTokenPool, which requires mint and burn rights on the destination token.
# 1. Deploy ERC20LockBox first (pool address isn't known yet)
forge script \
script/deploy/DeployERC20LockBox.s.sol \
--rpc-url \
$ETHEREUM_SEPOLIA_RPC_URL \
--account \
$KEYSTORE_NAME \
--broadcast \
--verify
# Optional: add AUTHORIZED_CALLERS=<DEPLOYER_OR_TOKEN_ISSUER_EOA> to the command above to authorize initial liquidity deposits/withdrawals
# 2. Deploy LockRelease pool, passing the lockbox address from step 1
LOCK_BOX=<LOCKBOX_ADDRESS> \
forge script \
script/deploy/DeployLockReleaseTokenPool.s.sol \
--rpc-url \
$ETHEREUM_SEPOLIA_RPC_URL \
--account \
$KEYSTORE_NAME \
--broadcast \
--verify
# 3. Authorize the pool to call the lockbox (deposit/withdraw)
LOCK_BOX=<LOCKBOX_ADDRESS> \
ADD_ADDRESSES=<POOL_ADDRESS> \
forge script \
script/configure/authorized-callers/UpdateAuthorizedCallers.s.sol \
--rpc-url \
$ETHEREUM_SEPOLIA_RPC_URL \
--account \
$KEYSTORE_NAME \
--broadcast
# 4. BurnMint pool on Mantle Sepolia (minting side)
forge script \
script/deploy/DeployBurnMintTokenPool.s.sol \
--rpc-url \
$MANTLE_SEPOLIA_RPC_URL \
--account \
$KEYSTORE_NAME \
--broadcast \
--verifyThe token already exists on both chains independently. Each chain needs its own ERC20LockBox and
LockReleaseTokenPool.
This is a liquidity bridge, not a mint/burn mesh: every release is paid out of the destination's own
liquidity, so the busy direction drains and somebody has to rebalance. Fund and monitor both sides;
make doctor warns once per such lane. It is a different thing from two silos of ONE pool talking to each
other, which never balances and is refused - see siloed pools.
# 1. Deploy ERC20LockBox on Ethereum Sepolia
forge script \
script/deploy/DeployERC20LockBox.s.sol \
--rpc-url \
$ETHEREUM_SEPOLIA_RPC_URL \
--account \
$KEYSTORE_NAME \
--broadcast \
--verify
# 2. Deploy ERC20LockBox on Mantle Sepolia
forge script \
script/deploy/DeployERC20LockBox.s.sol \
--rpc-url \
$MANTLE_SEPOLIA_RPC_URL \
--account \
$KEYSTORE_NAME \
--broadcast \
--verify
# Optional: add AUTHORIZED_CALLERS=<DEPLOYER_OR_TOKEN_ISSUER_EOA> to either or both commands below for initial liquidity management
# 3. Deploy LockRelease pool on Ethereum Sepolia, passing its lockbox address from step 1
LOCK_BOX=<ETHEREUM_SEPOLIA_LOCKBOX_ADDRESS> \
forge script \
script/deploy/DeployLockReleaseTokenPool.s.sol \
--rpc-url \
$ETHEREUM_SEPOLIA_RPC_URL \
--account \
$KEYSTORE_NAME \
--broadcast \
--verify
# 4. Authorize the Ethereum Sepolia pool on its lockbox
LOCK_BOX=<ETHEREUM_SEPOLIA_LOCKBOX_ADDRESS> \
ADD_ADDRESSES=<ETHEREUM_SEPOLIA_POOL_ADDRESS> \
forge script \
script/configure/authorized-callers/UpdateAuthorizedCallers.s.sol \
--rpc-url \
$ETHEREUM_SEPOLIA_RPC_URL \
--account \
$KEYSTORE_NAME \
--broadcast
# 5. Deploy LockRelease pool on Mantle Sepolia, passing its lockbox address from step 2
LOCK_BOX=<MANTLE_SEPOLIA_LOCKBOX_ADDRESS> \
forge script \
script/deploy/DeployLockReleaseTokenPool.s.sol \
--rpc-url \
$MANTLE_SEPOLIA_RPC_URL \
--account \
$KEYSTORE_NAME \
--broadcast \
--verify
# 6. Authorize the Mantle Sepolia pool on its lockbox
LOCK_BOX=<MANTLE_SEPOLIA_LOCKBOX_ADDRESS> \
ADD_ADDRESSES=<MANTLE_SEPOLIA_POOL_ADDRESS> \
forge script \
script/configure/authorized-callers/UpdateAuthorizedCallers.s.sol \
--rpc-url \
$MANTLE_SEPOLIA_RPC_URL \
--account \
$KEYSTORE_NAME \
--broadcastEach deployment is saved to history/:
- ERC20LockBox to
history/lock-boxes/{selectorName}/{timestamp}-{SYMBOL}-LockBox.json(keysLOCK_BOX,{CHAIN_NAME_IDENTIFIER}_TOKEN) - LockReleaseTokenPool to
history/token-pools/{selectorName}/{timestamp}-{SYMBOL}-LockReleaseTokenPool.json(keys{CHAIN_NAME_IDENTIFIER}_TOKEN_POOL,LOCK_BOX,{CHAIN_NAME_IDENTIFIER}_TOKEN)
The LockRelease pool deploy also resolves LOCK_BOX from the registry once a lockbox is recorded.
To verify the lockbox address is correctly attached to the pool:
forge script script/configure/GetLockBox.s.sol --rpc-url $MANTLE_SEPOLIA_RPC_URLFor managing LockRelease liquidity after deploy (the rebalancer model on v1.x pools versus the lockbox model on v2.0), see LockRelease liquidity.
A SiloedLockReleaseTokenPool keeps each remote chain's liquidity apart, so releases for one chain can
never drain tokens locked for another. The 2.0.0 pool takes no lock box at deploy time; each remote chain
maps to an ERC20LockBox, and chains that share liquidity share a box. The order is pool, one box per
silo (each authorizing the pool), ConfigureLockBoxes, then the lanes:
make deploy-siloed-pool CHAIN=ethereum-testnet-sepolia
make deploy-lockbox CHAIN=ethereum-testnet-sepolia SILO=fuji AUTHORIZED_CALLERS=<pool>
make deploy-lockbox CHAIN=ethereum-testnet-sepolia SILO=base AUTHORIZED_CALLERS=<pool>
LOCK_BOXES=AVALANCHE_TESTNET_FUJI=<fuji box>,ETHEREUM_TESTNET_SEPOLIA_BASE_1=<base box> \
forge script script/configure/siloed/ConfigureLockBoxes.s.sol --rpc-url $ETHEREUM_SEPOLIA_RPC_URL \
--account <KEYSTORE_NAME> --broadcastApplyChainUpdates refuses a lane whose chain has no box yet, and make doctor fails a supported chain
without one. Operating the silos, and the 1.6.x versions that keep liquidity on the pool itself, are
covered in liquidity; moving from 1.6.x to 2.0.0 is
migrate a Siloed pool.