Add Oracle Aggregator and CCIP Integration

- Introduced Aggregator.sol for Chainlink-compatible oracle functionality, including round-based updates and access control. - Added OracleWithCCIP.sol to extend Aggregator with CCIP cross-chain messaging capabilities. - Created .gitmodules to include OpenZeppelin contracts as a submodule. - Developed a comprehensive deployment guide in NEXT_STEPS_COMPLETE_GUIDE.md for Phase 2 and smart contract deployment. - Implemented Vite configuration for the orchestration portal, supporting both Vue and React frameworks. - Added server-side logic for the Multi-Cloud Orchestration Portal, including API endpoints for environment management and monitoring. - Created scripts for resource import and usage validation across non-US regions. - Added tests for CCIP error handling and integration to ensure robust functionality. - Included various new files and directories for the orchestration portal and deployment scripts.
2025-12-12 14:57:48 -08:00
parent a1466e4005
commit 1fb7266469
1720 changed files with 241279 additions and 16 deletions
--- a/docs/operations/integrations/BLOCKSCOUT_METAMASK.md
+++ b/docs/operations/integrations/BLOCKSCOUT_METAMASK.md
@@ -0,0 +1,156 @@
+# Blockscout MetaMask Integration
+
+Blockscout configuration for MetaMask Portfolio compatibility.
+
+## Overview
+
+Blockscout must be configured to support MetaMask Portfolio's token auto-detection and balance display features.
+
+## Required API Endpoints
+
+### Token Metadata
+
+Blockscout must provide token metadata via API:
+
+```
+GET /api/v2/tokens/{address}
+```
+
+**Response**:
+```json
+{
+  "address": "0x...",
+  "name": "Wrapped Ether",
+  "symbol": "WETH",
+  "decimals": 18,
+  "total_supply": "1000000000000000000000",
+  "holders_count": 100,
+  "transactions_count": 1000
+}
+```
+
+### Token Holders
+
+```
+GET /api/v2/tokens/{address}/holders
+```
+
+### Account Token Balances
+
+```
+GET /api/v2/addresses/{address}/token-balances
+```
+
+## CORS Configuration
+
+### Required CORS Headers
+
+Blockscout must allow CORS requests from MetaMask Portfolio:
+
+```
+Access-Control-Allow-Origin: https://portfolio.metamask.io
+Access-Control-Allow-Methods: GET, OPTIONS
+Access-Control-Allow-Headers: Content-Type
+Access-Control-Max-Age: 3600
+```
+
+### Configuration
+
+Add to Blockscout deployment:
+
+```yaml
+env:
+  - name: CORS_ALLOWED_ORIGINS
+    value: "https://portfolio.metamask.io,https://metamask.io,https://chainlist.org"
+  - name: ENABLE_CORS
+    value: "true"
+```
+
+## Token Logo Serving
+
+### Logo URL Format
+
+Token logos should be served from:
+
+```
+https://explorer.d-bis.org/images/tokens/{address}.png
+```
+
+### Configuration
+
+1. **Enable Logo Serving**: Enable logo serving in Blockscout
+2. **Logo Storage**: Store logos in Blockscout or CDN
+3. **Fallback**: Use default token logo if not found
+4. **Format**: PNG format, 512x512 pixels
+
+## Contract Verification
+
+### Required for Token Metadata
+
+All token contracts should be verified on Blockscout to provide accurate metadata:
+
+1. **Verify Contracts**: Verify all token contracts
+2. **Update Metadata**: Update token metadata as needed
+3. **Monitor**: Monitor for contract updates
+
+## API Rate Limiting
+
+### Portfolio-Specific Limits
+
+Configure rate limiting for Portfolio requests:
+
+- **Default**: 120 requests/minute per IP
+- **Portfolio**: Higher limits for Portfolio domain
+- **API Keys**: Optional API keys for higher limits
+
+## Testing
+
+### Test Checklist
+
+- [ ] Token metadata API works
+- [ ] Token holders API works
+- [ ] Account token balances API works
+- [ ] CORS headers are present
+- [ ] Token logos are accessible
+- [ ] Contract verification works
+- [ ] Rate limiting works correctly
+
+### Test Commands
+
+```bash
+# Test token metadata API
+curl https://explorer.d-bis.org/api/v2/tokens/0xYourTokenAddress
+
+# Test CORS headers
+curl -H "Origin: https://portfolio.metamask.io" \
+     -H "Access-Control-Request-Method: GET" \
+     -X OPTIONS \
+     https://explorer.d-bis.org/api/v2/tokens/0xYourTokenAddress
+
+# Test token logo
+curl https://explorer.d-bis.org/images/tokens/0xYourTokenAddress.png
+```
+
+## Monitoring
+
+### Metrics
+
+- API request rate
+- CORS request rate
+- Token metadata API usage
+- Logo serving performance
+- Error rates
+
+### Alerts
+
+- API errors
+- CORS configuration issues
+- Logo serving failures
+- Rate limiting issues
+
+## References
+
+- [Blockscout API Documentation](https://docs.blockscout.com/for-developers/api)
+- [MetaMask Portfolio](https://portfolio.metamask.io)
+- [CORS Configuration](https://docs.blockscout.com/for-developers/api/cors)
+
--- a/docs/operations/integrations/BRIDGE_CONFIGURATION.md
+++ b/docs/operations/integrations/BRIDGE_CONFIGURATION.md
@@ -0,0 +1,125 @@
+# Bridge Configuration Guide
+
+## Overview
+
+After deploying CCIP WETH bridges on both Ethereum Mainnet and ChainID 138, you need to configure them to enable cross-chain transfers.
+
+## Prerequisites
+
+1. **Bridges deployed on both chains:**
+   - Mainnet: CCIPWETH9Bridge and CCIPWETH10Bridge
+   - ChainID 138: CCIPWETH9Bridge and CCIPWETH10Bridge
+
+2. **Chain selectors:**
+   - Ethereum Mainnet: `5009297550715157269`
+   - ChainID 138: (to be determined from CCIP Router)
+
+3. **Admin access** to bridge contracts
+
+## Configuration Steps
+
+### Step 1: Get Chain Selectors
+
+```bash
+# Get ChainID 138 selector from CCIP Router
+cast call $CCIP_ROUTER "getChainSelector()" --rpc-url $RPC_URL
+
+# Ethereum Mainnet selector is known: 5009297550715157269
+```
+
+### Step 2: Configure Mainnet Bridges
+
+On Ethereum Mainnet, configure bridges to send to ChainID 138:
+
+```bash
+# Add ChainID 138 as destination for WETH9 bridge
+cast send $MAINNET_WETH9_BRIDGE \
+  "addDestination(uint64,address)" \
+  $CHAIN138_SELECTOR \
+  $CHAIN138_WETH9_BRIDGE \
+  --rpc-url $MAINNET_RPC \
+  --private-key $MAINNET_PRIVATE_KEY
+
+# Add ChainID 138 as destination for WETH10 bridge
+cast send $MAINNET_WETH10_BRIDGE \
+  "addDestination(uint64,address)" \
+  $CHAIN138_SELECTOR \
+  $CHAIN138_WETH10_BRIDGE \
+  --rpc-url $MAINNET_RPC \
+  --private-key $MAINNET_PRIVATE_KEY
+```
+
+### Step 3: Configure ChainID 138 Bridges
+
+On ChainID 138, configure bridges to send to Mainnet:
+
+```bash
+# Add Mainnet as destination for WETH9 bridge
+cast send $CHAIN138_WETH9_BRIDGE \
+  "addDestination(uint64,address)" \
+  $MAINNET_SELECTOR \
+  $MAINNET_WETH9_BRIDGE \
+  --rpc-url $RPC_URL \
+  --private-key $PRIVATE_KEY
+
+# Add Mainnet as destination for WETH10 bridge
+cast send $CHAIN138_WETH10_BRIDGE \
+  "addDestination(uint64,address)" \
+  $MAINNET_SELECTOR \
+  $MAINNET_WETH10_BRIDGE \
+  --rpc-url $RPC_URL \
+  --private-key $PRIVATE_KEY
+```
+
+### Step 4: Verify Configuration
+
+```bash
+# Check destinations on Mainnet bridge
+cast call $MAINNET_WETH9_BRIDGE \
+  "destinations(uint64)" \
+  $CHAIN138_SELECTOR \
+  --rpc-url $MAINNET_RPC
+
+# Check destinations on ChainID 138 bridge
+cast call $CHAIN138_WETH9_BRIDGE \
+  "destinations(uint64)" \
+  $MAINNET_SELECTOR \
+  --rpc-url $RPC_URL
+```
+
+## Gas Costs
+
+Each `addDestination` call costs approximately:
+- **Gas**: ~50,000 gas
+- **Cost at 30 gwei**: ~0.0015 ETH (~$3.75)
+- **Total for 4 calls**: ~0.006 ETH (~$15)
+
+## Testing Cross-Chain Transfers
+
+After configuration, test a cross-chain transfer:
+
+```bash
+# On Mainnet: Send WETH9 to ChainID 138
+cast send $MAINNET_WETH9_BRIDGE \
+  "sendCrossChain(uint64,address,uint256)" \
+  $CHAIN138_SELECTOR \
+  $RECIPIENT_ADDRESS \
+  $AMOUNT \
+  --rpc-url $MAINNET_RPC \
+  --private-key $MAINNET_PRIVATE_KEY
+```
+
+## Troubleshooting
+
+### Error: "destination not enabled"
+- Ensure `addDestination` was called successfully
+- Verify chain selector is correct
+- Check bridge addresses are correct
+
+### Error: "insufficient fee"
+- Ensure LINK token balance is sufficient
+- Check fee calculation: `calculateFee(chainSelector, amount)`
+
+### Error: "transfer failed"
+- Ensure WETH balance is sufficient
+- Check WETH approval for bridge contract
--- a/docs/operations/integrations/CACTI_INTEGRATION.md
+++ b/docs/operations/integrations/CACTI_INTEGRATION.md
@@ -0,0 +1,145 @@
+# Hyperledger Cacti Integration
+
+## Overview
+
+Hyperledger Cacti is integrated into the Besu network for cross-chain interoperability. Cacti provides connectors for multiple blockchains and enables cross-chain transactions.
+
+## Architecture
+
+### Components
+
+1. **Cactus API Server**: Main Cacti API service
+2. **Besu Connector**: Connects Cacti to Besu network
+3. **Plugins**: Various blockchain plugins
+
+### Network Integration
+
+- **Chain ID**: 138 (DeFi Oracle Meta Mainnet)
+- **RPC Endpoint**: Besu RPC nodes
+- **WebSocket Endpoint**: Besu WebSocket nodes
+
+## Deployment
+
+### Prerequisites
+
+- Kubernetes cluster (AKS)
+- Besu network deployed
+- RPC endpoints accessible
+
+### Deploy Cacti
+
+```bash
+# Deploy Cacti
+./scripts/deployment/deploy-cacti.sh
+
+# Or manually
+kubectl apply -f k8s/cacti/
+```
+
+### Verify Deployment
+
+```bash
+# Check Cacti status
+kubectl get pods -n cacti
+
+# Check Cacti API
+curl http://cactus-api.cacti.svc.cluster.local:4000/api/v1/api-server/healthcheck
+```
+
+## Configuration
+
+### Cacti Configuration
+
+Cacti is configured via ConfigMap (`k8s/cacti/configmap.yaml`):
+
+- **Node ID**: cactus-node-1
+- **API Port**: 4000
+- **WebSocket Port**: 4001
+- **Besu RPC**: Besu RPC endpoints
+- **Chain ID**: 138
+
+### Environment Variables
+
+- `CACTUS_NODE_ID`: cactus-node-1
+- `CACTUS_LOG_LEVEL`: info
+- `HTTP_PORT`: 4000
+- `WS_PORT`: 4001
+- `BESU_RPC_HTTP`: Besu RPC URL
+- `BESU_RPC_WS`: Besu WebSocket URL
+- `BESU_CHAIN_ID`: 138
+
+## Usage
+
+### Register Besu Ledger
+
+```bash
+curl -X POST http://cactus-api.cacti.svc.cluster.local:4000/api/v1/plugins/ledger-connector/besu \
+  -H "Content-Type: application/json" \
+  -d '{
+    "ledgerId": "besu-chain-138",
+    "chainId": 138,
+    "rpc": {
+      "http": "http://besu-rpc-service:8545",
+      "ws": "ws://besu-rpc-service:8546"
+    }
+  }'
+```
+
+### Deploy Contract
+
+```bash
+curl -X POST http://cactus-api.cacti.svc.cluster.local:4000/api/v1/plugins/ledger-connector/besu/deploy-contract \
+  -H "Content-Type: application/json" \
+  -d '{
+    "ledgerId": "besu-chain-138",
+    "abi": [...],
+    "bytecode": "0x...",
+    "constructorArgs": []
+  }'
+```
+
+### Invoke Contract
+
+```bash
+curl -X POST http://cactus-api.cacti.svc.cluster.local:4000/api/v1/plugins/ledger-connector/besu/invoke-contract \
+  -H "Content-Type: application/json" \
+  -d '{
+    "ledgerId": "besu-chain-138",
+    "contractAddress": "0x...",
+    "abi": [...],
+    "method": "transfer",
+    "args": ["0x...", "1000"]
+  }'
+```
+
+## Integration with Besu
+
+Cacti connects to Besu via:
+
+1. **Besu Connector Plugin**: Connects to Besu RPC
+2. **Chain ID**: 138
+3. **RPC Endpoints**: Besu RPC and WebSocket
+
+### Besu-Cacti Connector
+
+The Besu-Cacti connector (`connectors/besu-cacti/connector.py`) provides:
+
+- Ledger registration
+- Contract deployment
+- Contract invocation
+- Status monitoring
+
+## Cross-Chain Interoperability
+
+Cacti enables:
+
+- **Cross-chain transfers**: Transfer assets between chains
+- **Cross-chain contracts**: Deploy contracts on multiple chains
+- **Cross-chain bridges**: Bridge assets between chains
+
+## References
+
+- [Cacti Documentation](https://hyperledger.github.io/cacti/)
+- [Cacti API](https://hyperledger.github.io/cacti/api/)
+- [Besu Connector](https://hyperledger.github.io/cacti/plugins/ledger-connector-besu/)
+
--- a/docs/operations/integrations/CCIP_FEES.md
+++ b/docs/operations/integrations/CCIP_FEES.md
@@ -0,0 +1,168 @@
+# CCIP Fees
+
+## Overview
+
+CCIP messages require LINK tokens to pay for cross-chain message delivery. This document explains how fees are calculated and managed.
+
+## Fee Calculation
+
+CCIP fees are calculated based on:
+
+1. **Message Size**: Larger messages cost more
+2. **Target Chain**: Different chains have different fee rates
+3. **Gas Price**: Current gas prices on target chain
+4. **Token Type**: Native tokens vs LINK tokens
+
+## Calculating Fees
+
+Use the `calculateFee()` function to get the required fee:
+
+```solidity
+CCIPSender sender = CCIPSender(senderAddress);
+uint256 fee = sender.calculateFee(targetChainSelector, messageData);
+```
+
+## Fee Payment
+
+Fees are paid when sending the message:
+
+```solidity
+sender.sendOracleUpdate{value: fee}(targetChainSelector, receiverAddress, messageData);
+```
+
+## Fee Estimation
+
+### Typical Fees (as of 2024)
+
+- **Small message** (< 100 bytes): ~0.01-0.05 LINK
+- **Medium message** (100-500 bytes): ~0.05-0.2 LINK
+- **Large message** (> 500 bytes): ~0.2-1.0 LINK
+
+*Note: Fees vary by chain and network conditions*
+
+## Managing LINK Balance
+
+### Check Balance
+
+```solidity
+IERC20 linkToken = IERC20(LINK_TOKEN_ADDRESS);
+uint256 balance = linkToken.balanceOf(address(this));
+```
+
+### Transfer LINK
+
+```bash
+# Transfer LINK to sender contract
+cast send $LINK_TOKEN "transfer(address,uint256)" $SENDER_CONTRACT $AMOUNT \
+  --rpc-url $RPC_URL --private-key $PRIVATE_KEY
+```
+
+### Approve Spending
+
+```solidity
+IERC20 linkToken = IERC20(LINK_TOKEN_ADDRESS);
+linkToken.approve(senderAddress, amount);
+```
+
+## Fee Monitoring
+
+Monitor fee consumption:
+
+- Track total fees spent
+- Monitor fee per message
+- Alert on high fee usage
+- Set fee budgets
+
+### Metrics
+
+- `ccip_fees_total`: Total LINK spent on fees
+- `ccip_fees_per_message`: Average fee per message
+- `ccip_fee_errors`: Failed transactions due to insufficient fees
+
+## Cost Optimization
+
+### 1. Minimize Message Size
+
+- Use efficient encoding
+- Remove unnecessary data
+- Compress data when possible
+
+### 2. Batch Updates
+
+- Combine multiple updates into one message
+- Reduce number of messages sent
+- Lower total fee cost
+
+### 3. Monitor Gas Prices
+
+- Send during low gas price periods
+- Use gas price oracles
+- Schedule updates strategically
+
+### 4. Use Native Tokens
+
+- Some chains support native token payments
+- May be cheaper than LINK in some cases
+
+## Fee Limits
+
+Set maximum fee limits to prevent excessive spending:
+
+```solidity
+uint256 constant MAX_FEE_PER_MESSAGE = 1 ether; // 1 LINK
+
+require(fee <= MAX_FEE_PER_MESSAGE, "Fee too high");
+```
+
+## Refunds
+
+CCIP may refund unused fees if:
+- Message fails to deliver
+- Target chain is unavailable
+- Message is rejected
+
+Check refund status in transaction logs.
+
+## Troubleshooting
+
+### Insufficient LINK
+
+**Error**: "Insufficient LINK balance"
+
+**Solution**:
+1. Check LINK balance
+2. Transfer more LINK tokens
+3. Verify token address is correct
+
+### Fee Too High
+
+**Error**: "Fee exceeds limit"
+
+**Solution**:
+1. Reduce message size
+2. Wait for lower gas prices
+3. Increase fee limit (if appropriate)
+
+### Fee Calculation Failed
+
+**Error**: "Failed to calculate fee"
+
+**Solution**:
+1. Verify CCIP Router is accessible
+2. Check target chain selector is valid
+3. Ensure router is properly configured
+
+## Best Practices
+
+1. **Maintain Buffer**: Keep 2-3x expected fees in balance
+2. **Monitor Regularly**: Check fee consumption daily
+3. **Set Alerts**: Alert on low balance or high fees
+4. **Budget Planning**: Plan for fee costs in operations budget
+5. **Test Fees**: Test fee calculation in staging environment
+
+## References
+
+- [CCIP Integration Guide](docs/CCIP_INTEGRATION.md)
+- [CCIP Router Setup](docs/CCIP_ROUTER_SETUP.md)
+- [Chainlink CCIP Fees](https://docs.chain.link/ccip/fees)
+
--- a/docs/operations/integrations/CCIP_INTEGRATION.md
+++ b/docs/operations/integrations/CCIP_INTEGRATION.md
@@ -0,0 +1,155 @@
+# CCIP Integration Guide
+
+## Overview
+
+Chainlink Cross-Chain Interoperability Protocol (CCIP) enables secure cross-chain communication for oracle data updates. This guide explains how to integrate CCIP with the DeFi Oracle Meta Mainnet.
+
+## Architecture
+
+```
+┌─────────────────┐         ┌──────────────┐         ┌─────────────────┐
+│  Source Chain   │────────▶│  CCIP Router │────────▶│  Target Chain   │
+│  (ChainID 138)  │         │              │         │  (Other Chain)  │
+└─────────────────┘         └──────────────┘         └─────────────────┘
+       │                            │                          │
+       │                            │                          │
+       ▼                            ▼                          ▼
+┌──────────────┐         ┌──────────────┐         ┌──────────────┐
+│ CCIPSender   │         │ CCIP Router  │         │ CCIPReceiver │
+│  Contract    │         │   Service    │         │   Contract   │
+└──────────────┘         └──────────────┘         └──────────────┘
+```
+
+## Components
+
+### 1. CCIP Router Interface
+
+The `IRouterClient` interface defines the standard CCIP Router interface for sending and receiving cross-chain messages.
+
+**Location**: `contracts/ccip/IRouterClient.sol`
+
+### 2. CCIP Sender Contract
+
+The `CCIPSender` contract sends oracle data to other chains via CCIP.
+
+**Location**: `contracts/ccip/CCIPSender.sol`
+
+**Key Functions**:
+- `sendOracleUpdate()`: Sends oracle price update to target chain
+- `calculateFee()`: Calculates CCIP message fee
+
+### 3. CCIP Receiver Contract
+
+The `CCIPReceiver` contract receives oracle data from other chains via CCIP.
+
+**Location**: `contracts/ccip/CCIPReceiver.sol`
+
+**Key Functions**:
+- `ccipReceive()`: Handles incoming CCIP messages
+- `updateOracle()`: Updates oracle aggregator with received data
+
+## Integration Steps
+
+### Step 1: Deploy CCIP Router
+
+1. Deploy Chainlink CCIP Router on your chain
+2. Get the router address
+3. Configure router in your contracts
+
+### Step 2: Deploy CCIP Contracts
+
+```bash
+# Deploy CCIPSender
+forge script script/DeployCCIPSender.s.sol --rpc-url $RPC_URL --broadcast
+
+# Deploy CCIPReceiver
+forge script script/DeployCCIPReceiver.s.sol --rpc-url $RPC_URL --broadcast
+```
+
+### Step 3: Configure Contracts
+
+1. Set CCIP Router address in sender and receiver contracts
+2. Set target chain selector
+3. Configure oracle aggregator address
+4. Set transmitter role for receiver contract
+
+### Step 4: Send Cross-Chain Messages
+
+```solidity
+// In your oracle update function
+CCIPSender sender = CCIPSender(senderAddress);
+uint256 fee = sender.calculateFee(targetChainSelector, messageData);
+sender.sendOracleUpdate{value: fee}(targetChainSelector, receiverAddress, priceData);
+```
+
+### Step 5: Receive Cross-Chain Messages
+
+The CCIP Router automatically calls `ccipReceive()` on the receiver contract when a message arrives.
+
+## Message Format
+
+CCIP messages contain encoded oracle data:
+
+```solidity
+struct OracleMessage {
+    uint256 answer;      // Oracle price/answer
+    uint256 roundId;     // Round ID
+    uint256 timestamp;   // Timestamp
+}
+```
+
+## Fee Calculation
+
+CCIP fees are calculated based on:
+- Message size
+- Target chain
+- Gas price on target chain
+
+Use `calculateFee()` to get the required fee before sending.
+
+## Security Considerations
+
+1. **Replay Protection**: Messages are tracked by `messageId` to prevent replay attacks
+2. **Access Control**: Only authorized transmitters can update oracles
+3. **Message Validation**: Validate message format and source chain
+4. **Fee Management**: Ensure sufficient LINK tokens for fees
+
+## Monitoring
+
+Monitor CCIP message flow:
+- Message send success/failure rates
+- Message delivery latency
+- Fee consumption
+- Error rates
+
+See `monitoring/prometheus/alerts/ccip.yml` for alerting rules.
+
+## Troubleshooting
+
+### Message Not Received
+
+1. Check CCIP Router is deployed and running
+2. Verify target chain selector is correct
+3. Check receiver contract address is correct
+4. Verify sufficient LINK tokens for fees
+5. Check message was sent successfully
+
+### High Fees
+
+1. Optimize message size
+2. Consider batching multiple updates
+3. Monitor gas prices on target chain
+
+### Replay Protection Errors
+
+1. Check `processedMessages` mapping
+2. Verify message IDs are unique
+3. Check for duplicate message sends
+
+## References
+
+- [Chainlink CCIP Documentation](https://docs.chain.link/ccip)
+- [CCIP Router Setup Guide](docs/CCIP_ROUTER_SETUP.md)
+- [CCIP Message Format](docs/CCIP_MESSAGE_FORMAT.md)
+- [CCIP Fees](docs/CCIP_FEES.md)
+
--- a/docs/operations/integrations/CCIP_MESSAGE_FORMAT.md
+++ b/docs/operations/integrations/CCIP_MESSAGE_FORMAT.md
@@ -0,0 +1,147 @@
+# CCIP Message Format
+
+## Overview
+
+This document describes the message format used for CCIP cross-chain oracle updates.
+
+## Message Structure
+
+CCIP messages contain encoded oracle data in the following format:
+
+```solidity
+struct OracleMessage {
+    uint256 answer;      // Oracle price/answer (scaled by 10^8)
+    uint256 roundId;     // Round ID for this update
+    uint256 timestamp;   // Unix timestamp of the update
+}
+```
+
+## Encoding
+
+Messages are encoded using ABI encoding:
+
+```solidity
+bytes memory messageData = abi.encode(answer, roundId, timestamp);
+```
+
+## Decoding
+
+On the receiving chain, messages are decoded:
+
+```solidity
+(uint256 answer, uint256 roundId, uint256 timestamp) = abi.decode(message.data, (uint256, uint256, uint256));
+```
+
+## Example
+
+### Sending Message
+
+```solidity
+uint256 price = 25000000000; // $250.00 (scaled by 10^8)
+uint256 roundId = 12345;
+uint256 timestamp = block.timestamp;
+
+bytes memory messageData = abi.encode(price, roundId, timestamp);
+
+CCIPSender sender = CCIPSender(senderAddress);
+uint256 fee = sender.calculateFee(targetChainSelector, messageData);
+sender.sendOracleUpdate{value: fee}(targetChainSelector, receiverAddress, messageData);
+```
+
+### Receiving Message
+
+```solidity
+function ccipReceive(
+    IRouterClient.Any2EVMMessage calldata message
+) external onlyRouter {
+    (uint256 answer, uint256 roundId, uint256 timestamp) = abi.decode(
+        message.data,
+        (uint256, uint256, uint256)
+    );
+    
+    // Update oracle
+    updateOracle(answer, roundId, timestamp);
+}
+```
+
+## Data Types
+
+### Answer (uint256)
+
+- Oracle price/value
+- Scaled by 10^8 (8 decimal places)
+- Example: $250.00 = 25000000000
+
+### Round ID (uint256)
+
+- Sequential round identifier
+- Increments with each update
+- Used for ordering and deduplication
+
+### Timestamp (uint256)
+
+- Unix timestamp (seconds since epoch)
+- When the price was observed
+- Used for staleness checks
+
+## Message Size
+
+Typical message size: ~96 bytes (3 * 32 bytes)
+
+Maximum recommended size: 256 bytes
+
+## Validation
+
+Before processing, validate:
+
+1. **Message ID**: Check for replay attacks
+2. **Source Chain**: Verify source chain selector
+3. **Sender**: Verify sender address is authorized
+4. **Timestamp**: Check timestamp is recent
+5. **Round ID**: Ensure round ID is sequential
+
+## Error Handling
+
+### Invalid Format
+
+If message cannot be decoded:
+
+```solidity
+try abi.decode(message.data, (uint256, uint256, uint256)) returns (uint256, uint256, uint256) {
+    // Process message
+} catch {
+    // Log error and reject message
+    emit InvalidMessageFormat(message.messageId);
+    return;
+}
+```
+
+### Stale Data
+
+Check timestamp is recent:
+
+```solidity
+require(block.timestamp - timestamp < MAX_STALENESS, "Data too stale");
+```
+
+### Invalid Round ID
+
+Ensure round ID is sequential:
+
+```solidity
+require(roundId > lastRoundId, "Invalid round ID");
+```
+
+## Security Considerations
+
+1. **Replay Protection**: Track processed message IDs
+2. **Source Validation**: Verify source chain and sender
+3. **Data Validation**: Validate all fields before processing
+4. **Access Control**: Only authorized contracts can receive messages
+
+## References
+
+- [CCIP Integration Guide](docs/CCIP_INTEGRATION.md)
+- [CCIP Router Setup](docs/CCIP_ROUTER_SETUP.md)
+- [Chainlink CCIP Documentation](https://docs.chain.link/ccip)
+
--- a/docs/operations/integrations/CCIP_ROUTER_SETUP.md
+++ b/docs/operations/integrations/CCIP_ROUTER_SETUP.md
@@ -0,0 +1,189 @@
+# CCIP Router Setup Guide
+
+## Overview
+
+This guide explains how to set up and deploy the Chainlink CCIP Router for cross-chain oracle updates.
+
+## Prerequisites
+
+- Chainlink CCIP Router contract deployed on source and target chains
+- LINK tokens for paying CCIP fees
+- Access to deploy contracts
+- Validator keys for signing transactions
+
+## Deployment Steps
+
+### Step 1: Get CCIP Router Addresses
+
+CCIP Router addresses vary by chain:
+
+- **Ethereum Mainnet**: `0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D`
+- **Polygon**: `0x3C3D92629A02a8D95D5CB9650fe49C3544f69B43`
+- **Avalanche**: `0xF694E193200268f9a4868e4Aa017A0118C9a8177`
+- **Arbitrum**: `0x1619DE6B6B20eD217a58d00f37B9d47C7663feca`
+- **Optimism**: `0x261c05167db67Be2E2dc4a347C4E6B000C677852`
+
+For ChainID 138, deploy a custom CCIP Router or use a compatible implementation.
+
+### Step 2: Deploy CCIP Router (if needed)
+
+If deploying a custom CCIP Router:
+
+```bash
+# Deploy CCIP Router
+forge script script/DeployCCIPRouter.s.sol --rpc-url $RPC_URL --broadcast
+```
+
+### Step 3: Configure Router Address
+
+Update contract configurations:
+
+```solidity
+// In CCIPSender.sol
+address public constant CCIP_ROUTER = 0x...; // Your router address
+
+// In CCIPReceiver.sol
+constructor(address _router, address _oracleAggregator) {
+    router = IRouterClient(_router);
+    // ...
+}
+```
+
+### Step 4: Set Chain Selectors
+
+Configure chain selectors for target chains:
+
+```solidity
+// Chain selectors
+uint64 constant ETHEREUM_MAINNET = 5009297550715157269;
+uint64 constant POLYGON = 4051577828743386545;
+uint64 constant AVALANCHE = 6433500567565415381;
+uint64 constant ARBITRUM = 4949039107694359620;
+uint64 constant OPTIMISM = 3734403246176062136;
+```
+
+### Step 5: Fund LINK Tokens
+
+Ensure contracts have sufficient LINK tokens for fees:
+
+```bash
+# Transfer LINK to sender contract
+cast send $SENDER_CONTRACT "transfer(address,uint256)" $LINK_TOKEN $AMOUNT --rpc-url $RPC_URL --private-key $PRIVATE_KEY
+```
+
+### Step 6: Verify Deployment
+
+```bash
+# Check router address
+cast call $SENDER_CONTRACT "router()" --rpc-url $RPC_URL
+
+# Check chain selector
+cast call $SENDER_CONTRACT "targetChainSelector()" --rpc-url $RPC_URL
+```
+
+## Configuration Files
+
+### Kubernetes Deployment
+
+Deploy CCIP Router service (if running as a service):
+
+```yaml
+# k8s/ccip/router-deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: ccip-router
+  namespace: besu-network
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: ccip-router
+  template:
+    metadata:
+      labels:
+        app: ccip-router
+    spec:
+      containers:
+        - name: ccip-router
+          image: chainlink/ccip-router:v1.0.0
+          env:
+            - name: RPC_URL
+              value: "http://besu-rpc:8545"
+            - name: PRIVATE_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: ccip-router-secrets
+                  key: private_key
+```
+
+### Environment Variables
+
+```bash
+# .env
+CCIP_ROUTER_ADDRESS=0x...
+TARGET_CHAIN_SELECTOR=5009297550715157269
+LINK_TOKEN_ADDRESS=0x...
+```
+
+## Testing
+
+### Test CCIP Router Connection
+
+```bash
+# Test router is accessible
+cast call $CCIP_ROUTER "getSupportedTokens(uint64)" $CHAIN_SELECTOR --rpc-url $RPC_URL
+```
+
+### Test Message Sending
+
+```bash
+# Send test message
+forge script script/TestCCIPSend.s.sol --rpc-url $RPC_URL --broadcast
+```
+
+## Monitoring
+
+Monitor CCIP Router health:
+
+- Router availability
+- Message processing rate
+- Fee consumption
+- Error rates
+
+See `monitoring/prometheus/alerts/ccip.yml` for alerting rules.
+
+## Troubleshooting
+
+### Router Not Found
+
+1. Verify router address is correct
+2. Check router is deployed on the chain
+3. Verify network/chain ID matches
+
+### Insufficient LINK
+
+1. Check LINK balance
+2. Transfer more LINK tokens
+3. Monitor fee consumption
+
+### Message Delivery Failures
+
+1. Check target chain selector
+2. Verify receiver contract address
+3. Check target chain router is operational
+4. Review error logs
+
+## Security
+
+1. **Access Control**: Restrict router configuration to authorized addresses
+2. **Fee Limits**: Set maximum fee limits to prevent excessive spending
+3. **Rate Limiting**: Implement rate limiting for message sending
+4. **Monitoring**: Monitor for unusual activity
+
+## References
+
+- [Chainlink CCIP Documentation](https://docs.chain.link/ccip)
+- [CCIP Integration Guide](docs/CCIP_INTEGRATION.md)
+- [CCIP Message Format](docs/CCIP_MESSAGE_FORMAT.md)
+
--- a/docs/operations/integrations/CCIP_TROUBLESHOOTING.md
+++ b/docs/operations/integrations/CCIP_TROUBLESHOOTING.md
@@ -0,0 +1,223 @@
+# CCIP Troubleshooting Guide
+
+## Common Issues
+
+### Message Not Received
+
+**Symptoms**: Message sent but not received on target chain
+
+**Diagnosis**:
+1. Check message was sent successfully
+2. Verify target chain selector is correct
+3. Check receiver contract address
+4. Verify CCIP Router is operational
+5. Check LINK balance for fees
+
+**Solutions**:
+- Verify transaction hash on source chain
+- Check CCIP Router logs
+- Verify receiver contract is deployed
+- Ensure sufficient LINK tokens
+- Check target chain status
+
+### High Fees
+
+**Symptoms**: Fees are unexpectedly high
+
+**Diagnosis**:
+1. Check message size
+2. Monitor gas prices on target chain
+3. Verify fee calculation
+4. Check for network congestion
+
+**Solutions**:
+- Reduce message size
+- Wait for lower gas prices
+- Optimize message encoding
+- Consider batching updates
+
+### Replay Protection Errors
+
+**Symptoms**: "Message already processed" error
+
+**Diagnosis**:
+1. Check `processedMessages` mapping
+2. Verify message IDs are unique
+3. Check for duplicate sends
+
+**Solutions**:
+- Ensure message IDs are unique
+- Clear processed messages (if safe)
+- Check for duplicate transaction sends
+- Verify replay protection logic
+
+### Router Not Found
+
+**Symptoms**: "Router not found" or "Invalid router address"
+
+**Diagnosis**:
+1. Verify router address is correct
+2. Check router is deployed
+3. Verify network/chain ID matches
+
+**Solutions**:
+- Update router address in contracts
+- Deploy router if missing
+- Verify chain ID configuration
+- Check router deployment status
+
+### Insufficient LINK
+
+**Symptoms**: "Insufficient LINK balance" error
+
+**Diagnosis**:
+1. Check LINK token balance
+2. Verify token address is correct
+3. Check approval for spending
+
+**Solutions**:
+- Transfer more LINK tokens
+- Verify LINK token address
+- Approve contract to spend LINK
+- Check token contract is correct
+
+### Message Encoding Errors
+
+**Symptoms**: "Invalid message format" or decode failures
+
+**Diagnosis**:
+1. Check message encoding format
+2. Verify data types match
+3. Check for encoding errors
+
+**Solutions**:
+- Verify encoding matches expected format
+- Check data types are correct
+- Test encoding/decoding separately
+- Review message structure
+
+### Target Chain Unavailable
+
+**Symptoms**: Message fails to deliver, router unavailable
+
+**Diagnosis**:
+1. Check target chain status
+2. Verify router is operational
+3. Check network connectivity
+
+**Solutions**:
+- Wait for chain to recover
+- Check router health status
+- Verify network connectivity
+- Contact support if persistent
+
+## Diagnostic Commands
+
+### Check Router Status
+
+```bash
+# Check router is accessible
+cast call $CCIP_ROUTER "getSupportedTokens(uint64)" $CHAIN_SELECTOR --rpc-url $RPC_URL
+```
+
+### Check Message Status
+
+```bash
+# Check if message was processed
+cast call $RECEIVER "processedMessages(bytes32)" $MESSAGE_ID --rpc-url $RPC_URL
+```
+
+### Check LINK Balance
+
+```bash
+# Check LINK balance
+cast call $LINK_TOKEN "balanceOf(address)" $SENDER_CONTRACT --rpc-url $RPC_URL
+```
+
+### Calculate Fee
+
+```bash
+# Calculate fee for message
+cast call $SENDER "calculateFee(uint64,bytes)" $CHAIN_SELECTOR $MESSAGE_DATA --rpc-url $RPC_URL
+```
+
+## Monitoring
+
+### Key Metrics
+
+- Message send success rate
+- Message delivery latency
+- Fee consumption
+- Error rates
+- Router availability
+
+### Alerts
+
+Set up alerts for:
+- High error rates
+- Low success rates
+- High fees
+- Router unavailability
+- Low LINK balance
+
+## Logs
+
+### Check Contract Logs
+
+```bash
+# Get recent events
+cast logs --from-block latest-100 --address $SENDER_CONTRACT --rpc-url $RPC_URL
+```
+
+### Check Router Logs
+
+Check CCIP Router service logs for errors.
+
+## Recovery Procedures
+
+### Resend Failed Message
+
+1. Verify original message failed
+2. Check why it failed
+3. Fix underlying issue
+4. Resend message with new message ID
+
+### Clear Processed Messages
+
+**Warning**: Only if safe to do so
+
+```solidity
+// Admin function to clear processed messages (use with caution)
+function clearProcessedMessage(bytes32 messageId) external onlyAdmin {
+    delete processedMessages[messageId];
+}
+```
+
+### Emergency Pause
+
+If critical issues occur:
+
+```solidity
+// Pause message sending
+function pause() external onlyAdmin {
+    paused = true;
+    emit Paused();
+}
+```
+
+## Getting Help
+
+1. Check CCIP documentation
+2. Review contract code
+3. Check Chainlink status page
+4. Contact Chainlink support
+5. Review GitHub issues
+
+## References
+
+- [CCIP Integration Guide](docs/CCIP_INTEGRATION.md)
+- [CCIP Router Setup](docs/CCIP_ROUTER_SETUP.md)
+- [CCIP Message Format](docs/CCIP_MESSAGE_FORMAT.md)
+- [CCIP Fees](docs/CCIP_FEES.md)
+- [Chainlink CCIP Support](https://chain.link/support)
+
--- a/docs/operations/integrations/FIREFLY_INTEGRATION.md
+++ b/docs/operations/integrations/FIREFLY_INTEGRATION.md
@@ -0,0 +1,141 @@
+# Hyperledger Firefly Integration
+
+## Overview
+
+Hyperledger Firefly is integrated into the Besu network for tokenization and asset management. Firefly provides a high-level API for managing tokens, NFTs, and data on the blockchain.
+
+## Architecture
+
+### Components
+
+1. **Firefly Core**: Main Firefly service
+2. **PostgreSQL**: Database for Firefly
+3. **IPFS**: Distributed storage for Firefly data
+4. **Besu Connector**: Connects Firefly to Besu network
+
+### Network Integration
+
+- **Chain ID**: 138 (DeFi Oracle Meta Mainnet)
+- **RPC Endpoint**: Besu RPC nodes
+- **WebSocket Endpoint**: Besu WebSocket nodes
+
+## Deployment
+
+### Prerequisites
+
+- Kubernetes cluster (AKS)
+- Besu network deployed
+- RPC endpoints accessible
+
+### Deploy Firefly
+
+```bash
+# Deploy Firefly
+./scripts/deployment/deploy-firefly.sh
+
+# Or manually
+kubectl apply -f k8s/firefly/
+```
+
+### Verify Deployment
+
+```bash
+# Check Firefly status
+kubectl get pods -n firefly
+
+# Check Firefly API
+curl http://firefly-api.firefly.svc.cluster.local:5000/api/v1/status
+```
+
+## Configuration
+
+### Firefly Configuration
+
+Firefly is configured via ConfigMap (`k8s/firefly/configmap.yaml`):
+
+- **Database**: PostgreSQL
+- **Blockchain**: Ethereum (Besu)
+- **RPC**: Besu RPC endpoints
+- **Chain ID**: 138
+- **IPFS**: IPFS service for data storage
+
+### Environment Variables
+
+- `FF_DATABASE_TYPE`: postgres
+- `FF_DATABASE_URL`: PostgreSQL connection string
+- `FF_BLOCKCHAIN_TYPE`: ethereum
+- `FF_BLOCKCHAIN_RPC`: Besu RPC URL
+- `FF_BLOCKCHAIN_WS`: Besu WebSocket URL
+- `FF_CHAIN_ID`: 138
+
+## Usage
+
+### Create Token Pool
+
+```bash
+curl -X POST http://firefly-api.firefly.svc.cluster.local:5000/api/v1/tokens/pools \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "MyToken",
+    "symbol": "MTK",
+    "type": "fungible"
+  }'
+```
+
+### Mint Tokens
+
+```bash
+curl -X POST http://firefly-api.firefly.svc.cluster.local:5000/api/v1/tokens/mint \
+  -H "Content-Type: application/json" \
+  -d '{
+    "pool": "pool-id",
+    "amount": "1000",
+    "to": "0x..."
+  }'
+```
+
+### Create NFT
+
+```bash
+curl -X POST http://firefly-api.firefly.svc.cluster.local:5000/api/v1/tokens/nfts \
+  -H "Content-Type: application/json" \
+  -d '{
+    "pool": "pool-id",
+    "tokenId": "1",
+    "uri": "ipfs://...",
+    "to": "0x..."
+  }'
+```
+
+## Integration with Besu
+
+Firefly connects to Besu via:
+
+1. **RPC Endpoint**: HTTP JSON-RPC
+2. **WebSocket Endpoint**: WebSocket JSON-RPC
+3. **Chain ID**: 138
+
+### Besu-Firefly Connector
+
+The Besu-Firefly connector (`connectors/besu-firefly/connector.py`) provides:
+
+- Network registration
+- Contract deployment
+- Status monitoring
+
+## Tokenization
+
+Firefly enables tokenization of:
+
+- **Financial Files**: ISO-20022, SWIFT FIN
+- **Assets**: Real-world assets
+- **Data**: Any digital data
+
+See [Financial Tokenization Service](../services/financial-tokenization/) for details.
+
+## References
+
+- [Firefly Documentation](https://hyperledger.github.io/firefly/)
+- [Firefly API](https://hyperledger.github.io/firefly/api/)
+- [Firefly Tokens](https://hyperledger.github.io/firefly/tokens/)
+
--- a/docs/operations/integrations/INTEGRATIONS_INDEX.md
+++ b/docs/operations/integrations/INTEGRATIONS_INDEX.md
@@ -0,0 +1,87 @@
+# Integrations Index
+
+**Last Updated**: 2025-01-27  
+**Status**: Active
+
+This index organizes all integration documentation for the DeFi Oracle Meta Mainnet (ChainID 138).
+
+## Overview
+
+This project integrates with multiple external services and protocols. This index helps you find the right integration guide.
+
+## Integration Categories
+
+### CCIP Integration
+
+- **[CCIP Integration](CCIP_INTEGRATION.md)** - Complete CCIP integration guide
+- **[CCIP Router Setup](CCIP_ROUTER_SETUP.md)** - Setting up CCIP Router
+- **[CCIP Message Format](CCIP_MESSAGE_FORMAT.md)** - CCIP message format reference
+- **[CCIP Fees](CCIP_FEES.md)** - CCIP fee calculation and management
+- **[CCIP Troubleshooting](CCIP_TROUBLESHOOTING.md)** - CCIP troubleshooting guide
+- **[WETH CCIP Deployment](WETH_CCIP_DEPLOYMENT.md)** - Deploying WETH with CCIP
+
+### MetaMask Integration
+
+- **[MetaMask Integration](METAMASK_INTEGRATION.md)** - Complete MetaMask integration
+- **[MetaMask Developer Guide](METAMASK_DEVELOPER_GUIDE.md)** - Developer-focused guide
+- **[MetaMask Chainlist](METAMASK_CHAINLIST.md)** - Adding to Chainlist
+- **[MetaMask Portfolio](METAMASK_PORTFOLIO.md)** - Portfolio integration
+- **[MetaMask Safety](METAMASK_SAFETY.md)** - Safety and security
+- **[MetaMask Test Checklist](METAMASK_TEST_CHECKLIST.md)** - Testing checklist
+- **[MetaMask Gaps Analysis](METAMASK_GAPS_ANALYSIS.md)** - Gap analysis
+- **[MetaMask Bridge Swap](METAMASK_BRIDGE_SWAP.md)** - Bridge and swap integration
+- **[Blockscout MetaMask](BLOCKSCOUT_METAMASK.md)** - Blockscout integration
+
+### Other Integrations
+
+- **[Firefly Integration](FIREFLY_INTEGRATION.md)** - Hyperledger Firefly integration
+- **[Cacti Integration](CACTI_INTEGRATION.md)** - Hyperledger Cacti integration
+- **[Bridge Configuration](BRIDGE_CONFIGURATION.md)** - Bridge configuration
+
+### WETH Deployment
+
+- **[WETH Deployment Methods](WETH_DEPLOYMENT_METHODS.md)** - WETH deployment options
+- **[WETH CCIP Deployment](WETH_CCIP_DEPLOYMENT.md)** - WETH with CCIP
+
+## Quick Reference
+
+### I want to integrate CCIP
+
+1. Start with [CCIP Integration](CCIP_INTEGRATION.md)
+2. Follow [CCIP Router Setup](CCIP_ROUTER_SETUP.md)
+3. Review [CCIP Message Format](CCIP_MESSAGE_FORMAT.md)
+4. Check [CCIP Troubleshooting](CCIP_TROUBLESHOOTING.md) if issues
+
+### I want to integrate MetaMask
+
+1. Start with [MetaMask Integration](METAMASK_INTEGRATION.md)
+2. Follow [MetaMask Developer Guide](METAMASK_DEVELOPER_GUIDE.md)
+3. Add to [MetaMask Chainlist](METAMASK_CHAINLIST.md)
+4. Use [MetaMask Test Checklist](METAMASK_TEST_CHECKLIST.md)
+
+### I want to deploy WETH
+
+1. Review [WETH Deployment Methods](WETH_DEPLOYMENT_METHODS.md)
+2. Follow deployment guide for chosen method
+3. For CCIP: See [WETH CCIP Deployment](WETH_CCIP_DEPLOYMENT.md)
+
+## Integration Status
+
+| Integration | Status | Documentation |
+|-------------|--------|---------------|
+| CCIP | ✅ Complete | [CCIP Integration](CCIP_INTEGRATION.md) |
+| MetaMask | ✅ Complete | [MetaMask Integration](METAMASK_INTEGRATION.md) |
+| Firefly | ✅ Complete | [Firefly Integration](FIREFLY_INTEGRATION.md) |
+| Cacti | ✅ Complete | [Cacti Integration](CACTI_INTEGRATION.md) |
+| WETH | ✅ Complete | [WETH Deployment Methods](WETH_DEPLOYMENT_METHODS.md) |
+
+## Related Documentation
+
+- [Master Documentation Index](../../MASTER_DOCUMENTATION_INDEX.md)
+- [Integration Guide](../../guides/INTEGRATION_GUIDE.md)
+- [Getting Started](../../guides/GETTING_STARTED.md)
+
+---
+
+**Last Updated**: 2025-01-27
+
--- a/docs/operations/integrations/METAMASK_BD.md
+++ b/docs/operations/integrations/METAMASK_BD.md
@@ -0,0 +1,201 @@
+# MetaMask Business Development Guide
+
+Guide for engaging with Consensys/MetaMask for native feature support.
+
+## Overview
+
+This guide outlines the process for requesting native MetaMask feature support for ChainID 138, including Swaps, Bridge, and on-ramp integration.
+
+## Current Status
+
+ChainID 138 is **not** currently supported in:
+- MetaMask Swaps aggregator
+- MetaMask Portfolio Bridge
+- MetaMask Buy/Sell on-ramps
+
+## Contact Information
+
+### Consensys Business Development
+
+- **Website**: [consensys.io](https://consensys.io)
+- **Contact**: Business development team
+- **Email**: [To be provided]
+- **Twitter**: [@Consensys](https://twitter.com/Consensys)
+
+### MetaMask
+
+- **Website**: [metamask.io](https://metamask.io)
+- **Documentation**: [docs.metamask.io](https://docs.metamask.io)
+- **Support**: [support.metamask.io](https://support.metamask.io)
+
+## Integration Requirements
+
+### Swaps Integration
+
+**Requirements**:
+- Sufficient liquidity on ChainID 138
+- DEX integration with aggregator
+- Security audit completion
+- Regulatory compliance
+- User base and volume
+
+**Timeline**: 3-6 months (estimated)
+
+**Cost**: Negotiable (partnership terms)
+
+### Bridge Integration
+
+**Requirements**:
+- Bridge provider partnership
+- Security audit completion
+- Liquidity on both sides
+- Monitoring and alerts
+- Regulatory compliance
+
+**Timeline**: 3-6 months (estimated)
+
+**Cost**: Negotiable (partnership terms)
+
+### On-Ramp Integration
+
+**Requirements**:
+- On-ramp partner integration
+- Regulatory compliance
+- KYC/AML compliance
+- User experience optimization
+- Payment processing
+
+**Timeline**: 6-12 months (estimated)
+
+**Cost**: Negotiable (partnership terms)
+
+## Outreach Template
+
+### Initial Contact
+
+**Subject**: ChainID 138 Integration Request - DeFi Oracle Meta Mainnet
+
+**Body**:
+
+Dear Consensys Business Development Team,
+
+We are reaching out to request native MetaMask feature support for ChainID 138 (DeFi Oracle Meta Mainnet).
+
+**About ChainID 138**:
+- ChainID: 138 (0x8a)
+- Network: DeFi Oracle Meta Mainnet
+- Consensus: IBFT 2.0 (Istanbul BFT)
+- Block Time: ~2 seconds
+- Finality: Immediate (BFT)
+- RPC: https://rpc.d-bis.org
+- Explorer: https://explorer.d-bis.org
+
+**Current Status**:
+- Network is listed on Chainlist
+- Token list is published
+- Blockscout explorer is deployed
+- RPC endpoints are operational
+- User base is growing
+
+**Integration Request**:
+We would like to request integration for:
+1. MetaMask Swaps aggregator
+2. MetaMask Portfolio Bridge
+3. MetaMask Buy/Sell on-ramps
+
+**Next Steps**:
+We would appreciate the opportunity to discuss:
+- Integration requirements
+- Timeline and milestones
+- Partnership terms
+- Technical specifications
+
+Please let us know if you would like to schedule a call to discuss this further.
+
+Best regards,
+[Your Name]
+[Your Organization]
+
+## Proposal Template
+
+### Executive Summary
+
+- **Network**: DeFi Oracle Meta Mainnet (ChainID 138)
+- **Use Case**: Oracle data aggregation and cross-chain oracle synchronization
+- **User Base**: [Number] users
+- **Volume**: [Transaction volume]
+- **Liquidity**: [Liquidity metrics]
+
+### Technical Specifications
+
+- **ChainID**: 138
+- **Consensus**: IBFT 2.0
+- **Block Time**: ~2 seconds
+- **Finality**: Immediate
+- **RPC Endpoints**: 2+ high-availability endpoints
+- **Explorer**: Blockscout with full API
+- **Token List**: Official token list published
+
+### Integration Plan
+
+1. **Phase 1**: Swaps integration (3-6 months)
+2. **Phase 2**: Bridge integration (3-6 months)
+3. **Phase 3**: On-ramp integration (6-12 months)
+
+### Benefits
+
+- **User Experience**: Seamless wallet integration
+- **Liquidity**: Access to MetaMask's user base
+- **Visibility**: Increased network visibility
+- **Adoption**: Faster network adoption
+
+## Regulatory Considerations
+
+### Swaps
+
+- **SEC Scrutiny**: Swaps have been under SEC scrutiny
+- **Compliance**: Ensure regulatory compliance
+- **Legal Review**: Legal review required
+- **Risk Assessment**: Risk assessment required
+
+### Bridge
+
+- **Security**: Security audit required
+- **Regulatory**: Regulatory compliance required
+- **Monitoring**: Monitoring and alerts required
+- **Risk Management**: Risk management required
+
+### On-Ramp
+
+- **KYC/AML**: KYC/AML compliance required
+- **Regulatory**: Regulatory compliance required
+- **Payment Processing**: Payment processing compliance
+- **User Protection**: User protection measures
+
+## Tracking
+
+### Milestones
+
+- [ ] Initial contact made
+- [ ] Proposal submitted
+- [ ] Technical discussion scheduled
+- [ ] Partnership agreement signed
+- [ ] Integration development started
+- [ ] Testing completed
+- [ ] Integration launched
+
+### Updates
+
+Track updates and communications:
+
+- **Date**: ___________
+- **Update**: ___________
+- **Next Steps**: ___________
+
+## References
+
+- [MetaMask Documentation](https://docs.metamask.io)
+- [Consensys Website](https://consensys.io)
+- [MetaMask Support](https://support.metamask.io)
+- [SEC Swaps Scrutiny](https://www.reuters.com/legal/us-sec-sues-blockchain-software-technology-company-consensys-2024-06-28/)
+
--- a/docs/operations/integrations/METAMASK_BRIDGE_SWAP.md
+++ b/docs/operations/integrations/METAMASK_BRIDGE_SWAP.md
@@ -0,0 +1,195 @@
+# MetaMask Bridge & Swap Support for ChainID 138
+
+Current status and workarounds for Bridge and Swap features on ChainID 138.
+
+## Current Status
+
+ChainID 138 is **not** currently supported in MetaMask's native Swaps and Bridge features. Users must use third-party bridges and DEXs until native support is added.
+
+## Swaps (In-Wallet Aggregator)
+
+### Current Limitation
+
+MetaMask Swaps supports a fixed set of networks:
+- Ethereum
+- BNB Chain
+- Polygon
+- Avalanche
+- Optimism
+- Arbitrum
+- zkSync Era
+- Linea
+- Base
+- Sei
+
+ChainID 138 is **not** on this list, so the in-wallet Swaps button will not aggregate quotes natively.
+
+### Workaround: Use DEX UI
+
+Users can swap tokens via DEX UIs that support ChainID 138:
+
+1. **Connect to ChainID 138**: Add network to MetaMask
+2. **Navigate to DEX**: Open DEX that supports ChainID 138
+3. **Connect Wallet**: Connect MetaMask wallet
+4. **Execute Swap**: Execute swap through DEX UI
+
+### Recommended DEXs
+
+List DEXs that support ChainID 138 (to be populated after DEX deployment):
+
+- **DEX 1**: [URL] - Description
+- **DEX 2**: [URL] - Description
+
+## Bridge (Portfolio Bridge)
+
+### Current Limitation
+
+MetaMask Portfolio Bridge supports a curated network set:
+- Ethereum
+- BNB Chain
+- Linea
+- Polygon
+- Arbitrum
+- Optimism
+- Avalanche
+- Base
+- zkSync Era
+
+ChainID 138 is **not** currently supported.
+
+### Workaround: Use Third-Party Bridges
+
+Users must bridge via third-party bridges until native support is added.
+
+### Recommended Bridges
+
+List bridges that support ChainID 138 (to be populated after bridge deployment):
+
+- **Bridge 1**: [URL] - Description
+- **Bridge 2**: [URL] - Description
+
+### Bridge Integration Requirements
+
+For bridges to work with ChainID 138:
+
+1. **Network Support**: Bridge must support ChainID 138
+2. **Liquidity**: Sufficient liquidity on both sides
+3. **Security**: Audited bridge contracts
+4. **Monitoring**: Bridge monitoring and alerts
+
+## Buy/Sell (Fiat On/Off-Ramp)
+
+### Current Limitation
+
+MetaMask's on-/off-ramp partners only support certain chains/tokens. ChainID 138 assets are not currently supported.
+
+### Workaround: Bridge from Supported Chains
+
+1. **Buy on Supported Chain**: Buy ETH/tokens on a supported chain (Ethereum, etc.)
+2. **Bridge to ChainID 138**: Use third-party bridge to bridge to ChainID 138
+3. **Use on ChainID 138**: Use bridged assets on ChainID 138
+
+### Alternative: CEX Withdrawal
+
+1. **Buy on CEX**: Buy ETH/tokens on centralized exchange
+2. **Withdraw to ChainID 138**: Withdraw directly to ChainID 138 address (if supported)
+3. **Use on ChainID 138**: Use withdrawn assets on ChainID 138
+
+### Recommended On-Ramp Partners
+
+List on-ramp partners that support ChainID 138 (to be populated):
+
+- **Partner 1**: [URL] - Description
+- **Partner 2**: [URL] - Description
+
+## How to Fund ChainID 138
+
+### Method 1: Bridge from Ethereum
+
+1. **Bridge Provider**: Use a bridge that supports Ethereum → ChainID 138
+2. **Connect Wallets**: Connect MetaMask wallets for both chains
+3. **Initiate Bridge**: Initiate bridge transaction
+4. **Wait for Confirmation**: Wait for bridge confirmation
+5. **Receive on ChainID 138**: Receive bridged assets on ChainID 138
+
+### Method 2: CEX Withdrawal
+
+1. **Buy on CEX**: Buy ETH on centralized exchange
+2. **Withdraw**: Withdraw to ChainID 138 address (if supported)
+3. **Wait for Confirmation**: Wait for withdrawal confirmation
+4. **Receive on ChainID 138**: Receive assets on ChainID 138
+
+### Method 3: Peer-to-Peer
+
+1. **Find Seller**: Find someone willing to sell ETH on ChainID 138
+2. **Arrange Transfer**: Arrange transfer via trusted method
+3. **Receive Assets**: Receive assets on ChainID 138
+
+## Path to Native Support
+
+### Swaps Integration
+
+To enable native Swaps support:
+
+1. **Business Development**: Engage with Consensys for partnership
+2. **Liquidity Requirements**: Ensure sufficient liquidity for aggregator
+3. **DEX Integration**: Integrate with DEXs on ChainID 138
+4. **Testing**: Test swap functionality
+5. **Regulatory Compliance**: Ensure regulatory compliance
+
+### Bridge Integration
+
+To enable native Bridge support:
+
+1. **Business Development**: Engage with Consensys for partnership
+2. **Bridge Providers**: Partner with bridge providers
+3. **Security Audit**: Complete security audit
+4. **Testing**: Test bridge functionality
+5. **Monitoring**: Set up bridge monitoring
+
+### On-Ramp Integration
+
+To enable native on-ramp support:
+
+1. **Partner Integration**: Partner with on-ramp providers
+2. **Regulatory Compliance**: Ensure regulatory compliance
+3. **Testing**: Test on-ramp functionality
+4. **User Experience**: Optimize user experience
+
+## Business Development
+
+### Consensys Outreach
+
+1. **Initial Contact**: Reach out to Consensys business development
+2. **Proposal**: Submit integration proposal
+3. **Requirements**: Discuss requirements and timeline
+4. **Partnership**: Establish partnership agreement
+5. **Implementation**: Implement integration
+
+### Tracking
+
+- Monitor MetaMask feature updates
+- Track network support announcements
+- Engage with Consensys regularly
+- Submit feature requests
+
+## Documentation
+
+### User Guides
+
+- **How to Bridge to ChainID 138**: Step-by-step bridge guide
+- **How to Swap on ChainID 138**: Step-by-step swap guide
+- **How to Fund ChainID 138**: Funding options guide
+
+### Developer Guides
+
+- **Bridge Integration**: How to integrate bridges
+- **DEX Integration**: How to integrate DEXs
+- **On-Ramp Integration**: How to integrate on-ramps
+
+## References
+
+- [MetaMask Swaps](https://support.metamask.io/manage-crypto/move-crypto/swap/user-guide-swaps/)
+- [MetaMask Portfolio Bridge](https://portfolio.metamask.io/bridge)
+- [Consensys Business Development](https://consensys.io)
+
--- a/docs/operations/integrations/METAMASK_CHAINLIST.md
+++ b/docs/operations/integrations/METAMASK_CHAINLIST.md
@@ -0,0 +1,41 @@
+# Chainlist Status for ChainID 138
+
+## Current Status
+
+ChainID 138 (DeFi Oracle Meta Mainnet) is listed on Chainlist and chainid.network.
+
+## Verification Checklist
+
+- [ ] Verify entry on [chainlist.org/chain/138](https://chainlist.org/chain/138)
+- [ ] Verify entry on [chainid.network/chain/138](https://chainid.network/chain/138)
+- [ ] Confirm RPC URLs are accessible and have high availability
+- [ ] Confirm explorer URL is accessible
+- [ ] Verify network metadata matches production configuration
+- [ ] Test "Add to MetaMask" button on Chainlist
+
+## Network Metadata
+
+- **ChainID**: 138 (0x8a)
+- **Chain Name**: DeFi Oracle Meta Mainnet
+- **Native Currency**: ETH (18 decimals)
+- **RPC URLs**:
+  - Primary: `https://rpc.d-bis.org`
+  - Secondary: `https://rpc2.d-bis.org`
+  - WebSocket: `wss://rpc.d-bis.org`
+- **Block Explorer**: `https://explorer.d-bis.org`
+- **Domain**: `d-bis.org` (Cloudflare DNS/SSL)
+
+## Update Process
+
+1. Update metadata in `metamask/ethereum-lists-chain.json`
+2. Submit PR to [ethereum-lists/chains](https://github.com/ethereum-lists/chains)
+3. Verify Chainlist automatically updates from ethereum-lists
+4. Test network addition via Chainlist
+
+## Monitoring
+
+- Monitor RPC endpoint uptime (target: ≥99.9%)
+- Monitor explorer availability
+- Track user reports of network addition issues
+- Update metadata when RPC endpoints change
+
--- a/docs/operations/integrations/METAMASK_DEVELOPER_GUIDE.md
+++ b/docs/operations/integrations/METAMASK_DEVELOPER_GUIDE.md
@@ -0,0 +1,309 @@
+# MetaMask Developer Guide for ChainID 138
+
+Developer guide for integrating ChainID 138 with MetaMask in your dapp.
+
+## Installation
+
+### Using npm
+
+```bash
+npm install @defi-oracle/metamask-sdk
+```
+
+### Using the source
+
+```bash
+cd metamask-sdk
+npm install
+npm run build
+```
+
+## Basic Usage
+
+### Import the SDK
+
+```typescript
+import {
+  addOrSwitchNetwork,
+  addToken,
+  isOnChain138,
+  getCurrentChainId,
+} from '@defi-oracle/metamask-sdk';
+```
+
+### Connect to ChainID 138
+
+```typescript
+async function connect() {
+  try {
+    await addOrSwitchNetwork();
+    const isOn138 = await isOnChain138();
+    if (isOn138) {
+      console.log('Connected to ChainID 138');
+    }
+  } catch (error) {
+    console.error('Connection error:', error);
+  }
+}
+```
+
+### Add Token
+
+```typescript
+async function addWETHToken() {
+  try {
+    await addToken(
+      '0xYourWETHAddress',
+      'WETH',
+      18,
+      'https://explorer.d-bis.org/images/tokens/weth.png'
+    );
+  } catch (error) {
+    console.error('Token add error:', error);
+  }
+}
+```
+
+## React Integration
+
+### Custom Hook
+
+```typescript
+import { useState, useEffect } from 'react';
+import { isOnChain138, addOrSwitchNetwork } from '@defi-oracle/metamask-sdk';
+
+function useChain138() {
+  const [isConnected, setIsConnected] = useState(false);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    checkConnection();
+    
+    // Listen for chain changes
+    if (window.ethereum) {
+      window.ethereum.on('chainChanged', checkConnection);
+      return () => {
+        window.ethereum.removeListener('chainChanged', checkConnection);
+      };
+    }
+  }, []);
+
+  async function checkConnection() {
+    try {
+      const on138 = await isOnChain138();
+      setIsConnected(on138);
+    } catch (error) {
+      setIsConnected(false);
+    } finally {
+      setIsLoading(false);
+    }
+  }
+
+  async function connect() {
+    try {
+      await addOrSwitchNetwork();
+      await checkConnection();
+    } catch (error) {
+      console.error('Connection error:', error);
+    }
+  }
+
+  return { isConnected, isLoading, connect };
+}
+```
+
+### React Component
+
+```typescript
+import React from 'react';
+import { useChain138 } from './useChain138';
+
+function Chain138Button() {
+  const { isConnected, isLoading, connect } = useChain138();
+
+  if (isLoading) {
+    return <button disabled>Loading...</button>;
+  }
+
+  if (isConnected) {
+    return <button disabled>Connected to ChainID 138</button>;
+  }
+
+  return (
+    <button onClick={connect}>
+      Connect to ChainID 138
+    </button>
+  );
+}
+```
+
+## Vue Integration
+
+### Composable
+
+```typescript
+import { ref, onMounted, onUnmounted } from 'vue';
+import { isOnChain138, addOrSwitchNetwork } from '@defi-oracle/metamask-sdk';
+
+export function useChain138() {
+  const isConnected = ref(false);
+  const isLoading = ref(true);
+
+  async function checkConnection() {
+    try {
+      const on138 = await isOnChain138();
+      isConnected.value = on138;
+    } catch (error) {
+      isConnected.value = false;
+    } finally {
+      isLoading.value = false;
+    }
+  }
+
+  async function connect() {
+    try {
+      await addOrSwitchNetwork();
+      await checkConnection();
+    } catch (error) {
+      console.error('Connection error:', error);
+    }
+  }
+
+  function handleChainChanged() {
+    checkConnection();
+  }
+
+  onMounted(() => {
+    checkConnection();
+    if (window.ethereum) {
+      window.ethereum.on('chainChanged', handleChainChanged);
+    }
+  });
+
+  onUnmounted(() => {
+    if (window.ethereum) {
+      window.ethereum.removeListener('chainChanged', handleChainChanged);
+    }
+  });
+
+  return { isConnected, isLoading, connect };
+}
+```
+
+## Error Handling
+
+### Common Errors
+
+```typescript
+import { addNetwork } from '@defi-oracle/metamask-sdk';
+
+try {
+  await addNetwork();
+} catch (error) {
+  if (error.message.includes('MetaMask is not installed')) {
+    // Handle MetaMask not installed
+    alert('Please install MetaMask');
+  } else if (error.message.includes('User rejected')) {
+    // Handle user rejection
+    console.log('User rejected the request');
+  } else if (error.code === 4902) {
+    // Network already added, try switching
+    await switchNetwork();
+  } else {
+    // Handle other errors
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+## RPC Best Practices
+
+### Rate Limiting
+
+- Default: 1200 requests/minute per IP
+- Use request batching when possible
+- Implement client-side rate limiting
+- Use WebSocket connections for real-time data
+
+### Request Batching
+
+```typescript
+const batch = [
+  { method: 'eth_blockNumber', params: [] },
+  { method: 'eth_gasPrice', params: [] },
+  { method: 'eth_getBalance', params: [address, 'latest'] },
+];
+
+const results = await Promise.all(
+  batch.map(req => window.ethereum.request(req))
+);
+```
+
+### WebSocket Connections
+
+```typescript
+const ws = new WebSocket('wss://rpc.d-bis.org');
+
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log('Received:', data);
+};
+
+ws.send(JSON.stringify({
+  jsonrpc: '2.0',
+  method: 'eth_subscribe',
+  params: ['newHeads'],
+  id: 1
+}));
+```
+
+## Testing
+
+### Mock MetaMask for Testing
+
+```typescript
+// mock-metamask.ts
+export function createMockMetaMask() {
+  return {
+    isMetaMask: true,
+    request: async (args: { method: string; params?: unknown[] }) => {
+      if (args.method === 'eth_chainId') {
+        return '0x8a';
+      }
+      if (args.method === 'wallet_addEthereumChain') {
+        return null;
+      }
+      if (args.method === 'wallet_switchEthereumChain') {
+        return null;
+      }
+      throw new Error('Method not implemented');
+    },
+    on: () => {},
+    removeListener: () => {},
+  };
+}
+
+// In your tests
+global.window.ethereum = createMockMetaMask();
+```
+
+## Production Checklist
+
+- [ ] Verify RPC URLs are correct and accessible
+- [ ] Test network addition on all target browsers
+- [ ] Test token addition for all tokens
+- [ ] Verify error handling for all error cases
+- [ ] Test network switching functionality
+- [ ] Verify chain change event listeners
+- [ ] Test on mobile MetaMask
+- [ ] Verify token logos are accessible
+- [ ] Test with different MetaMask versions
+- [ ] Verify CORS headers on RPC endpoints
+
+## References
+
+- [MetaMask SDK Documentation](../metamask-sdk/README.md)
+- [MetaMask Integration Guide](./METAMASK_INTEGRATION.md)
+- [Quick Start Guide](../metamask/QUICK_START.md)
+- [MetaMask Documentation](https://docs.metamask.io)
+
--- a/docs/operations/integrations/METAMASK_GAPS_ANALYSIS.md
+++ b/docs/operations/integrations/METAMASK_GAPS_ANALYSIS.md
@@ -0,0 +1,248 @@
+# MetaMask Integration Gaps Analysis
+
+Comprehensive gap analysis for MetaMask integration with ChainID 138.
+
+## Overview
+
+This document identifies gaps in the MetaMask integration implementation and provides recommendations for addressing them.
+
+## Completed Tasks
+
+### ✅ Phase A - Foundations (Self-Serve)
+
+All Phase A tasks have been completed:
+
+1. ✅ **Network Metadata**: Created network-metadata.json and ethereum-lists-chain.json
+2. ✅ **Token List**: Created official token list with schema validation
+3. ✅ **MetaMask SDK**: Created complete SDK package with all functions
+4. ✅ **Documentation**: Created comprehensive user and developer documentation
+5. ✅ **Examples**: Created React and Vanilla JS examples
+6. ✅ **Tests**: Created unit tests and E2E tests
+7. ✅ **CORS Configuration**: Updated Blockscout and Application Gateway for CORS
+8. ✅ **Domain Migration**: Updated all files to use d-bis.org domain
+9. ✅ **Ethereum-Lists PR**: Created PR template and submission guide
+10. ✅ **Token List Submissions**: Created tracking document
+11. ✅ **Phishing Detection**: Created check guide
+12. ✅ **RPC SLO**: Created service level objectives documentation
+13. ✅ **Blockscout API**: Created API documentation
+14. ✅ **Portfolio Compatibility**: Created compatibility documentation
+15. ✅ **Bridge/Swap Docs**: Created documentation with workarounds
+16. ✅ **Business Development**: Created Consensys outreach guide
+17. ✅ **SDK Integration**: Integrated MetaMask SDK into main SDK
+18. ✅ **Environment Configuration**: Created .env.example with Cloudflare and Azure secrets
+19. ✅ **Circular Dependencies**: Fixed import circular dependencies
+20. ✅ **README Updates**: Updated README with MetaMask integration section
+21. ✅ **GitHub Actions**: Created workflow for token list validation
+22. ✅ **E2E Testing**: Tested all MetaMask integration functions
+23. ✅ **Production Config**: Updated production-config.yaml with d-bis.org URLs
+24. ✅ **Blockscout CORS**: Updated Blockscout deployment with MetaMask CORS config
+25. ✅ **Application Gateway CORS**: Updated Application Gateway for CORS headers
+
+## Identified Gaps
+
+### 🔴 Critical Gaps (Must Address)
+
+#### 1. Production RPC Endpoints Not Deployed
+
+**Status**: ⚠️ Not Deployed
+**Priority**: 🔴 Critical
+**Impact**: High - MetaMask cannot connect to ChainID 138 without RPC endpoints
+**Recommendation**: Deploy RPC endpoints at https://rpc.d-bis.org and https://rpc2.d-bis.org
+
+#### 2. Blockscout Explorer Not Deployed
+
+**Status**: ⚠️ Not Deployed
+**Priority**: 🔴 Critical
+**Impact**: High - Users cannot verify transactions or view token metadata
+**Recommendation**: Deploy Blockscout explorer at https://explorer.d-bis.org
+
+#### 3. Token Contracts Not Deployed
+
+**Status**: ⚠️ Not Deployed
+**Priority**: 🔴 Critical
+**Impact**: High - Token list references tokens that don't exist on-chain
+**Recommendation**: Deploy WETH and other tokens, update token-list.json with actual addresses
+
+#### 4. Ethereum-Lists PR Not Submitted
+
+**Status**: ⚠️ Not Submitted
+**Priority**: 🔴 Critical
+**Impact**: High - ChainID 138 not available on Chainlist
+**Recommendation**: Submit PR to ethereum-lists/chains repository
+
+#### 5. Token List Not Submitted to Aggregators
+
+**Status**: ⚠️ Not Submitted
+**Priority**: 🔴 Critical
+**Impact**: High - Tokens not auto-detected in MetaMask Portfolio
+**Recommendation**: Submit token list to CoinGecko, Uniswap, and other aggregators
+
+### 🟡 High Priority Gaps (Should Address)
+
+#### 6. Cloudflare DNS Configuration Not Completed
+
+**Status**: ⚠️ Not Completed
+**Priority**: 🟡 High
+**Impact**: Medium - Domain d-bis.org not configured
+**Recommendation**: Configure Cloudflare DNS for d-bis.org domain
+
+#### 7. SSL Certificates Not Configured
+
+**Status**: ⚠️ Not Configured
+**Priority**: 🟡 High
+**Impact**: Medium - HTTPS endpoints not accessible
+**Recommendation**: Configure SSL certificates via Cloudflare
+
+#### 8. Azure Application Gateway Not Deployed
+
+**Status**: ⚠️ Not Deployed
+**Priority**: 🟡 High
+**Impact**: Medium - RPC endpoints not accessible via Application Gateway
+**Recommendation**: Deploy Azure Application Gateway with CORS configuration
+
+#### 9. Blockscout CORS Configuration Not Applied
+
+**Status**: ⚠️ Not Applied
+**Priority**: 🟡 High
+**Impact**: Medium - MetaMask Portfolio cannot access Blockscout API
+**Recommendation**: Apply Blockscout CORS configuration in production
+
+#### 10. Token Logos Not Hosted
+
+**Status**: ⚠️ Not Hosted
+**Priority**: 🟡 High
+**Impact**: Medium - Token logos not displayed in MetaMask
+**Recommendation**: Host token logos at https://explorer.d-bis.org/images/tokens/
+
+### 🟢 Medium Priority Gaps (Nice to Have)
+
+#### 11. MetaMask Portfolio Integration Not Tested
+
+**Status**: ⚠️ Not Tested
+**Priority**: 🟢 Medium
+**Impact**: Low - Portfolio compatibility not verified
+**Recommendation**: Test Portfolio read-only features after deployment
+
+#### 12. Bridge Integration Not Implemented
+
+**Status**: ⚠️ Not Implemented
+**Priority**: 🟢 Medium
+**Impact**: Low - Users cannot bridge to ChainID 138
+**Recommendation**: Implement bridge integration or partner with bridge providers
+
+#### 13. DEX Integration Not Implemented
+
+**Status**: ⚠️ Not Implemented
+**Priority**: 🟢 Medium
+**Impact**: Low - Users cannot swap tokens on ChainID 138
+**Recommendation**: Implement DEX integration or partner with DEX providers
+
+#### 14. On-Ramp Integration Not Implemented
+
+**Status**: ⚠️ Not Implemented
+**Priority**: 🟢 Medium
+**Impact**: Low - Users cannot buy tokens with fiat
+**Recommendation**: Partner with on-ramp providers (MoonPay, Ramp, etc.)
+
+#### 15. Consensys Outreach Not Initiated
+
+**Status**: ⚠️ Not Initiated
+**Priority**: 🟢 Medium
+**Impact**: Low - Native MetaMask features not available
+**Recommendation**: Initiate Consensys outreach for Swaps and Bridge integration
+
+## Recommendations
+
+### Immediate Actions (Week 1)
+
+1. **Deploy RPC Endpoints**: Deploy RPC endpoints at https://rpc.d-bis.org and https://rpc2.d-bis.org
+2. **Deploy Blockscout**: Deploy Blockscout explorer at https://explorer.d-bis.org
+3. **Configure Cloudflare DNS**: Configure DNS for d-bis.org domain
+4. **Configure SSL Certificates**: Configure SSL certificates via Cloudflare
+5. **Deploy Token Contracts**: Deploy WETH and update token-list.json
+
+### Short-Term Actions (Month 1)
+
+1. **Submit Ethereum-Lists PR**: Submit PR to ethereum-lists/chains
+2. **Submit Token List**: Submit token list to CoinGecko and Uniswap
+3. **Apply CORS Configuration**: Apply Blockscout and Application Gateway CORS configuration
+4. **Host Token Logos**: Host token logos at Blockscout
+5. **Test Portfolio Integration**: Test MetaMask Portfolio compatibility
+
+### Long-Term Actions (Quarter 1)
+
+1. **Bridge Integration**: Implement or partner with bridge providers
+2. **DEX Integration**: Implement or partner with DEX providers
+3. **On-Ramp Integration**: Partner with on-ramp providers
+4. **Consensys Outreach**: Initiate Consensys outreach for native features
+5. **User Testing**: Conduct user testing of MetaMask integration
+
+## Testing Checklist
+
+### Pre-Production Testing
+
+- [ ] RPC endpoints are accessible
+- [ ] Blockscout explorer is accessible
+- [ ] Token contracts are deployed
+- [ ] Token list is accurate
+- [ ] CORS headers are configured
+- [ ] SSL certificates are valid
+- [ ] Token logos are accessible
+- [ ] Network addition works in MetaMask
+- [ ] Token addition works in MetaMask
+- [ ] Portfolio compatibility is verified
+
+### Post-Production Testing
+
+- [ ] Ethereum-lists PR is merged
+- [ ] Token list is accepted by aggregators
+- [ ] Chainlist displays ChainID 138 correctly
+- [ ] MetaMask Portfolio displays tokens correctly
+- [ ] Bridge integration works (if implemented)
+- [ ] DEX integration works (if implemented)
+- [ ] On-ramp integration works (if implemented)
+- [ ] User feedback is positive
+- [ ] No critical issues reported
+
+## Success Metrics
+
+### Phase A - Foundations
+
+- ✅ Network metadata created
+- ✅ Token list created
+- ✅ SDK package created
+- ✅ Documentation created
+- ✅ Examples created
+- ✅ Tests created
+- ✅ CORS configuration created
+- ✅ Domain migration completed
+
+### Phase B - Deployment
+
+- [ ] RPC endpoints deployed
+- [ ] Blockscout explorer deployed
+- [ ] Token contracts deployed
+- [ ] Ethereum-lists PR submitted
+- [ ] Token list submitted
+- [ ] CORS configuration applied
+- [ ] Token logos hosted
+
+### Phase C - Integration
+
+- [ ] Portfolio compatibility verified
+- [ ] Bridge integration implemented
+- [ ] DEX integration implemented
+- [ ] On-ramp integration implemented
+- [ ] Consensys outreach initiated
+
+## Conclusion
+
+All Phase A tasks (foundations) have been completed. The main gaps are in deployment and integration:
+
+1. **Deployment**: RPC endpoints, Blockscout, and token contracts need to be deployed
+2. **Integration**: Ethereum-lists PR and token list submissions need to be completed
+3. **Testing**: Portfolio compatibility and user testing need to be conducted
+4. **Partnerships**: Bridge, DEX, and on-ramp partnerships need to be established
+
+The MetaMask integration is **code-complete** but requires **deployment and operational procedures** to be fully functional.
+
--- a/docs/operations/integrations/METAMASK_INTEGRATION.md
+++ b/docs/operations/integrations/METAMASK_INTEGRATION.md
@@ -0,0 +1,241 @@
+# MetaMask Integration Guide
+
+Complete guide for integrating ChainID 138 (DeFi Oracle Meta Mainnet) with MetaMask.
+
+## Overview
+
+This guide covers how to add ChainID 138 to MetaMask, add tokens, and integrate wallet functionality into your dapp.
+
+## Network Information
+
+- **ChainID**: 138 (0x8a in hex)
+- **Chain Name**: DeFi Oracle Meta Mainnet
+- **Native Currency**: ETH (18 decimals)
+- **RPC URLs**:
+  - Primary: `https://rpc.d-bis.org`
+  - Secondary: `https://rpc2.d-bis.org`
+  - WebSocket: `wss://rpc.d-bis.org`
+- **Block Explorer**: `https://explorer.d-bis.org`
+- **Domain**: `d-bis.org` (Cloudflare DNS/SSL)
+
+## Adding the Network
+
+### Option 1: Using the MetaMask SDK
+
+```typescript
+import { addOrSwitchNetwork } from '@defi-oracle/metamask-sdk';
+
+// Add or switch to ChainID 138
+await addOrSwitchNetwork();
+```
+
+### Option 2: Using wallet_addEthereumChain
+
+```javascript
+await window.ethereum.request({
+  method: 'wallet_addEthereumChain',
+  params: [{
+    chainId: '0x8a',
+    chainName: 'DeFi Oracle Meta Mainnet',
+    nativeCurrency: {
+      name: 'Ether',
+      symbol: 'ETH',
+      decimals: 18
+    },
+    rpcUrls: ['https://rpc.d-bis.org', 'https://rpc2.d-bis.org'],
+    blockExplorerUrls: ['https://explorer.d-bis.org'],
+    iconUrls: ['https://explorer.d-bis.org/images/logo.png']
+  }]
+});
+```
+
+### Option 3: Using Chainlist
+
+1. Visit [chainlist.org](https://chainlist.org)
+2. Search for "ChainID 138" or "DeFi Oracle Meta"
+3. Click "Add to MetaMask"
+4. Approve the network addition in MetaMask
+
+### Option 4: Manual Addition
+
+1. Open MetaMask
+2. Click the network dropdown
+3. Click "Add Network"
+4. Click "Add a network manually"
+5. Enter the network details:
+   - Network Name: DeFi Oracle Meta Mainnet
+   - RPC URL: `https://rpc.d-bis.org`
+   - Chain ID: 138
+   - Currency Symbol: ETH
+   - Block Explorer URL: `https://explorer.d-bis.org`
+
+## Switching Networks
+
+```javascript
+await window.ethereum.request({
+  method: 'wallet_switchEthereumChain',
+  params: [{ chainId: '0x8a' }]
+});
+```
+
+## Adding Tokens
+
+### Using the SDK
+
+```typescript
+import { addToken } from '@defi-oracle/metamask-sdk';
+
+await addToken(
+  '0xYourTokenAddress',
+  'WETH',
+  18,
+  'https://explorer.d-bis.org/images/tokens/weth.png'
+);
+```
+
+### Using wallet_watchAsset (EIP-747)
+
+```javascript
+await window.ethereum.request({
+  method: 'wallet_watchAsset',
+  params: {
+    type: 'ERC20',
+    options: {
+      address: '0xYourTokenAddress',
+      symbol: 'WETH',
+      decimals: 18,
+      image: 'https://explorer.d-bis.org/images/tokens/weth.png'
+    }
+  }
+});
+```
+
+## Checking Current Network
+
+```javascript
+const chainId = await window.ethereum.request({ method: 'eth_chainId' });
+if (chainId === '0x8a') {
+  console.log('Connected to ChainID 138');
+}
+```
+
+## Listening to Network Changes
+
+```javascript
+window.ethereum.on('chainChanged', (chainId) => {
+  if (chainId === '0x8a') {
+    console.log('Switched to ChainID 138');
+  } else {
+    console.log('Switched to another network');
+  }
+});
+```
+
+## Complete Integration Example
+
+```javascript
+async function connectToChain138() {
+  // Check if MetaMask is installed
+  if (typeof window.ethereum === 'undefined') {
+    alert('Please install MetaMask');
+    return;
+  }
+
+  try {
+    // Get current chain ID
+    const chainId = await window.ethereum.request({ method: 'eth_chainId' });
+
+    // If not on ChainID 138, switch or add
+    if (chainId !== '0x8a') {
+      try {
+        // Try to switch first
+        await window.ethereum.request({
+          method: 'wallet_switchEthereumChain',
+          params: [{ chainId: '0x8a' }]
+        });
+      } catch (error) {
+        // If switch fails, network might not be added
+        if (error.code === 4902) {
+          // Add the network
+          await window.ethereum.request({
+            method: 'wallet_addEthereumChain',
+            params: [{
+              chainId: '0x8a',
+              chainName: 'DeFi Oracle Meta Mainnet',
+              nativeCurrency: {
+                name: 'Ether',
+                symbol: 'ETH',
+                decimals: 18
+              },
+              rpcUrls: ['https://rpc.d-bis.org'],
+              blockExplorerUrls: ['https://explorer.d-bis.org']
+            }]
+          });
+        } else {
+          throw error;
+        }
+      }
+    }
+
+    console.log('Connected to ChainID 138');
+  } catch (error) {
+    console.error('Error connecting to ChainID 138:', error);
+  }
+}
+```
+
+## Token List
+
+See the official token list at: `metamask/token-list.json`
+
+Tokens are automatically detected by MetaMask when they appear on 2+ reputable token lists. To enable auto-detection:
+
+1. Add your token to the official token list
+2. Submit the token list to reputable aggregators (CoinGecko, etc.)
+3. Ensure token metadata is available on Blockscout
+
+## Troubleshooting
+
+### MetaMask not detected
+
+```javascript
+if (typeof window.ethereum === 'undefined') {
+  alert('Please install MetaMask');
+  window.open('https://metamask.io/download/', '_blank');
+}
+```
+
+### Network already added
+
+If you get an error that the network is already added, use `wallet_switchEthereumChain` instead.
+
+### RPC endpoint errors
+
+- Verify RPC URL is correct: `https://rpc.d-bis.org`
+- Check network connectivity
+- Verify RPC node is running and accessible
+- Check firewall/security settings
+
+### Token not showing
+
+- Verify token address is correct
+- Check token contract is deployed on ChainID 138
+- Verify token metadata (symbol, decimals) is correct
+- Ensure token logo URL is accessible
+
+## Security Best Practices
+
+1. **Verify RPC URLs**: Always use the official RPC URLs from this documentation
+2. **Verify Explorer URLs**: Use the official Blockscout explorer
+3. **Verify Token Addresses**: Double-check token contract addresses before adding
+4. **Avoid Phishing**: Only add networks from trusted sources
+5. **Check Domain**: Verify you're on the official domain (d-bis.org)
+
+## References
+
+- [MetaMask Documentation](https://docs.metamask.io)
+- [EIP-3085: wallet_addEthereumChain](https://eips.ethereum.org/EIPS/eip-3085)
+- [EIP-747: wallet_watchAsset](https://eips.ethereum.org/EIPS/eip-747)
+- [Chainlist](https://chainlist.org)
+- [Blockscout Explorer](https://explorer.d-bis.org)
+
--- a/docs/operations/integrations/METAMASK_PORTFOLIO.md
+++ b/docs/operations/integrations/METAMASK_PORTFOLIO.md
@@ -0,0 +1,167 @@
+# MetaMask Portfolio Compatibility for ChainID 138
+
+Guide for MetaMask Portfolio compatibility with ChainID 138.
+
+## Current Status
+
+ChainID 138 is **not** currently supported in MetaMask Portfolio's native features (Swaps, Bridge, Buy/Sell). However, read-only features (balances, token display) may work if token metadata is properly configured.
+
+## Portfolio Read-Only Features
+
+### Token Auto-Detection
+
+MetaMask Portfolio can auto-detect tokens when they appear on **2+ reputable token lists**. To enable auto-detection:
+
+1. **Official Token List**: Maintain an official token list for ChainID 138
+2. **Token List Inclusion**: Submit token list to reputable aggregators:
+   - CoinGecko Token Lists
+   - Uniswap Token Lists
+   - Other major DEX token lists
+3. **Explorer Metadata**: Ensure Blockscout returns standard ERC-20 metadata endpoints
+
+### Balance Visibility
+
+Portfolio can display token balances if:
+
+- Token metadata is available on token lists
+- Explorer returns standard ERC-20 metadata
+- Token contract implements standard ERC-20 interface
+- Token balances are queryable via RPC
+
+### Token Symbols and Logos
+
+Portfolio displays token symbols and logos from:
+
+- Token lists (primary source)
+- Explorer metadata (fallback)
+- Contract metadata (if available)
+
+## CAIP-2 Identifier
+
+ChainID 138 uses the CAIP-2 identifier: `eip155:138`
+
+This identifier is used by:
+- Portfolio for chain identification
+- Token lists for chain-specific tokens
+- Indexers for chain-specific data
+
+## Blockscout Integration
+
+### Required API Endpoints
+
+Blockscout must provide these endpoints for Portfolio compatibility:
+
+1. **Token Metadata**: `/api/v2/tokens/{address}`
+   - Returns: name, symbol, decimals, total_supply
+   
+2. **Token Holders**: `/api/v2/tokens/{address}/holders`
+   - Returns: list of token holders
+   
+3. **Token Transfers**: `/api/v2/tokens/{address}/transfers`
+   - Returns: token transfer history
+
+### CORS Configuration
+
+Blockscout must allow CORS requests from Portfolio:
+
+```
+Access-Control-Allow-Origin: https://portfolio.metamask.io
+Access-Control-Allow-Methods: GET, OPTIONS
+Access-Control-Allow-Headers: Content-Type
+```
+
+### Token Logo Serving
+
+Token logos should be served from Blockscout or CDN:
+
+- URL format: `https://explorer.d-bis.org/images/tokens/{address}.png`
+- Fallback: Token logo from token list
+- Standard: 512x512 PNG format
+
+## Token List Requirements
+
+### Official Token List
+
+The official token list for ChainID 138 must:
+
+1. **Follow Token Lists Schema**: Use Uniswap Token Lists JSON schema
+2. **Include All Tokens**: Include all ecosystem tokens
+3. **Provide Logos**: Include logo URLs for all tokens
+4. **Maintain Accuracy**: Keep token metadata up to date
+5. **Host Publicly**: Host on public URL (HTTPS)
+
+### Token List Submission
+
+Submit token list to:
+
+1. **CoinGecko**: For token discovery
+2. **Uniswap**: For DEX integration
+3. **Other Aggregators**: For wider reach
+
+## Limitations
+
+### Not Supported (Requires MetaMask Partnership)
+
+- **Swaps**: In-wallet swap aggregator
+- **Bridge**: Portfolio Bridge integration
+- **Buy/Sell**: Fiat on/off-ramps
+- **Advanced Charts**: Market data and charts
+- **Full Portfolio Features**: Complete portfolio functionality
+
+### Supported (Read-Only)
+
+- **Token Balances**: Display token balances
+- **Token Symbols**: Display token symbols
+- **Token Logos**: Display token logos
+- **Transaction History**: View transaction history (via explorer)
+- **Account Overview**: Basic account information
+
+## Testing Portfolio Compatibility
+
+### Checklist
+
+- [ ] Token list is publicly accessible
+- [ ] Token list follows Token Lists schema
+- [ ] Token logos are accessible
+- [ ] Blockscout API endpoints work
+- [ ] CORS headers are configured
+- [ ] Token metadata is accurate
+- [ ] Token balances are queryable
+- [ ] CAIP-2 identifier is used correctly
+
+### Test Steps
+
+1. **Add Network**: Add ChainID 138 to MetaMask
+2. **Add Tokens**: Add tokens to MetaMask
+3. **Check Portfolio**: Open MetaMask Portfolio
+4. **Verify Balances**: Check if token balances display
+5. **Verify Symbols**: Check if token symbols display
+6. **Verify Logos**: Check if token logos display
+7. **Test Explorer**: Verify explorer links work
+
+## Future Integration
+
+### Path to Full Support
+
+To enable full Portfolio features:
+
+1. **Business Development**: Engage with Consensys for partnership
+2. **Liquidity Requirements**: Ensure sufficient liquidity for swaps
+3. **Bridge Integration**: Integrate with bridge providers
+4. **On-Ramp Partners**: Partner with fiat on/ramp providers
+5. **Regulatory Compliance**: Ensure regulatory compliance
+
+### Tracking
+
+- Monitor MetaMask Portfolio updates
+- Track network support announcements
+- Engage with Consensys for integration
+- Submit feature requests
+
+## References
+
+- [MetaMask Portfolio](https://portfolio.metamask.io)
+- [Token Lists](https://tokenlists.org)
+- [CAIP-2](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md)
+- [Blockscout API](https://docs.blockscout.com/for-developers/api)
+
--- a/docs/operations/integrations/METAMASK_SAFETY.md
+++ b/docs/operations/integrations/METAMASK_SAFETY.md
@@ -0,0 +1,150 @@
+# MetaMask Safety Guide for ChainID 138
+
+Security best practices for using ChainID 138 with MetaMask.
+
+## Verifying Network Details
+
+### Official Network Information
+
+- **ChainID**: 138 (0x8a in hex)
+- **Chain Name**: DeFi Oracle Meta Mainnet
+- **RPC URL**: `https://rpc.d-bis.org`
+- **Block Explorer**: `https://explorer.d-bis.org`
+- **Domain**: `d-bis.org` (Cloudflare DNS/SSL)
+
+### How to Verify
+
+1. **Check the Domain**: Always verify you're on the official domain (`d-bis.org`)
+2. **Verify RPC URL**: Use only the official RPC URLs listed in this documentation
+3. **Verify Explorer URL**: Use only the official Blockscout explorer
+4. **Check ChainID**: Always verify ChainID is 138 (0x8a) before adding
+5. **Verify Token Addresses**: Double-check token contract addresses before adding
+
+## Avoiding Phishing
+
+### Red Flags
+
+- **Unofficial Domains**: Be wary of domains that look similar but are not `d-bis.org`
+- **Unofficial RPC URLs**: Only use RPC URLs from official documentation
+- **Unofficial Token Addresses**: Verify token addresses on Blockscout
+- **Unexpected Requests**: Never approve unexpected network addition requests
+- **Suspicious Links**: Don't click on suspicious links or download files from untrusted sources
+
+### Best Practices
+
+1. **Bookmark Official Sites**: Bookmark the official explorer and documentation
+2. **Verify Before Adding**: Always verify network details before adding to MetaMask
+3. **Use Official Sources**: Only add networks from official sources (Chainlist, official docs)
+4. **Check URLs**: Always check URLs in the address bar
+5. **Enable Phishing Detection**: Keep MetaMask's phishing detection enabled
+
+## Securing Your Wallet
+
+### MetaMask Security
+
+1. **Use Strong Password**: Use a strong, unique password for MetaMask
+2. **Enable 2FA**: Enable two-factor authentication if available
+3. **Keep Software Updated**: Keep MetaMask updated to the latest version
+4. **Backup Seed Phrase**: Backup your seed phrase in a secure location
+5. **Never Share Seed Phrase**: Never share your seed phrase with anyone
+
+### Network Security
+
+1. **Verify Network Details**: Always verify network details before adding
+2. **Use Official RPC URLs**: Only use official RPC URLs
+3. **Check SSL Certificates**: Verify SSL certificates are valid
+4. **Monitor Transactions**: Monitor your transactions on the explorer
+5. **Use Hardware Wallets**: Consider using a hardware wallet for large amounts
+
+## Token Safety
+
+### Verifying Tokens
+
+1. **Check Contract Address**: Verify token contract address on Blockscout
+2. **Verify Token Metadata**: Check token name, symbol, and decimals
+3. **Check Token Logo**: Verify token logo is from official source
+4. **Review Token Contract**: Review token contract code if possible
+5. **Check Token List**: Prefer tokens from official token lists
+
+### Token Red Flags
+
+- **Unofficial Addresses**: Tokens with addresses not on official lists
+- **Suspicious Metadata**: Tokens with suspicious names or symbols
+- **Missing Logos**: Tokens without logos or with broken logo URLs
+- **Unofficial Sources**: Tokens from unofficial sources
+
+## Transaction Safety
+
+### Before Signing
+
+1. **Verify Recipient**: Double-check recipient address
+2. **Verify Amount**: Verify transaction amount
+3. **Verify Gas Fees**: Check gas fees are reasonable
+4. **Verify Network**: Ensure you're on the correct network
+5. **Review Transaction**: Review all transaction details
+
+### After Signing
+
+1. **Monitor Transaction**: Monitor transaction on explorer
+2. **Verify Success**: Verify transaction was successful
+3. **Check Balance**: Verify balance updates correctly
+4. **Report Issues**: Report any issues immediately
+
+## Reporting Issues
+
+### If You Suspect Phishing
+
+1. **Don't Panic**: Stay calm and don't make hasty decisions
+2. **Disconnect**: Disconnect from suspicious sites
+3. **Report**: Report to MetaMask and project team
+4. **Check Accounts**: Check your accounts for unauthorized transactions
+5. **Secure Wallet**: Secure your wallet if compromised
+
+### Contact Information
+
+- **MetaMask Support**: [support.metamask.io](https://support.metamask.io)
+- **Project Team**: [GitHub Issues](https://github.com/Defi-Oracle-Tooling/smom-dbis-138/issues)
+- **Security Issues**: [Security Policy](https://github.com/Defi-Oracle-Tooling/smom-dbis-138/security)
+
+## Additional Resources
+
+- [MetaMask Security](https://support.metamask.io/hc/en-us/articles/360015489591)
+- [Phishing Prevention](https://support.metamask.io/hc/en-us/articles/4427602331163)
+- [Wallet Security](https://support.metamask.io/hc/en-us/articles/360015489591-Basic-safety-and-security-tips-for-MetaMask)
+
+## Checklist
+
+Before adding ChainID 138 to MetaMask:
+
+- [ ] Verified domain is `d-bis.org`
+- [ ] Verified RPC URL is `https://rpc.d-bis.org`
+- [ ] Verified explorer URL is `https://explorer.d-bis.org`
+- [ ] Verified ChainID is 138 (0x8a)
+- [ ] Verified source is official
+- [ ] Checked for phishing warnings
+- [ ] Reviewed network details
+- [ ] Understood risks
+
+Before adding tokens:
+
+- [ ] Verified token address on Blockscout
+- [ ] Verified token metadata is correct
+- [ ] Verified token is from official source
+- [ ] Checked token contract if possible
+- [ ] Verified token logo is official
+- [ ] Understood token risks
+
+## Emergency Contacts
+
+If you suspect your wallet is compromised:
+
+1. **Immediately**: Disconnect from all sites
+2. **Transfer Funds**: Transfer funds to a new wallet if possible
+3. **Report**: Report to MetaMask and project team
+4. **Secure**: Secure your wallet and accounts
+5. **Monitor**: Monitor for unauthorized transactions
+
+## Conclusion
+
+Always prioritize security when using MetaMask. Verify all network details, token addresses, and transactions before approving. When in doubt, don't proceed and contact support.
+
--- a/docs/operations/integrations/METAMASK_TEST_CHECKLIST.md
+++ b/docs/operations/integrations/METAMASK_TEST_CHECKLIST.md
@@ -0,0 +1,237 @@
+# MetaMask Integration Test Checklist
+
+Comprehensive test checklist for MetaMask integration with ChainID 138.
+
+## Pre-Testing Setup
+
+- [ ] MetaMask extension installed (latest version)
+- [ ] MetaMask mobile app installed (for mobile testing)
+- [ ] Test accounts created and funded
+- [ ] RPC endpoints accessible
+- [ ] Blockscout explorer accessible
+- [ ] Token contracts deployed
+
+## Browser Testing
+
+### Chrome/Chromium
+
+- [ ] Network addition via `wallet_addEthereumChain`
+- [ ] Network addition via Chainlist
+- [ ] Network switching via `wallet_switchEthereumChain`
+- [ ] Token addition via `wallet_watchAsset`
+- [ ] Account connection
+- [ ] Transaction signing
+- [ ] Network change event handling
+- [ ] Account change event handling
+
+### Firefox
+
+- [ ] Network addition via `wallet_addEthereumChain`
+- [ ] Network addition via Chainlist
+- [ ] Network switching
+- [ ] Token addition
+- [ ] Account connection
+- [ ] Transaction signing
+
+### Edge
+
+- [ ] Network addition
+- [ ] Network switching
+- [ ] Token addition
+- [ ] Account connection
+
+## Mobile Testing
+
+### iOS (MetaMask Mobile)
+
+- [ ] Network addition
+- [ ] Network switching
+- [ ] Token addition
+- [ ] Account connection
+- [ ] Transaction signing
+- [ ] Deep linking
+
+### Android (MetaMask Mobile)
+
+- [ ] Network addition
+- [ ] Network switching
+- [ ] Token addition
+- [ ] Account connection
+- [ ] Transaction signing
+- [ ] Deep linking
+
+## Network Addition Tests
+
+### Method 1: wallet_addEthereumChain
+
+- [ ] Add network successfully
+- [ ] Handle network already added error
+- [ ] Handle user rejection
+- [ ] Handle invalid parameters
+- [ ] Verify network appears in MetaMask
+- [ ] Verify network details are correct
+
+### Method 2: Chainlist
+
+- [ ] Find network on Chainlist
+- [ ] Click "Add to MetaMask" button
+- [ ] Approve network addition
+- [ ] Verify network added correctly
+
+### Method 3: Manual Addition
+
+- [ ] Add network manually via MetaMask UI
+- [ ] Verify all fields are correct
+- [ ] Test with different RPC URLs
+- [ ] Test with different explorer URLs
+
+## Network Switching Tests
+
+- [ ] Switch to ChainID 138 from another network
+- [ ] Switch away from ChainID 138
+- [ ] Handle network not added error
+- [ ] Handle user rejection
+- [ ] Verify chain change event fires
+- [ ] Verify UI updates on chain change
+
+## Token Addition Tests
+
+### Method 1: wallet_watchAsset
+
+- [ ] Add token successfully
+- [ ] Handle invalid address
+- [ ] Handle invalid decimals
+- [ ] Handle user rejection
+- [ ] Verify token appears in MetaMask
+- [ ] Verify token balance displays correctly
+- [ ] Verify token logo displays correctly
+
+### Method 2: Token List
+
+- [ ] Token auto-detection works
+- [ ] Token appears in token list
+- [ ] Token metadata is correct
+- [ ] Token logo is accessible
+
+## Integration Tests
+
+### React Integration
+
+- [ ] useChain138 hook works correctly
+- [ ] Chain138Button component works
+- [ ] AddTokenButton component works
+- [ ] Event listeners work correctly
+- [ ] State management works correctly
+
+### Vanilla JS Integration
+
+- [ ] Network addition works
+- [ ] Network switching works
+- [ ] Token addition works
+- [ ] Event handlers work correctly
+
+### Vue Integration
+
+- [ ] useChain138 composable works
+- [ ] Components work correctly
+- [ ] Event listeners work correctly
+
+## Error Handling Tests
+
+- [ ] MetaMask not installed error
+- [ ] MetaMask locked error
+- [ ] User rejection error
+- [ ] Network not added error
+- [ ] Invalid parameters error
+- [ ] RPC endpoint error
+- [ ] Network connectivity error
+
+## Edge Cases
+
+- [ ] Multiple network additions
+- [ ] Rapid network switching
+- [ ] Network addition during transaction
+- [ ] Token addition with invalid logo URL
+- [ ] Token addition with missing metadata
+- [ ] Network change during token addition
+- [ ] Account change during network switch
+
+## Performance Tests
+
+- [ ] Network addition response time
+- [ ] Network switching response time
+- [ ] Token addition response time
+- [ ] Event handler performance
+- [ ] Memory usage
+
+## Security Tests
+
+- [ ] Verify RPC URLs are correct
+- [ ] Verify explorer URLs are correct
+- [ ] Verify token addresses are correct
+- [ ] Test with malicious RPC URLs
+- [ ] Test with malicious token addresses
+- [ ] Verify CORS headers
+- [ ] Verify SSL certificates
+
+## Regression Tests
+
+- [ ] Test with older MetaMask versions
+- [ ] Test with newer MetaMask versions
+- [ ] Test with different browser versions
+- [ ] Test with different operating systems
+- [ ] Test with different network conditions
+
+## Documentation Tests
+
+- [ ] Code examples work correctly
+- [ ] Documentation is accurate
+- [ ] Links are working
+- [ ] Screenshots are up to date
+
+## Production Readiness
+
+- [ ] All tests pass
+- [ ] Error handling is comprehensive
+- [ ] User experience is smooth
+- [ ] Documentation is complete
+- [ ] Security checks pass
+- [ ] Performance is acceptable
+
+## Test Results
+
+### Test Date: ___________
+
+### Tester: ___________
+
+### Browser: ___________
+
+### MetaMask Version: ___________
+
+### Results:
+
+- Total Tests: ___________
+- Passed: ___________
+- Failed: ___________
+- Skipped: ___________
+
+### Notes:
+
+___________
+
+___________
+
+___________
+
+## Sign-off
+
+- [ ] All critical tests passed
+- [ ] All high-priority tests passed
+- [ ] Documentation reviewed
+- [ ] Security reviewed
+- [ ] Ready for production
+
+**Tester Signature**: ___________
+
+**Date**: ___________
+
--- a/docs/operations/integrations/WETH_CCIP_DEPLOYMENT.md
+++ b/docs/operations/integrations/WETH_CCIP_DEPLOYMENT.md
@@ -0,0 +1,320 @@
+# WETH9 and WETH10 with CCIP Cross-Chain Deployment Guide
+
+## Overview
+
+This guide covers the deployment of WETH9 and WETH10 contracts with Chainlink CCIP (Cross-Chain Interoperability Protocol) for complete cross-chain token transfer functionality.
+
+## Contracts
+
+### WETH9 (`contracts/tokens/WETH.sol`)
+- Standard WETH9 implementation
+- ERC-20 compatible
+- Deposit/withdraw functionality
+- Transfer/approve functionality
+
+### WETH10 (`contracts/tokens/WETH10.sol`)
+- Enhanced WETH implementation
+- ERC-3156 flash loan support
+- Zero flash loan fees
+- Advanced features for DeFi integrations
+
+### CCIPWETH9Bridge (`contracts/ccip/CCIPWETH9Bridge.sol`)
+- Cross-chain WETH9 transfer bridge
+- CCIP integration for token transfers
+- Replay protection with nonces
+- Admin-controlled destination chains
+
+### CCIPWETH10Bridge (`contracts/ccip/CCIPWETH10Bridge.sol`)
+- Cross-chain WETH10 transfer bridge
+- CCIP integration for token transfers
+- Replay protection with nonces
+- Admin-controlled destination chains
+
+## Prerequisites
+
+1. **Chainlink CCIP Router**: Deployed CCIP Router on your chain
+2. **LINK Token**: LINK token address for paying CCIP fees
+3. **Private Key**: Deployer private key with sufficient balance
+4. **Environment Variables**: Configured in `.env` file
+
+## Environment Variables
+
+Create a `.env` file with the following variables:
+
+```bash
+# Deployer private key
+PRIVATE_KEY=your_private_key_here
+
+# CCIP Configuration
+CCIP_ROUTER=0x...  # CCIP Router address
+CCIP_FEE_TOKEN=0x...  # LINK token address
+
+# WETH9 Address (if not deploying)
+WETH9_ADDRESS=0x...  # Optional: existing WETH9 address
+
+# WETH10 Address (if not deploying)
+WETH10_ADDRESS=0x...  # Optional: existing WETH10 address
+
+# Deployment Flags
+DEPLOY_WETH9=true
+DEPLOY_WETH10=true
+DEPLOY_BRIDGES=true
+```
+
+## Deployment Steps
+
+### Option 1: Deploy All Contracts (Recommended)
+
+Deploy WETH9, WETH10, and both bridges in a single transaction:
+
+```bash
+forge script script/DeployWETHWithCCIP.s.sol:DeployWETHWithCCIP \
+    --rpc-url $RPC_URL \
+    --broadcast \
+    --verify \
+    -vvvv
+```
+
+### Option 2: Deploy Individually
+
+#### 1. Deploy WETH9
+
+```bash
+forge script script/DeployWETH.s.sol:DeployWETH \
+    --rpc-url $RPC_URL \
+    --broadcast \
+    --verify \
+    -vvvv
+```
+
+#### 2. Deploy WETH10
+
+```bash
+forge script script/DeployWETH10.s.sol:DeployWETH10 \
+    --rpc-url $RPC_URL \
+    --broadcast \
+    --verify \
+    -vvvv
+```
+
+#### 3. Deploy CCIPWETH9Bridge
+
+```bash
+forge script script/DeployCCIPWETH9Bridge.s.sol:DeployCCIPWETH9Bridge \
+    --rpc-url $RPC_URL \
+    --broadcast \
+    --verify \
+    -vvvv
+```
+
+#### 4. Deploy CCIPWETH10Bridge
+
+```bash
+forge script script/DeployCCIPWETH10Bridge.s.sol:DeployCCIPWETH10Bridge \
+    --rpc-url $RPC_URL \
+    --broadcast \
+    --verify \
+    -vvvv
+```
+
+## Configuration
+
+### 1. Add Destination Chains
+
+After deployment, configure destination chains for cross-chain transfers:
+
+```solidity
+// Add destination chain for WETH9 bridge
+bridge.addDestination(
+    destinationChainSelector,  // Chain selector (e.g., Ethereum: 5009297550715157269)
+    receiverBridgeAddress      // Address of corresponding bridge on destination chain
+);
+
+// Add destination chain for WETH10 bridge
+bridge10.addDestination(
+    destinationChainSelector,
+    receiverBridgeAddress
+);
+```
+
+### 2. Verify Configuration
+
+```solidity
+// Check if destination is enabled
+(bool enabled, uint64 chainSelector, address receiver) = bridge.destinations(chainSelector);
+
+// Get all destination chains
+uint64[] memory chains = bridge.getDestinationChains();
+```
+
+## Usage
+
+### Sending WETH9 Cross-Chain
+
+```solidity
+// 1. Approve bridge to spend WETH9
+weth9.approve(bridgeAddress, amount);
+
+// 2. Approve LINK token for fees
+linkToken.approve(bridgeAddress, feeAmount);
+
+// 3. Send cross-chain
+bytes32 messageId = bridge.sendCrossChain(
+    destinationChainSelector,
+    recipientAddress,
+    amount
+);
+```
+
+### Sending WETH10 Cross-Chain
+
+```solidity
+// 1. Approve bridge to spend WETH10
+weth10.approve(bridgeAddress, amount);
+
+// 2. Approve LINK token for fees
+linkToken.approve(bridgeAddress, feeAmount);
+
+// 3. Send cross-chain
+bytes32 messageId = bridge10.sendCrossChain(
+    destinationChainSelector,
+    recipientAddress,
+    amount
+);
+```
+
+### Calculating Fees
+
+```solidity
+// Calculate fee for cross-chain transfer
+uint256 fee = bridge.calculateFee(
+    destinationChainSelector,
+    amount
+);
+```
+
+### Receiving Cross-Chain Transfers
+
+The bridge automatically receives tokens via CCIP and transfers them to the recipient. No user action required.
+
+## Testing
+
+Run tests to verify functionality:
+
+```bash
+# Test WETH9
+forge test --match-contract WETHTest -vvvv
+
+# Test WETH10
+forge test --match-contract WETH10Test -vvvv
+
+# Test CCIPWETH9Bridge
+forge test --match-contract CCIPWETH9BridgeTest -vvvv
+
+# Test CCIPWETH10Bridge
+forge test --match-contract CCIPWETH10BridgeTest -vvvv
+```
+
+## Chain Selectors
+
+Common chain selectors for reference:
+
+| Chain | Chain Selector |
+|-------|---------------|
+| Ethereum Mainnet | 5009297550715157269 |
+| Arbitrum One | 4949039107694359620 |
+| Optimism | 3734403246176062136 |
+| Polygon | 4051577828743386545 |
+| Base | 15971525489660198786 |
+| Avalanche | 6433500567565415381 |
+
+## Security Considerations
+
+1. **Admin Controls**: Bridge admin has full control over destination chains
+2. **Replay Protection**: Messages are protected against replay attacks
+3. **Fee Management**: Users must approve LINK tokens for fees
+4. **Token Approvals**: Users must approve bridges to spend tokens
+5. **Destination Validation**: Always verify destination chain addresses
+
+## Monitoring
+
+Monitor cross-chain transfers:
+
+```solidity
+// Check if transfer was processed
+bool processed = bridge.processedTransfers(messageId);
+
+// Get user nonce
+uint256 nonce = bridge.getUserNonce(userAddress);
+
+// Listen for events
+event CrossChainTransferInitiated(
+    bytes32 indexed messageId,
+    address indexed sender,
+    uint64 indexed destinationChainSelector,
+    address recipient,
+    uint256 amount,
+    uint256 nonce
+);
+
+event CrossChainTransferCompleted(
+    bytes32 indexed messageId,
+    uint64 indexed sourceChainSelector,
+    address indexed recipient,
+    uint256 amount
+);
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Insufficient LINK**: Ensure user has enough LINK for fees
+2. **Destination Not Enabled**: Verify destination chain is added and enabled
+3. **Invalid Token**: Ensure correct WETH9/WETH10 address
+4. **Replay Attack**: Message ID already processed
+
+### Error Messages
+
+- `CCIPWETH9Bridge: destination not enabled` - Destination chain not configured
+- `CCIPWETH9Bridge: transfer already processed` - Replay attack detected
+- `CCIPWETH9Bridge: insufficient repayment` - Insufficient token balance
+- `CCIPWETH9Bridge: zero recipient` - Invalid recipient address
+
+## Next Steps
+
+1. ✅ Deploy WETH9 and WETH10 contracts
+2. ✅ Deploy CCIP bridges
+3. ✅ Configure destination chains
+4. ✅ Test cross-chain transfers
+5. ✅ Monitor deployments
+6. ✅ Update documentation with deployed addresses
+
+## Support
+
+For issues or questions:
+- Check contract documentation
+- Review test files for examples
+- Verify CCIP router configuration
+- Check chain selector compatibility
+
+## Deployment Checklist
+
+- [ ] CCIP Router deployed and verified
+- [ ] LINK token address confirmed
+- [ ] WETH9 deployed (if new)
+- [ ] WETH10 deployed (if new)
+- [ ] CCIPWETH9Bridge deployed
+- [ ] CCIPWETH10Bridge deployed
+- [ ] Destination chains configured
+- [ ] Tests passed
+- [ ] Contracts verified on explorer
+- [ ] Documentation updated
+
+## References
+
+- [Chainlink CCIP Documentation](https://docs.chain.link/ccip)
+- [WETH9 Specification](https://github.com/gnosis/canonical-weth)
+- [WETH10 Repository](https://github.com/WETH10/WETH10)
+- [ERC-3156 Flash Loans](https://eips.ethereum.org/EIPS/eip-3156)
+
--- a/docs/operations/integrations/WETH_DEPLOYMENT_METHODS.md
+++ b/docs/operations/integrations/WETH_DEPLOYMENT_METHODS.md
@@ -0,0 +1,104 @@
+# WETH Deployment Methods
+
+## Current Deployment Status
+
+### WETH9 Deployment
+- **Current Method**: Standard `new WETH()` (CREATE opcode)
+- **Address**: Non-deterministic (depends on deployer nonce)
+- **Ethereum Mainnet Address**: `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
+
+### WETH10 Deployment
+- **Current Method**: Standard `new WETH10()` (CREATE opcode)
+- **Address**: Non-deterministic (depends on deployer nonce)
+- **Ethereum Mainnet Address**: `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f`
+
+---
+
+## Can We Match Ethereum Mainnet Addresses?
+
+### WETH9: ❌ **NO**
+**Reason**: WETH9 on Ethereum Mainnet was deployed using the `CREATE` opcode (not CREATE2). The address was determined by:
+- Deployer address
+- Deployer nonce (transaction count)
+
+Since the nonce is chain-specific, it's **impossible** to replicate the exact Ethereum Mainnet address on ChainID 138.
+
+### WETH10: ⚠️ **POSSIBLY**
+**Reason**: WETH10 may have been deployed with CREATE2. To match the address, we need:
+1. **Exact same bytecode** (must match byte-for-byte)
+2. **Same deployer address** (or factory address)
+3. **Same salt** (if deployed with CREATE2)
+
+If WETH10 on Ethereum Mainnet was deployed with CREATE2, we can match the address by:
+- Using the same bytecode
+- Using the same CREATE2Factory address (or deploying from the same address)
+- Using the same salt
+
+---
+
+## CREATE2 Deployment Scripts
+
+We've created CREATE2 deployment scripts:
+
+1. **`script/DeployWETHWithCREATE2.s.sol`**
+   - Deploys WETH9 using CREATE2
+   - Creates a **new deterministic address** for ChainID 138
+   - Will NOT match Ethereum Mainnet (since Mainnet used CREATE)
+
+2. **`script/DeployWETH10WithCREATE2.s.sol`**
+   - Deploys WETH10 using CREATE2
+   - Attempts to match Ethereum Mainnet address
+   - Will match if WETH10 on Mainnet was deployed with CREATE2 and we use the same parameters
+
+---
+
+## Usage
+
+### Deploy WETH9 with CREATE2 (New Deterministic Address)
+```bash
+forge script script/DeployWETHWithCREATE2.s.sol:DeployWETHWithCREATE2 \
+  --rpc-url $RPC_URL \
+  --broadcast \
+  --private-key $PRIVATE_KEY
+```
+
+### Deploy WETH10 with CREATE2 (Attempt to Match Mainnet)
+```bash
+forge script script/DeployWETH10WithCREATE2.s.sol:DeployWETH10WithCREATE2 \
+  --rpc-url $RPC_URL \
+  --broadcast \
+  --private-key $PRIVATE_KEY
+```
+
+---
+
+## Benefits of CREATE2
+
+1. **Deterministic Addresses**: Same address across deployments if parameters match
+2. **Predictable**: Can compute address before deployment
+3. **Cross-Chain Compatibility**: Same address on different chains if parameters match
+4. **Upgrade Safety**: Can deploy new version to same address after self-destruct
+
+---
+
+## Important Notes
+
+1. **WETH9 on Ethereum Mainnet**: Cannot be replicated (was CREATE, not CREATE2)
+2. **WETH10 on Ethereum Mainnet**: May be replicable if deployed with CREATE2
+3. **Bytecode Must Match**: For address matching, bytecode must be identical
+4. **Salt Must Match**: If using CREATE2, the salt must be the same
+5. **Deployer Must Match**: The deployer address (or factory) must be the same
+
+---
+
+## Recommendation
+
+For ChainID 138, we recommend:
+- **Option 1**: Use CREATE2 for deterministic addresses (new addresses, but predictable)
+- **Option 2**: Use standard CREATE (current method) for simplicity
+- **Option 3**: If WETH10 was deployed with CREATE2 on Mainnet, attempt to match the address
+
+The choice depends on whether you need:
+- **Address matching with Mainnet**: Only possible for WETH10 if it was deployed with CREATE2
+- **Deterministic addresses**: Use CREATE2 with known salt
+- **Simplicity**: Use standard CREATE (current method)