Skip to content

Commit

Permalink
Merge pull request #1 from anton-rs/rf/feat/clean-up-docs
Browse files Browse the repository at this point in the history 
feat: Cleanup
  • Loading branch information
@refcell
refcell authored Aug 28, 2024
2 parents 0e3f69a + faea419 commit 1f18398
Show file tree
Hide file tree
Showing 2 changed files with 141 additions and 33 deletions.
169 changes: 139 additions & 30 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,34 +9,125 @@
<p align="center">
<a href="https://github.com/anton-rs/superchain/actions/workflows/rust_ci.yaml"><img src="https://github.com/anton-rs/superchain/actions/workflows/rust_ci.yaml/badge.svg?label=ci" alt="CI"></a>
<img src="https://img.shields.io/badge/License-MIT-green.svg?label=license&labelColor=2a2f35" alt="License">
<a href="https://github.com/ethereum-optimism/monorepo"><img src="https://img.shields.io/badge/OP%20Stack-monorepo-red?labelColor=2a2f35" alt="OP Stack"></a>
<a href="https://docs.optimism.io/"><img src="https://img.shields.io/badge/Docs-optimism.io-854a15?logo=mdBook&labelColor=2a2f35" alt="OP Stack Docs"></a>
<a href="https://github.com/ethereum-optimism/monorepo"><img src="https://img.shields.io/badge/OP%20Stack-config-red?labelColor=2a2f35" alt="OP Stack"></a>
</p>

<p align="center">
<a href="#whats-superchain">What's Superchain?</a> •
<a href="#usage">Usage</a> •
<a href="#example">Example</a> •
<a href="#feature-flags">Feature Flags</a> •
<a href="#credits">Credits</a>
</p>


## What's Superchain?

