WIP: HYBX OMNL and deployment documentation updates

2026-06-02 06:09:56 -07:00
parent f04a7cb7c8
commit d31aad7d66
33 changed files with 78 additions and 2878 deletions
--- a/docs/ccip-integration/reference/CCIP_BRIDGE_USER_GUIDE.md
+++ b/docs/ccip-integration/reference/CCIP_BRIDGE_USER_GUIDE.md
@@ -0,0 +1,282 @@
+# CCIP Bridge User Guide
+
+**Date**: 2025-01-27  
+**Network**: ChainID 138 (DeFi Oracle Meta Mainnet)
+
+---
+
+## Overview
+
+This guide explains how to use the CCIP bridges to transfer WETH9 and WETH10 tokens between ChainID 138 and other supported chains.
+
+---
+
+## Prerequisites
+
+- Wallet connected to ChainID 138
+- WETH9 or WETH10 tokens in your wallet
+- LINK tokens (if using LINK for fees) or native ETH (if using native fees)
+- Sufficient balance for gas fees
+
+---
+
+## Bridge Addresses
+
+### ChainID 138
+
+- **CCIPWETH9Bridge**: See `.env` or documentation for deployed address
+- **CCIPWETH10Bridge**: See `.env` or documentation for deployed address
+
+### Ethereum Mainnet
+
+- **CCIPWETH9Bridge**: `0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6`
+- **CCIPWETH10Bridge**: `0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e`
+
+---
+
+## Step-by-Step Guide
+
+### Step 1: Prepare Tokens
+
+#### Option A: You have native ETH
+
+Wrap ETH to WETH:
+
+```solidity
+// For WETH9
+weth9.deposit{value: amount}();
+
+// For WETH10
+weth10.deposit{value: amount}();
+```
+
+#### Option B: You already have WETH
+
+Ensure you have sufficient WETH balance.
+
+### Step 2: Approve Bridge
+
+Approve the bridge to spend your tokens:
+
+```solidity
+// For WETH9
+weth9.approve(bridgeAddress, amount);
+
+// For WETH10
+weth10.approve(bridgeAddress, amount);
+```
+
+### Step 3: Calculate Fees
+
+Estimate the CCIP fee:
+
+```solidity
+uint256 fee = bridge.calculateFee(destinationChainSelector, amount);
+```
+
+### Step 4: Approve Fee Token
+
+If using LINK for fees:
+
+```solidity
+linkToken.approve(bridgeAddress, fee);
+```
+
+If using native ETH, ensure you have sufficient balance.
+
+### Step 5: Send Cross-Chain
+
+Send tokens to destination chain:
+
+```solidity
+bytes32 messageId = bridge.sendCrossChain(
+    destinationChainSelector,  // e.g., 5009297550715157269 for Ethereum Mainnet
+    recipientAddress,           // Address on destination chain
+    amount                      // Amount to transfer
+);
+```
+
+### Step 6: Monitor Transfer
+
+Track the transfer using the `messageId`:
+
+- Check events: `CrossChainTransferInitiated`
+- Wait for confirmation on destination chain
+- Check events: `CrossChainTransferCompleted`
+
+---
+
+## Example: Transfer WETH9 from ChainID 138 to Ethereum Mainnet
+
+```solidity
+// 1. Wrap ETH to WETH9
+weth9.deposit{value: 1 ether}();
+
+// 2. Approve bridge
+weth9.approve(bridgeAddress, 1 ether);
+
+// 3. Calculate fee
+uint256 fee = bridge.calculateFee(5009297550715157269, 1 ether);
+
+// 4. Approve fee (if using LINK)
+linkToken.approve(bridgeAddress, fee);
+
+// 5. Send cross-chain
+bytes32 messageId = bridge.sendCrossChain(
+    5009297550715157269,  // Ethereum Mainnet selector
+    recipientAddress,     // Your address on Ethereum Mainnet
+    1 ether
+);
+
+// 6. Monitor transfer
+// Check events or use messageId to track
+```
+
+---
+
+## Using with Web3 Libraries
+
+### ethers.js
+
+```javascript
+const bridge = new ethers.Contract(bridgeAddress, bridgeABI, signer);
+
+// Approve
+await weth9.approve(bridgeAddress, amount);
+
+// Calculate fee
+const fee = await bridge.calculateFee(destinationSelector, amount);
+
+// Approve fee token (if LINK)
+await linkToken.approve(bridgeAddress, fee);
+
+// Send cross-chain
+const tx = await bridge.sendCrossChain(
+    destinationSelector,
+    recipientAddress,
+    amount
+);
+const receipt = await tx.wait();
+const messageId = receipt.events.find(e => e.event === 'CrossChainTransferInitiated').args.messageId;
+```
+
+### web3.js
+
+```javascript
+// Approve
+await weth9.methods.approve(bridgeAddress, amount).send({ from: account });
+
+// Calculate fee
+const fee = await bridge.methods.calculateFee(destinationSelector, amount).call();
+
+// Approve fee token (if LINK)
+await linkToken.methods.approve(bridgeAddress, fee).send({ from: account });
+
+// Send cross-chain
+const tx = await bridge.methods.sendCrossChain(
+    destinationSelector,
+    recipientAddress,
+    amount
+).send({ from: account });
+```
+
+---
+
+## Supported Destination Chains
+
+| Network | Chain ID | Chain Selector |
+|---------|----------|---------------|
+| Ethereum Mainnet | 1 | `5009297550715157269` |
+| BSC | 56 | `11344663589394136015` |
+| Polygon | 137 | `4051577828743386545` |
+| Avalanche | 43114 | `6433500567565415381` |
+| Base | 8453 | `15971525489660198786` |
+| Arbitrum | 42161 | `4949039107694359620` |
+| Optimism | 10 | `3734403246176062136` |
+
+---
+
+## Fees
+
+### Fee Structure
+
+- **Base Fee**: Fixed fee per message
+- **Data Fee**: Fee per byte of message data
+- **Token Fee**: Percentage of token amount (if applicable)
+
+### Fee Payment
+
+- **Native ETH**: Fees paid in native token (if configured)
+- **LINK Token**: Fees paid in LINK token (if configured)
+
+### Estimating Fees
+
+Always calculate fees before sending:
+
+```solidity
+uint256 fee = bridge.calculateFee(destinationSelector, amount);
+```
+
+---
+
+## Troubleshooting
+
+### Issue: Transfer Fails
+
+**Possible Causes**:
+- Insufficient token balance
+- Insufficient fee balance
+- Destination not configured
+- Invalid recipient address
+
+**Solutions**:
+1. Check token and fee balances
+2. Verify destination is enabled
+3. Verify recipient address is valid
+4. Check recent bridge events
+
+### Issue: Transfer Stuck
+
+**Possible Causes**:
+- Destination chain issues
+- Router problems
+- Network congestion
+
+**Solutions**:
+1. Check destination chain status
+2. Monitor bridge events
+3. Contact support if persistent
+
+### Issue: High Fees
+
+**Possible Causes**:
+- Large transfer amount
+- Network congestion
+- Fee configuration
+
+**Solutions**:
+1. Check fee calculation
+2. Consider smaller amounts
+3. Wait for lower network activity
+
+---
+
+## Security Considerations
+
+1. **Verify Addresses**: Always verify bridge and token addresses
+2. **Check Fees**: Verify fee calculations before sending
+3. **Monitor Transfers**: Track your transfers using messageId
+4. **Use Official Sources**: Only use addresses from official documentation
+
+---
+
+## Related Documentation
+
+- [CCIP Deployment Guide](../ccip/DEPLOYMENT_GUIDE_CHAIN138.md)
+- [CCIP Review](../CCIP_CHAIN138_REVIEW.md)
+- [Main Guide](../ETH_WETH_CHAINLINK_GUIDE.md)
+
+---
+
+**Last Updated**: 2025-01-27
+