3f76bc9507
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- MASTER_INDEX: Last Updated 2026-03-06; status 59/59 contracts; add NEXT_STEPS_LIST, CONTRACT_NEXT_STEPS_LIST - docs/README, NEXT_STEPS_INDEX, 06-besu/MASTER_INDEX: Last Updated 2026-03-06 - Contract check script: 59 addresses (PMM, vault/reserve, CompliantFiatTokens); canonical CCIP/router - New docs: EXECUTION_CHECKLIST, NEXT_STEPS_LIST, DOTENV_AUDIT, ADDITIONAL_PATHS, deployer gas runbook, WEMIX_ACQUISITION_TABLED, etc. - Config: deployer-gas-routes, cro-wemix-swap-routes, routing-registry, token-mapping - Scripts: check-contracts-on-chain-138, check-pmm-pool-balances-chain138, deployer-gas-auto-route, acquire-cro-and-wemix-gas - Operator rule: operator-lan-access-check.mdc Made-with: Cursor
97 lines
4.2 KiB
Markdown
97 lines
4.2 KiB
Markdown
# Non-Prefunded AVAX Migration Runbook
|
|
|
|
**Date:** 2026-03-04
|
|
**Scope:** Replace inventory-backed AVAX settlement behavior with a non-prefunded bridge path for future transfers.
|
|
|
|
## 1. Problem Statement
|
|
|
|
Current `138 -> AVAX` flow is inventory-backed:
|
|
- Source bridge on 138 escrows WETH.
|
|
- Destination bridge must already hold AVAX-side WETH to pay recipients.
|
|
- If destination inventory is zero, messages remain unprocessed.
|
|
|
|
This does not satisfy the requirement "move value to AVAX without pre-funding AVAX bridge inventory."
|
|
|
|
## 2. Target Architecture
|
|
|
|
Use a **lock/mint or burn/mint path** for the bridged asset, not release-from-inventory.
|
|
|
|
Recommended implementation in this repo:
|
|
1. Use dedicated receiver model from `CW_BRIDGE_APPROACH.md` (Option 2).
|
|
2. Bridge a mintable wrapped representation (for example `cW*` family), not canonical AVAX-side WETH.
|
|
3. Convert destination minted asset to required target assets through DEX routing.
|
|
|
|
Notes:
|
|
- Canonical WETH itself cannot be minted by your bridge contracts.
|
|
- If you require canonical WETH/AVAX output directly, you must use an external canonical bridge/protocol that supports that asset path.
|
|
|
|
## 3. Execution Order
|
|
|
|
### Phase A: Stop Further Loss Exposure
|
|
1. Freeze large `138 -> AVAX` sends on inventory-backed bridges.
|
|
2. Add preflight guard: block sends when destination delivery model is inventory-backed and inventory is below requested amount.
|
|
3. Keep BSC relay running only if still needed for legacy pending messages.
|
|
|
|
### Phase B: Recover Existing Stuck Message(s)
|
|
1. Enumerate pending message IDs (`processedTransfers == false`) on AVAX bridge.
|
|
2. For each pending message, either:
|
|
- fund destination bridge inventory and relay once, or
|
|
- implement explicit source-side refund path (if contract supports it; current WETH9 bridge does not expose one).
|
|
3. Verify each recovered message transitions to `processedTransfers == true`.
|
|
|
|
### Phase C: Deploy Non-Prefunded Path
|
|
1. Deploy/verify destination mintable token(s) and grant bridge roles:
|
|
- `MINTER_ROLE` and `BURNER_ROLE` to dedicated receiver (`TwoWayTokenBridgeL2` or equivalent).
|
|
2. Deploy sender/receiver pair:
|
|
- L1 sender/lock bridge on 138.
|
|
- L2 receiver/mint bridge on AVAX.
|
|
3. Configure chain selector mapping and router support for AVAX selector `6433500567565415381`.
|
|
4. Wire fee token and fee approvals.
|
|
5. Register token mapping in routing/config files.
|
|
|
|
### Phase D: E2E Validation (Required Before Production)
|
|
1. Test amounts: `0.01`, `1`, `20` units.
|
|
2. Validate:
|
|
- source escrow/burn,
|
|
- destination mint,
|
|
- no destination inventory dependency,
|
|
- reverse path burn/send works if required.
|
|
3. Run consistency tests for quote/fee, message replay protection, and mapping correctness.
|
|
|
|
### Phase E: Cutover
|
|
1. Mark legacy AVAX inventory-backed route as deprecated.
|
|
2. Update all operator scripts/docs to new route.
|
|
3. Keep monitoring and alerting on:
|
|
- message backlog,
|
|
- mint/burn failures,
|
|
- fee-token depletion.
|
|
|
|
## 4. Acceptance Criteria
|
|
|
|
Migration is complete only when all are true:
|
|
1. A `138 -> AVAX` transfer succeeds when destination bridge token inventory is `0`.
|
|
2. No relay payout from destination inventory is required.
|
|
3. End-to-end tests pass at small and medium sizes.
|
|
4. Runbooks/scripts no longer route AVAX through legacy inventory-backed path by default.
|
|
|
|
## 5. Immediate Operator Commands (Verification)
|
|
|
|
Check legacy destination dependency:
|
|
```bash
|
|
cast call 0x24293CA562aE1100E60a4640FF49bd656cFf93B4 "processedTransfers(bytes32)(bool)" <message_id> --rpc-url https://avalanche-c-chain.publicnode.com
|
|
cast call 0xa4B9DD039565AeD9641D45b57061f99d9cA6Df08 "balanceOf(address)(uint256)" 0x24293CA562aE1100E60a4640FF49bd656cFf93B4 --rpc-url https://avalanche-c-chain.publicnode.com
|
|
```
|
|
|
|
Check source escrow:
|
|
```bash
|
|
cast call 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 "balanceOf(address)(uint256)" 0x9cba0D04Ae5f6f16e3C599025aB97a05c4A593d5 --rpc-url https://rpc-http-pub.d-bis.org
|
|
```
|
|
|
|
## 6. Related Files
|
|
|
|
- `docs/07-ccip/CW_BRIDGE_APPROACH.md`
|
|
- `docs/11-references/CCIP_138_DESTINATION_RECEIVER_BY_CHAIN_AND_TOKEN.md`
|
|
- `smom-dbis-138/contracts/bridge/TwoWayTokenBridgeL1.sol`
|
|
- `smom-dbis-138/contracts/bridge/TwoWayTokenBridgeL2.sol`
|
|
- `smom-dbis-138/contracts/tokens/CompliantWrappedToken.sol`
|