The [Superchain](https://docs.optimism.io/stack/explainer) is a network of chains that share bridging, decentralized governance, upgrades, a communication layer and more.
The [Superchain][op-superchain] is a network of chains that share bridging,
decentralized governance, upgrades, a communication layer and more.

Chain configurations for the [Superchain][op-superchain] are defined in the
[superchain-registry][sr] directory. This repository provides rust bindings
for the [ethereum-optimism/superchain-registry][osr].

The best way to interface with these rust bindings is through [`superchain`][s],
an optionally `no_std` crate that re-exports two core crates in this workspace.
- [`superchain-primitives`][sp]
- [`superchain-registry`][sr] _Only available if `serde` feature flag is enabled_


### `superchain-primitives`

[`superchain-primitives`][spc] is a `no_std` crate that contains rust types for the
configuration objects defined in the [`superchain-registry`][osr]. There are two
feature flags available on [`superchain-primitives`][spc], `std` and `serde`,
enabling the `std` library use and [`serde`][serde] serialization and deserialization
support.

Both `serde` and `std` are enabled by default but can be individually enabled when
`default-features = false`. In a project's `Cargo.toml`, to use the `superchain-primitives`
crate with `serde` support, add the following to the `[dependencies]` section.

```toml
# By default, superchain-primitives enables the `std` and `serde` feature flags.
superchain-primitives = { version = "0.3", features = [ "serde" ], default-features = false }
```

Alternatively, the [`superchain`][sc] crate can be used which re-exports the
[`superchain-primitives`][spc].

```toml
superchain = { version = "0.3", default-features = false }
```

[`superchain-primitives`][spc] has minimal dependencies itself and uses [alloy][alloy] Ethereum
types internally. Below provides a breakdown of core types defined in [`superchain-primitives`][spc].

**`ChainConfig`**

The [`ChainConfig`][cc-html] is an execution-layer construct defining a configuration for this chain.
It's output from the `add-chain` command in the [`superchain-registry`][osr]. It contains genesis
data, addresses for the onchain system config, hardfork timestamps, rpc information, and other
superchain-specific information. Static chain config files are defined in the
[`superchain-registry`][osr].

**`RollupConfig`**

The [`RollupConfig`][rc-html] defines the configuration for a rollup node, the consensus-layer.
The [`RollupConfig`][rc-html] defines the parameters used for deriving the L2 chain as well as
batch-submitting data on L1.

[`superchain-primitives`][spc] also exposes a few default `RollupConfig`s for convenience,
providing an alternative to depending on [`superchain-registry`][osr] with `serde` required.

This repository contains rust bindings for the [superchain-registry][sr].
**`Superchain`**

The best way to work with this repo is through the [`superchain`][sup]
crate. [`superchain`][sup] is an optionally `no_std` crate that provides
core types and bindings for the Superchain.
[`Superchain`][s-html] defines a superchain for a given L1 network. It holds metadata
such as the name of the superchain, the L1 anchor information (chain id, rpc, explorer), and
default hardfork configuration values. Within the [`Superchain`][s-html], there's a list
of [`ChainConfig`][cc-html]s that belong to this superchain.

It re-exports two crates:
- [`superchain-primitives`][scp]
- [`superchain-registry`][scr] _Only available if `serde` feature flag is enabled_

[`superchain-primitives`][scp] defines core types used in the `superchain-registry`
along with a few default values for core chains.
### `superchain-registry`

[`superchain-registry`][src] is a `no_std` crate that exports rust type definitions for chains
in the [`superchain-registry`][osr]. Since it reads static files to read configurations for
various chains into instantiated objects, the [`superchain-registry`][osr] crate requires
`serde` as a dependency and enables `serde` features on dependencies including
[`superchain-primitives`][spc]. To use the [`superchain-regsitry`][src] crate, add the crate
as a dependency to a `Cargo.toml`.

```toml
# By default, superchain-registry enables the `std` feature, disabling `no_std`.
superchain-registry = { version = "0.3", default-features = false }
```

Alternatively, the [`superchain`][sc] crate can be used which re-exports the [`superchain-registry`][src].

```toml
superchain = "0.3"
```

[`superchain-registry`][src] declares lazy evaluated statics that expose `ChainConfig`s, `RollupConfig`s,
and `Chain` objects for all chains with static definitions in the superchain registry. The way this works
is the the golang side of the superchain registry contains an "internal code generation" script that has
been modified to output configuration files to the [`crates/superchain-registry`][sr] directory in the
`etc` folder that are read by the [`superchain-registry`][src] rust crate. These static config files
contain an up-to-date list of all superchain configurations with their chain configs.

There are three core statics exposed by the [`superchain-registry`][src].
- `CHAINS`: A list of chain objects containing the superchain metadata for this chain.
- `OPCHAINS`: A map from chain id to `ChainConfig`.
- `ROLLUP_CONFIGS`: A map from chain id to `RollupConfig`.

Where the [`superchain-primitives`][spc] crate contains a few hardcoded `RollupConfig` objects, the
[`superchain-registry`][src] exports the _complete_ list of superchains and their chain's `RollupConfig`s
and `ChainConfig`s, at the expense of requiring `serde`.

[`CHAINS`][chains], [`OPCHAINS`][opchains], and [`ROLLUP_CONFIGS`][rollups] are exported at the top-level
of the [`superchain-primitives`][spc] crate and can be used directly. See the [usage](#usage) section
below for how to work with [`superchain-registry`][src] mappings.

[`superchain-registry`][scr] provides bindings to all chains in the `superchain`.

## Usage

Expand All @@ -47,21 +138,24 @@ Add the following to your `Cargo.toml`.
superchain = "0.2"
```

To make make `superchain` `no_std`, toggle `default-features` off like so.
To make `superchain` `no_std`, toggle `default-features` off like so.

> [!NOTE]
>
> The `superchain-registry` is only available if the `serde` feature is enabled.

```toml
[dependencies]
superchain = { version = "0.2", default-features = false }
```

## Example

[`superchain-registry`][scr] exposes lazily defined mappings from chain id
to chain configurations that the [`superchain`][sup] re-exports. Below
demonstrates getting the `RollupConfig` for OP Mainnet (Chain ID `10`).
The re-exported [`superchain-registry`][src] exposes lazily defined mappings
from L2 chain id to chain configurations. Below demonstrates getting the
`RollupConfig` for OP Mainnet (Chain ID `10`).

```rust
use superchain::ROLLUP_CONFIGS;
use superchain::registry::ROLLUP_CONFIGS;

let op_chain_id = 10;
let op_rollup_config = ROLLUP_CONFIGS.get(&op_chain_id);
Expand All @@ -71,7 +165,7 @@ println!("OP Mainnet Rollup Config: {:?}", op_rollup_config);
A mapping from chain id to `ChainConfig` is also available.

```rust
use superchain::OPCHAINS;
use superchain::registry::OPCHAINS;

let op_chain_id = 10;
let op_chain_config = OPCHAINS.get(&op_chain_id);
Expand All @@ -80,20 +174,35 @@ println!("OP Mainnet Chain Config: {:?}", op_chain_config);

## Feature Flags

- `serde`: Enables [`serde`][s] support for types and makes [`superchain-registry`][scr] types available.
- `serde`: Enables [`serde`][serde] support for types and makes [`superchain-registry`][src] types available.
- `std`: Uses the standard library to pull in environment variables.

## Credits

This repository could not be built without OP Labs contributors working on the [superchain-registry][scr] and [alloy-rs](https://github.com/alloy-rs) contributors.
[superchain-registry][osr] contributors for building and maintaining superchain types.

[Alloy][alloy] for creating and maintaining high quality Ethereum types in rust.


<!-- Hyperlinks -->

[sp]: ./crates/superchain-primitives
[serde]: https://crates.io/crates/serde
[alloy]: https://github.com/alloy-rs/alloy
[superchain-repo]: https://github.com/anton-rs/superchain
[op-superchain]: https://docs.optimism.io/stack/explainer
[osr]: https://github.com/ethereum-optimism/superchain-registry

[s]: https://crates.io/crates/serde
[sr]: https://github.com/ethereum-optimism/superchain-registry
[scr]: https://crates.io/crates/superchain-registry
[sup]: https://crates.io/crates/superchain
[scp]: https://crates.io/crates/superchain-primitives
[superchain]: https://github.com/anton-rs/superchain
[s]: ./crates/superchain
[sp]: ./crates/superchain-primitives
[sr]: ./crates/superchain-primitives
[sc]: https://crates.io/crates/superchain
[src]: https://crates.io/crates/superchain-registry
[spc]: https://crates.io/crates/superchain-primitives

[chains]: https://docs.rs/superchain-registry/latest/superchain_registry/struct.CHAINS.html
[opchains]: https://docs.rs/superchain-registry/latest/superchain_registry/struct.OPCHAINS.html
[rollups]: https://docs.rs/superchain-registry/latest/superchain_registry/struct.ROLLUP_CONFIGS.html

[s-html]: https://docs.rs/superchain-primitives/latest/superchain_primitives/superchain/struct.Superchain.html
[cc-html]: https://docs.rs/superchain-primitives/latest/superchain_primitives/chain_config/struct.ChainConfig.html
[rc-html]: https://docs.rs/superchain-primitives/latest/superchain_primitives/rollup_config/struct.RollupConfig.html
5 changes: 2 additions & 3 deletions crates/superchain/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,11 @@
#![cfg_attr(not(feature = "std"), no_std)]
#![cfg_attr(not(test), warn(unused_crate_dependencies))]

/// Re-export types from [superchain_primitives].
pub use superchain_primitives as primitives;
pub use superchain_primitives::*;

/// Re-export [superchain_registry].
#[cfg(feature = "serde")]
pub use superchain_registry;
pub use superchain_registry as registry;

#[cfg(feature = "serde")]
pub use superchain_registry::{
Expand Down

0 comments on commit 1f18398

Please sign in to comment.