Luke/private blockspace - #2312
Conversation
Summary of ChangesHello @lukecd, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces documentation for private blockspace, reorganizes the documentation menus, and performs general maintenance such as dependency cleanup and adding a pre-push git hook. The primary goal is to provide users with information on private blockspace and improve the overall structure and quality of the documentation. Highlights
Ignored Files
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.github.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request is a major migration from VitePress to Next.js and Nextra, and introduces new documentation for private blockspace. The changes are extensive and represent a significant improvement in the documentation infrastructure. My review focuses on the new content and configuration. I've identified a few issues, including some broken links, incorrect configuration values, and placeholder content that needs to be addressed. Specifically, the docsRepositoryBase in app/layout.tsx needs to be corrected for edit links to function, and the old README.md content should be preserved. Additionally, many new pages contain placeholder 'Lorem ipsum' text and should be populated with actual content before merging.
| This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). | ||
|
|
||
| # Celestia Documentation Site | ||
| ## Getting Started | ||
|
|
||
| Welcome to the official documentation repository for [Celestia](https://celestia.org/). | ||
|
|
||
| Here you'll find comprehensive guides, tutorials, and reference materials | ||
| to help you make the most out of Celestia. | ||
|
|
||
| ## Building the site | ||
|
|
||
| To get started, clone the repository and run the following: | ||
| First, run the development server: | ||
|
|
||
| ```bash | ||
| yarn && yarn dev | ||
| npm run dev | ||
| # or | ||
| yarn dev | ||
| # or | ||
| pnpm dev | ||
| # or | ||
| bun dev | ||
| ``` | ||
|
|
||
| This documentation site is built with [VitePress](https://vitepress.dev) | ||
|
|
||
| ## Link checking | ||
|
|
||
| To check for broken links in the documentation, run: | ||
|
|
||
| ```bash | ||
| yarn link-check | ||
| ``` | ||
|
|
||
| This uses [lychee](https://github.com/lycheeverse/lychee) to validate all internal and | ||
| external links. | ||
| The link checker is also run automatically in CI on every push and pull request. | ||
|
|
||
| ## Contribution guidelines | ||
|
|
||
| We love contributions from the community! Whether you're fixing typos, | ||
| improving content clarity, or adding new topics, every contribution helps. | ||
|
|
||
| - Fork & clone: Fork this repository and clone it to your local machine. | ||
| - Branch: Always create a new branch for your changes. Naming it relevantly. | ||
| - Commit Changes: Make your changes and commit them with a clear and concise | ||
| commit message. | ||
| - Push & Create PR: Push your changes to your fork and create a pull request | ||
| to the main branch of this repository. | ||
|
|
||
| Please ensure to review the **[full Contribution Guidelines](https://github.com/celestiaorg/.github/blob/main/CONTRIBUTING.md#external-contributions)** before | ||
| making a pull request. | ||
|
|
||
| ## Documentation standards | ||
|
|
||
| This section outlines the standards and guidelines for maintaining | ||
| consistent, high-quality documentation across the Celestia project. | ||
|
|
||
| ### Styling rules | ||
|
|
||
| - **Sentence case**: Use sentence case for headings and titles | ||
| (reference: [issue #161](https://github.com/celestiaorg/docs/issues/161)) | ||
| - **No "click here"**: Avoid using "click here" for link text | ||
| (reference: [issue #1073](https://github.com/celestiaorg/docs/issues/1073)) | ||
| - **International English**: Use international (common) English spelling | ||
| and terminology | ||
| - **Network names**: Use "Arabica devnet", not "Arabica Devnet" | ||
| - **Node types**: Use lowercase for node types (_e.g._, "bridge node", | ||
| not "Bridge Node") | ||
| - **Politeness**: Avoid using "please" in instructional content | ||
| - **Unique headings**: Ensure no duplicate headings within a document | ||
| - **Network references**: Use "Coffee Beta" network (note the specific | ||
| capitalization) | ||
| - **Latin abbreviations**: Use italicized _i.e._ or _e.g._ instead of | ||
| plain i.e. or e.g. | ||
| - **Code references**: Use `celestia-app` in regular text, not as inline | ||
| code when referring to the application name | ||
| - **Tab ordering**: When using tabs, order them as: Coffee Beta, Mocha, | ||
| Arabica | ||
| - **Placeholders**: Use angle brackets with underscores for placeholders: | ||
| `<flag_name>` not `<flag-name>` or `<flag name>` | ||
|
|
||
| ### Documentation update procedures | ||
|
|
||
| When updating documentation: | ||
|
|
||
| 1. **Run automation**: Execute any available automation tools before | ||
| manual updates | ||
| 2. **Chain ID updates**: If there are chain-id breaking changes: | ||
| - Update all chain-id references throughout the documentation | ||
| - Search comprehensively to ensure no references are missed | ||
| - Reference example: [chain-id update PR](https://github.com/celestiaorg/docs/pull/857/files#diff-7c3322aa40bebbde7be394c354f900d6b5606eabbd03ac0d661f7565fcadcb70) | ||
| 3. **Release notes review**: Read through release notes to identify and | ||
| implement any breaking changes that affect documentation | ||
| 4. **Process reference**: See [documentation update process video](https://www.loom.com/share/0d6897939b654b60b766887b37f86790) | ||
|
|
||
| ### Documentation requirements for software | ||
| Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. | ||
|
|
||
| All software documentation must include: | ||
| You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. | ||
|
|
||
| - **Proof of functionality**: Demonstrate that the software works through: | ||
| - Passing CI checks | ||
| - Manual testing evidence | ||
| - Links to block explorer (where applicable) | ||
| - Clear, step-by-step instructions for running the software | ||
| - **Comprehensive setup**: Provide complete setup and usage instructions | ||
| - **Troubleshooting**: Include common issues and their solutions | ||
| - **Version compatibility**: Clearly state which versions are supported | ||
| This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. | ||
|
|
||
| ### Link format guidelines | ||
| ## Learn More | ||
|
|
||
| When adding internal links to documentation, please use the following format: | ||
| `[link text](/base-working-dir/subdir/page.md#section-id)`, i.e. `[link text](/how-to-guides/quick-start.md#get-your-auth-token)` | ||
| To learn more about Next.js, take a look at the following resources: | ||
|
|
||
| This format ensures long-term compatibility and consistent behavior across | ||
| different platforms and documentation builds. | ||
| - [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. | ||
| - [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. | ||
|
|
||
| ## Directory structure | ||
| You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! | ||
|
|
||
| - /learn: A category for learning about Celestia. | ||
| - /how-to guides: A category with guides for running a node, deploying | ||
| rollups, and building on Celestia. | ||
| - /tutorials: A category with tutorials on interacting with celestia-node. | ||
| <!-- * /guides [WIP]: In-depth articles that cover specific topics in detail. --> | ||
| - /community: A category for the Celestia community. | ||
| - /public: Images, diagrams, and other media files used in the documentation. | ||
| ## Deploy on Vercel | ||
|
|
||
| ## Feedback & suggestions | ||
| The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. | ||
|
|
||
| We value feedback from the community. If you have suggestions for improvements | ||
| or find any discrepancies in the documentation, please raise an issue in this | ||
| repository. |
There was a problem hiding this comment.
The updated README.md is a generic Next.js template and is missing the valuable project-specific information from the old README, such as contribution guidelines, documentation standards, and local development instructions for VitePress (which could be adapted for Nextra). It's important to retain this information to guide contributors and maintain documentation quality. Please consider moving the relevant sections from the old README to a CONTRIBUTING.md file or updating this README with the project-specific context.
|
|
||
| - **Submit blobs**: Store data on Celestia's data availability layer | ||
| - **Retrieve blobs**: Get data back from the network | ||
| - **Check balance**: See your account's token balance |
There was a problem hiding this comment.
This link to the 'Go Node RPC Client' points to ./not-found, which is a broken link. Please update it to point to the correct location.
| banner={banner} | ||
| navbar={navbar} | ||
| pageMap={await getPageMap()} | ||
| docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs" |
There was a problem hiding this comment.
The docsRepositoryBase prop is hardcoded to https://github.com/shuding/nextra/tree/main/docs. This should be updated to point to this project's repository (https://github.com/celestiaorg/docs/edit/main/) so that the 'Edit this page' links work correctly.
| docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs" | |
| docsRepositoryBase="https://github.com/celestiaorg/docs/edit/main" |
| ## Parallel tx submission | ||
|
|
||
| 1. parallel transaction submission: https://github.com/celestiaorg/docs/issues/2273 - different accounts. must track height, namespace, commitment | ||
|
|
||
| ## Queued tx submission | ||
|
|
||
| 1. queued transaction submission https://github.com/celestiaorg/celestia-app/blob/98bb2ab0de430f59e2c2664524cacb3f71974562/specs/src/tx_client.md |
There was a problem hiding this comment.
This section appears to contain placeholder notes and links to GitHub issues rather than complete documentation. Please replace these notes with the intended content for parallel and queued transaction submission.
|
|
||
| ## Pruning windows | ||
|
|
||
| if you want data older than the pruning window, you can use the SyncFromHash = "" and SyncFromHeight = "" in config.toml |
There was a problem hiding this comment.
The instruction if you want data older than the pruning window, you can use the SyncFromHash = "" and SyncFromHeight = "" in config.toml is unclear. It's not obvious if this means setting these values to empty strings disables a feature or if it's an example of what not to do. Please clarify the intended action for users who want to access data older than the pruning window.
| When posting a blob, you send both the namespace and the blob data in hexadecimal format. When retrieving, you switch to base64. This is because Twinkle converts and stores blob data in base64 internally once it's published to Celestia. Using base64 on retrieval ensures you're querying the same encoding the chain uses for commitments and proofs. In short: write in hex, read in base64. | ||
| </Callout> |
There was a problem hiding this comment.
The explanation for why different encodings are used for posting and retrieving data is a bit confusing. Stating that Twinkle converts data to base64 internally is an implementation detail that might not be necessary for the user. It could be simplified by just stating what encoding the API expects for each endpoint. For example: 'The POST /v0/blob endpoint expects the namespace and data fields to be hex-encoded. In contrast, the GET /v0/blob endpoint requires the namespace and blobCommitment as base64-encoded query parameters.'
| | `TLS_CERTS_PATH required` | Missing or commented-out cert vars | Generate certs (see above). | | ||
| | `account not found` | Unfunded signer | Use [Mocha faucet](https://faucet.celestia-mocha.com). | | ||
| | `blob: not found` | Wrong commitment | Run `blob.GetAll` to find the real one. | | ||
| | `grpc-status header missing` | Invalid gRPC URL | Must be `https://<host>:9090`, no token. | |
There was a problem hiding this comment.
The troubleshooting guide for grpc-status header missing suggests the URL format https://<host>:9090. This seems to contradict the setup instructions on line 44, which imply a format of <host>:9090 (without the https:// scheme). gRPC endpoints typically do not use the https:// prefix. To avoid confusion, please ensure the troubleshooting advice aligns with the correct format.
|
|
||
| const versions = [ | ||
| 'v0.11.0-rc8', | ||
| 'rc8-0cf4a49', |
There was a problem hiding this comment.
The version rc8-0cf4a49 in the versions array appears to be a commit hash rather than a semantic version tag. This is inconsistent with the other version names in the list. For clarity and consistency, consider using version tags for all entries.
|
|
||
|  | ||
|
|
||
| **TEMPOARY DIAGRAM, WELL HAVE YONI REDO IN CELESTIA STYLE IN THE FUTURE** |
There was a problem hiding this comment.
This appears to be a placeholder note for the diagram. Please replace it with the final diagram or remove the note if the current diagram is final.
| Proxy->>JSON RPC Client: *Failure* -> <Passthrough> | ||
| ``` | ||
|
|
||
| When retrieving a blob, the Proxy acts as a transparent relay between the client and the Celestia network. The proxy forwards the `blob.Get` request to the Celestia network, receives the raw blob data, and then attempts to deserialize and decrypt it using the configured encryption key. If the blob was encrypted through the proxy, decryption succeeds and the proxy returns the original plaintext data. If it was not, the proxy simply passes the response through unchanged. This design ensures compatibility with both encrypted and unencrypted blobs, so existing clients can retrieve data without modification. |
There was a problem hiding this comment.
| When retrieving a blob, the Proxy acts as a transparent relay between the client and the Celestia network. The proxy forwards the `blob.Get` request to the Celestia network, receives the raw blob data, and then attempts to deserialize and decrypt it using the configured encryption key. If the blob was encrypted through the proxy, decryption succeeds and the proxy returns the original plaintext data. If it was not, the proxy simply passes the response through unchanged. This design ensures compatibility with both encrypted and unencrypted blobs, so existing clients can retrieve data without modification. | |
| When retrieving a blob, the proxy acts as a transparent relay between the client and the Celestia network. The proxy forwards the `blob.Get` request to the Celestia network, receives the raw blob data, and then attempts to deserialize and decrypt it using the configured encryption key. If the blob was encrypted through the proxy, decryption succeeds and the proxy returns the original plaintext data. If it was not, the proxy simply passes the response through unchanged. This design ensures compatibility with both encrypted and unencrypted blobs, so existing clients can retrieve data without modification. |
| ``` | ||
| https://celestia-mocha.quiknode.pro/<your-token>/ | ||
| ``` | ||
| 4. Copy the token from your endpoint URL (this is your **write token**). |
| ``` | ||
| 4. Copy the token from your endpoint URL (this is your **write token**). | ||
| 5. Save both the **URL** and **token** — you’ll add them to your `.env` file next. | ||
|
|
There was a problem hiding this comment.
need to resolve extra spaces, breaks build
jcstein
left a comment
jcstein
left a comment
There was a problem hiding this comment.
nits on app/build/private-blockspace/quickstart/page.mdx
…g + visuals #1848 Update index.md: Revise hero section with new text and tagline, and change image source
2 participants
this pr adds an overview and quickstart for private blockspace along with re-organizing the menus some