@unruggable/gateways

Unruggable Gateways

This repository provides an end-to-end solution for proving data from rollup chains and verifying it against state posted on the parent chain.

Audits

The codebase has been audited. Details of our audits can be found here.

Quickstart

npm i @unruggable/gateways ✓

• We have extensive documentation, with a slightly less quick Quickstart.
• The examples page may be of particular interest.
• We also have an examples repo that utilises our npm package to demonstrate both simple and complex use cases in a few clicks.

Architecture

• Request — a program that fetches data from one or more contracts
  • constructable in Solidity and TypeScript using (almost) the same syntax
• Commit — a commitment (eg. StateRoot) of one chain on another
• VM — a machine that executes a Request for a Commit
  • TypeScript — records sequence of necessary proofs
  • Solidity — verifies sequence of supplied proofs (in the same order)
• Rollup (TypeScript) — traverses Commit history, generates a Commit proof and supplies a Prover
• Prover (TypeScript) — generates rollup-specific Account and Storage proofs
• Gateway (TypeScript) — receives a Request, finds the appropriate Commit, executes the VM, and responds with a sequence of proofs via CCIP-Read
• Verifier (Solidity) — verifies a Commit proof and executes the VM with Hooks
• Verifier Hooks (Solidity) — verifies rollup-specific Account and Storage proofs

Chain Support

• Rollups & Verifers
  • Superchain
  • Superchain w/Fault Proofs
  • Arbitrum: Nitro and BoLD
  • Linea (and Unfinalized)
  • Polygon PoS
  • Scroll and Euclid
  • Taiko
  • ZKSync
  • Reverse OP — L2 → L1
  • Self — any → itself
  • Trusted — any → any
  • Unchecked — any → any
  • DoubleArbitrum — L1 → L2 → L3
  • Polygon ZK — WIP
  • Morph — WIP
  • Starknet — WIP
• Provers
  • Eth — eth_getProof
  • Linea — linea_getProof
  • ZKSync — zks_getProof
  • ZKEVM — zkevm_getProof — WIP
  • Starknet — pathfinder_getProof — WIP
• Verifier Hooks
  • Eth — Patricia Merkle Tree
  • Linea — Sparse Merkle Tree + Mimc
  • Scroll — Binary Merkle Tree + Poseidon
  • ZKSync — Sparse Merkle Tree + Blake2S

If you are interested in building a solution for another chain, please take a look at our our Contribution Guidelines and/or get in touch.

Setup

• foundryup
• forge i
• bun i
• create .env

Running a Gateway

• bun run serve <chain> [port]
  • eg. bun run serve op 9000
  • Chains: 1 or 0x1 or mainnet
  • Default port: 8000
  • Use trusted:<chain> for TrustedRollup
    • eg. bun run serve trusted:op
    • Include 0x{64} to set signing key
  • Use unchecked:<chain> for UncheckedRollup
  • Use reverse:<chain> for ReverseOPRollup
  • Use self:<chain> for EthSelfRollup
  • Include --unfinalized(=minAge) to use unfinalized commits (will throw if not available)
  • Include --latest for "latest" instead of "finalized" block tag
  • Include --debug to print OP_DEBUG statements
  • Include --calls to print RPC calls.
  • Include --dump to print config, latest commit, prover information, and then exit.
  • Include --no-fast to disable eth_getStorageAt
  • Include --no-cache to disable caching
  • Include --no-double to disable double rollups
    • eg. if APE, serves L2 → L3 instead of L1 → L2 → L3
  • Include --depth=# to adjust commit depth
  • Include --step=# to adjust commit step
  • Use PROVIDER_ORDER to customize global RPC provider priority.
  • Use PROVIDER_ORDER_{CHAIN_NAME} to customize per-chain RPC provider priority.
  • Use PROVIDER_{CHAIN_NAME} to customize per-chain RPC provider override.
  • Use BEACON_{CHAIN_NAME} to customize per-chain Beacon RPC provider override.

Testing

There is an extensive test suite available for testing individual components of the solution in an isolated manner.

Using Foundry and blocksmith.js, we fork the chain in question (such that can interact with contracts deployed on a real network) and then deploy and test against an isolated unit (for example the chain specific verifier).

Commands available include:

• bun run test
  • bun run test-components
    • Supported Operations
    • Protocol Limits
    • Batched eth_getProof
  • bun run test-gateways
    • Contract → Reader → Tests
    • ⚠️ Polygon has poor eth_getProof support

Examples

A number of examples are provided as part of this repository. For more extensive step-wise example code, please see our documentation.

• linea-ens
  • Replacement backend demo for https://names.linea.build/
  • bun serve v1:linea

Notes

Suggested VSCode Extensions

• JuanBlanco.solidity
• esbenp.prettier-vscode
• dbaeumer.vscode-eslint

Forge Setup

# installed by forge in step (2)
# provided for reference
forge install foundry-rs/forge-std
forge install OpenZeppelin/openzeppelin-contracts@v5.0.2

# installed by script instead of the following command
# placed at standard remapping location
# see: https://github.com/ethereum-optimism/optimism/issues/10202
#forge install ethereum-optimism/optimism
bun script/import-op.ts

Contribution Guidelines

We welcome contributions to this codebase.

The premise behind the development of this software is to minimise duplication of effort and provide tooling that allows developers to interface with a simple, standardised API to read data from other chains.

Please take a look at our CONTRIBUTING.md file for a more in depth overview of our contribution process.

Release Process

Branching strategy

• main is our stable release branch that reflects the latest release.
• develop is our ongoing development branch. Feature branches are to merged down into this.
• Feature Branches: Separate branches will be utilised for new feature development or bug fixes.

License

All files within this repository are licensed under the MIT License unless stated otherwise.