Skip to main content

​
Overview

The Eco Routes Protocol is designed to support both EVM chains (Ethereum, Polygon, Arbitrum, etc.) and non-EVM chains (Solana, Sui, etc.) through a flexible type system and modular architecture.

​
Dual-Type System

The protocol supports two parallel type systems to accommodate different blockchain architectures:

​
EVM Intent Types

Optimized for Ethereum Virtual Machine chains using native address types (20 bytes):
contracts/types/Intent.sol
struct Call {
    address target;      // 20-byte EVM address
    bytes data;
    uint256 value;
}

struct TokenAmount {
    address token;       // 20-byte ERC20 address
    uint256 amount;
}

struct Route {
    bytes32 salt;
    uint64 deadline;
    address portal;      // 20-byte portal address
    uint256 nativeAmount;
    TokenAmount[] tokens;
    Call[] calls;
}

struct Reward {
    uint64 deadline;
    address creator;     // 20-byte creator address
    address prover;      // 20-byte prover address
    uint256 nativeAmount;
    TokenAmount[] tokens;
}
Benefits:
  • Familiar to Solidity developers
  • Gas-efficient on EVM chains
  • Native tooling support
  • Type safety for EVM addresses

​
Universal Intent Types

Designed for cross-VM compatibility using bytes32 for address identifiers: 
// Same struct names, different address representation
struct Route {
    bytes32 salt;
    uint64 deadline;
    bytes32 portal;      // 32-byte universal identifier
    uint256 nativeAmount;
    TokenAmount[] tokens;
    Call[] calls;
}

struct Reward {
    uint64 deadline;
    bytes32 creator;     // 32-byte universal identifier
    bytes32 prover;      // 32-byte universal identifier
    uint256 nativeAmount;
    TokenAmount[] tokens;
}
Benefits:
  • Compatible with non-EVM chains (Solana, Sui, etc.)
  • Unified cross-chain addressing
  • Future-proof for new blockchain architectures
  • Same struct names simplify integration

​
bytes32 vs address Types

​
Technical Design

The dual-type approach leverages EVM’s ABI encoding: 
// EVM addresses are 20 bytes
address evmAddress = 0x1234567890123456789012345678901234567890;

// When ABI-encoded, addresses are padded to 32 bytes
// Encoding: 0x000000000000000000000000{20-byte address}

// bytes32 exactly matches this encoding pattern
bytes32 universalId = bytes32(uint256(uint160(evmAddress)));
Key insight: The bytes32 type can represent both:
  • EVM addresses (with zero-padding)
  • Non-EVM identifiers (using full 32 bytes)
This allows both type systems to be interchangeable at the binary level.

​
Claimant Identifiers

The protocol uses bytes32 for claimant identifiers to support cross-VM reward distribution:
contracts/Inbox.sol
mapping(bytes32 => bytes32) public claimants;

function fulfill(
    bytes32 intentHash,
    Route memory route,
    bytes32 rewardHash,
    bytes32 claimant  // Universal claimant identifier
) external payable returns (bytes[] memory)
On fulfillment:
  • EVM solver: Converts their address to bytes32
  • Non-EVM solver: Provides their native identifier as bytes32
On withdrawal:
  • Prover converts bytes32 claimant back to the appropriate address type
  • Rewards distributed using the native address format

​
Type Conversion

The protocol includes the AddressConverter library for converting between types:
contracts/libs/AddressConverter.sol
library AddressConverter {
    // Convert EVM address to universal bytes32
    function toBytes32(address addr) internal pure returns (bytes32) {
        return bytes32(uint256(uint160(addr)));
    }

    // Convert universal bytes32 to EVM address
    function toAddress(bytes32 id) internal pure returns (address) {
        return address(uint160(uint256(id)));
    }
}
Usage example: 
import {AddressConverter} from "./libs/AddressConverter.sol";

using AddressConverter for address;
using AddressConverter for bytes32;

