Architecture

The Unruggable Gateways codebase (opens in a new tab) includes both a Typescript (opens in a new tab) and a Solidity (opens in a new tab) version of the virtual machine. The idea is simple: write your code in Typescript to read data from your chosen Layer 2 (L2) network, then easily convert it to Solidity and deploy it without changes.

How It Works (High-Level Overview)

1. Your Contract: builds a GatewayRequest that is passed to our fetch (opens in a new tab) method defined in GatewayFetchTarget.sol (opens in a new tab).
2. Offchain Data Handling: The fetch method uses the ERC-3668 (opens in a new tab) standard and reverts with an OffchainLookup, instructing the client to query the Gateway.
3. Response Processing: The fetchCallback (opens in a new tab) method processes the response, using a chain-specific Verifier to validate proofs and return the results to the caller.

Core Components

1. Request Builder

• GatewayFetcher.sol (opens in a new tab) provides a public API for building a GatewayRequest. This request consists of a series of operations that the virtual machine interprets to read and process data from other rollups.
• Solidity developers can write contracts that build these requests by inheriting from GatewayFetchTarget.sol.
• A Typescript version is also available for easier development and testing. You can check out our Examples page for more details.

2. The Gateway

• The gateway.ts (opens in a new tab) Typescript file sets up a simple HTTP server to handle requests for data from other rollups. It uses a Rollup instance as a parameter (explained below).
• The gateway connects to the necessary rollup to gather data, create proofs, and send them back to the client, so users don’t have to interact directly with the rollups.

3. The Rollup

• Rollup classes (e.g. OPFaultRollup (opens in a new tab)) instruct the Gateway on how to request data and create verifiable proofs for that specific chain.
• They have methods (encodeWitness and encodeWitnessV1) that appropriately encode proof data fetched by the gateway in a way that is understood by the chain specific Verifier.

Commits

• A Commit represents the data submitted to Layer 1 (L1) by the L2 chain. It contains the data necessary to verify a proof returned by the Gateway.
• The chain specific rollup classes implement abstract methods (fetchLatestCommitIndex and fetchCommit) to help the Gateway fetch data/proofs for for the commit requested by the user.

4. Verifiers

• A Verifier is a Solidity contract deployed on L1. It is used by the ERC-3668 callback to verify the proofs returned by the Gateway.
• Different chains utilize different hashing functions and Trie structures. Verifiers use different verification steps based on the rollup.

Verifier Hooks

• Verifier Hook contracts implement the verifyAccountState, and verifyStorageValue interface (IVerifierHooks (opens in a new tab)) methods to specify how account and storage proofs should be used to verify state for specific Trie structures.

Gateway URL

• The Verifier specifies the URLs of the Gateways to query for handling a request via the gatewayURLs() method.
• The user can operate their own gateway and overwrite the gateways used to handle their request.

Context

• Each Verifier implements the getLatestContext method from the IGatewayVerifier (opens in a new tab) interface. This method determines what L2 chain state the request can access. The gateway considers this context when responding and includes it in its response.