Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: update to v3.0.0 #1609

Closed
wants to merge 9 commits into from
Closed
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
docs: updates for new fallback
  • Loading branch information
jcstein committed Jun 18, 2024
commit 0b13a11f41a18d108cc45eade23f85282727f55f
75 changes: 17 additions & 58 deletions developers/arbitrum-deploy.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ and [the original deployment guide](https://docs.arbitrum.io/launch-orbit-chain/
running on your machine
- [Docker Compose](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-compose-on-ubuntu-20-04)
- A fully synced and funded Mocha testnet [light node](../nodes/light-node.md)
on **v0.13.2**
on **v0.13.7**
- [Mocha testnet faucet](../nodes/mocha-testnet.md#mocha-testnet-faucet)
- A browser-based Ethereum wallet (like [MetaMask](https://metamask.io))
- At least 1 Arbitrum Sepolia testnet ETH (for custom gas token chains,
Expand Down Expand Up @@ -180,36 +180,7 @@ root of your cloned `orbit-setup-script` repository.

3. Install dependencies by running `yarn install` from the root of the `orbit-setup-script` repository.

### Step 6: Pick an L2 RPC URL for the Batch Poster

In order for the Batch Poster, which is responsible for posting batches of data, to
subscribe to Blobstream's smart contract events, the node most use a WebSocket
connection, since an HTTP one will not support subscriptions. This RPC URL is different
from the `parent-chain.connection.url` object used in the node config, and is
not necessary when running a full node. WebSocket (WSS) URLs which are
essential for real-time data fetching and interaction with the
Arbitrum Sepolia network.

To establish a WebSocket connection for your rollup to Arbitrum Sepolia, it's
recommended to
[find an RPC provider with WSS connections from Arbitrum's docs](https://docs.arbitrum.io/build-decentralized-apps/reference/node-providers).

For this example, we will make an account on Alchemy. Follow these steps to set up your account and obtain a WSS URL using Alchemy:

1. Visit [Alchemy's website](https://www.alchemy.com/) and sign up for an account.
2. Once logged in, create a new app by selecting the Arbitrum network, specifically
targeting the Arbitrum Sepolia testnet.
3. After creating your app, navigate to the "API key" section to find your WebSocket
(WSS) URL.
4. In the next step, use this WSS URL in your `nodeConfig.json` under the
`celestia-cfg.eth-rpc` object to ensure your node can establish a
WebSocket connection to the Arbitrum Sepolia network
and successfully subscribe to Blobstream events.

Without a WSS connection, the Batch Poster won't be able to subscribe to Blobstream
events, and thus will fall back to posting data to parent chain.

### Step 7: Run your light node for Mocha testnet
### Step 6: Run your light node for Mocha testnet

First, be sure that your light node is running, using a command similar to:

Expand Down Expand Up @@ -246,25 +217,16 @@ to communicate with Blobstream, you now only have to configure your node
accordingly. First understand the different variables that will be set in the config:

- **`enable`:** set it to true if you are using Celestia DA 😁
- **`gas-price`:** how much to pay for gas (in uTIA)
- **`gas-multiplier`:** will increase the gas price linearly based on the number
you provide. 1.01 increases the gas by 1%.
- **`rpc`:** RPC endpoint for **celestia-node**
- **`tendermint-rpc`:** a celestia-core endpoint from a full node
(**NOTE:** only needed for a batch poster node)
- **`eth-rpc`:** Ethereum Client WSS RPC endpoint, only used when the node is a batch
poster. The eth-rpc must be WSS. Otherwise, it won't be able to subscribe to events
for Blobstream.
- **`namespace-id`:** namespace being used to post data to Celestia
- **`auth-token`:** auth token for your Celestia Node
- **`is-poster`:** is the node with Celestia DA the batch poster, set to true if so.
- **`gas-price`:** how much to pay for gas (in uTIA)
- **`event-channel-size`:** size of the events channel used by the batch poster
to wait for a range of headers that contains the header for the block in which
it posted a blob, before posting the batch to the base layer for verification
on Blobstream X.
- **`blobstreamx-address`:** address of the Blobstream X contract on the base chain.
- Note that the `SequencerInbox` contract for each chain has a constant
address for the `BlobstreamX` contract, thus make sure that the Blobstream X
address in the `SequencerInbox` being used for the templates in
`RollupCreator` matches the one in your config.
- **`noop-writer`:** setting this to true allows you to force fallbacks by
disabling storing posting data to Celestia
- **`validator-config` (optional):** optional validator configuration as
described on [Running a full node and/or validator](./arbitrum-full-node.md)

Now enable Celestia DA in your Arbitrum chain params in
`config/nodeConfig.json`. If you'd like to use your own namespace,
Expand All @@ -283,21 +245,18 @@ This is crucial to protect against potential misuse by copy-paste errors.
```ts
"celestia-cfg": {
"enable": true,
"gas-price": 0.01,
"gas-multiplier", 1.01,
"rpc": "http://host.docker.internal:26658",
"tendermint-rpc": "http://consensus-full-mocha-4.celestia-mocha.com:26657",
"eth-rpc": "wss://<YOUR_ETH_RPC_WSS_URL>",
"namespace-id": "<YOUR_10_BYTE_NAMESPACE>",
"auth-token": "<YOUR_AUTH_TOKEN>",
"is-poster": true,
"gas-price": 0.3,
"event-channel-size": 100,
"blobstreamx-address": "0xc3e209eb245Fd59c8586777b499d6A665DF3ABD2",
"noop-writer": false,
}
```

[See the compatibility matrix in the appendix to verify you're using the right versions.](#compatibility-matrix)

### Step 8: Run your chain's node and block explorer
### Step 7: Run your chain's node and block explorer

Start Docker, then run `docker-compose up -d` from the root of
the `orbit-setup-script` repository.
Expand All @@ -313,7 +272,7 @@ After you have some activity on your rollup, it will look more like this:

![explorer-view](/arbitrum/explorer-view.png)

### Step 9: Finish setting up your chain
### Step 8: Finish setting up your chain

The Offchain Labs team has provided a Hardhat script that
handles the following tasks:
Expand Down Expand Up @@ -416,14 +375,14 @@ Extra resources in Arbitrum documentation:
| Nitro | [v2.3.3](https://github.com/celestiaorg/nitro/releases/tag/v2.3.3) | Includes the replay binary for the WASM root `0x9286b47ebb3f668fbba011c0e541655a7ecc833032154bba0d8d5ce4f2411f2a`. [Read the overview for overall changes](../developers/arbitrum-integration.md). |
| Contracts | [v1.2.1-celestia](https://github.com/celestiaorg/nitro-contracts/releases/tag/v1.2.1-celestia) | Integrates Blobstream X functionality into nitro-contracts v1.2.1 |
| Orbit SDK | [v0.8.2 Orbit SDK for Celestia DA](https://github.com/celestiaorg/arbitrum-orbit-sdk/releases/tag/v0.8.2) | This is not compatible with Orbit SDK v0.8.2 or with the latest changes to nitro-contracts for the Atlas upgrade. The Orbit SDK itself is in Alpha. |
| celestia-node | [v0.13.1](https://github.com/celestiaorg/celestia-node/releases/tag/v0.13.1) | This integration has only been tested with celestia-node 0.13.1 and only works with said version, and with future versions after that. Under the hood, the Nitro node uses [this commit](https://github.com/celestiaorg/celestia-openrpc/commit/64f04840aa97d4deb821b654b1fb59167d242bd1) of celestia-openrpc. |
| celestia-node | [v0.13.7](https://github.com/celestiaorg/celestia-node/releases/tag/v0.13.7) | This integration has only been tested with celestia-node 0.13.7 and only works with said version, and with future versions after that. Under the hood, the Nitro node uses [this commit](https://github.com/celestiaorg/celestia-openrpc/commit/64f04840aa97d4deb821b654b1fb59167d242bd1) of celestia-openrpc. |
<!-- markdownlint-enable MD013 -->

### Blobstream X contract deployments

The Orbit contracts depend on the following Blobstream X deployments.
The current deployments, which can be found at
`0xc3e209eb245Fd59c8586777b499d6A665DF3ABD2` in both chains, relays
The current deployments, which can be
[found on the Blobstream page](../developers/blobstream#deployed-contracts), relays
headers from the **Mocha-4** testnet to the chains below:

- Ethereum Sepolia
Expand Down
39 changes: 37 additions & 2 deletions developers/arbitrum-full-node.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,13 @@ with the difference being that you will use this image:
in the Arbitrum docs.

Note that you can either use the flags in the nitro binary + the flags
[found in the celestia package](https://github.com/celestiaorg/nitro/blob/v2.3.1-rc.1/das/celestia/celestia.go#L53-L65),
[found in the celestia package](https://github.com/celestiaorg/nitro/blob/v2.3.3/das/celestia/celestia.go#L53-L65),
or you can just provide a node `config.json` file with the `celestia-cfg`
for them to run it, which would look something like this:

```json
docker run --rm -v "$HOME/Documents/configs/nodeConfig.json:/config.json:ro" \
--network host celestia-nitro:v2.3.1-rc.1 --conf.file /config.json
--network host celestia-nitro:v2.3.3 --conf.file /config.json
```

## Running a full node with validation
Expand All @@ -37,3 +37,38 @@ The information above applies to
Finally, note that this will require connection to a DA node,
and we recommend running a Bridge node if you will be instantiating
multiple rollups.

### Configuring your validating full node

An optional configuration is required when running a validating full node.
Configuration options for validating full nodes include:

- **`tendermint-rpc`:** a celestia-core endpoint from a full node
(**NOTE:** only needed for a batch poster node)
- **`eth-rpc`:** Ethereum Client WSS RPC endpoint, only used when the node is a batch
poster. The eth-rpc must be WSS. Otherwise, it won't be able to subscribe to events
for Blobstream.
- **`blobstream`:** address of the Blobstream X contract on the base chain.
- Note that the `SequencerInbox` contract for each chain has a constant
address for the `BlobstreamX` contract, thus make sure that the Blobstream X
address in the `SequencerInbox` being used for the templates in
`RollupCreator` matches the one in your config.

An example configuration with `validator-config` can be found below:

```ts
"celestia-cfg": {
"enable": true,
"gas-price": 0.01,
"gas-multiplier", 1.01,
"rpc": "http://host.docker.internal:26658",
"namespace-id": "<YOUR_10_BYTE_NAMESPACE>",
"auth-token": "<YOUR_AUTH_TOKEN>",
"noop-writer": false,
"validator-config": {
"tendermint-rpc": "http://consensus-full-mocha-4.celestia-mocha.com:26657",
"eth-rpc": "wss://<YOUR_ETH_RPC_WSS_URL>",
"blobstream": "0xc3e209eb245Fd59c8586777b499d6A665DF3ABD2",
},
}
```
40 changes: 22 additions & 18 deletions developers/arbitrum-integration.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
description: An overview of the integration of Arbitrum Nitro with Celestia, detailing the key features and benefits, including the Ethereum fallback mechanism.
description: An overview of the integration of Arbitrum Nitro with Celestia, detailing the key features and benefits, including the DA fallback mechanism.
---

# Introduction to Arbitrum rollups with Celestia as DA
Expand All @@ -26,7 +26,7 @@ The integration of Celestia with Arbitrum orbit is possible thanks to 3 key comp
- [Preimage Oracle implementation](#preimage-oracle-implementation)
- [Blobstream X implementation](#blobstream-x-implementation)

Additionally, the [Ethereum fallback mechanism](#ethereum-fallback-mechanism-in-nitro) is a feature of the integration, which is native in Nitro.
Additionally, the [DA fallback mechanism](#da-fallback-mechanism-in-nitro) is a feature of the integration, which is native in Nitro.

### DA provider implementation

Expand All @@ -37,28 +37,25 @@ This integration implements the [`DataAvailabilityProvider` interface for Celest
Additionally, this integration comes with
[the necessary code for a Nitro chain node to post and retrieve data from Celestia](https://github.com/celestiaorg/nitro/tree/v2.3.1-rc.1/das/celestia).

The core logic behind posting and retrieving data happens in [celestia.go](https://github.com/celestiaorg/nitro/blob/v2.3.1-rc.1/das/celestia/celestia.go) where data is stored on Celestia and serialized into a small batch of data that gets published once the necessary range of headers (data roots) has been relayed to the [BlobstreamX contract](https://github.com/succinctlabs/blobstreamx).
The core logic behind posting and retrieving data happens in [celestia.go](https://github.com/celestiaorg/nitro/blob/v2.3.1-rc.1/das/celestia/celestia.go) where data is stored on Celestia and serialized into a small batch of data that gets published in the sequencer inbox contract.
Then the `Read` logic takes care of taking the deserialized Blob Pointer struct and consuming it in order to fetch the data from Celestia and additionally inform the fetcher about the position of the data on Celestia (we'll get back to this in the next section).

The following represents a non-exhaustive list of considerations when running a Batch Poster node for a chain with Celestia underneath:
- You will need to use a consensus full node RPC endpoint, you can find a list of them for Mocha [here](https://docs.celestia.org/nodes/mocha-testnet#rpc-endpoints)
- The Batch Poster will only post a Celestia batch to the underlying chain if the height for which it posted is in a recent range in BlobstreamX and if the verification succeeds, otherwise it will discard the batch. Since it will wait until a range is relayed, it can take several minutes for a batch to be posted, but one can always make an on-chain request for the BlobstreamX contract to relay a header promptly.

The following represents a non-exhaustive list of considerations when running a Nitro node for a chain with Celestia underneath:
- The `TendermintRpc` endpoint is only needed by the batch poster, every other node can operate without a connection to a full node.
- The message header flag for Celestia batches is `0x0c`.

- You will need to run the DA server for Celestia that connects to your Celestia DA node
- The message header flag for Celestia batches is `0x63`.
- You will need to know the namespace for the chain that you are trying to connect to, but don't worry if you don't find it, as the information in the BlobPointer can be used to identify where a batch of data is in the Celestia Data Square for a given height, and thus can be used to find out the namespace as well!

### Preimage Oracle Implementation

In order to support fraud proofs, this integration has the necessary code for a Nitro validator to populate its preimage mapping with Celestia hashes that then get "unpealed" in order to reveal the full data for a Blob. You can
In order to support fraud proofs, this integration has the necessary code for a Nitro validator to populate its preimage mapping with Celestia hashes that then get "unpeeled" in order to reveal the full data for a Blob. You can
[read more about the "Hash Oracle Trick"](https://docs.arbitrum.io/inside-arbitrum-nitro/#readpreimage-and-the-hash-oracle-trick).

The data structures and hashing functions for this can be found in the [`nitro/das/celestia/tree` folder](https://github.com/celestiaorg/nitro/tree/v2.3.1-rc.1/das/celestia/tree)
The data structures and hashing functions for this can be found in the [`nitro/das/celestia/tree` folder](https://github.com/celestiaorg/nitro/tree/v2.3.3/das/celestia/tree)

You can see where the preimage oracle gets used in the fraud proof replay binary [here](https://github.com/celestiaorg/nitro/blob/966e631f1a03b49d49f25bea67a92b275d3bacb9/cmd/replay/main.go#L153-L294)

Something important to note is that the preimage oracle only keeps track of hashes for the rows in the Celestia data square in which a blob resides in, this way each Orbit chain with Celestia underneath does not need validators to recompute an entire Celestia Data Square, but instead, only have to compute the row roots for the rows in which it's data lives in, and the header data root, which is the binary merkle tree hash built using the row roots and column roots fetched from a Celestia node. Because only data roots that can be confirmed on Blobstream get accepted into the sequencer inbox, one can have a high degree of certainty that the canonical data root being unpealed as well as the row roots are in fact correct.
Something important to note is that the preimage oracle only keeps track of hashes for the rows in the Celestia data square in which a blob resides in, this way each Orbit chain with Celestia underneath does not need validators to recompute an entire Celestia Data Square, but instead, only have to compute the row roots for the rows in which it's data lives in, and the header data root, which is the binary merkle tree hash built using the row roots and column roots fetched from a Celestia node. Because only data roots that can be confirmed on Blobstream get accepted into the sequencer inbox, one can have a high degree of certainty that the canonical data root being unpeeled as well as the row roots are in fact correct.

### Blobstream X implementation

Expand All @@ -72,29 +69,36 @@ which relays commitments to Celestia’s data root to an onchain light client
on Ethereum. This allows L2 solutions that settle on Ethereum to benefit
from the scalability Celestia’s data availability layer can provide.

### Ethereum fallback mechanism in Nitro
### DA fallback mechanism in Nitro

By default in [Arbitrum Nitro](https://github.com/OffchainLabs/nitro), the
[Ethereum fallback mechanism in the `BatchPoster` function](https://github.com/OffchainLabs/nitro/blob/master/arbnode/batch_poster.go#L989-L1001)
[DA fallback mechanism in the `BatchPoster` function](https://github.com/OffchainLabs/nitro/blob/master/arbnode/batch_poster.go#L989-L1001)
is handling the process of storing data, with a fallback mechanism
to store data onchain if the primary data availability storage
fails.

The [@celestiaorg/nitro](https://github.com/celestiaorg/nitro) integration
[uses the same fallback mechanism](https://github.com/celestiaorg/nitro/blob/f01968eb3d4e19329e9c92b050e98a8e5772f1f2/arbnode/batch_poster.go#L845-L857).
[uses a similar fallback mechanism](https://github.com/celestiaorg/nitro/blob/celestia-v3.0.0/arbnode/batch_poster.go#L1264-L1272).

[More information can be found on the Ethereum fallback mechanisms for Celestia](./ethereum-fallback.md),
which enables Ethereum L2s (or L3s) to “fall back” to using Ethereum
[More information can be found on the DA and Ethereum fallback mechanisms for Celestia](./ethereum-fallback.md),
which enables Ethereum L2s (or L3s) to “fall back” to using Anytrust DAC or Ethereum
calldata for data availability in the event of downtime on Celestia Mainnet
Beta.

The fallback logic for Celestia DA is configurable, providing an alternative
to the previous default fallback mechanism. Additionally, an ability has been
to the previous default fallback mechanism.
For example, using the fallback to Anytrust is useful
if you plan on having high throughput and cannot fallback to Ethereum
because your blobs are too big.

Additionally, an ability has been
added to the Arbitrum node software which allows the sequencer to call
`VerifyAttestation` to check if a data root has been posted on Blobstream or
not, before it sends the sequencer message (data pointer) to the underlying
chain.



## Next steps

In the next page,
Expand Down
Loading