@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.

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
  • OP
  • OP w/Fault Proofs
  • Nitro
  • Linea
  • Polygon PoS
  • Polygon ZK — WIP
  • Scroll
  • Taiko
  • ZKSync
  • Reverse OP — L2 → L1
  • Self — any → itself
  • Trusted — any → any
  • DoubleNitro — L1 → L2 → L3
• Provers
  • Eth — eth_getProof
  • Linea — linea_getProof
  • ZKSync — zks_getProof
  • ZKEVM — zkevm_getProof
• 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 install
• bun i
• create .env

Running a Gateway

• bun run serve <chain> [port]
  • eg. bun run serve op 9000
  • Chains: ape arb1-sepolia arb1 base-sepolia base blast celo-alfajores cyber fraxtal ink-sepolia linea-sepolia lineaV1 linea mantle mode op-sepolia op opbnb polygon redstone reverse-op scroll-sepolia scroll self-eth self-holesky self-sepolia shape soneium-minato taiko-hekla taiko unichain-sepolia zero-sepolia zero zksync-sepolia zksync zora
  • Default port: 8000
  • Use trusted:<Chain> for a TrustedRollup
    • eg. bun run serve trusted:op
    • Include 0x{64} to set signing key
  • Include --unfinalized 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 --dump to print config, latest commit, prover information, and then exit.

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
    • ⚠️ Scroll fails readZero() test
    • ⚠️ 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 lineaV1

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.