Eco Routes

• Abstract
• Components
• Contract Addresses
• Future Work
• Usage
  • Installation
  • Testing
  • Deployment
  • End-to-End Testing
• Contributing
• License
• Contact

Abstract

An intents-driven, permissionless, trust-neutral protocol for facilitating the creation, incentivized execution, and proof of cross-L2 transactions.

Warning: This code has not been audited. Use at your own risk.

• Intent Creation / Settlement
• Intent Fulfillment / Execution
• Intent Proving

We identify three main user profiles:

• Users: Individuals who want to transact across different L2s.
• Fillers: Individuals interested in performing transactions on behalf of others for a fee.
• Provers: Individuals interested in proving on the source chain that an intent was fulfilled on the destination chain.

How it works

A User initiates a cross-chain transaction by creating an intent. Put simply, an intent represents a User's end goals on the destination chain. It contains the calls they'd want to make, those calls' corresponding addresses, and the price they'd be willing to pay someone to execute this call on their behalf, along with other metadata. Seeing this intent and being enticed by the fee they'd receive, a Filler creates and executes a fulfill transaction on the destination chain that corresponds to the user's intent, storing the fulfilled intent's hash on the destination chain. A Prover - perhaps the Filler themselves or a service they subscribe to - sees this fulfillment transaction and performs a proof that the hash of the fulfilled transaction on the destination chain matches that of the intent on the source chain. After the intent proven, the filler can withdraw their reward.

Components

Within the following sections, the terms 'source chain' and 'destination chain' will be relative to any given intent. Each supported chain will have its own IntentSource, Inbox, and Provers.

Intent Creation / Settlement

Intent creation and filler settlement processes both exist on the IntentSource on the source chain, and is where the full intent lifecycle will start and end. Both Users and Fillers interact with this contract, Users to create intents and Fillers to claim their reward after fulfillment has been proven.

Intent Fulfillment / Execution

Intent fulfillment lives on the Inbox, which lives on the destination chain. Fillers interact with this contract to fulfill Users' intents. At time of launch solving may be private, restricted only to a whitelisted set of filler addresses while we live test the system, but it will soon become possible for anyone to fill orders.

Intent Proving

Intent proving lives on the Prover and HyperProver contracts, which exist on the source chain. Provers are the parties that should be interacting with prover contracts, but the IntentSource does read state from it. There are currently two types of provers: StorageProvers (Prover.sol), which use storage proofs to verify the fulfillment of an intent, and HyperProvers(HyperProver.sol), which utilize a Hyperlane bridge in verifying intent fulfillment.

See contracts for a detailed API documentation

Contract Addresses

Mainnet Chains	IntentSource	Inbox	StorageProver	HyperProver
Optimism	0xa6B316239015DFceAC5bc9c19092A9B6f59ed905	0xfB853672cE99D9ff0a7DE444bEE1FB2C212D65c0	0xE00c8FD8b50Fed6b652A5cC66c1d0C090fde037f	0xAfD3029f582455ed0f06F22AcD916B27bc9b3a55
Base	0xa6B316239015DFceAC5bc9c19092A9B6f59ed905	0xfB853672cE99D9ff0a7DE444bEE1FB2C212D65c0	0xE00c8FD8b50Fed6b652A5cC66c1d0C090fde037f	0xc8E7060Cd790A030164aCbE2Bd125A6c06C06f69
Mantle	0xa6B316239015DFceAC5bc9c19092A9B6f59ed905	0xfB853672cE99D9ff0a7DE444bEE1FB2C212D65c0	0xE00c8FD8b50Fed6b652A5cC66c1d0C090fde037f	0xaf034DD5eaeBB49Dc476402C6650e85Cc22a0f1a
Arbitrum	0xa6B316239015DFceAC5bc9c19092A9B6f59ed905	0xfB853672cE99D9ff0a7DE444bEE1FB2C212D65c0	WIP	0xB1017F865c6306319C65266158979278F7f50118

Testnet Chains	IntentSource	Inbox	StorageProver	HyperProver
OptimismSepolia	0x734a3d5a8D691d9b911674E682De5f06517c79ec	0xB73fD43C293b250Cb354c4631292A318248FB33E	0xDcbe9977821a2565a153b5c3622a999F7BeDcdD9	0x39cBD6e1C0E6a30dF33428a54Ac3940cF33B23D6
BaseSepolia	0x734a3d5a8D691d9b911674E682De5f06517c79ec	0xB73fD43C293b250Cb354c4631292A318248FB33E	0xDcbe9977821a2565a153b5c3622a999F7BeDcdD9	0x39cBD6e1C0E6a30dF33428a54Ac3940cF33B23D6
MantleSepolia	0x734a3d5a8D691d9b911674E682De5f06517c79ec	0xB73fD43C293b250Cb354c4631292A318248FB33E	0xDcbe9977821a2565a153b5c3622a999F7BeDcdD9	WIP
ArbitrumSepolia	0x734a3d5a8D691d9b911674E682De5f06517c79ec	0xB73fD43C293b250Cb354c4631292A318248FB33E	WIP	0x6D6556B3a199cbbdcFE4E7Ba3FA6330D066A31a9

Future Work

Fully-operational end-to-end tests are currently under development. We are also working on services for streamlining and batching prover and solver functionalities. Additionally, we intend to build out support for additional chains.

Usage

To get a local copy up and running follow these simple steps.

Prerequisites

Running this project locally requires the following:

• NodeJS v18.20.3 - using nvm (instructions below)
• Yarn v1.22.19

It is recommended to use nvm to install Node. This is a Node version manager so your computer can easily handle multiple versions of Node:

1. Install nvm using the following command in your terminal:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

2. If you're not on an M1 Mac, skip to step 3. For Node < v15, nvm will need to be run in a Rosetta terminal since those versions are not supported by the M1 chip for installation. To do that, in the terminal simply run either:

If running bash:

arch -x86_64 bash

If running zsh:

arch -x86_64 zsh

More information about this can be found in this thread.

3. Install our Node version using the following command:

nvm install v18.20.3

4. Once the installation is complete you can use it by running:

nvm use v18.20.3

You should see it as the active Node version by running:

nvm ls

Installation

1. Clone the repo

 git clone [email protected]:the-eco-foundation/eco-routes.git

2. Install and build using yarn

 yarn install

 yarn build

Lint

yarn lint

Testing

# tests
$ yarn  test

# test coverage
$ yarn coverage

Deployment

Deploy using deploy.ts in the scripts directory. This script draws from the configs (found in the config directory) as well as a local .env file. See .env.example.

End-To-End Testing

This section is under development. While the tests are not yet operational, the scripts are available in the scripts directory

Contributing

1. Fork the Project
2. Create your Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

MIT License

(back to top)

Contact

Project Link: https://github.com/eco/eco-routes

(back to top)