Skip to content

Commit

Permalink
docs: combine Blobstream and Blobstream X docs (#1379)
Browse files Browse the repository at this point in the history 
* docs: initial attempt to integrate BlobstreamX docs

* Update nodes/hardfork-process.md

* feat: rearrange menu and remove old workflow

* docs: add snippets to proofs queries

* chore: blobstream -> blobstreamx

* chore: contract -> library

* chore: contract -> library

* chore: tabs

* docs: add proofs queries overview

* chore: remove unnecessary note

* docs: add listening for new events docs

* feat: add initial blobstream x intro section + linting + formatting

* feat: add overview of blobstream x section

* feat: wrap up edits to blobstream.md page for blobstream x

* feat: edits to blobstream.md

* feat: add local blobstream x instructions

* docs: address code review changes

* Update developers/blobstreamx-offchain.md

by @Gunter038

* docs:some feedback by @puma314

* feat: add proof language

* feat: update requesting-data-commitment-ranges intro

* feat: feedback for description on requesting-data-commitment-ranges.md page

* feat: use sections for datacommittment ranges page

* feat: split blobstreamxdeploy page into sections

* feat: upgrade diagrams

* Apply suggestions from code review

* feat: upgrade contracts with placeholders

* feat: remove page and link to succint docs

* feat: add docs.succint.xyz in place of succint.xyz

* feat: add testnet on table

* feat: resolve todos

* feat: add links to mocha/mainnet

* feat: add blobstream header for clarity

* feat: put intro in menu bc top level link of menu is weird

* feat: styling updates and graphics update

* feat: add page back for blobstream-x deploy

* docs: Apply suggestions from code review

Co-authored-by: CHAMI Rachid <[email protected]>

* Apply suggestions from code review

Co-authored-by: CHAMI Rachid <[email protected]>

* feat: feedback from comment on GH

* feat: update file paths and config.ts

* Update developers/blobstream.md

* Apply suggestions from code review

* Apply suggestions from code review

---------

Co-authored-by: joshcs.eth ᵍᵐ <[email protected]>
Co-authored-by: Josh Stein <[email protected]>
  • Loading branch information
@rach-id @jcstein
3 people authored Feb 22, 2024
1 parent 37907c4 commit e251e39
Show file tree
Hide file tree
Showing 17 changed files with 1,101 additions and 1,413 deletions.
46 changes: 18 additions & 28 deletions .vitepress/config.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -411,33 +411,6 @@ function sidebarHome() {
],
},
{ text: "Consensus", link: "/nodes/consensus-node" },
{
text: "Blobstream for validators",
collapsed: true,
items: [
{
text: "Install the binary",
link: "/nodes/blobstream-binary",
},
{
text: "Blobstream Orchestrator",
link: "/nodes/blobstream-orchestrator",
},
{ text: "Key management", link: "/nodes/blobstream-keys" },
{
text: "Blobstream Relayer",
link: "/nodes/blobstream-relayer",
},
{
text: "Deploy the contract",
link: "/nodes/blobstream-deploy",
},
{
text: "Blobstream Bootstrapper",
link: "/nodes/blobstream-bootstrapper",
},
],
},
{
text: "IBC relayers",
collapsed: true,
Expand Down Expand Up @@ -553,9 +526,12 @@ function sidebarHome() {
},
{
text: "Integrate with Blobstream",
link: "/developers/blobstream",
collapsed: true,
items: [
{
text: "Overview of Blobstream",
link: "/developers/blobstream",
},
{
text: "Integrate with Blobstream contracts",
link: "/developers/blobstream-contracts",
Expand All @@ -568,6 +544,20 @@ function sidebarHome() {
text: "Querying the Blobstream proofs",
link: "/developers/blobstream-proof-queries",
},
{
text: "Local Blobstream X operators",
collapsed: true,
items: [
{
text: "Requesting data commitment ranges",
link: "/developers/requesting-data-commitment-ranges",
},
{
text: "Non-canonical Blobstream X deployments",
link: "/developers/blobstream-x-deploy",
},
],
},
],
},
{
Expand Down
54 changes: 29 additions & 25 deletions developers/blobstream-contracts.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,15 @@ Make sure to have the following installed:

- [Foundry](https://github.com/foundry-rs/foundry)

### Installing Blobstream contracts
### Installing Blobstream X contracts

Install the Blobstream contracts repo as a dependency:
We will be using the Blobstream X implementation of
Blobstream, so we can install its repo as a dependency:

Install the Blobstream X contracts repo as a dependency:

```sh
forge install celestiaorg/blobstream-contracts --no-commit
forge install TBD --no-commit
```

Note that the minimum Solidity compiler version for using the Blobstream
Expand All @@ -27,38 +30,39 @@ contracts is `0.8.19`.
### Example usage

Example minimal Solidity contract for a stub ZK rollup that leverages the
Blobstream contract to check that data has been posted to Celestia:
`BlobstreamX.sol` contract to check that data has been posted to Celestia:

```solidity
// SPDX-License-Identifier: Apache-2.0
pragma solidity ^0.8.19;
TBD
import "blobstream-contracts/IDAOracle.sol";
import "blobstream-contracts/DataRootTuple.sol";
import "blobstream-contracts/lib/tree/binary/BinaryMerkleProof.sol";
contract MyRollup {
IDAOracle immutable blobstream;
IDAOracle immutable blobstreamX;
bytes32[] public rollup_block_hashes;
constructor(IDAOracle _blobstream) {
blobstream = _blobstream;
constructor(IDAOracle _blobstreamX) {
blobstreamX = _blobstreamX;
}
function submitRollupBlock(
bytes32 _rollup_block_hash,
bytes calldata _zk_proof,
uint256 _blobstream_nonce,
uint256 _blobstreamX_nonce,
DataRootTuple calldata _tuple,
BinaryMerkleProof calldata _proof
) public {
// Verify that the data root tuple (analog. block header) has been
// attested to by the Blobstream contract.
require(
blobstream.verifyAttestation(_blobstream_nonce, _tuple, _proof)
blobstreamX.verifyAttestation(_blobstreamX_nonce, _tuple, _proof)
);
// Verify the ZKP.
// Verify the ZKP (zero-knowledge proof).
// _tuple.dataRoot is a public input, leaves (shares) are private inputs.
require(verifyZKP(_rollup_block_hash, _zk_proof, _tuple.dataRoot));
Expand Down Expand Up @@ -93,18 +97,18 @@ verifying a Merkle inclusion proof.

The [`IDAOracle`](https://github.com/celestiaorg/blobstream-contracts/blob/master/src/IDAOracle.sol)
(**D**ata **A**vailability **O**racle Interface) interface allows L2 contracts
on Ethereum to query the Blobstream contract for relayed `DataRootTuple`s. The
single interface method `verifyAttestation` verifies a Merkle inclusion proof
that a `DataRootTuple` is included under a specific batch (indexed by batch
nonce). In other words, analogously it verifies that a specific block header is
included in the canonical Celestia chain.
on Ethereum to query the `BlobstreamX.sol` contract for relayed `DataRootTuple`s.
The single interface method `verifyAttestation` verifies a Merkle inclusion
proof that a `DataRootTuple` is included under a specific batch (indexed by
batch nonce). In other words, analogously it verifies that a specific block
header is included in the canonical Celestia chain.

## Querying the proof

To prove that the data was published to Celestia, check out the
[proof queries documentation](./blobstream-proof-queries.md)
[proof queries documentation](./blobstreamx-proof-queries.md)
to understand how to query the proofs from Celestia consensus
nodes and make them usable in the Blobstream verifier contract.
nodes and make them usable in the Blobstream X verifier contract.

## Verifying data inclusion for fraud proofs

Expand All @@ -119,27 +123,27 @@ against a `DataRootTuple`. The library is stateless, and allows to pass an

In the `DAVerifier` library, we find functions that help
with data inclusion verification and calculating the square size of a
Celestia block. These functions work with the Blobstream smart contract,
Celestia block. These functions work with the Blobstream X smart contract,
using different proofs to check and confirm the data's availability. Let's
take a closer look at these functions:

- [`verifySharesToDataRootTupleRoot`](https://github.com/celestiaorg/blobstream-contracts/blob/3a552d8f7bfbed1f3175933260e6e440915d2da4/src/lib/verifier/DAVerifier.sol#L80-L124):
This function verifies that the
shares, which were posted to Celestia, were committed to by the Blobstream
shares, which were posted to Celestia, were committed to by the Blobstream X
smart contract. It checks that the data root was committed to by the
Blobstream smart contract and that the shares were committed to by the
Blobstream X smart contract and that the shares were committed to by the
rows roots.
- [`verifyRowRootToDataRootTupleRoot`](https://github.com/celestiaorg/blobstream-contracts/blob/3a552d8f7bfbed1f3175933260e6e440915d2da4/src/lib/verifier/DAVerifier.sol#L133-L155):
This function verifies that a
row/column root, from a Celestia block, was committed to by the
Blobstream smart contract. It checks that the data root was committed
to by the Blobstream smart contract and that the row root commits to
Blobstream X smart contract. It checks that the data root was committed
to by the Blobstream X smart contract and that the row root commits to
the data root.
- [`verifyMultiRowRootsToDataRootTupleRoot`](https://github.com/celestiaorg/blobstream-contracts/blob/3a552d8f7bfbed1f3175933260e6e440915d2da4/src/lib/verifier/DAVerifier.sol#L164-L194):
This function verifies
that a set of rows/columns, from a Celestia block, were committed
to by the Blobstream smart contract. It checks that the data root was
committed to by the Blobstream smart contract and that the rows roots
to by the Blobstream X smart contract. It checks that the data root was
committed to by the Blobstream X smart contract and that the rows roots
commit to the data root.
- [`computeSquareSizeFromRowProof`](https://github.com/celestiaorg/blobstream-contracts/blob/3a552d8f7bfbed1f3175933260e6e440915d2da4/src/lib/verifier/DAVerifier.sol#L204-L215):
This function computes the Celestia
Expand All @@ -155,4 +159,4 @@ take a closer look at these functions:
`verifySharesToDataRootTupleRoot()` method.

For an overview of a demo rollup implementation, head to
[the next section](./blobstream-offchain.md).
[the next section](./blobstreamx-offchain.md).
11 changes: 7 additions & 4 deletions developers/blobstream-offchain.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,14 @@ description: Learn how to integrate your L2's offchain logic with Blobstream

## Blobstream demo rollup

Rollups can use the Blobstream for DA by posting their data to Celestia and then
Rollups can use Blobstream for DA by posting their data to Celestia and then
proving that it was posted on Ethereum. This is done identically to how any
rollup or user would post data to Celestia, and then the validators sign over
additional commitments that are relayed to Ethereum via a light client relay
(aka Blobstream!). This demo will outline (note outline is not an
rollup or user would post data to Celestia. Then, a zero-knowledge proof that
Celestia validators have come to consensus on Celestia block headers is
generated, and subsequently relayed to Ethereum to the Blobstream X smart
contract.

This demo rollup will outline (the outline is not an
implementation! please do not expect to copy and paste this code 🙂) a very
simple Blobstream rollup to illustrate at a high level what this could look
like.
Expand Down
Loading

0 comments on commit e251e39

Please sign in to comment.