docs: combine Blobstream and Blobstream X docs#1379
Conversation
|
WalkthroughThe recent updates focus on transitioning to Blobstream X for enhanced data availability and integration within the ecosystem. This involves a significant restructuring of documentation and development guides, including the removal of outdated sections, the introduction of new deployment instructions, and refined processes for utilizing Blobstream with Celestia and Ethereum. These changes aim to streamline developer interactions and improve the infrastructure for high-throughput rollups. Changes
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (invoked as PR comments)
Additionally, you can add CodeRabbit Configration File (
|
jcstein
changed the title
rach-id
left a comment
rach-id
left a comment
There was a problem hiding this comment.
lefts some nits, thanks for your help 🙏
jcstein
changed the title
Co-authored-by: CHAMI Rachid <chamirachid1@gmail.com>
Co-authored-by: CHAMI Rachid <chamirachid1@gmail.com>
haha. just bumping this for vis again |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review Status
Actionable comments generated: 11
Configuration used: CodeRabbit UI
Files ignored due to path filters (2)
public/img/blobstream/Celestia_Blobstream_X1b.pngis excluded by:!**/*.pngpublic/img/blobstream/Celestia_Blobstream_X2b.pngis excluded by:!**/*.png
Files selected for processing (8)
- .vitepress/config.ts (3 hunks)
- developers/blobstream-contracts.md (5 hunks)
- developers/blobstream-offchain.md (1 hunks)
- developers/blobstream-proof-queries.md (10 hunks)
- developers/blobstream-x-deploy.md (1 hunks)
- developers/blobstream.md (5 hunks)
- developers/requesting-data-commitment-ranges.md (1 hunks)
- nodes/consensus-node.md (2 hunks)
Files not summarized due to errors (1)
- developers/blobstream-proof-queries.md: Error: Message exceeds token limit
Files skipped from review due to trivial changes (1)
- nodes/consensus-node.md
Additional comments: 21
developers/blobstream-x-deploy.md (2)
- 9-9: The link provided for deploying a new
SuccinctGatewaycontract is correct and leads to the relevant section in the Succinct documentation. This ensures users have a direct resource for the deployment process.- 13-13: The guide link for deploying a new Blobstream X contract using the deployed
SuccinctGatewayis correctly pointing to the Blobstream X GitHub repository. However, ensure the link's fragment (#deploy-blobstream-x-contract) correctly anchors to the relevant section in the README. If the section's title changes, this link may need to be updated.developers/requesting-data-commitment-ranges.md (4)
- 3-7: The introduction clearly outlines the default maintenance schedule for canonical Blobstream X deployments on Ethereum and other chains, as well as the option for users to request updates at a different cadence. This provides a good overview for users on how to interact with the system based on their needs.
- 14-18: The instructions for running the Blobstream X operator with hosted proving on the Succinct platform are clear and direct users to an external guide. It's important to ensure that the external guide remains up-to-date and accessible to users.
Verification successful
The external guide for running the Blobstream X operator with hosted proving on the Succinct platform appears to be accessible and contains sections relevant to the topic, as indicated by the presence of the phrase "operator-with-hosted-proving" multiple times in the fetched content. However, the quality and the up-to-dateness of the guide cannot be fully assessed based on this verification alone.
* 36-36: The option for running the Blobstream X operator with local proving is mentioned, with a link to further instructions. This provides an alternative for users who prefer or require local proving capabilities. Ensure the linked guide is comprehensive and up-to-date. * 46-57: The instructions for directly requesting a proof via the Blobstream X contract interface are clear and provide a straightforward method for users to request data commitments on-chain. This section effectively communicates the process and the expected outcome (the `DataCommitmentStored` event).Scripts Executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Verify if the external guide for running the operator script is accessible and contains relevant information. curl -s https://github.com/succinctlabs/blobstreamx?tab=readme-ov-file | grep -o "operator-with-hosted-proving"Length of output: 200
developers/blobstream-contracts.md (2)
- 100-104: The explanation of the
IDAOracleinterface and its methodverifyAttestationis clear and provides a good understanding of how L2 contracts on Ethereum can query theBlobstreamX.solcontract. This section effectively communicates the interface's purpose and usage.- 109-111: The reference to the proof queries documentation is helpful for developers looking to understand how to query proofs from Celestia consensus nodes. Ensure that the linked documentation is comprehensive and up-to-date.
developers/blobstream.md (5)
- 5-5: The introduction to Blobstream and its rebranding from the Quantum Gravity Bridge (QGB) is clear and provides a good historical context. This helps readers understand the evolution of the technology.
- 19-24: The section introducing Blobstream X and its implementation by Succinct is informative and highlights the use of zero-knowledge proofs for verifying Celestia block headers. This section effectively communicates the added security benefits of Blobstream X.
- 57-57: The diagram illustrating Blobstream X's architecture and deployment is a valuable visual aid. Ensure that the diagram is up-to-date and accurately reflects the current architecture and deployment process.
- 93-100: The explanation of how Blobstream X works, including the role of the
SuccinctGatewaysmart contract and the verification of proofs, is detailed and informative. This section provides a clear understanding of the update process for theBlobstreamX.solcontract.- 160-167: > 📝 NOTE
This review was outside the diff hunks and was mapped to the diff hunk with the greatest overlap. Original lines [148-164]
The comparison between Blobstream and data availability committees (DACs) is insightful and highlights the decentralization, security, and scalability benefits of Blobstream. This section helps readers understand the advantages of using Blobstream for data availability.
developers/blobstream-offchain.md (4)
- 16-18: The disclaimer about the demo rollup outline not being an actual implementation is helpful for setting expectations. It's clear and communicates the intent well.
- 6-19: > 📝 NOTE
This review was outside the diff hunks, and no overlapping diff hunk was found. Original lines [54-76]
The explanation of Celestia-specific structures and the Blobstream-specific structure called
Spanis informative. It effectively links to additional resources for readers to dive deeper into the concepts of namespaces and shares. This approach enhances the documentation's utility by guiding readers to more detailed information.
- 6-19: > 📝 NOTE
This review was outside the diff hunks, and no overlapping diff hunk was found. Original lines [118-156]
The documentation on downloading the block and the fraud proof process is comprehensive and provides a clear overview of the operations a rollup full node performs. The explanation of different mechanisms for downloading blocks and the potential for using gossip networks adds depth to the understanding of the system's flexibility.
- 6-19: > 📝 NOTE
This review was outside the diff hunks, and no overlapping diff hunk was found. Original lines [158-172]
The links to further documentation on proving inclusion via Blobstream, submitting block data to Celestia, and posting headers to Ethereum are valuable resources. They effectively round out the documentation by providing readers with direct access to more detailed information on specific operations within the Blobstream integration process.
.vitepress/config.ts (1)
- 544-563: > 📝 NOTE
This review was outside the diff hunks and was mapped to the diff hunk with the greatest overlap. Original lines [531-560]
The addition of "Local Blobstream X operators" and related subsections under "Integrate with Blobstream" in the sidebar configuration aligns well with the PR objectives of updating and consolidating the documentation for Blobstream and Blobstream X. This change effectively organizes the new content, making it accessible and easy to navigate for users. However, ensure that all links provided (
/developers/requesting-data-commitment-ranges,/developers/blobstream-x-deploy) are valid and lead to the correct documentation pages. Additionally, consider maintaining consistency in the use of capitalization across all sidebar items for a polished and professional appearance.developers/blobstream-proof-queries.md (3)
- 31-37: The links to the Celestia specs are pinned to version
v1.1.0. It's important to verify that these links are still current and point to the most relevant version of the documentation. If the Celestia specs have been updated, consider updating these links to point to the latest version to ensure readers have access to the most accurate and up-to-date information.- 94-102: The
go.modreplacements provided are specific versions. Ensure these versions are up-to-date and compatible with the current versions of the dependencies used in the project. Dependency management is crucial for maintaining the security and stability of the software.- 113-123: The documentation references a specific endpoint and provides a link to a GitHub blob with a line range. Ensure that the referenced code and endpoint are still current and accurately described. Code and APIs can evolve, potentially making these references outdated.
| 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. |
There was a problem hiding this comment.
The explanation of how rollups can use Blobstream for data availability (DA) by posting data to Celestia and proving its posting on Ethereum is clear and concise. However, it would be beneficial to include a brief explanation or link to what zero-knowledge proofs are, especially for readers who may not be familiar with the concept.
Consider adding a sentence or two explaining zero-knowledge proofs or providing a link to a resource for readers to learn more about them.
|
|
||
| ## 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. |
There was a problem hiding this comment.
📝 NOTE
This review was outside the diff hunks, and no overlapping diff hunk was found. Original lines [22-52]
The Go code snippet defining the Block, Data, and Header structs is well-structured and provides a clear example of how to define the structure of commitments for a new chain. However, there's a minor typo in the comment for DataShareLen in the Span struct.
- // DataShareLen is length in shares of the rollup block data. This is used
+ // DataShareLen is the length in shares of the rollup block data. This is used📝 NOTE
This review was outside the diff hunks, and no overlapping diff hunk was found. Original lines [78-116]
The Go code snippets for defining the blockchain, rollup sequencer, and their interactions with Celestia and Ethereum are clear and provide a good foundation for understanding the roles of different components in the system. However, there's a typo in the ProduceBlock function where Namespce should be Namespace.
- Namespce: s.Namespace,
+ Namespace: s.Namespace,Additionally, consider adding error handling for the case where i exceeds the length of s.Blocks in the UpdateHeaders function to prevent potential index out of range errors.
+ if i > uint64(len(s.Blocks)) {
+ return fmt.Errorf("index out of range")
+ }| <!-- markdownlint-disable MD010 --> | ||
|
|
There was a problem hiding this comment.
Please ensure that disabling markdownlint for MD010 is necessary for this document. If it's to allow for tabs in code blocks or similar formatting reasons, consider if there's an alternative way to format the content that adheres to markdownlint rules.
| provide two proofs: (1) a namespace Merkle proof of the transaction to | ||
| a row root. This could be done via proving the shares that contain the | ||
| transaction to the row root using a namespace Merkle proof. And, a | ||
| transaction to the row root using a namespace Merkle proof. (2) And, a |
There was a problem hiding this comment.
The explanation of the namespace Merkle proof and binary Merkle proof is clear, but it would benefit from a brief example or illustration to help readers better understand how these proofs are structured and used. Adding examples can significantly enhance comprehension, especially for complex technical concepts.
Would you like me to generate an example or diagram illustrating the namespace Merkle proof and binary Merkle proof process?
| Smart contracts that use the `DAVerifier` library takes the following proof | ||
| format: |
There was a problem hiding this comment.
The documentation switches to discussing smart contract proof formats without a clear transition from the previous sections. Adding a brief introduction or transition paragraph could help readers understand the shift in focus from querying proofs to using them in smart contracts.
| ```solidity | ||
| pragma solidity ^0.8.22; | ||
|
|
||
| import {DAVerifier} from "@blobstream/lib/verifier/DAVerifier.sol"; | ||
| import {IDAOracle} from "@blobstream/IDAOracle.sol"; | ||
|
|
||
| contract SimpleRollup { | ||
| IDAOracle bridge; | ||
| ... | ||
| function submitFraudProof(SharesProof memory _sharesProof, bytes32 _root) public { | ||
| // (1) verify that the data is committed to by BlobstreamX contract | ||
| (bool committedTo, DAVerifier.ErrorCodes err) = DAVerifier.verifySharesToDataRootTupleRoot(bridge, _sharesProof, _root); | ||
| if (!committedTo) { | ||
| revert("the data was not committed to by Blobstream"); | ||
| } | ||
| // (2) verify that the data is part of the rollup block | ||
| // (3) parse the data | ||
| // (4) verify invalid state transition | ||
| // (5) effects | ||
| } | ||
| } |
There was a problem hiding this comment.
The Solidity code snippet for a simple rollup contract using the DAVerifier is a good practical example. However, ensure that the contract address and other parameters used in the example are clearly marked as placeholders or provide guidance on how to obtain or set these values for a real deployment.
| We can be sure that the data was published to Celestia, and then rollups can | ||
| proceed with their normal fraud proving mechanism. | ||
|
|
||
| :::tip NOTE | ||
| The above proof constructions are implemented in Solidity, |
There was a problem hiding this comment.
The conclusion provides a good summary of the proof construction process. However, it might be beneficial to include a final note on the importance of these proofs in the context of Celestia and Blobstream X, emphasizing their role in ensuring data integrity and security in the ecosystem.
| ### 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 |
There was a problem hiding this comment.
The instructions for installing Blobstream X contracts as a dependency are clear but include a placeholder (TBD) for the repository. It's crucial to replace this placeholder with the actual repository URL or package name before finalizing the documentation.
- forge install TBD --no-commit
+ forge install succinctlabs/blobstreamx --no-commitPlease replace TBD with the actual repository URL or package name for the Blobstream X contracts.
Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation.
| ### 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 | |
| ```sh | |
| forge install succinctlabs/blobstreamx --no-commit |
</details>
<!-- suggestion_end -->
<!-- This is an auto-generated comment by CodeRabbit -->
| // SPDX-License-Identifier: Apache-2.0 | ||
| pragma solidity ^0.8.19; | ||
|
|
||
| TBD |
There was a problem hiding this comment.
The example contract provided uses placeholders (TBD) for imports, which should be replaced with actual paths to the Blobstream X contracts. This ensures that developers can directly use the example as a starting point for their integration.
- TBD
+ import "@succinctlabs/blobstreamx/contracts/IDAOracle.sol";
+ import "@succinctlabs/blobstreamx/contracts/DataRootTuple.sol";
+ import "@succinctlabs/blobstreamx/contracts/lib/tree/binary/BinaryMerkleProof.sol";Please replace TBD with the actual import paths for the Blobstream X contracts.
Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation.
| TBD | |
| import "@succinctlabs/blobstreamx/contracts/IDAOracle.sol"; | |
| import "@succinctlabs/blobstreamx/contracts/DataRootTuple.sol"; | |
| import "@succinctlabs/blobstreamx/contracts/lib/tree/binary/BinaryMerkleProof.sol"; |
| You can interact with the Blobstream X contracts today on testnet. The | ||
| Blobstream X Solidity smart contracts are currently deployed on | ||
| the following Ethereum testnets: | ||
|
|
||
| <!-- markdownlint-disable MD013 --> | ||
|
|
||
| | Contract | EVM network | Contract address | Attested data | | ||
| | Contract | EVM network | Contract address | Attested data on Celestia | | ||
| | ------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------- | | ||
| | Blobstream | Sepolia | [`0x3a5cbB6EF4756DA0b3f6DAE7aB6430fD8c46d247`](https://sepolia.etherscan.io/address/0x3a5cbB6EF4756DA0b3f6DAE7aB6430fD8c46d247) | Mocha testnet | | ||
| | Blobstream | Arbitrum Sepolia | [`0x040769edbca5218e616c8eb16e4faea49ced5e33`](https://sepolia.arbiscan.io/address/0x040769edbca5218e616c8eb16e4faea49ced5e33) | Mocha testnet | | ||
| | Blobstream X | Goerli | [`0x67ea962864cdad3f2202118dc6f65ff510f7bb4d`](https://goerli.etherscan.io/address/0x67ea962864cdad3f2202118dc6f65ff510f7bb4d) | Mocha testnet | | ||
| | Blobstream X | Ethereum Mainnet | [`Not yet deployed`](https://etherscan.io/address/0xTODO) | [Mainnet Beta](../nodes/mainnet.md) | | ||
| | Blobstream X | Arbitrum One | [`Not yet deployed`](https://arbiscan.io/address/0xTODO) | [Mainnet Beta](../nodes/mainnet.md) | | ||
| | Blobstream X | Base | [`Not yet deployed`](https://goerli.etherscan.io/address/0xTODO) | [Mainnet Beta](../nodes/mainnet.md) | | ||
| | Blobstream X | Ethereum Sepolia | [`Not yet deployed`](https://sepolia.etherscan.io/address/0x48B257EC1610d04191cC2c528d0c940AdbE1E439) | [Mainnet Beta](../nodes/mainnet.md) | | ||
| | Blobstream X | Arbitrum Sepolia | [`Not yet deployed`](https://sepolia.arbiscan.io/address/0xTODO) | [Mocha testnet](../nodes/mocha-testnet.md) | |
There was a problem hiding this comment.
The section on deployed contracts contains placeholders (Not yet deployed) for contract addresses. It's essential to update these placeholders with actual contract addresses once the deployments are complete to provide developers with accurate information for integration.
- [`Not yet deployed`](https://etherscan.io/address/0xTODO)
+ [`Deployed Address`](https://etherscan.io/address/0xActualContractAddress)Please update the placeholders with the actual contract addresses once the deployments are complete.
Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation.
| You can interact with the Blobstream X contracts today on testnet. The | |
| Blobstream X Solidity smart contracts are currently deployed on | |
| the following Ethereum testnets: | |
| <!-- markdownlint-disable MD013 --> | |
| | Contract | EVM network | Contract address | Attested data | | |
| | Contract | EVM network | Contract address | Attested data on Celestia | | |
| | ------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------- | | |
| | Blobstream | Sepolia | [`0x3a5cbB6EF4756DA0b3f6DAE7aB6430fD8c46d247`](https://sepolia.etherscan.io/address/0x3a5cbB6EF4756DA0b3f6DAE7aB6430fD8c46d247) | Mocha testnet | | |
| | Blobstream | Arbitrum Sepolia | [`0x040769edbca5218e616c8eb16e4faea49ced5e33`](https://sepolia.arbiscan.io/address/0x040769edbca5218e616c8eb16e4faea49ced5e33) | Mocha testnet | | |
| | Blobstream X | Goerli | [`0x67ea962864cdad3f2202118dc6f65ff510f7bb4d`](https://goerli.etherscan.io/address/0x67ea962864cdad3f2202118dc6f65ff510f7bb4d) | Mocha testnet | | |
| | Blobstream X | Ethereum Mainnet | [`Not yet deployed`](https://etherscan.io/address/0xTODO) | [Mainnet Beta](../nodes/mainnet.md) | | |
| | Blobstream X | Arbitrum One | [`Not yet deployed`](https://arbiscan.io/address/0xTODO) | [Mainnet Beta](../nodes/mainnet.md) | | |
| | Blobstream X | Base | [`Not yet deployed`](https://goerli.etherscan.io/address/0xTODO) | [Mainnet Beta](../nodes/mainnet.md) | | |
| | Blobstream X | Ethereum Sepolia | [`Not yet deployed`](https://sepolia.etherscan.io/address/0x48B257EC1610d04191cC2c528d0c940AdbE1E439) | [Mainnet Beta](../nodes/mainnet.md) | | |
| | Blobstream X | Arbitrum Sepolia | [`Not yet deployed`](https://sepolia.arbiscan.io/address/0xTODO) | [Mocha testnet](../nodes/mocha-testnet.md) | | |
| You can interact with the Blobstream X contracts today on testnet. The | |
| Blobstream X Solidity smart contracts are currently deployed on | |
| the following Ethereum testnets: | |
| <!-- markdownlint-disable MD013 --> | |
| | Contract | EVM network | Contract address | Attested data on Celestia | | |
| | ------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------- | | |
| | Blobstream X | Ethereum Mainnet | [`Deployed Address`](https://etherscan.io/address/0xActualContractAddress) | [Mainnet Beta](../nodes/mainnet.md) | | |
| | Blobstream X | Arbitrum One | [`Not yet deployed`](https://arbiscan.io/address/0xTODO) | [Mainnet Beta](../nodes/mainnet.md) | | |
| | Blobstream X | Base | [`Not yet deployed`](https://goerli.etherscan.io/address/0xTODO) | [Mainnet Beta](../nodes/mainnet.md) | | |
| | Blobstream X | Ethereum Sepolia | [`Not yet deployed`](https://sepolia.etherscan.io/address/0x48B257EC1610d04191cC2c528d0c940AdbE1E439) | [Mainnet Beta](../nodes/mainnet.md) | | |
| | Blobstream X | Arbitrum Sepolia | [`Not yet deployed`](https://sepolia.arbiscan.io/address/0xTODO) | [Mocha testnet](../nodes/mocha-testnet.md) | |
4 participants
Overview
Preview of pages modified in this PR:
Other modified pages
Checklist
Summary by CodeRabbit