Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-10 11:32:49 -08:00
parent aafcd913c2
commit 88bc76da91
815 changed files with 125522 additions and 264 deletions
--- a/docs/CCIP_FEE_STRUCTURE.md
+++ b/docs/CCIP_FEE_STRUCTURE.md
@@ -0,0 +1,182 @@
+# CCIP Fee Structure Documentation
+
+**Date**: 2025-01-12  
+**Network**: ChainID 138
+
+---
+
+## Overview
+
+This document describes the fee structure and payment mechanism for CCIP (Cross-Chain Interoperability Protocol) transactions.
+
+---
+
+## Fee Configuration
+
+### Fee Token
+- **Token Address**: `0x514910771AF9Ca656af840dff83E8264EcF986CA` (LINK)
+- **Network**: ChainID 138
+- **Purpose**: Payment token for CCIP fees
+
+### Fee Structure
+
+#### Base Fee
+- **Amount**: 1000000000000000 wei (0.001 LINK)
+- **Purpose**: Base fee for all CCIP messages
+- **Applies To**: All cross-chain messages
+
+#### Data Fee Per Byte
+- **Amount**: 100000000 wei (0.0000001 LINK per byte)
+- **Purpose**: Fee for message data size
+- **Calculation**: `dataFee = dataSize * dataFeePerByte`
+
+#### Total Fee Calculation
+```
+totalFee = baseFee + (dataSize * dataFeePerByte)
+```
+
+---
+
+## Fee Payment Mechanism
+
+### Payment Method
+Fees are paid in **LINK tokens** (not native ETH).
+
+### Fee Payment Process
+
+1. **User Initiates Transfer**:
+   - User calls bridge contract
+   - Bridge contract calculates fee
+   - Bridge contract checks LINK balance
+
+2. **Fee Payment**:
+   - Bridge contract transfers LINK to Router
+   - Router processes payment
+   - Message is sent
+
+3. **Fee Verification**:
+   - Router verifies fee payment
+   - Message is queued for processing
+   - Oracle network processes message
+
+---
+
+## Fee Calculation
+
+### Current Status: ⚠️ Failing
+
+Fee calculation in scripts is currently failing. This may be due to:
+1. Router contract not exposing `getFee()` function
+2. Fee calculation requiring different parameters
+3. Fee calculation handled by separate contract
+
+### Verification
+
+**Script**: `scripts/verify-fee-calculation.sh`
+
+**Usage**:
+```bash
+./scripts/verify-fee-calculation.sh [amount_eth] [destination_selector]
+```
+
+**Example**:
+```bash
+./scripts/verify-fee-calculation.sh 0.001 5009297550715157269
+```
+
+---
+
+## LINK Token Requirements
+
+### LINK Token Balance
+
+Bridge contracts need LINK tokens to pay fees:
+- **Minimum Balance**: Enough to cover expected fees
+- **Recommended**: Buffer for multiple transactions
+
+### Checking LINK Balance
+
+```bash
+cast call 0x514910771AF9Ca656af840dff83E8264EcF986CA \
+  "balanceOf(address)" \
+  <bridge_address> \
+  --rpc-url <rpc_url>
+```
+
+### Acquiring LINK Tokens
+
+1. **Purchase**: Buy LINK tokens on exchange
+2. **Transfer**: Send LINK to bridge contract
+3. **Faucet**: Use testnet faucet (if available)
+
+---
+
+## Fee Estimation
+
+### Estimating Fees
+
+For a typical cross-chain transfer:
+- **Base Fee**: 0.001 LINK
+- **Data Fee**: ~0.0001 LINK (depends on message size)
+- **Total**: ~0.0011 LINK per transfer
+
+### Factors Affecting Fees
+
+1. **Message Size**: Larger messages = higher fees
+2. **Destination Chain**: Different chains may have different fees
+3. **Network Conditions**: Fees may vary with network load
+
+---
+
+## Fee Optimization
+
+### Strategies
+
+1. **Batch Transfers**: Combine multiple transfers to reduce per-transfer fees
+2. **Optimize Message Size**: Minimize data in messages
+3. **Monitor Fees**: Track fee trends and optimize timing
+
+### Cost Analysis
+
+- **Per Transfer**: ~0.001 LINK
+- **Monthly (100 transfers)**: ~0.1 LINK
+- **Annual (1000 transfers)**: ~1 LINK
+
+---
+
+## Troubleshooting
+
+### Fee Calculation Failing
+
+**Symptoms**:
+- Scripts cannot calculate fees
+- `getFee()` returns 0 or fails
+
+**Solutions**:
+1. Verify Router contract address
+2. Check function availability
+3. Verify LINK token configuration
+
+### Insufficient LINK Balance
+
+**Symptoms**:
+- Transactions failing with insufficient balance
+- Fee payment errors
+
+**Solutions**:
+1. Check LINK balance
+2. Transfer LINK to bridge contract
+3. Verify LINK token address
+
+---
+
+## Related Documentation
+
+- [CCIP Router Configuration](./CCIP_ROUTER_CONFIGURATION.md)
+- [CCIP Configuration Status](./CCIP_CONFIGURATION_STATUS.md)
+- [Complete Task Catalog](./CCIP_COMPLETE_TASK_CATALOG.md)
+
+---
+
+**Last Updated**: 2025-01-12
+