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:

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

### Message Structure

```solidity
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

```bash
# 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](./CCIP_CONFIGURATION_STATUS.md)
- [Complete Task Catalog](./CCIP_COMPLETE_TASK_CATALOG.md)
- [Bridge Contract Architecture](./BRIDGE_CONTRACT_ARCHITECTURE.md)

---

**Last Updated**: 2025-01-12