diff --git a/.gemini/README.md b/.gemini/README.md new file mode 100644 index 00000000000..0c8abd83930 --- /dev/null +++ b/.gemini/README.md @@ -0,0 +1,5 @@ +# Gemini Code Assist + +Gemini Code Assist is disabled for this repository via `config.yaml`. + +See: diff --git a/.gemini/config.yaml b/.gemini/config.yaml new file mode 100644 index 00000000000..db2ecad6584 --- /dev/null +++ b/.gemini/config.yaml @@ -0,0 +1,4 @@ +# Disable Gemini Code Assist for this repository +# For more information, see: https://developers.google.com/gemini-code-assist/docs/customize-gemini-behavior-github +code_review: + disable: true diff --git a/.github/workflows/check-endpoints.yml b/.github/workflows/check-endpoints.yml new file mode 100644 index 00000000000..e9ab6c54dc5 --- /dev/null +++ b/.github/workflows/check-endpoints.yml @@ -0,0 +1,81 @@ +name: Check Community Endpoints + +on: + schedule: + # Run weekly on Monday at 9 AM UTC + - cron: "0 9 * * 1" + workflow_dispatch: + +permissions: + contents: write + pull-requests: write + +jobs: + check-endpoints: + name: Check community endpoints across all networks + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: "20" + + - name: Check endpoints and remove broken ones + run: node scripts/check-endpoints.mjs + + - name: Read summary and check for changes + id: diff + run: | + if [ -f endpoint-check-summary.txt ]; then + { + echo "summary<> "$GITHUB_OUTPUT" + rm endpoint-check-summary.txt + fi + if git diff --quiet; then + echo "has_changes=false" >> "$GITHUB_OUTPUT" + else + echo "has_changes=true" >> "$GITHUB_OUTPUT" + fi + + - name: Build PR body + if: steps.diff.outputs.has_changes == 'true' + id: body + env: + SUMMARY: ${{ steps.diff.outputs.summary }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + run: | + { + echo "text<> "$GITHUB_OUTPUT" + + - name: Create pull request + if: steps.diff.outputs.has_changes == 'true' + uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676 # v7 + with: + token: ${{ secrets.GITHUB_TOKEN }} + branch: automated/remove-broken-endpoints + delete-branch: true + title: "fix: remove unreachable community endpoints" + body: ${{ steps.body.outputs.text }} + labels: endpoint-check + commit-message: "fix: remove unreachable community endpoints" diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 0ffc1c1a1b5..f0eeebd459c 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -21,10 +21,10 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v6 - name: Setup Node - uses: actions/setup-node@v4 + uses: actions/setup-node@v6 with: node-version: 20 cache: yarn diff --git a/.github/workflows/latest-tags.yaml b/.github/workflows/latest-tags.yaml index eab38c28b64..c5bf3b72c79 100644 --- a/.github/workflows/latest-tags.yaml +++ b/.github/workflows/latest-tags.yaml @@ -32,11 +32,11 @@ jobs: OWNER: celestiaorg NETWORK: ${{ matrix.network }} steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v6 - name: Fetch latest tags and commit SHAs id: latest - uses: actions/github-script@v7 + uses: actions/github-script@v9 with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | @@ -165,7 +165,7 @@ jobs: - name: Open PR if: steps.latest.outputs.should_update == 'true' - uses: peter-evans/create-pull-request@v6 + uses: peter-evans/create-pull-request@v8 with: branch: gh-action/latest-tags-${{ matrix.network }} commit-message: "[automated GH action] update latest release tags & commit sha (${{ matrix.network }})" diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml index 31b977bb8cd..2d05ceb19b5 100644 --- a/.github/workflows/lint.yaml +++ b/.github/workflows/lint.yaml @@ -19,10 +19,10 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v4.1.7 + uses: actions/checkout@v6 - name: Setup Node - uses: actions/setup-node@v4.0.3 + uses: actions/setup-node@v6 with: node-version: 20 cache: npm @@ -37,10 +37,10 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v4.1.7 + uses: actions/checkout@v6 - name: Setup Node - uses: actions/setup-node@v4.0.3 + uses: actions/setup-node@v6 with: node-version: 20 cache: npm diff --git a/.github/workflows/preview.yaml b/.github/workflows/preview.yaml index 6bf74e67a93..01222f1c1c9 100644 --- a/.github/workflows/preview.yaml +++ b/.github/workflows/preview.yaml @@ -21,10 +21,10 @@ jobs: pull-requests: write steps: - name: Checkout - uses: actions/checkout@v4.1.7 + uses: actions/checkout@v6 - name: Setup Node - uses: actions/setup-node@v4.0.3 + uses: actions/setup-node@v6 with: node-version: 20 cache: yarn @@ -42,7 +42,7 @@ jobs: run: yarn build - name: Checkout docs-preview repository - uses: actions/checkout@v4.1.7 + uses: actions/checkout@v6 with: repository: celestiaorg/docs-preview token: ${{ secrets.PR_PREVIEW_DEPLOY }} @@ -74,11 +74,12 @@ jobs: echo "No changes to deploy" else git commit -m "Deploy preview for PR #${{ github.event.number }} from ${{ github.sha }}" + git pull --rebase git push fi - name: Post Preview Link - uses: actions/github-script@v7 + uses: actions/github-script@v9 with: script: | const prNumber = context.payload.pull_request.number; @@ -119,7 +120,7 @@ jobs: contents: read steps: - name: Checkout docs-preview repository - uses: actions/checkout@v4.1.7 + uses: actions/checkout@v6 with: repository: celestiaorg/docs-preview token: ${{ secrets.PR_PREVIEW_DEPLOY }} @@ -137,6 +138,7 @@ jobs: git config user.email "github-actions[bot]@users.noreply.github.com" git add . git commit -m "Remove preview for PR #${{ github.event.number }}" + git pull --rebase git push else echo "Preview directory $TARGET_DIR does not exist, skipping cleanup." diff --git a/.gitignore b/.gitignore index 95caa3931a6..c0a76da121f 100644 --- a/.gitignore +++ b/.gitignore @@ -46,3 +46,11 @@ _pagefind/ # agents llms AGENTS.md /public/llms.txt +/public/llms-full.txt +/public/**/*.md +!/public/SKILL.md +/public/**/llms.txt +/public/robots.txt +/public/sitemap.xml +/public/.well-known/ +package-lock.json diff --git a/README.md b/README.md index 2cf0e4fa20c..5fcc86c53a9 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,27 @@ Welcome to the official documentation repository for [Celestia](https://celestia.org/). - Live site: https://docs.celestia.org + +## LLM and agent support + +### Quick reference for AI agents + +``` +Celestia Documentation Access: +- Clean markdown: Add .md to any URL (e.g., https://docs.celestia.org/learn/TIA/overview.md) +- LLMs.txt: https://docs.celestia.org/llms.txt +- Skill file: https://docs.celestia.org/SKILL.md +- CIPs: https://cips.celestia.org +- DeepWikis: https://deepwiki.com/celestiaorg/docs, https://deepwiki.com/celestiaorg/cips, https://deepwiki.com/celestiaorg/celestia-app, https://deepwiki.com/celestiaorg/celestia-node +``` + +### Resources + - LLMs.txt: https://docs.celestia.org/llms.txt +- Skill file: https://docs.celestia.org/SKILL.md (served from `public/SKILL.md`) +- CIPs (Celestia Improvement Proposals): https://cips.celestia.org - Built with: Next.js + Nextra (MDX), exported as a static site. +- **LLM-ready**: Add `.md` to any URL to get clean markdown (e.g., `https://docs.celestia.org/learn/TIA/overview` → `https://docs.celestia.org/learn/TIA/overview.md`) - DeepWikis for @celestiaorg: - https://deepwiki.com/celestiaorg/docs - https://deepwiki.com/celestiaorg/cips @@ -53,14 +72,18 @@ BASE=/docs-preview/new_docs/ NEXT_PUBLIC_BASE_PATH=/docs-preview/new_docs yarn b - `app/**/page.mdx`: documentation pages - `app/**/_meta.js`: sidebar order/titles -- `public/`: static assets +- `public/`: static assets, including the published agent skill at `public/SKILL.md` - `constants/*.json`: shared values referenced in MDX (e.g. `{{mainnetVersions['app-latest-tag']}}`), replaced by `plugins/remark-replace-variables.mjs` ## Useful scripts - `yarn lint`: lint the codebase (also runs on `git push` via hook) - `yarn check-links -- --all`: validate internal + external links (see `scripts/check-links.mjs --help`) -- `yarn generate:llms`: generate `public/llms.txt` (ignored by git) for ingestion tools/LLMs +- `yarn generate:llms`: generate LLM-ready markdown files from MDX sources + - Creates clean `.md` versions of all documentation pages + - Removes JSX components, imports, and MDX-specific syntax + - Automatically runs during build process (`yarn build`) + - Access any doc page as markdown by adding `.md` to the URL ## Contribution guidelines @@ -87,10 +110,10 @@ This section outlines the standards and guidelines for maintaining consistent, h - **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) +- **Network references**: use "Mainnet 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 inline code) when referring to the application name -- **Tab ordering**: when using tabs, order them as: Coffee Beta, Mocha, Arabica +- **Tab ordering**: when using tabs, order them as: Mainnet Beta, Mocha, Arabica - **Placeholders**: use angle brackets with underscores for placeholders: `` not `` or `` ### Documentation update procedures diff --git a/app/_meta.js b/app/_meta.js index 59a5137a170..f5af2711525 100644 --- a/app/_meta.js +++ b/app/_meta.js @@ -12,6 +12,11 @@ const meta = { title: "Operate", type: "page", }, + status: { + title: "Status", + type: "page", + href: "https://status.celestia.org", + }, }; export default meta; diff --git a/app/build/blobstream/integrate-contracts/page.mdx b/app/build/blobstream/integrate-contracts/page.mdx index 89bc16b6914..ead47d8f209 100644 --- a/app/build/blobstream/integrate-contracts/page.mdx +++ b/app/build/blobstream/integrate-contracts/page.mdx @@ -115,9 +115,8 @@ the following chains: | SP1 Blobstream | Ethereum Mainnet | [`0x7Cf3876F681Dbb6EdA8f6FfC45D66B996Df08fAe`](https://etherscan.io/address/0x7Cf3876F681Dbb6EdA8f6FfC45D66B996Df08fAe#events) | [Mainnet Beta](/operate/networks/mainnet-beta) | [Deployment on Celenium](https://celenium.io/blobstream?network=ethereum&page=1) | | SP1 Blobstream | Arbitrum One | [`0xA83ca7775Bc2889825BcDeDfFa5b758cf69e8794`](https://arbiscan.io/address/0xA83ca7775Bc2889825BcDeDfFa5b758cf69e8794#events) | [Mainnet Beta](/operate/networks/mainnet-beta) | [Deployment on Celenium](https://celenium.io/blobstream?network=arbitrum&page=1) | | SP1 Blobstream | Base | [`0xA83ca7775Bc2889825BcDeDfFa5b758cf69e8794`](https://basescan.org/address/0xA83ca7775Bc2889825BcDeDfFa5b758cf69e8794#events) | [Mainnet Beta](/operate/networks/mainnet-beta) | [Deployment on Celenium](https://celenium.io/blobstream?network=base&page=1) | -| SP1 Blobstream | Scroll | [`0x5008fa5CC3397faEa90fcde71C35945db6822218`](https://scrollscan.com/address/0x5008fa5CC3397faEa90fcde71C35945db6822218) | [Mainnet Beta](/operate/networks/mainnet-beta) | N/A | | SP1 Blobstream | Sepolia | [`0xf0c6429ebab2e7dc6e05dafb61128be21f13cb1e`](https://sepolia.etherscan.io/address/0xf0c6429ebab2e7dc6e05dafb61128be21f13cb1e#events) | [Mocha testnet](/operate/networks/mocha-testnet) | [Deployment on Celenium](https://mocha.celenium.io/blobstream?network=ethereum&page=1) | | SP1 Blobstream | Arbitrum Sepolia | [`0xc3e209eb245Fd59c8586777b499d6A665DF3ABD2`](https://sepolia.arbiscan.io/address/0xc3e209eb245Fd59c8586777b499d6A665DF3ABD2#events) | [Mocha testnet](/operate/networks/mocha-testnet) | [Deployment on Celenium](https://mocha.celenium.io/blobstream?network=arbitrum&page=1) | | SP1 Blobstream | Base Sepolia | [`0xc3e209eb245Fd59c8586777b499d6A665DF3ABD2`](https://sepolia.basescan.org/address/0xc3e209eb245Fd59c8586777b499d6A665DF3ABD2#events) | [Mocha testnet](/operate/networks/mocha-testnet) | [Deployment on Celenium](https://mocha.celenium.io/blobstream?network=base&page=1) | | SP1 Blobstream | Holesky | [`0x315A044cb95e4d44bBf6253585FbEbcdB6fb41ef`](https://holesky.etherscan.io/address/0x315A044cb95e4d44bBf6253585FbEbcdB6fb41ef) | [Mocha testnet](/operate/networks/mocha-testnet) | N/A | -| SP1 Blobstream | ZKSync Gateway Staging | [`0x3a038D77A9b4eBBc8A7482B438BCff11c3591792`](https://explorer.era-gateway-stage.zksync.dev/address/0x3a038D77A9b4eBBc8A7482B438BCff11c3591792) | [Mocha testnet](/operate/networks/mocha-testnet) | N/A | \ No newline at end of file +| SP1 Blobstream | ZKSync Gateway Staging | `0x3a038D77A9b4eBBc8A7482B438BCff11c3591792` | [Mocha testnet](/operate/networks/mocha-testnet) | N/A | diff --git a/app/build/blobstream/integrate-offchain/page.mdx b/app/build/blobstream/integrate-offchain/page.mdx index 534ba159570..3d63d286b66 100644 --- a/app/build/blobstream/integrate-offchain/page.mdx +++ b/app/build/blobstream/integrate-offchain/page.mdx @@ -71,7 +71,7 @@ The rollup sequencer is responsible for creating blocks and, in this demo, writi Therefore, we can start by first defining the reading and writing interactions rollup nodes will have with both the Celestia and Ethereum networks. The actual implementations of these interfaces are left as exercises to the reader. Assume that those implementations of these interfaces are verifying the respective chain. For the connection to Celestia, this would likely mean connecting to a Celestia light node, which can detect faults in consensus such as hidden data. For the connection to Ethereum, this would likely mean running and connecting to a full node. -More information on the RPC that is exposed by a Celestia light node can be found [in the RPC documentation](https://node-rpc-docs.celestia.org/?version=v0.28.4). Additionally, if you need more information on how to run a light node, you can [check out the documentation](/operate/data-availability/light-node/quickstart). +More information on the RPC that is exposed by a Celestia light node can be found [in the Node API docs](/build/rpc/node-api/). Additionally, if you need more information on how to run a light node, you can [check out the documentation](/operate/data-availability/light-node/quickstart). ```go // CelestiaLightNodeClient summarizes the actions that a rollup that uses @@ -246,4 +246,4 @@ As linked above, use the [Celestia Node API](/build/rpc/node-api) or [check out ### Posting headers to Ethereum -How headers are posted to Ethereum is entirely dependent upon how the rollup light client contracts work. For examples of interacting with the Ethereum blockchain programmatically, please see the [go-ethereum book](https://goethereumbook.org/en/transactions/) or one of the many other resources for [submitting transactions](https://github.com/ethereumbook/ethereumbook/blob/first_edition_first_print/06transactions.asciidoc) or [writing contracts](https://github.com/ethereumbook/ethereumbook/blob/first_edition_first_print/07smart-contracts-solidity.asciidoc). +How headers are posted to Ethereum is entirely dependent upon how the rollup light client contracts work. For examples of interacting with the Ethereum blockchain programmatically, please see resources for [submitting transactions](https://github.com/ethereumbook/ethereumbook/blob/first_edition_first_print/06transactions.asciidoc) or [writing contracts](https://github.com/ethereumbook/ethereumbook/blob/first_edition_first_print/07smart-contracts-solidity.asciidoc). diff --git a/app/build/post-retrieve-blob/client/go/page.mdx b/app/build/post-retrieve-blob/client/go/page.mdx index 55905baba71..64afca4504b 100644 --- a/app/build/post-retrieve-blob/client/go/page.mdx +++ b/app/build/post-retrieve-blob/client/go/page.mdx @@ -11,7 +11,7 @@ The Celestia Go client lets you submit and retrieve data from the Celestia netwo ## Prerequisites -- Go 1.24 or later +- Go 1.25.1 or later - A Celestia account (created automatically) - Testnet tokens from the [Mocha faucet](/operate/networks/mocha-testnet#mocha-testnet-faucet) @@ -139,7 +139,7 @@ func main() { if balanceStr == "0utia" || balanceStr == "0 utia" { fmt.Println("Account has no funds. Fund this address at the Mocha faucet to submit blobs:") fmt.Printf("Address: %s\n", address.String()) - fmt.Println("Faucet: https://docs.celestia.org/operate/networks/mocha-testnet#mocha-testnet-faucet") + fmt.Println("Faucet: https://mocha.celenium.io/faucet") } else { if err := submitAndRetrieveBlob(ctx, c); err != nil { panic(err) @@ -246,10 +246,23 @@ go mod tidy Choose your connection type: -For QuickNode: `CELE_DA_URL` uses `https://` and no port, while `CELE_CORE_GRPC` uses a port (e.g. `:9090`) and no `https://` prefix. +To submit blobs, you need both a DA JSON-RPC endpoint on port `26658` and a consensus gRPC endpoint on port `9090`. +The public Mocha combination verified for this guide is ITRocket for DA JSON-RPC +and P-OPS for consensus gRPC: +`http://celestia-testnet-consensus.itrocket.net:26658` and +`rpc-mocha.pops.one:9090`. -**QuickNode (recommended for beginners):** +**Public community endpoints (tested on Mocha):** + +```bash +export CELE_DA_URL=http://celestia-testnet-consensus.itrocket.net:26658 +export CELE_DA_TLS=false +export CELE_CORE_GRPC=rpc-mocha.pops.one:9090 +export CELE_CORE_TLS=false +``` + +**Managed provider (for example QuickNode):** ```bash export CELE_DA_URL=https://your-quicknode-url.celestia-mocha.quiknode.pro/ @@ -259,19 +272,19 @@ export CELE_CORE_TLS=true export CELE_CORE_TOKEN= ``` -**Local bridge node:** +**Local bridge node + local consensus node:** ```bash export CELE_DA_URL=http://localhost:26658 export CELE_DA_TLS=false -export CELE_CORE_GRPC=localhost:26657 +export CELE_CORE_GRPC=localhost:9090 export CELE_CORE_TLS=false ``` **Read-only mode (no blob submission):** ```bash -export CELE_DA_URL=http://localhost:26658 +export CELE_DA_URL=http://celestia-testnet-consensus.itrocket.net:26658 export CELE_DA_TLS=false # Don't set CELE_CORE_GRPC for read-only mode ``` @@ -282,7 +295,7 @@ export CELE_DA_TLS=false go run main.go ``` -**First run:** You'll see your account address. Fund it at the [Mocha faucet](/operate/networks/mocha-testnet#mocha-testnet-faucet). +**First run:** You'll see your account address. Fund it at [https://mocha.celenium.io/faucet](https://mocha.celenium.io/faucet). **Second run:** After funding, you'll see: @@ -310,7 +323,7 @@ Connecting to Celestia... Balance: 0utia Account has no funds. Fund this address at the Mocha faucet to submit blobs: Address: celestia16k0wsej6rewd2pfh0taah35suzf3apj552q8c3 -Faucet: https://docs.celestia.org/operate/networks/mocha-testnet#mocha-testnet-faucet +Faucet: https://mocha.celenium.io/faucet ✓ Tutorial complete! ``` @@ -340,10 +353,10 @@ Balance: 1000000utia ### Connection types -| Purpose | Node type | Example URL | -| ----------- | -------------- | ------------------------ | -| Read data | Bridge node | `http://localhost:26658` | -| Submit data | Consensus node | `localhost:26657` | +| Purpose | Node type | Example URL | +| ----------- | ----------------------- | --------------------------------------------- | +| Read data | DA JSON-RPC | `http://localhost:26658` | +| Submit data | Consensus node gRPC | `localhost:9090` | ### Read-only mode diff --git a/app/build/post-retrieve-blob/client/rust/page.mdx b/app/build/post-retrieve-blob/client/rust/page.mdx index 7e3a6ff982c..8dc135eb771 100644 --- a/app/build/post-retrieve-blob/client/rust/page.mdx +++ b/app/build/post-retrieve-blob/client/rust/page.mdx @@ -1,6 +1,6 @@ # Rust client -The [Lumina Rust client](https://github.com/eigerco/lumina/tree/main/client) provides a high-level API for interacting with a Celestia node over RPC and gRPC. It builds on top of the lower-level `celestia-rpc` and `celestia-grpc` crates and exposes a unified `Client` that supports both **read-only** and **submit** modes. +The [Lumina Rust client](https://github.com/celestiaorg/lumina/tree/main/client) provides a high-level API for interacting with a Celestia node over RPC and gRPC. It builds on top of the lower-level `celestia-rpc` and `celestia-grpc` crates and exposes a unified `Client` that supports both **read-only** and **submit** modes. In read-only mode, the client connects to a node via RPC (and optionally gRPC) to query headers, blobs, and state. diff --git a/app/build/rpc/_meta.js b/app/build/rpc/_meta.js index f7094366e6c..a6d9e491bd4 100644 --- a/app/build/rpc/_meta.js +++ b/app/build/rpc/_meta.js @@ -1,5 +1,9 @@ const meta = { "node-api": "Node API", + "app-api": { + title: "Celestia-app", + href: "https://celestiaorg.github.io/celestia-app/swagger/", + }, "clients": "Clients", }; diff --git a/app/build/rpc/clients/page.mdx b/app/build/rpc/clients/page.mdx index 54b33bce5cd..3d5e29cadb3 100644 --- a/app/build/rpc/clients/page.mdx +++ b/app/build/rpc/clients/page.mdx @@ -9,14 +9,14 @@ Official Go implementation of the Celestia Node RPC client and Transaction Clien - **Repository**: [celestiaorg/celestia-node @ /api/client](https://github.com/celestiaorg/celestia-node/tree/main/api/client) - **Tutorial**: [Go Client Tutorial](/build/post-retrieve-blob/client/go/) - Learn how to submit and retrieve blobs without running your own node -## Community Clients - ### Rust Client - Community-maintained Rust implementation of the Celestia Node RPC client -- **Repository**: [eigerco/celestia-node-rs](https://github.com/eigerco/celestia-node-rs) +Official Rust implementation of the Celestia Node RPC client (Lumina) +- **Repository**: [celestiaorg/lumina](https://github.com/celestiaorg/lumina) - **Tutorial**: [Rust Client Tutorial](/build/post-retrieve-blob/client/rust/) - Submit and retrieve blobs using the Lumina Rust client +## Community Clients + ### Python Client Community-maintained Python client for the Celestia Node RPC API diff --git a/app/build/rpc/components/NodeAPIContent.tsx b/app/build/rpc/components/NodeAPIContent.tsx index 0b545e2d6dd..73516e5500a 100644 --- a/app/build/rpc/components/NodeAPIContent.tsx +++ b/app/build/rpc/components/NodeAPIContent.tsx @@ -135,32 +135,19 @@ export default function RPCDocumentation() { } }, []); - // Initialize version from URL on mount and fetch data useEffect(() => { - const urlParams = new URLSearchParams(window.location.search); - const versionParam = urlParams.get('version'); - const targetVersion = (versionParam && versions.includes(versionParam)) - ? versionParam - : versions[0]; - + // Read URL params on mount (client-only, avoids SSR hydration mismatch). + const versionParam = new URLSearchParams(window.location.search).get('version'); + const targetVersion = versionParam && versions.includes(versionParam) ? versionParam : versions[0]; + if (targetVersion !== selectedVersion) { + // eslint-disable-next-line react-hooks/set-state-in-effect setSelectedVersion(targetVersion); } - - fetchJsonData(targetVersion, true); // Mark as initial load + fetchJsonData(targetVersion, true); // eslint-disable-next-line react-hooks/exhaustive-deps }, []); - // Handle version changes after mount - useEffect(() => { - // Skip if this is the initial render - if (isInitialLoading) return; - - if (selectedVersion !== versions[0] || window.location.search) { - fetchJsonData(selectedVersion, false); // Mark as version switch - } - }, [selectedVersion, fetchJsonData, isInitialLoading]); - // Scroll to hash with MutationObserver (replaces hardcoded setTimeout) useEffect(() => { if (!spec) return; @@ -208,6 +195,7 @@ export default function RPCDocumentation() { const newVersion = event.target.value; setSelectedVersion(newVersion); window.history.pushState({}, '', `?version=${newVersion}`); + fetchJsonData(newVersion, false); }; const activateSidebar = (param: Param) => { diff --git a/app/build/stacks/op-alt-da/aws-kms-guide/page.mdx b/app/build/stacks/op-alt-da/aws-kms-guide/page.mdx index 2e5e93d7aef..fc4513f3bef 100644 --- a/app/build/stacks/op-alt-da/aws-kms-guide/page.mdx +++ b/app/build/stacks/op-alt-da/aws-kms-guide/page.mdx @@ -9,7 +9,6 @@ This guide walks through running [op-alt-da](https://github.com/celestiaorg/op-a - Docker - Go 1.21+ - A Celestia RPC endpoint from [Quicknode](https://quicknode.com/) -- [cel-key utility installed](/operate/keys-wallets/celestia-node-key/#installation) import { Steps } from "nextra/components"; @@ -25,45 +24,13 @@ import { Steps } from "nextra/components"; brew install awscli ``` -2. Clone and build op-alt-da ([v0.11.0](https://github.com/celestiaorg/op-alt-da/releases/tag/v0.11.0)+): +2. Clone and build op-alt-da ([v0.12.0](https://github.com/celestiaorg/op-alt-da/releases/tag/v0.12.0)+): ```bash git clone https://github.com/celestiaorg/op-alt-da.git && cd op-alt-da make ``` -## Celestia key - -1. Create a key, in this example you will name it `celestia_key`: - - ```bash - ./cel-key add celestia_key \ - --keyring-backend test \ - --keyring-dir ~/.celestia-light-mocha-4/keys \ - --node.type light \ - --p2p.network mocha - ``` - -2. Show address: - - ```bash - ./cel-key show celestia_key \ - --keyring-backend test \ - --keyring-dir ~/.celestia-light-mocha-4/keys - - ``` - -3. Fund the address at the faucet: https://mocha.celenium.io/faucet. -4. Export private key hex: - - ```bash - ./cel-key export celestia_key \ - --keyring-dir ~/.celestia-light-mocha-4/keys \ - --keyring-backend test \ - --unarmored-hex \ - --unsafe - ``` - ## Localstack 1. Set mock AWS credentials (required even for localstack): @@ -91,6 +58,20 @@ import { Steps } from "nextra/components"; # should return: { "Keys": [] } ``` +## Create KMS key + +Create a KMS key and alias: + +```bash +KEY_ID=$(aws --endpoint-url=http://localhost:4566 kms create-key \ + --key-spec ECC_SECG_P256K1 \ + --key-usage SIGN_VERIFY \ + --query 'KeyMetadata.KeyId' --output text) + +aws --endpoint-url=http://localhost:4566 kms create-alias \ + --alias-name alias/op-alt-da/celestia_key --target-key-id $KEY_ID +``` + ## Configure op-alt-da 1. Copy config example into `config.toml`: @@ -103,9 +84,9 @@ import { Steps } from "nextra/components"; ```toml [celestia] - namespace = "00000000000000000000000000000000000000000000000000000000acfe" + namespace = "000000000000000000000000000000000000000000000000000000acfe" keyring_backend = "awskms" - default_key_name = "celestia_key" + default_key_name = "alias/op-alt-da/celestia_key" bridge_addr = "https://your-endpoint.celestia-mocha.quiknode.pro/your-token/" bridge_auth_token = "" @@ -118,13 +99,9 @@ import { Steps } from "nextra/components"; [celestia.awskms] region = "us-east-1" endpoint = "http://localhost:4566" - alias_prefix = "alias/op-alt-da/" - auto_create = true - import_key_name = "celestia_key" - import_key_hex = "YOUR_EXPORTED_PRIVATE_KEY_HEX" ``` -When you run the DA server with `auto_create = true`, it will automatically create a new key in AWS KMS if it doesn't exist. + Note: In v0.12.0+, the `default_key_name` must include the full alias path (e.g., `alias/op-alt-da/celestia_key`). ## Run the DA server @@ -145,15 +122,33 @@ When you run the DA server with `auto_create = true`, it will automatically crea INFO [01-20|14:53:57.004] Started DA Server ``` -2. Test a POST request: +2. Test a POST request to get your Celestia address: + + ```bash + curl -s -X POST http://127.0.0.1:3100/put \ + -H "Content-Type: application/octet-stream" \ + -d "hello celestia" -o /dev/null + ``` + + The first request will fail because the account has no funds. Check the server logs for the error message which reveals your Celestia address: + + ``` + submission failed: account for signer celestia1rwuklcs36jm6wqxk8w9cx9vyja93856nz3sdlf not found + ``` + +3. Fund your address at the faucet: https://mocha.celenium.io/faucet + + Copy the `celestia1...` address from the error message and request testnet tokens. + +4. Retry the POST request: ```bash - curl -X POST http://127.0.0.1:3100/put \ + curl -s -X POST http://127.0.0.1:3100/put \ -H "Content-Type: application/octet-stream" \ - -d "hello celestia" + -d "hello celestia" -o /dev/null ``` - Where the successful POST shows: + A successful POST shows in the server logs: ```bash INFO [01-20|14:54:15.342] celestia: blob successfully submitted id=74a5940000000000677e645183667f4d9efe506226fd0dd0b70a4144c8fd05c0aa68407ccf886507 @@ -162,20 +157,21 @@ When you run the DA server with `auto_create = true`, it will automatically crea Check your transaction on [Celenium](https://mocha.celenium.io) by navigating to `https://mocha.celenium.io/address/YOUR_CELESTIA_ADDRESS`. -3. List your keys again, to see the key you just created: +5. Verify your key and alias: ```bash - AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1 aws --endpoint-url=http://localhost:4566 kms list-keys + AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1 aws --endpoint-url=http://localhost:4566 kms list-aliases ``` - This time, you will see your new key: + You should see your alias pointing to the key: ```bash { - "Keys": [ + "Aliases": [ { - "KeyId": "79b26b15-0635-4b3c-aad0-0ab4406e6754", - "KeyArn": "arn:aws:kms:us-east-1:000000000000:key/79b26b15-0635-4b3c-aad0-0ab4406e6754" + "AliasName": "alias/op-alt-da/celestia_key", + "AliasArn": "arn:aws:kms:us-east-1:000000000000:alias/op-alt-da/celestia_key", + "TargetKeyId": "79b26b15-0635-4b3c-aad0-0ab4406e6754" } ] } @@ -187,14 +183,40 @@ Congratulations, you're set up! You should be able to see your blob has been pos ## Production (AWS) -For production AWS-KMS usage, remove the endpoint, set your region, and private key: +For production AWS KMS usage: -```toml -[celestia.awskms] -region = "us-east-2" -endpoint = "" -alias_prefix = "alias/op-alt-da/" -auto_create = false -import_key_name = "celestia_key" -import_key_hex = "YOUR_EXPORTED_PRIVATE_KEY_HEX" -``` +1. Create a KMS keypair in AWS with key spec `ECC_SECG_P256K1` and key usage `SIGN_VERIFY`. + +2. Create an alias for your key (e.g., `alias/op-alt-da/my_celes_key`). Per AWS requirements, the alias name must start with `alias/`. + +3. Configure your IAM policy with the minimum required permissions: + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "kms:GetPublicKey", + "kms:Sign" + ], + "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/KEY_ID" + } + ] + } + ``` + +4. Update your `config.toml`: + + ```toml + [celestia] + keyring_backend = "awskms" + default_key_name = "alias/op-alt-da/my_celes_key" + + [celestia.awskms] + region = "us-east-2" + endpoint = "" + ``` + + Note: Leave `endpoint` empty for production AWS. The `default_key_name` must include the full alias path (e.g., `alias/my_celes_key` or `alias/op-alt-da/my_celes_key`). diff --git a/app/layout.tsx b/app/layout.tsx index 8d4b124174e..e5da0a3c200 100644 --- a/app/layout.tsx +++ b/app/layout.tsx @@ -6,6 +6,10 @@ import "nextra-theme-docs/style.css"; import "katex/dist/katex.min.css"; import { FontStyles } from "@/components/FontStyles"; +const SITE_ORIGIN = "https://docs.celestia.org"; +const SITE_DESCRIPTION = + "Learn, build, and operate on Celestia - the modular data availability network."; + // Use BASE env var (same as next.config.mjs) and ensure it's available client-side const basePath = process.env.NEXT_PUBLIC_BASE_PATH || @@ -23,10 +27,142 @@ const THEME_CONFIG = { primarySaturation: 100, }; export const metadata = { - // Define your metadata here - // For more information on metadata API, see: https://nextjs.org/docs/app/building-your-application/optimizing/metadata + metadataBase: new URL(SITE_ORIGIN), + title: { + default: "Celestia Documentation", + template: "%s - Celestia Documentation", + }, + description: SITE_DESCRIPTION, + openGraph: { + type: "website", + siteName: "Celestia Documentation", + title: "Celestia Documentation", + description: SITE_DESCRIPTION, + images: [ + { + url: "/Celestia-og.png", + width: 1200, + height: 630, + alt: "Celestia Documentation", + }, + ], + }, + twitter: { + card: "summary_large_image", + site: "@CelestiaOrg", + title: "Celestia Documentation", + description: SITE_DESCRIPTION, + images: ["/Celestia-og.png"], + }, + robots: { + index: true, + follow: true, + googleBot: { + index: true, + follow: true, + }, + }, +}; + +const organizationJsonLd = { + "@context": "https://schema.org", + "@type": "Organization", + name: "Celestia", + url: "https://celestia.org", + logo: `${SITE_ORIGIN}/logo-light.svg`, + sameAs: [ + "https://github.com/celestiaorg", + "https://x.com/CelestiaOrg", + "https://discord.com/invite/YsnTPcSfWQ", + ], +}; + +const websiteJsonLd = { + "@context": "https://schema.org", + "@type": "WebSite", + name: "Celestia Documentation", + url: SITE_ORIGIN, + description: SITE_DESCRIPTION, +}; + +const documentationJsonLd = { + "@context": "https://schema.org", + "@type": "TechArticle", + headline: "Celestia Documentation", + description: SITE_DESCRIPTION, + url: SITE_ORIGIN, + publisher: { + "@type": "Organization", + name: "Celestia", + url: "https://celestia.org", + }, + about: [ + "Celestia", + "data availability", + "modular blockchain", + "blobspace", + "node operation", + ], +}; + +const softwareApplicationJsonLd = { + "@context": "https://schema.org", + "@type": "SoftwareApplication", + name: "Celestia Node API", + applicationCategory: "DeveloperApplication", + operatingSystem: ["Linux", "macOS"], + url: `${SITE_ORIGIN}/build/rpc/node-api/`, + softwareHelp: `${SITE_ORIGIN}/operate/maintenance/troubleshooting/`, + isAccessibleForFree: true, + publisher: { + "@type": "Organization", + name: "Celestia", + url: "https://celestia.org", + }, }; +const faqJsonLd = { + "@context": "https://schema.org", + "@type": "FAQPage", + mainEntity: [ + { + "@type": "Question", + name: "Where can I troubleshoot Celestia node issues?", + acceptedAnswer: { + "@type": "Answer", + text: "Use the Celestia troubleshooting documentation for common node, sync, network, and operational issues.", + url: `${SITE_ORIGIN}/operate/maintenance/troubleshooting/`, + }, + }, + { + "@type": "Question", + name: "Where can I find the Celestia Node API reference?", + acceptedAnswer: { + "@type": "Answer", + text: "Use the Celestia Node API reference for RPC methods and the OpenRPC specification for machine-readable API details.", + url: `${SITE_ORIGIN}/build/rpc/node-api/`, + }, + }, + { + "@type": "Question", + name: "Where can I learn how to run a Celestia light node?", + acceptedAnswer: { + "@type": "Answer", + text: "Start with the light node quickstart guide, then use the troubleshooting page if setup, sync, or connectivity issues appear.", + url: `${SITE_ORIGIN}/operate/data-availability/light-node/quickstart/`, + }, + }, + ], +}; + +const jsonLd = [ + organizationJsonLd, + websiteJsonLd, + documentationJsonLd, + softwareApplicationJsonLd, + faqJsonLd, +]; + const banner = ( Welcome to our new docs! 🎉 ); @@ -83,11 +219,29 @@ export default async function RootLayout({ href={withBasePath("/favicons/favicon-16x16.png")} /> - - + + + + {jsonLd.map((data, index) => ( +