// Convert address to bytes32
address solver = msg.sender;
bytes32 claimant = solver.toBytes32();

// Convert bytes32 to address
bytes32 storedClaimant = claimants[intentHash];
address recipient = storedClaimant.toAddress();
When converting from bytes32 to address, the upper 12 bytes must be zero for valid EVM addresses. The conversion extracts only the lower 20 bytes.

​
Modular Contract Structure

The protocol uses inheritance to separate EVM-specific and universal functionality: 
Portal
├── IntentSource (EVM-specific intent operations)
│   ├── Uses address types for creators, provers
│   ├── Manages reward claiming and refunding
│   └── Handles vault interactions
└── Inbox (universal fulfillment functionality)
    ├── Uses bytes32 for claimant identifiers
    ├── Accepts Route with address or bytes32 portal
    └── Stores fulfillment in universal format

​
Source Chain (IntentSource)

EVM-specific operations:
contracts/IntentSource.sol
function publish(
    Intent calldata intent  // Uses address types
) public returns (bytes32 intentHash, address vault)

function withdraw(
    uint64 destination,
    bytes32 routeHash,
    Reward calldata reward  // reward.creator, reward.prover are addresses
) public
Universal format support:
contracts/IntentSource.sol
function publish(
    uint64 destination,
    bytes memory route,      // Encoded route as bytes
    Reward memory reward
) public returns (bytes32 intentHash, address vault)
  • Accepts route as bytes for cross-VM compatibility
  • Computes hash from encoded bytes: keccak256(route)
  • Allows non-EVM chains to create intents via encoding

​
Destination Chain (Inbox)

Universal fulfillment:
contracts/Inbox.sol
function fulfill(
    bytes32 intentHash,
    Route memory route,      // Can use address or bytes32 for portal
    bytes32 rewardHash,
    bytes32 claimant         // Universal identifier
) external payable returns (bytes[] memory)
Claimant storage:
contracts/Inbox.sol
claimants[intentHash] = claimant;
Stores claimant as bytes32, enabling:
  • EVM addresses (converted to bytes32)
  • Solana public keys (native bytes32)
  • Any other 32-byte identifier

​
Cross-Chain Prover Support

Provers handle the conversion between universal and EVM-specific types: 
interface IProver {
    struct ProofData {
        uint64 destination;   // Destination chain ID
        address claimant;     // EVM address for reward recipient
    }

    function provenIntents(bytes32 intentHash) 
        external view returns (ProofData memory);
}
Prover responsibility:
  1. Receive bytes32 claimant from destination chain
  2. Convert to address for EVM source chain storage
  3. Store proof with converted address
  4. Enable withdrawal to EVM address
Conversion in withdraw:
contracts/IntentSource.sol
IProver.ProofData memory proof = IProver(reward.prover).provenIntents(
    intentHash
);
address claimant = proof.claimant;  // Already converted by prover

vault.withdraw(reward, claimant);   // Transfer to EVM address
Provers act as the bridge between universal bytes32 identifiers on destination chains and EVM address types on source chains.

​
Integration Guidelines

​
For EVM-Only Applications

If your application only interacts with EVM chains: 
import {Intent, Route, Reward} from "./types/Intent.sol";

// Create intent with familiar address types
Intent memory intent = Intent({
    destination: 137,  // Polygon
    route: Route({
        salt: bytes32(0),
        deadline: block.timestamp + 86400,
        portal: 0x1234...,  // Portal address
        nativeAmount: 0,
        tokens: tokenAmounts,
        calls: calls
    }),
    reward: Reward({
        deadline: block.timestamp + 86400,
        creator: msg.sender,
        prover: 0x5678...,  // Prover address
        nativeAmount: 1 ether,
        tokens: rewardTokens
    })
});

// Publish using EVM interface
IIntentSource(portal).publishAndFund(intent, false);

​
For Cross-VM Applications

