explorer-monorepo/docs/CCIP_RECEIVER_REQUIREMENTS.md

CCIP Receiver Requirements Documentation

Date: 2025-01-12
Network: ChainID 138

---

Overview

This document describes the requirements for receivers in CCIP (Cross-Chain Interoperability Protocol) transactions.

---

Receiver Types

EOA (Externally Owned Account)

Description: Standard Ethereum address controlled by a private key.

Requirements:

• ✅ No special interface required
• ✅ Can receive tokens directly
• ✅ Can receive native ETH
• ✅ Can receive ERC-20 tokens

Use Case: Simple token transfers to user wallets.

Example:

Receiver: 0x4A666F96fC8764181194447A7dFdb7d471b301C8
Type: EOA
Status: ✅ Ready

Contract Receiver

Description: Smart contract that receives CCIP messages.

Requirements:

• ⚠️ Must implement ccipReceive() function
• ⚠️ Must handle message data
• ⚠️ Must handle token transfers
• ⚠️ Must handle errors gracefully

Use Case: Automated processing of cross-chain messages.

---

EOA Receiver Requirements

Basic Requirements

1. Valid Address: Must be a valid Ethereum address (20 bytes)
2. No Code: Address must not have deployed bytecode (for EOA)
3. Accessible: Address must be accessible on destination chain

Token Receipt

EOA receivers can receive:

• ✅ Native tokens (ETH, BNB, etc.)
• ✅ ERC-20 tokens (WETH9, WETH10, etc.)
• ✅ NFTs (if supported)

No Special Interface Required

EOA receivers do not need to implement any special interface. Tokens are transferred directly to the address.

---

Contract Receiver Requirements

Required Interface

Contract receivers must implement the ccipReceive() function:

function ccipReceive(
    Client.Any2EVMMessage calldata message
) external {
    // Process message
    // Handle tokens
    // Handle errors
}

Message Structure

struct Any2EVMMessage {
    bytes32 messageId;
    uint64 sourceChainSelector;
    bytes sender;
    bytes data;
    EVMTokenAmount[] tokenAmounts;
}

Token Handling

Contract receivers must:

1. Accept token transfers
2. Process token amounts
3. Handle multiple tokens (if applicable)
4. Handle errors gracefully

---

Receiver Validation

Address Validation

Before bridging, validate receiver address:

1. Format Check: Verify address is valid (20 bytes, hex format)
2. Chain Check: Verify address exists on destination chain
3. Type Check: Determine if EOA or contract

Validation Script

# Check if address is valid
cast --to-checksum-address <address>

# Check if address has code (contract)
cast code <address> --rpc-url <rpc_url>

# Check balance
cast balance <address> --rpc-url <rpc_url>

---

Current Receiver Configuration

Receiver Address

• Address: 0x4A666F96fC8764181194447A7dFdb7d471b301C8
• Type: EOA (Externally Owned Account)
• Status: ✅ Ready

Verification

Status: ✅ Complete (Task 68)

The receiver address has been verified as:

• Valid Ethereum address
• EOA (no contract code)
• Accessible on destination chains

---

Testing

Test Receiver with Small Amount

Status: ⏳ Pending (Task 69)

Procedure:

1. Send small test amount (0.001 ETH or less)
2. Verify receiver receives tokens
3. Verify tokens are correct amount
4. Verify tokens are correct type

Script: scripts/wrap-and-bridge-to-ethereum.sh 0.001

---

Best Practices

For EOA Receivers

1. Verify Address: Double-check address before bridging
2. Test First: Send small test amount first
3. Keep Private Key Safe: Protect private key for receiver

For Contract Receivers

1. Implement Interface: Ensure ccipReceive() is implemented
2. Handle Errors: Implement error handling
3. Test Thoroughly: Test with various message types
4. Gas Optimization: Optimize gas usage

---

Troubleshooting

Receiver Not Receiving Tokens

Possible Causes:

1. Invalid receiver address
2. Receiver contract not implementing interface
3. Message execution failed
4. Network issues

Solutions:

1. Verify receiver address
2. Check message execution status
3. Verify receiver contract (if applicable)
4. Check network connectivity

Receiver Contract Errors

Possible Causes:

1. Missing ccipReceive() function
2. Incorrect function signature
3. Insufficient gas
4. Logic errors

Solutions:

1. Verify interface implementation
2. Check function signature
3. Increase gas limit
4. Review contract logic

---

Related Documentation

• CCIP Configuration Status
• Complete Task Catalog
• Bridge Contract Architecture

---

Last Updated: 2025-01-12