From 0f547a0ca9da8e79ae4cd5a5dcd0f7f2b505bdd2 Mon Sep 17 00:00:00 2001 From: Gabriel Barros Date: Fri, 12 Dec 2025 15:04:47 -0300 Subject: [PATCH 1/4] feat: add audits page and update metadata - Introduced a new page for security audits conducted on Celestia software, detailing various audits and their respective reports. - Updated metadata in _meta.js files to include new entries for audits and IBC relayer setup. - Removed optional services metadata as it is no longer needed. --- app/learn/_meta.js | 1 + .../audits/page.mdx | 0 app/operate/_meta.js | 1 - app/operate/data-availability/_meta.js | 1 + .../ibc-relayer/page.mdx | 0 app/operate/networks/local-devnet/page.mdx | 186 +++++++++-------- app/operate/optional-services/_meta.js | 7 - .../instantiate-testnet/page.mdx | 189 ------------------ 8 files changed, 110 insertions(+), 275 deletions(-) rename app/{operate/optional-services => learn}/audits/page.mdx (100%) rename app/operate/{optional-services => data-availability}/ibc-relayer/page.mdx (100%) delete mode 100644 app/operate/optional-services/_meta.js delete mode 100644 app/operate/optional-services/instantiate-testnet/page.mdx diff --git a/app/learn/_meta.js b/app/learn/_meta.js index 7c080e32bbc..2e40e194f9f 100644 --- a/app/learn/_meta.js +++ b/app/learn/_meta.js @@ -3,6 +3,7 @@ const meta = { features: "Features", TIA: "TIA", "code-of-conduct": "Code of Conduct", + audits: "Audits", }; export default meta; diff --git a/app/operate/optional-services/audits/page.mdx b/app/learn/audits/page.mdx similarity index 100% rename from app/operate/optional-services/audits/page.mdx rename to app/learn/audits/page.mdx diff --git a/app/operate/_meta.js b/app/operate/_meta.js index 6949a24a8d0..1e8ec430979 100644 --- a/app/operate/_meta.js +++ b/app/operate/_meta.js @@ -5,7 +5,6 @@ const meta = { "consensus-validators": "Consensus & validators", maintenance: "Maintenance", "keys-wallets": "Keys & wallets", - "optional-services": "Optional operator services", }; export default meta; diff --git a/app/operate/data-availability/_meta.js b/app/operate/data-availability/_meta.js index 59bef02a838..d5303d27f30 100644 --- a/app/operate/data-availability/_meta.js +++ b/app/operate/data-availability/_meta.js @@ -4,6 +4,7 @@ const meta = { "bridge-node": "Run a bridge node", "config-reference": "Configuration reference", "custom-networks": "Custom networks & values", + "ibc-relayer": "IBC relayer setup", metrics: "Metrics & dashboards", "storage-optimization": "Storage optimization (ZFS)", }; diff --git a/app/operate/optional-services/ibc-relayer/page.mdx b/app/operate/data-availability/ibc-relayer/page.mdx similarity index 100% rename from app/operate/optional-services/ibc-relayer/page.mdx rename to app/operate/data-availability/ibc-relayer/page.mdx diff --git a/app/operate/networks/local-devnet/page.mdx b/app/operate/networks/local-devnet/page.mdx index 46f913043a2..5e90a35702c 100644 --- a/app/operate/networks/local-devnet/page.mdx +++ b/app/operate/networks/local-devnet/page.mdx @@ -2,7 +2,7 @@ description: Learn how to set up a local devnet with Celestia consensus and bridge nodes. --- -import { Steps } from 'nextra/components' +import { Steps, Tabs } from 'nextra/components' # Local devnet setup @@ -10,64 +10,17 @@ This guide covers how to set up a local devnet with both consensus and bridge nodes for development and testing purposes. A local devnet allows you to run a complete Celestia network environment on your local machine. -## Prerequisites +## Choose your setup method -- [Install celestia-app](/operate/consensus-validators/install-celestia-app) -- [Install celestia-node](/operate/data-availability/install-celestia-node) -- [Install Docker and Docker Compose](https://docs.docker.com/get-docker) - (for Docker setup) - -## Script-based setup - -### Single consensus node - -To start a local consensus node using the provided script: - -1. Clone and build celestia-app: - - ```bash - git clone https://github.com/celestiaorg/celestia-app.git - cd celestia-app - make install - ``` - -2. Run the single node script: - - ```bash - ./scripts/single-node.sh - ``` - - This script will: - - - Initialize a new chain with a single validator - - Create a genesis file with pre-funded accounts - - Start the consensus node - - Make RPC endpoints available at `localhost:26657` - -### Single consensus node + bridge node - -To set up both a consensus node and a bridge node together: - -1. Follow the consensus node setup above - -2. In a new terminal, run the bridge node script: - - ```bash - ./scripts/single-bridge-node.sh - ``` - - This will: +Pick the approach you want to follow: - - Start a bridge node that connects to your local consensus node - - Enable data availability sampling - - Make the bridge node API available at `localhost:26658` + + + -## Docker setup +### Install Docker -For a containerized setup using Docker Compose, you can use a simplified -configuration based on the Celestia ZKEVM IBC demo repository. - - +Install [Docker and Docker Compose](https://docs.docker.com/get-docker). ### Create a Docker Compose file @@ -135,58 +88,135 @@ Create a `docker-compose.yml` file with the following content: docker-compose logs celestia-validator docker-compose logs celestia-bridge ``` - +### Test your setup -## Default endpoints +1. Check consensus node status: -Once your local devnet is running, you can access these endpoints: + ```bash + curl http://localhost:26657/status + ``` -| Service | Endpoint | -| --------------- | ------------------------ | -| Consensus RPC | `http://localhost:26657` | -| Consensus gRPC | `http://localhost:9090` | -| Consensus P2P | `http://localhost:26656` | -| Bridge node API | `http://localhost:26658` | +2. Query the latest block: -## Testing your setup + ```bash + curl http://localhost:26657/block + ``` + +3. Check the bridge node head: -You can test that your local devnet is working by: + ```bash + curl http://localhost:26658/head + ``` + +### Stop the devnet + +Stop and remove containers: + +```bash +docker-compose down +``` -1. Checking node status: +### Reset / start fresh + +Stop and remove containers **and wipe chain data** (volumes): + +```bash +docker-compose down -v +``` + + + + + + + +### Install dependencies + +- [Install celestia-app](/operate/consensus-validators/install-celestia-app) +- [Install celestia-node](/operate/data-availability/install-celestia-node) + +### Start a single consensus node + +1. Clone and build celestia-app: + + ```bash + git clone https://github.com/celestiaorg/celestia-app.git + cd celestia-app + make install + ``` + +2. Run the single node script: + + ```bash + ./scripts/single-node.sh + ``` + +### Start a bridge node + +In a new terminal, run the bridge node script: + +```bash +./scripts/single-bridge-node.sh +``` + +### Test your setup + +1. Check consensus node status: ```bash curl http://localhost:26657/status ``` -2. Querying the latest block: +2. Query the latest block: ```bash curl http://localhost:26657/block ``` -3. For bridge nodes, check the DA network info: +3. Check the bridge node head: ```bash curl http://localhost:26658/head ``` -## Stopping the devnet - -### Stopping script-based setup +### Stop the devnet Stop the processes with `Ctrl+C` in each terminal. -### Stopping Docker setup +### Reset / start fresh + +Stop the node(s) with `Ctrl+C`, then reset the local chain state (be careful if you’re +running a real validator): ```bash -docker-compose down +celestia-appd tendermint unsafe-reset-all --home $HOME/.celestia-app ``` -To also remove the volumes: +For more reset options and safety notes (especially if you are running a validator), see +[Reset network](/operate/consensus-validators/consensus-node#optional-reset-network). -```bash -docker-compose down -v -``` + + + + +## Default endpoints + +Once your local devnet is running, you can access these endpoints: + +| Service | Endpoint | +| --------------- | ------------------------ | +| Consensus RPC | `http://localhost:26657` | +| Consensus gRPC | `http://localhost:9090` | +| Consensus P2P | `http://localhost:26656` | +| Bridge node API | `http://localhost:26658` | + +## Multi-validator private networks (not local-only) + +This page focuses on a single-machine devnet. If you instead want to create a private +testnet across multiple machines/participants (genesis + gentx flow), start from: + +- [Signing genesis for a new network](/operate/consensus-validators/cli-reference#signing-genesis-for-a-new-network) +- [Optional: Set persistent peers](/operate/consensus-validators/consensus-node#optional-set-persistent-peers) ## Next steps diff --git a/app/operate/optional-services/_meta.js b/app/operate/optional-services/_meta.js deleted file mode 100644 index 8f9a7f58fa8..00000000000 --- a/app/operate/optional-services/_meta.js +++ /dev/null @@ -1,7 +0,0 @@ -const meta = { - "ibc-relayer": "IBC relayer setup", - "instantiate-testnet": "Create a Celestia testnet", - audits: "Audit references", -}; - -export default meta; diff --git a/app/operate/optional-services/instantiate-testnet/page.mdx b/app/operate/optional-services/instantiate-testnet/page.mdx deleted file mode 100644 index 20232152223..00000000000 --- a/app/operate/optional-services/instantiate-testnet/page.mdx +++ /dev/null @@ -1,189 +0,0 @@ ---- -description: A guide that helps you instantiate a new testnetwork with Celestia App. ---- - -import { Callout, Steps } from 'nextra/components' - -# Celestia App network instantiation guide - -Use this guide to spin up your own Celestia test network for experiments or feature testing. - -## Hardware requirements - -Follow the validator hardware requirements. - -## Setup dependencies - -Install prerequisites via the environment setup guide. - -## celestia-app installation - -Install celestia-app via the install guide. - -## Spin up a Celestia testnet - -If you want to spin up a quick testnet with your friends, you can follow these steps. -Unless otherwise noted, every step must be done by everyone who wants to -participate in this testnet. - - - -### (Optional) Reset working directory - -If you have already initialized a working directory for `celestia-appd` in the past, -you must clean up before reinitializing a new directory. You can do so by running -the following command: - -```sh -celestia-appd tendermint unsafe-reset-all --home $HOME/.celestia-app -``` - -### Initialize a working directory - -Run the following command: - -```sh -VALIDATOR_NAME=validator1 -CHAIN_ID=testnet -celestia-appd init $VALIDATOR_NAME --chain-id $CHAIN_ID -``` - -- The value we will use for `$VALIDATOR_NAME` is `validator1` but you should choose - your own node name. -- The value we will use for `$CHAIN_ID` is `testnet`. The `$CHAIN_ID` must - remain the same for everyone participating in this network. - -### Create a new key - -Next, run the following command: - -```sh -KEY_NAME=validator -celestia-appd keys add $KEY_NAME --keyring-backend test -``` - -This will create a new key, with a name of your choosing. -Save the output of this command somewhere; you'll need -the address generated here later. Here, we set the value of our -key `$KEY_NAME` to `validator` for demonstration. - -### Add genesis account KeyName - -Run the following command: - -```sh -TIA_AMOUNT="10000000utia" -celestia-appd genesis add-genesis-account $KEY_NAME $TIA_AMOUNT --keyring-backend test -``` - -Here `$KEY_NAME` is the same key name as before. - -### Optional: Adding other validators - -If other participants in your testnet also want to be validators, -repeat the command above with the specific amount for their public keys. - -Once all the validators are added, the `genesis.json` file is created. You need -to share it with all other validators in your testnet in order for everyone to -proceed with the following step. - -You can find the `genesis.json` at `$HOME/.celestia-app/config/genesis.json` - -### Create the genesis transaction for new chain - -Run the following command: - -```sh -STAKING_AMOUNT=9000000utia -celestia-appd gentx $KEY_NAME $STAKING_AMOUNT --chain-id $CHAIN_ID \ - --keyring-backend test -``` - -This will create the genesis transaction for your new chain. -Here `$STAKING_AMOUNT` should be at least `9000000utia`. If you -provide too much or too little, you will encounter an error -when starting your node. - -You will find the generated gentx JSON file inside `$HOME/.celestia-app/config/gentx/gentx-$KEY_NAME.json` - -> **Note:** If you have other validators in your network, they need to also -> run the above command with the `genesis.json` file you shared with -> them in the previous step. - -### Creating the genesis JSON file - -Once all participants have submitted their gentx JSON files to you, -you will pull all those gentx files inside the following directory: -`$HOME/.celestia-appd/config/gentx` and use them to create the final -`genesis.json` file. - -Once you added the gentx files of all the participants, run the following command: - -```sh -celestia-appd collect-gentxs -``` - -This command will look for the gentx files in this repo which should -be moved to the following directory `$HOME/.celestia-app/config/gentx`. - -It will update the `genesis.json` file after in this location -`$HOME/.celestia-app/config/genesis.json` which now includes the gentx -of other participants. - -You should then share this final `genesis.json` file with all the -other participants who must add it to their `$HOME/.celestia-app/config` directory. - -Everyone must ensure that they replace their existing `genesis.json` file with -this new one created. - -### Modify your config file - -Open the following file `$HOME/.celestia-app/config/config.toml` to modify it. - -Inside the file, add the other participants by modifying the following line to -include other participants as persistent peers: - -```text -# Comma separated list of nodes to keep persistent connections to -persistent_peers = "[validator_address]@[ip_address]:[port],[validator_address]@[ip_address]:[port]" -``` - -### Add your node as a persistent peer - -The following allows you to share your node as a persistent peer -that you can share with others so other participants can peer with you. - -Run the following command: - -```sh -IP_ADDRESS=$(curl ifconfig.me) -NODE_ID=$(celestia-appd tendermint show-node-id) -PORT_NUMBER=26656 -``` - -Note that the default port is `26656`. - -Now you can run the following command to output your validator node address: - -```sh -PEER="$NODE_ID@$IP_ADDRESS:$PORT_NUMBER" -echo $PEER -``` - -The output is your validator node address which you can share with other validators -so they can peer with you. - -### Instantiate the network - -You can start your node by running the following command: - -```sh -celestia-appd start -``` - - -Refer to the ports section of the troubleshooting page for information on which ports are required to be open on your machine. - - -Now you have a new Celestia testnet to play around with! - From bd5f90a1506bd80fab40ead2513cf80518b6e386 Mon Sep 17 00:00:00 2001 From: Gabriel Barros Date: Fri, 12 Dec 2025 15:37:46 -0300 Subject: [PATCH 2/4] refactor: update DynamicRPCTOC and NodeAPIContent for Celestia Node API - Changed the hidden heading in DynamicRPCTOC from "## Loading" to "## Celestia Node API" to improve clarity. - Updated the placeholder item selector in TOC_CONFIG to reflect the new heading. - Modified the link in NodeAPIContent to point to the GitHub releases page instead of the previous documentation URL. - Adjusted comments in DynamicRPCTOC to reference the new placeholder item. --- app/build/rpc/components/DynamicRPCTOC.tsx | 10 +++++----- app/build/rpc/components/NodeAPIContent.tsx | 2 +- app/build/rpc/node-api/page.mdx | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/app/build/rpc/components/DynamicRPCTOC.tsx b/app/build/rpc/components/DynamicRPCTOC.tsx index fe19a0f9496..18a70308d3d 100644 --- a/app/build/rpc/components/DynamicRPCTOC.tsx +++ b/app/build/rpc/components/DynamicRPCTOC.tsx @@ -10,7 +10,7 @@ * @breaking-change-risk MEDIUM - Relies on Nextra's CSS class structure and selectors * * === HOW IT WORKS === - * 1. MDX has a hidden "## Loading" heading → Nextra renders a TOC with one item + * 1. MDX has a hidden "## Celestia Node API" heading → Nextra renders a TOC with one item * 2. This component finds that TOC list, caches its styling, and replaces items with dynamic content * 3. MutationObserver watches for content changes (e.g., version switches) and updates the TOC * 4. IntersectionObserver provides scroll-spy functionality for active highlighting @@ -36,7 +36,7 @@ * * 2. **Selector Changes** (see TOC_CONFIG below): * - .nextra-toc ul (the TOC list container) - * - .nextra-toc a[href="#loading"] (placeholder item) + * - .nextra-toc a[href="#celestia-node-api"] (placeholder item) * - main h2[id] (content headings) * * 3. **New Nextra TOC API**: @@ -67,10 +67,10 @@ interface Heading { // Configuration - centralized to reduce brittleness const TOC_CONFIG = { - placeholderHeadingId: 'loading', + placeholderHeadingId: 'celestia-node-api', selectors: { tocList: '.nextra-toc ul', - placeholderItem: '.nextra-toc a[href="#loading"]', + placeholderItem: '.nextra-toc a[href="#celestia-node-api"]', contentHeadings: 'main h2[id]', scrollButton: '.nextra-toc button[type="button"]', mainContent: 'main', @@ -110,7 +110,7 @@ const toggleScrollButton = (button: HTMLButtonElement, show: boolean) => { export function DynamicRPCTOC() { useEffect(() => { - // Cache the classes from Nextra's rendered "Loading" item + // Cache the classes from Nextra's rendered "celestia-node-api" item // We need to grab these ONCE before we remove it let cachedLinkClasses = '' let cachedLiClasses = '' diff --git a/app/build/rpc/components/NodeAPIContent.tsx b/app/build/rpc/components/NodeAPIContent.tsx index 3cf0ccef5ef..e6a1c11ca2a 100644 --- a/app/build/rpc/components/NodeAPIContent.tsx +++ b/app/build/rpc/components/NodeAPIContent.tsx @@ -280,7 +280,7 @@ export default function RPCDocumentation() {
The Celestia Node API is the collection of RPC methods that can be used to interact with the services provided by Celestia Data Availability Nodes. Node API uses auth tokens to control access to this API.{' '} -Loading... +## Celestia Node API The Celestia Node API is the collection of RPC methods that can be used to interact with the services provided by Celestia Data Availability Nodes. Node API uses auth tokens to control access to this API. From dd85584dbdf6ceb8b84ff7a1a50693966a5a3299 Mon Sep 17 00:00:00 2001 From: Gabriel Barros Date: Fri, 12 Dec 2025 15:42:10 -0300 Subject: [PATCH 3/4] refactor: simplify link processing in check-links script - Removed unused parameters from the processFile function to streamline its usage. - Updated the handling of redirects to improve clarity and maintainability. - Enhanced error handling in the checkExternalLink function by omitting the error variable. --- scripts/check-links.mjs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/scripts/check-links.mjs b/scripts/check-links.mjs index a0816e07a0d..87a501b938d 100644 --- a/scripts/check-links.mjs +++ b/scripts/check-links.mjs @@ -162,7 +162,7 @@ function checkInternalLink(href, routes, redirects) { } // Check case-insensitive redirects - for (const [source, dest] of redirects.entries()) { + for (const [source] of redirects.entries()) { if (source.toLowerCase() === normalizedLower || source.toLowerCase() === withSlashLower || source.toLowerCase() === withoutSlashLower) { return { valid: true, redirected: true, note: `Case mismatch in redirect` }; } @@ -293,7 +293,7 @@ function extractLinksFromAST(tree) { /** * Process a single MDX file and extract links */ -async function processFile(filePath, routes, redirects) { +async function processFile(filePath) { const content = fs.readFileSync(filePath, 'utf8'); // Parse with remark and replace variables @@ -451,7 +451,7 @@ async function checkExternalLink(url, skipPatterns = [], timeout = DEFAULT_TIMEO method: 'GET', waitTime: waitTimeGet || waitTime }; - } catch (e) { + } catch { // Ignore GET error and return original HEAD error } } @@ -612,7 +612,7 @@ async function main() { // Process all files console.log('Processing files and extracting links...'); const fileResults = await Promise.all([ - ...mdxFiles.map(file => processFile(path.join(rootDir, file), routes, redirects)), + ...mdxFiles.map(file => processFile(path.join(rootDir, file))), ...metaFiles.map(file => processMetaFile(path.join(rootDir, file))) ]); From 5210586f17420ff6251a7291184c7ce618fc474a Mon Sep 17 00:00:00 2001 From: jcstein Date: Fri, 12 Dec 2025 11:49:47 -0700 Subject: [PATCH 4/4] docs: add other audit, rm v4v5 --- app/learn/audits/page.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/app/learn/audits/page.mdx b/app/learn/audits/page.mdx index aa3335cb021..62c3091e33b 100644 --- a/app/learn/audits/page.mdx +++ b/app/learn/audits/page.mdx @@ -19,6 +19,4 @@ This page provides a comprehensive list of audits conducted on various Celestia | Blobstream X | Veridise | [Link](https://docs.celestia.org/audits/Blobstream_X-Veridise_Audit.pdf) | | Blobstream X | Zellic | [Link](https://docs.celestia.org/audits/Blobstream_X-Zellic_Audit.pdf) | | Shwap | OtterSec | [Link](https://docs.celestia.org/audits/celestia_shwap_audit_final.pdf) | -| v4 celestia-app | TBD | TBD | -| v5 celestia-app | TBD | TBD | -| ZK Sync | TBD | TBD | +| High throughput recovery | Informal Systems | [Link](https://github.com/celestiaorg/celestia-app/blob/main/docs/audit/informal-systems-recovery.pdf) |