If your application needs to support non-EVM chains: 
import {Intent, Route, Reward} from "./types/Intent.sol";
import {AddressConverter} from "./libs/AddressConverter.sol";

using AddressConverter for address;

// Create intent with bytes32 identifiers
Intent memory intent = Intent({
    destination: 1399811149,  // Solana Mainnet
    route: Route({
        salt: bytes32(0),
        deadline: block.timestamp + 86400,
        portal: bytes32(0x1234...),  // Solana program ID
        nativeAmount: 0,
        tokens: tokenAmounts,
        calls: calls
    }),
    reward: Reward({
        deadline: block.timestamp + 86400,
        creator: msg.sender.toBytes32(),  // Convert to bytes32
        prover: proverAddress.toBytes32(),
        nativeAmount: 1 ether,
        tokens: rewardTokens
    })
});

// Publish using universal interface
IIntentSource(portal).publish(
    intent.destination,
    abi.encode(intent.route),  // Encode route as bytes
    intent.reward
);
As a solver on Solana: 
// Fulfill intent and provide Solana public key as claimant
let claimant: [u8; 32] = solver_pubkey.to_bytes();

// This claimant identifier will be:
// 1. Stored in Inbox.claimants mapping
// 2. Sent to prover via cross-chain message
// 3. Converted to EVM address by prover (if possible)
// 4. Used for reward distribution on source chain

​
Chain ID Considerations

The protocol uses uint64 for chain IDs to support both EVM and non-EVM chains:
contracts/Inbox.sol
uint64 private immutable CHAIN_ID;

constructor() {
    if (block.chainid > type(uint64).max) {
        revert ChainIdTooLarge(block.chainid);
    }
    CHAIN_ID = uint64(block.chainid);
}
Examples:
  • Ethereum Mainnet: 1
  • Polygon: 137
  • Arbitrum One: 42161
  • Solana Mainnet: 1399811149
  • Sui Mainnet: 101
The destination chain ID must fit within a uint64. Most major chains, including Solana and Sui, use chain IDs that fit within this range.

​
CREATE2 Prefix Support

The protocol adapts to different CREATE2 implementations:
contracts/IntentSource.sol
bytes1 private immutable CREATE2_PREFIX;

uint256 private immutable TRON_MAINNET_CHAIN_ID = 728126428;
uint256 private immutable TRON_TESTNET_CHAIN_ID = 2494104990;

constructor() {
    // TRON support
    CREATE2_PREFIX = block.chainid == TRON_MAINNET_CHAIN_ID ||
        block.chainid == TRON_TESTNET_CHAIN_ID
        ? bytes1(0x41)  // TRON chain custom CREATE2 prefix
        : bytes1(0xff); // Standard EVM CREATE2 prefix

    VAULT_IMPLEMENTATION = address(new Vault());
}
Vault address calculation: 
function _getVault(bytes32 intentHash) internal view returns (address) {
    return VAULT_IMPLEMENTATION.predict(intentHash, CREATE2_PREFIX);
}
This ensures deterministic vault addresses across different EVM implementations:
  • Standard EVM (Ethereum, Polygon, etc.): 0xff prefix
  • TRON: 0x41 prefix

​
Best Practices

Recommendations for protocol integrators:
  1. Use the universal types (bytes32-based) for core protocol interactions if you need cross-VM support
  2. Use EVM-specific types for user-facing interfaces on EVM chains
  3. Convert at the boundaries of your application using AddressConverter
  4. Test conversions thoroughly, especially bytes32 ↔ address transformations
  5. Document which format your interface expects (EVM address vs. bytes32 identifier)
  6. Validate identifiers before conversion to avoid truncation errors
Remember: Reward claiming is always EVM-specific on the source chain, even if the intent was fulfilled on a non-EVM destination chain. Provers must convert universal identifiers to EVM addresses.

Build docs developers (and LLMs) love

Get started for freeTalk to us