# Celestia documentation full context

> Full cleaned markdown export of the Celestia documentation for LLM and agent ingestion.

---
Title: Blobstream proof queries (legacy)
URL: https://docs.celestia.org/build/blobstream/proof-queries.md
Source: app/build/blobstream/proof-queries/page.mdx
---

# Blobstream proof queries (legacy)

> **Legacy reference:** As of September 2026, the Succinct-operated SP1 Blobstream deployments are no longer maintained and do not receive new commitments, and Celenium no longer offers its Blobstream explorer. This page preserves the proof-query and contract-format reference. It does not imply that a maintained deployment is available.

## Prerequisites

- Access to a Celestia consensus full node RPC endpoint (or full node). The node doesn't need to be a validating node in order for the proofs to be queried. A full node is enough.

## Querying the proofs

To prove PFBs, blobs or shares, we can use the Celestia consensus node's RPC to query proofs for them:

### Heavy RPC request limit

Proof queries such as `data_root_inclusion_proof` and `prove_shares` are
memory-intensive. They share the consensus node's process-wide heavy RPC
request limit with other heavy endpoints and transports.

When the limit is reached, clients receive a temporary capacity response:

- HTTP GET requests return `503 Service Unavailable`.
- JSON-RPC and WebSocket requests return a JSON-RPC error with
  `server busy: too many concurrent heavy RPC requests, retry later` in the
  error's `data` field. Use this message to distinguish temporary overload from
  other JSON-RPC errors.
- gRPC requests return `ResourceExhausted`.

These responses indicate that the node is busy, not that proof generation
failed. Retry with exponential backoff and jitter. Where appropriate, bound the
maximum delay or number of retries.

### 1. Data root inclusion proof

To prove the data root is committed to by the Blobstream smart contract, we will need to provide a Merkle proof of the data root tuple to a data root tuple root. This can be created using the [`data_root_inclusion_proof`](https://github.com/celestiaorg/celestia-core/blob/c3ab251659f6fe0f36d10e0dbd14c29a78a85352/rpc/client/http/http.go#L492-L511) query.

This [endpoint](https://github.com/celestiaorg/celestia-core/blob/793ece9bbd732aec3e09018e37dc31f4bfe122d9/rpc/openapi/openapi.yaml#L1045-L1093) allows querying a data root to data root tuple root proof. It takes a block `height`, a starting block, and an end block, then it generates the binary Merkle proof of the `DataRootTuple`, corresponding to that `height`, to the `DataRootTupleRoot` which is committed to in the Blobstream contract.

Example request: `/data_root_inclusion_proof?height=15&start=10&end=20`

Which queries the proof of the height `15` to the data commitment defined by the range `[10, 20)`.

Example response:

```json
{
  "jsonrpc": "2.0",
  "id": -1,
  "result": {
    "proof": {
      "total": "10",
      "index": "5",
      "leaf_hash": "vkRaRg7FGtZ/ZhsJRh/Uhhb3U6dPaYJ1pJNEfrwq5HE=",
      "aunts": [
        "nmBWWwHpipHwagaI7MAqM/yhCDb4cz7z4lRxmVRq5f8=",
        "nyzLbFJjnSKOfRZur8xvJiJLA+wBPtwm0KbYglILxLg=",
        "GI/tJ9WSwcyHM0r0i8t+p3hPFtDieuYR9wSPVkL1r2s=",
        "+SGf6MfzMmtDKz5MLlH+y7mPV9Moo2x5rLjLe3gbFQo="
      ]
    }
  }
}
```

> **Note:** The values are base64 encoded. For these to be usable with the solidity smart contract, they need to be converted to `bytes32`. Check the next section for more information.

### 2. Transaction inclusion proof

To prove that a rollup transaction is part of the data root, we will need to provide two proofs: (1) a namespace Merkle proof of the transaction to (2) 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 binary Merkle proof of the row root to the data root.

These proofs can be generated using the [`ProveShares`](https://github.com/celestiaorg/celestia-core/blob/c3ab251659f6fe0f36d10e0dbd14c29a78a85352/rpc/client/http/http.go#L526-L543) query.

This [endpoint](https://github.com/celestiaorg/celestia-core/blob/793ece9bbd732aec3e09018e37dc31f4bfe122d9/rpc/core/tx.go#L175-L213) allows querying a shares proof to row roots, then a row roots to data root proofs. It takes a block `height`, a starting share index and an end share index which define a share range. Then, two proofs are generated:

- An NMT proof of the shares to the row roots
- A binary Merkle proof of the row root to the data root

> **Note:** If the share range spans multiple rows, then the proof can contain multiple NMT and binary proofs.

Example request: `/prove_shares?height=15&startShare=0&endShare=1`

Which queries the proof of shares `[0,1)` in block `15`.

Example response:

```json
{
  "jsonrpc": "2.0",
  "id": -1,
  "result": {
    "data": [
      "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQBAAABXAAAACbaAgrOAgqgAQqdAQogL2NlbGVzdGlhLmJsb2IudjEuTXNnUGF5Rm9yQmxvYnMSeQovY2VsZXN0aWExdWc1ZWt0MmNjN250dzRkdG1zZDlsN3N0cTBzN3Z5ZTd5bTJyZHISHQAAAAAAAAAAAAAAAAAAAAAAAAASExIyQkMkMoiZGgKXAiIgrfloW1M/Y33zlD2luveDELZzr9cF92+2eTaImIWhN9pCAQASZwpQCkYKHy9jb3Ntb3MuY3J5cHRvLnNlY3AyNTZrMS5QdWJLZXkSIwohA36hewmW/AXtrw6S+QsNUzFGfeg37Da6igoP2ZQcK+04EgQKAggBGAISEwoNCgR1dGlhEgUyMTAwMBDQ6AwaQClYLQPNrFoD6H8mgmwxjFeNhwhRu39EcrVKMFkNQ8+HHuodhdOQIG/8DXEmrBwrpwj6hi+3uEsZ+0p5vrf3v8sSAQEaBElORFgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
    ],
    "share_proofs": [
      {
        "end": 1,
        "nodes": [
          "AAAAAAAAAAAAAAAAAAAAAAAAABITEjJCQyQyiJkAAAAAAAAAAAAAAAAAAAAAAAAAEhMSMkJDJDKImbiwnpOdwIZBFr0UiFhPKwGy/XIIjL+gqm0fqxIw0z0o",
          "/////////////////////////////////////////////////////////////////////////////3+fuhlzUfKJnZD8yg/JOtZla2V3g2Q7y+18iH5j0Uxk"
        ]
      }
    ],
    "namespace_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABA==",
    "row_proof": {
      "row_roots": [
        "000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000121312324243243288993946154604701154F739F3D1B5475786DDD960F06D8708D4E870DA6501C51750"
      ],
      "proofs": [
        {
          "total": "8",
          "index": "0",
          "leaf_hash": "300xzO8TiLwPNuREY6OJcRKzTHQ4y6yy6qH0wAuMMrc=",
          "aunts": [
            "ugp0sV9YNEI5pOiYR7RdOdswwlfBh2o3XiRsmMNmbKs=",
            "3dMFZFaWZMTZVXhphF5TxlCJ+CT3EvmMFOpiXFH+ID4=",
            "srl59GiTSiwC9LqdYASzFC6TvusyY7njX8/XThp6Xws="
          ]
        }
      ],
      "start_row": 0,
      "end_row": 0
    },
    "namespace_version": 0
  }
}
```

> **Note:** The values are base64 encoded. For these to be usable with the solidity smart contract, they need to be converted to `bytes32`. Check the next section for more information.

## Converting the proofs to be usable in the DAVerifier contract

The `DAVerifier` smart contract takes the following proof format:

```solidity
/// @notice Contains the necessary parameters to prove that some shares, which were posted to
/// the Celestia network, were committed to by the Blobstream smart contract.
struct SharesProof {
    // The shares that were committed to.
    bytes[] data;
    // The shares proof to the row roots. If the shares span multiple rows, we will have multiple nmt proofs.
    NamespaceMerkleMultiproof[] shareProofs;
    // The namespace of the shares.
    Namespace namespace;
    // The rows where the shares belong. If the shares span multiple rows, we will have multiple rows.
    NamespaceNode[] rowRoots;
    // The proofs of the rowRoots to the data root.
    BinaryMerkleProof[] rowProofs;
    // The proof of the data root tuple to the data root tuple root that was posted to the Blobstream contract.
    AttestationProof attestationProof;
}

/// @notice Contains the necessary parameters needed to verify that a data root tuple
/// was committed to, by the Blobstream smart contract, at some specific nonce.
struct AttestationProof {
    // the attestation nonce that commits to the data root tuple.
    uint256 tupleRootNonce;
    // the data root tuple that was committed to.
    DataRootTuple tuple;
    // the binary Merkle proof of the tuple to the commitment.
    BinaryMerkleProof proof;
}
```

To construct the `SharesProof`, we will need the proof that we queried above, and it goes as follows:

### data

This is the raw shares that were submitted to Celestia in the `bytes` format. If we take the example blob that was submitted in the [`RollupInclusionProofs.t.sol`](https://github.com/celestiaorg/blobstream-contracts/blob/3a552d8f7bfbed1f3175933260e6e440915d2da4/src/lib/verifier/test/RollupInclusionProofs.t.sol#L64-L65), we can convert it to bytes using the `abi.encode(...)` as done for [this variable](https://github.com/celestiaorg/blobstream-contracts/blob/3a552d8f7bfbed1f3175933260e6e440915d2da4/src/lib/verifier/test/RollupInclusionProofs.t.sol#L384-L402). This can be gotten from the above result of the [transaction inclusion proof](#2-transaction-inclusion-proof) query in the field `data`, which is in `base64` encoded then be converted to hex to be used as described.

### shareProofs

This is the shares proof to the row roots. These can contain multiple proofs if the shares containing the blob span across multiple rows. To construct them, we will use the result of the [transaction inclusion proof](#2-transaction-inclusion-proof) section:

```json
"share_proofs": [
  {
    "start": ...,
    "end": ...,
    "nodes": [
      "...",
      "..."
    ]
  }
],
```

> **Note:** If any of the fields is empty, then it will not be in the response. For example, if the `start` field is `0`, it will be omitted in the response.

While the `NamespaceMerkleMultiproof` being:

```solidity
/// @notice Namespace Merkle Tree Multiproof structure. Proves multiple leaves.
struct NamespaceMerkleMultiproof {
    // The beginning key of the leaves to verify.
    uint256 beginKey;
    // The ending key of the leaves to verify.
    uint256 endKey;
    // List of side nodes to verify and calculate tree.
    NamespaceNode[] sideNodes;
}
```

So, we can construct the `NamespaceMerkleMultiproof` with the following mapping:

- `beginKey` in the Solidity struct **==** `start` in the query response
- `endKey` in the Solidity struct **==** `end` in the query response
- `sideNodes` in the Solidity struct **==** `nodes` in the query response

The `NamespaceNode`, which is the type of the `sideNodes`, is defined as follows:

```solidity
/// @notice Namespace Merkle Tree node.
struct NamespaceNode {
    // Minimum namespace.
    Namespace min;
    // Maximum namespace.
    Namespace max;
    // Node value.
    bytes32 digest;
}
```

So, we construct a `NamespaceNode` via taking the values from the `nodes` field in the query response, we convert them from base64 to `hex`, then we use the following mapping:

- `min` == the first 29 bytes in the decoded value
- `max` == the second 29 bytes in the decoded value
- `digest` == the remaining 32 bytes in the decoded value

The `min` and `max` are `Namespace` type which is:

```solidity
/// @notice A representation of the Celestia-app namespace ID and its version.
/// See: https://celestiaorg.github.io/celestia-app/namespace.html
struct Namespace {
    // The namespace version.
    bytes1 version;
    // The namespace ID.
    bytes28 id;
}
```

So, to construct them, we separate the 29 bytes in the decoded value to:

- first byte: `version`
- remaining 28 bytes: `id`

An example of doing this can be found in the [RollupInclusionProofs.t.sol](https://github.com/celestiaorg/blobstream-contracts/blob/3a552d8f7bfbed1f3175933260e6e440915d2da4/src/lib/verifier/test/RollupInclusionProofs.t.sol#L465-L477) test.

### namespace

Which is the namespace used by the rollup when submitting data to Celestia. As described above, it can be constructed as follows:

```solidity
/// @notice A representation of the Celestia-app namespace ID and its version.
/// See: https://celestiaorg.github.io/celestia-app/namespace.html
struct Namespace {
    // The namespace version.
    bytes1 version;
    // The namespace ID.
    bytes28 id;
}
```

Via taking the `namespace` value from the `prove_shares` query response, decoding it from base64 to hex, then:

- first byte: `version`
- remaining 28 bytes: `id`

An example can be found in the [RollupInclusionProofs.t.sol](https://github.com/celestiaorg/blobstream-contracts/blob/3a552d8f7bfbed1f3175933260e6e440915d2da4/src/lib/verifier/test/RollupInclusionProofs.t.sol#L488) test.

### rowRoots

Which are the roots of the rows where the shares containing the Rollup data are localized. These can be taken from the `prove_shares` query response:

```json
"row_proof":
{
    "row_roots":
    [
        "..."
    ],
},
```

The values inside the `row_roots` are already in hex, and the Solidity type of the `rowRoots` is `NamespaceNode`. So, we will construct them similar to the `sideNodes` of the [shareProofs](#shareproofs). Except that no base64 conversion is needed.

### rowProofs

These are the proofs of the rows to the data root. They are of type `BinaryMerkleProof`:

```solidity
/// @notice Merkle Tree Proof structure.
struct BinaryMerkleProof {
    // List of side nodes to verify and calculate tree.
    bytes32[] sideNodes;
    // The key of the leaf to verify.
    uint256 key;
    // The number of leaves in the tree
    uint256 numLeaves;
}
```

To construct them, we take the response of the `prove_shares` query:

```json
"row_proof": {
      "row_roots": [
        "..."
      ],
      "proofs": [
        {
          "total": "...",
          "index": "...",
          "leaf_hash": "...",
          "aunts": [
            "...",
            "..."
          ]
        }
      ],
```

and do the following mapping:

- `key` in the Solidity struct **==** `index` in the query response
- `numLeaves` in the Solidity struct **==** `total` in the query response
- `sideNodes` in the Solidity struct **==** `aunts` in the query response

The type of the `sideNodes` is a `bytes32`. So, we take the values in the query response, we convert them from base64 to hex, then we create the values.

An example can be found in the [RollupInclusionProofs.t.sol](https://github.com/celestiaorg/blobstream-contracts/blob/3a552d8f7bfbed1f3175933260e6e440915d2da4/src/lib/verifier/test/RollupInclusionProofs.t.sol#L479-L484) test.

### attestationProof

This is the proof of the data root to the data root tuple root, which is committed to in the Blobstream contract:

```solidity
/// @notice Contains the necessary parameters needed to verify that a data root tuple
/// was committed to, by the Blobstream smart contract, at some specific nonce.
struct AttestationProof {
    // the attestation nonce that commits to the data root tuple.
    uint256 tupleRootNonce;
    // the data root tuple that was committed to.
    DataRootTuple tuple;
    // the binary Merkle proof of the tuple to the commitment.
    BinaryMerkleProof proof;
}
```

- `tupleRootNonce`: the nonce at which Blobstream committed to the batch containing the block containing the data.
- `tuple`: the `DataRootTuple` of the block:

```solidity
/// @notice A tuple of data root with metadata. Each data root is associated
///  with a Celestia block height.
/// @dev `availableDataRoot` in
///  https://github.com/celestiaorg/celestia-specs/blob/master/src/specs/data_structures.md#header
struct DataRootTuple {
    // Celestia block height the data root was included in.
    // Genesis block is height = 0.
    // First queryable block is height = 1.
    uint256 height;
    // Data root.
    bytes32 dataRoot;
}
```

which comprises a `dataRoot`, i.e. the block containing the Rollup data data root, and the `height` which is the `height` of that block.

- `proof`: the `BinaryMerkleProof` of the data root tuple to the data root tuple root. Constructing it is similar to constructing the row roots to data root proof in the [rowProofs](#rowproofs) section.

An example can be found in the [RollupInclusionProofs.t.sol](https://github.com/celestiaorg/blobstream-contracts/blob/3a552d8f7bfbed1f3175933260e6e440915d2da4/src/lib/verifier/test/RollupInclusionProofs.t.sol#L488) test.

If the `dataRoot` or the `tupleRootNonce` is unknown during the verification:

- `dataRoot`: can be queried using the `/block?height=15` query (`15` in this example endpoint), and taking the `data_hash` field from the response.
- `tupleRootNonce`: can be retrieved using a `gRPC` query to the app to the [`/qgb/v1/data_commitment/range/height`](https://github.com/celestiaorg/celestia-app/blob/c517bd27c4e0b3d6e4521a7d2946662cb0f19f1d/proto/celestia/qgb/v1/query.proto#L51-L56) endpoint. An example can be found in the [`verify`](https://github.com/celestiaorg/celestia-app/blob/c517bd27c4e0b3d6e4521a7d2946662cb0f19f1d/x/blobstream/client/verify.go#L245-L251) command.

## High-level diagrams

The two diagrams below summarize how a single share is committed to in Blobstream. The share is highlighted in green. `R0`, `R1`, etc represent the respective row and column roots, the blue and pink gradients are erasure encoded data. More details on the square layout can be found [in the data square layout](https://github.com/celestiaorg/celestia-app/blob/v1.1.0/specs/src/specs/data_square_layout.md) and [data structures](https://github.com/celestiaorg/celestia-app/blob/v1.1.0/specs/src/specs/data_structures.md#erasure-coding) portion of the specs.

### The Celestia square

![Square](/img/blobstream/blobstream-square.png)

### The commitment scheme

![Blobstream Commitment Diagram](/img/blobstream/blobstream-commitment-diagram.png)

## Conclusion

After creating all the proofs, and verifying them:

1. Verify inclusion proof of the transaction to Celestia data root
2. Prove that the data root tuple is committed to by the Blobstream smart contract

We can be sure that the data was published to Celestia.

> **Note:** The above proof constructions are implemented in Solidity, and may require different approaches in other programming languages.

---
Title: Go client tutorial
URL: https://docs.celestia.org/build/post-retrieve-blob/client/go.md
Source: app/build/post-retrieve-blob/client/go/page.mdx
---

# Go client tutorial

The Celestia Go client lets you submit and retrieve data from the Celestia network without running your own node. This tutorial shows you how to get started with the basics.

## What you can do

- **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
- **Read-only mode**: Just retrieve data without submitting

## Prerequisites

- Go 1.25.x (Go 1.26 is not yet supported by a transitive dependency,
  `bytedance/sonic`; if your default toolchain is newer, run the tutorial with
  `GOTOOLCHAIN=go1.25.1 go run main.go`)
- A Celestia account (created automatically)
- Testnet tokens from the [Mocha faucet](/operate/networks/mocha-testnet#mocha-testnet-faucet)

## Quick setup

### Create your project

```bash
mkdir celestia-client-example
cd celestia-client-example
go mod init celestia-client-example
```

### Create main.go

```go
package main

import (
	"context"
	"fmt"
	"os"
	"time"

	"github.com/celestiaorg/celestia-node/api/client"
	"github.com/celestiaorg/celestia-node/blob"
	"github.com/celestiaorg/celestia-node/nodebuilder/p2p"
	"github.com/celestiaorg/go-square/v3/share"
	"github.com/cosmos/cosmos-sdk/crypto/keyring"
)

func main() {
	ctx := context.Background()

	// Get connection details from environment
	daURL := os.Getenv("CELE_DA_URL")
	coreGRPC := os.Getenv("CELE_CORE_GRPC")
	daTLS := os.Getenv("CELE_DA_TLS") == "true"
	daToken := os.Getenv("CELE_DA_TOKEN")
	coreTLS := os.Getenv("CELE_CORE_TLS") == "true"
	coreToken := os.Getenv("CELE_CORE_TOKEN")

	if daURL == "" {
		fmt.Println("Error: Set CELE_DA_URL environment variable")
		fmt.Println("Example: export CELE_DA_URL=http://localhost:26658")
		return
	}

	// Create a new account
	fmt.Println("Creating account...")
	kr, err := client.KeyringWithNewKey(client.KeyringConfig{
		KeyName:     "my_key",
		BackendName: keyring.BackendTest,
	}, "./keys")
	if err != nil {
		panic(err)
	}

	// Show your address
	keyInfo, err := kr.Key("my_key")
	if err != nil {
		panic(err)
	}
	address, err := keyInfo.GetAddress()
	if err != nil {
		panic(err)
	}
	fmt.Printf("Your address: %s\n", address.String())

	// Connect to Celestia (read-only or full client)
	cfg := client.Config{
		ReadConfig: client.ReadConfig{
			BridgeDAAddr: daURL,
			EnableDATLS:  daTLS,
		},
		SubmitConfig: client.SubmitConfig{
			DefaultKeyName: "my_key",
		},
	}

	// Add DA auth token if provided
	if daToken != "" {
		cfg.ReadConfig.DAAuthToken = daToken
	}

	// Add Core gRPC config if provided
	if coreGRPC != "" {
		network := p2p.Network("mocha-5")
		cfg.SubmitConfig.Network = network
		cfg.SubmitConfig.CoreGRPCConfig = client.CoreGRPCConfig{
			Addr:       coreGRPC,
			TLSEnabled: coreTLS,
		}
		if coreToken != "" {
			cfg.SubmitConfig.CoreGRPCConfig.AuthToken = coreToken
		}
		fmt.Println("Full client mode (can submit blobs)")
	} else {
		fmt.Println("Read-only mode (cannot submit blobs)")
		fmt.Println("To submit blobs, set CELE_CORE_GRPC environment variable")
	}

	fmt.Println("Connecting to Celestia...")
	c, err := client.New(ctx, cfg, kr)
	if err != nil {
		panic(err)
	}
	defer c.Close()

	// Check your balance
	balance, err := c.State.Balance(ctx)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Balance: %s\n", balance.String())

	// Submit a blob only if in full mode
	if coreGRPC != "" {
		// Check if account has funds before trying to submit
		balanceStr := balance.String()
		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://mocha.celenium.io/faucet")
		} else {
			if err := submitAndRetrieveBlob(ctx, c); err != nil {
				panic(err)
			}
		}
	}

	fmt.Println("✓ Tutorial complete!")
}

func submitAndRetrieveBlob(ctx context.Context, c *client.Client) error {
	// Set timeout for network operations
	ctx, cancel := context.WithTimeout(ctx, time.Minute)
	defer cancel()

	// Create namespace (groups your data)
	ns, err := share.NewV0Namespace([]byte("tutorial"))
	if err != nil {
		return err
	}

	// Create blob with your data
	message := "Hello Celestia!"
	blobData := []byte(message)
	b, err := blob.NewBlob(share.ShareVersionZero, ns, blobData, nil)
	if err != nil {
		return err
	}

	// Submit to network
	fmt.Println("Submitting blob...")
	height, err := c.Blob.Submit(ctx, []*blob.Blob{b}, nil)
	if err != nil {
		return err
	}
	fmt.Printf("✓ Blob submitted at block %d\n", height)

	// Retrieve it back
	fmt.Println("Retrieving blob...")
	retrieved, err := c.Blob.Get(ctx, height, ns, b.Commitment)
	if err != nil {
		return err
	}

	// Verify the data
	retrievedData := string(retrieved.Data())
	fmt.Printf("✓ Retrieved: %s\n", retrievedData)

	if retrievedData != message {
		return fmt.Errorf("data mismatch!")
	}

	fmt.Println("✓ Data verified!")
	return nil
}
```

### Set up your go.mod

Create `go.mod` with these dependencies:

```go
module celestia-client-example

go 1.25.1

require (
	github.com/celestiaorg/celestia-node v0.28.2-mocha
	github.com/celestiaorg/go-square/v3 v3.0.2
	github.com/cosmos/cosmos-sdk v0.50.13
)

replace (
	cosmossdk.io/x/upgrade => github.com/celestiaorg/cosmos-sdk/x/upgrade v0.2.0
	github.com/cometbft/cometbft => github.com/celestiaorg/celestia-core v0.39.10
	github.com/cosmos/cosmos-sdk => github.com/celestiaorg/cosmos-sdk v0.51.4
	github.com/cosmos/ibc-go/v8 => github.com/celestiaorg/ibc-go/v8 v8.7.2
	github.com/gogo/protobuf => github.com/regen-network/protobuf v1.3.3-alpha.regen.1
	// broken goleveldb needs to be replaced for the cosmos-sdk and celestia-app
	github.com/syndtr/goleveldb => github.com/syndtr/goleveldb v1.0.1-0.20210819022825-2ae1ddf74ef7
	// celestia-core(v0.34.x): used for multiplexing abci v1 requests
	github.com/tendermint/tendermint => github.com/celestiaorg/celestia-core v1.55.0-tm-v0.34.35
)

replace github.com/ipfs/boxo => github.com/celestiaorg/boxo v0.29.0-fork-4

replace github.com/ipfs/go-datastore => github.com/celestiaorg/go-datastore v0.0.0-20250801131506-48a63ae531e4
```

Then run:

```bash
go mod tidy
```

## Running the tutorial

### Set environment variables

Choose your connection type:

To submit blobs, you need both a DA JSON-RPC endpoint and a consensus gRPC endpoint.
The public Quicknode Mocha endpoint serves both, and the full submit and
retrieve flow in this guide was verified against it:
`https://public-endpoint.celestia-mocha.quiknode.pro` for DA JSON-RPC and
`public-endpoint.celestia-mocha.quiknode.pro:9090` for consensus gRPC.

**Public endpoints (tested on Mocha):**

```bash
export CELE_DA_URL=https://public-endpoint.celestia-mocha.quiknode.pro
export CELE_DA_TLS=true
export CELE_CORE_GRPC=public-endpoint.celestia-mocha.quiknode.pro:9090
export CELE_CORE_TLS=true
```

**Managed provider (for example Quicknode):**

```bash
export CELE_DA_URL=https://your-quicknode-url.celestia-mocha.quiknode.pro/<your-token>
export CELE_DA_TLS=true
export CELE_CORE_GRPC=your-quicknode-url:9090
export CELE_CORE_TLS=true
export CELE_CORE_TOKEN=<your-token>
```

**Local bridge node + local consensus node:**

```bash
export CELE_DA_URL=http://localhost:26658
export CELE_DA_TLS=false
export CELE_CORE_GRPC=localhost:9090
export CELE_CORE_TLS=false
```

**Read-only mode (no blob submission):**

```bash
export CELE_DA_URL=https://public-endpoint.celestia-mocha.quiknode.pro
export CELE_DA_TLS=true
# Don't set CELE_CORE_GRPC for read-only mode
```

### Run the program

```bash
go run main.go
```

**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:

```
Creating account...
Your address: celestia16k0wsej6rewd2pfh0taah35suzf3apj552q8c3
Full client mode (can submit blobs)
Connecting to Celestia...
Balance: 1000000utia
Submitting blob...
✓ Blob submitted at block 1234567
Retrieving blob...
✓ Retrieved: Hello Celestia!
✓ Data verified!
✓ Tutorial complete!
```

**First run (unfunded account):**

```
Creating account...
Your address: celestia16k0wsej6rewd2pfh0taah35suzf3apj552q8c3
Full client mode (can submit blobs)
Connecting to Celestia...
Balance: 0utia
Account has no funds. Fund this address at the Mocha faucet to submit blobs:
Address: celestia16k0wsej6rewd2pfh0taah35suzf3apj552q8c3
Faucet: https://mocha.celenium.io/faucet
✓ Tutorial complete!
```

**Read-only mode output:**

```
Creating account...
Your address: celestia16k0wsej6rewd2pfh0taah35suzf3apj552q8c3
Read-only mode (cannot submit blobs)
To submit blobs, set CELE_CORE_GRPC environment variable
Connecting to Celestia...
Balance: 1000000utia
✓ Tutorial complete!
```

## Understanding the code

### Key components

- **Keyring**: Manages your Celestia account keys
- **Client**: Connects to Celestia nodes for read/write operations
- **Namespace**: Groups related data together (like a folder)
- **Blob**: The data structure you submit to the network
- **Commitment**: A hash that uniquely identifies your blob

### Connection types

| Purpose     | Node type               | Example URL                                   |
| ----------- | ----------------------- | --------------------------------------------- |
| Read data   | DA JSON-RPC             | `http://localhost:26658`                      |
| Submit data | Consensus node gRPC     | `localhost:9090`                              |

### Read-only mode

To only retrieve data (no submission), remove the `SubmitConfig` from your client configuration:

```go
cfg := client.Config{
    ReadConfig: client.ReadConfig{
        BridgeDAAddr: daURL,
    },
    // No SubmitConfig for read-only
}
```

## Advanced features

### Submitting multiple blobs

You can submit multiple blobs in a single transaction. All blobs are included atomically at the same block height, which is useful for grouping related data together.

```go
func submitMultipleBlobs(ctx context.Context, c *client.Client) error {
	ctx, cancel := context.WithTimeout(ctx, 2*time.Minute)
	defer cancel()

	// Create namespace
	ns, err := share.NewV0Namespace([]byte("tutorial"))
	if err != nil {
		return err
	}

	// Create multiple blobs (can use same namespace, or different namespaces)
	blob1, err := blob.NewBlob(share.ShareVersionZero, ns, []byte("First blob"), nil)
	if err != nil {
		return err
	}
	blob2, err := blob.NewBlob(share.ShareVersionZero, ns, []byte("Second blob"), nil)
	if err != nil {
		return err
	}
	blob3, err := blob.NewBlob(share.ShareVersionZero, ns, []byte("Third blob"), nil)
	if err != nil {
		return err
	}

	// Submit all blobs in a single transaction
	height, err := c.Blob.Submit(ctx, []*blob.Blob{blob1, blob2, blob3}, nil)
	if err != nil {
		return err
	}
	fmt.Printf("✓ All 3 blobs submitted at block %d\n", height)

	// Retrieve each blob using its unique commitment
	retrieved1, _ := c.Blob.Get(ctx, height, ns, blob1.Commitment)
	retrieved2, _ := c.Blob.Get(ctx, height, ns, blob2.Commitment)
	retrieved3, _ := c.Blob.Get(ctx, height, ns, blob3.Commitment)

	fmt.Printf("✓ Retrieved: %s, %s, %s\n",
		string(retrieved1.Data()),
		string(retrieved2.Data()),
		string(retrieved3.Data()))

	return nil
}
```

**Key points:**

- All blobs in the array are included in a single `PayForBlobs` transaction
- They all appear at the same block height
- Each blob can have a different namespace
- Retrieve blobs individually using their namespace and commitment

### Transaction submission modes

Celestia supports three transaction submission modes controlled by `TxWorkerAccounts` in your client configuration. This setting affects how transactions are queued and submitted, impacting throughput and ordering guarantees.

#### Default mode (TxWorkerAccounts = 0)

This is the default behavior (same as the basic tutorial). Transactions are submitted immediately without a queue:

```go
cfg := client.Config{
    ReadConfig: client.ReadConfig{
        BridgeDAAddr: daURL,
        EnableDATLS:  daTLS,
    },
    SubmitConfig: client.SubmitConfig{
        DefaultKeyName: "my_key",
        Network:        p2p.Network("mocha-5"),
        CoreGRPCConfig: client.CoreGRPCConfig{
            Addr:       coreGRPC,
            TLSEnabled: coreTLS,
        },
        // TxWorkerAccounts defaults to 0 (immediate submission)
    },
}
```

**Characteristics:**

- Transactions enter the mempool immediately
- No queuing or waiting for confirmations
- Potential sequence number conflicts if submitting multiple transactions quickly
- Same behavior as versions prior to v0.28.2

#### Queued mode (TxWorkerAccounts = 1)

Enable synchronous, ordered submission by setting `TxWorkerAccounts` to `1`:

```go
cfg.SubmitConfig.TxWorkerAccounts = 1
```

**Characteristics:**

- Each transaction queues until the previous one is confirmed
- Preserves strict ordering of transactions based on submission time
- Works with both sequential and concurrent submission patterns
- Avoids sequence mismatch errors
- Throughput: approximately 1 PayForBlobs transaction every other block

**Example:** Submitting 5 blobs in queued mode:

```go
import (
    "golang.org/x/sync/errgroup"
)

func submitBlobsQueued(ctx context.Context, c *client.Client) error {
    // Create 5 blobs
    blobs := make([]*blob.Blob, 5)
    namespaces := make([]share.Namespace, 5)
    commitments := make([][]byte, 5)

    for i := 0; i < 5; i++ {
        nsBytes := make([]byte, 10)
        copy(nsBytes, fmt.Sprintf("blob-%d", i))
        ns, _ := share.NewV0Namespace(nsBytes)
        namespaces[i] = ns
        blobs[i], _ = blob.NewBlob(share.ShareVersionZero, ns,
            []byte(fmt.Sprintf("Data %d", i)), nil)
        commitments[i] = blobs[i].Commitment
    }

    heights := make([]uint64, 5)
    var g errgroup.Group

    for i := 0; i < 5; i++ {
        idx := i
        g.Go(func() error {
            height, err := c.Blob.Submit(ctx, []*blob.Blob{blobs[idx]}, nil)
            if err != nil {
                return err
            }
            heights[idx] = height
            fmt.Printf("Blob %d submitted at height %d\n", idx+1, height)
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        return err
    }

    // Retrieve and verify all blobs
    for i := 0; i < 5; i++ {
        retrieved, err := c.Blob.Get(ctx, heights[i], namespaces[i], commitments[i])
        if err != nil {
            return err
        }
        fmt.Printf("✓ Blob %d retrieved: %s\n", i+1, string(retrieved.Data()))
    }

    return nil
}
```

**Expected output:**

```
Blob 3 submitted at height 1234567  // First to call Submit()
Blob 1 submitted at height 1234568  // Second to call Submit()
Blob 5 submitted at height 1234569  // Third to call Submit()
Blob 2 submitted at height 1234570  // Fourth to call Submit()
Blob 4 submitted at height 1234571  // Fifth to call Submit()
✓ Blob 1 retrieved: Data 0
✓ Blob 2 retrieved: Data 1
✓ Blob 3 retrieved: Data 2
✓ Blob 4 retrieved: Data 3
✓ Blob 5 retrieved: Data 4
```

Note: With concurrent submission, blobs may print in any order, but their heights will always reflect their submission order (first submitted = lowest height).

#### Parallel mode (TxWorkerAccounts > 1)

For high-throughput applications that don't require sequential ordering, enable parallel submission:

```go
cfg.SubmitConfig.TxWorkerAccounts = 8  // Creates 8 parallel lanes
```

**How it works:**

- Creates `TxWorkerAccounts` parallel submission lanes
- Each lane is a subaccount automatically created and funded from your default account
- Example: `TxWorkerAccounts = 8` creates 7 subaccounts + 1 default account = 8 parallel lanes
- Enables at least 8 PayForBlobs transactions per block

**Important:** To actually utilize parallel lanes, you must submit blobs concurrently (using goroutines). Each `Blob.Submit()` call blocks until the transaction is confirmed, so sequential calls will still be processed sequentially even with `TxWorkerAccounts > 1`. Concurrent submission allows multiple transactions to be processed simultaneously across different parallel lanes.

**Example:** Submitting 8 blobs concurrently in parallel mode:

```go
import (
    "golang.org/x/sync/errgroup"
)

func submitBlobsParallel(ctx context.Context, c *client.Client) error {
    // Create 8 blobs
    blobs := make([]*blob.Blob, 8)
    namespaces := make([]share.Namespace, 8)
    commitments := make([][]byte, 8)

    for i := 0; i < 8; i++ {
        nsBytes := make([]byte, 10)
        copy(nsBytes, fmt.Sprintf("parallel-%d", i))
        ns, _ := share.NewV0Namespace(nsBytes)
        namespaces[i] = ns
        blobs[i], _ = blob.NewBlob(share.ShareVersionZero, ns,
            []byte(fmt.Sprintf("Parallel data %d", i)), nil)
        commitments[i] = blobs[i].Commitment
    }

    heights := make([]uint64, 8)
    var g errgroup.Group

    for i := 0; i < 8; i++ {
        idx := i
        g.Go(func() error {
            height, err := c.Blob.Submit(ctx, []*blob.Blob{blobs[idx]}, nil)
            if err != nil {
                return err
            }
            heights[idx] = height
            fmt.Printf("Blob %d submitted at height %d\n", idx+1, height)
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        return err
    }

    // Retrieve and verify all blobs
    for i := 0; i < 8; i++ {
        retrieved, err := c.Blob.Get(ctx, heights[i], namespaces[i], commitments[i])
        if err != nil {
            return err
        }
        fmt.Printf("✓ Blob %d retrieved: %s\n", i+1, string(retrieved.Data()))
    }

    return nil
}
```

**Expected output (unordered):**

```
Blob 1 submitted at height 1234567
Blob 2 submitted at height 1234567  // Same block!
Blob 3 submitted at height 1234568
Blob 4 submitted at height 1234567  // Same block as 1 and 2!
Blob 5 submitted at height 1234568
Blob 6 submitted at height 1234568
Blob 7 submitted at height 1234569
Blob 8 submitted at height 1234568
✓ Blob 1 retrieved: Parallel data 0
✓ Blob 2 retrieved: Parallel data 1
✓ Blob 3 retrieved: Parallel data 2
✓ Blob 4 retrieved: Parallel data 3
✓ Blob 5 retrieved: Parallel data 4
✓ Blob 6 retrieved: Parallel data 5
✓ Blob 7 retrieved: Parallel data 6
✓ Blob 8 retrieved: Parallel data 7
```

**Important considerations:**

**Ordering**: Parallel submission does NOT guarantee transaction ordering. Blobs may be included in blocks in a different order than submitted.

**Default account only**: Queued and parallel submission modes always use your default account (`DefaultKeyName`). If you specify a different account in `TxConfig` (via `WithKeyName` or `WithSignerAddress`), it will be ignored and the default account will be used instead.

**Retrieving blobs from parallel submission:**

Since you don't know which subaccount submitted each blob, retrieve them using namespace, height, and commitment:

```go
// Store these when submitting
height, err := c.Blob.Submit(ctx, []*blob.Blob{myBlob}, nil)
commitment := myBlob.Commitment
namespace := myBlob.Namespace()

// Later, retrieve using stored values
retrieved, err := c.Blob.Get(ctx, height, namespace, commitment)
```

**Subaccount management:**

- Subaccounts are automatically created and funded from your default account
- They are named `parallel-worker-1`, `parallel-worker-2`, etc. in your keyring
- Subaccounts are reused across node restarts if `TxWorkerAccounts` value remains the same
- If you decrease `TxWorkerAccounts`, only the first N workers are used
- If you increase `TxWorkerAccounts`, additional workers are created

#### Comparison table

| Mode     | TxWorkerAccounts | Ordering       | Throughput       | Use case                                 |
| -------- | ---------------- | -------------- | ---------------- | ---------------------------------------- |
| Default  | 0                | Not guaranteed | Immediate        | Simple applications, single transactions |
| Queued   | 1                | Guaranteed     | ~1 tx per block  | Applications requiring strict ordering   |
| Parallel | >1               | Not guaranteed | ≥N txs per block | High-throughput, unordered workflows     |

## Next steps

- **Production**: Use `keyring.BackendFile` instead of `keyring.BackendTest`
- **Security**: Enable TLS with authentication tokens for production
- **Advanced**: Read the [full client documentation](https://github.com/celestiaorg/celestia-node/blob/main/api/client#readme)

## Troubleshooting

Common errors and solutions:

### Connection errors

**`failed to initialize [share|header|blob] client`**
- Check that your `CELE_DA_URL` is correct and accessible
- Verify the bridge node is running and reachable
- Ensure TLS settings match your node configuration

**`couldn't connect to core endpoint`**
- Verify your `CELE_CORE_GRPC` address is correct
- Check that the consensus node is running
- Ensure firewall rules allow the connection

### Configuration errors

**`default key name should not be empty`**
- Ensure `DefaultKeyName` is set in your `SubmitConfig`

**`keyring is nil`**
- Pass a valid keyring to `client.New()` (cannot be `nil`)

### Blob submission errors

**`blob: not found`**
- The blob doesn't exist at the specified height/namespace/commitment
- Verify the height, namespace, and commitment are correct

**`not allowed namespace ... were used to build the blob`**
- The namespace is reserved or invalid
- Use `share.NewV0Namespace()` with valid user namespaces

**`account for signer ... not found`**
- The account has not been funded yet
- Fund your account at the [Mocha faucet](/operate/networks/mocha-testnet#mocha-testnet-faucet)

**`failed to submit blobs due to insufficient gas price`**
- The estimated or configured gas price is too low
- Either increase `MaxGasPrice` in `TxConfig` or let the client estimate
- Check network congestion (gas prices may be elevated)

**`context deadline exceeded`**
- Network timeout occurred
- Increase the context timeout: `context.WithTimeout(ctx, 5*time.Minute)`
- Check network connectivity to the node

---
Title: Rust client
URL: https://docs.celestia.org/build/post-retrieve-blob/client/rust.md
Source: app/build/post-retrieve-blob/client/rust/page.mdx
---

# Rust client

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.

In submit mode, it additionally uses gRPC and a local signer to build, sign, and broadcast transactions such as transfers and PayForBlobs.

The crate re-exports common Celestia types (namespaces, blobs, app versions, etc.) and is designed to be the easiest way for Rust applications to integrate with Celestia nodes for data retrieval, blob submission, and general chain interaction. ([lib.rs][1], [docs.rs][2])

[1]: https://lib.rs/crates/celestia-client "celestia-client, in Rust // Lib.rs"
[2]: https://docs.rs/celestia-client/latest/celestia_client/ "celestia-client, in Rust // Docs.rs"

---
Title: Submit and retrieve a Fibre blob on Mocha
URL: https://docs.celestia.org/build/post-retrieve-blob/fibre.md
Source: app/build/post-retrieve-blob/fibre/page.mdx
---

# Submit and retrieve a Fibre blob on Mocha

Fibre stores blob shards on validator-operated servers and settles payment
on-chain with `MsgPayForFibre`. This walkthrough deposits testnet TIA into
escrow, submits a namespaced payload, waits for settlement, and downloads the
original bytes.

Use `fibre.Submit` for this first test: it waits for transaction confirmation.
Fibre is separate from the [blob/transaction client flow](/build/post-retrieve-blob/overview)
that uses `blob.Submit` and PayForBlob. Fibre retrieval uses a `blob_id`, rather
than the height, namespace and commitment tuple used by `blob.Get`.

## Prepare a Mocha node

You need:

- A Mocha light or bridge node with Fibre support. The examples use
  celestia-node `v0.34.3-mocha` and a core endpoint running
  celestia-app `v10.4.0-mocha` on `mocha-5`.
  Follow [Install celestia-node](/operate/data-availability/install-celestia-node).
- Bash, `curl`, `jq` and Python 3 for the commands below.
- A local signer funded with Mocha testnet TIA.
- Enough reachable Fibre providers to collect signatures representing the
  required two-thirds of voting power. Check the
  [Mocha Fibre dashboard](https://testnet.celestia.valopers.com/fibre).
  App v10 activation alone does not establish provider readiness.

Check `celestia version` before starting. Older node releases without the
`fibre` API cannot run these requests. The
[released Node API reference](/build/rpc/node-api)
covers these methods when you select `v0.34.3-mocha`.
Select the specification that matches your node version.

If you already have a synced Mocha light or bridge node with a Fibre-capable
core endpoint, use its store, key and RPC address. Otherwise, initialise a
separate light-node store:

```bash
export FIBRE_HOME="$HOME/.celestia-fibre-mocha-guide"
celestia light init --p2p.network mocha --node.store "$FIBRE_HOME"
```

Initialisation creates a signer. Keep the recovery phrase private. If another
node is running on this machine, stop it or configure different P2P listen
ports before starting this node. For faster initial sync, see
[Syncing from a trusted hash](/operate/maintenance/trusted-hash-recovery), including
its checkpoint trust assumption.

Start the node in one terminal and leave it running:

```bash
celestia light start --p2p.network mocha --node.store "$FIBRE_HOME" \
  --core.ip grpc-mocha.pops.one \
  --core.port 443 --core.tls \
  --rpc.addr 127.0.0.1 --rpc.port 27658
```

This core endpoint is a public community service and may rate-limit requests.
For repeated or large tests, use your own Fibre-capable core endpoint or a
provider with suitable limits. Fibre discovers validator upload/download hosts
from the network; the core address is not a Fibre storage server address.

## Fund the signer and authenticate

In a second Bash terminal, enable pipeline failure reporting and set the same
store and local RPC address:

```bash
set -o pipefail
export FIBRE_HOME="$HOME/.celestia-fibre-mocha-guide"
export NODE_RPC=http://127.0.0.1:27658
export KEY_NAME=my_celes_key

celestia state account-address --node.store "$FIBRE_HOME" --url "$NODE_RPC"
```

Fund the returned address using the [Mocha faucet](https://mocha.celenium.io/faucet).
Check the wallet balance:

```bash
celestia state balance --node.store "$FIBRE_HOME" --url "$NODE_RPC"
```

With celestia-node v0.34.2-mocha, restart the node after funding a signer that
was unfunded when the node started. Otherwise, `fibre.Deposit` can panic during
gas estimation. Stop the node with Ctrl+C in the first terminal, then run the
same start command again.

Wait for header sync to catch up before submitting:

```bash
celestia header sync-state --node.store "$FIBRE_HOME" --url "$NODE_RPC"
```

Check that the reported `height` has reached `to_height` and the initial sync
has a non-zero `end` timestamp. The node should continue following new headers.

Generate a token that permits writes. It also permits the read calls used here:

```bash
export AUTH_TOKEN=$(celestia light auth write \
  --p2p.network mocha --node.store "$FIBRE_HOME")
export SIGNER=$(celestia state account-address \
  --node.store "$FIBRE_HOME" --url "$NODE_RPC" | jq -er '.result')

rpc() {
  curl --fail-with-body --silent --show-error \
    --connect-timeout 10 --max-time 180 \
    -H "Authorization: Bearer $AUTH_TOKEN" \
    -H 'Content-Type: application/json' \
    --data-binary @- "$NODE_RPC"
}
```

The examples select `my_celes_key`, the default key created by initialisation.
To use another key, start the node with `--keyring.keyname <key_name>` and set
`KEY_NAME` to that name. `SIGNER` must be that key's public address. The key must
exist in this node's keyring; an address alone does not give the node signing
access. See [Node key management](/operate/keys-wallets/celestia-node-key).

## Query and deposit escrow

Wallet funds pay transaction gas. Fibre escrow pays for blob storage. Keep
some TIA in the wallet when depositing; escrow cannot pay transaction gas.
Amounts use `utia`, where 1 TIA is 1,000,000 utia.

Query this signer's escrow:

```bash
jq -nc --arg signer "$SIGNER" \
  '{jsonrpc:"2.0",id:1,method:"fibre.QueryEscrowAccount",params:[$signer]}' | rpc
```

For a new signer, `escrow account not found for signer` is expected. Deposit
2 testnet TIA for the small example below, after confirming the wallet holds
more than 2 TIA:

```bash
jq -nc --arg key "$KEY_NAME" \
  '{jsonrpc:"2.0",id:2,method:"fibre.Deposit",
    params:[{denom:"utia",amount:"2000000"},{key_name:$key}]}' \
  | rpc > deposit.json &&
jq -es '
  length == 1 and (.[0] | type == "object" and
    (has("error") | not) and has("result") and .result == null)
' deposit.json
```

Success returns `{"jsonrpc":"2.0","id":2,"result":null}`, not a transaction
receipt. Query escrow again and confirm the deposit before proceeding:

```bash
jq -nc --arg signer "$SIGNER" \
  '{jsonrpc:"2.0",id:3,method:"fibre.QueryEscrowAccount",params:[$signer]}' \
  | rpc > escrow.json &&
jq -es '
  length == 1 and (.[0] | type == "object" and
    (has("error") | not) and (.result | type == "object" and
      (.available_balance | type == "object" and .denom == "utia" and
        (.amount | type == "string" and test("^[0-9]+$")))))
' escrow.json &&
jq '.result.available_balance' escrow.json
```

A newly deposited account has these balance fields:

```json
{
  "balance": {"denom": "utia", "amount": "2000000"},
  "available_balance": {"denom": "utia", "amount": "2000000"}
}
```

These are fields inside `result`, alongside `signer`. Pending withdrawals
reduce `available_balance` before they reduce the total `balance`.

## Submit and save the receipt

Both the full 29-byte namespace and the payload are base64 strings in JSON.
Create a version-0 namespace with the ID `fibre-demo` and a small file:

```bash
printf 'Hello, Fibre!\n' > original.bin
NS=$(python3 -c 'import base64; print(base64.b64encode(bytes(19)+b"fibre-demo").decode())')
DATA=$(python3 -c 'import base64; print(base64.b64encode(open("original.bin","rb").read()).decode())')

jq -nc --arg ns "$NS" --arg data "$DATA" --arg key "$KEY_NAME" \
  '{jsonrpc:"2.0",id:4,method:"fibre.Submit",params:[$ns,$data,{key_name:$key}]}' \
  | rpc > submit.json &&
jq -es '
  length == 1 and (.[0] | type == "object" and
    (has("error") | not) and (.result | type == "object" and
      (.height | type == "number" and . > 0 and . == floor) and
      (.tx_hash | type == "string" and length > 0) and
      (.blob_id | type == "string" and length > 0)))
' submit.json &&
jq '.result | {blob_id,height,tx_hash}' submit.json > receipt.json &&
cat receipt.json
```

Stop if any command reports an error or a validation prints `false`. The
`&&` chains run each next command only after the previous command succeeds.
The checks require exactly one JSON response with the expected result fields,
including when the response is empty. A failed submission or validation leaves
any existing `receipt.json` unchanged; do not use an old receipt for this attempt.
An empty response or timeout does not prove that payment failed. Reconcile
settlement as described below before retrying.

On success, `Submit` has uploaded the shards, collected signatures and confirmed
the payment transaction. Save all three receipt fields. For example, the
validated small-blob run returned:

```json
{
  "blob_id": "AMGy8xgg3+lxgxQxMedurPYBoj8Q9V1eZWH05AEyeNTk",
  "height": 1111896,
  "tx_hash": "26E4B81DC2E88F41301F89FD36B7852B049653CFC7F03DF7153AEBDA5F3F49BE"
}
```

Your transaction hash and height will differ. The full response also contains
`validator_signatures` and `payment_promise`. Download your own freshly
submitted blob rather than relying on the historical example remaining stored.

## Download and verify the bytes

Pass the returned `blob_id` unchanged. In JSON-RPC it is base64, whereas the
native Go client's `BlobID.String()` prints hexadecimal. A payment promise
hash shown by an explorer is a separate identifier, not the download blob ID.

```bash
BLOB_ID=$(jq -er '.blob_id' receipt.json)
jq -nc --arg id "$BLOB_ID" \
  '{jsonrpc:"2.0",id:5,method:"fibre.Download",params:[$id]}' \
  | rpc > download.json

python3 - <<'PY'
import base64, hashlib, json
response = json.load(open('download.json'))
if 'error' in response:
    raise SystemExit(response['error'])
data = base64.b64decode(response['result']['data'], validate=True)
if data != open('original.bin', 'rb').read():
    raise SystemExit('Downloaded bytes differ from original')
open('downloaded.bin', 'wb').write(data)
print('Verified identical bytes; SHA-256:', hashlib.sha256(data).hexdigest())
PY
```

The response's `result` is `{"data":"SGVsbG8sIEZpYnJlIQo="}` for this payload.
The expected SHA-256 is:

```text
f0e7fdccb71e36e867930a1f6f0b55bf5cdb5d0d8eca369a8675a7c1cec64cba
```

## Larger blobs and the native client

There are two different size limits in the tested releases:

| Path | Limit |
|---|---|
| Fibre version-0 payload | 128 MiB minus the 5-byte header: 134,217,723 bytes |
| Node HTTP JSON-RPC request | 16 MiB including JSON and base64, leaving slightly less than 12 MiB for payload |

The [node RPC server](https://github.com/celestiaorg/celestia-node/blob/v0.34.2-mocha/api/rpc/server.go)
limits the request body independently of the
[Fibre protocol](https://github.com/celestiaorg/celestia-app/blob/v10.2.0-mocha/fibre/protocol_params.go).
For larger blobs, use the native celestia-app
[Fibre client](https://github.com/celestiaorg/celestia-app/blob/v10.2.0-mocha/fibre/client.go).
Its upload sends shards directly to validators; only the payment transaction
goes through core. See
[`fibre.Put`](https://github.com/celestiaorg/celestia-app/blob/v10.2.0-mocha/fibre/client_put.go)
for a combined upload/settlement example and
[`tools/fibre-txsim`](https://github.com/celestiaorg/celestia-app/blob/v10.2.0-mocha/tools/fibre-txsim/main.go)
for the separate upload, transaction and download steps.

Storage charges use the encoded, padded size, not just the original file's
length. The release's
[payment calculation](https://github.com/celestiaorg/celestia-app/blob/v10.2.0-mocha/x/fibre/types/gas.go)
explains the charge. The observations below are test results, not permanent
prices or performance guarantees. Budget escrow and transaction gas separately.

### Verified Mocha results

Tests on 25 September 2026 used celestia-node v0.34.2-mocha for JSON-RPC and
celestia-app v10.2.0-mocha for the native client. Each successful run confirmed
settlement and verified downloaded bytes against the original payload and hash.

| Payload | Path | Settlement height | Escrow charge, excluding gas |
|---|---|---|---|
| 14 bytes | JSON-RPC | [1,111,896](https://testnet.celestia.valopers.com/transactions/26E4B81DC2E88F41301F89FD36B7852B049653CFC7F03DF7153AEBDA5F3F49BE) | 0.695 testnet TIA |
| 10 MiB | JSON-RPC | [1,112,086](https://testnet.celestia.valopers.com/transactions/B937331E897D90D6B50AD6F7630AF681F970D2577D1D3463A067F1D386A8832C) | 2.495 testnet TIA |
| 128 MiB minus 5 bytes | Native Go | [1,113,071](https://testnet.celestia.valopers.com/transactions/ADD4C5190131D0AFB55AF3341B347700B2ADEC2B128FAF3C7CA06495852C5C16) | 23.69 testnet TIA |

The maximum-size run's SHA-256 was
`53a0a70e69fac696d73438aada6cfa989c5a36c90c3164525f262fed2775721f`.
Its blob ID was `AJ+0/lcm8YgL/06EFKHMnnMaQfJp/ChDQskMk7rkd8FQ`;
the [Tensile record](https://tensile-mocha.huginn.tech/blob/?tx=ADD4C5190131D0AFB55AF3341B347700B2ADEC2B128FAF3C7CA06495852C5C16)
links to the settlement transaction. Tensile accepts transaction hashes, blob IDs
(base64 or hexadecimal), and payment promise hashes. If an identifier matches
multiple records, it shows all matches. The native test trusted the selected
core endpoint for validator state; the light-node path uses locally verified
headers.

## Retention and withdrawals

Fibre storage is time-limited. Query current Mocha parameters before planning
retention or a withdrawal:

```bash
curl --fail --silent --show-error \
  https://api-mocha.pops.one/fibre/v1/params | jq '.params'
```

`shard_retention` determines the minimum shard-retention period;
`payment_promise_timeout` bounds the settlement promise. Keep your own copy of
the data: a confirmed payment is not a permanent storage guarantee.

`fibre.Withdraw` requests a withdrawal, reducing available escrow. The chain
processes it after `withdrawal_delay`; it is not an immediate wallet transfer.
Use `fibre.PendingWithdrawals` with the signer's address to inspect the amount
and `available_timestamp`. Do not reuse escrow committed to outstanding payment
promises, including uploads whose settlement outcome is still unknown.

## Asynchronous uploads and recovery

`fibre.Upload` returns after upload and starts settlement in the background.
In v0.34.2-mocha, background settlement errors are logged. An upload result is
not proof of confirmed payment. Use `Submit` for the first walkthrough.

A timeout or rate limit while confirming a transaction does not prove that it
failed. In the maximum-size test, the core endpoint returned HTTP 429 during
confirmation even though the transaction had settled. A second endpoint
confirmed execution code `0` and the matching Fibre event.

Before resubmitting, check the transaction hash, node logs and chain state
through a working endpoint or explorer. Native clients should retain the
broadcast transaction hash before waiting for confirmation. If the client
returns no hash, inspect the signer's transactions and match the namespace and
commitment. Signed promises can also be charged through the timeout path after
an upload failure; blindly retrying can create another payment obligation.

## Troubleshoot the walkthrough

| Symptom | Check |
|---|---|
| `fibre client is not available` | Configure a Fibre-capable core endpoint, then restart the node. |
| Missing Fibre services or method not found | Check both the node release and the core endpoint's app version and exposed services. |
| Unfunded signer or insufficient escrow | Verify the selected key/address; fund the wallet and deposit into that signer's escrow. Retain wallet funds for gas. |
| Deposit gas-estimation panic after faucet funding | Restart v0.34.2-mocha after the signer is funded, then query escrow before retrying. |
| Header syncing or historical state unavailable | Wait for header sync and use a core endpoint that serves the required state. |
| Not enough voting power, unreachable providers or TLS failures | Check registered/reachable provider stake and client logs. Some stored shards may be retrievable even when signature quorum was not reached. |
| HTTP 429 or uncertain settlement | Back off or use another endpoint; reconcile payment status before resubmitting. |
| Large JSON-RPC request rejected | Account for base64 and JSON overhead, or use the native client. |
| Download fails after retention expires | Recover from your own stored copy. The on-chain receipt does not contain the blob bytes. |

---
Title: Overview to posting and retrieving blobs on Celestia
URL: https://docs.celestia.org/build/post-retrieve-blob/overview.md
Source: app/build/post-retrieve-blob/overview/page.mdx
---

# Overview to posting and retrieving blobs on Celestia

This section will show you how to post and retrieve blobs on Celestia using the transaction client in Golang and Rust.

There are two transaction clients available:

| Option     | What you need                       | Endpoints to set                  | Guides                                                    |
| ---------- | ----------------------------------- | --------------------------------- | --------------------------------------------------------- |
| **Golang** | Local keyring handled by the client | **2** — DA bridge RPC + Core gRPC | [Go client tutorial](/build/post-retrieve-blob/client/go) |
| **Rust**   | Local keyring handled by the client | **2** — DA bridge RPC + Core gRPC | [Rust client](/build/post-retrieve-blob/client/rust)      |

For Fibre storage on Mocha, follow [Submit and retrieve a Fibre blob](/build/post-retrieve-blob/fibre). That guide covers escrow, on-chain settlement, retrieval and the separate Fibre size limits.

---
Title: About Private Blockspace
URL: https://docs.celestia.org/build/private-blockspace/about.md
Source: app/build/private-blockspace/about/page.mdx
---

# About Private Blockspace

The highest-stakes onchain markets—including perpetual exchanges, order books, and institutional rails—depend on information that cannot be public. Positions, balances, liquidations, and routing logic are inherently sensitive. Yet pushing that data offchain reintroduces trusted operators and weakens the core promise of being onchain: **independent auditing, verifiability, and safe exits when it matters most.**

**Private Blockspace** is Celestia’s approach to solving this problem: keep sensitive state **confidential**, while still making it **publicly accountable**.

Private Blockspace enables networks to publish **encrypted state to Celestia**, allowing anyone to verify data availability and protocol commitments **without revealing the underlying contents**. The result is **private systems with public verifiability guarantees**—fault-resistant, auditable, and designed to support safe exit mechanisms.

At a high level, Private Blockspace adds an encryption + proof layer between your application and Celestia’s data availability layer. This layer is implemented as the **Private Blockspace Proxy**: a lightweight service that encrypts, proves, and routes data **without modifying existing Celestia integrations**.

## Submitting a blob

The Private Blockspace Proxy acts as an intermediary between your JSON-RPC client and the Celestia network.

When you submit a blob:

1. The proxy encrypts the data.
2. The proxy generates a proof inside a zkVM attesting to correct encryption and any configured “anchors” about the plaintext.
3. The proxy stores the job result in a local database and returns an acknowledgement while processing continues.
4. Once the proof completes, the result is cached so identical submissions can return immediately.
5. The proxy submits the verifiably encrypted blob to Celestia via `blob.Submit`.

From the client’s perspective, posting encrypted data feels like a single RPC call, while the proxy handles encryption, verifiability, and coordination with Celestia behind the scenes.

```mermaid
sequenceDiagram
    participant JSON RPC Client
    participant Proxy
    participant Celestia Node
    JSON RPC Client->>+Proxy: blob.Submit(blobs, options)<br>{AUTH_TOKEN in header}
    Proxy->>Proxy: Job Processing...<br>{If no DB entry, start new zkVM Job}
    Proxy->>-JSON RPC Client: Response{"Call back"}
    Proxy->>Proxy: ...Job runs to completion...
    JSON RPC Client->>+Proxy:  blob.Submit(blobs, options)<br>{AUTH_TOKEN in header}
    Proxy->>Proxy: Query Job DB<br>Done!<br>{Job Result cached}
    Proxy->>Celestia Node: blob.Submit(V. Encrypt. blobs, options)
    Celestia Node->>Proxy: Response{Inclusion Block Height}
    Proxy->>-JSON RPC Client: Response{Inclusion Block Height}
```

## Retrieving a blob

When retrieving a blob, the proxy behaves as a transparent relay:

1. The client calls `blob.Get(height, namespace, commitment)`.
2. The proxy forwards the request to a Celestia node.
3. The proxy receives the raw blob response.
4. The proxy attempts to deserialize and decrypt using the configured encryption key.

If the blob was encrypted through the proxy, decryption succeeds and the proxy returns the original plaintext bytes. If it was not, the proxy passes the response through unchanged.

This ensures compatibility with both encrypted and unencrypted blobs, so existing clients can adopt Private Blockspace incrementally.

```mermaid
sequenceDiagram
    participant JSON RPC Client
    participant Proxy
    participant Celestia Node

    JSON RPC Client->>+Proxy: blob.Get(height, namespace, commitment)
    Proxy->>Celestia Node: <Passthrough>
    Celestia Node->>Proxy: Response{namespace,data,<br>share_version,commitment,index}
    Proxy->>Proxy: *Try* deserialize & decrypt
    Proxy->>-JSON RPC Client: *Success* -> Response{...,decrypted bytes,...}
    Proxy->>JSON RPC Client: *Failure* -> <Passthrough>
```

## Verifiable Encryption (VE)

With normal encryption, ciphertext should be indistinguishable from random noise. That property is what keeps data private—but it also makes it difficult to prove _anything_ about encrypted data without decrypting it.

Private Blockspace uses **Verifiable Encryption (VE)** to bridge this gap.

VE enables proofs of _select properties_ of fully encrypted data **without decryption**. For example, a system can prove statements like:

- “This encrypted blob contains a Merkle proof whose root is `0xabc123…`”
- “This ciphertext was produced using the expected algorithm, key format, and nonce rules”
- “The plaintext hashes to a specific commitment”

This is accomplished by running encryption inside a zkVM, producing a proof that encryption was executed correctly while also exposing application-defined “anchors” (such as hashes or commitment checks) that remain safe to reveal.

**Outcome:** anyone can verify availability and correctness constraints, while only authorized parties can decrypt the underlying contents.

## Key exchange and management strategies

A critical design question in Private Blockspace is key management:

> If keys are withheld, then the data is effectively withheld.

Private Blockspace is designed to support different key exchange and reconstruction strategies depending on your application requirements and threat model.

### Account-centric model

A proposed account-centric model enforces that **all account state is published and available**, while also being encrypted such that only the intended party (or parties) can decrypt.

Key properties of this approach:

- **User-defined encryption keys:** users define keys for encrypting their own account state, ensuring they can always decrypt their data and enabling forward secrecy.
- **Conditional selective disclosure:** users can allow decryption by specific parties using standard public key cryptography, key exchange protocols, and/or threshold schemes.
- **User-initiated protocol progression:** applications can allow users to progress the protocol themselves by proving correct state transitions onchain, enabling “forced” state updates such as withdrawals.

This model is designed to support systems that remain private during normal operation, while still enabling safe exits and recovery paths under application-defined conditions.

## Use cases

Private Blockspace is designed for applications where **privacy is required**, but **public accountability cannot be sacrificed**.

### Accountable offchain exchanges

Operators of offchain or hybrid exchanges can keep internal state private while still being required (by protocol design) to prove state availability and commitments publicly.

This improves fault tolerance and auditability without forcing users to trust an opaque operator for safe exits.

**In production: Hibachi**

Hibachi is the first independent deployment using Private Blockspace for a fast perps exchange. Hibachi publishes verifiably encrypted exchange state to Celestia, keeping balances and positions private while making data availability and correctness publicly verifiable.

### Trust-minimized data marketplaces

Private Blockspace can also support trust-minimized private data markets:

- sellers publish verifiably encrypted data to Celestia
- buyers verify availability and integrity before payment—without seeing the plaintext
- payment is enforced only once availability is proven

This shifts trust away from intermediaries and toward verification, producing private exchange workflows that are auditable and fault-resistant by design.

## References and further reading

- [Private Blockspace Proxy repo on GitHub](https://github.com/celestiaorg/private-blockspace-proxy/)
- [Verifiable Encryption (VE) in depth](https://github.com/celestiaorg/private-blockspace-proxy/blob/main/doc/verifiable_encryption.md)
- [Forum post: Account-centric model](https://forum.celestia.org/t/account-user-centric-private-blockspace/2155)

---
Title: Private blockspace quickstart
URL: https://docs.celestia.org/build/private-blockspace/quickstart.md
Source: app/build/private-blockspace/quickstart/page.mdx
---

# Private blockspace quickstart

Private blockspace encrypts your blob data before it’s posted to Celestia using a lightweight proxy.  
In this quickstart, you’ll use hosted Celestia nodes (like Quicknode) instead of running your own.

## Get your node credentials

To use Private Blockspace, you’ll need access to a hosted **Celestia Data Availability (DA) + Consensus Node**. The easiest option is [Quicknode’s Celestia service](https://www.quicknode.com/docs/celestia), which provides ready-to-use mainnet and Mocha testnet endpoints. They offer a free 30-day trial, which is enough for this quickstart.

1. Visit the [Quicknode Celestia dashboard](https://www.quicknode.com/docs/celestia) and log in (or create a free account).  
2. Click **Create Endpoint**, then select:  
   - **Chain:** `Celestia`  
   - **Network:** `Mainnet` or `Mocha`
3. Copy the generated endpoint URL (it looks like this): `https://celestia-mocha.quiknode.pro/<your-token>/`
4. Copy the token from your endpoint URL (this is your **write / read token**).  
5. Save both the **URL** and **token** — you’ll add them to your `.env` file next.

## Create your `.env`

Download the repo’s `example.env` and save it as `.env`.  
Edit **only** the following items.

| Key | What to do |
| --- | --- |
| `PBS_DB_PATH` | Absolute path for local proxy data (e.g. `/Users/you/dev/pbs-db`) |
| `ENCRYPTION_KEY` | 32-byte key — see command below |
| `CELESTIA_NODE_RPC` | Your Quicknode HTTPS endpoint (includes your token) |
| `CELESTIA_CORE_GRPC` | Same host + `:9090` (no token in path) |
| `CELESTIA_NODE_WRITE_TOKEN` | Your Quicknode token |
| `CELESTIA_SIGNING_KEY` | 32-byte private key for your signer (funded on Mocha) |
| `TLS_CERTS_PATH` / `TLS_KEY_PATH` | Path to your local TLS cert + key (see next step) |
| `CELESTIA_NETWORK` etc. | Keep defaults; ensure all paths are absolute |

### Generate an `ENCRYPTION_KEY` (ChaCha20, 32 bytes)
This is a random 256-bit symmetric key, **not** a wallet key.

```bash
openssl rand -hex 32
# or
python3 -c "import secrets; print(secrets.token_hex(32))"
```

Paste the value (no quotes) as your `ENCRYPTION_KEY`.

## Generate TLS certificates

The proxy requires TLS certificates (even for local testing).

```bash
mkdir -p tls
openssl req -x509 -nodes -newkey rsa:2048   -keyout tls/tls.key -out tls/tls.crt -days 365   -subj "/CN=localhost"
```

Then mount that folder when running Docker and set:
```
TLS_CERTS_PATH=/app/tls/tls.crt
TLS_KEY_PATH=/app/tls/tls.key
```

Without valid certs, the proxy will exit with  
`TLS_CERTS_PATH required: NotPresent`.

## Fund your signer

Your `CELESTIA_SIGNING_KEY` corresponds to a Mocha testnet address.  
That address must exist and hold some test TIA.

**Get funds from the [Celestia Mocha faucet](https://faucet.celestia-mocha.com).**

You can verify your signer address in the proxy logs it prints the address when starting.

## Run the proxy container

**Apple Silicon (M1/M2/M3)**

The published image is `amd64` only — run it under emulation:

```bash
docker pull --platform=linux/amd64 ghcr.io/celestiaorg/pda-proxy:latest
mkdir -p "$PBS_DB_PATH"

docker run --name pda-proxy --rm -it   --platform=linux/amd64   --env-file ./.env   -v "$PBS_DB_PATH:$PBS_DB_PATH"   -v "./tls:/app/tls"   -p 26657:26657   ghcr.io/celestiaorg/pda-proxy:latest
```

**Intel/AMD Linux or other amd64 hosts**

```bash
docker pull ghcr.io/celestiaorg/pda-proxy:latest
mkdir -p "$PBS_DB_PATH"

docker run --name pda-proxy --rm -it   --env-file ./.env   -v "$PBS_DB_PATH:$PBS_DB_PATH"   -v "./tls:/app/tls"   -p 26657:26657   ghcr.io/celestiaorg/pda-proxy:latest
```

### Verify it’s running

Check logs:
```bash
docker logs -f pda-proxy
```

Or test status:
```bash
curl -k -sS -X POST   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_TOKEN"   --data '{"jsonrpc":"2.0","id":1,"method":"status","params":[]}'   https://127.0.0.1:26657 | jq .
```

On Apple Silicon, keep `--platform=linux/amd64` until a native arm64 image exists.

## Send a blob

Try a small encrypted payload:

```bash
curl -k -sS \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -X POST --data '{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "blob.Submit",
    "params": [[
      {
        "namespace": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAMJ/xGlNMdE=",
        "data": "SSBMb3ZlIEJpZyBCbG9icw==",
        "share_version": 0,
        "commitment": "aHlbp+J9yub6hw/uhK6dP8hBLR2mFy78XNRRdLf2794=",
        "index": -1
      }
    ], {}]
  }' https://127.0.0.1:26657 | jq .

```

The proxy will:
- Encrypt your blob  
- Submit to Celestia  
- Return a `height` and `tx hash`

If the response includes `"result": { "height": "…" }`, you’re set. Jump to **Verify your blob** with that height.

If you see `"[pda-proxy] Verifiable encryption processing..."`, the proxy queued the job. Two quick options:

**Option A — resend once**

Sometimes it finishes fast and you’ll get the height on the next call.

**Option B — find the height**

Either tail logs:
```bash
docker logs -f pda-proxy | egrep -i 'submit|height|commit|error'
```

Or poll a small window around the tip for your namespace:
```bash
LATEST=$(
  curl -k -sS \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -X POST --data '{"jsonrpc":"2.0","id":1,"method":"status","params":[]}' \
    https://127.0.0.1:26657 |
  jq -r '.result.sync_info.latest_block_height'
)

for h in $(seq $((LATEST-2)) $((LATEST+2))); do
  RES=$(
    curl -k -sS \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_TOKEN" \
      -X POST --data "{
        \"id\":1,
        \"jsonrpc\":\"2.0\",
        \"method\":\"blob.GetAll\",
        \"params\":[ $h, [ \"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAMJ/xGlNMdE=\" ] ]
      }" \
      https://127.0.0.1:26657
  )

  if echo "$RES" | jq -e '.result | length > 0' >/dev/null; then
    echo "Height $h"
    echo "$RES" | jq .
  fi
done
```
Copy the `commitment` you see there and use it with `blob.Get`.

## Verify your blob

Now, fetch the same blob through your proxy using the following command with `HEIGHT` replaced with your actual height:

```bash
curl -k -sS   -H "Content-Type: application/json"   -H "Authorization: Bearer YOUR_TOKEN"   -X POST --data "{
    \"id\":1,
    \"jsonrpc\":\"2.0\",
    \"method\":\"blob.GetAll\",
    \"params\":[HEIGHT,[\"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAMJ/xGlNMdE=\"]]
  }" https://127.0.0.1:26657 | jq .
```

You’ll see a `commitment` and your decrypted data:

```json
{
  "commitment": "…base64…",
  "data": "SSBMb3ZlIEJpZyBCbG9icw==",
  "namespace": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAMJ/xGlNMdE="
}
```

**Decode base64 to plaintext**

When you retrieve a blob, the `data` field is base64. To see the plaintext:

**macOS/Linux**
```bash
echo "SSBMb3ZlIEJpZyBCbG9icw==" | base64 -d
```

**Python**
```bash
python3 - <<'PY'
import base64
print(base64.b64decode("SSBMb3ZlIEJpZyBCbG9icw==").decode())
PY
```

**Node.js**
```bash
node -e 'console.log(Buffer.from("SSBMb3ZlIEJpZyBCbG9icw==","base64").toString())'
```

## Troubleshooting

| Error message | Cause | Fix |
| --- | --- | --- |
| `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. |

## ✅ You’re done

You’re running **private blockspace** end-to-end using hosted infrastructure.

✅ No local Celestia node  
✅ Fully containerized  
✅ Encrypted data posted to Celestia

---
Title: Client Libraries
URL: https://docs.celestia.org/build/rpc/clients.md
Source: app/build/rpc/clients/page.mdx
---

# Client Libraries

Celestia Node API can be accessed through various client libraries in different programming languages.

## Official Clients

### Golang Client
Official Go implementation of the Celestia Node RPC client and Transaction Client
- **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

### Rust Client

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
- **Repository**: [grumpyp/celestia-node-client-py](https://github.com/grumpyp/celestia-node-client-py)

### TypeScript Client

Community-maintained TypeScript/JavaScript client for the Celestia Node RPC API
- **Repository**: [ashishbhintade/cntsc](https://github.com/ashishbhintade/cntsc)

## Getting Started

Each client library provides methods to interact with the Celestia Node RPC API. Choose the language that best fits your project requirements.

For API reference and method documentation, see the [Node API](/build/rpc/node-api) section.

---
Title: Community services
URL: https://docs.celestia.org/build/rpc/community-services.md
Source: app/build/rpc/community-services/page.mdx
---

# Community services

Community providers offer paid RPC reads, indexed data APIs, and Model Context
Protocol (MCP) connections for Celestia Mainnet Beta. These services are operated
by their respective providers. Follow their documentation for current pricing,
supported methods, and client compatibility.

## NODERS paid archive RPC

[NODERS archive RPC](https://noders.services/mainnet/celestia/archive-rpc/)
provides paid reads from a Celestia archive consensus node through CometBFT RPC.
Paid requests use the x402 payment protocol with TIA. This is a consensus RPC
service; for blob retrieval through the DA node API, see
[archival DA RPC endpoints](/operate/networks/mainnet-beta#archival-da-rpc-endpoints).

Check connectivity with the free `status` method:

```bash
curl -s https://celestia-archive-rpc.noders.services/status
```

Paid methods return HTTP `402 Payment Required` until payment is supplied.
To make paid calls, follow the provider's
[setup guide](https://noders.services/mainnet/celestia/archive-rpc/#quick-start)
for `x402-celestia-rpc-payer`, fund its wallet with TIA, and configure spending
limits. Each paid call also incurs a network transaction fee. The provider's
guide covers current prices and payment troubleshooting.

## NODERS MCP server

The [NODERS MCP server](https://noders.services/mainnet/celestia/mcp/) lets AI
clients query indexed Mainnet Beta data, including validators, delegations,
staking metrics, account balances, and transactions. Its tools are read-only.

In a client that supports remote MCP servers, add this URL with the
**Streamable HTTP** transport:

```text
https://celestia-mcp.noders.services/mcp
```

After connecting, ask the client to list five bonded Celestia validators and
include their addresses. If the connection fails, check that the URL ends in
`/mcp` and the client uses Streamable HTTP. See the
[connection guide](https://noders.services/mainnet/celestia/mcp/) for client-specific
setup and local installation options.

## Celenium paid API

[Celenium's paid API](https://www.mppscan.com/server/ac886177d1fcc678779495d697f5a5000fca922337cb70c8bed1a5d182c2181a)
provides REST access to indexed Celestia data, including blocks, transactions,
blobs, namespaces, validators, rollups, and network statistics. It supports
pay-per-request access through the Machine Payments Protocol (MPP), without an
account or API key.

Use an MPP-compatible client with `https://mpp.celenium.io`. The
[OpenAPI specification](https://mpp.celenium.io/openapi.json) lists supported
routes and payment requirements; the MPPscan listing includes an AgentCash setup
command. Requests to paid routes without payment return HTTP
`402 Payment Required`.

---
Title: Node API
URL: https://docs.celestia.org/build/rpc/node-api.md
Source: app/build/rpc/node-api/page.mdx
---

# 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.

## Fibre on Mocha

Select `v0.34.3-mocha` in the version selector below for the
released Fibre API, or download its [OpenRPC specification](/specs/openrpc-v0.34.3-mocha.json).
The [Mocha Fibre walkthrough](/build/post-retrieve-blob/fibre) covers node setup,
escrow funding, submission and retrieval, including tested request encodings
and the JSON-RPC size limit. The Mainnet Beta `v0.34.3`
specification does not include Fibre.

The Mocha specification also includes `blob.SubscribeFromStartHeight`, which
replays blobs for a namespace from a start height, then streams new blobs.

## celestia-node v0.31.3 breaking changes

Starting with celestia-node v0.31.3:

- The `fraud` RPC namespace was removed. Calls to `fraud.Get` and
  `fraud.Subscribe` are no longer supported.
- The `type` field returned by `node.Info` is a string such as `"Bridge"` or
  `"Light"` instead of an integer.
- RPC request bodies are limited to 16 MiB. Larger requests are rejected.
- In the Go API, `blob.Commitment.String()` returns a hexadecimal string
  instead of raw bytes. This does not change the JSON encoding of commitment
  fields returned by RPC methods.

See the [celestia-node v0.31.3 release notes](https://github.com/celestiaorg/celestia-node/releases/tag/v0.31.3)
for the complete list of changes.

---
Title: Select a Celestia account in integrations
URL: https://docs.celestia.org/build/stacks/account-selection.md
Source: app/build/stacks/account-selection/page.mdx
---

# Select a Celestia account in integrations

## Overview

One DA node can submit blobs for multiple execution environments, but each
blob submission still needs a specific Celestia signer. Use the OpenRPC
options on `blob.Submit` to select the account per request.

## OpenRPC methods to use

- `blob.Submit(blobs, options)`:
  `options.key_name` or `options.signer_address` selects the signer for that
  submission.
- `state.BalanceForAddress(addr)`:
  checks the balance for the selected signer before submission.
- `state.AccountAddress()`:
  returns the node's default signer, useful for fallback behavior.

Both account selectors refer to a key that is already available in the
Celestia node's keyring. `signer_address` does not provide an external signer.
If both `key_name` and `signer_address` are set, `signer_address` takes
precedence. If neither is set, the node uses its default signer.

## JSON-RPC examples

Submit using a key name:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "blob.Submit",
  "params": [
    [
      {
        "namespace": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAMJ/xGlNMdE=",
        "data": "aGVsbG8gY2VsZXN0aWE=",
        "share_version": 0
      }
    ],
    {
      "key_name": "rollup-a"
    }
  ]
}
```

Submit using an explicit signer address:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "blob.Submit",
  "params": [
    [
      {
        "namespace": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAMJ/xGlNMdE=",
        "data": "aGVsbG8gY2VsZXN0aWE=",
        "share_version": 0
      }
    ],
    {
      "signer_address": "celestia1..."
    }
  ]
}
```

Pre-flight balance check for a signer:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "state.BalanceForAddress",
  "params": ["celestia1..."]
}
```

## Integration notes

Not every integration forwards `blob.Submit` options. Use the configuration
supported by the integration:

| Integration | How to select the Celestia account |
| --- | --- |
| Direct Node API client | Pass `key_name` or `signer_address` in the `blob.Submit` options. |
| OP Stack (`op-alt-da`) | The DA server signs submissions directly. Set `key_name` under `[celestia.signer.local]` in the config file or use `--celestia.tx-client.key-name`. This selects one signer for the DA server, not a signer per Node API request. |
| Arbitrum (`nitro-das-celestia`) | The sidecar does not currently set a signer in `blob.Submit` options, so the Celestia node's default signer is used. Start the node with `--keyring.keyname` to select it. |
| Rollkit / ev-node | Set `--evnode.da.signing_addresses` to a comma-separated list of funded addresses in the Celestia node's keyring. ev-node rotates through the addresses for submissions. |

RollApps and Sovereign SDK deployments can use different Celestia DA adapters.
Check whether the adapter forwards `blob.Submit` options. If it does not,
configure the signer in the adapter or use the Celestia node's default signer.

## Key management and node defaults

If your integration uses only the node default signer, set that default account
at node startup:

```bash
celestia <node-type> start --p2p.network <network> --keyring.keyname <key-name>
```

For wallet/key setup, see
[Create a wallet with celestia-node](/operate/keys-wallets/celestia-node-key).

---
Title: Arbitrum Nitro with Celestia DA
URL: https://docs.celestia.org/build/stacks/nitro-das-server.md
Source: app/build/stacks/nitro-das-server/page.mdx
---

# Arbitrum Nitro with Celestia DA

## Overview

The Arbitrum Nitro integration with Celestia enables Orbit chains to use Celestia for data availability instead of Arbitrum AnyTrust. The implementation uses a sidecar architecture where a separate `celestia-server` handles Celestia-specific operations via RPC.

## How it works

Nitro's batch poster coordinates with the Celestia DAS server to store batch data:

1. **Batch posting**: The [`MaybePostSequencerBatch`](https://github.com/celestiaorg/nitro/blob/v3.6.8/arbnode/batch_poster.go#L1675) method checks if a DAS writer is configured and acquires a lock before posting
2. **Data storage**: The DAS writer calls the Celestia server's [`Store`](https://github.com/celestiaorg/nitro-das-celestia/blob/main/daserver/celestia.go#L302) method, which:
   - Creates a blob from the batch data
   - Submits it to Celestia with retry logic and gas price adjustment
   - Returns a `BlobPointer` containing block height, share indices, and data commitments
3. **Verification dependency**: The dispute-verification design uses Blobstream (default: SP1 Blobstream) to confirm batch availability on Celestia through the hash oracle trick.

> **Blobstream service status:** As of September 2026, the Succinct-operated SP1 Blobstream deployments are no longer maintained and do not receive new commitments. Do not rely on them for new batch commitments. Establish a working Blobstream verification path before relying on this integration for disputes.

## Key features

- **Sidecar architecture**: Processing logic handled by separate `celestia-server`, keeping Nitro nodes lightweight
- **Fallback support**: Native fallback mechanism with configurable `da-preference` parameter (e.g., `["celestia", "anytrust"]`)
- **Preimage oracle**: Validators populate preimage mappings with Celestia hashes for fraud proof support
- **Robust submission**: Automatic retry with gas price adjustment for network congestion

## Resources

- [Nitro fork repository](https://github.com/celestiaorg/nitro)
- [Celestia DAS server](https://github.com/celestiaorg/nitro-das-celestia)
- [Select a Celestia account in integrations](/build/stacks/account-selection)

---
Title: How to run op-alt-da with AWS KMS
URL: https://docs.celestia.org/build/stacks/op-alt-da/aws-kms-guide.md
Source: app/build/stacks/op-alt-da/aws-kms-guide/page.mdx
---

# How to run op-alt-da with AWS KMS

## Overview

This guide walks through running [op-alt-da](https://github.com/celestiaorg/op-alt-da) (da-server) using a Celestia key stored in Amazon Web Services (AWS) key management service (KMS). You will use the localstack, a mock of AWS, to learn how to run the da-server. Once you've done this, you can log in to AWS and use your private key in [prod](#production-aws).

## Prerequisites

- Docker
- Go 1.21+
- A Celestia RPC endpoint from [Quicknode](https://quicknode.com/)

## Getting started

## Setup environment

1. Install awscli:

   ```bash
   brew install awscli
   ```

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
   ```

## Localstack

1. Set mock AWS credentials (required even for localstack):

   ```bash
   export AWS_ACCESS_KEY_ID=test
   export AWS_SECRET_ACCESS_KEY=test
   export AWS_DEFAULT_REGION=us-east-1
   ```

2. Start localstack with KMS enabled:

   ```bash
   docker run -d \
     --name localstack \
     -p 4566:4566 \
     -e SERVICES=kms \
     localstack/localstack
   ```

3. Verify it's running:

   ```bash
   aws --endpoint-url=http://localhost:4566 kms list-keys
   # 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`:

   ```bash
   cp config.toml.example config.toml
   ```

2. Edit `config.toml` with the configs you gathered in the setup:

   ```toml
   [celestia]
   namespace = "000000000000000000000000000000000000000000000000000000acfe"
   keyring_backend = "awskms"
   default_key_name = "alias/op-alt-da/celestia_key"

   bridge_addr = "https://your-endpoint.celestia-mocha.quiknode.pro/your-token/"
   bridge_auth_token = ""
   bridge_tls_enabled = true

   core_grpc_addr = "your-endpoint.celestia-mocha.quiknode.pro:9090"
   core_grpc_auth_token = "your-token"
   core_grpc_tls_enabled = true

   [celestia.awskms]
   region = "us-east-1"
   endpoint = "http://localhost:4566"
   ```

   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

1. Run the op-alt-da server:

   ```bash
   AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1 ./bin/da-server -config config.toml
   ```

   Where this is what the successful start looks like:

   ```bash
   INFO [01-20|14:53:56.130] Initializing Stateless Alt-DA server...
   INFO [01-20|14:53:56.131] Using celestia storage                   url=https://your-endpoint.celestia-mocha.quiknode.pro/your-token/
   INFO [01-20|14:53:56.179] Immediate submission mode (default, no queue)
   INFO [01-20|14:53:56.992] Starting HTTP server                     addr=127.0.0.1:3100
   INFO [01-20|14:53:56.992] Starting metrics server                  addr=:6060
   INFO [01-20|14:53:57.004] Started DA Server
   ```

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 -s -X POST http://127.0.0.1:3100/put \
     -H "Content-Type: application/octet-stream" \
     -d "hello celestia" -o /dev/null
   ```

   A successful POST shows in the server logs:

   ```bash
   INFO [01-20|14:54:15.342] celestia: blob successfully submitted    id=74a5940000000000677e645183667f4d9efe506226fd0dd0b70a4144c8fd05c0aa68407ccf886507
   INFO [01-20|14:54:15.342] Blob submitted successfully              commitment=010c74a5940000000000677e645183667f4d9efe506226fd0dd0b70a4144c8fd05c0aa68407ccf886507 size=14 duration=11.5436025s
   ```

   Check your transaction on [Celenium](https://mocha.celenium.io) by navigating to `https://mocha.celenium.io/address/YOUR_CELESTIA_ADDRESS`.

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-aliases
   ```

   You should see your alias pointing to the key:

   ```bash
   {
       "Aliases": [
           {
               "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"
           }
       ]
   }
   ```

Congratulations, you're set up! You should be able to see your blob has been posted successfully using op-alt-da and AWS KMS. Now you can run your OP Stack rollup with AWS KMS, using the Celestia key in AWS.

## Production (AWS)

For production AWS KMS usage:

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`).

---
Title: Introduction
URL: https://docs.celestia.org/build/stacks/op-alt-da/introduction.md
Source: app/build/stacks/op-alt-da/introduction/page.mdx
---

# Introduction

## Overview

The OP Stack integration with Celestia enables rollups to post transaction data to Celestia instead of Ethereum, while still settling on Ethereum. This reduces costs and improves scalability by using Celestia as a modular data availability layer.

## How it works

The `op-batcher` component batches rollup blocks and submits them to Celestia rather than posting calldata to Ethereum:

1. **Data submission**: The batcher calls [`publishTxToL1`](https://github.com/ethereum-optimism/optimism/blob/develop/op-batcher/batcher/driver.go#L931) which retrieves batch data from the channel manager
2. **Celestia storage**: For Celestia-enabled chains, [`celestia_storage.Put`](https://github.com/celestiaorg/op-alt-da/blob/main/celestia_storage.go#L200) submits the blob to Celestia using a configured namespace
3. **Commitment recording**: A commitment identifier (version byte + blob ID) is generated and recorded on Ethereum
4. **Data retrieval**: When `op-node` needs data, it reads the commitment from Ethereum, then fetches the actual blob from Celestia

## Celestia fork differences

The [Celestia fork](https://github.com/celestiaorg/optimism/blob/celestia-develop/op-batcher/batcher/driver.go#L1092) of OP Stack includes:

- Direct blob submission to Celestia with namespace-based organization
- Fallback mechanisms for DA failures (supporting both blob data and calldata alternatives)
- Commitment-based references using Celestia block heights

## Resources

- [op-alt-da repository](https://github.com/celestiaorg/op-alt-da)
- [Celestia OP Stack fork](https://github.com/celestiaorg/optimism)
- [Select a Celestia account in integrations](/build/stacks/account-selection)

---
Title: Celestia docs
URL: https://docs.celestia.org/index.md
Source: app/page.mdx
---

# Celestia docs

    Build with modular data availability.

    Celestia is a modular data availability network. Rollups publish transaction
    data to Celestia while choosing their own execution and settlement layers.
    Use these docs to learn how data availability works, post and retrieve blobs,
    and run a node on Mainnet Beta or the Mocha testnet.

[Start building](/build/post-retrieve-blob/overview/)

[Explore the API](/build/rpc/node-api/)

[Learn](/learn/celestia-101/data-availability/): Understand modular blockchains and Celestia's architecture, including data availability sampling and how rollups use blobspace.

[Build](/build/post-retrieve-blob/overview/): Post and retrieve your first blob with Go and Rust transaction clients. Follow the guides for signer setup, funding, and testnet examples.

[Operate](/operate/getting-started/overview/): Choose a node type, check hardware requirements, and install Celestia software. Find guides for maintenance, monitoring, and troubleshooting.

[Node API](/build/rpc/node-api/): Explore Celestia Node JSON-RPC methods, authentication, and client libraries. Download versioned OpenRPC specifications from the API reference.

---
Title: Security and audits
URL: https://docs.celestia.org/learn/audits.md
Source: app/learn/audits/page.mdx
---

# Security and audits

## Security disclosures

The security disclosure contact is [security@celestia.org](mailto:security@celestia.org).
Do not report vulnerabilities in public issues or discussions. Follow the
[Celestia security policy](https://github.com/celestiaorg/.github/blob/main/SECURITY.md):
submit a private security advisory in the affected repository, or email the
security disclosure contact if private reporting is unavailable.

## Audit reports

This page provides a comprehensive list of audits conducted on various Celestia software, including OP Stack, Nitro, celestia-app, Blobstream, and more. Each audit is linked to its respective report.

| Software                   | Auditor          | Link                                                                                                                       |
| -------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| OP Stack                   | OtterSec         | [Link](/audits/Celestia_OP_Stack_Audit.pdf)                                                       |
| Nitro                      | OtterSec         | [Link](https://github.com/celestiaorg/nitro/blob/celestia-v2.3.3/audits/celestia/arbitrum_nitro_celestia_audit_report.pdf) |
| v2 celestia-app Lemongrass | Informal Systems | [Link](https://github.com/celestiaorg/celestia-app/blob/main/docs/audit/informal-systems-v2.pdf)                           |
| v3 celestia-app            | Informal Systems | [Link](https://github.com/celestiaorg/celestia-app/blob/main/docs/audit/informal-systems-authored-blobs.pdf)               |
| Blobstream SP1             | OtterSec         | [Link](/audits/SP1_Blobstream_Ottersec_Audit.pdf)                                                 |
| Blobstream SP1             | Multiple         | [Link](https://github.com/succinctlabs/sp1/tree/dev/audits)                                                                |
| Blobstream X               | Informal Systems | [Link](/audits/Blobstream_X-Informal_Systems_Audit.pdf)                                           |
| Blobstream X               | OtterSec         | [Link](/audits/Blobstream_X-OtterSec_Audit.pdf)                                                   |
| Blobstream X               | Veridise         | [Link](/audits/Blobstream_X-Veridise_Audit.pdf)                                                   |
| Blobstream X               | Zellic           | [Link](/audits/Blobstream_X-Zellic_Audit.pdf)                                                     |
| Shwap                      | OtterSec         | [Link](/audits/celestia_shwap_audit_final.pdf)                                                    |
| High throughput recovery   | Informal Systems | [Link](https://github.com/celestiaorg/celestia-app/blob/main/docs/audit/informal-systems-recovery.pdf)                     |

---
Title: Blobstream (legacy)
URL: https://docs.celestia.org/learn/blobstream.md
Source: app/learn/blobstream/page.mdx
---

# Blobstream (legacy)

Blobstream was a data availability attestation bridge that let EVM chains verify that data was published to Celestia. It relayed commitments to Celestia data roots to a smart contract on the target EVM chain, where rollup contracts could verify inclusion proofs against them.

> **Legacy notice:** As of September 2026, the Succinct-operated SP1 Blobstream deployments are no longer maintained and do not receive new commitments, and Celenium no longer offers its Blobstream explorer. The integration and operator guides that previously lived in these docs have been removed.

## What remains

- [Blobstream proof queries (legacy)](/build/blobstream/proof-queries) documents how to query inclusion proofs from a Celestia consensus node and how they map to the Blobstream contract format.
- [Audits](/learn/audits) lists the historical Blobstream X and SP1 Blobstream audit reports.
- The [blobstream-contracts](https://github.com/celestiaorg/blobstream-contracts) and [sp1-blobstream](https://github.com/succinctlabs/sp1-blobstream) repositories remain available on GitHub.

If you depend on Blobstream for dispute verification, such as with [Arbitrum Nitro with Celestia DA](/build/stacks/nitro-das-server), you must operate or source your own Blobstream verification path.

---
Title: Data availability FAQ
URL: https://docs.celestia.org/learn/celestia-101/data-availability-faq.md
Source: app/learn/celestia-101/data-availability-faq/page.mdx
---

# Data availability FAQ

# What is data availability?

Data availability is about proving that a block's transactions have been published to the network. In most chains this means downloading all transaction data for a new block; in Celestia, light nodes can answer this question via DAS without full downloads.

![Data availability](/img/learn/data-availability-faq/Data-availability.png)

## What is the data availability problem?

If a block producer withholds data for a proposed block (a data withholding attack), other nodes cannot update state or verify the chain. The risk varies by architecture—for example, rollups and validiums are especially sensitive.

## How do nodes verify data availability in Celestia?

Full nodes can download entire blocks as usual. Light nodes leverage DAS: they request random shares with Merkle proofs from the extended data matrix. See [Data availability sampling](#data-availability-sampling-das) for details.

## What is data availability sampling?

DAS lets light nodes make repeated random sampling requests for small portions of a block. As more samples succeed, confidence that the full block is available rises (e.g., to 99%+). A simple analogy is coin flips: enough successful flips (samples) give high confidence the data exists.

## What security assumptions does DAS rely on?

- Enough light nodes sample for the given block size so an honest bridge node can reconstruct the full block from their collected shares.
- Light nodes connect to at least one honest bridge node to receive fraud proofs for incorrectly erasure-coded blocks; eclipse attacks can break this assumption.

## Why is block reconstruction necessary for security?

Blocks are erasure coded; malicious encoders could extend data incorrectly. Bridge nodes need the full block to produce fraud proofs of bad encoding. If only light nodes receive data and bridge nodes cannot reconstruct the block, the network could miss invalid encoding.

## What is data storage and how is it different?

Data storage concerns keeping and retrieving historical transaction data. The security assumption for storage is 1-of-N honesty—only one honest keeper of history is needed—while data availability is about new blocks being publishable and verifiable.

![Data storage](/img/learn/data-availability-faq/Data-storage.png)

## What problems arise around data storage?

If historical data cannot be retrieved, users may lose access to transaction history and nodes cannot sync from genesis. This is a retrieval problem, not an availability problem.

## Where does blockchain state fit into this?

State (balances, contract storage, validator set) is a snapshot derived from transaction data. Its growth poses different challenges than DA or data retrieval.

## Why doesn’t Celestia incentivize storing historical data?

Guaranteeing permanent storage is not the DA layer’s role, and storage needs only 1-of-N honest providers. Celestia focuses on securely publishing data; third parties store history based on their incentives.

## Who might store historical data?

- Block explorers serving past transactions
- Indexers with query APIs
- Applications or rollups needing history for processes
- Users who want their own transaction history

## How can chains improve data retrievability?

- Reward nodes for storing and serving data (e.g., storage networks like [Filecoin](https://filecoin.io)).
- Publish transaction data to an incentivized storage layer.
- Offer paid archival access or snapshots so others can sync from known good data.

---
Title: Celestia's data availability layer
URL: https://docs.celestia.org/learn/celestia-101/data-availability.md
Source: app/learn/celestia-101/data-availability/page.mdx
---

# Celestia's data availability layer

Data availability (DA) answers a simple question: **has this block's data been published and can it be downloaded? In other words, is the data available?** When a node receives a new block, it must be able to retrieve the associated transaction data; otherwise, the chain can stall or be exploited. Celestia provides a modular DA layer so light nodes can verify availability efficiently without downloading whole blocks.

## tl;dr

1. Celestia is a modular data availability network: it orders blobs and keeps them available while execution and settlement live on layers above.
2. It scales by decoupling execution from consensus and using data availability sampling (DAS) so light nodes can verify availability without downloading whole blocks; more light nodes sampling safely unlocks larger block sizes.
3. Namespaced Merkle trees (NMTs) let each app fetch only its own namespaced data and prove availability.
4. Block producers erasure-code blobs into a $2k \times 2k$ matrix, commit to every row and column, and put that root in the header.
5. Light nodes sample within a rolling window; archival nodes (or providers) keep older data retrievable.

Celestia is a data availability (DA) layer that provides a
scalable solution to the [data availability problem](https://coinmarketcap.com/academy/article/what-is-data-availability).
Due to the permissionless nature of the blockchain networks,
a DA layer must provide a mechanism for the execution and settlement
layers to check in a trust-minimized way whether transaction data is indeed available.

Two key features of Celestia's DA layer are [data availability sampling](https://blog.celestia.org/celestia-mvp-release-data-availability-sampling-light-clients)
(DAS) and [Namespaced Merkle trees](https://github.com/celestiaorg/nmt) (NMTs).
Both features are novel blockchain scaling solutions: DAS enables light
nodes to verify data availability without needing to download an entire block;
NMTs enable execution and settlement layers on Celestia to download transactions
that are only relevant to them.

## Data availability sampling (DAS)

In general, light nodes download only block headers that contain
commitments (_i.e._, Merkle roots) of the block data (_i.e._, the list of transactions).

To make DAS possible, Celestia uses a 2-dimensional Reed-Solomon
encoding scheme to encode the block data: every block data is split
into $k \times k$ shares, arranged in a $k \times k$ matrix, and extended with parity
data into a $2k \times 2k$ extended matrix by applying multiple
times Reed-Solomon encoding.

Then, $4k$ separate Merkle roots are computed for the rows and columns
of the extended matrix; the Merkle root of these Merkle roots is used
as the block data commitment in the block header.

![2D Reed-Soloman (RS) Encoding](/img/learn/reed-solomon-encoding.png)

To verify that the data is available, Celestia light nodes are sampling
the $2k \times 2k$ data shares.

Every light node randomly chooses a set of unique coordinates in the
extended matrix and queries bridge nodes for the data shares and the
corresponding Merkle proofs at those coordinates. If light nodes
receive a valid response for each sampling query, then there is a
[high probability guarantee](https://github.com/celestiaorg/celestia-node/issues/805#issuecomment-1150081075)
that the whole block's data is available.

Additionally, every received data share with a correct Merkle proof
is gossiped to the network. As a result, as long as the Celestia light
nodes are sampling together enough data shares (_i.e._, at least
$k \times k$ unique shares),
the full block can be recovered by honest bridge nodes.

For more details on DAS, take a look at the [original paper](https://arxiv.org/abs/1809.09044).

### Scalability

DAS enables Celestia to scale the DA layer. DAS can be performed by
resource-limited light nodes since each light node only samples a small
portion of the block data. The more light nodes there are in the network,
the more data they can collectively download and store.

This means that increasing the number of light nodes performing DAS allows
for larger blocks (_i.e._, with more transactions), while still keeping DAS
feasible for resource-limited light nodes. However, in order to validate
block headers, Celestia light nodes need to download the $4k$ intermediate
Merkle roots.

For a block data size of $n^2$ bytes, this means that every light node must
download $O(n)$ bytes. Therefore, any improvement in the bandwidth capacity
of Celestia light nodes has a quadratic effect on the throughput of Celestia's
DA layer.

### Fraud proofs of incorrectly extended data

The requirement of downloading the $4k$ intermediate Merkle roots is a
consequence of using a 2-dimensional Reed-Solomon encoding scheme. Alternatively,
DAS could be designed with a standard (_i.e._, 1-dimensional) Reed-Solomon encoding,
where the original data is split into $k$ shares and extended with $k$ additional
shares of parity data. Since the block data commitment is the Merkle root of the
$2k$ resulting data shares, light nodes no longer need to download $O(n)$ bytes to
validate block headers.

The downside of the standard Reed-Solomon encoding is dealing with malicious
block producers that generate the extended data incorrectly.

This is possible as **Celestia does not require a majority of the consensus
(_i.e._, block producers) to be honest to guarantee data availability.**
Thus, if the extended data is invalid, the original data might not be
recoverable, even if the light nodes are sampling sufficient unique shares
(_i.e._, at least $k$ for a standard encoding and $k \times k$ for a
2-dimensional encoding).

As a solution, _Fraud Proofs of Incorrectly Generated Extended Data_ enable
light nodes to reject blocks with invalid extended data. Such proofs require
reconstructing the encoding and verifying the mismatch. With standard Reed-Solomon
encoding, this entails downloading the original data, _i.e._, _n²_ bytes.
Contrastingly, with 2-dimensional Reed-Solomon encoding, only $O(n)$ bytes are
required as it is sufficient to verify only one row or one column of the
extended matrix.

## Namespaced Merkle trees (NMTs)

Celestia partitions the block data into multiple namespaces, one for
every application (e.g., rollup) using the DA layer. As a result, every
application needs to download only its own data and can ignore the data
of other applications.

For this to work, the DA layer must be able to prove that the provided
data is complete, _i.e._, all the data for a given namespace is returned.
To this end, Celestia is using Namespaced Merkle trees (NMTs).

An NMT is a Merkle tree with the leaves ordered by the namespace identifiers
and the hash function modified so that every node in the tree includes the
range of namespaces of all its descendants. The following figure shows an
example of an NMT with height three (_i.e._, eight data shares). The data is
partitioned into three namespaces.

![Namespaced Merkle Tree](/img/learn/nmt.png)

When an application requests the data for namespace 2, the DA layer must
provide the data shares `D3`, `D4`, `D5`, and `D6` and the nodes `N2`, `N8`
and `N7` as proof (note that the application already has the root `N14` from
the block header).

As a result, the application is able to check that the provided data is part
of the block data. Furthermore, the application can verify that all the data
for namespace 2 was provided. If the DA layer provides for example only the
data shares `D4` and `D5`, it must also provide nodes `N12` and `N11` as proofs.
However, the application can identify that the data is incomplete by checking
the namespace range of the two nodes, _i.e._, both `N12` and `N11` have descendants
part of namespace 2.

For more details on NMTs, refer to the [original paper](https://arxiv.org/abs/1905.09274).

## Building a PoS blockchain for DA

### Providing data availability

The Celestia DA layer consists of a PoS blockchain. Celestia is dubbing this
blockchain as the [celestia-app](https://github.com/celestiaorg/celestia-app),
an application that provides transactions to facilitate the DA layer and is built
using [Cosmos SDK](https://docs.cosmos.network/sdk/v0.53). The following figure
shows the main components of celestia-app.

![Main components of celestia-app](/img/learn/celestia-app.png)

celestia-app is built on top of [celestia-core](https://github.com/celestiaorg/celestia-core),
a modified version of the [Tendermint consensus algorithm](https://arxiv.org/abs/1807.04938).
Among the more important changes to vanilla Tendermint, celestia-core:

- Enables the erasure coding of block data (using the [2-dimensional Reed-Solomon
  encoding scheme](https://github.com/celestiaorg/rsmt2d)).
- Replaces the regular Merkle tree used by Tendermint to store block data with
  a [Namespaced Merkle tree](https://github.com/celestiaorg/nmt) that enables
  the above layers (_i.e._, execution and settlement) to only download the needed
  data (for more details, see the section below describing use cases).

For more details on the changes to Tendermint, take a look at the
[ADRs](https://github.com/celestiaorg/celestia-core/tree/v0.34.x-celestia/docs/celestia-architecture).
Notice that celestia-core nodes are still using the Tendermint p2p network.

Similarly to Tendermint, celestia-core is connected to the application layer
(_i.e._, the state machine) by [ABCI++](https://github.com/tendermint/tendermint/tree/master/spec/abci%2B%2B),
a major evolution of [ABCI](https://github.com/tendermint/tendermint/tree/master/spec/abci)
(Application Blockchain Interface).

The celestia-app state machine is necessary to execute the PoS logic and to
enable the governance of the DA layer.

However, the celestia-app is data-agnostic -- the state machine neither
validates nor stores the data that is made available by the celestia-app.

## Monolithic vs. modular blockchains

Blockchains instantiate [replicated state machines](https://dl.acm.org/doi/abs/10.1145/98163.98167):
the nodes in a permissionless distributed network apply an ordered sequence
of deterministic transactions to an initial state resulting in a common
final state.

In other words, this means that nodes in a network all follow
the same set of rules (_i.e._, an ordered sequence of transactions) to go from a
starting point (_i.e._, an initial state) to an ending point
(_i.e._, a common final state). This process ensures that all
nodes in the network agree on the final state
of the blockchain, even though they operate independently.

This means blockchains
require the following four functions:

- **Execution** entails executing transactions that update the state correctly.
  Thus, execution must ensure that only valid transactions are executed, _i.e._,
  transactions that result in valid state machine transitions.
- **Settlement** entails an environment for execution layers to verify proofs,
  resolve fraud disputes, and bridge between other execution layers.
- **Consensus** entails agreeing on the order of the transactions.
- **Data Availability** (DA) entails making the transaction data available.
  Note that execution, settlement, and consensus require DA.

Traditional blockchains, _i.e._ _monolithic blockchains_, implement all four
functions together in a single base consensus layer. The problem with
monolithic blockchains is that the consensus layer must perform numerous
different tasks, and it cannot be optimized for only one of these functions.
As a result, the monolithic paradigm limits the throughput of the system.

![Modular VS Monolithic](/img/learn/monolithic-modular.png)

As a solution, modular blockchains decouple these functions among
multiple specialized layers as part of a modular stack. Due to the
flexibility that specialization provides, there are many possibilities
in which that stack can be arranged. For example, one such arrangement
is the separation of the four functions into three specialized layers.

The base layer consists of DA and consensus and thus, is referred to
as the Consensus and DA layer (or for brevity, the DA layer), while both
settlement and execution are moved on top in their own layers. As a result,
every layer can be specialized to optimally perform only its function, and thus,
increase the throughput of the system. Furthermore, this modular paradigm
enables multiple execution layers, _i.e._,
[rollups](https://vitalik.eth.limo/general/2021/01/05/rollup.html), to use the
same settlement and DA layers.

---
Title: Data, dashboards, and analytics
URL: https://docs.celestia.org/learn/celestia-101/resources.md
Source: app/learn/celestia-101/resources/page.mdx
---

# Data, dashboards, and analytics

A collection of useful tools, dashboards, and analytics platforms for exploring the Celestia network.

## Useful links

1. Learn category of celestia.org: https://celestia.org/learn/
2. Celestia glossary: https://celestia.org/glossary/
3. Celestia-app specifications: https://celestiaorg.github.io/celestia-app/
4. Awesome-celestia repo: https://github.com/celestiaorg/awesome-celestia/

## Data analytics & dashboards

| Resource          | Description                                                  | URL                                                                            |
| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| **Celenium**      | Blockchain explorer and analytics platform for Celestia      | [celenium.io](https://celenium.io/)                                            |
| **Celestia Data** | Comprehensive analytics and metrics for the Celestia network | [celestiadata.com](https://celestiadata.com/)                                  |
| **L2 Beat**       | Data availability tracking and metrics by L2BEAT             | [l2beat.com](https://l2beat.com/data-availability/projects/celestia/no-bridge) |
| **ProbeLab**      | Network monitoring and topology analytics for Celestia       | [probelab.io](https://probelab.io/celestia/)                                   |

## Bridge & node data

| Resource                       | Description                                         | URL                                                                                                             |
| ------------------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Bridge node data dashboard** | Looker Studio dashboard for Celestia bridge metrics | [View dashboard](https://lookerstudio.google.com/u/0/reporting/73fc0733-5f3e-4a85-be1f-081f99991f4c/page/Tn17D) |

## Research & analytics

| Resource                       | Description                                                     | URL                                                                                                                    |
| ------------------------------ | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Blockworks research (paid)** | In-depth analytics and research on TIA and the Celestia network | [View analytics](https://app.blockworks.com/analytics/celestia)                  |
| **Numia blocks dashboard**     | Blocks analytics dashboard                                      | [View dashboard](https://lookerstudio.google.com/u/0/reporting/6d5530fd-4115-4951-8a79-644842f6a2b3/page/Tn17D)        |
| **Numia rollups dashboard**    | Rollups analytics dashboard                                     | [View dashboard](https://lookerstudio.google.com/u/0/reporting/8853db32-fe0b-4a39-b4d7-3b9efd9e5226/page/p_da0hhwxfjd) |

## Rollup tracking

| Resource       | Description                             | URL                              |
| -------------- | --------------------------------------- | -------------------------------- |
| **rollup.wtf** | Rollup ecosystem tracking and analytics | [rollup.wtf](https://rollup.wtf) |

---
Title: Data retrievability and pruning
URL: https://docs.celestia.org/learn/celestia-101/retrievability.md
Source: app/learn/celestia-101/retrievability/page.mdx
---

# Data retrievability and pruning

The purpose of data availability layers such as Celestia is to ensure
that block data is provably published, so that applications
and rollups can know what the state of their chain is, and store that data.
Once the data is published, data availability layers
[do not inherently guarantee that historical data will be permanently stored](https://notes.ethereum.org/@vbuterin/proto_danksharding_faq#If-data-is-deleted-after-30-days-how-would-users-access-older-blobs)
and remain retrievable.

In this document, we discuss the state of data retrievability and
pruning in Celestia, as well as some tips for rollup developers in
order to ensure that syncing new rollup nodes is possible.

## Data retrievability and pruning in celestia-node

As of version v6 of celestia-app, celestia-node has implemented a light node
sampling window of 7 days, as specified in
[CIP-36](https://github.com/celestiaorg/CIPs/blob/main/cips/cip-036.md).
Light nodes now only sample blocks within a 7-day
window instead of sampling all blocks from genesis. This change
introduces the concept of pruning to celestia-node, where data
outside of the 7-day window may not be stored by light nodes,
marking a significant update in how data retrievability and
storage are managed within the network.

Data blobs older than the recency window will be pruned by default
on light nodes,
but will continue to be stored by archival nodes that do not prune data. Light
nodes will be able to query historic blob data in namespaces from archival
nodes, as long as archival nodes exist on the public network.

## Suggested practices for rollups

Rollups may need to access historic data in order to allow new rollup nodes
to reconstruct the latest state by replaying historical blocks. Once data has
been published on Celestia and guaranteed to have been made available, rollups
and applications are responsible for storing their historical data.

While it is possible to continue to do this by using the `GetAll` API method in
celestia-node on historic blocks as long as archival nodes exist on the public
Celestia network, rollup developers should not rely on this as the only method
to access historical data, as archival nodes serving requests for historical
data for free is not guaranteed. Below are some other suggested methods to
access historical data.

- **Use professional archival node or data providers.** It is expected that
  professional infrastructure providers will provide paid access to archival
  nodes, where historical data can be retrieved, for example using the `GetAll`
  API method. Providers like Quicknode offer archival node services that maintain
  complete historical data, ensuring reliable access to past transactions and state.
  This provides better guarantees than solely relying on free archival nodes on the
  public Celestia network. For a list of available providers, see the
  [network's](/operate/networks/mainnet-beta) page, and for specific archival
  node endpoints, refer to the [archival DA RPC endpoints](/operate/networks/mainnet-beta#archival-da-rpc-endpoints)
  section.

- **Share snapshots of rollup nodes.** Rollups could share snapshots of their
  data directories which can be downloaded manually by users bootstrapping new
  nodes. These snapshots could contain the latest state of the rollup, and/or
  all the historical blocks.
- **Add peer-to-peer support for historical block sync.** A less manual version
  of sharing snapshots, where rollup nodes could implement built-in support for
  block sync, where rollup nodes download historical block data from each other
  over a peer-to-peer network.
  - [**Namespace pinning.**](https://github.com/celestiaorg/celestia-node/issues/2830)
    In the future, celestia-node is expected to allow nodes to choose to "pin"
    data from selected namespaces that they wish to store and make available for
    other nodes. This will allow rollup nodes to be responsible for storing their
    data, without needing to implement their own peer-to-peer historical block
    sync mechanism.

---
Title: The lifecycle of a celestia-app transaction
URL: https://docs.celestia.org/learn/celestia-101/transaction-lifecycle.md
Source: app/learn/celestia-101/transaction-lifecycle/page.mdx
---

# The lifecycle of a celestia-app transaction

Users request the celestia-app to make data available by
sending `PayForBlobs` transactions. Every such transaction consists
of the identity of the sender, the data to be made available, also
referred to as the message, the data size, the namespace, and
a signature. Every block producer batches multiple `PayForBlobs`
transactions into a block.

Before proposing the block though, the producer passes it to the
state machine via ABCI++, where each `PayForBlobs` transaction is
split into a namespaced message (denoted by `Msg` in the figure below),
i.e., the data together with the namespace ID, and an executable
transaction (denoted by `e-Tx` in the figure below) that does not
contain the data, but only a commitment that can be used at a later
time to prove that the data was indeed made available.

Thus, the block data consists of data partitioned into namespaces
and executable transactions. Note that only these transactions are
executed by the Celestia state machine once the block is committed.

![Lifecycle of a celestia-app Transaction](/img/learn/tx-lifecycle.png)

Next, the block producer adds to the block header a commitment
of the block data. As
[described in the "Celestia's data availability layer" page](/learn/celestia-101/data-availability),
the commitment is the Merkle root of the $4k$ intermediate Merkle roots
(i.e., one for each row and column of the extended matrix).
To compute this commitment, the block producer performs the following operations:

- It splits the executable transactions and the namespaced data
  into shares. Every share consists of some bytes prefixed by a
  namespace. To this end, the executable transactions are associated
  with a reserved namespace.
- It arranges these shares into a square matrix (row-wise). Note that
  the shares are padded to the next power of two. The outcome square
  of size $k \times k$ is referred to as the original data.
- It extends the original data to a $2k \times 2k$ square matrix using
  the 2-dimensional Reed-Solomon encoding scheme described above.
  The extended shares (i.e., containing erasure data) are associated
  with another reserved namespace.
- It computes a commitment for every row and column of the extended
  matrix using the NMTs described above.

Thus, the commitment of the block data is the root of a Merkle tree
with the leaves the roots of a forest of Namespaced Merkle subtrees,
one for every row and column of the extended matrix.

## Checking data availability

![DA network](/img/learn/consensus-da.png)

To enhance connectivity, the celestia-node augments the celestia-app
with a separate libp2p network, _i.e._, the so-called _DA network_,
that serves DAS requests.

Light nodes connect to a celestia-node in the DA network, listen to
extended block headers (i.e., the block headers together with the
relevant DA metadata, such as the $4k$ intermediate Merkle roots), and
perform DAS on the received headers (i.e., ask for random data shares).

Note that although it is recommended, performing DAS is optional -- light
nodes could just trust that the data corresponding to the commitments in
the block headers was indeed made available by the Celestia DA layer.
In addition, light nodes can also submit transactions to the celestia-app,
i.e., `PayForBlobs` transactions.

While performing DAS for a block header, every light node queries Celestia
Nodes for a number of random data shares from the extended matrix and the
corresponding Merkle proofs. If all the queries are successful, then the
light node accepts the block header as valid (from a DA perspective).

If at least one of the queries fails (i.e., either the data share is not
received or the Merkle proof is invalid), then the light node rejects the
block header and tries again later. The retrial is necessary to deal with
false negatives, i.e., block headers being rejected although the block
data is available. This may happen due to network congestion for example.

Alternatively, light nodes may accept a block header although the data
is not available, i.e., a _false positive_. This is possible since the
soundness property (i.e., if an honest light node accepts a block as available,
then at least one honest bridge node will eventually have the entire block data)
is probabilistically guaranteed (for more details, take a look at the
[original paper](https://arxiv.org/abs/1809.09044)).

By fine tuning Celestia's parameters (e.g., the number of data shares sampled
by each light node) the likelihood of false positives can be sufficiently
reduced such that block producers have no incentive to withhold the block data.

---
Title: Celestia.org Code of Conduct
URL: https://docs.celestia.org/learn/code-of-conduct.md
Source: app/learn/code-of-conduct/page.mdx
---

# Celestia.org Code of Conduct

## Our Pledge

We as Celestia.org members, contributors, and leaders pledge to make
participation in our community a harassment-free experience for everyone,
regardless of age, body size, visible or invisible disability, ethnicity,
sex characteristics, gender identity and expression, level of experience,
education, socio-economic status, nationality, personal appearance, race,
caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.

## Our Standards

Examples of behavior that contributes to a positive environment for our
community include:

- Demonstrating empathy and kindness toward other people
- Being respectful of differing opinions, viewpoints, and experiences
- Giving and gracefully accepting constructive feedback
- Accepting responsibility and apologizing to those affected by our mistakes,
  and learning from the experience
- Focusing on what is best not just for us as individuals, but for the overall
  community
- Contributing to conversations about Celestia’s technology and ecosystem

Examples of unacceptable behavior include:

- The use of sexualized language or imagery, and sexual attention or advances of
  any kind
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or email address,
  without their explicit permission
- Focusing on the prices of digital assets or tokens, or where they can be purchased
- Other conduct which could reasonably be considered inappropriate in a
  professional setting

## Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.

Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.

## Scope

This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at Celestia.org Discord.
All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the
reporter of any incident.

## Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:

### 1. Correction

**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.

**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.

### 2. Warning

**Community Impact**: A violation through a single incident or series of
actions.

**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or permanent
ban.

### 3. Temporary Ban

**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.

**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.

### 4. Permanent Ban

**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.

**Consequence**: A permanent ban from any sort of public interaction within the
community.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.1, available at
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].

Community Impact Guidelines were inspired by
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].

For answers to common questions about this code of conduct, see the FAQ at
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
[https://www.contributor-covenant.org/translations][translations].

[homepage]: https://www.contributor-covenant.org
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
[Mozilla CoC]: https://github.com/mozilla/diversity
[FAQ]: https://www.contributor-covenant.org/faq
[translations]: https://www.contributor-covenant.org/translations

---
Title: Using Hyperlane with Celestia
URL: https://docs.celestia.org/learn/features/bridging/hyperlane.md
Source: app/learn/features/bridging/hyperlane/page.mdx
---

# Using Hyperlane with Celestia

## Live bridge

- [Hyperlane Nexus UI](https://nexus.hyperlane.xyz/?origin=celestia&token=TIA&destination=base)

## Summary

[Hyperlane](https://hyperlane.xyz/) is a permissionless interoperability layer that lets blockchains send messages and trigger actions on one another. Along with [IBC](/learn/features/bridging/ibc), it is one of the standards used on Celestia for cross-chain asset transfers and messages.

You can use Hyperlane to bridge TIA between Celestia and other EVM-compatible chains, as well as send arbitrary cross-chain messages.

## How bridging works

```mermaid
flowchart LR

    %% --- Chain A ---
    subgraph ChainA["Chain A"]
        A_App["Application"]
        A_Mailbox["Mailbox Contract"]
        A_ISM["Interchain Security Module"]
    end

    %% --- Chain B ---
    subgraph ChainB["Chain B"]
        B_App["Application"]
        B_Mailbox["Mailbox Contract"]
        B_ISM["Interchain Security Module"]
    end

    %% Internal flows (Chain A)
    A_App --> A_Mailbox
    A_Mailbox --> A_ISM
    A_ISM -->|Verify Message| A_Mailbox

    %% Internal flows (Chain B)
    B_App --> B_Mailbox
    B_Mailbox --> B_ISM
    B_ISM -->|Verify Message| B_Mailbox

    %% Cross-chain relayer messages
    A_Mailbox <-->|Relayers<br/>Messages + Proofs| B_Mailbox
```

- **Mailbox** — the core contract on each chain that dispatches and processes messages.

- **Relayer** — an off-chain program that delivers messages and metadata between blockchains.

- **Interchain Security Module (ISM)** — a modular security component that verifies messages before they're processed on the destination chain.

**Bridging flow**

1. **Source chain** — the application sends a message to the Mailbox contract, which emits an event and stores a commitment.

2. **Relayer** — an offchain relayer observes the source chain, reads the message event, and fetches the necessary metadata and proofs.

3. **Relayer → destination** — the relayer submits the message plus metadata to the destination Mailbox contract.

4. **Destination chain** — the ISM verifies the message using the provided metadata (proofs, signatures, etc.), and if valid, the Mailbox delivers the message to the recipient application.

5. **Recipient application** — the destination application receives and processes the message (for example, mints tokens, executes a function call, etc.).

---
Title: Using IBC with Celestia
URL: https://docs.celestia.org/learn/features/bridging/ibc.md
Source: app/learn/features/bridging/ibc/page.mdx
---

# Using IBC with Celestia

## Live IBC channels

- [Mocha testnet](https://www.mintscan.io/celestia-testnet/relayers/)
- [Mainnet](https://www.mintscan.io/celestia/relayers/)

## Summary
[IBC (Inter-Blockchain Communication)](https://ibcprotocol.dev/) is a protocol for authenticated, permissionless message passing between blockchains. Along with [Hyperlane](/learn/features/bridging/hyperlane), it is one of the standards used on Celestia for cross-chain asset transfers and messages.

You can use IBC to bridge assets between Celestia-native chains along with other chains.

Celestia uses relayers to forward packets between chains. Relayers are processes that can be run by anyone which constantly scan for outbound packets on one chain and submits these packets alongside corresponding proofs on the destination chain. This doc covers using IBC to bridge assets; see also [how to run a relayer](/operate/data-availability/ibc-relayer). 

## How bridging works

```mermaid
flowchart LR

    %% --- Chain A ---
    subgraph ChainA["Chain A"]
        A_App["Application"]
        A_Router["Router (Core)"]
        A_Light["Light Client of Chain B"]
    end

    %% --- Chain B ---
    subgraph ChainB["Chain B"]
        B_App["Application"]
        B_Router["Router (Core)"]
        B_Light["Light Client of Chain A"]
    end

    %% Internal flows (Chain A)
    A_App --> A_Router
    A_Router --> A_Light
    A_Router -->|Verify Membership / Verify Non-Membership| A_Light

    %% Internal flows (Chain B)
    B_App --> B_Router
    B_Router --> B_Light
    B_Router -->|Verify Membership / Verify Non-Membership| B_Light

    %% Cross-chain relayer packets
    A_Router <-->|Relayers<br/>Data Packets| B_Router
```

- **Light client** — a lightweight representation of a destination chain that lives within the state machine of a source chain.

- **Relayer** — an off-chain program that facilitates communication between independent blockchains.

- **Router** — a component in the that connects two blockchains, handles packet routing between applications, and manages the verification of cross-chain data.

**Bridging flow**
1. **Source chain** — the source router (onchain module) escrows or burns the tokens, builds a packet (payload + seq + timeout), and stores a packet commitment (hash) in state.

2. **Relayer** — an offchain relayer observes the source, reads the packet and the packet-commitment, and fetches a proof of that commitment from the source chain.

3. **Relayer → destination** — the relayer submits the packet plus the commitment proof to the destination router.

4. **Destination chain** — the destination’s light client verifies the commitment proof and, if valid, the destination router processes the packet (for example mints or credits) and writes an acknowledgement commitment.

5. **Relayer → Source** — the relayer fetches the acknowledgement and submits the acknowledgement proof back to the source chain.

6. **Source chain** — the source’s light client verifies the acknowledgement proof and the source router finalizes the transfer (releases escrow or marks the packet complete); if the timeout elapsed first, the source router executes refund logic.

---
Title: Private Blockspace
URL: https://docs.celestia.org/learn/features/private-blockspace.md
Source: app/learn/features/private-blockspace/page.mdx
---

# Private Blockspace

Private Blockspace lets applications publish **encrypted state to Celestia** while still making it **publicly accountable**.

Networks can keep sensitive data—like balances, positions, liquidations, and routing logic—confidential, without pushing trust back onto offchain operators. Anyone can verify that encrypted data is **available and properly committed to**, while only authorized parties can decrypt the underlying contents.

Private Blockspace is built for systems where **privacy is required** and **verifiability is non-negotiable**.

## How it works

Private Blockspace is implemented as a lightweight **Private Blockspace Proxy** that sits between your application and Celestia’s data availability layer:

1. **Submit**: Your app sends blobs to the proxy. The proxy encrypts the data, generates a zkVM proof (**Verifiable Encryption**), and publishes the encrypted blob to Celestia.

2. **Retrieve**: Your app fetches blobs through the proxy. The proxy retrieves encrypted data from Celestia and attempts to decrypt it using the configured key material.

3. **Verify**: Anyone can verify that the encrypted data is available on Celestia and that protocol-defined commitments about the plaintext hold—without revealing the plaintext itself.

## Use cases

Private Blockspace is designed for applications that need private execution or private state while preserving public guarantees. Here are a few novel use cases it can be applied to:

- **Accountable offchain exchanges**: Keep exchange state private while making availability and commitments publicly verifiable.

- **Trust-minimized data marketplaces**: Sellers can publish verifiably encrypted data to Celestia so buyers can verify availability and integrity before payment—without relying on intermediaries.

## Get started

- [About Private Blockspace](/build/private-blockspace/about): Architecture and technical details
- [Quickstart guide](/build/private-blockspace/quickstart): Run it locally and submit encrypted blobs
- [Private Blockspace Proxy](https://github.com/celestiaorg/private-blockspace-proxy/): Source code and implementation details

---
Title: Overview of TIA
URL: https://docs.celestia.org/learn/TIA/overview.md
Source: app/learn/TIA/overview/page.mdx
---

# Overview of TIA

## TIA at a glance

| Property                | Details                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| Abbreviation            | TIA                                                                                              |
| Total supply at genesis | 1,000,000,000 TIA                                                                                |
| Inflation schedule      | 8% in the first year, decreasing 10% per year until reaching an inflation floor of 1.5% annually |
| Decimals                | 6                                                                                                |
| Conversion              | 1 uTIA = 1 TIA × 10⁻⁶                                                                            |

## Role of TIA

### Paying for blobspace

Celestia’s native asset, TIA, is an essential part of how developers build on
the first modular blockchain network. To use Celestia for data availability,
rollup developers submit PayForBlobs transactions on the network for a fee,
denominated in TIA.

### Bootstrapping new rollups

A core part of the Celestia vision is that deploying a blockchain should be as
easy as deploying a smart contract. In the modular era, developers no longer
need to issue a token to launch their own blockchain.

Similarly to ETH on Ethereum-based rollups, developers may opt to bootstrap
their chain quickly by using TIA as a gas token and currency, in addition to
paying for data availability. In this mode, developers can focus on creating
their application or execution layer, instead of issuing a token right away.

### Proof-of-stake

As a permissionless network built with Cosmos SDK, Celestia uses proof-of-stake
to secure its own consensus. Like in other Cosmos networks, any user can help
secure the network by delegating their TIA to a Celestia validator for a portion
of their validator’s staking rewards.

Learn [how proof-of-stake works in Cosmos](https://docs.cosmos.network/sdk/v0.53/build/modules/staking).

### Decentralised governance

TIA staking also allows the community to play a critical role in decentralised
governance over key parts of Celestia, such as voting on network parameters
through governance proposals, and governing the community pool, which receives
2% of block rewards.

Learn more about [Celestia’s decentralised governance model](/learn/TIA/staking-governance-supply#decentralised-governance).

### Denominations

#### TIA: display token

TIA is the [`DisplayDenom`](https://github.com/celestiaorg/celestia-app/blob/ada77509d7fdedf2a3e3400b720549365851454c/app/app.go#L110-L111)
that you will typically see in wallets and user interfaces.

#### utia: staking denomination

`utia` is the [`BondDenom`](https://github.com/celestiaorg/celestia-app/blob/ada77509d7fdedf2a3e3400b720549365851454c/pkg/appconsts/global_consts.go#L75-L76)
and stands for "micro TIA", with 1 TIA = 1,000,000 `utia`. This is the
native staking denomination.

In staking operations or transactions, if no denomination is specified, `utia`
is assumed.

#### microtia: staking denomination alias

`microtia` is the [`BondDenomAlias`](https://github.com/celestiaorg/celestia-app/blob/ada77509d7fdedf2a3e3400b720549365851454c/app/app.go#L108-L109),
an alias for `utia`.

---
Title: Paying for blobspace
URL: https://docs.celestia.org/learn/TIA/paying-for-blobspace.md
Source: app/learn/TIA/paying-for-blobspace/page.mdx
---

# Paying for blobspace

## PayForBlobs transactions

To publish data on Celestia, developers can submit `PayForBlobs` transactions. A
`PayForBlobs` transaction consists of the identity of the sender, the data to be
made available, the data size, the namespace, and a signature.

Each `PayForBlobs` transaction is split into two parts: the blob or blobs which
include the data to be made available along with the namespace, and the executable
payment transaction which includes a commitment to the data.

Both the blobs and executable payment transactions are put into the block within
the appropriate namespace. The block data is extended using erasure coding and then
Merkelized into a data root commitment included in the block header.

![Lifecycle of a celestia-app Transaction](/img/learn/tx-lifecycle.png)

See
[the detailed life cycle of a Celestia transaction](/learn/celestia-101/transaction-lifecycle).

Learn how to
[submit data to Celestia’s data availability layer](/learn/TIA/submit-data).

## Fee market overview

Celestia uses a standard gas-price prioritised mempool. This means that
transactions with higher fees will be prioritised by validators. Fees are
comprised of a flat fee per transaction and then a variable fee based on the
size of each blob in the transaction.

Understand how fees are calculated on Celestia in
[the overview on submitting PFB transactions](/learn/TIA/submit-data).

---
Title: Staking, governance, & supply
URL: https://docs.celestia.org/learn/TIA/staking-governance-supply.md
Source: app/learn/TIA/staking-governance-supply/page.mdx
---

# Staking, governance, & supply

## Proof-of-stake on Celestia

Celestia is a proof-of-stake blockchain based on CometBFT and the Cosmos SDK.
Celestia supports in-protocol delegation and will start with an initial
validator set of 100.

Staking TIA as a validator or delegator enables you to earn staking rewards from
the network. Validators charge a fee to delegators which gives them a percentage
of staking rewards.

Learn
[how proof of stake works on Cosmos SDK chains like Celestia](https://docs.cosmos.network/sdk/v0.53/build/modules/staking).

| Consensus mechanism  | Proof-of-stake |
| -------------------- | -------------- |
| Blockchain framework | Cosmos SDK     |
| Validator set size   | 100            |
| Delegation support   | Yes            |

Learn how to
[stake on your own at the community dashboards](/learn/TIA/staking).

## Inflation

TIA inflation started at 8% annually.

1. Initially, it was set to decrease by 10% every year until reaching a long-term issuance rate of 1.5%.

2. With the v4 Lotus upgrade ([CIP-29](https://cips.celestia.org/cip-029.html)) in July 2025, the inflation rate dropped from ~7.2% to ~5.0% and was set to continue decreasing by 6.7% every year until it stabilized at 1.5%.

3. With the v6 ([CIP-41](https://cips.celestia.org/cip-041.html#inflation-schedule-over-time)) upgrade in November 2025, the inflation rate again dropped to ~2.5% and will continue to decrease by 6.7% every year until it stabilizes at 1.5%.

The diagram below illustrates both the initial inflation rates and those after the v6 upgrade.

![inflation diagram](/img/learn/TIA_inflation_post-cip41.jpg)

For an in-depth understanding, refer to
[ADR019](https://github.com/celestiaorg/celestia-app/blob/main/docs/architecture/adr-019-strict-inflation-schedule.md).

## Decentralised governance

### Network parameters

TIA holders (not just stakers) can propose and vote on governance proposals to
change a subset of network parameters. To learn more, see a
[complete list of both the changeable and non-changeable parameters and their values](https://celestiaorg.github.io/celestia-app/parameters_v6.html).
Additionally, learn how to
[submit and vote on governance proposals](/operate/consensus-validators/cli-reference#governance).

### Community pool

Starting at genesis, Celestia’s
[community pool](https://docs.cosmos.network/sdk/v0.53/build/modules/distribution)
receives 2% of all Celestia block rewards. TIA stakers may vote to fund
ecosystem initiatives as in many other Cosmos SDK chains.

Learn how to
[submit a governance proposal to spend community pool funds](/operate/consensus-validators/cli-reference#community-pool).

## TIA allocation at genesis

Celestia will have a total supply of 1,000,000,000 TIA at genesis,
split across five categories described in the chart and table below.

![allocation diagram](/img/learn/Celestia_TIA_Allocation_at_Genesis.png)

| Category                  | Description                                                                                                                                                                                                                                   | %      |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| Public Allocation         | Genesis Drop and Incentivized Testnet: 7.41%<br/>Future initiatives: 12.59%                                                                                                                                                                   | 20.00% |
| R&D & Ecosystem           | Tokens allocated to the Celestia Foundation and core devs for research, development, and ecosystem initiatives including:<br/>- Protocol maintenance and development<br/>- Programs for rollup developers, infrastructure, and node operators | 26.79% |
| Early Backers: Series A&B | Early supporters of Celestia                                                                                                                                                                                                                  | 19.67% |
| Early Backers: Seed       | Early supporters of Celestia                                                                                                                                                                                                                  | 15.90% |
| Initial Core Contributors | Members of Celestia Labs, the first core contributor to Celestia                                                                                                                                                                              | 17.64% |

### Unlocks

Celestia’s 1 billion TIA supply at genesis will be subject to several different
unlock schedules. All tokens, locked or unlocked, may be staked, but staking
rewards are unlocked upon receipt and will add to the circulating supply.

**Circulating supply** is defined as the amount of TIA tokens in general
circulation without onchain transfer restrictions.

**Available supply** is defined as the amount of TIA tokens that are either part
of the circulating supply or are unlocked but subject to some form of governance
to determine when the tokens are allocated. This includes the unlocked portion
of the R&D & Ecosystem tokens and the tokens set aside for future initiatives.

_The definitions for circulating and available supply were adapted from
[Optimism’s definitions](https://community.optimism.io/docs/governance/allocations/#token-distribution-details)._

![supply diagram](/img/learn/Celestia_TIA_Available_Supply.png)

Unlock schedule by category is described in the table below.

_Note: Due to 2024 being a leap year, the yearly unlock intervals will occur on October 30th of each year. For example, unlocks at year 1 will occur on October 30, 2024._

| Category                  | Unlock Schedule                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| Public Allocation         | Fully unlocked at launch.                                                                   |
| R&D & Ecosystem           | 25.00% unlocked at launch.<br/>Remaining 75.00% unlocks continuously from year 1 to year 4. |
| Initial Core Contributors | 33.33% unlocked at year 1.<br/>Remaining 66.67% unlocks continuously from year 1 to year 3. |
| Early Backers: Seed       | 33.33% unlocked at year 1.<br/>Remaining 66.67% unlocks continuously from year 1 to year 2. |
| Early Backers: Series A&B | 33.33% unlocked at year 1.<br/>Remaining 66.67% unlocks continuously from year 1 to year 2. |

---
Title: Staking on Celestia
URL: https://docs.celestia.org/learn/TIA/staking.md
Source: app/learn/TIA/staking/page.mdx
---

# Staking on Celestia

Engage with the Celestia network at a deeper level through staking. An
essential mechanism to a proof-of-stake network, users can secure the
network by delegating to a validator and receive a share of its
staking rewards.

As of [CIP-30](https://cips.celestia.org/cip-030.html), when delegators modify their staking positions (_e.g._, redelegate or undelegate), the distribution no longer auto-claim rewards on delegation-share changes. Instead, rewards are accrued until the user calls `MsgWithdrawDelegatorReward`.

## Mainnet Beta

Currently, the following staking interfaces exist for the
Mainnet Beta.

Just connect your wallet to get started!

- [https://wallet.keplr.app/chains/celestia?tab=staking](https://wallet.keplr.app/chains/celestia?tab=staking)
- [https://alphab.ai/s/m/celestia/](https://alphab.ai/s/m/celestia/)

## Mocha testnet

Currently, the following staking interfaces exist for the
Mocha testnet.

Just connect your wallet to get started!

- [https://testnet.keplr.app/chains/celestia-mocha-testnet](https://testnet.keplr.app/chains/celestia-mocha-testnet)
- [https://explorer.kjnodes.com/celestia-testnet](https://explorer.kjnodes.com/celestia-testnet)
- [https://alphab.ai/s/t/celestia-mocha-4/](https://alphab.ai/s/t/celestia-mocha-4/)

---
Title: Submitting data blobs to Celestia
URL: https://docs.celestia.org/learn/TIA/submit-data.md
Source: app/learn/TIA/submit-data/page.mdx
---

# Submitting data blobs to Celestia

To submit data to Celestia, users submit blob transactions (`BlobTx`). Blob
transactions contain two components, a standard Cosmos-SDK transaction called
`MsgPayForBlobs` and one or more `Blob`s of data.

## Maximum blob size

As of **v6**, the maximum transaction size on all networks is **8 MiB (8,388,608 bytes)**. This cap applies to the _entire_ transaction—including the PFB, all blobs, and overhead—so the maximum total blob size is slightly smaller than 8 MiB.

The _exact_ maximum total blob size in a transaction depends on:

- the number of shares available after accounting for the PFB transaction,
- the share version and layout rules,
- and the fact that the **first sparse share has 478 bytes**, while **all subsequent sparse shares have 482 bytes**.

The current max square size on Mocha and Mainnet Beta is 32 MiB.

Under v6 and future upgrades, networks will use larger square sizes, so the absolute maximum blob capacity per transaction will increase correspondingly—up to the global **8 MiB transaction size limit**, which is now the binding constraint.

See the [Mainnet Beta page under “Transaction size limit”](/operate/networks/mainnet-beta#transaction-size-limit) for details.

## Fee market and mempool

Celestia makes use of a standard gas-priced prioritized mempool. By default,
transactions with gas prices higher than that of other transactions in the mempool
will be prioritized by validators.

### Fee estimation

Celestia-node provides flexible fee estimation options for submitting transactions:

1. **Default estimation**: By default, fee estimation relies on the consensus node to which the node is connected.

2. **Third-party estimation**: Users can specify a separate endpoint for fee estimation using the `--core.estimator.address` flag in the CLI. This allows using a dedicated service for fee estimation.

3. **Maximum gas price**: Users can set a maximum gas price they're willing to pay for transactions using the `--max.gas.price` flag. If the estimated gas price exceeds this maximum, the transaction will not be submitted. The default maximum is set to 100 times the minimum gas price (0.2 TIA).

- PayForBlobs (PFB) transactions: Only the gas price (cost per unit) is dynamically estimated. The gas usage (number of units) uses a fixed calculation method.
- All other transactions: Both gas price and gas usage are dynamically estimated.

When using third-party estimation, the consensus endpoint must be running celestia-app v3.8.1 or higher.

### Fees and gas limits

As of version v1.0.0 of the application (celestia-app), there is no protocol
enforced minimum fee (similar to EIP-1559 in Ethereum). Instead, each
consensus node running a mempool uses a locally configured gas price threshold
that must be met in order for that node to accept a transaction, either directly
from a user or gossiped from another node, into its mempool.

As of version v1.0.0 of the application (celestia-app), gas is not refunded.
Instead, transaction fees are deducted by a flat fee, originally specified by
the user in their tx (where fees = gasLimit \* gasPrice). This means that
users should use an accurate gas limit value if they do not wish to overpay.

Under the hood, fees are currently handled by specifying and deducting a flat
fee. However gas price is often specified by users instead of calculating the
flat fee from the gas used and the gas price. Since the state machine does not
refund users for unused gas, gas price is calculated by dividing the total fee
by the gas limit.

#### Estimating PFB gas

Generally, the gas used by a PFB transaction involves a static fixed cost and
a dynamic cost based on the size of each blob in the transaction.

For a general use case of a normal account submitting a PFB, the static
costs can be treated as such. However, due to the description above of how gas
works in the Cosmos-SDK this is not always the case. Notably, if a
vesting account or the `feegrant` modules are used, then these static costs change.

The fixed cost is an approximation of the gas consumed by operations outside
the function `GasToConsume` (for example, signature verification, tx size, read
access to accounts), which has a default value of 65,000 gas.

The first transaction sent by an account (sequence number == 0) has an
additional one time gas cost of 10,000 gas. If this is the case, this
should be accounted for.

Each blob in the PFB contributes to the total gas cost based on its size. The
function `GasToConsume` calculates the total gas consumed by all the blobs
involved in a PFB, where each blob's gas cost is computed by first determining
how many shares are needed to store the blob size. Then, it computes the product
of the number of shares, the number of bytes per share, and the `gasPerByte`
parameter. Finally, it adds a static amount per blob.

The [`blob.GasPerBlobByte`](https://github.com/celestiaorg/celestia-app/blob/29906a468910184f221b42be0a15898722a2b08f/specs/src/parameters_v6.md?plain=1#L33)
and [`auth.TxSizeCostPerByte`](https://github.com/celestiaorg/celestia-app/blob/29906a468910184f221b42be0a15898722a2b08f/specs/src/parameters_v6.md?plain=1#L31)
are parameters that
could potentially be adjusted through the system's governance mechanisms. Hence,
actual costs may vary depending on the current state of these parameters.

#### Gas fee calculation

The total fee for a transaction is calculated as the product of the gas limit
for the transaction and the gas price set by the user:

$$
\text{Total Fee} = \text{Gas Limit} \times \text{Gas Price}
$$

The gas limit for a transaction is the maximum amount of gas that a user is
willing to spend on a transaction. It is determined by both a static
fixed cost (FC) and a variable dynamic cost based on the size of each blob involved
in the transaction:

$$
\text{Gas Limit} = FC + \sum_{i=1}^{n} \text{SSN}(B_i) \times SS \times GCPBB
$$

Where:

- $FC$ = Fixed Cost, is a static value (65,000 gas)
- $\sum_{i=1}^{n} \text{SSN}(B_i)$ = SparseSharesNeeded for the ith Blob, is the number of shares needed for the ith blob in the transaction
- $SS$ = Share Size, is the size of each share
- $GCPBB$ = Gas Cost Per Blob Byte, is a parameter that could potentially be adjusted through the system's governance mechanisms.

The gas fee is set by the user when they submit a transaction. The fee is often
specified by users directly. The total cost for the transaction is then
calculated as the product of the estimated gas limit and the gas price.
Since the state machine does not refund users for unused gas,
it's important for users to estimate the gas limit accurately to
avoid overpaying.

For more details on how gas is calculated per blob, refer to the
[`PayForBlobs` function](https://github.com/celestiaorg/celestia-app/blob/32d247971386c1944d44bec1faeb000b1ff1dd51/x/blob/keeper/keeper.go#L53)
that consumes gas based on the blob sizes. This function uses the
[`GasToConsume` function](https://github.com/celestiaorg/celestia-app/blob/32d247971386c1944d44bec1faeb000b1ff1dd51/x/blob/types/payforblob.go#L157-L167)
to calculate the extra gas charged to pay for a set of blobs in a `MsgPayForBlobs`
transaction. This function calculates the total shares used by all blobs and
multiplies it by the `ShareSize` and `gasPerByte` to get the total gas to consume.

For estimating the total gas required for a set of blobs, refer to the
[`EstimateGas` function](https://github.com/celestiaorg/celestia-app/blob/32d247971386c1944d44bec1faeb000b1ff1dd51/x/blob/types/payforblob.go#L169-L181).
This function estimates the gas based on a linear model that is dependent on
the governance parameters: `gasPerByte` and `txSizeCost`. It assumes other
variables are constant, including the assumption that the `MsgPayForBlobs`
is the only message in the transaction. The `DefaultEstimateGas` function
runs `EstimateGas` with the system defaults.

#### Estimating gas programmatically

Users can estimate an efficient gas limit by using this function:

```go
import (
    blobtypes "github.com/celestiaorg/celestia-app/x/blob/types"
)
gasLimit := blobtypes.DefaultEstimateGas([]uint32{uint32(sizeOfDataInBytes)})
```

If using a celestia-node light client, then this function is automatically
called for you when submitting a blob. This function works by breaking down the
components of calculating gas for a blob transaction. These components consist
of a flat costs for all PFBs, the size of each blob and how many shares each
uses and the parameter for gas used per byte. More information about how gas is
used can be found in the [gas
specs](https://github.com/celestiaorg/celestia-app/blob/d17e231ae3a0150b50a1854f3e9a268c34502b6b/specs/src/specs/resource_pricing.md)
and the exact formula can be found in the [blob
module](https://github.com/celestiaorg/celestia-app/blob/d17e231ae3a0150b50a1854f3e9a268c34502b6b/x/blob/types/payforblob.go#L157-L181).

## Transaction submission strategies

Celestia-node offers three transaction submission modes, controlled by the `TxWorkerAccounts` configuration parameter in your node's
state config in `config.toml`. Each mode has different throughput characteristics and ordering guarantees.

### Default behavior (TxWorkerAccounts = 0)

By default, `TxWorkerAccounts` is set to `0`, which means queued submission is disabled. All PayForBlobs transactions are submitted
immediately to the mempool without waiting for confirmations. This is the same behavior as versions before queued submission was introduced.

The mempool maintains a fork of the canonical state each block, updating the sequence number (nonce) for each account that submits a
transaction. If you wish to submit multiple transactions from the same account in quick succession, you must specify the nonce
manually. Otherwise, subsequent transactions will not be accepted until the first transaction is reaped from the mempool (included in
a block) or dropped after timing out.

By default, nodes will drop a transaction if it does not get included in 12 blocks (roughly 72 seconds). At this point, you must
resubmit your transaction if you want it to eventually be included.

As of v1.0.0 of celestia-app, you cannot replace an existing transaction with a higher-fee version. You must wait 5 blocks from the
original submission time and then resubmit the transaction.

### Synchronous submission (TxWorkerAccounts = 1)

Setting `TxWorkerAccounts` to `1` enables synchronous, queued transaction submission:

```toml
[State]
  TxWorkerAccounts = 1
```

Characteristics:

- Each transaction queues until the previous one is confirmed
- Preserves strict ordering of transactions
- Avoids sequence mismatch errors
- Throughput: approximately 1 PayForBlobs transaction every other block

If you specify an account other than the default account in TxConfig, the queue is bypassed and transactions enter the mempool
directly without waiting for confirmations.

### Parallel transaction submission (TxWorkerAccounts > 1)

This feature is currently available on Mocha testnet.

For high-throughput applications that do not require sequential transaction ordering, you can enable parallel transaction submission
by setting `TxWorkerAccounts` to a value > 1:

```toml
[State]
  DefaultKeyName = "my_celes_key"
  DefaultBackendName = "test"
  TxWorkerAccounts = 8
```

#### How it works:

`TxWorkerAccounts` defines how many parallel lanes the node will initialize for submitting transactions. These lanes are implemented as
subaccounts that are automatically:

1. Created and derived from your default account
2. Funded by your default account
3. Added to your node's keyring

This bypasses account sequence limits and enables significantly higher throughput.

Example: TxWorkerAccounts = 8 creates 7 subaccounts plus your 1 default account, allowing at least 8 PayForBlobs transactions per
block.

#### Important considerations

Parallel submission is not suitable for implementations that require sequential transaction ordering. Only use this mode for
unordered transaction workflows where your system requires a single signer, a.k.a. authored blobs.

#### Key points to understand:

- Account opacity: You will not know which subaccount signed which blob. Subaccounts are managed automatically by the node.
- Default account only: Parallel submission only works with your node's default account. If you specify a different account in
  TxConfig, parallel submission is bypassed.
- Blob retrieval: Since you don't know which account submitted each blob, retrieve your blobs using namespace, height, and commitment.

### Retrieving blobs submitted via parallel lanes

When using parallel submission, retrieve your blobs using the following RPC methods from the [Node API `blob` section](/build/rpc/node-api/):

- [`blob.Get`](/build/rpc/node-api/#blob) - Get blob by namespace and commitment
- [`blob.GetProof`](/build/rpc/node-api/#blob) - Get inclusion proof by height, namespace, and commitment
- [`blob.GetCommitmentProof`](/build/rpc/node-api/#blob) - Get commitment proof by height, namespace, and share commitment

Example using blob.Get:

```bash
celestia blob get <height> <namespace> <commitment>
```

You should store the namespace, height, and commitment from your submission response to retrieve blobs later.

## API

Users can currently create and submit `BlobTx`s in six ways.

### The celestia-app consensus node CLI

```bash
celestia-appd tx blob PayForBlobs <hex-encoded namespace> <hex-encoded data> [flags]
```

### The celestia-node light node CLI

Using `blob.Submit`:

```bash
celestia blob submit <hex_namespace> <data> [flags]
```

For hex-encoded data, include the `0x` prefix: `0x676d` submits the text `gm`.
On builds containing the blob submission fix in celestia-node #5262, data
without that prefix is literal text, even if it looks like hex: `cafe` submits
`cafe`. Use explicit `0x`-prefixed hex data for compatibility with earlier builds.
The namespace remains hex-encoded.

Available flags:

- `--core.estimator.address string`: Specifies the endpoint of the third-party service for gas price and gas estimation. Format: `<address>:<port>`. If not provided, the default connection to the consensus node will be used.
- `--max.gas.price`: Sets the maximum gas price you're willing to pay for the transaction. If the estimated gas price exceeds this value, the transaction will not be submitted. Default is 0.2 TIA (100x the minimum gas price).

Learn more in the [light node tutorial](/operate/data-availability/light-node/quickstart).

### The celestia-node API golang client

See the [golang client tutorial](/build/post-retrieve-blob/client/go).

### The celestia-node API Rust client

See the [Rust client tutorial](/build/post-retrieve-blob/client/rust).

### RPC to a celestia-node

With the JSON-RPC API, encode blob `data` as base64, rather than using the
CLI data argument format. For example, the text `gm` is `"Z20="` in a
JSON-RPC blob's `data` field. The CLI prefix change does not change this encoding.

Submit data using the following methods:

- [`blob.Submit`](/build/rpc/node-api/#blob.Submit)
- [`state.SubmitPayForBlob`](/build/rpc/node-api/#state.SubmitPayForBlob)

Learn more in the [Node API docs](/build/rpc/node-api/).

### Post a blob directly from Celenium

Celenium provides a user-friendly interface to view and interact with data on Celestia,
and allows for submitting blobs directly from the explorer interface.

To submit a blob from Celenium, follow these steps:

1. Navigate to the [Celenium explorer](https://celenium.io) and connect your wallet.
2. Click on the terminal button in the top right corner of the screen and select the "Submit data blob" option.
3. Next, ensure the file you are submitting is in a supported format and upload it.
4. In the "Namespace" field, input the namespace you want to use for the blob in hex format.
5. Finally, click on the "Continue" button to submit your blob, then approve the transaction in your wallet.

Once the blob is submitted, you will see its hash on the screen.
You can also use Celenium’s search bar to search for the blob's hash and view its details.

---
Title: Helpful CLI commands
URL: https://docs.celestia.org/operate/consensus-validators/cli-reference.md
Source: app/operate/consensus-validators/cli-reference/page.mdx
---

# Helpful CLI commands

View all options:

```console
$ celestia-appd --help
Start celestia-app

Usage:
  celestia-appd [command]

Available Commands:
  add-genesis-account Add a genesis account to genesis.json
  collect-gentxs      Collect genesis txs and output a genesis.json file
  config              Create or query an application CLI configuration file
  debug               Tool for helping with debugging your application
  export              Export state to JSON
  gentx               Generate a genesis tx carrying a self delegation
  help                Help about any command
  init                Initialize private validator, p2p, genesis,
  and application configuration files
  keys                Manage your application's keys
  migrate             Migrate genesis to a specified target version
  query               Querying subcommands
  rollback            rollback cosmos-sdk and tendermint state by one height
  start               Run the full node
  status              Query remote node for status
  tendermint          Tendermint subcommands
  tx                  Transactions subcommands
  validate-genesis    validates the genesis file at the default
  location or at the location passed as an arg
  version             Print the application binary version information
```

## Updating node configuration

The `celestia-appd update-config` command is deprecated as of v9. Required
configuration values are now enforced by the binary at startup, so do not add
this command to new node initialisation or upgrade procedures. It currently
prints a deprecation warning and will be removed in a future release.

See the [celestia-app v9 release notes](https://github.com/celestiaorg/celestia-app/blob/v9.0.4/docs/release-notes/release-notes.md#update-config-command-deprecated)
for details.

## Creating a wallet

```sh
celestia-appd config keyring-backend <backend>
```

`keyring-backend` configures the keyring's backend, where the keys are stored.

Options are: `os|file|kwallet|pass|test|memory`.

`test` keeps the key unencrypted on disk with no password, so reserve it for
local development and testnets. See
[create a wallet with celestia-app](/operate/keys-wallets/celestia-app-wallet)
for a comparison of the backends.

You can learn more on the [Cosmos documentation](https://docs.cosmos.network/sdk/v0.53/user/run-node/keyring)
or [Go Package documentation](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/crypto/keyring).

## Key management

```sh
# listing keys
celestia-appd keys list

# adding keys
celestia-appd keys add <KEY_NAME>

# deleting keys
celestia-appd keys delete <KEY_NAME>

# renaming keys
celestia-appd keys rename <CURRENT_KEY_NAME> <NEW_KEY_NAME>
```

### Importing and exporting keys

Import an encrypted and ASCII-armored private key into the local keybase.

```sh
celestia-appd keys import <KEY_NAME> <KEY_FILE>
```

Example usage:

```sh
celestia-appd keys import amanda ./keyfile.txt
```

Export a private key from the local keyring in encrypted and ASCII-armored format:

```sh
celestia-appd keys export <KEY_NAME>

# you will then be prompted to set a password for the encrypted private key:
Enter passphrase to encrypt the exported key:
```

After you set a password, your encrypted key will be displayed.

## Querying subcommands

Usage:

```sh
celestia-appd query <FLAGS> | <COMMAND>

# alias q
celestia-appd q <FLAGS> | <COMMAND>
```

To see all options:

```sh
celestia-appd q --help
```

## Token management

Get token balances:

```sh
celestia-appd q bank balances <ADDRESS> --node <NODE_URI>
```

Example usage:

```sh
celestia-appd q bank balances celestia1czpgn3hdh9sodm06d5qk23xzgpq2uyc8ggdqgw \
    --node https://public-endpoint.celestia-mocha.quiknode.pro
```

Transfer tokens from one wallet to another:

```sh
celestia-appd tx bank send <FROM_ADDRESS> <TO_ADDRESS> \
    <amount> --node <NODE_URI> --chain-id <CHAIN_ID>
```

Example usage:

```sh
celestia-appd tx bank send <FROM_ADDRESS> <TO_ADDRESS> \
    19000000utia --node https://public-endpoint.celestia-mocha.quiknode.pro \
    --chain-id mocha-5
```

To see options:

```sh
celestia-appd tx bank send --help
```

## Governance

Governance proposals on Celestia are limited as there are no text proposals,
upgrades occur via social consensus, and some params are not modifiable.
However, one can submit governance proposals to change certain parameters and
spend community funds. More detailed information on this topic can be found in
the [cosmos-sdk documentation for submitting
proposals](https://docs.cosmos.network/sdk/v0.53/build/modules/gov),
the list of [parameter defaults in the
specs](https://github.com/celestiaorg/celestia-app/blob/0012451c4dc118767dd59bc8d341878b7a7cacdf/specs/src/specs/params.md),
and the [x/paramfilter module
specs](https://github.com/celestiaorg/celestia-app/tree/1570b3d4937ac4418b3ecf77365d47c5f094ad8f/x/paramfilter).

Viewing the available proposals can be done with the query command:

```sh
celestia-appd q gov proposals
```

There are four options when voting "yes", "no", "no_with_veto" and "abstain".
The "no_with_veto" vote is different from the "no" vote in that the submitter of
the proposer's deposit will get burned, and a minority of stake (1/3) can stop a
proposal that might otherwise pass quorum. You can use those options to vote on
a governance proposal with the following command:

```sh
celestia-appd tx gov vote <proposal id> <option> \
    --from <wallet> --chain-id <chain-id>
```

To submit a proposal, there are two commands that can be used. The first is the
legacy command, which is the recommended way to submit a proposal.

To change the max validators to 105, one would first save this JSON file:

```json
{
  "title": "Staking Param Change",
  "description": "Update max validators",
  "changes": [
    {
      "subspace": "staking",
      "key": "MaxValidators",
      "value": 105
    }
  ],
  "deposit": "1000000000utia"
}
```

Then you can submit the proposal with:

```sh
celestia-appd tx gov submit-legacy-proposal \
    parameter-change <path to json file> \
    --from <wallet> --chain-id <chain-id>
```

If we want to use the newer api, we can submit a proposal by first saving the
`sdk.Msg` proposal in the json encoded format to a json.

```json
{
  "messages": [
    {
      "@type": "/cosmos.gov.v1beta1.MsgSubmitProposal",
      "content": {
        "@type": "/cosmos.params.v1beta1.ParameterChangeProposal",
        "title": "title",
        "description": "description",
        "changes": [
          { "subspace": "staking", "key": "MaxValidators", "value": "103" }
        ]
      },
      "initial_deposit": [{ "denom": "utia", "amount": "1000000000" }],
      "proposer": "celestia10d07y265gmmuvt4z0w9aw880jnsr700jtgz4v7"
    }
  ]
}
```

Note that the proposer here must be the gov module
account. That account can be found by using this command:

```sh
celestia-appd q auth module-account gov
```

Then one can submit the proposal with:

```sh
celestia-appd tx gov submit-proposal <path to json file> \
    --from <wallet> --chain-id <chain-id>
```

### Community Pool

A percentage of the block rewards are allocated to the community pool. Community
members can submit governance proposals to spend the community pool funds, and
token holders can vote on these proposals. The proposals to spend are arbitrary
in nature in that they can only contain text and some address to send funds to.
To view the community pool balance, use the following command:

```sh
celestia-appd q distribution community-pool
```

To submit a proposal to spend the community pool funds, first create a JSON file
that contains the proposal.

```json
{
  "title": "Community Pool Spend",
  "description": "Fund an open source project.",
  "recipient": "celestia17adsjkuecgjheugrdrwdqv9uh3qkrfmj9xzawx",
  "amount": "100000000000utia",
  "deposit": "1000000000utia"
}
```

The json file can be submitted using a similar proposal submission command as above:

```sh
celestia-appd tx gov submit-legacy-proposal \
    community-pool-spend <path to json file> \
    --from <wallet>
```

## Claim validator rewards

You can claim your validator rewards with
the following command:

```sh
celestia-appd tx distribution withdraw-rewards <validator valoper> \
    --commission --from=<validator wallet> --chain-id <chain-id> \
    --gas auto -y
```

## Delegate & undelegate tokens

You can `delegate` your tokens to a validator
with the following command:

```sh
celestia-appd tx staking delegate <validator valoper> <amount>\
    --from <wallet> --chain-id <chain-id>
```

You can undelegate tokens to a validator
with the `unbond` command:

```sh
celestia-appd tx staking unbond <validator valoper> <amount>\
    --from <wallet> --chain-id <chain-id>
```

## Unjailing the validator

You can unjail your validator with the
following command:

```sh
celestia-appd tx slashing unjail --from <validator wallet>\
    --chain-id <chain-id> --gas auto -y
```

## How to export logs with SystemD

You can export your logs if you are running
a SystemD service with the following command:

```sh
sudo journalctl -u <your systemd service> -S yesterday > node_logs.txt
sudo journalctl -u <your systemd service> -S today > node_logs.txt
# This command outputs the last 1 million lines!
sudo journalctl -u <your systemd service> -n 1000000 > node_logs.txt
```

## Signing genesis for a new network

You can first run the following commands:

```sh
VALIDATOR_NAME=validator1
CHAIN_ID=testnet
celestia-appd init $VALIDATOR_NAME --chain-id $CHAIN_ID
MONIKER=validator_name
```

Next create a wallet:

```sh
KEY_NAME=validator
celestia-appd keys add $KEY_NAME
```

Create or assign an EVM address:

```sh
EVM_ADDRESS=<EVM_ADDRESS>
```

Then add genesis account:

```sh
CELES_AMOUNT="5000100000000utia"
celestia-appd genesis add-genesis-account $KEY_NAME $CELES_AMOUNT
```

Then generate your gentx:

```sh
STAKING_AMOUNT=5000000000000utia
celestia-appd gentx $KEY_NAME $STAKING_AMOUNT --chain-id $CHAIN_ID \
    --pubkey=$(celestia-appd tendermint show-validator) \
    --moniker=$MONIKER \
    --commission-rate=0.1 \
    --commission-max-rate=0.2 \
    --commission-max-change-rate=0.01 \
    --min-self-delegation=1 \
    --evm-address=$EVM_ADDRESS
```

You can then share your gentx JSON file on
[the networks repo](https://github.com/celestiaorg/networks)
in the respective network directory you are participating in.

---
Title: Consensus node
URL: https://docs.celestia.org/operate/consensus-validators/consensus-node.md
Source: app/operate/consensus-validators/consensus-node/page.mdx
---

# Consensus node

This guide covers how to set up a consensus node on Celestia.
Consensus nodes allow you to sync the entire blockchain history in the Celestia
consensus layer.

![consensus node](/img/nodes/consensus-node.jpg)

## Minimum hardware requirements

See [hardware requirements](/operate/getting-started/hardware-requirements).

## Set up a consensus node

The following tutorial is done on an Ubuntu Linux 24.04 (LTS) x64
instance machine.

### Set up the dependencies

Follow the instructions on [installing dependencies](/operate/getting-started/environment-setup).

### Install celestia-app

Follow the tutorial on [installing `celestia-app`](/operate/consensus-validators/install-celestia-app).

### Set up the P2P networks

To initialize the network, pick a "node-name" that describes your
node. Keep in mind that this might change if a new testnet is deployed.

**Mainnet Beta**

```bash
celestia-appd init "node-name" --chain-id celestia
```

**Mocha**

```bash
celestia-appd init "node-name" --chain-id mocha-5
```

Download the `genesis.json` file:

**Mainnet Beta**

```bash
celestia-appd download-genesis celestia
```

**Mocha**

```bash
celestia-appd download-genesis mocha-5
```

Set seeds in the `$HOME/.celestia-app/config/config.toml` file:

**Mainnet Beta**

```bash
SEEDS=$(curl -sL https://raw.githubusercontent.com/celestiaorg/networks/master/celestia/seeds.txt | tr '\n' ',')
echo $SEEDS
sed -i.bak -e "s/^seeds *=.*/seeds = \"$SEEDS\"/" $HOME/.celestia-app/config/config.toml
```

**Mocha**

```bash
SEEDS=$(curl -sL https://raw.githubusercontent.com/celestiaorg/networks/main/mocha-5/seeds.txt | tr '\n' ',')
echo $SEEDS
sed -i.bak -e "s/^seeds *=.*/seeds = \"$SEEDS\"/" $HOME/.celestia-app/config/config.toml
```

#### Optional: Set persistent peers

You can set persistent peers in your `config.toml` file. If you set persistent peers, your node will **always** try to connect to these peers. This is useful when running a local devnet, for example, when you would always want to connect to the same local nodes in your devnet. In production, setting persistent peers is advised only if you are running a [sentry node](https://hub.cosmos.network/main/validators/security.html#sentry-nodes-ddos-protection).

You can get the persistent peers from the [@cosmos/chain-registry](https://github.com/cosmos/chain-registry) repository (for Mainnet Beta) or [@celestiaorg/networks repository](https://github.com/celestiaorg/networks) repo (for Mocha) with the following commands:

**Mainnet Beta**

```bash
PERSISTENT_PEERS=$(curl -s https://raw.githubusercontent.com/cosmos/chain-registry/master/celestia/chain.json | jq -r '.peers.persistent_peers[].address' | tr '\n' ',' | sed 's/,$/\n/')
echo $PERSISTENT_PEERS
sed -i.bak -e "s/^persistent_peers *=.*/persistent_peers = \"$PERSISTENT_PEERS\"/" $HOME/.celestia-app/config/config.toml
```

**Mocha**

```bash
PERSISTENT_PEERS=$(curl -sL https://raw.githubusercontent.com/celestiaorg/networks/main/mocha-5/peers.txt | tr '\n' ',')
echo $PERSISTENT_PEERS
sed -i.bak -e "s/^persistent_peers *=.*/persistent_peers = \"$PERSISTENT_PEERS\"/" $HOME/.celestia-app/config/config.toml
```

## Storage and pruning configurations

### Database backend

celestia-app v9 and later use PebbleDB by default for new nodes. Before
changing an existing node's `db_backend` from `"goleveldb"` to `"pebbledb"`,
stop the node and use the
[`migrate-db` tool](https://github.com/celestiaorg/celestia-app/tree/v9.x/tools/migrate-db)
to migrate its databases.

### Optional: Connect a consensus node to a bridge node

If your consensus node is being connected to a celestia-node bridge node,
you will need to enable transaction indexing and retain all block
data. This can be achieved with the following settings in your `config.toml`.

#### Enable transaction indexing

There is currently no way of entirely disabling indexing. Set the `indexer`
to `"null"` in your `config.toml`:

```toml
indexer = "null"
```

The `null` indexer is a lightweight indexer that is sufficient for bridge
nodes.

#### Retain all block data

In your `app.toml`, explicitly set `min-retain-blocks` to `0`:

```toml
min-retain-blocks = 0 # retain all block data
```

### Query transactions by hash

To query transactions using their hash, transaction
indexing must be turned on. Set the `indexer` to `"kv"` in your `config.toml`:

```toml
indexer = "kv"
```

### Optional: Access historical state

If you want to query the historical state — for example, you might want
to know the balance of a Celestia wallet at a given height in the past —
you should run an archive node. In your `app.toml`, set `pruning = "nothing"`
to retain application state and `min-retain-blocks = 0` to retain all block
data. Note that this configuration is resource-intensive and will require
significant storage:

```toml
pruning = "nothing"
min-retain-blocks = 0
```

`min-retain-blocks` defaults to `0`. Any non-zero value enables block pruning,
so archival operators must keep the value at `0`. Changing the value from `0`
to a non-zero value starts pruning the existing backlog when the node restarts
and can temporarily increase sync time.

### Save on storage requirements

If you want to save on storage requirements, consider using
`pruning = "everything"` in your `app.toml` to prune everything. If you
select `"everything"` or `"default"`, but still want to keep the block data,
you can do so by explicitly setting
`min-retain-blocks = 0` in your `app.toml`. A value of `0` for
`min-retain-blocks` will keep all block data. This will prune snapshots of
the state, but it will keep block data:

```toml
pruning = "everything"
min-retain-blocks = 0 # retain all block data
```

### Recommended block retention for validators

The default `min-retain-blocks` value is `3000`. For validators that do not
need to retain all block data, set `min-retain-blocks = 600000` in your
`app.toml`. This keeps a larger recent block history without retaining all
block data:

```toml
min-retain-blocks = 600000 # retain recent block data while pruning older blocks
```

## Sync types

| Sync mode  | Time     | Notes                                                                                                                                        |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Block sync | ~3 weeks | Downloads and executes all blocks from genesis to the tip                                                                                    |
| State sync | ~1 hour  | Downloads a snapshot of the state then downloads and executes all blocks after that snapshot to the tip.                                     |
| Quick sync | ~5 hours | Downloads the data directory from a node. Time depends on your download speed because the data being downloaded can exceed 1 TB for mainnet. |

### Option 1: Block sync

By default, a consensus node will sync using block sync; which will request, validate
and execute every block up to the head of the blockchain. This is the most secure
mechanism yet the slowest (taking up to weeks depending on the height of the blockchain).

Starting with celestia-app v9, `verify_data` defaults to `false` in the
`[blocksync]` section of `config.toml`. This skips re-running `ProcessProposal`
on historical blocks to improve block sync speed. Blocks are still verified by
their validator signatures, and normal validation resumes after the node enters
consensus mode. To restore the pre-v9 behaviour, set:

```toml
[blocksync]
verify_data = true
```

See the [celestia-app v9 release notes](https://github.com/celestiaorg/celestia-app/blob/v9.0.4/docs/release-notes/release-notes.md#block-sync-verify_data-default-changed-to-false)
for details.

There are two alternatives for quicker syncing.

### Option 2: State sync

State sync uses light client verification to verify state snapshots from peers
and then apply them. State sync relies on weak subjectivity; a trusted header
(specifically the hash and height) must be provided. This can be found by querying
a trusted RPC endpoint (/block). RPC endpoints are also required for retrieving
light blocks. These can be found in the docs here under the respective networks or
from [the chain-registry](https://github.com/cosmos/chain-registry).

#### State sync quick start scripts

If you are looking to quickly sync a consensus node, and do not need historical blocks,
you can use the following scripts and state sync.

**Before running the scripts, make sure to checkout to the [correct version](/operate/networks/overview):**

> **Note:** State sync scripts for each network are available in the [networks repository](https://github.com/celestiaorg/networks).

The public networks will use state sync so they'll get to the tip very quickly,
but won't work for your use case if you need historical blocks.

#### Manual state sync setup

In `$HOME/.celestia-app/config/config.toml`, set

```toml
rpc_servers = ""
trust_height = 0
trust_hash = ""
```

And also set statesync to `true`:

```toml
#######################################################
###         State Sync Configuration Options        ###
#######################################################
[statesync]
enable = true
```

To their respective fields. At least two different rpc endpoints should be provided.
The more, the greater the chance of detecting any fraudulent behavior.

Once setup, you should be ready to start the node as normal. In the logs, you should
see: `Discovering snapshots`. This may take a few minutes before snapshots are found
depending on the network topology.

### Option 3: Quick sync

Quick sync effectively downloads the entire `data` directory from a third-party provider
meaning the node has all the application and blockchain state as the node it was
copied from.

Run the following command to quick-sync from a snapshot:

**Mainnet Beta**

```bash
cd $HOME
rm -rf ~/.celestia-app/data
mkdir -p ~/.celestia-app/data
SNAP_NAME=$(curl -s https://snaps.qubelabs.io/celestia/ | \
    egrep -o ">celestia.*tar" | tr -d ">")
aria2c -x 16 -s 16 -o celestia-snap.tar "https://snaps.qubelabs.io/celestia/${SNAP_NAME}"
tar xf celestia-snap.tar -C ~/.celestia-app/data/
```

**Mocha**

```bash
cd $HOME
rm -rf ~/.celestia-app/data
mkdir -p ~/.celestia-app/data
SNAP_NAME=$(curl -s https://snaps.qubelabs.io/celestia/ | \
    egrep -o ">mocha-5.*tar" | tr -d ">")
aria2c -x 16 -s 16 -o celestia-snap.tar "https://snaps.qubelabs.io/celestia/${SNAP_NAME}"
tar xf celestia-snap.tar -C ~/.celestia-app/data/
```

The [Node snapshots guide](/operate/maintenance/snapshots) provides everything you need to quick sync your node:

- Details about pruned and archive snapshots
- A list of snapshot providers for different node types
- Installation and usage instructions for `celestia-snapshot-finder` - a tool that automatically finds and downloads the fastest snapshot for your server location

## Start the consensus node

If you are running celestia-app >= v4.0.0, the `rpc.grpc_laddr` config option is required. This option can be set via the CLI flag `--rpc.grpc_laddr tcp://0.0.0.0:9098` or in the `config.toml`.

```sh
celestia-appd start --rpc.grpc_laddr tcp://0.0.0.0:9098
```

If you are running celestia-app v2.x.x then you'll want to start the node with a `--v2-upgrade-height` that is dependent on the network. The `--v2-upgrade-height` flag is only needed during the v2 upgrade height so after your node has executed the upgrade (e.g. you see the log `upgraded from app version 1 to 2`), you don't need to provide this flag for future `celestia-appd start` invocations.

**Mainnet Beta**

```sh
celestia-appd start --v2-upgrade-height 2371495
```

**Mocha**

```sh
celestia-appd start --v2-upgrade-height 2585031
```

Optional: If you would like celestia-app to run as a background process, you can follow the [SystemD tutorial](/operate/maintenance/systemd).

## Extra resources for consensus nodes

### Optional: Reset network

There are several ways to reset your consensus node, depending on what you need to preserve:

#### Option 1: Reset blockchain data with `reset-state`

This command removes blockchain data but preserves validator state and address book of the consensus node:

```sh
celestia-appd tendermint reset-state
```

This preserves your configuration, validator state (`priv_validator_state.json`), and peer connections (`addrbook.json`), but removes:

- blockstore.db
- state.db
- evidence.db

This option is safe for validator nodes and was created specifically for validators who need to reset their node's blockchain data without risking double signing. Use this when you need to resync your node but want to maintain your validator's signing state and peer connections.

#### Option 2: Full reset with `unsafe-reset-all`

⚠️ **CAUTION FOR VALIDATORS**: This is considered "unsafe" because it resets validator state:

```sh
celestia-appd tendermint unsafe-reset-all --home $HOME/.celestia-app
```

This command:

- Resets blockchain data
- Resets validator state (`priv_validator_state.json`) but NOT private keys (which are in `priv_validator_key.json`)
- Clears address book (`addrbook.json`)
- Preserves node configuration

This option should ONLY be used when you're absolutely certain your validator isn't actively participating in consensus. Using this while your validator is active could lead to double signing. Always back up your validator keys before using this command.

#### Option 3: Manual reset (recommended for validator nodes)

For more granular control over what gets reset:

```sh
mv ~/.celestia-app/data ~/.celestia-app/old-data
mkdir -pv ~/.celestia-app/data
cp ~/.celestia-app/old-data/priv_validator_state.json ~/.celestia-app/data/priv_validator_state.json
```

This approach lets you manually preserve the validator state file while replacing all other data. The advantage over Option 1 is that you can selectively copy additional files if needed. Use this when you want maximum control over which files are preserved during reset.

#### Option 4: Simple data directory cleanup

For non-validator nodes, you can completely erase all blockchain data and test keys by removing and recreating the data directory:

```sh
# Remove data directory
rm -rf ~/.celestia-app/data
rm -rf ~/.celestia-app/keyring-test

# Create data directory and initialize validator state file
mkdir -p ~/.celestia-app/data/
echo "{}" > ~/.celestia-app/data/priv_validator_state.json
```

This approach:

- Completely removes all blockchain data (blocks, state, evidence, etc.)
- Removes the keyring-test directory containing transaction signing keys (but not validator consensus keys)
- Creates a new, empty data directory structure
- Initializes a blank validator state file, which erases the record of blocks your validator has signed

**Important:** This option should NOT be used for validator nodes because it creates a double-signing risk. The validator's consensus private key (in `priv_validator_key.json` in the config directory) remains intact, but the node loses all record of which blocks it has already signed. If the node is still an active validator on the network, it could sign conflicting blocks at the same height, resulting in slashing penalties.

Use this option only for non-validator nodes when you want a complete fresh start with no preserved state or connections.

It's recommended to test these commands on a testnet first before applying them to a mainnet node.

### Optional: Configure an RPC endpoint

You can configure your consensus node to be a public RPC endpoint.
This allows it to accept connections from data availability nodes and
serve requests for the data availability API.

If you're running a bridge node that connects to your consensus node, ensure that gRPC is properly configured in your `app.toml` file. Bridge nodes require gRPC access (typically on port 9090) to communicate with the consensus layer.

The Cosmos SDK REST API also requires application gRPC. If you enable
`[api]` with `enable = true` in `config/app.toml`, keep `enable = true`
in the existing `[grpc]` section. The equivalent CLI flags are
`--api.enable=true --grpc.enable=true`. The `rpc.grpc_laddr` setting in
`config.toml` configures a separate service and does not satisfy this
dependency.

#### Configure heavy RPC concurrency

Memory-intensive RPC endpoints share a process-wide concurrency limit across
HTTP, WebSocket and gRPC. The default limit is `20` concurrent requests. Set it
under `[rpc]` in `config.toml`:

```toml
[rpc]
max_concurrent_heavy_requests = 20
```

A value of `0` selects the built-in default of `20`. A negative value disables
the limit, which is not recommended. Increasing the limit can increase peak
memory consumption. Only raise it when the node has sufficient RAM, and monitor
node memory usage under RPC load.

#### Expose RPC

By default, the RPC service listens on `localhost` which means it can't
be accessed from other machines. To make the RPC service available publicly,
you need to bind it to a public IP or `0.0.0.0` (which means listening on all
available network interfaces).

You can do this by editing the config.toml file:

```sh
sed -i 's#"tcp://127.0.0.1:26657"#"tcp://0.0.0.0:26657"#g' ~/.celestia-app/config/config.toml
```

This command replaces the `localhost` IP address with `0.0.0.0`, making the
RPC service listen on all available network interfaces.

#### Note on `external-address`

The `external-address` field in the configuration is used when your node
is behind a NAT and you need to advertise a different address for peers
to dial. Populating this field is not necessary for making the RPC
endpoint public.

```sh
EXTERNAL-ADDRESS=$(wget -qO- eth0.me)
sed -i.bak -e "s/^external-address = ""/external-address = "$EXTERNAL-ADDRESS:26656"/" \
    $HOME/.celestia-app/config/config.toml
```

#### Restart the node

After making these changes, restart `celestia-appd` to load the new
configurations.

### Optional: Transaction indexer configuration options

This section guides you on how to configure your `config.toml`
file in `celestia-app` to select which transactions to index.
Depending on the application's configuration, a node operator
may decide which transactions to index.

The available options are:

1. `null` (default): This option disables indexing outside of
   transaction status. If you don't need to query transaction data,
   you can choose this option to save space.
2. `kv`: This is the simplest indexer, backed by
   PebbleDB key-value storage.
   When `kv` is chosen, `tx.height` and `tx.hash` will always be
   indexed. This option is suitable for basic queries on transactions.
3. `psql`: This indexer is backed by PostgreSQL. When psql is chosen,
   `tx.height` and `tx.hash` will always be indexed. This option is
   suitable for complex queries on transactions.

An example to set the value to `kv` in `config.toml` is:

```toml
indexer = "kv"
```

Remember to restart `celestia-appd` after making changes to the
configuration to load the new settings.

### Optional: Discard ABCI responses configuration

This section will guide you on how to configure your `config.toml` file in
`celestia-app` to manage the storage of ABCI responses. ABCI responses are
the results of executing transactions and are used for `/block_results` RPC
queries and to reindex events in the command-line tool.

The `discard_abci_responses` option allows you to control whether these
responses are persisted in the state store:

- `false` (default): ABCI responses are stored in the state store. This
  ensures that ABCI responses are available for `/block_results` RPC queries
  and for reindexing events. However, it can consume a significant amount
  of disk space.
- `true`: ABCI responses are not stored in the state store. This can
  save a considerable amount of disk space, but `/block_results` RPC queries
  and event reindexing will not be available.

An example to set the value to false in `config.toml` is:

```toml
discard_abci_responses = false
```

Remember to restart `celestia-appd` after making changes to the
configuration to load the new settings.

### Optional: Reduce log level

To reduce the log level, you can modify the `log_level` field in your `config.toml` file.

```diff
# Output level for logging, including package level options
-log_level = "info"
+log_level = "*:error,p2p:info,state:info"
```

### Passthrough command for historical queries

Starting with celestia-app v4 the `passthrough` command allows you to invoke queries on historical app versions. This is particularly useful when you need to query data from before a major version upgrade occurred.

#### When to use the passthrough command

The passthrough command is useful in scenarios where:

- You need to query state or transactions that existed before a major app version upgrade
- You're running a post-upgrade node but need to access data using the query format from a previous version
- You're debugging issues related to version compatibility after an upgrade

#### Basic usage

```sh
celestia-appd passthrough [app-version] [command] [flags]
```

Where:

- `[app-version]` is the historical app version you want to query against (e.g., `v1`, `v2`, `v3`)
- `[command]` is the command you want to execute using that app version's format

#### Examples

Query account balance using app version 1 format:

```sh
celestia-appd passthrough v1 query bank balances [address]
```

Query validator information using app version 2 format:

```sh
celestia-appd passthrough v2 query staking validator [validator-address]
```

Query transaction using app version 3 format:

```sh
celestia-appd passthrough v3 query tx [transaction-hash]
```

#### Important considerations

- The passthrough command requires that your node has the historical data for the version you're querying
- Not all query types may be available for all historical versions
- This command is most useful immediately after major version upgrades when you need backward compatibility
- Ensure your node is fully synced before using passthrough queries for accurate results

#### Getting help

To see all available options for the passthrough command:

```sh
celestia-appd passthrough --help
```

To see available commands for a specific app version:

```sh
celestia-appd passthrough [app-version] --help
```

---
Title: Run a Fibre server
URL: https://docs.celestia.org/operate/consensus-validators/fibre.md
Source: app/operate/consensus-validators/fibre/page.mdx
---

# Run a Fibre server

Fibre is a data availability service that validators run alongside
celestia-app. Clients upload blob shards to validator-operated Fibre servers
and download them from there, and each server's storage budget is derived from
the validator's stake. Starting with app version 10, every bonded validator is
expected to run one. Select your network below and use the matching release
of celestia-app and Fibre throughout this guide.

**Mainnet Beta**

Use `v10.4.0` for chain ID `celestia`.
Read the [release upgrade instructions](https://github.com/celestiaorg/celestia-app/releases/tag/v10.4.0)
and [Fibre server reference](https://github.com/celestiaorg/celestia-app/blob/v10.4.0/fibre/cmd/README.md).

Prepare Fibre before activation, then start it and register its public
address only after your node reports active app version 10 or later.

**Mocha**

Use `v10.4.0-mocha` for chain ID `mocha-5`.
Read the [release upgrade instructions](https://github.com/celestiaorg/celestia-app/releases/tag/v10.4.0-mocha)
and [Fibre server reference](https://github.com/celestiaorg/celestia-app/blob/v10.4.0-mocha/fibre/cmd/README.md).

Mocha has activated app version 10. Bonded Mocha validators can now start
Fibre and register their public address. See the
[Mocha-5 upgrade history](/operate/maintenance/network-upgrades#mocha-5).

Installing a v10 binary does not activate app version 10 on the chain. Prepare
the binaries and configuration before activation, then start Fibre and register
its address after activation. Follow the upgrade announcement for your network
for timing.

## Prerequisites

- A running, synced [validator node](/operate/consensus-validators/validator-node)
  in the bonded validator set. Fibre derives its storage budget from your stake.
- The v10 multiplexer celestia-app binary installed before activation. Follow
  your network's release upgrade instructions above and check the
  [celestia-app installation requirements](/operate/consensus-validators/install-celestia-app#linux-requirements).
- Separate disks for Fibre data and celestia-app data, and enough memory for
  the receive buffers described in [Plan capacity](#plan-capacity).
- If your consensus key lives in an external key management system (KMS), the
  KMS must support the `SignRawBytes` request and keep median signing latency
  at or below 10 ms. Fibre talks to the node's signing service, which forwards
  requests to the KMS.

Any KMS may be used if it meets these requirements. Review the KMS policy for
[Mainnet Beta](https://github.com/celestiaorg/celestia-app/blob/v10.4.0/docs/release-notes/release-notes.md#key-management-systems-kms)
or [Mocha](https://github.com/celestiaorg/celestia-app/blob/v10.4.0-mocha/docs/release-notes/release-notes.md#key-management-systems-kms)
before choosing or upgrading a signer. It describes Horcrux's maintenance
risks and the risk of double signing and slashing from incorrect KMS
configuration.

The 10 ms requirement is measured on celestia-app, not on Fibre. Nodes using a
remote signer expose `cometbft_privval_signing_latency_*` Prometheus metrics,
and the node logs a warning when the median of the last 50 signatures exceeds
10 ms. Collect these through the
[validator metrics setup](/operate/consensus-validators/metrics) and colocate
the signing infrastructure if needed to stay within the threshold.

## Plan capacity

Store Fibre data on a different disk from celestia-app data, so that growth in
one service cannot exhaust the space available to the other.

Memory is dominated by gRPC receive buffers. Each in-flight upload stream can
buffer a full message of about 132 MiB, and two settings in Fibre's
`server_config.toml` bound how many streams can be in flight at once:

| Setting | Default | Limits |
|---|---|---|
| `max_connections` | `16` | Client connections to the server |
| `max_concurrent_streams` | `13` | Concurrent gRPC streams per connection |

```text
worst-case receive buffers ≈ max_connections × max_concurrent_streams × 132 MiB
```

With the defaults that is about 27 GiB. Size the host for that figure plus
celestia-app, Fibre's other work, and the operating system. Raise the limits
only when the host has memory to spare.

An upload uses all 16 default connection slots, which blocks concurrent
downloads. To keep slots free for downloads, raise `max_connections` above 16
and recompute the memory budget. How to change these settings is covered in
[Connection limits](#connection-limits) below.

## Install Fibre

### Prebuilt binary

Linux Fibre archives require glibc 2.34 or later. The celestia-app multiplexer
has separate [Linux requirements](/operate/consensus-validators/install-celestia-app#linux-requirements);
check both when choosing the operating system for your validator.

Download the Fibre archive and checksums from the same release as celestia-app.
For Linux x86_64:

**Mainnet Beta**

```bash
fibre_version=v10.4.0
curl -fLO "https://github.com/celestiaorg/celestia-app/releases/download/$fibre_version/fibre_Linux_x86_64.tar.gz"
curl -fLO "https://github.com/celestiaorg/celestia-app/releases/download/$fibre_version/checksums.txt"
sha256sum --ignore-missing --check checksums.txt
tar -xzf fibre_Linux_x86_64.tar.gz
./fibre version
```

**Mocha**

```bash
fibre_version=v10.4.0-mocha
curl -fLO "https://github.com/celestiaorg/celestia-app/releases/download/$fibre_version/fibre_Linux_x86_64.tar.gz"
curl -fLO "https://github.com/celestiaorg/celestia-app/releases/download/$fibre_version/checksums.txt"
sha256sum --ignore-missing --check checksums.txt
tar -xzf fibre_Linux_x86_64.tar.gz
./fibre version
```

For Linux arm64, use `fibre_Linux_arm64.tar.gz`. macOS archives use `Darwin`
instead of `Linux`; verify them with `shasum -a 256 --ignore-missing --check checksums.txt`.
Place the verified binary on your executable path before using `fibre` below.

### Build from source

Install Git, Make, a C compiler, and the Go version required by your release.
Clone the same release used by your celestia-app node:

**Mainnet Beta**

Check the Go version required by the release's
[`go.mod`](https://github.com/celestiaorg/celestia-app/blob/v10.4.0/go.mod).

```bash
git clone --branch v10.4.0 --depth 1 https://github.com/celestiaorg/celestia-app.git celestia-app-fibre
cd celestia-app-fibre
make build-fibre-server VERSION=v10.4.0
./build/fibre version
```

**Mocha**

Check the Go version required by the release's
[`go.mod`](https://github.com/celestiaorg/celestia-app/blob/v10.4.0-mocha/go.mod).

```bash
git clone --branch v10.4.0-mocha --depth 1 https://github.com/celestiaorg/celestia-app.git celestia-app-fibre
cd celestia-app-fibre
make build-fibre-server VERSION=v10.4.0-mocha
./build/fibre version
```

The binary is written to `build/fibre` with the release version and short commit
hash. Setting `VERSION` avoids selecting another network's tag when tags share
a commit. Place the binary on your executable path before using `fibre` below.

## Configure the node connections

Fibre needs the application's gRPC service and the validator's signing service.

| Service | Node setting | Example address | Fibre option |
|---|---|---|---|
| Application gRPC | `config/app.toml`, `[grpc] address` | `127.0.0.1:9090` | `--app-grpc-address` |
| Priv-validator gRPC | `config/config.toml`, top-level `priv_validator_grpc_laddr` | `127.0.0.1:26669` | `--signer-grpc-address` |

Paths are relative to your existing node home, normally `~/.celestia-app`.
Back up the configuration files before editing. Edit existing keys and sections
instead of appending duplicate TOML sections.

### Enable application gRPC

In `config/app.toml`, edit the existing `[grpc]` section:

```toml
[grpc]
enable = true
address = "127.0.0.1:9090"
```

Set `enable = true` even if gRPC already appears to work. The multiplexer
turns it on for the embedded v9 application regardless of this setting, but
once the chain switches to v10 the setting in `app.toml` is what counts, and a
freshly generated config has it disabled.

The core RPC gRPC listener (`[rpc] grpc_laddr` in `config/config.toml`) is a
separate service. Keep its existing address for bridge nodes and other clients;
Fibre's `--app-grpc-address` must point to the application service above.

### Configure the signing connection

In `config/config.toml`, edit the top-level setting before the first section:

```toml
priv_validator_grpc_laddr = "127.0.0.1:26669"
```

> **Signer address compatibility:** In celestia-app builds that include
> [celestia-core #3379](https://github.com/celestiaorg/celestia-core/pull/3379),
> the hostname `localhost` no longer counts as loopback for
> `priv_validator_grpc_laddr`. Only loopback IP literals qualify. Before upgrading,
> replace `localhost:26669` with `127.0.0.1:26669` or `[::1]:26669` for a local
> plaintext signer, preserving your configured port. Update Fibre's
> `--signer-grpc-address` or `signer_grpc_address` to match, then restart both
> services. The node refuses to start with a hostname or non-loopback address
> unless mutual TLS is fully configured or `priv_validator_grpc_allow_insecure`
> is explicitly enabled. Use loopback IPs for local signing rather than bypassing
> the check; for remote signing, follow the
> [mutual TLS setup](#connections-between-fibre-and-your-validator)
> and use binaries with TLS support on both sides.

Fresh v10 configs use `26669` to avoid a port clash with TMKMS. Existing
configs may still have `26659`, a custom address, or an empty value, which
disables the service. Replacing the binary does not rewrite the saved value.
You can keep a custom port that already works, as long as it does not collide
with another listener. Whatever port you use, pass the same address to Fibre's
`--signer-grpc-address`.

Application and signing addresses, including Fibre's connection options, use
`host:port` without `tcp://`.

Restart the node after editing and confirm it resumes syncing and signing.
Check service-manager flags for overrides. If deployment tooling manages the
configuration, update its source templates too.

The `127.0.0.1` addresses shown above allow unencrypted connections on the
same host. If Fibre connects from another host or through a container network,
configure [mutual TLS for the signing connection](#connections-between-fibre-and-your-validator).
Keep the application and signing ports private. Open Fibre's client port
(default `7980`) so clients can reach it.

## Start after activation

Check the active app version through your node's HTTP RPC endpoint:

```bash
curl -s http://127.0.0.1:26657/abci_info
```

Confirm `result.response.app_version` is `10` or later. The installed binary
version does not tell you this: a v10 multiplexer binary keeps running v9 until
the chain activates the upgrade.

Start Fibre with its data home on the separate disk:

```bash
fibre start \
  --home <fibre_home> \
  --app-grpc-address 127.0.0.1:9090 \
  --signer-grpc-address 127.0.0.1:26669 \
  --server-listen-address 0.0.0.0:7980
```

Use your actual node addresses if different. On first start, Fibre creates
`<fibre_home>/config/server_config.toml`. The corresponding keys are `app_grpc_address`,
`signer_grpc_address`, and `server_listen_address`; command-line flags override
the file. Fibre rejects unknown keys and tables instead of silently ignoring
them. If startup reports an unknown field, correct or remove the reported
setting before restarting.

Check the startup log for the chain ID, connected addresses, and effective
storage backend. When object storage is configured, the log also includes its
canonical bucket, prefix, chain ID, and validator address.

### Connection limits

To change the limits sized in [Plan capacity](#plan-capacity), edit
`<fibre_home>/config/server_config.toml`:

```toml
max_connections = 16
max_concurrent_streams = 13
```

Add either key if it is missing from an existing file, then restart Fibre for
the change to take effect.

### Object storage

Object storage is supported in `v10.4.0` for Mainnet Beta and `v10.4.0-mocha`
for Mocha. The older `v10.2.0-mocha` binary ignores `storage_backend` and
`[object_storage]` and continues writing shards to local disk. Check `fibre version` before continuing. If upgrading,
follow the release upgrade instructions for
[Mainnet Beta](https://github.com/celestiaorg/celestia-app/releases/tag/v10.4.0)
or [Mocha](https://github.com/celestiaorg/celestia-app/releases/tag/v10.4.0-mocha)
to replace both celestia-app and Fibre, sync their configuration, and check
[signer TLS compatibility](#connections-between-fibre-and-your-validator).
Use the matching binaries from [Install Fibre](#install-fibre).

Fibre stores blob shards on local disk by default. To store them in
S3-compatible object storage instead, such as Amazon S3 or Cloudflare R2, set
the backend and bucket in `<fibre_home>/config/server_config.toml`:

```toml
storage_backend = "object"

[object_storage]
endpoint = "https://s3.us-east-1.amazonaws.com"
region = "us-east-1"
bucket = "<bucket_name>"
prefix = "fibre"
```

Use your bucket's endpoint and region. For Cloudflare R2, use its S3 API
endpoint and `region = "auto"`. Fibre's metadata database still needs
persistent local storage.

Fibre reads the bucket credentials from its environment through the standard
AWS variables and refuses to start if none are found. There is no credentials
field in the config file. To provide them to a systemd service:

1. Create an access key in your storage provider with read, write, and delete
   permissions on the bucket. On Amazon S3, create an IAM user with
   `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`, and `s3:ListBucket` on
   the bucket. On Cloudflare R2, create an API token with **Object Read &
   Write** permission scoped to the bucket.

2. Save the key in a file readable only by root:

   ```bash
   sudo mkdir -p /etc/fibre
   sudo tee /etc/fibre/s3.env > /dev/null <<'EOT'
   AWS_ACCESS_KEY_ID=<access_key_id>
   AWS_SECRET_ACCESS_KEY=<secret_access_key>
   EOT
   sudo chmod 0600 /etc/fibre/s3.env
   ```

   If AWS gave you temporary credentials, add a third line with
   `AWS_SESSION_TOKEN=<session_token>`.

3. Point the Fibre service at the file. Run `sudo systemctl edit fibre.service`,
   using your service name if it differs, and add:

   ```ini
   [Service]
   EnvironmentFile=/etc/fibre/s3.env
   ```

4. Restart Fibre and confirm it started:

   ```bash
   sudo systemctl daemon-reload
   sudo systemctl restart fibre.service
   sudo systemctl status fibre.service
   ```

To rotate keys, update the file and restart Fibre. If the host already has
credentials from an IAM role or the shared AWS credentials file, Fibre uses
them and you can skip the environment file.

### Switching shard storage backends

Fibre can store blob shards locally or in S3-compatible object storage, such
as Amazon S3 or Cloudflare R2. Create the bucket in the same region as the
Fibre host. A bucket in another region adds latency to every upload and
download. Changing `storage_backend` between `local` and `object` changes
where new shards are stored. Existing shards stay on their original backend.

**After switching back to `local`, keep access to object storage until pruning finishes.**
Keep `[object_storage]` configured and
preserve access to the same bucket and prefix with valid credentials until
all object-stored shards have been pruned. Do not delete the retained objects
or change the bucket or prefix while those shards remain.

Fibre still needs the bucket to read and prune retained shards, even in local
mode. Removing the object storage configuration or credentials prevents
startup while those shards remain.

### Migrate to another bucket

At startup, Fibre records the object endpoint, bucket, prefix, chain ID, and
validator address it uses. While object shards remain, starting with a
different endpoint, bucket, or prefix fails with `object namespace mismatch`,
in either storage mode. This stops retained shards from becoming unreachable
by accident. If it happens, restore the previous configuration to recover
access. To move the shards on purpose:

1. Stop Fibre, so no new shards are written to the old bucket during the copy.

2. Create the new bucket in the same region as the Fibre host.

3. Copy every object under the old prefix to the new bucket with the same key
   layout. Fibre looks shards up by key, so a different layout makes them
   unavailable. For example, with the AWS CLI:

   ```bash
   aws s3 sync s3://<old_bucket>/<old_prefix> s3://<new_bucket>/<new_prefix>
   ```

4. Set the new endpoint, bucket, or prefix in `[object_storage]` in
   `<fibre_home>/config/server_config.toml`. If the new bucket uses different
   keys, update the [credentials](#object-storage) too.

5. Start Fibre once with `--override-object-namespace` added to your usual
   start command. Fibre logs the old and new namespaces and records the new
   one. The flag does not copy or verify objects, so an override before the
   copy is complete makes shards unavailable and leaves orphaned objects after
   pruning.

6. Remove the flag and restart Fibre. The flag is not saved in the config
   file. Leaving it in the start command would accept any future mismatch
   without protection.

7. Once Fibre serves from the new bucket, delete the old bucket and revoke its
   credentials.

After all object shards are pruned, changing the bucket or prefix needs no
override.

## Register the public address

Once Fibre is running and reachable, register its public host using your
validator account:

**Mainnet Beta**

```bash
celestia-appd tx valaddr set-host <public_host>:7980 \
  --from <validator_account_key> --chain-id celestia
```

**Mocha**

```bash
celestia-appd tx valaddr set-host <public_host>:7980 \
  --from <validator_account_key> --chain-id mocha-5
```

Add your usual node, home, and transaction fee flags. The host must be
`host:port`, either an IP address or a DNS name, without a URL scheme or path.
Registration requires active app version 10 and a bonded validator. Register
only after the server is reachable, so clients do not discover an unavailable
host and time out against it.

Verify the registration with your consensus address, which
`celestia-appd comet show-address` prints:

```bash
celestia-appd query valaddr provider <celestiavalcons_address>
```

Confirm that `found` is `true` and that the returned host matches your public
address. `celestia-appd query valaddr providers` lists the hosts of all bonded
validators.

Registration persists across restarts, so re-run `set-host` only when the
address changes. The entry is removed if the validator is removed from staking,
or stays jailed and unbonded for more than 7 days. If your entry was removed,
register again after rejoining the active set.

## Transport security (TLS)

Client connections to Fibre are always TLS-encrypted, with no certificates to
obtain or renew. At startup the server generates a certificate and has the
node's signing service endorse it with your validator's consensus key, which
clients verify against the validator set. Because identity is bound to the key
rather than the address, the registered host can be an IP address or a DNS
name. Restart Fibre after changing `--signer-grpc-address` so the certificate
is endorsed with the right key.

### Connections between Fibre and your validator

The default signing address, `127.0.0.1:26669`, allows unencrypted connections
from the same host. No TLS certificates or extra flags are needed when Fibre
connects to this address.

For a remote signing connection, use binaries with mTLS support. The
[`v10.4.0` Mainnet Beta release](https://github.com/celestiaorg/celestia-app/releases/tag/v10.4.0)
and [`v10.4.0-mocha` Mocha release](https://github.com/celestiaorg/celestia-app/releases/tag/v10.4.0-mocha)
include this support in both celestia-app and Fibre. The `v10.2.0-mocha`
release does not; keep its signing connection on `127.0.0.1`.

If Fibre connects from another host or through a container network, configure
mutual TLS (mTLS) on both sides. mTLS encrypts the connection and uses
certificates to authenticate the node and Fibre. Without it, the node refuses
to start with a signing address such as `0.0.0.0:26669`, and Fibre refuses to
connect to a remote signer.

Follow the [core privval TLS guide](https://github.com/celestiaorg/celestia-core/blob/main/docs/guides/privval-grpc-tls.md)
to generate certificates and configure the node and Fibre. The server
certificate must match the IP address or DNS name Fibre connects to. Restart
both services after configuring or replacing certificates.

On Fibre, set all three certificate flags together when running `fibre start`,
or set their equivalent keys in `server_config.toml`:

| Fibre flag | Configuration key | File |
|---|---|---|
| `--signer-grpc-ca-file` | `signer_grpc_ca_file` | CA certificate used to verify the node |
| `--signer-grpc-cert-file` | `signer_grpc_cert_file` | Fibre's client certificate |
| `--signer-grpc-key-file` | `signer_grpc_key_file` | Private key for Fibre's client certificate |

These flags configure Fibre only; configure the node's certificates using
the guide above as well.

Keep the signing port on a private network and restrict access to the Fibre
host. For local development only, `--privval-grpc-allow-insecure` on the node
and `--signer-grpc-allow-insecure` on Fibre allow remote connections without
TLS. Do not use these overrides in production: anyone who can reach the
unprotected endpoint can request signatures from the validator key.

These settings protect the signing connection only. The application gRPC
connection shown in this guide is still unencrypted; keep it on the same host
or a trusted private network. Fibre's automatic client TLS does not protect
either connection.

See the Fibre server specification for
[Mainnet Beta](https://github.com/celestiaorg/celestia-app/blob/v10.4.0/specs/src/fibre_server.md)
or [Mocha](https://github.com/celestiaorg/celestia-app/blob/v10.4.0-mocha/specs/src/fibre_server.md)
for details of how clients verify Fibre's certificate.

## Troubleshoot startup

| Symptom | Check |
|---|---|
| `unknown service cosmos.base.tendermint.v1beta1.Service` | Confirm Fibre targets application gRPC, then check the active app version. The error alone does not identify the cause. |
| Missing Fibre or valaddr services | Wait for app version 10 to activate before starting Fibre or registering. |
| Application connection refused | Enable `[grpc]` in `app.toml`, restart the node, and check addresses and flag overrides. |
| Signer connection failed | Match Fibre's signer address to `priv_validator_grpc_laddr`; check for a disabled value or a port conflict. |
| `loading object storage credentials` | The service did not receive the bucket key. Check the environment file and the `EnvironmentFile=` override in [Object storage](#object-storage), then restart Fibre. |
| `object namespace mismatch` | The object endpoint, bucket, prefix, chain ID, or validator address changed while object shards remain. Restore the previous bucket settings and node connections, or follow [Migrate to another bucket](#migrate-to-another-bucket) when moving objects. |
| Configuration decode error reports an unknown field | Correct or remove the reported key or table in `<fibre_home>/config/server_config.toml`, then restart Fibre. |
| TLS identity verification failed | Check that the signing service holds your validator's consensus key, then restart Fibre after correcting the signer address. |
| `derived storage budget is 0` warning | The app node reports no stake for your validator. Check that the validator is bonded and that `--app-grpc-address` points at a synced node on the right network. Fibre keeps running and re-derives the budget periodically. |
| Server runs but no uploads arrive | Check that `query valaddr provider` finds your host, that the registered `host:port` is reachable from outside your network, and that the validator is bonded. Clients only dial registered, bonded validators. |
| `payment promise verification failed` | A chain ID mismatch means `--app-grpc-address` points at a different network than the client used. Other causes, such as an underfunded escrow, are on the uploader's side. |

For logging, metrics, tracing, and profiling, see
[Fibre monitoring](/operate/consensus-validators/fibre/metrics).
The Fibre server references for
[Mainnet Beta](https://github.com/celestiaorg/celestia-app/blob/v10.4.0/fibre/cmd/README.md)
and [Mocha](https://github.com/celestiaorg/celestia-app/blob/v10.4.0-mocha/fibre/cmd/README.md)
have further configuration details.

---
Title: Fibre monitoring
URL: https://docs.celestia.org/operate/consensus-validators/fibre/metrics.md
Source: app/operate/consensus-validators/fibre/metrics/page.mdx
---

# Fibre monitoring

This page covers observability in Fibre `v10.4.0-mocha`.
Complete the [server setup](/operate/consensus-validators/fibre) first. Add the
flags below to your existing start command, keeping your home and node addresses.
All observability flags apply to every subcommand.

## Logging

| Flag | Environment variable | Default | Values |
|---|---|---|---|
| `--log-level` | `FIBRE_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |
| `--log-format` | `FIBRE_LOG_FORMAT` | `text` | `text`, `json` |

```bash
fibre start --log-level debug --log-format json
```

## Tracing and metrics

Fibre sends traces and metrics over OTLP/HTTP to an OpenTelemetry collector,
such as Grafana Alloy or the OTel Collector. The collector must accept both
signals and forward them to your tracing and metrics backends. The celestia-app
repository ships a reference
[collector configuration](https://github.com/celestiaorg/celestia-app/blob/v10.4.0-mocha/observability/docker/otel-collector/config.yml)
and a
[Docker Compose stack](https://github.com/celestiaorg/celestia-app/tree/v10.4.0-mocha/observability/docker)
with Prometheus, Tempo, and Grafana that you can start from. The stack
publishes Prometheus on host port `9090`, which the setup guide uses for
application gRPC. When running it on the validator host, change that mapping
in `docker-compose.yml`, for example to `9091:9090`.

| Flag | Environment variable | Default |
|---|---|---|
| `--otel-endpoint` | `FIBRE_OTEL_ENDPOINT` | Disabled |

```bash
fibre start --otel-endpoint http://localhost:4318
```

Use the collector's base URL. Fibre appends `/v1/traces` and `/v1/metrics` itself.
For example, `https://collector.example.com/otel` sends data to
`/otel/v1/traces` and `/otel/v1/metrics`.

### Grafana dashboard

Import the release's
[Fibre dashboard JSON](https://github.com/celestiaorg/celestia-app/blob/v10.4.0-mocha/observability/docker/grafana/dashboards/fibre.json)
into Grafana. The dashboard expects a Prometheus data source with UID
`prometheus`; use that UID or update the dashboard to match your data source.
Client panels need telemetry from Fibre clients as well as the server. The same
directory has a
[Fibre runtime dashboard](https://github.com/celestiaorg/celestia-app/blob/v10.4.0-mocha/observability/docker/grafana/dashboards/fibre-runtime.json)
for Go runtime metrics such as memory and goroutines.

To verify the pipeline, start Fibre with `--otel-endpoint` set, open the Fibre
dashboard, and confirm the server panels populate once uploads or downloads
arrive. If they stay empty, work through the [troubleshooting](#troubleshooting)
table.

## Community dashboards

Use these community-maintained dashboards to monitor Fibre on Mainnet Beta and Mocha:

| Dashboard | Mainnet Beta | Mocha | What it monitors |
|---|---|---|---|
| Valopers | [Mainnet Beta](https://celestia.valopers.com/fibre) | [Mocha](https://testnet.celestia.valopers.com/fibre) | Registered providers, host reachability, and validator endorsements. |
| Tensile by Huginn Tech | [Mainnet Beta](https://tensile.huginn.tech/) | [Mocha](https://tensile-mocha.huginn.tech/) | Endpoint reachability, validator TLS identity, and whether validators serve their assigned blob rows during the retention window. |

See Tensile's [methodology](https://tensile-mocha.huginn.tech/methodology/) for how
observations and verdicts are calculated.

## Metric reference

### Traces

Fibre samples 10% of root spans and respects upstream sampling decisions, using
`ParentBased(TraceIDRatioBased(0.1))`. W3C TraceContext and Baggage propagation
carry trace context across gRPC and HTTP calls.

Each trace includes `service.name=fibre`, `service.version`, and
`service.instance.id` (the hostname).

### Metrics

Metrics are exported periodically over OTLP. Duration histograms include a
`success` attribute, so their counts can be used to calculate error rates.
Metric exemplars link observations to traces; in Grafana, select an exemplar
to open its trace.

The tables below list the original OTLP metric names. Your collector or backend
may convert dots to underscores and add unit suffixes.

#### Server metrics

| Metric | Type | Attributes | Description |
|---|---|---|---|
| `fibre.server.upload_shard.in_flight` | UpDownCounter | — | Concurrent UploadShard RPCs |
| `fibre.server.upload_shard.duration` | Histogram (s) | `success`, `upload_size` | UploadShard RPC latency |
| `fibre.server.upload_shard.bytes` | Counter (By) | — | Bytes received |
| `fibre.server.download_shard.in_flight` | UpDownCounter | — | Concurrent DownloadShard RPCs |
| `fibre.server.download_shard.duration` | Histogram (s) | `success`, `shard_size` | DownloadShard RPC latency |
| `fibre.server.download_shard.bytes` | Counter (By) | — | Bytes sent |
| `fibre.server.store.put.duration` | Histogram (s) | `success` | Store write latency |
| `fibre.server.store.get.duration` | Histogram (s) | `success` | Store read latency |
| `fibre.server.sign.duration` | Histogram (s) | `success` | Payment promise signing latency |
| `fibre.server.prune.entries` | Counter | — | Entries pruned |
| `fibre.server.prune.duration` | Histogram (s) | `success` | Prune cycle duration |

`fibre.server.sign.duration` measures how long Fibre waits for payment promise
endorsements. It is not the metric behind the 10 ms signing latency
requirement; that is celestia-app's `cometbft_privval_signing_latency_*`, see
[signing latency](/operate/consensus-validators/fibre#prerequisites) on the
setup page.

#### Client metrics

These metrics come from instrumented Fibre clients. Collect client telemetry
alongside server telemetry to measure end-to-end uploads and downloads.

| Metric | Type | Attributes | Description |
|---|---|---|---|
| `fibre.client.upload.in_flight` | UpDownCounter | — | Concurrent uploads |
| `fibre.client.upload.duration` | Histogram (s) | `success`, `blob_size` | Upload latency |
| `fibre.client.upload.bytes` | Counter (By) | — | Uploaded bytes, including row padding |
| `fibre.client.upload.data_bytes` | Counter (By) | — | Original data bytes, without padding or coding overhead |
| `fibre.client.upload.network_bytes` | Counter (By) | — | Bytes sent to all validators, including shard duplication |
| `fibre.client.upload.signatures_collected` | Histogram | — | Signatures collected per upload |
| `fibre.client.upload_to.duration` | Histogram (s) | `success`, `blob_size`, `validator_address` | Upload duration per validator |
| `fibre.client.upload_to.rpc_latency` | Histogram (s) | `success`, `validator_address` | Upload RPC network latency per validator |
| `fibre.client.download.in_flight` | UpDownCounter | — | Concurrent downloads |
| `fibre.client.download.duration` | Histogram (s) | `success`, `blob_size` | Download latency |
| `fibre.client.download.bytes` | Counter (By) | — | Downloaded bytes |
| `fibre.client.download_from.duration` | Histogram (s) | `success`, `validator_address` | Download duration per validator |
| `fibre.client.download_from.rpc_latency` | Histogram (s) | `success`, `validator_address` | Download RPC network latency per validator |

## Profiling with pprof

Enable the HTTP profiling server when you need to inspect CPU use, memory,
goroutines, or contention:

```bash
fibre start --pprof
```

The default address is `localhost:6060`. To use a different local port:

```bash
fibre start --pprof=localhost:7070
```

| Endpoint | Description |
|---|---|
| `/debug/pprof/` | Profile index |
| `/debug/pprof/goroutine` | Goroutine stack traces |
| `/debug/pprof/heap` | Heap memory allocations |
| `/debug/pprof/allocs` | Past memory allocations |
| `/debug/pprof/block` | Goroutine blocking events |
| `/debug/pprof/mutex` | Mutex contention |
| `/debug/pprof/profile` | 30-second CPU profile |
| `/debug/pprof/trace` | Execution trace |

Mutex and block profiling start automatically with the pprof server, using
mutex fraction `5` and block rate `1`.

## Continuous profiling with Pyroscope

Fibre can push profiles to a Pyroscope server. When tracing and Pyroscope are
both enabled, goroutine labels include span IDs so Grafana can link traces to
profiles. Profiles have `version` and `hostname` tags for filtering.

| Flag | Environment variable | Default |
|---|---|---|
| `--pyroscope-endpoint` | `FIBRE_PYROSCOPE_ENDPOINT` | Disabled |
| `--pyroscope-basic-auth-user` | `FIBRE_PYROSCOPE_BASIC_AUTH_USER` | None |
| `--pyroscope-basic-auth-password` | `FIBRE_PYROSCOPE_BASIC_AUTH_PASSWORD` | None |

```bash
fibre start --pyroscope-endpoint http://localhost:4040
```

For an endpoint that requires authentication:

```bash
fibre start \
  --pyroscope-endpoint https://<pyroscope_host> \
  --pyroscope-basic-auth-user <user_id> \
  --pyroscope-basic-auth-password <api_key>
```

## Troubleshooting

| Symptom | Check |
|---|---|
| No metrics or traces | Set `--otel-endpoint` to the collector's base URL, confirm it is reachable, and check that both signal pipelines are configured. |
| No client metrics on the dashboard | Enable telemetry on the Fibre clients generating traffic; server telemetry only supplies server metrics. |
| No pprof endpoint | Add `--pprof` to the start command and connect to its configured address on the Fibre host. |
| No continuous profiles | Check the Pyroscope endpoint, authentication values, and Fibre logs for export errors. |

See the release's
[observability reference](https://github.com/celestiaorg/celestia-app/blob/v10.4.0-mocha/fibre/cmd/README.md#observability)
for more details.

---
Title: The Celestia Foundation Delegation Program
URL: https://docs.celestia.org/operate/consensus-validators/foundation-delegation-program.md
Source: app/operate/consensus-validators/foundation-delegation-program/page.mdx
---

# The Celestia Foundation Delegation Program

![Delegation program banner](/img/foundation-delegation-program.jpg)

## Objectives of the program

The primary objectives of the Celestia Foundation Delegation Program are:

- To provide a fair opportunity for Celestia’s users to join the validator set, while ensuring the validator set remains proficient, trustworthy, and dependable.
- To maintain network stability by promoting a steady transition of validators and avoiding sudden and disruptive changes in participation.
- To enable the Celestia Foundation to use its stake towards its mission of fostering a modular blockchain network that delivers exceptional performance.

## Foundation delegation process

### Program launch

Prospective validators are welcome to apply to the program. The application is designed to assess a validator’s uptime performance and contributions to the Celestia ecosystem. Of the 100 total slots in Celestia’s active validator set, up to 35 will receive delegations within the program.

Application submissions will be reviewed by the Celestia Foundation. More details about the application and eligibility criteria are described below.

### Cohort process

![cohort timeline](/img/cohort-timeline.png)

Every 6 months, the Celestia Foundation will distribute a portion of the Foundation’s total available stake to a cohort of validators who meet certain criteria, detailed below. Here is an overview of how the cohort process will work.

### Key Points

- The program is split into Cohorts every 6 months.
- Each Cohort has to renew in 12 months, except the bottom 7 validators.
- The bottom 7 validators renew every 6 months.
- Open slots may be filled by existing Cohort members up for renewal or new applicants.

| Cohort    | Cohort size | Delegation duration | Renewal by cohort | Applications open | Applications close | Delegation begins |
| --------- | ----------- | ------------------- | ----------------- | ----------------- | ------------------ | ----------------- |
| Cohort 9  | 35          | 12 months           | Cohort 11         | 1 October 2026    | 1 November 2026    | 1 December 2026   |
| Cohort 10 | 7           | 6 months            | Cohort 11         | 1 April 2027      | 1 May 2027         | 1 June 2027       |
| Cohort 11 | 35          | 12 months           | Cohort 13         | 1 October 2027    | 1 November 2027    | 1 December 2027   |
| Cohort 12 | 7           | 6 months            | Cohort 13         | 1 April 2028      | 1 May 2028         | 1 June 2028       |

This structure allows for a steady flow of both existing applicants and new applicants to maintain a stable set of participants in the program.

During this period, so long as the validator maintains high uptime and does not violate the rules of the program, the validator will receive the delegation for the duration of the cohort they are currently in.

### Eligibility criteria

The minimum requirements for participation in the program are as follows:

- Run an active Mainnet Beta validator **or** an active Mocha testnet validator for **at least 2 months before application deadline**
- The validator has to have significant stake to be able to propose blocks
- Not jailed more than once in the 6 months before application deadline
- If jailed more than once in the 6 months period before application deadline, then we require a public forum post with detailed post mortem and we consider case by case
- Not associated with an exchange or custodian
- Not in the top 10 validators by delegation power, unless it enters the top 10 as a result of the Foundation’s delegation under this program
- Have 25% or less commission
- Not based within the US, within any country subject to economic sanctions, or within any other prohibited jurisdiction, and successfully complete a compliance screen
- Dedicated email address so that the Foundation can reach you in the event of emergency upgrades and fixes
- Not running your infrastructure in Hetzner or OVH (EU and US)
- EU and US location is not recommended
- Run Fibre once it is live

Not adhering to any of the criteria above will automatically disqualify your application, and violating any of the criteria after you have received delegation will result in withdrawal of the delegation. A participant who loses stake due to being jailed by the protocol may reapply to the program after 2 cohort periods.

Applicants are also expected to have reviewed Celestia docs and recommended guides on devops and monitoring setups.

Other optional but important criteria:

- Develop and maintain developer tooling, services, applications, and dashboards
- Work on projects aligned with Celestia's values
- Contribute to documentation and new guides and tutorials
- Quality of infrastructure
- Operated within a location that improves geolocation of the validator set

### Undelegation criteria

- Getting slashed/tombstoned (cannot apply for 1 year afterwards)
- Getting jailed more than once during the cohort’s applicable delegation period
- Violating the [Celestia.org Community Code of Conduct](/learn/code-of-conduct) or engaging in harmful activities towards the network
- Failing to upgrade your node in a timely manner (24 hours or less)
- If necessary to protect or secure Mainnet Beta or to comply with applicable law
- For any other reason, in the Celestia Foundation’s sole discretion

## Application

The program will be divided into cohorts with applications open for new applicants and renewal of existing applicants every 6 months. Validators will be delegated for up to a year. For each cohort, the deadline to apply/be evaluated (if you are reapplying) is exactly 1 month prior to the date of being delegated to.

Selected validators are required to support both Mainnet Beta and Mocha networks as an active validator and Fibre support (once Fibre is live).

### Application details

Before applying, be ready to share the following:

- General info
  - Security Email
  - Validator Entity Name
  - Discord ID
  - Mark if entity or individual
  - Website if any
  - Github page of your organization
  - Team experience and roster (including Twitter + Github links)
  - Which networks you validate on Mainnet + links to your validators
  - A personal statement why you should receive delegation from the Foundation (max 1500 characters)
- Infrastructure
  - Validator address on Mainnet Beta
  - Validator address on Mocha testnet
  - Have you been slashed or jailed in the last 6 months on Celestia or other chains you validated on.
  - Hosting provider and Data Center location (Mainnet Beta and testnet if applicable)
  - Setup of the validator
    - Hardware
    - Security setup (servers, private keys)
    - Monitoring and alerting
- Contributions
  - Please list all contributions for Celestia and its ecosystem

Please note, the objective of the program is to contribute to Celestia’s resilience and uptime. If you contribute a lot to the Celestia ecosystem, but your validator uptime is low, this will negatively impact your chance at selection for the program. Furthermore, merely receiving delegation from the Foundation under the program does not guarantee your placement in the active validator set.

[Get Started with the Application Form](https://forms.gle/RHTLvvkF4jHuaviEA)

## Cohort information

The Foundation will report each cohort’s composition and the duration of their respective delegations.

- [Cohort 1](https://docs.google.com/spreadsheets/d/1Fxu9uYJ4wxfHChEiSg5bmXAMU8IZSq7J3GYDCFgk1HA/edit#gid=0): 50 Validator Seats
- [Cohort 2](https://docs.google.com/spreadsheets/d/1Fxu9uYJ4wxfHChEiSg5bmXAMU8IZSq7J3GYDCFgk1HA/edit?gid=855157686#gid=855157686): 15 Validator Seats (Applications open June 1, 2024)
- [Cohort 3](https://docs.google.com/spreadsheets/d/1Fxu9uYJ4wxfHChEiSg5bmXAMU8IZSq7J3GYDCFgk1HA/edit?gid=1432570846#gid=1432570846): 15 Validator Seats (Applications open October 1, 2024)
- [Cohort 4](https://docs.google.com/spreadsheets/d/1Fxu9uYJ4wxfHChEiSg5bmXAMU8IZSq7J3GYDCFgk1HA/edit?gid=1814073511#gid=1814073511): 20 Validator Seats (Applications open February 1, 2025)
- [Cohort 5](https://docs.google.com/spreadsheets/d/1Fxu9uYJ4wxfHChEiSg5bmXAMU8IZSq7J3GYDCFgk1HA/edit?gid=1471991269#gid=1471991269): 15 Validator Seats (Applications open June 1, 2025)
- [Cohort 6](https://docs.google.com/spreadsheets/d/1Fxu9uYJ4wxfHChEiSg5bmXAMU8IZSq7J3GYDCFgk1HA/edit?gid=1010270944): 15 Validator Seats (Applications open October 1, 2025)
- [Cohort 7](https://forum.celestia.org/t/foundation-delegation-cohort-7-is-live/2232): 20 Validator Seats (Applications open February 1, 2026)
- [Cohort 8](https://forum.celestia.org/t/foundation-delegation-cohort-8-is-live/2281): 15 Validator Seats (Applications open June 1, 2026)

---
Title: Install celestia-app
URL: https://docs.celestia.org/operate/consensus-validators/install-celestia-app.md
Source: app/operate/consensus-validators/install-celestia-app/page.mdx
---

# Install celestia-app

This tutorial will guide you through installing celestia-app, both
[from source](#building-binary-from-source) and with
[a pre-built binary](#installing-a-pre-built-binary)

Celestia-app is the software that enables you to run
consensus nodes (including validators) and provide RPC endpoints.

## Supported architectures

Celestia-app officially supports the following architectures:

- linux/amd64
- linux/arm64
- darwin/amd64 (macOS Intel)
- darwin/arm64 (macOS Apple Silicon)

Only these four architectures are officially tested and supported.

## Linux requirements

celestia-app v9 and later multiplexer binaries require glibc 2.38 or later. Use Ubuntu
24.04 LTS or an equivalent Linux distribution. Ubuntu 22.04 and older are not
supported and the binary will fail to start with a glibc version mismatch.

Check the installed glibc version before installing or upgrading:

```bash
ldd --version
```

See the [celestia-app v9 release notes](https://github.com/celestiaorg/celestia-app/blob/v9.0.4/docs/release-notes/release-notes.md#supported-operating-systems)
and the [Mocha release requirements](https://github.com/celestiaorg/celestia-app/releases/tag/v10.4.0-mocha)
for the supported operating system details.

## Building binary from source

This section of the tutorial assumes you completed the steps in
[setting up your own environment](/operate/getting-started/environment-setup).

The steps below will create a binary file named `celestia-appd`
inside `$HOME/go/bin` folder which will be used later to run the node.
Be sure to select the correct network to install the binary for.

### Remove any existing copy and clone the repository

   ```bash
   cd $HOME
   rm -rf celestia-app
   git clone https://github.com/celestiaorg/celestia-app.git
   cd celestia-app
   ```

### Check out the desired version

**Mainnet Beta**

```bash
git checkout tags/v10.4.0
```

**Mocha**

```bash
git checkout tags/v10.4.0-mocha
```

On Linux, enable BBR TCP congestion control before building. Run the following
from the checked-out `celestia-app` directory on the node's host, with sudo
access. Skip this step on macOS.

```bash
make enable-bbr
make check-bbr
```

The enable command loads the `tcp_bbr` kernel module, persists it in
`/etc/modules`, and adds the `fq` queueing and `bbr` congestion control defaults
to `/etc/sysctl.conf` before applying that file. These are host-wide network
settings. The check command should print `BBR is enabled.`

If enabling BBR fails, inspect the command output and confirm that the host's
Linux kernel provides the `tcp_bbr` module and that you have sudo access. Run
these commands on the host rather than inside a container, then rerun
`make check-bbr` to verify the result.

### Build and install the `celestia-appd` binary with multiplexer support

   ```bash
   make install
   ```

### Verify the installation

To check if the binary was successfully installed you can run the binary
using the `--help` flag:

   ```sh
   celestia-appd --help
   ```

You will see an output with the menu for `celestia-appd`. Learn more
on the [helpful CLI commands page](/operate/consensus-validators/cli-reference)

## Installing a pre-built binary

Installing a pre-built binary is the fastest way to get started with your
Celestia consensus node. Releases after celestia-app v1.3.0 should have
these binaries available.

The steps below will download a binary file named `celestia-appd`.
Depending on the setup that you choose during installation, the `celestia-appd`
binary will be available at either:

- `$HOME/celestia-app-temp/celestia-appd`
- `/usr/local/bin/celestia-appd`

Pre-built binaries are available for:

- Operating systems: Darwin (Apple), Linux
- Architectures: x86_64 (amd64), arm64

To install the latest, or a specific version of the pre-built binary you can run this command in your
terminal:

```bash
# Install latest version
bash -c "$(curl -sL https://docs.celestia.org/celestia-app.sh)"

# Install specific version, latest version for Mocha testnet in this example
bash -c "$(curl -sL https://docs.celestia.org/celestia-app.sh)" -- -v v10.4.0-mocha
```

Follow the instructions in the terminal output to choose your installation
preferences.

You will see an output with the menu for `celestia-appd`. Learn more
on the [helpful CLI commands page](/operate/consensus-validators/cli-reference)

View [the script](https://github.com/celestiaorg/docs/blob/main/public/celestia-app.sh)
to learn more about what it is doing.

## Ports

When interacting with a consensus node,
you may need to open ports on your machine to allow
communication between nodes, such as bridge nodes. It is essential that
specific ports are accessible. Make sure that your firewall allows
connections to the correct ports.

If you run a node on a cloud server, make sure that the ports are open
on the server's firewall. If you run a node at home, make sure that your
router allows connections to the correct ports.

For example, validator ports 9090
and 26657 need to be accessible by the bridge, and port 2121 is
required for P2P connections for all node types.

The following ports are used by Celestia app nodes:

| Port  | Protocol | Address   | Description | Enabled by default on node     | Flag                    |
| ----- | -------- | --------- | ----------- | ------------------------------ | ----------------------- |
| 2121  | TCP/UDP  | 127.0.0.1 | P2P         | true                           | N/A                     |
| 9090  | HTTP     | 0.0.0.0   | gRPC        | true                           | `--grpc.address string` |
| 26657 | TCP      | 127.0.0.1 | RPC         | false (only open to localhost) | `--rpc.laddr string`    |

## Next steps

Now that you've installed `celestia-appd`, learn how to run a [consensus](/operate/consensus-validators/consensus-node) and [validator](/operate/consensus-validators/validator-node) node.

---
Title: Metrics
URL: https://docs.celestia.org/operate/consensus-validators/metrics.md
Source: app/operate/consensus-validators/metrics/page.mdx
---

# Metrics

Metrics are a powerful tool for monitoring the health
and performance of a system. Celestia provides support
for metrics to make sure, as an operator, your system
continues to remain up and running. Metrics can also
provide critical insight into how Celestia is used and
how it can be improved.

## Setup

Celestia uses [Prometheus](https://prometheus.io/) to
publish metrics. It can be enabled through the `config.toml` file.

```bash
#######################################################
###       Instrumentation Configuration Options     ###
#######################################################
[instrumentation]

# When true, Prometheus metrics are served under /metrics on
# PrometheusListenAddr.
# Check out the documentation for the list of available metrics.
prometheus = true

# Address to listen for Prometheus collector(s) connections
prometheus_listen_addr = ":26660"

# Maximum number of simultaneous connections.
# If you want to accept a larger number than the default, make sure
# you increase your OS limits.
# 0 - unlimited.
max_open_connections = 3

# Instrumentation namespace
namespace = "celestia"
```

If you restart your node, you can check to see it's working
by running:

```bash
curl localhost:26660/metrics
```

## Visualization

Now your nodes are publishing metrics, we need something to
scrape it and a visualizer to create a dashboard. Commonly,
Prometheus is paired with Grafana.

First, you will need to install Prometheus either from their
[downloads page](https://prometheus.io/download/) or through
a package manager like `brew`.

Next, create a config file `$HOME/.celestia-app/config/prometheus.yml`
and fill out some basic settings as follows:

```yml
global:
  scrape_interval: 15s # By default, scrape targets every 15 seconds.

  # Attach these labels to any time series or alerts when communicating
  # with external systems (federation, remote storage, Alertmanager).
  external_labels:
    monitor: "codelab-monitor"

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
  # The job name is added as a label `job=<job_name>` to any timeseries
  # scraped from this config.
  - job_name: "prometheus"

    # Override the global default and scrape targets from this job every
    # 5 seconds.
    scrape_interval: 5s

    static_configs:
      # Point to the same endpoint that Celestia is publishing on
      - targets: ["localhost:26660"]
```

Note, that Prometheus by default runs its server on `:9090`.
If you are running this on the same machine as your consensus
node, it will collide with gRPC which runs on the same port.
To avoid this, change the gRPC port in `app.toml`, or run Prometheus on a
different port, _e.g._ `--web.listen-address="0.0.0.0:8000"`.
When `[api]` has `enable = true` in `app.toml`, `[grpc]` must also
have `enable = true` because the REST API uses Cosmos SDK gRPC.

To run the prometheus server:

```bash
prometheus --config.file="$HOME/.celestia-app/config/prometheus.yml"
```

A prometheus server can scrape metrics from multiple nodes at once;
a good way of bringing together information from many machines to one place.

To visualize the information, you can use [Grafana](https://grafana.com/):
either with their cloud option or run the [open source code](https://grafana.com/grafana/download?pg=graf&platform=linux&plcmt=deploy-box-1)
yourself.

Once setup, run:

```bash
grafana server
```

which will begin a server on `localhost:3000`.
If you open the url on your browser you will
see the Grafana login page. Use `admin` for both
the user and password to log in.

You will need to link the prometheus server as a
data source. To do that go to "Configuration" in
the sidebar and then "Data Sources". Add a new data
source specifying the URL of the Prometheus instance
(default at `localhost:9090`). Click "Save & test" to confirm.

Lastly, you will need to setup a dashboard. You can
choose to do this yourself, handpicking the metrics
that are important or you can simply export an existing
design. Fortunately the cosmos ecosystem has conjured a
"Cosmos Dashboard". On the sidebar, click "Dashboards"
and then "import". Enter the following dashboard ID: 11036
and then link it to the "Prometheus" data source you just set up.
Finally click the "Import" button and the "Cosmos Dashboard" should appear.

## Node exporter

Celestia's metrics include a plethora of application specific
trackers but it's also important to keep an eye on system level
metrics such as memory usage and disk space. This can be best
achieved by running [Node Exporter](https://prometheus.io/docs/guides/node-exporter/).
Follow the guide in the link to get set up, adding the port
number to the `prometheus.yml` file.

## Alerts

The final cherry on the cake is to integrate your monitoring
system with a mechanism for producing alerts to warn you if
your node has crashed or is no longer able to stay at the head
of the chain.

Since we're already using Grafana, we can install the
[Grafana OnCall](https://grafana.com/grafana/plugins/grafana-oncall-app/)
plugin. OnCall allows you to setup integrations. It could be a
webhook or a direct integration into Telegram or Slack.
You can find more information on Grafana's [Docs Page](https://grafana.com/docs/oncall/latest/integrations/).

---
Title: Jailing and slashing on Celestia
URL: https://docs.celestia.org/operate/consensus-validators/slashing.md
Source: app/operate/consensus-validators/slashing/page.mdx
---

# Jailing and slashing on Celestia

Slashing is a mechanism employed in proof of stake blockchains
that is used to deter and punish malicious behavior.
It functions by removing a percentage of a validator's stake
each time they act harmfully towards the network.

Celestia is built with the Cosmos SDK and uses the `x/slashing` module.

If a validator gets slashed, delegators bonded to that validator will also
have the same percentage of their delegated funds slashed.

The following are the conditions for a validator to get jailed or slashed:

1. **Downtime**: If a validator is offline for more than 25% of a rolling window
   of the last 5,000 blocks, they will be jailed for 1 minute.
   During this period, the validator is removed from the validator set
   temporarily, and will be unable to propose new blocks or earn rewards.
   After the jail period, the validator can send an unjail request to
   rejoin the validator set.

2. **Double signing**: This is a more severe offense and results in getting slashed.
   If a validator engages in double signing, the validator
   will lose 2% of their stake and the remainder of their stake
   will be returned to them. The validator will be permanently removed
   from the validator set and will not have the ability to unjail.
   Delegators bonded to that validator will automatically enter the unbonding
   period for 21 days, and can delegate to another validator after
   they have been unbonded.

For more details on the jailing and slashing parameters, refer to the
[celestia-app specifications](https://celestiaorg.github.io/celestia-app/parameters_v6.html)
page.

---
Title: Upgrade Monitor
URL: https://docs.celestia.org/operate/consensus-validators/upgrade-monitor.md
Source: app/operate/consensus-validators/upgrade-monitor/page.mdx
---

# Upgrade Monitor

Upgrade monitor is a binary that monitors that status of upgrades on a Celestia
network. See the [README](https://github.com/celestiaorg/upgrade-monitor) for
instructions on how to install and use the binary.

---
Title: Setting up a Celestia validator node
URL: https://docs.celestia.org/operate/consensus-validators/validator-node.md
Source: app/operate/consensus-validators/validator-node/page.mdx
---

# Setting up a Celestia validator node

This tutorial will guide you through setting up a validator node on Celestia.
Validator nodes allow you to participate in consensus in the Celestia network.

![validator node](/img/nodes/validator.png)

## Hardware requirements

See [hardware requirements](/operate/getting-started/hardware-requirements).

## Setting up a validator node

The following tutorial is done on an Ubuntu Linux 24.04 (LTS) x64
instance machine.

First, follow the instructions on
[setting up a consensus node](/operate/consensus-validators/consensus-node#set-up-a-consensus-node).

### Wallet

Follow [the tutorial on creating a wallet](/operate/keys-wallets/celestia-app-wallet).
That page also covers the available keyring backends. Pick one before you
create the wallet: a Mainnet Beta validator should not use the `test` backend,
which stores the key unencrypted on disk.

## Optional: Deploy the celestia-node

Running a bridge node is critical to the Celestia network as it enables
the data availability and consensus nodes to communicate with one
another. It is recommended to support the data availability network,
but is not required.

If you are not running a bridge node, you can skip to
[run a validator node](#run-the-validator-node).

This section describes part 2 of Celestia validator node setup: running a
Celestia bridge node daemon.

### Install celestia-node

You can [follow the tutorial for installing `celestia-node`](/operate/data-availability/install-celestia-node)

### Initialize the bridge node

Run the following:

```bash
celestia bridge init --core.ip <URI> --core.port <port>
```

Refer to [the ports section of the celestia-node troubleshooting page](/operate/maintenance/troubleshooting#ports) for information on which ports are required to be open on your machine.

When connecting your bridge node to a localhost consensus node, ensure that gRPC
is properly configured in your consensus node's `app.toml` file. The `[grpc]`
section should have `enable = true` and the appropriate address setting for the
bridge node to connect successfully.

Using an RPC of your own, or one listed for
[Mainnet Beta](/operate/networks/mainnet-beta#integrations) or
[Mocha testnet](/operate/networks/mocha-testnet#community-consensus-endpoints),
initialize your node.

### Run the bridge node

Run the following:

```bash
celestia bridge start
```

#### Optional: start the bridge node with SystemD

Follow
[the tutorial on setting up the bridge node as a background process with SystemD](/operate/maintenance/systemd).

You have successfully set up a bridge node that is syncing with the network.

## Run the validator node

> **Fibre signer compatibility:** Before starting an upgraded celestia-app build
> that includes
> [celestia-core #3379](https://github.com/celestiaorg/celestia-core/pull/3379),
> check `priv_validator_grpc_laddr` in `config/config.toml` if you use the signing
> service. The hostname `localhost` no longer counts as loopback. For local
> plaintext signing, replace `localhost:26669` with `127.0.0.1:26669` or
> `[::1]:26669`, preserving your port, and update Fibre's signer address to match.
> Without mutual TLS or an explicit insecure override, a hostname or non-loopback
> address prevents the node from starting. Follow the
> [Fibre signing connection guide](/operate/consensus-validators/fibre#configure-the-signing-connection)
> for configuration and restart instructions. This check applies to the
> priv-validator signing service, not application gRPC in `app.toml`.

In order to create a validator on-chain, follow the steps below.

1. Start the consensus node

   ```sh
   celestia-appd start
   ```

1. Export an environment variable for the chain ID you want to run on:

**Mainnet Beta**

```bash
export CHAIN_ID=celestia
```

**Mocha**

```bash
export CHAIN_ID=mocha-5
```

1. Export more environment variables.

   ```bash
   # Pick a moniker name of your choice.
   export MONIKER="your_moniker"

   # Set VALIDATOR_WALLET to the same you defined previously.
   export VALIDATOR_WALLET="validator"

   # Set KEYRING_BACKEND to the backend you chose when creating the wallet.
   # `test` stores the key unencrypted on disk: it is a reasonable choice on
   # Mocha, but do not use it on Mainnet Beta.
   export KEYRING_BACKEND="file"

   # Set VALIDATOR_PUBKEY to the pubkey of your validator wallet.
   export VALIDATOR_PUBKEY=$(celestia-appd tendermint show-validator)
   ```

1. Create a validator

**Mainnet Beta**

```bash
celestia-appd tx staking create-validator \
    --amount=1000000utia \
    --pubkey=$VALIDATOR_PUBKEY \
    --moniker=$MONIKER \
    --identity=<optional_identity_signature> \
    --website="<optional_validator_website>" \
    --security-contact="<optional_email_address_for_security_contact>" \
    --details="A short and optional description of the validator." \
    --chain-id=$CHAIN_ID \
    --commission-rate=0.1 \
    --commission-max-rate=0.2 \
    --commission-max-change-rate=0.01 \
    --min-self-delegation=1000000 \
    --from=$VALIDATOR_WALLET \
    --keyring-backend=$KEYRING_BACKEND \
    --fees=21000utia \
    --gas=220000 \
    --yes
```

**Mocha**

```bash
celestia-appd tx staking create-validator \
    --amount=1000000utia \
    --pubkey=$VALIDATOR_PUBKEY \
    --moniker=$MONIKER \
    --identity=<optional_identity_signature> \
    --website="<optional_validator_website>" \
    --security-contact="<optional_email_address_for_security_contact>" \
    --details="A short and optional description of the validator." \
    --chain-id=$CHAIN_ID \
    --commission-rate=0.1 \
    --commission-max-rate=0.2 \
    --commission-max-change-rate=0.01 \
    --min-self-delegation=1000000 \
    --from=$VALIDATOR_WALLET \
    --keyring-backend=$KEYRING_BACKEND \
    --fees=21000utia \
    --gas=220000 \
    --yes
```

You should see output like:

```console
code: 0
codespace: ""
data: ""
gas_used: "0"
gas_wanted: "0"
height: "0"
info: ""
logs: []
raw_log: '[]'
timestamp: ""
tx: null
txhash: <tx-hash>
```

> **Note:** The options `--identity`, `--website`, `--security-contact` and `--details` are optional. The `--identity` value is used to verify identity with systems like [Keybase](https://keybase.io/) or UPort. If you need to add or update the values of these descriptive fields when your validator is already created, you can use the following command (remove the options that you don't want to change the values for):

```bash
celestia-appd tx staking edit-validator \
    --new-moniker=<new_validator_name> \
    --identity=<identity_signature> \
    --website="<validator_website>" \
    --security-contact="<email_address_for_security_contact>" \
    --details="New description of the validator." \
    --from=$VALIDATOR_WALLET \
    --keyring-backend=$KEYRING_BACKEND \
    --fees=21000utia \
    --gas=220000
```

You should now be able to see your validator from a [block explorer](/operate/networks/mocha-testnet#explorers).

## Submit your validator information

After starting your node, please submit your node as a seed and peer to the
[networks repository](https://github.com/celestiaorg/networks).

## Optional: Delegate stake to a validator

Create an environment variable for the address:

```bash
VALIDATOR_WALLET=<validator-wallet-name>
```

If you want to delegate more stake to any validator, including your own you
will need the `celestiavaloper` address of the validator in question. You can run
the command below to get the `celestiavaloper` of your local validator wallet in
case you want to delegate more to it:

```bash
celestia-appd keys show $VALIDATOR_WALLET --bech val -a \
--keyring-backend=$KEYRING_BACKEND
```

After entering the wallet passphrase you should see a similar output:

```bash
Enter keyring passphrase:
celestiavaloper1q3v5cugc8cdpud87u4zwy0a74uxkk6u43cv6hd
```

To delegate tokens to the `celestiavaloper` validator, as an
example you can run:

```bash
celestia-appd tx staking delegate \
<the_valoper_address_starts_with_celestiavaloper1...> 1000000utia \
--from=$VALIDATOR_WALLET --chain-id=mocha-5 \
--keyring-backend=$KEYRING_BACKEND \
--fees=21000utia
```

If successful, you should see a similar output as:

```console
code: 0
codespace: ""
data: ""
gas_used: "0"
gas_wanted: "0"
height: "0"
info: ""
logs: []
raw_log: '[]'
timestamp: ""
tx: null
txhash: <tx-hash>
```

You can check if the TX hash went through using the block explorer by
inputting the `txhash` ID that was returned.

## Optional: Transaction indexer configuration options

Follow the instructions under
[transaction indexer configuration options](/operate/consensus-validators/consensus-node#optional-transaction-indexer-configuration-options)
to configure your `config.toml` file to select which transactions to index.

## Migrating a validator to another machine

> **Warning:** Moving a validator to a new machine is a sensitive process that needs to be done carefully. If the transfer isn’t handled properly, it could result in double signing, which will permanently slash your validator, wipe out delegated tokens, and remove you from the active validator set. To avoid this, make sure to follow the steps closely and stop the old node completely before starting the migration.

### Step 1: Set up a new full consensus node

First, set up a new [consensus node](/operate/consensus-validators/consensus-node) on the new server and make sure the node is fully synced with the chain. To check whether your node is synced, you can check the `catching_up` status using:

```bash
celestia-appd status | jq '{ "catching_up": .SyncInfo.catching_up }'
```

If the node is synced, the output will look like this:

```json
{
  "catching_up": false
}
```

### Step 2: Stop the old validator

After your new consensus node is synced, proceed to stop the current validator on the old machine. If you’re running it with [SystemD](/operate/maintenance/systemd), use the following command:

```bash
sudo systemctl stop <SERVICE_NAME>
```

Additionally, it’s recommended to disable the service to prevent it from restarting automatically after a system reboot. You can do this with:

```bash
sudo systemctl disable <SERVICE_NAME>
```

For extra safety, you may also delete the service file from the server:

```bash
sudo rm -rf /etc/systemd/system/<SERVICE_NAME>.service
```

### Step 3: Backup and transfer `priv_validator_key.json`

Once the old validator is stopped and the new node is synced, you’ll need to back up the `priv_validator_key.json` file from the old server (if it has not been backed up earlier). This file is located at:

```plaintext
~/.celestia-app/config/priv_validator_key.json
```

Copy this file to the same location on the new server. To verify that the file has been transferred correctly, compare its contents on both servers using:

```bash
cat ~/.celestia-app/config/priv_validator_key.json
```

### Step 4: Start the new validator

If everything checks out, you can now restart the new node with the updated validator key:

```bash
sudo systemctl restart <SERVICE_NAME>
```

After this, your validator will resume signing blocks on the new server, and the migration is complete. Validators operate within a 10,000 signed block window, and missing more than 2,500 blocks in this window will result in downtime jail. The faster you complete the transfer, the fewer blocks your validator will miss.

## Additional resources

For additional resources, refer to
[the extra resources for consensus nodessection of the consensus node page](/operate/consensus-validators/consensus-node#extra-resources-for-consensus-nodes).

## FAQ

### `+2/3 committed an invalid block: wrong Block.Header.Version`

If you encounter an error like:

```bash
2024-04-25 14:48:24 6:48PM ERR CONSENSUS FAILURE!!! err="+2/3 committed an invalid block: wrong Block.Header.Version. Expected {11 1}, got {11 2}" module=consensus stack="goroutine 214 [running]:\nruntime/debug.Stack()\n\t/usr/local/go/src/runtime/debug/stack.go:24 +0x64\ngithub.com/tendermint/tendermint/consensus.(*State).receiveRoutine.func2()\n\t/go/pkg/mod/github.com/celestiaorg/celestia-core@v1.35.0-tm-v0.34.29/consensus/state.go:746 +0x44\npanic({0x1b91180?, 0x400153b240?})\n\t/usr/local/go/src/runtime/panic.go:770 +0x124\ngithub.com/tendermint/tendermint/consensus.(*State).finalizeCommit(0x400065ea88, 0x3)\n\t/go/pkg/mod/github.com/celestiaorg/celestia-core@v1.35.0-tm-v0.34.29/consensus/state.go:1637 +0xd30\ngithub.com/tendermint/tendermint/consensus.(*State).tryFinalizeCommit(0x400065ea88, 0x3)\n\t/go/pkg/mod/github.com/celestiaorg/celestia-core@v1.35.0-tm-v0.34.29/consensus/state.go:1606 +0x26c\ngithub.com/tendermint/tendermint/consensus.(*State).handleCompleteProposal(0x400065ea88, 0x3)\n\t/go/pkg/mod/github.com/celestiaorg/celestia-core@v1.35.0-tm-v0.34.29/consensus/state.go:2001 +0x2d8\ngithub.com/tendermint/tendermint/consensus.(*State).handleMsg(0x400065ea88, {{0x2b30a00, 0x400143e048}, {0x40002a61b0, 0x28}})\n\t/go/pkg/mod/github.com/celestiaorg/celestia-core@v1.35.0-tm-v0.34.29/consensus/state.go:856 +0x1c8\ngithub.com/tendermint/tendermint/consensus.(*State).receiveRoutine(0x400065ea88, 0x0)\n\t/go/pkg/mod/github.com/celestiaorg/celestia-core@v1.35.0-tm-v0.34.29/consensus/state.go:782 +0x2c4\ncreated by github.com/tendermint/tendermint/consensus.(*State).OnStart in goroutine 169\n\t/go/pkg/mod/github.com/celestiaorg/celestia-core@v1.35.0-tm-v0.34.29/consensus/state.go:391 +0x110\n"
```

then it is likely that the network has upgraded to a new app version but your consensus node was not prepared for the upgrade. To fix this, you'll need to update your binary to the latest version and restart your node with the relevant `--v2-upgrade-height` for the network you're running on. If your node still can't sync to the tip of the chain after the above steps, consider a `celestia-appd tendermint reset-state` to reset your node and start syncing from the genesis block.

1. [Optional] Back up your validator keys.
1. [Optional] Back up the `data/priv_validator_state.json` inside your CELESTIA_HOME directory.
1. Remove DBs from your CELESTIA_HOME directory via: `celestia-appd tendermint reset-state`.
1. Remove the `data/application.db` inside your CELESTIA_HOME directory.
1. Download the latest binary for your network.
1. Restart your consensus node with the relevant `--v2-upgrade-height` for the network you're running on.

### `App cannot be started without CometBFT when using the multiplexer`

If you encounter an error like:

```bash
2025-11-13 14:48:24 6:48PM ERR App cannot be started without CometBFT when using the multiplexer.
```

It is possible that one of the historical celestia-app binaries you have downloaded is a multiplexer binary. To resolve you can remove all historical binaries:

```bash
rm -rf ~/.celestia-app/bin
```

Re-download all historical binaries:

```bash
make download-v3-binaries download-v4-binaries download-v5-binaries
```

### `ERR failed to LoadFinalizeBlockResponse err="node is not persisting finalize block responses"`

If you encounter an error like:

```bash
ERR failed to LoadFinalizeBlockResponse err="node is not persisting finalize block responses" module=rpc
```

Then the RPC node you are querying is not persisting finalize block responses. To resolve, you can query a node that _does_ persist finalize block responses.

If you run the node, you can modify the `config.toml` to set `discard_abci_responses = false`:

```toml
[storage]

# Set to true to discard ABCI responses from the state store, which can save a
# considerable amount of disk space. Set to false to ensure ABCI responses are
# persisted. ABCI responses are required for /block_results RPC queries, and to
# reindex events in the command-line tool.
discard_abci_responses = false
```

---
Title: Setting up a Celestia bridge node
URL: https://docs.celestia.org/operate/data-availability/bridge-node.md
Source: app/operate/data-availability/bridge-node/page.mdx
---

# Setting up a Celestia bridge node

This tutorial will go over the steps to set up your Celestia bridge node.

Bridge nodes connect the data availability layer and the consensus layer.

## Overview of bridge nodes

A Celestia bridge node has the following properties:

1. Import and process “raw” headers & blocks from a trusted core process
   (meaning a trusted RPC connection to a consensus node) in the
   Consensus network. Bridge nodes can run this core process internally
   (embedded) or simply connect to a remote endpoint. Bridge nodes also
   have the option of being an active validator in the consensus network.
2. Validate and erasure code the “raw” blocks
3. Supply block shares with data availability headers to light nodes in the DA network.

![bridge-node-diagram](/img/nodes/BridgeNodes.png)

From an implementation perspective, Bridge nodes run two separate processes:

1. celestia-app with celestia-core
   ([see repo](https://github.com/celestiaorg/celestia-app))

   - **celestia-app** is the state machine where the application and the
     proof-of-stake logic is run. celestia-app is built on
     [Cosmos SDK](https://docs.cosmos.network) and also encompasses
     **celestia-core**.
   - **celestia-core** is the state interaction, consensus and block production
     layer. celestia-core is built on [Tendermint Core](https://docs.tendermint.com),
     modified to store data roots of erasure coded blocks among other changes
     ([see ADRs](https://github.com/celestiaorg/celestia-core/tree/master/docs/celestia-architecture)).

2. celestia-node ([see repo](https://github.com/celestiaorg/celestia-node))

   - **celestia-node** augments the above with a separate libp2p network that
     serves data availability sampling requests. The team sometimes refers to
     this as the “halo” network.

## Hardware requirements

See [hardware requirements](/operate/getting-started/hardware-requirements).

## Setting up your bridge node

The following tutorial is done on an Ubuntu Linux 20.04 (LTS) x64 instance machine.

Deploy the Celestia bridge node with the following steps.

### Setup the dependencies

Follow the tutorial for [installing the dependencies](/operate/getting-started/environment-setup).

### Install Celestia Node

Install the `celestia-node` binary, which will be used to run the bridge node.

Follow the tutorial for [installing `celestia-node`](/operate/data-availability/install-celestia-node).

### Initialize the bridge node

Run the following:

```sh
celestia bridge init --core.ip <URI> --core.port <port>
```

After v0.21.5, the `--core.port` must be specified.
In most cases, it is port 9090 by default.

> **Warning:** Make sure port 2121 TCP/UDP is open and publicly accessible on your bridge node so it can be discovered by other peers in the DHT network. This port is essential for P2P connectivity and if not properly configured, your node won't be able to participate in the network effectively.

Refer to
[the ports section of the celestia-node troubleshooting page](/operate/maintenance/troubleshooting#ports)
for information on which ports are required to be open on your machine.

Using an RPC of your own, or one from the
[list on the Mocha testnet page](/operate/networks/mocha-testnet#community-rpc-endpoints),
start your node.

Connecting to a consensus node endpoint (flag: `--core.ip string`)
provides the light node with access to state queries (reading balances, submitting
transactions, and other state-related queries).

Here is an example of initializing the bridge node:

**Mainnet Beta**

```sh
celestia bridge init --core.ip <URI> --core.port <port>
```

**Mocha**

```sh
celestia bridge init --core.ip <URI> --core.port <port> \
    --p2p.network mocha
```

### Run the bridge node

Start the bridge node with a connection to a consensus node's gRPC endpoint, which is usually exposed on port 9090:

```sh
celestia bridge start --core.ip <URI> --core.port <port>
```

Here is an example of starting the bridge node on Mocha:

```sh
celestia bridge start --core.ip <archival-consensus-endpoint> --core.port 9090 --p2p.network mocha
```

Bridge nodes sync headers from genesis and require an archival consensus node. Public RPC endpoints are typically pruned and will not work for initial sync. Use your own archival consensus node or an archival endpoint from an infrastructure provider.

If you're connecting your bridge node to a localhost consensus node (`--core.ip localhost` or `--core.ip 127.0.0.1`), ensure that gRPC is enabled in your consensus node's `app.toml` configuration file. Look for the `[grpc]` section and verify that `enable = true` is set:

```toml
[grpc]
# Enable defines if the gRPC server should be enabled.
enable = true
# Address defines the gRPC server address to bind to.
address = "localhost:9090"
```

Without proper gRPC configuration, the bridge node will not be able to connect to the consensus node.

You can create your key for your node by [following the `cel-key` instructions](/operate/keys-wallets/celestia-node-key).

Once you start the bridge node, a wallet key will be generated for you.
You will need to fund that address with Testnet tokens to pay for
`PayForBlob` transactions.
You can find the address by running the following command:

```sh
./cel-key list --node.type bridge --keyring-backend test --p2p.network <network>
```

You do not need to declare a network for Mainnet Beta. Refer to
[the chain ID section on the troubleshooting page for more information](/operate/maintenance/troubleshooting).

You can get testnet tokens from:

- [Mocha](/operate/networks/mocha-testnet)

> **Note:** If you are running a bridge node for your validator, it is highly recommended to request Mocha testnet tokens as this is the testnet used to test out validator operations.

#### Optional: run the bridge node with a custom key

In order to run a bridge node using a custom key:

1. The custom key must exist inside the celestia bridge node directory at the
   correct path (default: `~/.celestia-bridge/keys/keyring-test`)
2. The name of the custom key must be passed upon `start`, like so:

**Mainnet Beta**

```sh
celestia bridge start --core.ip <URI> --keyring.keyname <name-of-custom-key> \
    --core.port <port>
```

**Mocha**

```sh
celestia bridge start --core.ip <URI> --keyring.keyname <name-of-custom-key> \
    --p2p.network mocha --core.port <port>
```

#### Optional: Migrate node id to another server

To migrate a bridge node ID:

1. You need to back up two files located in the celestia-bridge node directory at the correct path (default: `~/.celestia-bridge/keys`).
2. Upload the files to the new server and start the node.

### Optional: start the bridge node with SystemD

Follow the
[tutorial on setting up the bridge node as a background process with SystemD](/operate/maintenance/systemd).

You have successfully set up a bridge node that is syncing with the network.

### Optional: enable on-fly compression with ZFS

Follow the
[tutorial on how to set up your DA node to use on-fly compression with ZFS](/operate/data-availability/storage-optimization).

---
Title: config.toml guide
URL: https://docs.celestia.org/operate/data-availability/config-reference.md
Source: app/operate/data-availability/config-reference/page.mdx
---

# config.toml guide

## Pre-requisites

Please, make sure that you have installed and initialized `celestia-node`

## Viewing the help menu

In order to view all flags and their descriptions, use:

```bash
celestia light start --help
```

## Understanding config.toml

After initialization, for any type of node, you will find a
`config.toml` in the following path (default location):

- `$HOME/.celestia-bridge/config.toml` for bridge node
- `$HOME/.celestia-light/config.toml` for light node

Let's break down some of the most used sections.

### Core (Consensus)

This section is needed for the Celestia bridge node.
By default, `Remote = false`. Still for devnet, we are going
to use the remote consensus node option and this can also be set
by the command line flag `--core.remote`.

### RPC

Starting with celestia-node v0.31.3, the RPC server supports optional per-IP
rate limiting. If you upgraded an existing node from an earlier version, add
the new fields while preserving your custom configuration by running:

```bash
celestia <node_type> config-update --p2p.network <network>
```

The default rate-limit configuration is:

```toml
[RPC.RateLimit]
  Enabled = false
  RequestsPerSec = 100
  Burst = 200
  CacheSize = 8192
```

- `Enabled` turns per-IP rate limiting on or off.
- `RequestsPerSec` sets the sustained request rate allowed for each IP address.
- `Burst` allows short request spikes before the sustained rate is enforced.
- `CacheSize` limits the number of per-IP rate-limit buckets held in memory.

When the limit is exceeded, the RPC server responds with HTTP status `429 Too
Many Requests`. Leave this rate limiter disabled when the node is behind a
reverse proxy because all requests may appear to come from the proxy's IP
address. Apply rate limiting at the proxy instead.

RPC request bodies are limited to 16 MiB, and the server accepts up to 500
concurrent connections. These limits are enforced by the server and are not
configurable in `config.toml`.

See the [celestia-node v0.31.3 release notes](https://github.com/celestiaorg/celestia-node/releases/tag/v0.31.3)
for the complete upgrade instructions.

### P2P

#### Bootstrap

Bootstrappers help new nodes to find peers faster in the network.
By default, the `Bootstrapper = false` and the `BootstrapPeers` is empty.
If you want your node to be a bootstrapper, then activate `Bootstrapper = true`.
`BootstrapPeers` are already provided by default during initialisation.
If you want to add your own manually, you need to provide the
multiaddresses of the peers.

#### Mutual peers

The purpose of this config is to set up a bidirectional communication.
This is usually the case for Celestia bridge nodes. In addition, you
need to change the field `PeerExchange` from false to true.

### Services

#### TrustedHash and TrustedPeer

`TrustedHash` is needed to properly initialize a Celestia bridge
node with an already-running `Remote` Celestia consensus node. Celestia
light node will take a genesis hash as the trusted one, if no hash
is manually provided during initialization phase.

`TrustedPeers` is the array of bridge nodes' peers that Celestia
light node trusts. By default, bootstrap peers becomes trusted peers
for Celestia light nodes if a user is not setting the trusted peer params
in config file.

Any Celestia bridge node can be a trusted peer for the light one. However,
the light node by design can not be a trusted peer for another light node.

---
Title: Custom networks and values
URL: https://docs.celestia.org/operate/data-availability/custom-networks.md
Source: app/operate/data-availability/custom-networks/page.mdx
---

# Custom networks and values

This section will cover importing bootstrapper IDs, chain ID,
and network ID. This will allow you to import custom values
for a chain that is not in the default configuration.

If you have a custom network you can export `CELESTIA_CUSTOM`, which will
look something like:

```bash
export BRIDGE="/ip4/<ip-address>/tcp/2121/p2p/<node-ID>"
export GENESIS_HASH=<genesis-hash>
export NETWORK=<network-name>
export CELESTIA_CUSTOM="${NETWORK}:${GENESIS_HASH}:${BRIDGE}"
```

Query your node ID [from the CLI](/operate/data-availability/light-node/advanced#find-your-node-id).
These values with examples would look like:

```bash
export BRIDGE="/ip4/151.115.14.33/tcp/2121/p2p/12D3KooWKEeRtzVMPUdxYsZo2edqps6mS67n6LT5mPdULSkPSxBQ"
export GENESIS_HASH=580B3DFF8A7C716968161D91116A1E171F486298D582874E93714E489C9E6E88
export NETWORK=custom
export CELESTIA_CUSTOM="${NETWORK}:${GENESIS_HASH}:${BRIDGE}"
```

Then, start your node with:

```bash
celestia <node-type> start [flags...]
```

---
Title: IBC relaying guide
URL: https://docs.celestia.org/operate/data-availability/ibc-relayer.md
Source: app/operate/data-availability/ibc-relayer/page.mdx
---

# IBC relaying guide

Celestia uses [IBC](https://ibcprotocol.dev/) to enable cross-chain token transfers. Relayers scan for outbound packets on one chain and submit them with proofs on the destination chain. This guide shows how to set up a relayer and create connections using Hermes between Celestia Mocha testnet and Cosmos Hub theta-testnet-001.

There are two standard relayer implementations:

- [Hermes](https://hermes.informal.systems/) (Rust)
- [Go Relayer](https://pkg.go.dev/github.com/cosmos/relayer) (Go)

Check the [latest celestia-app release's `go.mod`](https://github.com/celestiaorg/celestia-app/blob/2b8cc9e23826ccb658b7dd5aa6cd51a0921a0c29/go.mod#L35) for the ibc-go version in use.

## Hermes

[Hermes](https://github.com/informalsystems/hermes) is an open-source Rust relayer. Follow the [Hermes Quick Start](https://hermes.informal.systems/quick-start/) to install, then verify with `hermes version`.

Hermes currently doesn't support configuring Tendermint `CompatMode` in chain config. Use Hermes [v1.7.0+](https://github.com/informalsystems/hermes/releases/tag/v1.7.0), which falls back to Tendermint `CompatMode` v0.34 (compatible with Celestia).

### Configuration

After installing Hermes, edit `config.toml` to add your chains. This tutorial uses:

- Celestia `mocha-5` testnet
- Cosmos Hub `theta-testnet-001` testnet

Edit the Hermes configuration:

```bash
vim $HOME/.hermes/config.toml
```

```toml
[global]
log_level = "info"

[mode.clients]
enabled = true
refresh = true
misbehaviour = true

[mode.connections]
enabled = false

[mode.channels]
enabled = false

[mode.packets]
enabled = true
clear_interval = 100
clear_on_start = true
tx_confirmation = false
auto_register_counterparty_payee = false

[rest]
enabled = false
host = "127.0.0.1"
port = 3000

[telemetry]
enabled = false
host = "127.0.0.1"
port = 3001

[telemetry.buckets.latency_submitted]
start = 500
end = 20000
buckets = 10

[telemetry.buckets.latency_confirmed]
start = 1000
end = 30000
buckets = 10

[[chains]]
id = "theta-testnet-001"
type = "CosmosSdk"
rpc_addr = "https://rpc.sentry-01.theta-testnet.polypore.xyz"
grpc_addr = "https://grpc.sentry-01.theta-testnet.polypore.xyz"
rpc_timeout = "10s"
trusted_node = false
account_prefix = "cosmos"
key_name = "key-cosmos"
key_store_type = "Test"
store_prefix = "ibc"
default_gas = 100000
max_gas = 400000
gas_multiplier = 1.5
max_msg_num = 30
max_tx_size = 180000
max_grpc_decoding_size = 33554432
clock_drift = "5s"
max_block_time = "30s"
ccv_consumer_chain = false
memo_prefix = ""
sequential_batch_tx = false

[chains.event_source]
mode = "push"
url = "ws://rpc.sentry-01.theta-testnet.polypore.xyz:26657/websocket"
batch_delay = "500ms"

[chains.trust_threshold]
numerator = "1"
denominator = "3"

[chains.gas_price]
price = 0.025
denom = "uatom"

[chains.packet_filter]
policy = "allow"
list = [["transfer", "channel-3108"]]

[chains.packet_filter.min_fees]

[chains.address_type]
derivation = "cosmos"

[[chains]]
id = "mocha-5"
type = "CosmosSdk"
rpc_addr = "https://public-endpoint.celestia-mocha.quiknode.pro"
grpc_addr = "https://grpc.celestia-mocha.com:443"
rpc_timeout = "10s"
trusted_node = false
account_prefix = "celestia"
key_name = "celestia-key"
key_store_type = "Test"
store_prefix = "ibc"
default_gas = 100000
max_gas = 400000
gas_multiplier = 1.5
max_msg_num = 30
max_tx_size = 180000
max_grpc_decoding_size = 33554432
clock_drift = "5s"
max_block_time = "30s"
ccv_consumer_chain = false
memo_prefix = ""
sequential_batch_tx = false

[chains.event_source]
mode = "push"
url = "wss://public-endpoint.celestia-mocha.quiknode.pro/websocket"
batch_delay = "500ms"

[chains.trust_threshold]
numerator = "1"
denominator = "3"

[chains.gas_price]
price = 0.1
denom = "utia"

[chains.packet_filter]
policy = "allow"
list = [["transfer", "channel-0"]]

[chains.packet_filter.min_fees]

[chains.address_type]
derivation = "cosmos"
```

### Add relayer wallets

Import and fund wallets for both chains (native tokens required). Faucets:

- Celestia: [discord.gg](https://discord.com/invite/YsnTPcSfWQ)
- Cosmos Hub: [discord.gg/cosmosnetwork](https://discord.gg/cosmosnetwork)

Add Cosmos wallet:

```bash
hermes keys add --key-name key-cosmos --chain theta-testnet-001 --mnemonic-file $HOME/.hermes/key-cosmos-mnemonic.txt
```

Add Celestia wallet:

```bash
hermes keys add --key-name celestia-key --chain mocha-5 --mnemonic-file $HOME/.hermes/key-celestia-mnemonic.txt
```

### Create a channel

With both chains configured and wallets funded, create a channel:

```bash
hermes create channel --a-chain theta-testnet-001 --b-chain mocha-5 --a-port transfer --b-port transfer --new-client-connection
```

This command creates:
- New clients on both chains
- A connection between them
- A channel on the `transfer` port

### Relay packets

Start relaying packets on the channel:

```bash
hermes start
```

Hermes will now relay IBC packets between Mocha testnet and Cosmos Hub theta-testnet-001.

---
Title: Install celestia-node
URL: https://docs.celestia.org/operate/data-availability/install-celestia-node.md
Source: app/operate/data-availability/install-celestia-node/page.mdx
---

# Install celestia-node

## Supported architectures

Celestia-node officially supports the following architectures:

- linux/amd64
- linux/arm64
- darwin/amd64 (macOS Intel)
- darwin/arm64 (macOS Apple Silicon)

Only these four architectures are officially tested and supported.

## Installing from source

This section goes over building and installing celestia-node. This
tutorial assumes you completed the steps in
[setting up your development environment](/operate/getting-started/environment-setup).

Install the celestia-node binary by running the following
commands:

### Remove any existing copy and clone

   ```bash
   cd $HOME
   rm -rf celestia-node
   git clone https://github.com/celestiaorg/celestia-node.git
   cd celestia-node/
   ```

### Check out the desired version

**Mainnet Beta**

```bash
git checkout tags/v0.34.3
```

**Mocha**

```bash
git checkout tags/v0.34.3-mocha
```

### Build the `celestia` binary

   a. Standard build

   ```bash
   make build
   ```

   b. Experimental build (optional)

   If you're a node operator comfortable with experimental features and seeking optimal performance with minimal RAM usage, this option is recommended for you.

   ```bash
   make build-jemalloc
   ```

   This build option enables CGO, and downloads and installs [jemalloc](https://jemalloc.net/). [Learn more about the build command](https://github.com/celestiaorg/celestia-node/releases/tag/v0.12.1#:~:text=%F0%9F%8F%97%EF%B8%8F-,New%20build%20option,-%3A%20Makefile%20now%20has).

### Install the binary

   ```bash
   make install
   ```

### Build and install the `cel-key` utility

   ```bash
   make cel-key
   make install-key
   ```

### Verify the installation

   ```bash
   celestia version
   ```

The output will show the semantic version of celestia-node,
commit hash, build date, system version, and Golang version.

## Installing a pre-built binary

Installing a pre-built binary is the fastest way to get started with your Celestia data availability node. Releases after celestia-node v0.13.3 have these binaries available.

The installation script will download a binary file named `celestia`. Depending on your environment and chosen installation option, the `celestia` binary will be available at one of these locations:

- The Homebrew bin directory (usually `/opt/homebrew/bin/celestia` on Apple silicon or `/usr/local/bin/celestia` on Intel Macs) when Go is installed with Homebrew
- `$GOBIN/celestia`, or `$GOPATH/bin/celestia` when `GOBIN` is unset, for other Go installations
- `/usr/local/bin/celestia`
- `$HOME/celestia-node-temp/celestia`

Pre-built binaries are available for:

- Operating systems: Darwin (Apple), Linux
- Architectures: x86_64 (amd64), arm64

### Installation options

Pass the `-v` flag to install the recommended version for your network:

**Mainnet Beta**

```bash
bash -c "$(curl -sL https://docs.celestia.org/celestia-node.sh)" -- -v v0.34.3
```

**Mocha**

```bash
bash -c "$(curl -sL https://docs.celestia.org/celestia-node.sh)" -- -v v0.34.3-mocha
```

If you omit `-v`, the script installs the
[latest stable GitHub release](https://github.com/celestiaorg/celestia-node/releases/latest).
This does not select a version for your network and excludes releases marked as
pre-releases, including Mocha releases. Use the network-specific command above.

The script will:

1. Detect your system's operating system and architecture
2. Download the appropriate binary
3. Verify the checksum for security
4. Provide installation location options based on your environment:
   - If Go is installed:
     - Detected Go bin directory (the Homebrew bin directory when Go is installed with Homebrew, otherwise `$GOBIN` or `$GOPATH/bin`)
     - System bin directory (`/usr/local/bin`)
     - Keep in current directory
   - If Go is not installed:
     - System bin directory (`/usr/local/bin`)
     - Keep in current directory

Follow the instructions in the terminal output to choose your installation preferences. After installation, you can verify the setup by checking the version:

```bash
celestia version && celestia --help
```

View [the script](https://github.com/celestiaorg/docs/blob/main/public/celestia-node.sh) to learn more about what it is doing.

> **Note**: The script maintains a log file at `$HOME/celestia-node-temp/logfile.log` for troubleshooting purposes.

## Next steps

First, we recommend [reading the overview](/operate/getting-started/hardware-requirements)
of our node types, if you haven't yet.

Now that you've installed Celestia Node, it's time to
[pick your node type](/operate/getting-started/overview) and run your node!

If you're planning to run a light node,
we recommend the [quick-start guide](/operate/data-availability/light-node/quickstart/).

## Upgrading your binary

To upgrade your binary, install the recommended version for your network using
the instructions above.

When upgrading from a version earlier than celestia-node v0.31.3 to v0.31.3 or later, update the node configuration after replacing the binary and before starting the node:

```bash
celestia <node_type> config-update --p2p.network <network>
```

The [v0.31.3 release](https://github.com/celestiaorg/celestia-node/releases/tag/v0.31.3) adds support for Mainnet Beta v9 and introduces new config fields. The command merges those fields into the existing configuration while preserving custom values. Review your configuration after the update, then start the node. If you run into any issues, refer to the [troubleshooting section](/operate/maintenance/troubleshooting#resetting-your-config).

---
Title: Advanced
URL: https://docs.celestia.org/operate/data-availability/light-node/advanced.md
Source: app/operate/data-availability/light-node/advanced/page.mdx
---

# Advanced

This page collects advanced topics for Celestia light nodes. For
setup and blob posting, see
[Getting started](/operate/data-availability/light-node/quickstart).

---

## Start light node with consensus endpoint authentication

If the consensus node gRPC endpoint you connect to requires authentication, pass
a directory containing `xtoken.json`:

```bash
celestia light start \
  --core.ip snowy-methodical-leaf.celestia-mainnet.quiknode.pro \
  --core.tls \
  --core.xtoken.path /path-to-directory \
  --core.port 9090
```

Where `/path-to-directory` contains `xtoken.json` (recommended: `chmod 600`):

```json
{
  "x-token": "<YOUR-SECRET-X-TOKEN>"
}
```

---

## Run the light node with a custom key

To use a non-default key, make sure the key exists in your node store and pass
`--keyring.keyname` on `start`:

For key creation, backup, import/recover, and Docker setups, see
[Create a wallet with celestia-node](/operate/keys-wallets/celestia-node-key).

**Mainnet Beta**

```bash
celestia light start --core.ip <URI> --core.port <port> \
  --keyring.keyname <name-of-custom-key>
```

**Mocha**

```bash
celestia light start --core.ip <URI> --core.port <port> \
  --keyring.keyname <name-of-custom-key> --p2p.network mocha
```

---

## Run the light node with SystemD

Follow the tutorial for running Celestia Node as a background process with
SystemD:
[/operate/maintenance/systemd#celestia-light-node](/operate/maintenance/systemd#celestia-light-node).

---

## Fast sync with a trusted hash

Setting and syncing to a trusted height and hash means your light node will not
sample the entire chain from genesis. This is useful when you want to sync your
light node quickly.

This adds the trust assumption that you trust the source of the height and
hash.

Celestia also supports initializing from a trusted hash via
[trusted hash recovery](/operate/maintenance/trusted-hash-recovery).

### Get a trusted height and hash

This example uses the public Quicknode Mocha endpoint. The `/block` response
provides the height and hash of the same block:

```bash
read -r TRUSTED_HEIGHT TRUSTED_HASH <<<"$(curl -s https://public-endpoint.celestia-mocha.quiknode.pro/block | jq -r '.result | "\(.block.header.height) \(.block_id.hash)"')" && export TRUSTED_HEIGHT TRUSTED_HASH
printf 'SyncFromHeight = %s\nSyncFromHash = "%s"\n' "$TRUSTED_HEIGHT" "$TRUSTED_HASH"
```

### Set `SyncFromHeight` and `SyncFromHash`

Edit your config file at `~/.celestia-light-mocha-5/config.toml`
and set `SyncFromHeight` and `SyncFromHash` to the values printed above. For example:

```toml
SyncFromHeight = 123456
SyncFromHash = "E8BD0C48260C496BB7A4D8D1E7BDBF1F26A2FE3CF5714DECE1741B2FFB3C095C"
```

Ensure `SyncFromHash` has **no `0x` prefix**.

### Start the node

```bash
celestia light start --p2p.network mocha \
  --core.ip public-endpoint.celestia-mocha.quiknode.pro \
  --core.port 9090 --core.tls
```

---

## High throughput transaction submission

Celestia supports three transaction submission modes that affect how
transactions are queued and submitted, impacting throughput and ordering
guarantees. These modes are controlled by the `TxWorkerAccounts` setting in your
light node's `config.toml` file.

### Default mode (TxWorkerAccounts = 0)

This is the default behavior. Transactions are submitted immediately without a
queue.

**Characteristics:**

- Transactions enter the mempool immediately
- No queuing or waiting for confirmations
- Potential sequence number conflicts if submitting multiple transactions quickly
- Same behavior as versions prior to v0.28.2

### Queued mode (TxWorkerAccounts = 1)

Enable synchronous, ordered submission by setting `TxWorkerAccounts` to `1` in
your `config.toml`.

#### Open your config file

```bash
nano ~/.celestia-light-mocha-5/config.toml
```

#### Set TxWorkerAccounts to 1

Find the `[SubmitClient]` section and add or update:

```toml
[SubmitClient]
TxWorkerAccounts = 1
```

#### Restart your node

```bash
celestia light start --p2p.network mocha \
  --core.ip public-endpoint.celestia-mocha.quiknode.pro \
  --core.port 9090 --core.tls
```

**Characteristics:**

- Each transaction queues until the previous one is confirmed
- Preserves strict ordering of transactions based on submission time
- Avoids sequence mismatch errors
- Throughput: approximately 1 PayForBlobs transaction every other block

**Use case:** Applications requiring strict transaction ordering

### Parallel mode (TxWorkerAccounts > 1)

For high-throughput applications that don't require sequential ordering, enable
parallel submission by setting `TxWorkerAccounts` to a value greater than 1.

#### Open your config file

```bash
nano ~/.celestia-light-mocha-5/config.toml
```

#### Set TxWorkerAccounts to desired number of lanes

Find the `[SubmitClient]` section and add or update:

```toml
[SubmitClient]
TxWorkerAccounts = 8
```

#### Restart your node

```bash
celestia light start --p2p.network mocha \
  --core.ip public-endpoint.celestia-mocha.quiknode.pro \
  --core.port 9090 --core.tls
```

**How it works:**

- Creates `TxWorkerAccounts` parallel submission lanes
- Each lane is a subaccount automatically created and funded from your default account
- Example: `TxWorkerAccounts = 8` creates 7 subaccounts + 1 default account = 8 parallel lanes
- Enables at least 8 PayForBlobs transactions per block

**Characteristics:**

- Transactions can be submitted concurrently across multiple lanes
- Does NOT guarantee transaction ordering
- Blobs may be included in blocks in a different order than submitted
- Higher throughput for applications that can handle unordered transactions

**Use case:** High-throughput, unordered workflows

  **Important:** When retrieving blobs submitted in parallel mode, you must
  track the height, namespace, and commitment for each blob submission, as you
  won't know which subaccount was used.

**Subaccount management:**

- Subaccounts are automatically created and funded from your default account
- They are named `parallel-worker-1`, `parallel-worker-2`, etc. in your keyring
- Subaccounts are reused across node restarts if `TxWorkerAccounts` value remains the same
- If you decrease `TxWorkerAccounts`, only the first N workers are used
- If you increase `TxWorkerAccounts`, additional workers are created

### Comparison table

| Mode     | TxWorkerAccounts | Ordering       | Throughput       | Use case                                 |
| -------- | ---------------- | -------------- | ---------------- | ---------------------------------------- |
| Default  | 0                | Not guaranteed | Immediate        | Simple applications, single transactions |
| Queued   | 1                | Guaranteed     | ~1 tx per block  | Applications requiring strict ordering   |
| Parallel | >1               | Not guaranteed | ≥N txs per block | High-throughput, unordered workflows     |

---

## Node store contents

The node store is created during `celestia light init` and lives under
`~/.celestia-<node-type>-<network>`.

For example, a Mocha light node store at `~/.celestia-light-mocha-5` contains:

- `config.toml`: Node configuration settings
- `data/`: Database files
- `keys/`: Node identity and account keys

---

## Get your auth token

Your auth token is useful when you want to interact with your Celestia light
node from another machine or a client application. Generate an admin token with:

```bash
celestia light auth admin --p2p.network mocha
```

Each time you run this, you will receive a new token. It's not possible to
revoke tokens once they are issued.

Use `celestia light auth --help` to learn more about the available options.

---

## Find your node ID

Your node ID is your libp2p peer ID. You’ll need it when creating multiaddrs
(for example, `.../p2p/<node-ID>`).

While your node is running, run:

```bash
celestia p2p info
```

See also `p2p.Info` in the [Node API `p2p` section](/build/rpc/node-api/#p2p).

---

## Migrate node ID to another server

If you want the new machine to keep the same node identity, back up the
identity material from your node store (for example, the `keys/` directory under
`~/.celestia-light-<network>/`) and restore it on the new machine before
starting the node.

---

## Pruning windows

If you need data older than your current pruning windows, use
`SyncFromHeight`/`SyncFromHash` to re-sync from an earlier point in time.

- Sampling window: 7 days ([v0.25.3 release notes](https://github.com/celestiaorg/celestia-node/releases/tag/v0.25.3))
- Header pruning window: 14 days ([v0.26.4 release notes](https://github.com/celestiaorg/celestia-node/releases/tag/v0.26.4))

---

## Advanced key management with `cel-key`

For key management beyond the built-in capabilities of the light node, use the
separate `cel-key` utility. This dedicated tool allows you to create, import,
and manage keys, and to select which key your node uses.

See [Create a wallet with celestia-node](/operate/keys-wallets/celestia-node-key).

---
Title: Light node: overview & quickstart
URL: https://docs.celestia.org/operate/data-availability/light-node/quickstart.md
Source: app/operate/data-availability/light-node/quickstart/page.mdx
---

# Light node: overview & quickstart

Celestia light nodes perform data availability sampling (DAS) to verify that
block data is available without downloading it all. They can also post and
retrieve blobs (data) from the Celestia network.

## Overview

Light nodes are the most common way to interact with Celestia networks.

![light-node](/img/nodes/LightNodes.png)

Light nodes:

1. Listen for `ExtendedHeaders` (block headers + DA metadata).
2. Perform DAS on received headers.

## Optional: run a light node in your browser

You can run Lumina in your browser on the decentralized explorer,
[Celenium](https://celenium.io).

<img
  width="1000"
  alt="Celenium running a light node with Lumina"
  src="https://github.com/user-attachments/assets/28183a24-8bb1-4f77-850c-d0528de075c7"
/>

## Run a light node (CLI)

This guide assumes you've completed:

- [Hardware requirements](/operate/getting-started/hardware-requirements)
- [Environment setup](/operate/getting-started/environment-setup)

### Install `celestia-node`

Follow the [Install celestia-node](/operate/data-availability/install-celestia-node)
guide (from source or using the pre-built binary installer).

### Initialize the node store

This creates the node store and a key for the network you choose.

Want to sync faster (skip sampling from genesis)? See
[Fast sync with a trusted hash](/operate/data-availability/light-node/advanced#fast-sync-with-a-trusted-hash).

**Mainnet Beta**

```bash
celestia light init
```

**Mocha**

```bash
celestia light init --p2p.network mocha
```

### Start the light node

Light nodes connect to a consensus node **gRPC** endpoint (usually port `9090`)
for state access (balances, submitting `PayForBlobs`, etc.).

**Mainnet Beta**

```bash
celestia light start \
  --core.ip public-endpoint.celestia-mainnet.quiknode.pro \
  --core.port 9090 --core.tls --p2p.network celestia
```

**Mocha**

```bash
celestia light start \
  --core.ip public-endpoint.celestia-mocha.quiknode.pro \
  --core.port 9090 --core.tls --p2p.network mocha
```

You can use any consensus node gRPC endpoint listed on
either [Mainnet Beta](/operate/networks/mainnet-beta#integrations) or
[Mocha testnet](/operate/networks/mocha-testnet#community-data-availability-da-grpc-endpoints-for-state-access).

If you're running on a server, make sure required ports are open. See
[Troubleshooting ports](/operate/maintenance/troubleshooting#ports).

### Get some testnet tokens (for blob posting)

To submit blobs on testnets, fund your light node address:

```bash
celestia state account-address
```

Then use a faucet:

- [Mocha faucet](/operate/networks/mocha-testnet#mocha-testnet-faucet)

On Mainnet Beta, fund this address with TIA to submit blobs.

### Check your balance (optional)

```bash
celestia state balance
```

### Post your first blob

Use `celestia blob submit <namespace> <data>` to post your first blob.
The example below uses a hex-encoded namespace and `0x`-prefixed hex data
to submit the text `gm`:

```bash
celestia blob submit 0x676d 0x676d
```

Keep the `0x` prefix when passing hex-encoded data. This explicit-hex form
works both before and after the blob submission fix in celestia-node #5262.
On builds containing that fix, unprefixed data is submitted as literal text:
`hello` submits `hello`, and `cafe` submits the four characters `cafe`.

Save the returned `height` and the first value in `commitments`. Commitments
are still returned as `0x`-prefixed hex strings.

### Retrieve your first blob

Replace `<height>` and `<commitment>` with the values from `blob submit`:

```bash
celestia blob get <height> 0x676d <commitment>
```

The returned `data` field should be `"gm"`.

If you see `header: syncing in progress`, wait for the node to sync or use
[fast sync](/operate/data-availability/light-node/advanced#fast-sync-with-a-trusted-hash).

## Next steps

- More operations and configuration: [Advanced](/operate/data-availability/light-node/advanced)
- Submitting blobs from an app: [Submit data](/learn/TIA/submit-data)

---
Title: celestia-node metrics
URL: https://docs.celestia.org/operate/data-availability/metrics.md
Source: app/operate/data-availability/metrics/page.mdx
---

# celestia-node metrics

This tutorial is for running metrics for your celestia-node data
availability instance. This tutorial will focus on running metrics for a light node.

This tutorial assumes you have already setup your light node
by following the tutorial in the
[light node guide](/operate/data-availability/light-node/quickstart).

## Running metrics flags

You can enable the `celestia-node` metric flags with the following
command:

```sh
celestia <node-type> start --metrics.tls=<boolean> \
    --metrics --metrics.endpoint <URI> \
    --p2p.network <network> \
    --core.ip <URI> --core.port <port>
```

Add metrics flags to your node start command and restart your node to apply it.
The metrics endpoint will gather your node's data to track your uptime.

Note that the `--metrics` flag enables metrics and expects
an input into `--metrics.endpoint`.

We will go over what the endpoint will need to be in the
[metrics endpoint design considerations](#metrics-endpoint-design-considerations)
section.

### Mainnet Beta

Here is an example for Mainnet Beta:

```sh
celestia <node-type> start --metrics.tls=true \
    --metrics --metrics.endpoint otel.celestia.observer \
    --core.ip <URI> --core.port <port>
```

### Mocha testnet

Here is an example for Mocha testnet:

```sh
celestia <node-type> start --metrics.tls=true \
    --metrics --metrics.endpoint otel.mocha.celestia.observer \
    --core.ip <URI> --core.port <port> --p2p.network mocha
```

### TLS connections

The `--metrics.tls` flag enables or disables a TLS connection to the
OpenTelemetry Protocol metrics backend. You need to choose a boolean
value (`true` or `false`) for this flag.

It's also common to set this flag to `false` when spinning up a local
collector
to check the metrics locally.

However, if the collector is hosted in the cloud as a separate entity
(like in a DevOps environment), enabling TLS is a necessity for secure
communication.

Here are examples of how to use it:

```bash
# To enable TLS connection
celestia <node-type> start --metrics.tls=true --metrics \
    --metrics.endpoint <URI> \
    --p2p.network <network> --core.ip <URI> --core.port <port>

# To disable TLS connection
celestia <node-type> start --metrics.tls=false --metrics \
    --metrics.endpoint <URI> \
    --p2p.network <network> --core.ip <URI> --core.port <port>
```

## DAS sampling head lag

Use `das_sampling_head_lag` to monitor how far data availability sampling (DAS)
is behind the network head known to your node. Enable metrics with the flags
above and view the gauge in your metrics backend.

> This metric requires a celestia-node build that includes
> [celestia-node #5307](https://github.com/celestiaorg/celestia-node/pull/5307).
> The change is merged but is not included in a published release as of
> 5 October 2026.

The gauge reports `max(NetworkHead - SampledChainHead, 0)` in headers.
`SampledChainHead` is the head of the continuously sampled chain. For example,
a network head of 100 and a sampled chain head of 90 produce a lag of 10.
This measures a difference in height, not elapsed time.

A sustained or growing positive value means sampling remains behind the node's
known network head; check the node logs for sampling errors. A value of zero means
the sampled chain head has reached or exceeded that known head. It does not
by itself prove the node has the latest network header.

If the metric is missing, check that your build includes the change and that
metrics are enabled and reaching your collector.

## Metrics endpoint design considerations

At the moment, the architecture of celestia-node metrics
works as specified in the following [ADR #010](https://github.com/celestiaorg/celestia-node/blob/main/docs/adr/adr-010-incentivized-testnet-monitoring.md).

Essentially, the design considerations here will necessitate
running an OpenTelemetry (OTEL) collector that connects to Celestia
light node.

For an overview of OTEL, check out [the guide](https://opentelemetry.io/docs/collector).

The ADR and the OTEL docs will help you run your collector on the metrics endpoint.
This will then allow you to process the data in the collector on a
Prometheus server which can then be viewed on a Grafana dashboard.

In the future, we do want to open-source some developer toolings around
this infrastructure to allow for node operators to be able to monitor
their data availability nodes.

### Configure celestia-node to export to multiple OTEL collectors

It is not supported to directly export metrics to multiple OTEL collectors (see the discussions [here](https://github.com/open-telemetry/opentelemetry-go/issues/3055)). To achieve this goal, an agent OTEL collector needs to be deployed for the node, from which the metrics can be forwarded to any other OTEL collectors. Here are the necessary steps and example configurations.

Follow the instructions [here](https://opentelemetry.io/docs/collector/installation/) to install the OTEL collector. If you have the binary installed in `/usr/local/bin/otelcol`, you may consider creating a systemd service to run the collector as a background service. Here is an example of a systemd service definition in `/etc/systemd/system/otelcol.service`:

```ini
[Unit]
Description=OpenTelemetry Collector
After=network.target

[Service]
ExecStart=/usr/local/bin/otelcol --config /path/to/otelcol_config.yaml
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

The following is an example of the `otelcol_config.yaml` file that transforms the metrics into Prometheus metrics and reports them to the Celestia OTEL collector at the same time:

```yaml
receivers:
  otlp:
    protocols:
      http: # Enable HTTP receiving
        endpoint: "127.0.0.1:4318" # the endpoint where the celestia-node will send metrics (the default value of --metrics.endpoint for celestia when --metrics is specified)
exporters:
  prometheus:
    # the node metrics will be transformed to Prometheus format and exposed on the following endpoint
    endpoint: "0.0.0.0:8889"
    namespace: "celestia"
  otlphttp:
    # report the metrics to Mocha testnet OTEL collector as an example
    # change it according to your network
    endpoint: https://otel.mocha.celestia.observer

service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [prometheus, otlphttp]
```

Run the following commands to enable the OTEL collector systemd service:

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now otelcol.service

# check the status of the service
sudo systemctl status otelcol.service
```

If the collector is up and running without any error, you can adjust the options for the `celestia-node` service:

```sh
celestia <node-type> start --metrics.tls=false \
    --metrics --metrics.endpoint localhost:4318 \
    ...
```

---
Title: Optional: Setting up your DA node to use ZFS
URL: https://docs.celestia.org/operate/data-availability/storage-optimization.md
Source: app/operate/data-availability/storage-optimization/page.mdx
---

# Optional: Setting up your DA node to use ZFS

> **Warning:**
Using ZFS compression may impact node performance depending on your hardware configuration. Ensure your system meets the recommended requirements before proceeding. This is an optional optimization that may not be suitable for all deployments.

Enabling ZFS compression on a DA Node server can significantly optimize storage efficiency by compressing data on the fly. Follow this step-by-step guide to implement ZFS compression without requiring any additional tuning on the DA node.

> **Note:** ZFS compression `zstd-3` example:

```
$ zfs get compressratio celestia && du -h /celestia/bridge/.celestia-bridge
NAME             PROPERTY       VALUE  SOURCE
celestia         compressratio  1.22x  -
1.3T    /celestia/bridge/.celestia-bridge
```

> EXT4, no compression:

```
$ du -h ~/.celestia-bridge/
1.8T    /home/ubuntu/.celestia-bridge/
```

## Requirements

1. A bare metal server with:
   - RAM: 64GB or more
   - CPU: Latest generation EPYC or Xeon with:
     - Clock speed: 2.1GHz or higher
     - Threads: 32 or higher
     - Note: Additional CPU overhead is required for ZFS compression
2. At least one empty disk (with no filesystem)

## Guide

Get your disk name:

```sh
lsblk --nodeps -o name
```

Verify disk is empty (should show no partitions):

```sh
lsblk YOUR_DISK_NAME (/dev/nvme0n1 or /dev/sda i.e.)
```

Verify disk is not mounted:

```sh
mount | grep YOUR_DISK_NAME
```

Set variables:

```sh
ZFS_POOL_NAME="celestia" && ZFS_DATASET_NAME="bridge"
```

Validate variables are set:

```sh
if [ -z "$ZFS_POOL_NAME" ] || [ -z "$ZFS_DATASET_NAME" ]; then
  echo "Error: Variables not set correctly"
  exit 1
fi
```

Install ZFS utils:

```sh
sudo apt update && sudo apt install zfsutils-linux
```

Create ZFS pool:

```sh
zpool create -o ashift=12 $ZFS_POOL_NAME /dev/nvme0n1
```

> **Note:** If you have more than one disk available, you can add them also:

```sh
zpool create -o ashift=12 $ZFS_POOL_NAME /dev/nvme0n1 /dev/nvme1n1
```

Verify pool status:

```sh
zpool status $ZFS_POOL_NAME
```

Verify pool properties:

```sh
zpool get all $ZFS_POOL_NAME
```

Create dataset:

```sh
zfs create $ZFS_POOL_NAME/$ZFS_DATASET_NAME
```

Enable compression:

```sh
zfs set compression=zstd-3 $ZFS_POOL_NAME/$ZFS_DATASET_NAME
```

Set the custom path to the bridge data folder:

**Mainnet Beta**

```sh
# Add flag --node.store /celestia/bridge/.celestia-bridge to your command, example:
celestia bridge start --metrics.tls=true --metrics --metrics.endpoint otel.celestia.observer --p2p.metrics --node.store /celestia/bridge/.celestia-bridge
```

**Mocha**

```sh
# Add flag --node.store /celestia/bridge/.celestia-bridge-mocha-5 to your command, example:
celestia bridge start --metrics.tls=true --metrics --metrics.endpoint otel.mocha.celestia.observer --p2p.metrics --node.store /celestia/bridge/.celestia-bridge-mocha-5 --p2p.network mocha
```

> **Note:** It is recommended to sync from scratch. In case of using a snapshot it is important to have your local route to `--data.store` identical to one in a snapshot.

After completing the steps above, you can begin syncing your DA node.

You can check your compression rate with the following command:

```sh
zfs get compressratio $ZFS_POOL_NAME
```

## ZFS Fine-Tuning (Advanced)

> **Warning:**
The following settings can significantly impact data integrity and system stability. Only proceed if you fully understand the implications of each setting. These optimizations should be carefully tested in a non-production environment first.
If you want to increase your I/O performance and sync speed, you can try the following steps:

### Disable Auto-Trim

Auto-trim disabling can improve I/O performance, but may lead to increased SSD wear over time.

```sh
sudo zpool set autotrim=off $ZFS_POOL_NAME
```

> **Note:** You can always trim manually: `sudo zpool trim $ZFS_POOL_NAME`

### Disable sync

> **Warning:**
Disabling sync provides faster write speeds but significantly increases the risk of data corruption in case of system crashes or power failures. Data in memory may be permanently lost before being written to disk.

This setting should:

1. Only be used during initial node sync
2. Never be used in production environments
3. Be re-enabled immediately after initial sync completes

### Disable prefetch

Disabling reduces memory usage but can slow down performance for sequential read workloads.

```sh
echo 1 | sudo tee /sys/module/zfs/parameters/zfs_prefetch_disable
```

> **Note:** You can always re-enable it: `echo 0 | sudo tee /sys/module/zfs/parameters/zfs_prefetch_disable`

### Set record size

Setting `recordsize=256K` defines the maximum block size that ZFS will use when writing data to a dataset.

```sh
zfs set recordsize=256K $ZFS_POOL_NAME/$ZFS_DATASET_NAME
```

---
Title: 🐳 Docker setup
URL: https://docs.celestia.org/operate/getting-started/docker.md
Source: app/operate/getting-started/docker/page.mdx
---

# 🐳 Docker setup

This page has instructions to run celestia-node using Docker. If you are
looking for instructions to run celestia-node using a binary, please
refer to the [celestia-node page](/operate/data-availability/install-celestia-node).

Using Docker is the easiest way to run celestia-node for most
users. Docker is a containerization platform that allows you to run celestia-node
in an isolated environment.

This means that you can run celestia-node on your machine without having
to worry about installing and configuring all of the dependencies required
to run the node.

If you would like to learn more about
key management in Docker, visit the
[Docker and `cel-key` section](/operate/keys-wallets/celestia-node-key#docker-and-cel-key).

The easiest way to install Docker is to use the Docker Desktop installer or
Ubuntu. You can
[follow the instructions for your operating system](https://docs.docker.com/engine/install).

## Prerequisites

- [Docker Desktop for Mac or Windows](https://docs.docker.com/get-docker) and a basic
  understanding of Docker
- [Docker Engine for Linux](https://docs.docker.com/engine/install/) and a
  basic understanding of Docker

## Quick start

### Set the network

Choose [the network](/operate/networks/overview) you would like to run your node on:

**Mainnet Beta**

```bash
export NETWORK=celestia
```

**Mocha**

```bash
export NETWORK=mocha
```

### Set the node type

**Light**

```bash
export NODE_TYPE=light
```

**Bridge**

```bash
export NODE_TYPE=bridge
```

**Full**

```bash
export NODE_TYPE=full
```

### Configure the consensus endpoint

celestia-node connects to consensus over gRPC via `--core.ip` and `--core.port`
(default `9090`). Pick a consensus host from
   [Mainnet Beta](/operate/networks/mainnet-beta#community-consensus-endpoints)
   or [Mocha](/operate/networks/mocha-testnet#community-consensus-endpoints)
   using the bare host (without `http://` or `https://`):

   ```bash
   export CORE_IP=consensus.example.com
   ```

Then set the gRPC port for that host (usually `9090`):

   ```bash
   export CORE_PORT=9090
   ```

### Run the container

**Mainnet Beta**

```bash
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    ghcr.io/celestiaorg/celestia-node:v0.34.3 \
    celestia $NODE_TYPE start --core.ip $CORE_IP --core.port $CORE_PORT --p2p.network $NETWORK
```

**Mocha**

```bash
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    ghcr.io/celestiaorg/celestia-node:v0.34.3-mocha \
    celestia $NODE_TYPE start --core.ip $CORE_IP --core.port $CORE_PORT --p2p.network $NETWORK
```

Congratulations! You now have a celestia-node running!

If you would like to run the node with custom flags,
you can refer to the
[celestia-node tutorial](/operate/data-availability/light-node/quickstart#start-the-light-node) page. Refer to
[the ports section of the celestia-node troubleshooting page](/operate/maintenance/troubleshooting#ports)
for information on which ports are required to be open on your machine.

## Light node setup with persistent storage

If you delete a container that you started above, all data will be lost.
To avoid this, you can mount a volume to the container.
This will allow you to persist data even after the container is deleted.

First, you will need to create a directory on your host machine.
This directory will be used to store the data for the container.
Create a directory on your host machine and give it a name.
For example, you can name it `my-node-store`:

```bash
cd $HOME
mkdir my-node-store
```

Now, you can mount this directory to the container.
Before mounting a volume, you _may_ need to set permissions for
the user on the host machine by running:

**Docker Engine on Linux**
```bash
sudo chown 10001:10001 $HOME/my-node-store
```

**Docker Desktop on Mac**
```bash
# you're good to go 😎
```

> Docker Desktop on Mac users typically do not need to change permissions.

### Initialize the node store and key

In order to mount a volume to the container, you need to specify
the path to the volume. When you run your container, you can specify
the path to the volume using the `--volume` (or `-v` for short) flag.
In this command, we'll create our key and initialize the node store,
using the variables we set in the [quick start](#quick-start) section:

```bash
# --volume == -v [local path]:[container path]
docker run [args...] -v $HOME/my-node-store:/home/celestia \
    celestia $NODE_TYPE init [args...]
```

An example init command will look similar to below:

**Mainnet Beta**

```bash
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    -v $HOME/my-node-store:/home/celestia \
    ghcr.io/celestiaorg/celestia-node:v0.34.3 \
    celestia light init --p2p.network $NETWORK
```

**Mocha**

```bash
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    -v $HOME/my-node-store:/home/celestia \
    ghcr.io/celestiaorg/celestia-node:v0.34.3-mocha \
    celestia light init --p2p.network $NETWORK
```

### Start the node

Run the following command to start the node:

```bash
# --volume == -v [local path]:[container path]
docker run [...args] -v $HOME/my-node-store:/home/celestia \
    celestia <node-type> start [...args]
```

A full start command will look similar to below.

**Mainnet Beta**

```bash
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    -v $HOME/my-node-store:/home/celestia \
    ghcr.io/celestiaorg/celestia-node:v0.34.3 \
    celestia light start --core.ip $CORE_IP --core.port $CORE_PORT --p2p.network $NETWORK
```

**Mocha**

```bash
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    -v $HOME/my-node-store:/home/celestia \
    ghcr.io/celestiaorg/celestia-node:v0.34.3-mocha \
    celestia light start --core.ip $CORE_IP --core.port $CORE_PORT --p2p.network $NETWORK
```

Congratulations! You now have a node running with persistent storage.

## Video walkthrough

  <iframe
    class="youtube-video"
    title="Running a Celestia light node"
    src="https://youtube.com/embed/WFubhQc8tGk"
    allowfullscreen
  ></iframe>

### 2.5 minute version

  <iframe
    class="youtube-video"
    title="Running a Celestia light node"
    src="https://youtube.com/embed/ROZv871Q7RM"
    allowfullscreen
  ></iframe>

## Troubleshooting

For security purposes Celestia expects to interact with your node's
keys in a read-only manner. This is enforced using linux style permissions
on the filesystem. Windows NTFS does not support these types of permissions.
As a result the recommended path for Windows users to mount a persisted
volume is to do so within WSL.
You can find
[instructions for installing WSL](https://learn.microsoft.com/en-us/windows/wsl/install).

---
Title: Development environment
URL: https://docs.celestia.org/operate/getting-started/environment-setup.md
Source: app/operate/getting-started/environment-setup/page.mdx
---

# Development environment

This page will go over setting up your development environment
to run Celestia software. This environment can be used for development, building
binaries, and running nodes.

## Supported architectures

Celestia-app and celestia-node only officially support the following architectures:

- linux/amd64
- linux/arm64
- darwin/amd64 (macOS Intel)
- darwin/arm64 (macOS Apple Silicon)

Only these four architectures are officially tested and supported.

### Install dependencies

Select your platform to update the OS and install required packages:

**Ubuntu (APT)**

```bash
sudo apt update && sudo apt upgrade -y
sudo apt install curl tar wget aria2 clang pkg-config libssl-dev jq build-essential \
git make ncdu -y
```

**RHEL/CentOS (YUM)**

```bash
sudo yum update
sudo yum install curl tar wget aria2 clang pkg-config libssl-dev jq build-essential \
git make ncdu -y
```

**macOS**

```bash
# install Homebrew, then wget & jq
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install wget && brew install jq
```

### Install Go

Install Go to build celestia-node or celestia-app from source. The versions below
meet the Go requirements of the releases documented for each network.
When building a different release, check the `go` and, if present, `toolchain`
directives in that release's `go.mod` before choosing a Go version.

| Network | celestia-node requirements | celestia-app requirements |
| --- | --- | --- |
| Mainnet Beta | [Release go.mod](https://github.com/celestiaorg/celestia-node/blob/v0.34.3/go.mod) | [Release go.mod](https://github.com/celestiaorg/celestia-app/blob/v10.4.0/go.mod) |
| Mocha | [Release go.mod](https://github.com/celestiaorg/celestia-node/blob/v0.34.3-mocha/go.mod) | [Release go.mod](https://github.com/celestiaorg/celestia-app/blob/v10.4.0-mocha/go.mod) |

Set the version for your desired network:

- Mainnet Beta: `ver="1.26.8"`
- Mocha: `ver="1.26.8"`

Download and install Go:

**Linux (AMD)**

```bash
cd $HOME
wget "https://go.dev/dl/go$ver.linux-amd64.tar.gz"
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf "go$ver.linux-amd64.tar.gz"
rm "go$ver.linux-amd64.tar.gz"
```

**Linux (ARM)**

```bash
cd $HOME
wget "https://go.dev/dl/go$ver.linux-arm64.tar.gz"
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf "go$ver.linux-arm64.tar.gz"
rm "go$ver.linux-arm64.tar.gz"
```

**macOS (Apple)**

```bash
cd $HOME
wget "https://go.dev/dl/go$ver.darwin-arm64.tar.gz"
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf "go$ver.darwin-arm64.tar.gz"
rm "go$ver.darwin-arm64.tar.gz"
```

**macOS (Intel)**

```bash
cd $HOME
wget "https://go.dev/dl/go$ver.darwin-amd64.tar.gz"
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf "go$ver.darwin-amd64.tar.gz"
rm "go$ver.darwin-amd64.tar.gz"
```

### Configure Go and verify

Add your `/usr/local/go/bin` directory to your `$PATH` if you have not already:

**bash**

```bash
echo "export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin" >> $HOME/.bash_profile
source $HOME/.bash_profile
```

**zsh**

```bash
echo "export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin" >> $HOME/.zshrc
source $HOME/.zshrc
```

Use `echo $SHELL` to figure out what type of shell you are using.

To verify that the correct version of Go was installed correctly run:

```bash
go version
```

The output will show the version installed.

---
Title: Hardware requirements
URL: https://docs.celestia.org/operate/getting-started/hardware-requirements.md
Source: app/operate/getting-started/hardware-requirements/page.mdx
---

# Hardware requirements

## Disk sizing

The consensus and bridge disk recommendations below are Mainnet Beta starting
points based on [node-store measurements from 30 September 2026](https://gist.github.com/rootulp/6680db718f4260948cf391ef0068d525),
with additional capacity for growth. They are not maximum-throughput guarantees
or a promise of a year of storage. The measurements did not verify sync status
or complete archival history. Mocha requires separate sizing based on its own
usage and retained history.

Disk sizes use decimal TB (1 TB = 1,000 GB), except the legacy archival light-node
estimate marked in TiB. Provision usable capacity after RAID and filesystem
overhead. Monitor both node-store usage and free filesystem space, measure growth
over time, and expand before the remaining space falls below what your node will
consume during your storage expansion lead time. Allow extra room for database
compaction, snapshots, backups, and other services.

For capacity planning, multiply data throughput by retention time, then allow for
the node's storage format and database overhead. Sustained utilisation of 20–30%
of a 32 MiB block every 3 seconds produces approximately 1.4–2.0 TB of payload
over 169 hours, before storage overhead. This is a planning scenario, not measured
network utilisation: a 2 TB bridge cannot be assumed to cover it. Size for your
expected traffic and retention rather than treating observed usage as a limit.

## Data availability nodes

### Non-archival data availability nodes

| Node type   | Memory     | CPU         | Disk        | Bandwidth |
| ----------- | ---------- | ----------- | ----------- | --------- |
| Light node  | 500 MB RAM | Single core | 20 GB SSD   | 56 Kbps   |
| Bridge node | 64 GB RAM  | 32 cores    | 2 TB NVMe | 1 Gbps    |

The measured pruned bridge store used approximately 317 GB. The recommendation
assumes pruning remains enabled. In celestia-node
v0.34.3, the default bridge
[storage window](https://github.com/celestiaorg/celestia-node/blob/v0.34.3/share/availability/window.go)
is 169 hours (seven days plus one hour). This is the software default; the
measured node's effective retention window was not independently verified.
Provision separately for any [consensus node](/operate/consensus-validators/consensus-node)
used by the bridge, even if both services share a host.

### Archival data availability nodes

| Node type                    | Memory     | CPU         | Disk          | Bandwidth |
| ---------------------------- | ---------- | ----------- | ------------- | --------- |
| Light node (unpruned headers) | 500 MB RAM | Single core | 7 TiB NVMe\*  | 56 Kbps   |
| Bridge node                  | 64 GB RAM  | 32 cores    | 12 TB NVMe | 1 Gbps    |

The measured archival bridge store used approximately 6.2 TB. Its service was
configured with `--archival`, but that does not establish complete historical
coverage. Check the history you need to retain and its growth before provisioning.
Archival storage continues to grow as new blocks arrive.

\*The archival light-node figure retains the earlier conservative estimate for
one year at the 128 MB/6 s planning envelope. No archival light node was measured
in this update; this figure has not been validated against observed usage.

## Consensus nodes

### Non-archival consensus nodes

| Node type      | Memory    | CPU      | Disk       | Bandwidth |
| -------------- | --------- | -------- | ---------- | --------- |
| Validator      | 32 GB RAM | 32 cores | 2 TB NVMe | 1 Gbps    |
| Consensus node | 32 GB RAM | 32 cores | 2 TB NVMe | 1 Gbps    |

The measured pruned consensus store used approximately 206 GB with
`pruning = "default"` and `min-retain-blocks = 3000` in `app.toml`.
The recommendation applies to nodes pruning both application state and old block
data. Pruning state alone does not bound block storage: `min-retain-blocks = 0`
retains all blocks. Longer retention, including the validator guide's
600,000-block recommendation, needs a separate capacity assessment. Review the
[storage and pruning configurations](/operate/consensus-validators/consensus-node#storage-and-pruning-configurations)
before choosing a disk; changing retention can permanently delete history.

Provision [Fibre storage](/operate/consensus-validators/fibre) separately from
consensus data. The measurements above do not size the Fibre service.

### Archival consensus nodes

| Node type      | Memory    | CPU      | Disk       | Bandwidth |
| -------------- | --------- | -------- | ---------- | --------- |
| Consensus node | 64 GB RAM | 32 cores | 16 TB NVMe | 1 Gbps    |

The measured archival consensus store used approximately 10.0 TB with
`pruning = "nothing"` and `min-retain-blocks = 0`. Confirm that your store contains
the history your application needs. The additional capacity is growth headroom,
not a validated number of months of operation.

Validators must use hardware that passes the [CPU benchmark](https://github.com/celestiaorg/celestia-app/blob/main/tools/cpu_requirements/README.md). If your server does not pass, upgrade to a more powerful machine.

For a list of CPUs tested against the v6 128MB/6s workload, see the [release notes](https://github.com/celestiaorg/celestia-app/blob/main/docs/release-notes/release-notes.md#v6---128mb6s). Other CPUs are acceptable if they pass the benchmark. Recommended CPU specs:

- 32 or more cores
- GFNI (Galois Field New Instructions) support
- SHA-NI (SHA New Instructions) support

---

---
Title: Overview to running nodes on Celestia
URL: https://docs.celestia.org/operate/getting-started/overview.md
Source: app/operate/getting-started/overview/page.mdx
---

# Overview to running nodes on Celestia

There are many ways you can participate in the Celestia
[networks](/operate/networks/overview).

Celestia node operators can run several options on the network.

Consensus:

- [Validator node](/operate/consensus-validators/validator-node):
  This type of node participates
  in consensus by producing and voting on blocks.
- [Consensus node](/operate/consensus-validators/consensus-node): A celestia-app full node
  to sync blockchain history.

Data Availability:

- [Bridge node](/operate/data-availability/bridge-node): This node bridges blocks between the
  Data-Availability network and the Consensus network.
- [Light node](/operate/data-availability/light-node/quickstart): Light clients conduct data availability
  sampling on the Data Availability network.

You can learn more about how to set up each different node by going through
each tutorial guide. If you want to get hands-on with a light node right away, follow the quickstart in the Build section: [Post/retrieve a blob → Light node quickstart](/operate/data-availability/light-node/quickstart/).

Please provide any feedback on the tutorials and guides. If you notice
a bug or issue, feel free to make a pull request or write up a Github
issue!

---
Title: Create a wallet with celestia-app
URL: https://docs.celestia.org/operate/keys-wallets/celestia-app-wallet.md
Source: app/operate/keys-wallets/celestia-app-wallet/page.mdx
---

# Create a wallet with celestia-app

For this guide, we will go over how you can generate a Celestia
wallet using celestia-app.

## Prerequisites

- Gone through [quick start and installed celestia-app](/operate/consensus-validators/install-celestia-app)

Note, you do not need to install celestia-node for this tutorial.

## Keyring backend

`keyring-backend` configures where celestia-appd stores your keys. Choose it
before you create a wallet, because the backend you pick decides whether the
private key is encrypted at rest.

| Backend | Where keys are stored | Suitable for |
| --- | --- | --- |
| `os` | The operating system keychain: Keychain on macOS, Credentials Management on Windows, libsecret, kwallet or keyctl on Linux | A single-operator machine |
| `file` | Encrypted inside the app's configuration directory; the password is requested on every access | Servers and containers |
| `pass` | GPG-encrypted files managed by the `pass` utility | Servers with an existing GPG setup |
| `kwallet` | KDE Wallet Manager | KDE desktops |
| `test` | **Unencrypted on disk, with no password** | Local development and testnets |
| `memory` | Process memory, discarded when the process exits | Throwaway scripts |

The Cosmos SDK describes `test` as "a password-less variation of the file
backend. Keys are stored unencrypted on disk" and states that it is "not
recommended for use in production environments". Anyone who can read the
directory can spend from the account and sign on behalf of the validator.

Do not use `test` for a wallet that holds real funds or operates a Mainnet Beta
validator. Use a hardware wallet, or a
[multisig account](/operate/keys-wallets/multisig) so that no single key can
move funds on its own.

You can set the backend for a single command with `--keyring-backend`, which is
what the examples in these docs do. Pass it on every command that touches a key:
without the flag, `celestia-appd` falls back to the default backend and will not
find a key that was created in a different one. You can learn more on the
[Cosmos documentation](https://docs.cosmos.network/sdk/v0.53/user/run-node/keyring)
or [Go Package documentation](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/crypto/keyring).

## Create a wallet

You can pick whatever wallet name you want. The examples below and the
[validator node guide](/operate/consensus-validators/validator-node) both use
`$VALIDATOR_WALLET`, so set it to the name you chose:

```sh
export VALIDATOR_WALLET=validator
export KEYRING_BACKEND=file # use `test` only on a testnet

celestia-appd keys add $VALIDATOR_WALLET \
  --keyring-backend=$KEYRING_BACKEND \
  --interactive
```

Save the mnemonic output as this is the only way to
recover your validator wallet in case you lose it!

To check all your wallets you can run:

```sh
celestia-appd keys list --keyring-backend=$KEYRING_BACKEND
```

## Key management

```sh
# listing keys
celestia-appd keys list --keyring-backend=$KEYRING_BACKEND

# adding keys
celestia-appd keys add <KEY_NAME> --keyring-backend=$KEYRING_BACKEND

# deleting keys
celestia-appd keys delete <KEY_NAME> --keyring-backend=$KEYRING_BACKEND

# renaming keys
celestia-appd keys rename <CURRENT_KEY_NAME> <NEW_KEY_NAME> \
  --keyring-backend=$KEYRING_BACKEND
```

### Importing and exporting keys

Import an encrypted and ASCII-armored private key into the local keybase.

```sh
celestia-appd keys import <KEY_NAME> <KEY_FILE> --keyring-backend=$KEYRING_BACKEND
```

Example usage:

```sh
celestia-appd keys import amanda ./keyfile.txt --keyring-backend=$KEYRING_BACKEND
```

Export a private key from the local keyring in encrypted and ASCII-armored format:

```sh
celestia-appd keys export <KEY_NAME> --keyring-backend=$KEYRING_BACKEND

# you will then be prompted to set a password for the encrypted private key:
Enter passphrase to encrypt the exported key:
```

After you set a password, your encrypted key will be displayed.

## Fund a wallet

For the public celestia address, you can fund the
previously created wallet via [Discord](https://discord.com/invite/YsnTPcSfWQ)
by sending this message to the #mocha-faucet channel:

```text
$request celestia1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Wait to see if you get a confirmation that the
tokens have been successfully sent. To check if
tokens have arrived successfully to the destination
wallet run the command below replacing the public
address with your own:

```sh
celestia-appd start
celestia-appd query bank balances celestia1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Refer to the ports section of the celestia-node troubleshooting page for information on which ports are required to be open on your machine.

---
Title: Create a wallet with celestia-node
URL: https://docs.celestia.org/operate/keys-wallets/celestia-node-key.md
Source: app/operate/keys-wallets/celestia-node-key/page.mdx
---

# Create a wallet with celestia-node

This tutorial will go over using the `cel-key` utility
to generate a wallet on celestia-node.

While this tutorial will go over the installation process
of `cel-key`, it is recommended that you complete
the following prerequisites first:

- [Setting up your environment](/operate/getting-started/environment-setup)

Once you completed the prerequisite, you can proceed with this
tutorial.

## Using the `cel-key` utility

Inside the celestia-node repository is a utility called `cel-key` that uses
the key utility provided by Cosmos-SDK under the hood. The utility can be
used to `add`, `delete`, and manage keys for any DA node
type `(bridge || light)`, or just keys in general.

### Installation

You need to first pull down the celestia-node repository:

```sh
git clone https://github.com/celestiaorg/celestia-node.git
cd celestia-node/
```

It can be built using either of the following commands:

```sh
# dumps binary in current working directory, accessible via `./cel-key`
make cel-key
```

or

```sh
# installs binary in GOBIN path, accessible via `cel-key`
make install-key
```

For the purpose of this guide, we will use the `make cel-key` command.

### Steps for generating node keys

To generate a key for a Celestia node, select
the tab for your node type:

You do not need to declare a network for Mainnet Beta. Refer to [the chain ID section on the troubleshooting page for more information](/operate/maintenance/troubleshooting).

```bash
./cel-key add <key-name> --keyring-backend test --node.type bridge \
  --p2p.network <network>
```

```bash
./cel-key add <key-name> --keyring-backend test --node.type light \
  --p2p.network <network>
```

This will load the key `<key-name>` into the directory of the node.

Further flags you can use to customize your key are the following:

- `--p2p.network`: Specifies which network you want the key for. Use `mocha`
  to target Mocha.

Keep in mind that your celestia-node will only pick up keys that
are inside the default directory under `/keys` so you should make
sure to point `cel-key` utility to the correct directory via the
`p2p.network` or `home` flags if you have specified a custom
directory or network other than Mocha or Mainnet Beta.

Also keep in mind that if you do not specify a network with `--p2p.network`,
the default one will always be `celestia` (Mainnet Beta).

### Steps for exporting node keys

You can export a private key from the local keyring in encrypted and
ASCII-armored format.

```bash
./cel-key export <key-name> --keyring-backend test --node.type bridge \
  --p2p.network <network>
```

```bash
./cel-key export <key-name> --keyring-backend test --node.type light \
  --p2p.network <network>
```

### Steps for importing node keys

To import from a mnemonic, use the following command,
then enter your bip39 mnemonic:

```bash
./cel-key add <key-name> --recover --keyring-backend test \
  --node.type bridge --p2p.network <network>
```

```bash
./cel-key add <key-name> --recover --keyring-backend test \
  --node.type light --p2p.network <network>
```

### View all options for `cel-key`

```sh
./cel-key --help
```

## Managing the key returned by `celestia state account-address`

When you run a Celestia node and use the command `celestia state account-address`, it returns the address of the key that your node is currently using. This key is the same one that was either:

1. Auto-generated during node initialization with `celestia <node-type> init`
2. Manually created using `cel-key add <name> [flags]`
3. Imported/recovered using `cel-key add <name> --recover --node.type <node-type>`

### Understanding the relationship

The key reported by `celestia state account-address` is stored in your node's keyring directory:

- For Mocha testnet: `~/.celestia-<node-type>-mocha-5/keys/keyring-test/`
- For Mainnet Beta: `~/.celestia-<node-type>/keys/keyring-test/`

You can verify this by listing your keys with `cel-key`:

```bash
cel-key list --keyring-backend test --node.type <node-type> --p2p.network <network>
```

For example, with a light node on Mocha:

```bash
cel-key list --keyring-backend test --node.type light --p2p.network mocha
```

The address shown in this output should match the one returned by `celestia state account-address`.

### Backing up your key

To back up the key used by your node, you have two options:

#### Option 1: Export the key's mnemonic

```bash
cel-key export <key-name> --keyring-backend test --node.type <node-type> --p2p.network <network>
```

For example, if your key is named "my_celes_key":

```bash
cel-key export my_celes_key --keyring-backend test --node.type light --p2p.network mocha
```

This will prompt you for a password to encrypt the exported key. Store this exported key and password securely.

#### Option 2: Back up the keyring directory

You can also directly back up the entire keyring directory:

```bash
# For Mocha testnet
cp -r ~/.celestia-<node-type>-mocha-5/keys/keyring-test /secure/backup/location

# For Mainnet Beta
cp -r ~/.celestia-<node-type>/keys/keyring-test /secure/backup/location
```

### Recovering your key

If you need to recover your key on a new machine or after reinstalling your node:

#### Option 1: Recover using the mnemonic

If you have the mnemonic phrase for your key:

```bash
cel-key add <key-name> --recover --keyring-backend test --node.type <node-type> --p2p.network <network>
```

For example:

```bash
cel-key add my_celes_key --recover --keyring-backend test --node.type light --p2p.network mocha
```

You'll be prompted to enter your mnemonic phrase.

#### Option 2: Restore from backup

If you backed up the keyring directory:

1. Install and initialize your node as normal
2. Stop the node if it's running
3. Replace the keyring-test directory with your backup:

```bash
# For Mocha testnet
cp -r /secure/backup/location/* ~/.celestia-<node-type>-mocha-5/keys/keyring-test/

# For Mainnet Beta
cp -r /secure/backup/location/* ~/.celestia-<node-type>/keys/keyring-test/
```

4. Start your node with the restored key:

```bash
celestia <node-type> start --p2p.network <network> --keyring.keyname <key-name> [other flags]
```

### Using a specific key with your node

If you have multiple keys and want to use a specific one with your node:

```bash
celestia <node-type> start --p2p.network <network> --keyring.keyname <key-name> [other flags]
```

For example:

```bash
celestia light start --p2p.network mocha --keyring.keyname my_celes_key \
  --core.ip public-endpoint.celestia-mocha.quiknode.pro \
  --core.port 9090 --core.tls
```

This ensures your node uses the specified key for all operations, including those reported by `celestia state account-address`.

## Docker and `cel-key`

### Prerequisites

- Docker installed on your machine
- Understanding of the
  [guide on how to run celestia-node with Docker](/operate/getting-started/docker).

### Running your node

Run the Docker image (in this example, we are using a light node on Mocha
testnet):

```bash
docker run --name celestia-node -e NODE_TYPE=light -e P2P_NETWORK=mocha -p 26659:26659 \
ghcr.io/celestiaorg/celestia-node:v0.34.3-mocha celestia light start \
--core.ip public-endpoint.celestia-mocha.quiknode.pro --core.port 9090 \
--core.tls --p2p.network mocha
```

Refer to [the ports section of the celestia-node troubleshooting page](/operate/maintenance/troubleshooting#ports) for information on which ports are required to be open on your machine. You do not need to declare a network for Mainnet Beta. Refer to [the chain ID section on the troubleshooting page for more information](/operate/maintenance/troubleshooting).

List active containers in another window with:

```bash
docker ps
```

The response will look like:

```bash
CONTAINER ID   IMAGE           COMMAND                  CREATED          STATUS          PORTS      NAMES
<container-id>   celestia-node   "/entrypoint.sh cele…"   22 seconds ago   Up 21 seconds   2121/tcp   docker-compose-test-celestia-1
```

Interact with the container by replacing `<container-id>` for the container ID:

```bash
docker exec -ti <container-id> /bin/bash
```

Now, interact with `cel-key` to check for the key that was autogenerated when
you started the node:

```bash
./cel-key list --keyring-backend test --node.type light
```

You can also export your key from the container. In the next section, you'll
learn how to mount existing keys to the container.

### Mounting existing keys to container

In this example, we'll be mounting an existing key to the container. We're also
using an existing image called celestia-node. This will mount the entire
`/.celestia-light-<p2p-network>/keys` directory to your image, or on Mainnet Beta
the `/.celestia-light/keys` directory.

Write a `docker-compose.yml` to accomplish this:

```yaml
version: "3.8"
services:
  celestia:
    image: celestia-node
    environment:
      - NODE_TYPE=light
    command: celestia light start --core.ip public-endpoint.celestia-mocha.quiknode.pro --core.port 9090 --core.tls --p2p.network mocha --keyring.keyname my_celes_key
    volumes:
      - ${PWD}/keys:/root/.celestia-light-mocha-5/keys
    ports:
      - 26659:26659
```

Start the container by running the following command in the directory with your `docker-compose.yml`:

```bash
docker-compose up
```

List active containers in another window with:

```bash
docker ps
```

The response will look like:

```bash
CONTAINER ID   IMAGE           COMMAND                  CREATED          STATUS          PORTS      NAMES
<container-id>   celestia-node   "/entrypoint.sh cele…"   22 seconds ago   Up 21 seconds   2121/tcp   docker-compose-test-celestia-1
```

Interact with the container by replacing `<container-id>` for the container ID:

```bash
docker exec -ti <container-id> /bin/bash
```

Now, interact with `cel-key` to check your address matches the address you
expect with the key you mounted:

```bash
root@<container-id>:/# ./cel-key list --keyring-backend test --node.type light
using directory:  ~/.celestia-light-mocha-5/keys
- address: celestia1wkhyhr7ngf0ayqlpnsnxg4d72hfs5453dvunm9
  name: my_celes_key
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A1/NsoY0RGL7Hqt4VWLg441GQKJsZ2fBUnZXipgns8oV"}'
  type: local
```

---
Title: Multisig
URL: https://docs.celestia.org/operate/keys-wallets/multisig.md
Source: app/operate/keys-wallets/multisig/page.mdx
---

# Multisig

Celestia inherits support for multisig accounts from the Cosmos SDK. Multisig
accounts behave similarly to regular accounts with the added requirement that
a threshold of signatures is needed to authorize a transaction.

Multisig accounts can be created from the [command line](#command-line) or using
a graphical interface such as [Keplr](https://multisig.keplr.app/).

## Command line

```bash
#!/bin/sh

# Prerequisite: prior to running this script, start a single node devnet with ./scripts/single-node.sh
CHAIN_ID="private"
KEY_NAME="validator"
KEYRING_BACKEND="test"
BROADCAST_MODE="block"

# Create 3 test keys
celestia-appd keys add test1
celestia-appd keys add test2
celestia-appd keys add test3
# Create the multisig account
celestia-appd keys add multisig \
    --multisig test1,test2,test3 \
    --multisig-threshold 2

# Send some funds from the validator account to the multisig account
celestia-appd tx bank send $VALIDATOR $MULTISIG 100000utia \
    --from $VALIDATOR \
    --fees 1000utia \
    --chain-id $CHAIN_ID \
    --keyring-backend $KEYRING_BACKEND \
    --broadcast-mode $BROADCAST_MODE \
    --yes

# Send some funds from the multisig account to the validator account.
# Note this transaction will need to be signed by at least 2 of the 3 test accounts.
celestia-appd tx bank send $MULTISIG $VALIDATOR 1utia \
    --from $MULTISIG \
    --fees 1000utia \
    --chain-id $CHAIN_ID \
    --keyring-backend $KEYRING_BACKEND \
    --generate-only > unsignedTx.json

# Sign from test1 and test2
celestia-appd tx sign unsignedTx.json \
    --multisig $MULTISIG \
    --from test1 \
    --output-document test1sig.json \
    --chain-id $CHAIN_ID
celestia-appd tx sign unsignedTx.json \
    --multisig $MULTISIG \
    --from test2 \
    --output-document test2sig.json \
    --chain-id $CHAIN_ID

# Generate the final signed transaction
celestia-appd tx multisign unsignedTx.json multisig \
    test1sig.json test2sig.json \
    --output-document signedTx.json \
    --chain-id $CHAIN_ID
```

## Resources

- [https://figment.io/insights/how-to-multi-sig-on-cosmos/](https://figment.io/insights/how-to-multi-sig-on-cosmos/)
- [https://github.com/aura-nw/Aura-Safe](https://github.com/aura-nw/Aura-Safe)
- [https://github.com/informalsystems/multisig](https://github.com/informalsystems/multisig)

---
Title: How to create a vesting account with celestia-app
URL: https://docs.celestia.org/operate/keys-wallets/vesting.md
Source: app/operate/keys-wallets/vesting/page.mdx
---

# How to create a vesting account with celestia-app

In this guide, we will learn how to create a vesting account using
celestia-app for both a local devnet and on Mocha testnet.

> **Note:** The instructions for this tutorial are for a **continuous** vesting account. To create a delayed vesting account, add the `--delayed` flag to your vesting transaction.

## Local devnet

[download and install celestia-app](/operate/consensus-validators/install-celestia-app),
selecting the
[network and corresponding version](/operate/networks/overview)
that you would like to use.

### Setting up the local devnet

#### Run the devnet

Next, change into the `$HOME/celestia-app` directory and
run the single-node-devnet script.

```bash
cd $HOME/celestia-app
./scripts/build-run-single-node.sh
```

#### Save the home directory path

At the top of the output, you will see a path to the "Home directory",
find yours from the output (**it will be unique every time**):

```bash
./scripts/build-run-single-node.sh
Home directory: /var/folders/_8/ljj6hspn0kn09qf9fy8kdyh40000gn/T/celestia_app_XXXXXXXXXXXXX.XV92a3qx
--> Updating go.mod
```

And set the location as the `CELESTIA_APP_HOME` variable. We will use this
for the remainder of the devnet section.

```bash
export CELESTIA_APP_HOME=/var/folders/_8/ljj6hspn0kn09qf9fy8kdyh40000gn/T/celestia_app_XXXXXXXXXXXXX.XV92a3qx
```

> **Note:** This does not replace the `celestia-appd` binary that was installed with `celestia-appd`, but builds and runs one in the `$HOME/celestia-app/build` directory.

#### Check the version of the devnet

If you'd like to check the version of your local devnet, you can use:

```bash
cd $HOME/celestia-app/build
./celestia-appd version
```

#### Next steps

Congratulations! You now have a private devnet running locally on your machine.
The devnet is made up of one validator that is creating new blocks. This is the
Celestia consensus network on your machine! The key that was created to
run the validator also lives in a temporary directory for the devnet.

Now you are ready to test creating a vesting account on our devnet before going
to Mocha, a live testnet.

### Setting up vesting account on devnet

You already have one key setup, but you will need one more to create
a vesting account.

#### Create a new key

First, create a vesting key:

```bash
cd $HOME/celestia-app/build
./celestia-appd keys add vesting-key --home $CELESTIA_APP_HOME
```

You will see the address, mnemonic, and more details about your key in the
output:

```bash
- address: celestia127fpaygehlsgjdknwvlr2mux7h5uvhkxktgkc5
  name: vesting-key
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A5JF/we+s5gFt6g944XbKVVYgQB9OY+U/l5dhZjLDczO"}'
  type: local

**Important** write this mnemonic phrase in a safe place.
It is the only way to recover your account if you ever forget your password.

index enter egg broken ostrich duty bitter blind all car hollow coral youth early verify point void anger daring sausage decline net shove oil
```

#### List your keys

```bash
./celestia-appd keys list --home $CELESTIA_APP_HOME
```

Output:

```bash
- address: celestia1adgkqcmzuxvg7x5avx8a8rjwpmxgzex3ztef6j
  name: validator
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"Ahzu6yr9XMPIxLquhgBhj9xL3wIaOz6PE3CvML/oPQym"}'
  type: local
- address: celestia127fpaygehlsgjdknwvlr2mux7h5uvhkxktgkc5
  name: vesting-key
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A5JF/we+s5gFt6g944XbKVVYgQB9OY+U/l5dhZjLDczO"}'
  type: local
```

#### Set variables

Set the keys as variables, using the validator address as the `FROM_ADDRESS`
and the vesting-key as the `TO_ADDRESS`.

```bash
export FROM_ADDRESS=celestia1adgkqcmzuxvg7x5avx8a8rjwpmxgzex3ztef6j
export TO_ADDRESS=celestia127fpaygehlsgjdknwvlr2mux7h5uvhkxktgkc5
```

#### Create your devnet vesting account

Create the vesting account with the following command:

> **Note:** The remainder of the instructions are for a **continuous** vesting account. To create a delayed vesting account, use the `--delayed` flag. For example:  
> `./celestia-appd tx vesting create-vesting-account $TO_ADDRESS 100000utia 1686748051 --from $FROM_ADDRESS --gas auto --fees 100000utia --chain-id private --home $CELESTIA_APP_HOME --delayed`

```bash
./celestia-appd tx vesting create-vesting-account $TO_ADDRESS 100000utia 1686748051 --from $FROM_ADDRESS --gas auto --fees 100000utia --chain-id private --home $CELESTIA_APP_HOME
```

Select "Y" to choose "yes".

> **Optional:** Add `-y` to run the transaction without an interactive prompt:  
> `./celestia-appd tx vesting create-vesting-account $TO_ADDRESS 100000utia 1686748051 --from $FROM_ADDRESS --gas auto --fees 100000utia --chain-id private --home $CELESTIA_APP_HOME -y`

Output:

```bash
gas estimate: 96112
auth_info:
  fee:
    amount:
    - amount: "100000"
      denom: utia
    gas_limit: "96112"
    granter: ""
    payer: ""
  signer_infos: []
  tip: null
body:
  extension_options: []
  memo: ""
  messages:
  - '@type': /cosmos.vesting.v1beta1.MsgCreateVestingAccount
    amount:
    - amount: "100000"
      denom: utia
    delayed: false
    end_time: "1686748051"
    from_address: celestia1adgkqcmzuxvg7x5avx8a8rjwpmxgzex3ztef6j
    to_address: celestia127fpaygehlsgjdknwvlr2mux7h5uvhkxktgkc5
  non_critical_extension_options: []
  timeout_height: "0"
signatures: []
confirm transaction before signing and broadcasting [y/N]: y
code: 0
codespace: ""
data: ""
events: []
gas_used: "0"
gas_wanted: "0"
height: "0"
info: ""
logs: []
raw_log: '[]'
timestamp: ""
tx: null
txhash: 6093DF76DBA90F04FF63D197FC1569F04ED3DBE64081A0BBA9BAD4E69AA570D2
```

The timestamp for the previous command is in the past, so once you create
the vesting account, the tokens will vest. You can check your account
balances to verify this.

#### Query the devnet vesting account details

Check that the account has been created and works as expected by querying
the `TO_ADDRESS` account details:

```bash
./celestia-appd query account $TO_ADDRESS --home $CELESTIA_APP_HOME
```

In the output, you will notice that the account type is a
`ContinuousVestingAccount`:

```bash
'@type': /cosmos.vesting.v1beta1.ContinuousVestingAccount
base_vesting_account:
  base_account:
    account_number: "7"
    address: celestia127fpaygehlsgjdknwvlr2mux7h5uvhkxktgkc5
    pub_key: null
    sequence: "0"
  delegated_free: []
  delegated_vesting: []
  end_time: "1686748051"
  original_vesting:
  - amount: "100000"
    denom: utia
start_time: "1687908352"
```

#### Query the devnet base account details

Check the `FROM_ADDRESS` account details:

```bash
./celestia-appd query account $FROM_ADDRESS --home $CELESTIA_APP_HOME
```

In the output, you will notice the account type is `BaseAccount`:

```bash
'@type': /cosmos.auth.v1beta1.BaseAccount
account_number: "0"
address: celestia1adgkqcmzuxvg7x5avx8a8rjwpmxgzex3ztef6j
pub_key:
  '@type': /cosmos.crypto.secp256k1.PubKey
  key: Ahzu6yr9XMPIxLquhgBhj9xL3wIaOz6PE3CvML/oPQym
sequence: "2"
```

#### Query the balances of the devnet accounts

Next, we can check the balance of the accounts:

```bash
./celestia-appd query bank balances $TO_ADDRESS --home $CELESTIA_APP_HOME
```

Output will show you the balance of the vesting account:

```bash
balances:
- amount: "100000"
  denom: utia
pagination:
  next_key: null
  total: "0"
```

```bash
./celestia-appd query bank balances $FROM_ADDRESS --home $CELESTIA_APP_HOME
```

The output will show the remaining balance of the validator:

```bash
balances:
- amount: "999994999800000"
  denom: utia
pagination:
  next_key: null
  total: "0"
```

Congratulations! You've now made your own vesting account on a local devnet.
Next, you can learn how to create a vesting account on Mocha testnet.

## Mocha

In the previous section of this tutorial, we learned how to create a vesting
account on a local devnet. In this portion of the tutorial, we'll cover how
to set up a consensus node and set up a vesting account on
[Mocha testnet](/operate/networks/mocha-testnet).

First, be sure that you have
[installed celestia-app for the latest version for Mocha testnet](/operate/consensus-validators/install-celestia-app).

### Create a wallet

Set the keyring backend, so you don't need to use the flag for every command:

```bash
celestia-appd config keyring-backend test
```

Add a new key for a full node and one for a vesting account:

```bash
celestia-appd keys add origin && celestia-appd keys add vesting
```

List the keys:

```bash
celestia-appd keys list
```

Set your keys as variables:

```bash
export FROM_ADDRESS=address_of_origin_account
export TO_ADDRESS=address_of_vesting_account
```

### Fund your account

Head to [the faucet](/operate/networks/mocha-testnet#mocha-testnet-faucet),
and fund your `origin` address.

### Create a vesting account on Mocha

To create a vesting account on Mocha, you will need an RPC URL to send
the transaction to. You can find the
[consensus endpoints on the Mocha testnet page](/operate/networks/mocha-testnet#community-consensus-endpoints).

If you are running a production application, use a production endpoint.

Set your RPC URL:

```bash
export RPC_URL=https://public-endpoint.celestia-mocha.quiknode.pro
```

We will use a few flags in our vesting command that are different than the
devnet version. Since we aren't using our own validator or full node, we will
use an RPC URL.

We also need to declare the chain ID as `mocha`.

View the help menu for vesting to understand these flags more:

```bash
celestia-appd tx vesting --help
```

Here's an example command to set up the vesting account:

```bash
celestia-appd tx vesting create-vesting-account $TO_ADDRESS 100000utia 1686748051 --from $FROM_ADDRESS --gas 100000 --fees 100000utia --node $RPC_URL --chain-id mocha --delayed
```

### Optional: Set up a consensus node or validator

Running a consensus node or validator will prevent you from needing
to use an RPC.

You can set up a [validator](/operate/consensus-validators/validator-node)
or [consensus node](/operate/consensus-validators/consensus-node)
for the previous portion of the tutorial.

Note: this may take some time depending on how you choose to sync the
state of the chain.

### Optional: Change your client.toml

If you edit your client configuration in `client.toml`, you can set both the
chain ID and the node RPC URL. This will prevent you from needing
to run each flag for every command line that you use.

```toml
# This is a TOML config file.
# For more information, see https://github.com/toml-lang/toml

###############################################################################
###                           Client Configuration                            ###
###############################################################################

# The network chain ID
chain-id = "mocha"
# The keyring's backend, where the keys are stored (os|file|kwallet|pass|test|memory)
keyring-backend = "test"
# CLI output format (text|json)
output = "text"
# <host>:<port> to Tendermint RPC interface for this chain
node = "https://public-endpoint.celestia-mocha.quiknode.pro"
# Transaction broadcasting mode (sync|async|block)
broadcast-mode = "sync"
```

## Notes

Not all vesting accounts can be created with a message, some need to be
set at genesis. You can
[learn more in the Cosmos Network documentation](https://docs.cosmos.network/sdk/v0.53/build/modules/auth/vesting).

## Conclusion

Congratulations! You've learned how to create a local devnet, create a
vesting account on it, and how to make a vesting account on the Mocha testnet!

---
Title: celestia-node datastore
URL: https://docs.celestia.org/operate/maintenance/datastore-structure.md
Source: app/operate/maintenance/datastore-structure/page.mdx
---

# celestia-node datastore

The node's datastore refers to the storage structure
used to manage the data that supports the node's operation.
It consists of directories and files that contain the node's state,
configuration, and other information relevant to the node.

The following are the directories and files found in the datastore:

- `/blocks`: This directory stores blocks. Each file contained in this directory
  represents a block on Celestia and contains its associated data. This directory is present in the datastore for bridge nodes but not light nodes, as light nodes do not store blocks.

- `/data`: This directory contains block headers and various files belonging to the node's log-structured merge (LSM) storage system. The LSM files (such as `DISCARD`, `KEYREGISTRY`, and `MANIFEST`) manage the efficient storage and retrieval of data.

- `/index`: This directory stores the index files that handle mapping specific keys such as block heights, to the corresponding data. Similar to `/blocks`, the light node's datastore does not include this directory, as they do not perform indexing.

- `/inverted_index`: This directory stores the inverted index files used for mapping queries to the corresponding data location, along with associated LSM storage system files. The light node's datastore does not contain this directory.
- `/keys`: This directory stores the cryptographic key pairs that are used to operate the node.

- `/transients`: This directory contains temporary data such as cache files
  that are used while the node is operating, but are not a part of the permanent blockchain state.

- `config.toml`: Located in the node's root directory, this is the primary configuration file that defines core settings such as network parameters, P2P configuration, and API endpoints. This file is generated during node initialization.

---
Title: Network upgrades
URL: https://docs.celestia.org/operate/maintenance/network-upgrades.md
Source: app/operate/maintenance/network-upgrades/page.mdx
---

# Network upgrades

Blockchain networks often need to upgrade with new features which require coordination work among the community of developers, validators, and node operators prior to activating the upgrades. This process is called a network upgrade, which can be breaking or non-breaking. During planned network upgrades the community will coordinate to prepare for the upcoming upgrade. Breaking network upgrades are not backward-compatible with older versions of the network software, which is why it is important that validators upgrade their software to continue validating on the network. Non-breaking network upgrades are backward-compatible and require less coordination.

## Network upgrade coordination

As of the Lemongrass upgrade in September 2024, Celestia has implemented [CIP-10](https://cips.celestia.org/cip-010.html), which establishes two methods for coordinating network upgrades:

1. **Pre-programmed height**: Used for the Lemongrass network upgrade (v2)
2. **In-protocol signaling**: Used for all subsequent upgrades (v3+)

Under the in-protocol signaling mechanism, validators submit messages to signal their readiness and preference for the next version. The upgrade activates automatically once a quorum of 5/6 of validators have signaled for the same version.

### Announcement channels

Follow the latest network upgrade announcements on:

- Telegram: [Network-wide announcement channel](https://t.me/+smSFIA7XXLU4MjJh)
- Discord
  - [Mainnet Beta announcements](https://discord.com/channels/638338779505229824/1169237690114388039)
  - [Mocha announcements](https://discord.com/channels/638338779505229824/979037494735691816)

## Upgrade process

The upgrade process can be broken down into a few steps:

1. [Celestia Improvement Proposals](https://cips.celestia.org) (CIPs) are created for consensus-breaking changes and features that impact user experience. These CIPs are included in a meta-CIP, which define the scope of the upgrade.
1. Celestia core developer teams implement the features defined in the CIPs.
1. A new binary is released with the new features to be tested on testnets.
1. Node operators upgrade to the new binary on [Mocha testnet](/operate/networks/mocha-testnet), and finally on Celestia [Mainnet Beta](/operate/networks/mainnet-beta).
   - Upgrades using pre-programmed height (v2) activate at a predetermined block number.
   - Upgrades using in-protocol signaling (v3+) activate one week after 5/6 of the voting power has signaled for a particular version

## Configuration changes in v10

### Existing configuration files

Replacing celestia-app does not add new settings or comments to existing
configuration files. Missing settings use the binary's defaults.

Starting with celestia-app v10.2.0, use `config sync` to add missing fields and
their documentation to `config/config.toml`. Preview the additions first:

```bash
celestia-appd config sync --home ~/.celestia-app --dry-run
celestia-appd config sync --home ~/.celestia-app
```

Use your node's home directory if different. The command preserves existing
values and creates a backup before writing changes. It does not run
automatically on startup. Use it instead of the deprecated `update-config`
command for v10 configuration maintenance.

### RPC and storage settings

These settings apply to celestia-app consensus nodes:

| Section in `config/config.toml` | Setting | Default |
|---|---|---|
| `[rpc]` | `max_concurrent_heavy_requests` | `20` |
| `[storage]` | `compact` | `false` |
| `[storage]` | `compaction_interval` | `10000` |

The RPC setting caps concurrent heavy requests such as `block_results` and
`tx_search`; public RPC providers may want to raise it. Blockstore compaction
is optional and does not enable pruning. When enabled, it compacts the pruned
range in the background. To compact an existing blockstore once, stop the node
and run `celestia-appd compact-blockstore`.

See the [Mocha release upgrade instructions](https://github.com/celestiaorg/celestia-app/releases/tag/v10.4.0-mocha)
for details. Follow the upgrade announcement for your network before replacing
its binary.

## Network upgrade history

v7 (Hibiscus) was skipped on Mainnet Beta due to a bug discovered after testnet activation; v8 (defined in [CIP-49](https://cips.celestia.org/cip-049.html)) was activated instead.

In the Mainnet Beta table, version links point to Celenium upgrade status pages for signaling upgrades (v3+). v2 used a pre-programmed height and does not have a Celenium signaling page.

### Mocha testnet

#### Mocha-5

App version 10 activated on `mocha-5` at the height specified in the
[activation announcement](https://status.celestia.org/incidents/vbsesey3).
Bonded validators can now [start and register their Fibre servers](/operate/consensus-validators/fibre).

| Version | Date and time | Upgrade height | Parameters |
| ------- | ------------- | -------------- | ---------- |
| v10 | 2026/09/24 20:20:15 UTC | [1082619](https://testnet.celestia.explorers.guru/block/1082619) | [v10](https://celestiaorg.github.io/celestia-app/parameters_v10.html) |

#### Mocha-4 (historical)

The upgrades below happened on the `mocha-4` chain. Celenium now indexes `mocha-5`, so explorer pages for these historical upgrades and heights are no longer available.

| Version | Name       | CIP                                                                     | Date and time           | Upgrade height | Delay period | Parameters                                                          |
| ------- | ---------- | ----------------------------------------------------------------------- | ----------------------- | -------------- | ------------ | ------------------------------------------------------------------- |
| v2      | Lemongrass | [CIP-17](https://github.com/celestiaorg/CIPs/blob/main/cips/cip-017.md) | 2024/08/28 14:00 UTC    | 2585031        | —            | [v2](https://celestiaorg.github.io/celestia-app/parameters_v2.html) |
| v3      | Ginger     | [CIP-25](https://cips.celestia.org/cip-025.html)                        | 2024/11/14 18:31:11 UTC | 3140052        | —            | [v3](https://celestiaorg.github.io/celestia-app/parameters_v3.html) |
| v4      | Lotus      | [CIP-33](https://cips.celestia.org/cip-033.html)                        | 2025/07/01 11:51:58 UTC | 6915786        | 2 days       | [v4](https://celestiaorg.github.io/celestia-app/parameters_v4.html) |
| v5      | —          | —                                                                       | 2025/07/30 17:07:29 UTC | 7401191        | 1 block      | [v5](https://celestiaorg.github.io/celestia-app/parameters_v5.html) |
| v6      | Matcha     | [CIP-42](https://cips.celestia.org/cip-042.html)                        | 2025/10/03 01:25:02 UTC | 8236886        | 2 days       | [v6](https://celestiaorg.github.io/celestia-app/parameters_v6.html) |
| v7      | Hibiscus   | [CIP-47](https://cips.celestia.org/cip-047.html)                        | 2026/02/23 18:21:52 UTC | 10209986       | 2 days       | [v7](https://celestiaorg.github.io/celestia-app/parameters_v7.html) |
| v8      | —          | [CIP-49](https://cips.celestia.org/cip-049.html)                        | 2026/04/16 14:26:21 UTC | 10941526       | 2 days       | [v8](https://celestiaorg.github.io/celestia-app/parameters_v8.html) |
| v9      | —          | [CIP-50](https://cips.celestia.org/cip-050.html)                        | 2026/06/05 08:16:10 UTC | 11655991       | 2 days       | [v9](https://celestiaorg.github.io/celestia-app/parameters_v9.html) |

### Mainnet Beta

| Version                                                                         | Name       | CIP                                                                     | Date and time                         | Upgrade height                                                | Delay period | Parameters                                                          |
| ------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------- | ------------ | ------------------------------------------------------------------- |
| v2                                                                              | Lemongrass | [CIP-17](https://github.com/celestiaorg/CIPs/blob/main/cips/cip-017.md) | 2024/09/18 14:00 UTC                  | [2371495](https://celenium.io/block/2371495)                  | —            | [v2](https://celestiaorg.github.io/celestia-app/parameters_v2.html) |
| [v3](https://celenium.io/upgrade/3?tab=signals&page=1)                          | Ginger     | [CIP-25](https://cips.celestia.org/cip-025.html)                        | 2024/12/12 14:28:52 UTC               | [2993219](https://celenium.io/block/2993219)                  | —            | [v3](https://celestiaorg.github.io/celestia-app/parameters_v3.html) |
| [v4](https://celenium.io/upgrade/4?tab=signals&page=1)                          | Lotus      | [CIP-33](https://cips.celestia.org/cip-033.html)                        | 2025/07/28 13:46:27 UTC               | [6680339](https://celenium.io/block/6680339)                  | 7 days       | [v4](https://celestiaorg.github.io/celestia-app/parameters_v4.html) |
| [v5](https://celenium.io/upgrade/5?tab=signals&page=1)                          | —          | —                                                                       | 2025/08/01 14:30:29 UTC               | [6748821](https://celenium.io/block/6748821)                  | 1 block      | [v5](https://celestiaorg.github.io/celestia-app/parameters_v5.html) |
| [v6](https://celenium.io/upgrade/6?tab=signals&page=1)                          | Matcha     | [CIP-42](https://cips.celestia.org/cip-042.html)                        | 2025/11/24 12:33:12 UTC               | [8662012](https://celenium.io/block/8662012?tab=transactions) | 7 days       | [v6](https://celestiaorg.github.io/celestia-app/parameters_v6.html) |
| [v7](https://celenium.io/upgrade/7?tab=signals&page=1)                          | Hibiscus   | [CIP-47](https://cips.celestia.org/cip-047.html)                        | N/A (skipped, see v8)                 | N/A                                                           | —            | —                                                                   |
| [v8](https://celenium.io/upgrade/8?tab=signals&page=1)                          | —          | [CIP-49](https://cips.celestia.org/cip-049.html)                        | 2026/05/05 16:37:35 UTC               | [10960599](https://celenium.io/block/10960599?tab=transactions) | 7 days       | [v8](https://celestiaorg.github.io/celestia-app/parameters_v8.html) |
| [v9](https://celenium.io/upgrade/9?tab=signals&page=1)                          | —          | [CIP-50](https://cips.celestia.org/cip-050.html)                        | 2026/07/01 18:53:25 UTC            | [11771699](https://celenium.io/block/11771699)              | 7 days       | [v9](https://celestiaorg.github.io/celestia-app/parameters_v9.html) |

## Upcoming upgrades

> **Warning:** You do not need to use a tool like [cosmovisor](https://docs.cosmos.network/sdk/v0.53/build/tooling/cosmovisor) to upgrade the binary. Please upgrade your binary before signaling support for the new version.

Mocha has activated app version 10; see the [Mocha-5 upgrade history](#mocha-5).
For upcoming upgrade schedules on each network, follow the
[network announcements](https://status.celestia.org/).

---
Title: Node snapshots
URL: https://docs.celestia.org/operate/maintenance/snapshots.md
Source: app/operate/maintenance/snapshots/page.mdx
---

# Node snapshots

## What are node snapshots?

Node snapshots are pre-synced copies of the blockchain state that allow you to get your node up and running quickly without having to sync from genesis. Think of them as checkpoints - instead of processing every single block since the beginning of the chain, you can start from a recent, verified state.

Among various options for setting up your node, snapshots offer one of the fastest ways to get started. Instead of syncing the entire chain history from the beginning, you can use a snapshot to start from a recent state.

Using snapshots can save you significant time and resources, especially as the blockchain grows larger.

## Pruned vs archive snapshots

There are two main types of snapshots available:

### Pruned snapshots

Pruned snapshots contain only the essential state needed to run a node. They exclude historical data that isn't necessary for current operations, making them much smaller in size. These are ideal for:

- Consensus nodes (including validators) that only need recent state to participate in consensus
- Consensus nodes that don't need complete historical data
- Users who want to get started quickly and aren't concerned with historical queries

### Archive snapshots

Archive snapshots contain the complete blockchain history, including all historical states. They're larger in size but provide access to the entire chain history. You'll need an archive snapshot if you're:

- Running a DA node that needs to serve historical block data
- Operating a consensus node that needs to support historical queries
- Building an application that requires access to past states

## Quick setup with ITRocket

ITRocket provides comprehensive setup services for both mainnet and testnet, including automated installation scripts, snapshots, and state sync services:

- **Mainnet**: [itrocket.net/services/mainnet/celestia/](https://itrocket.net/services/mainnet/celestia/) - Complete setup guides and tools
- **Mocha testnet**: [itrocket.net/services/testnet/celestia/](https://itrocket.net/services/testnet/celestia/) - Complete setup guides and tools

Their services include installation scripts, state sync, snapshots, RPC endpoints, and monitoring tools all in one place.

## Available snapshot providers

### Mainnet beta

| Provider    | Consensus Node                                                                                                                                 | Bridge Node                                                                |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| ITRocket    | [Pruned](https://itrocket.net/services/mainnet/celestia/) • [Archive](https://itrocket.net/services/mainnet/celestia/)                         | [Archive](https://itrocket.net/services/mainnet/celestia/)                 |
| Polkachu    | [Pruned](https://polkachu.com/tendermint_snapshots/celestia)                                                                                   | -                                                                          |
| kjnodes     | [Pruned](https://services.kjnodes.com/mainnet/celestia/snapshot/) • [Archive](https://services.kjnodes.com/mainnet/celestia/snapshot-archive/) | -                                                                          |
| Noders      | [Pruned](https://noders.services/mainnet-networks/celestia/snapshot/)                                                                          | -                                                                          |
| QubeLabs    | [Archive](https://snaps.qubelabs.io/celestia/)                                                                                                 | -                                                                          |

### Mocha testnet

| Provider    | Consensus Node                                                                                                         | Bridge Node                                                                |
| ----------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| ITRocket    | [Pruned](https://itrocket.net/services/testnet/celestia/) • [Archive](https://itrocket.net/services/testnet/celestia/) | [Archive](https://itrocket.net/services/testnet/celestia/)                 |
| Polkachu    | [Pruned](https://polkachu.com/testnets/celestia/snapshots)                                                             | -                                                                          |
| kjnodes     | [Pruned](https://services.kjnodes.com/testnet/celestia/snapshot/)                                                      | -                                                                          |
| QubeLabs    | [Archive](https://snaps.qubelabs.io/celestia/)                                                                         | -                                                                          |

## Using celestia-snapshot-finder

The `celestia-snapshot-finder` is a community tool that automatically finds and downloads the fastest available snapshot for your node. It tests download speeds from verified providers and selects the fastest available snapshot based on your location and network conditions.

### Features

- Automatically finds the optimal snapshot from verified providers
- Selects the best option based on file size and download speed
- Supports both consensus and bridge nodes (pruned and archive snapshots)
- Available for multiple platforms (Linux, macOS) with ARM and AMD64 support
- Includes download progress tracking and resume capability

### Installation

You can download pre-built binaries from the [latest release](https://github.com/21state/celestia-snapshot-finder/releases/latest) page:

- Linux: `celestia-snapshot-finder-linux-amd64` or `celestia-snapshot-finder-linux-arm64`
- macOS: `celestia-snapshot-finder-darwin-amd64` or `celestia-snapshot-finder-darwin-arm64`

Or build from source:

```bash
git clone https://github.com/21state/celestia-snapshot-finder.git
cd celestia-snapshot-finder
./build.sh
```

### Usage examples

A CLI tool for downloading Celestia node snapshots with direct URLs. Supports different node types and snapshot types with automatic or manual selection.

Basic usage:

```bash
celestia-snapshot-finder [node-type] [snapshot-type] [flags]
```

Examples:

```bash
# Download pruned consensus node snapshot
celestia-snapshot-finder consensus pruned

# Download archive bridge node snapshot with manual selection
celestia-snapshot-finder bridge archive --manual
```

Available flags:

```bash
  -n, --chain-id string   Chain ID (default "celestia")
      --debug             Enable debug mode with extra information
  -h, --help              help for celestia-snapshot-finder
  -m, --manual            Enable manual selection
  -v, --version           version for celestia-snapshot-finder
```

In automatic mode (default), the tool will:

1. Test download speeds and verify snapshots from all providers
2. Automatically select and use the fastest available option
3. Start downloading from the selected provider

In manual mode (`--manual` flag), the tool will:

1. Test download speeds and verify snapshots from all providers
2. Show you a list of providers with their download speed, snapshot size, and estimated download time
3. Let you select your preferred provider from the list
4. Start downloading from your selected provider

---
Title: Setting up your node as a background process with SystemD
URL: https://docs.celestia.org/operate/maintenance/systemd.md
Source: app/operate/maintenance/systemd/page.mdx
---

# Setting up your node as a background process with SystemD

SystemD is a daemon service useful for running applications as background
processes.

## Consensus nodes

If you are running a validator or consensus node, here are
the steps to setting up `celestia-appd` as a background process.

### Start the celestia-app with SystemD

SystemD is a daemon service useful for running applications as background
processes.

Create Celestia-App systemd file:

```sh
sudo tee <<EOF >/dev/null /etc/systemd/system/celestia-appd.service
[Unit]
Description=celestia-appd Cosmos daemon
After=network-online.target

[Service]
User=$USER
ExecStart=$(which celestia-appd) start
Restart=on-failure
RestartSec=3
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF
```

If the file was created successfully you will be able to see its content:

```sh
cat /etc/systemd/system/celestia-appd.service
```

Enable and start `celestia-appd` daemon:

```sh
sudo systemctl enable celestia-appd
sudo systemctl start celestia-appd
```

Check if daemon has been started correctly:

```sh
sudo systemctl status celestia-appd
```

Check daemon logs in real time:

```sh
sudo journalctl -u celestia-appd.service -f
```

To check if your node is in sync before going forward:

```sh
curl -s localhost:26657/status | jq .result | jq .sync_info
```

Make sure that you have `"catching_up": false`, otherwise leave it running
until it is in sync.

## Data availability nodes

Before creating either service, replace `<network>` in `ExecStart` with
`mainnet` for Mainnet Beta or `mocha` for Mocha. Use the same network and
user account as the corresponding `celestia bridge init` or `celestia light init`
command. The network determines the default node store; omitting the flag selects
Mainnet Beta, which may leave the service looking for an uninitialised store.

### Celestia bridge node

Create Celestia Bridge systemd file:

```sh
sudo tee <<EOF >/dev/null /etc/systemd/system/celestia-bridge.service
[Unit]
Description=celestia-bridge Cosmos daemon
After=network-online.target

[Service]
User=$USER
ExecStart=$(which celestia) bridge start --p2p.network <network>
Restart=on-failure
RestartSec=3
LimitNOFILE=1400000

[Install]
WantedBy=multi-user.target
EOF
```

If the file was created successfully you will be able to see its content:

```sh
cat /etc/systemd/system/celestia-bridge.service
```

Enable and start celestia-bridge daemon:

```sh
sudo systemctl enable celestia-bridge
sudo systemctl start celestia-bridge && sudo journalctl -u \
celestia-bridge.service -f
```

Now, the Celestia bridge node will start syncing headers and storing blocks
from `celestia-app`.

> **Note:** At startup, you can see the `multiaddress` from the Celestia bridge node. This is needed for future light node connections and communication between Celestia bridge nodes.

Example:

```sh
NODE_IP=<URI>]
/ip4/$NODE_IP/tcp/2121/p2p/12D3KooWD5wCBJXKQuDjhXFjTFMrZoysGVLtVht5hMoVbSLCbV22
```

You should be seeing logs coming through of the bridge node syncing.

### Celestia light node

Start the light node as daemon process in the background

```sh
sudo tee <<EOF >/dev/null /etc/systemd/system/celestia-lightd.service
[Unit]
Description=celestia-lightd light node
After=network-online.target

[Service]
User=$USER
ExecStart=$(which celestia) light start --p2p.network <network> --core.ip <URI> --core.port <port>
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target
EOF
```

If the file was created successfully you will be able to see its content:

```sh
cat /etc/systemd/system/celestia-lightd.service
```

Enable and start celestia-lightd daemon:

```sh
sudo systemctl enable celestia-lightd
sudo systemctl start celestia-lightd
```

Check if daemon has been started correctly:

```sh
sudo systemctl status celestia-lightd
```

Check daemon logs in real time:

```sh
sudo journalctl -u celestia-lightd.service -f
```

Now, the Celestia light node will start syncing headers.
After sync is finished, light node will do Data Availability
Sampling (DAS) from the bridge node.

## How to export logs with SystemD

You can export your logs if you are running
a SystemD service with the following command:

```sh
sudo journalctl -u <your systemd service> -S yesterday > node_logs.txt
sudo journalctl -u <your systemd service> -S today > node_logs.txt
# This command outputs the last 1 million lines!
sudo journalctl -u <your systemd service> -n 1000000 > node_logs.txt
```

---
Title: Troubleshooting
URL: https://docs.celestia.org/operate/maintenance/troubleshooting.md
Source: app/operate/maintenance/troubleshooting/page.mdx
---

# Troubleshooting

## Network selection

Note: If you do not select a network, the default network will be Mainnet Beta.

```sh
celestia <node-type> init --p2p.network <network>
celestia <node-type> start --p2p.network <network> \
    --core.ip <URI> --core.port <port>
```

Refer to [the ports section of this page](#ports) for information on which ports are required to be open on your machine.

> **Note:** It is advised before switching networks to reinitialize your node via `init` command. This is due to an old config being present. Re-initialisation will reset the config.

### Chain ID

When interacting with celestia-node, it is important to take into account
the different chain IDs for different networks. For Mainnet Beta, there is
no need to declare a chain ID, as the default is `celestia`,
_i.e._ no `--p2p.network string` flag is required for Mainnet Beta.

| Network      | Chain ID                   | `--p2p.network string`                  |
| ------------ | -------------------------- | --------------------------------------- |
| Mainnet Beta | celestia | not required (`--p2p.network celestia`) |
| Mocha        | mocha-5   | `--p2p.network mocha`                   |

## Ports

When interacting with a Celestia node,
you may need to open ports on your machine to allow
communication between nodes, such as bridge nodes. It is essential that
specific ports are accessible. Make sure that your firewall allows
connections to the correct ports.

If you run a node on a cloud server, make sure that the ports are open
on the server's firewall. If you run a node at home, make sure that your
router allows connections to the correct ports.

For example, validator (consensus node) ports 9090
and 26657 need to be accessible by the bridge, and port 2121 is
required for P2P connections for all node types.

The following ports are used by Celestia nodes:

| Port  | Protocol | Address   | Description  | Enabled by default on node | Flag                    |
| ----- | -------- | --------- | ------------ | -------------------------- | ----------------------- |
| 2121  | TCP/UDP  | localhost | P2P          | true                       | N/A                     |
| 26658 | HTTP     | localhost | RPC          | true                       | `--rpc.port string`     |
| 26659 | HTTP     | localhost | REST Gateway | false                      | `--gateway.port string` |

> **Warning:** The gateway endpoints have been deprecated and will be removed in the future. If you would like to use them anyway, you can [find more details on GitHub](https://github.com/celestiaorg/celestia-node/pull/2360).

## Changing the location of your node store

### Background

An [enhancement has been made in v0.14.0+](https://github.com/celestiaorg/celestia-node/pull/3246)
to automate the detection of the running node, eliminating the need to
manually specify the `--node.store` flag for each RPC request.

**Assumptions:**

- The presence of a lock signifies a running node.
- Networks are ordered as Mainnet Beta, Mocha, private, custom.
- Node types are ordered as bridge and light.
- Each network has only one running node type.
- Multiple nodes of the same network and type are prohibited
  (resulting in an `Error: node: store is in use`).

**Key Points:**

- Authentication token and other flags maintain their previous behavior
  and take precedence.
- Address and port details are fetched from the configuration.
- `skipAuth` allows bypassing authentication for trusted setups and follows
  Unix daemon conventions.
- Non-default node store and cel-key configurations still require specific
  flags in the configuration settings.

### Demonstration

In this section, we'll guide you through starting your node using a
node store in a different location than you originally started with.

First, stop your node safely using `control + C`.

Then, init your node again with a new node store:

```bash
celestia <node-type> init --node.store /home/user/celestia-<node-type>-location/ \
    --p2p.network mocha
```

Next, start your node:

```bash
celestia bridge start --core.ip <archival-consensus-endpoint> --p2p.network mocha \
    --node.store /home/user/celestia-bridge-location/ --core.port <port>
```

If you choose to change the location of your node store,
you will need to execute each command on your node with
the following flag:

```bash
--node.store /home/user/celestia-<node-type>-location/
```

When using `cel-key`, the process is different.
To show the keys you should add `--keyring-dir` like this example:

```bash
./cel-key list --p2p.network mocha --node.type bridge \
    --keyring-dir /home/user/celestia-bridge-location/keys/
```

### Examples

#### Mainnet Beta bridge and Mocha light

This example uses a Mainnet Beta bridge node and a Mocha light node. When
making the request:

```bash
❯ celestia blob get 1318129 0x42690c204d39600fddd3 0MFhYKQUi2BU+U1jxPzG7QY2BVV1lb3kiU+zAK7nUiY=
{
 "result": "RPC client error: sendRequest failed: http status 401 Unauthorized unmarshaling response: EOF"
}
```

The request will go to the Mainnet Beta node, and a 401 will show in
this node's logs. Note that a 401 is expected because this blob was
posted to Mocha and neither the namespace nor the blob exist on Mainnet Beta.

#### Using a custom rpc.config address

When using a custom RPC config address `0.0.0.1` and port `25231`,
the CLI accurately routes to the custom address and port, where no
node is running. It fails as expected:

```bash
❯ celestia blob get 1318129 0x42690c204d39600fddd3 0MFhYKQUi2BU+U1jxPzG7QY2BVV1lb3kiU+zAK7nUiY=
{
  "result": "RPC client error: sendRequest failed: Post \"http://0.0.0.1:25231\": dial tcp 0.0.0.1:25231: connect: no route to host"
}
```

## Resetting your config

> **Warning:** When upgrading from a version earlier than celestia-node v0.31.3 to v0.31.3 or later, run `config-update` after replacing the binary and before starting the node. The [v0.31.3 release](https://github.com/celestiaorg/celestia-node/releases/tag/v0.31.3) adds support for Mainnet Beta v9 and introduces new config fields, including RPC rate limiting. Skipping this step leaves the new options at their defaults and may cause config warnings.

If you encounter an error, it is likely that an old config file is present:

```sh
Error: nodebuilder/share: interval must be positive; nodebuilder/core: invalid IP addr given:

# or

Error: nodebuilder/share: interval must be positive
```

You can re-initialize your node's config with the following commands:

Save your config so custom values are not lost.

Run the following command to update your config:

```bash
celestia <node-type> config-update --p2p.network <network>
```

This will pull in any new values from new configuration
and merge them into the existing configuration.

After using the `config-update` command, double-check that your custom values are preserved.

Then, to start your node again:

```bash
celestia <node-type> start --p2p.network <network>
```

## Clearing the data store

For **bridge and light nodes**,
remove the data store with this command:

```bash
celestia <node-type> unsafe-reset-store --p2p.network <network>
```

```bash
celestia light unsafe-reset-store --p2p.network mocha
```

## FATAL headers given to the heightSub are in the wrong order

If you observe a FATAL log line like:

```bash
FATAL   header/store   store/heightsub.go:87    PLEASE FILE A BUG REPORT: headers given to the heightSub are in the wrong order"
```

then it is possible the celestia-node `data/` directory contains headers from a
previous instance of the network that you are currently trying to run against.
One resolution strategy is to delete the existing celestia-node config for the
target network and re-initialize it:

```sh
# rm -rf ~/.celestia-<node-type>-<network>
rm -rf ~/.celestia-bridge-private

# celestia <node-type> init --p2p.network <network>
celestia bridge init --p2p.network private
```

## Error: "too many open files"

When running a Celestia bridge node, you may encounter an error in the
logs similar to this:

```bash
Error while creating log file in valueLog.open error: while opening file: /opt/celestia/.celestia-bridge/data/003442.vlog error: open /opt/celestia/.celestia-bridge/data/003442.vlog: too many open files
```

This error indicates that the Celestia application is trying to open more
files than the operating system's limit allows. To fix this, you will need
to edit the Celestia bridge service file to increase the number of file
descriptors that the service can open.

1. Open the service file for editing:

```bash
nano /etc/systemd/system/celestia-bridge.service
```

2. Modify the `LimitNOFILE` parameter:

In the service file, find the `LimitNOFILE` parameter under the
`[Service]` section and set its value to `1400000`. It should look like this:

```ini
[Service]
...
LimitNOFILE=1400000
...
```

> **Note:** Be cautious when increasing file descriptor limits. Setting this value too high might affect system performance. Ensure the value is appropriate for your system's capabilities.

3. Reload daemon and restart bridge service:

```bash
sudo systemctl daemon-reload
```

```bash
sudo systemctl restart celestia-bridge
```

## Error: "no space left on device"

When a bridge node runs on `ext4` file system, there will be errors like the following due to large folder size:

```bash
ERROR   header/sync     sync/sync.go:227        syncing headers {"from": 5074102, "to": 5161144, "err": "creating file: creating ODSQ4 file: creating Q4 file: creating Q4 file: open /root/.celestia-bridge-mocha-5/blocks/C9ADF6D9F862D92993D67977DE407D17ECF7F1DACE5FB7FE9A6845F4BD0172CE.q4: no space left on device"}
```

You may also observe similar errors from the `tar` command when extracting a snapshot of an archival bridge node.

There are two solutions to this problem:

#### Option 1: enable the large_dir feature for ext4

> **Note:** If the Node Store is on the same partition as the OS, it is recommended to take Option 2.

1. Stop the node
2. Unmount the device and run the following command:

```bash
# unmount the partition
# the value of <target> can be either the partition name (e.g., /dev/sdc1) or the mountpoint (e.g., /mnt/celestia)
sudo umount <target>

# enable the large_dir feature, use the partition name like /dev/sdc1 here
# if RAID is set, you can use the partition name like /dev/md0 for tune2fs
sudo tune2fs -O large_dir </dev/partition>

# perform a filesystem consistency check
sudo fsck -f </dev/yourpartition>

# mount the partition again
sudo mount </dev/yourpartition> <mountpoint>
```

3. Restart the node

#### Option 2: migrate to XFS/ZFS file system

Make sure you have your node id backed up so that you can import them later on.

## Error: "can't get key ...: too many failed passphrase attempts"

If you have initialized a bridge node with option `--keyring.backend file`, you will be asked to provide a keyring passphrase. Then a bridge node key `my_celes_key` is auto-generated by the `init` command. However, this does not work well with the systemd service setup because every time when the bridge node is started, it asks for the passphrase. The systemd service will keep failing with the following error:

```bash
ERROR        module/state        state/keyring.go:23        can't get key: `my_celes_key` from the keystore: too many failed passphrase attempts
```

Usually a bridge node wallet does not need to be funded unless you plan to do `PayForBlob` through it. We suggest using the default keyring backend (`test`) in this case which does not require a passphrase.

If you don't want to init the node again, you can do the following steps:

```bash
# update the config.toml file in the home folder of the bridge node or adjust your systemd service definition
[State]
  DefaultKeyName = "my_celes_key"
  DefaultBackendName = "test"

# recover the key using `cel-key`
# add `--keyring-dir </service_home_folder/keys/>` if you are using a custom home folder for the node
cel-key add my_celes_key --recover --node.type bridge --p2p.network <network>
```

---
Title: Syncing a light node from a trusted hash
URL: https://docs.celestia.org/operate/maintenance/trusted-hash-recovery.md
Source: app/operate/maintenance/trusted-hash-recovery/page.mdx
---

# Syncing a light node from a trusted hash

This guide goes over how to sync a DA light node from a trusted hash.
The example uses the Mocha testnet. You will need to adjust the commands accordingly for Mainnet Beta or a custom network.

If you already have a data store for your node, you need to remove it before syncing from a trusted hash:

```sh
rm -rf ~/.celestia-light-mocha-5/data
```

You also cannot sync to a height earlier than the data availability sampling (DAS) start height.
If you want data from height `n`, start syncing from at least height `n`.

> **Warning:** Syncing to a trusted hash means that you will not sample the entire chain. This adds a trust assumption that you trust the history of the chain up to that point and that you trust the entity where you get the hash from. In this example, the trusted entity is a consensus endpoint or Celenium.

## Historical queries

> **Warning:** Default light nodes no longer support historical queries. By default, nodes maintain a sliding window of headers, bounded by Tail and Head headers. Requests with height below the Tail are rejected. This is temporary; lazy header fetching will be available with Backward Sync.

To retain the ability to request older queries with light nodes, use the new configuration fields to set an absolute header that the node will sync from:

- `Header.Syncer.SyncFromHeight`: Set the height from which the node will sync
- `Header.Syncer.SyncFromHash`: Set the hash from which the node will sync

By configuring these fields, your light node will maintain history from the specified height onward, allowing you to query historical data from that point.

## General Approach

### Get a trusted height and hash

Get trusted height & hash from a consensus endpoint or [Celenium](https://celenium.io).

### Initialize the node store

   ```sh
   celestia light init --p2p.network <network>
   ```

### Set the trusted height and hash

1. Open your `config.toml` at `.celestia-light/config.toml` (or `.celestia-light-<other-network>/config.toml`)
2. Set `Header.Syncer.SyncFromHeight` to the trusted height (e.g. `SyncFromHeight = 123456`)
3. Set `Header.Syncer.SyncFromHash` to the trusted hash (e.g. `SyncFromHash = "<hash_of_block_n>"`, with **no `0x` prefix**.)

### Start the node

```sh
celestia light start --p2p.network <network> --core.ip <consensus-node-rpc> --core.port <port>
```

## Automated Approach

You can automate the process of setting the trusted height and hash using the following commands for Mocha testnet:

### Initialize the node store (if not already done)

```sh
celestia light init --p2p.network mocha
```

### Get and set the trusted height and hash automatically

```sh
# Get the height and hash of the same block in a single call
read -r TRUSTED_HEIGHT TRUSTED_HASH <<<"$(curl -s https://public-endpoint.celestia-mocha.quiknode.pro/block | jq -r '.result | "\(.block.header.height) \(.block_id.hash)"')" && export TRUSTED_HEIGHT TRUSTED_HASH

# Use sed to find and replace the SyncFromHeight value in the config file (macOS version)
sed -i '' "s/SyncFromHeight = .*/SyncFromHeight = $TRUSTED_HEIGHT/" ~/.celestia-light-mocha-5/config.toml

# Add/update the SyncFromHash value
sed -i '' "s/SyncFromHash = .*/SyncFromHash = \"$TRUSTED_HASH\"/" ~/.celestia-light-mocha-5/config.toml

# Display the updated values to confirm
echo "SyncFromHeight updated to: $TRUSTED_HEIGHT"
echo "SyncFromHash updated to: $TRUSTED_HASH"
```

### Start the node

```sh
celestia light start --p2p.network mocha \
  --core.ip public-endpoint.celestia-mocha.quiknode.pro \
  --core.port 9090 --core.tls
```

> **Tip (Linux):** Remove the empty string (`''`) after `-i` in the `sed` commands:  
> `sed -i "s/SyncFromHeight = .*/SyncFromHeight = $TRUSTED_HEIGHT/" ~/.celestia-light-mocha-5/config.toml`  
> `sed -i "s/SyncFromHash = .*/SyncFromHash = \"$TRUSTED_HASH\"/" ~/.celestia-light-mocha-5/config.toml`

## For service operators

If you're using multiple light nodes for similar services like tracking the same rollup,
it is recommended to use the same hash and height for all services using
the same starting height.

---
Title: Local devnet setup
URL: https://docs.celestia.org/operate/networks/local-devnet.md
Source: app/operate/networks/local-devnet/page.mdx
---

# Local devnet setup

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.

## Choose your setup method

Pick the approach you want to follow:

**Docker Compose**

### Install Docker

Install [Docker and Docker Compose](https://docs.docker.com/get-docker).

### Create a Docker Compose file

Create a `docker-compose.yml` file with the following content:

   ```yaml
   version: "3.8"
   services:
     celestia-validator:
       image: ghcr.io/celestiaorg/celestia-app:latest
       container_name: celestia-validator
       volumes:
         - celestia_validator_data:/home/celestia
       ports:
         - "9090:9090"
         - "26656:26656"
         - "26657:26657"
       command: |
         sh -c "
         celestia-appd init mynode --chain-id private &&
         celestia-appd start
         "
       networks:
         - celestia-network

     celestia-bridge:
       image: ghcr.io/celestiaorg/celestia-node:latest
       container_name: celestia-bridge
       environment:
         - P2P_NETWORK=private
       volumes:
         - celestia_bridge_data:/home/celestia
       ports:
         - "26658:26658"
       command: >
         celestia bridge start
         --p2p.network private
         --core.ip celestia-validator
         --rpc.addr 0.0.0.0
         --rpc.port 26658
       depends_on:
         - celestia-validator
       networks:
         - celestia-network

   volumes:
     celestia_validator_data:
     celestia_bridge_data:

   networks:
     celestia-network:
       driver: bridge
   ```

### Start the services

   ```bash
   docker-compose up -d
   ```

### Check the status

   ```bash
   docker-compose ps
   docker-compose logs celestia-validator
   docker-compose logs celestia-bridge
   ```
### Test your setup

1. Check consensus node status:

   ```bash
   curl http://localhost:26657/status
   ```

2. Query the latest block:

   ```bash
   curl http://localhost:26657/block
   ```

3. Check the bridge node head:

   ```bash
   curl http://localhost:26658/head
   ```

### Stop the devnet

Stop and remove containers:

```bash
docker-compose down
```

### Reset / start fresh

Stop and remove containers **and wipe chain data** (volumes):

```bash
docker-compose down -v
```

**From source (scripts)**

### 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. Query the latest block:

   ```bash
   curl http://localhost:26657/block
   ```

3. Check the bridge node head:

   ```bash
   curl http://localhost:26658/head
   ```

### Stop the devnet

Stop the processes with `Ctrl+C` in each terminal.

### 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
celestia-appd tendermint unsafe-reset-all --home $HOME/.celestia-app
```

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).

## 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

With your local devnet running, you can:

- [Submit blob data](/learn/TIA/submit-data)
- Test rollup integrations
- Develop applications using the [Celestia Node API](/build/rpc/node-api)
- Practice validator operations without risking real tokens

---
Title: Mainnet Beta
URL: https://docs.celestia.org/operate/networks/mainnet-beta.md
Source: app/operate/networks/mainnet-beta/page.mdx
---

# Mainnet Beta

![Mainnet Beta](/img/Mainnet-Beta.png)

Welcome to the guide for Celestia's Mainnet Beta.
Mainnet Beta is the culmination of rigorous community testing,
upgrades, and feedback. It serves as the platform for deploying
Mainnet Beta rollups and unstoppable applications.

## Network stability and upgrades

Mainnet Beta is a stable network, but will still receive updates and
improvements. Any changes or upgrades will be coordinated with node
operators and the broader Celestia community to ensure seamless
integration and minimal service interruptions.

As we step into unexplored territories with groundbreaking technologies
like data availability sampling, it's crucial to remember that Mainnet
Beta remains experimental at this stage. While the network is live and
functional, users may encounter occasional instability or reduced performance.

## Network details

| Detail        | Value                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------- |
| Chain ID      | `celestia`                                                                       |
| Genesis hash  | `6BE39EFD10BA412A9DB5288488303F5DD32CF386707A5BEF33617F4C43301872`                                 |
| Genesis file  | <a href={`https://github.com/celestiaorg/networks/blob/main/$celestia/genesis.json`}>genesis.json</a> |
| Peers file    | <a href={`https://github.com/celestiaorg/networks/blob/main/$celestia/peers.txt`}>peers.txt</a>       |
| Validators    | 100                                                                                                |
| Block time    | [Approximately 3 seconds](https://cips.celestia.org/cip-048.html)                                      |

The happy-path cadence is approximately 2.6 seconds, so integrations should
treat 3 seconds as an approximate target rather than an exact interval.

## Software version numbers

| Software       | Version                                                             |
| -------------- | ------------------------------------------------------------------- |
| celestia-node  | [v0.34.3](https://github.com/celestiaorg/celestia-node/releases/tag/v0.34.3) |
| celestia-app   | [v10.4.0](https://github.com/celestiaorg/celestia-app/releases/tag/v10.4.0)   |

## Network status

For real-time network status information, including uptime, incident reports,
and service availability, visit the
[official Celestia Mainnet status page](https://status.celestia.dev/status/mainnet).

## Network parameters

### Transaction size limit

The maximum transaction size on all networks is 8 MiB (8,388,608 bytes). See [CIP-38](https://cips.celestia.org/cip-038.html) which activated at [the v6 upgrade height](/operate/maintenance/network-upgrades#matcha-network-upgrade).

Previously, in [CIP-28](https://cips.celestia.org/cip-028.html), there was a 2 MiB limit on transaction size. This limit was implemented to maintain network stability and provide clear expectations for users and developers, even as block sizes may be larger.

### Block size limit

While individual transactions are limited to 8 MiB as of v6, a block can contain multiple transactions and has a much larger capacity. The maximum block size is determined by the effective maximum square size.

The current maximum block capacity on Mocha and Mainnet Beta is 32 MiB. On
Mainnet Beta, the governance square size is 256 (a 32 MiB square) and the
consensus encoded-block limit is also 32 MiB; the effective capacity is the
smaller of the two.

The following provides an approximation of the maximum blob capacity:

- The maximum square size is 256x256, which gives us 65,536 shares.
- One share is reserved for the PFB transaction, leaving us with 65,535 shares available for blob data.
- The first sparse share has 478 bytes available, and the remaining sparse shares have 482 bytes each.

Approximate capacity:

```
First share:       1 x 478 bytes
Remaining shares:  65,534 x 482 bytes
Total bytes:       31,587,866 bytes
```

There is no precise, static upper bound on the maximum total
blob size. It depends on several factors:

- The maximum square size, which is determined by a governance parameter
  and a versioned constant.
- The maximum bytes in a block, which is determined by a governance parameter
  and a hard-coded constant in CometBFT.
- The number of shares occupied by the PFB transaction share.

These factors can cause the maximum total blob size that can be included in one
block to vary.

See the code in
[celestia-app](https://github.com/celestiaorg/celestia-app/blob/v9.0.4/pkg/appconsts/initial_consts.go#L13).

Full network parameters, such as [max bytes](https://github.com/celestiaorg/celestia-app/blob/v9.0.4/specs/src/parameters_v9.md?plain=1#L41),
can be found in the
[celestia-app specifications](https://celestiaorg.github.io/celestia-app/parameters_v9.html).

## Network constants

For the current Mainnet Beta network constants, see
[celenium.io/constants](https://celenium.io/constants).

## Integrations

This guide contains the relevant sections for how to connect to Mainnet Beta,
depending on the type of node you are running. Your best approach to
participating is to first [determine which node you would like to run](/operate/getting-started/overview). Each
node's guide will link to the relevant network in order to show you how
to connect to them. Learn about the different endpoint types
[in the Cosmos SDK documentation](https://docs.cosmos.network/sdk/v0.53/learn/advanced/grpc_rest).

### Production RPC endpoints

These RPC providers are meant to be used in production environments
and for specific use cases that require reliable access to full block
history, such as:

- Running Bridge Nodes that download data from core RPC endpoints
- Applications that need Bridge Node endpoints with guaranteed uptime and SLAs
- Submitting blobs in production settings (free RPC endpoints have no guarantees, even for submitting transactions)

| Provider  | URL                                                                                       |
| --------- | ----------------------------------------------------------------------------------------- |
| Quicknode | [https://www.quicknode.com/chains/celestia](https://www.quicknode.com/chains/celestia) ([docs](https://quicknode.com/docs/celestia)) |

If you are using Quicknode or another provider with authenticated endpoints,
see [the light node guide](/operate/data-availability/light-node/advanced#optional-start-light-node-with-consensus-endpoint-authentication)
to learn how to use an endpoint with x-token.

### Public RPC endpoint

For development, testing, and documentation examples, use the public Quicknode
endpoint:

| Interface | Endpoint |
| --------- | -------- |
| HTTP RPC and REST | `https://public-endpoint.celestia-mainnet.quiknode.pro` |
| WebSocket | `wss://public-endpoint.celestia-mainnet.quiknode.pro/websocket` |
| gRPC over TLS | `public-endpoint.celestia-mainnet.quiknode.pro:9090` |
| DA JSON-RPC | `https://public-endpoint.celestia-mainnet.quiknode.pro` |

This shared endpoint does not provide a production SLA. Use a [production
provider](#production-rpc-endpoints) or your own node for production workloads.

### Node setup and tools

For paid archive RPC reads, indexed data APIs, and MCP access, see
[community services](/build/rpc/community-services).

Several community providers offer comprehensive node setup tools, installation scripts, and monitoring services to help node operators get started quickly:

| Provider | Installation guide                                             | State sync                                                    | Monitoring tools                                                |
| -------- | -------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------- |
| ITRocket | [Setup guide](https://itrocket.net/services/mainnet/celestia/) | [State sync](https://itrocket.net/services/mainnet/celestia/) | [Chain status](https://itrocket.net/services/mainnet/celestia/) |

### Community consensus endpoints

> **Warning:** Do not rely on the free community endpoints listed below for production deployments. Production deployments should rely on [service providers with SLAs](#production-rpc-endpoints).

You can also find the list of official Celestia bootstrappers in the [celestia-node GitHub repository](https://github.com/celestiaorg/celestia-node/blob/a87a17557223d88231b56d323d22ac9da31871db/nodebuilder/p2p/bootstrap.go#L39).

The following table lists community-provided consensus node endpoints that you can use:

| Provider        | RPC Endpoint                            | API Endpoint                            | gRPC Endpoint                             | WebSocket Endpoint                                       |
| --------------- | --------------------------------------- | --------------------------------------- | ----------------------------------------- | -------------------------------------------------------- |
| AlphaB          | `rpc-celestia.alphab.ai`               | `api-celestia.alphab.ai`               | `rpc-celestia.alphab.ai:9090`             | -                                                        |
| CitizenWeb3     | `rpc.celestia.citizenweb3.com`          | `api.celestia.citizenweb3.com`          | `grpc.celestia.citizenweb3.com:443`       | -                                                        |
| Cumulo          | `celestia.cumulo.org.es`                | `celestia.api.cumulo.org.es`            | `celestia.grpc.cumulo.org.es:443`         | `wss://celestia.cumulo.org.es/websocket`                 |
| ITRocket        | `celestia-mainnet-rpc.itrocket.net:443` | `celestia-mainnet-api.itrocket.net:443` | `celestia-mainnet-grpc.itrocket.net:443`  | -                                                        |
| kjnodes         | `celestia.rpc.kjnodes.com`              | `celestia.api.kjnodes.com`              | `celestia.grpc.kjnodes.com:443`           | -                                                        |
| lunaroasis      | `rpc.lunaroasis.net`                    | -                                       | `grpc.lunaroasis.net:443`                 | -                                                        |
| Noders Services | `celestia-rpc.noders.services`          | -                                       | -                                         | -                                                        |
| Numia           | `public-celestia-rpc.numia.xyz`         | `public-celestia-lcd.numia.xyz`         | `public-celestia-grpc.numia.xyz`          | `wss://public-celestia-rpc.numia.xyz/websocket`          |
| P-OPS           | `rpc.celestia.pops.one`                 | `api.celestia.pops.one`                 | `grpc.celestia.pops.one`                  | -                                                        |
| Stakin          | `celestia.rpc.stakin-nodes.com`         | `celestia.rest.stakin-nodes.com`        | `celestia.grpc.stakin-nodes.com:443`      | -                                                        |
| deNodes         | `celestia-mainnet-rpc.denodes.xyz`      | `celestia-mainnet-api.denodes.xyz`      | -                                         | `wss://celestia-mainnet-rpc.denodes.xyz:443/websocket`   |

> Live latency benchmarks for public no-key Celestia RPC endpoints (PublicNode, Polkachu, LavenderFive — Tendermint status p50/p90/p99, 3 probe regions, updated every 60 s): [OpenChainBench Celestia RPC](https://openchainbench.com/benchmarks/celestia-rpc)

### Connecting DA nodes to consensus nodes

Data availability (DA) nodes need to connect to consensus nodes to sync blocks and access state. When starting a DA node, you'll need to provide a consensus node endpoint using the `--core.ip` parameter and the port.

Example command for starting a DA node with a consensus endpoint:

```bash
celestia <da_type> start --core.ip <consensus_node_url> --core.port <port>
```

You can use the [public endpoint](#public-rpc-endpoint) or any of the RPC
endpoints from the [community consensus endpoints](#community-consensus-endpoints)
table above. The default port is 9090, where gRPC is used for both block sync
and state access.

For example, to connect to the public Quicknode endpoint:

```bash
celestia light start \
  --core.ip public-endpoint.celestia-mainnet.quiknode.pro \
  --core.port 9090 --core.tls
```

### Bridge node requirements

Not all RPC endpoints guarantee the full block history.
Bridge nodes require access to the full historical block data, so you should use an archive endpoint to run your bridge node.

Check the [production endpoints](#production-rpc-endpoints) or the [community dashboard](https://celestia-tools.brightlystake.com/) to identify which endpoints are archive nodes with full historical data.

Alternatively, you can run your own consensus node with no pruning for your bridge node.

### Archival DA RPC endpoints

By default, light nodes prune recent data to save on storage space. Archival
data availability (DA) nodes store the entire history of the chain without
pruning any data so all data available data is retrievable. You can
[read more about light vs archival nodes](/learn/celestia-101/retrievability/).

| Provider                         | Endpoint                                                                                  | RPC Port | Gateway Port |
| -------------------------------- | ----------------------------------------------------------------------------------------- | -------- | ------------ |
| Quicknode                        | [https://www.quicknode.com/chains/celestia](https://www.quicknode.com/chains/celestia) ([docs](https://quicknode.com/docs/celestia)) | -        | -            |
| Mzonder                          | `celestia-da-full-storage.mzonder.com`                                                    | 27758    | 27759        |
| Noders Services                  | `celestia-archive-da.noders.services`                                                     | 26658    | 26659        |
| ITRocket                         | `celestia-mainnet-da-full-storage.itrocket.net`                                           | 26658    | 26659        |
| See the Brightly Stake dashboard | [https://celestia-tools.brightlystake.com/](https://celestia-tools.brightlystake.com/)                                               | -        | -            |

## Explorers

There are multiple explorers you can use for Mainnet Beta:

- [https://celenium.io](https://celenium.io)
- [https://celestia.explorers.guru](https://celestia.explorers.guru)
- [https://celestia.valopers.com/](https://celestia.valopers.com/)
- [https://explorer.nodestake.top/celestia](https://explorer.nodestake.top/celestia)
- [https://mainnet.itrocket.net/celestia/](https://mainnet.itrocket.net/celestia/)
- [https://mammoblocks.io/](https://mammoblocks.io/)
- [https://mintscan.io/celestia](https://mintscan.io/celestia)
- [https://stakeflow.io/celestia](https://stakeflow.io/celestia)

## Community endpoint status dashboard

To check the current status, uptime, and health of all community endpoints, visit the [RPC stats for Celestia dashboard](https://celestia-tools.brightlystake.com/). This dashboard provides real-time information about:

- Which endpoints are currently online
- Response times and performance metrics
- Which endpoints are archive nodes with full historical data
- Last seen heights for each endpoint

This is an essential resource when selecting endpoints for your nodes or applications.

For a multi-region view of public consensus RPC endpoints, use
[Cumulo's check_d Endpoint Scan](https://cumulo.pro/services/celestia/rpcscan.php).
It shows endpoint health, block height, historical reliability, and response
latency from probes in the United States, Europe, Canada, and Singapore.

## Analytics

The following websites provide analytics for Celestia:

- [https://alphab.ai/s/m/celestia/](https://alphab.ai/s/m/celestia/)
- [https://itrocket.net/services/mainnet/celestia/](https://itrocket.net/services/mainnet/celestia/) - Node setup, monitoring, and chain status tools
- [https://itrocket.net/services/mainnet/celestia/analytics/consensus-signal-tracker/](https://itrocket.net/services/mainnet/celestia/analytics/consensus-signal-tracker/) - Consensus signal tracker
- [https://itrocket.net/services/mainnet/celestia/decentralization/](https://itrocket.net/services/mainnet/celestia/decentralization/)
- [https://services.kjnodes.com/mainnet/celestia/slashboard](https://services.kjnodes.com/mainnet/celestia/slashboard)

## Node maps

The following websites provide visual maps of Celestia DA nodes:

- [https://probelab.io/celestia/](https://probelab.io/celestia/) (community contribution)

## Network upgrades

There are a few ways to stay informed about network upgrades on Mainnet Beta:

- Telegram [announcement channel](https://t.me/+smSFIA7XXLU4MjJh)
- Discord [Mainnet Beta announcements](https://discord.com/channels/638338779505229824/1169237690114388039)

See the [network upgrades page](/operate/maintenance/network-upgrades) to learn more
about specific upgrades like the [Ginger network upgrade](/operate/maintenance/network-upgrades#ginger-network-upgrade).

---
Title: Mocha testnet
URL: https://docs.celestia.org/operate/networks/mocha-testnet.md
Source: app/operate/networks/mocha-testnet/page.mdx
---

# Mocha testnet

![mocha-testnet](/img/mocha.jpg)

This guide contains the relevant sections for how to connect to Mocha,
depending on the type of node you are running. Mocha testnet is designed
to help validators test out their infrastructure and node software.
Developers can also deploy sovereign rollups on Mocha.

Mocha is a milestone in Celestia, allowing everyone to test out
core functionalities on the network. Read [the announcement](https://blog.celestia.org/celestia-testnet-introduces-alpha-data-availability-api).
Your best approach to participating is to first determine which node
you would like to run. Each node's guide will link to the relevant networks,
to show you how to connect to them.

## Mocha-5 network restart

Mocha-5 is a new chain that started at height 1; it is not an in-place
upgrade from `mocha-4`. Existing consensus operators must initialize
`mocha-5` in a separate home directory, as described below. You do not
need to keep your own copy of `mocha-4` chain data.

Mocha-5 is live. It is a hardspoon of `mocha-4` at block
[13205115](https://celestia.explorers.guru/block/13205115): only account
balances recorded at that height carried over. Transactions and balance
changes after that height do not exist on `mocha-5`, and account
sequences were reset to 0. Delegations, unbonding delegations, and
pending staking rewards were redeemed as liquid balances.

The initial validator set was created from separately coordinated
genesis transactions. Other validators can join by submitting
`MsgCreateValidator` once their node is synced. The `mocha-4` validator
set, governance proposals, IBC channels, Hyperlane state, community
pool, and all other chain state did not carry over.

`mocha-4` remains running until it is officially shut down on
September 1, 2026. All services still pointing at `mocha-4` should move
to `mocha-5` before then. If you operate a `mocha-4` validator, keep it
running while you migrate if possible; if you need to stop it sooner,
unbond it from the active set first so it does not affect `mocha-4`
block production.

### Accessing mocha-4 history

Because `mocha-5` started from a new genesis, `mocha-4` history is not
queryable on the new network. Blobs and rollup data posted to `mocha-4`
are not retrievable on `mocha-5`. Individual node operators are not
expected to retain `mocha-4` data. An exported copy of the final
`mocha-4` state will be available for one month after the shutdown.

If you depend on specific `mocha-4` transaction history, export what you
need before the September 1, 2026 shutdown.

An archival `mocha-4` node snapshot taken on 2026-08-19 is available at
[snaps.qubelabs.io/celestia/mocha-4_2026-08-19.tar](https://snaps.qubelabs.io/celestia/mocha-4_2026-08-19.tar).
Note that it is approximately 12.3 TB. Follow the
[status page announcement](https://status.celestia.org/incidents/nc1nkb54)
for updates.

### Prepare a separate consensus-node home

If you already operate a `mocha-4` consensus node or validator, do not
initialize `mocha-5` in the existing `$HOME/.celestia-app` directory.
That directory's `data/priv_validator_state.json` records the last
`mocha-4` height you signed, and a validator will not sign at a height
at or below that value. Because `mocha-5` restarts at height 1, a node
reusing the old home would refuse to sign. The old `data` directory also
holds blocks from a different chain, which will not reconcile with the
`mocha-5` genesis.

Using a separate home avoids both problems and leaves your `mocha-4`
node runnable if you need to fall back during the cutover. Back up your
[wallet keys](/operate/keys-wallets/celestia-app-wallet#key-management)
and `$HOME/.celestia-app/config/priv_validator_key.json` before
continuing.

Initialize `mocha-5` with its own home directory:

```bash
MOCHA_5_HOME="$HOME/.celestia-app-mocha-5"

celestia-appd init "node-name" \
  --chain-id mocha-5 \
  --home "$MOCHA_5_HOME"

celestia-appd download-genesis mocha-5 \
  --home "$MOCHA_5_HOME"
# if this command doesn't exist in the binary, use this instead:
# curl -sL "https://raw.githubusercontent.com/celestiaorg/networks/main/mocha-5/genesis.json" -o "$MOCHA_5_HOME/config/genesis.json"
```

Configure the new Mocha seeds and peers in that directory:

```bash
SEEDS=$(curl -sL https://raw.githubusercontent.com/celestiaorg/networks/main/mocha-5/seeds.txt | tr '\n' ',')

sed -i.bak -e "s/^seeds *=.*/seeds = \"$SEEDS\"/" "$MOCHA_5_HOME/config/config.toml"
```

Do not copy the `mocha-4` data directory or
`data/priv_validator_state.json` into the new home.

Run `mocha-5` under a separate service whose start command includes the
new home:

```bash
celestia-appd start --home "$MOCHA_5_HOME"
```

You have a list of options on the types of nodes you can run to
participate in Mocha:

Consensus:

- [Consensus node](/operate/consensus-validators/consensus-node)
- [Validator node](/operate/consensus-validators/validator-node)

Data Availability:

- [Bridge node](/operate/data-availability/bridge-node)
- [Light node](/operate/data-availability/light-node/quickstart)

Select the type of node you would like to run and follow the instructions
on each respective page. Whenever you are asked to select the type of network
you want to connect to in those guides, select `Mocha` to refer
to the correct instructions on this page on how to connect to Mocha.

## Network details

| Detail        | Value                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------- |
| Chain ID      | `mocha-5`                                                                                     |
| Genesis hash  | `82DB3AC5AB8485E4784054BD10457533A64563F055C0D234A3134603A9C85D33`                                 |
| Genesis file  | <a href={`https://github.com/celestiaorg/networks/blob/main/$mocha-5/genesis.json`}>genesis.json</a> |
| Peers file    | <a href={`https://github.com/celestiaorg/networks/blob/main/$mocha-5/peers.txt`}>peers.txt</a>       |
| Validators    | 100 (max)                                                                                                |

## Software version numbers

| Software       | Version                                                                           |
| -------------- | --------------------------------------------------------------------------------- |
| celestia-node  | [v0.34.3-mocha](https://github.com/celestiaorg/celestia-node/releases/tag/v0.34.3-mocha) |
| celestia-app   | [v10.4.0-mocha](https://github.com/celestiaorg/celestia-app/releases/tag/v10.4.0-mocha)   |

## Network status

For real-time network status information, including uptime, incident reports,
and service availability, visit the
[official Celestia Mocha testnet status page](https://status.celestia.dev/status/mocha).

## Network constants

For the current Mocha testnet network constants, see
[mocha.celenium.io/constants](https://mocha.celenium.io/constants).

Some community infrastructure is still migrating from `mocha-4` to
`mocha-5`. The endpoints listed below were verified to serve `mocha-5`
on September 1, 2026. Services still serving `mocha-4` are omitted until
they migrate. Explorers, faucets, indexers, and analytics services may
also still show `mocha-4` data.

## RPC for DA bridge, full, and light nodes

### Production RPC endpoints

These RPC providers are meant to be used in production environments
and for specific use cases that require reliable access to full block
history, such as:

- Running Bridge Nodes that download data from core RPC endpoints
- Applications that need Bridge Node endpoints with guaranteed uptime and SLAs
- Submitting blobs in production settings (free RPC endpoints have no guarantees, even for submitting transactions)

| Provider  | URL                                                                                       |
| --------- | ----------------------------------------------------------------------------------------- |
| Quicknode | [https://www.quicknode.com/chains/celestia](https://www.quicknode.com/chains/celestia) ([docs](https://quicknode.com/docs/celestia)) |

> **Warning:** Do not rely on the free community endpoints listed below for production deployments. Production deployments should rely on [service providers with SLAs](#production-rpc-endpoints) or your own node.

### Public RPC endpoint

For development, testing, and documentation examples, use the public Quicknode
endpoint:

| Interface | Endpoint |
| --------- | -------- |
| HTTP RPC and REST | `https://public-endpoint.celestia-mocha.quiknode.pro` |
| WebSocket | `wss://public-endpoint.celestia-mocha.quiknode.pro/websocket` |
| gRPC over TLS | `public-endpoint.celestia-mocha.quiknode.pro:9090` |
| DA JSON-RPC | `https://public-endpoint.celestia-mocha.quiknode.pro` |

This shared endpoint is pruned and does not provide a production SLA. Do not
use it for historical queries or bridge node sync from genesis.

### Community consensus endpoints

Use these hosts for `--core.ip`. celestia-node connects over gRPC with
`--core.port` (default `9090`). RPC ports are listed for operators who also
need Tendermint RPC from the same provider.

| Provider      | Endpoint for `--core.ip`                                          | RPC port | gRPC port |
| ------------- | ----------------------------------------------------------------- | -------- | --------- |
| P-OPS         | `rpc-mocha.pops.one`                                              | 443      | 9090      |

You can also find the list of official Celestia bootstrappers in the [celestia-node GitHub repository](https://github.com/celestiaorg/celestia-node/blob/a87a17557223d88231b56d323d22ac9da31871db/nodebuilder/p2p/bootstrap.go#L39).

### Community Data availability (DA) RPC endpoints for bridge node sync

These RPC endpoints allow bridge nodes to sync blocks from the Celestia network.
For users, they will need to provide a `–core.ip string`
from a consensus node's URL or IP that populates a default RPC port at 26657
to their respective DA node.

### Community Data availability (DA) gRPC endpoints for state access

These gRPC endpoints for DA nodes provide state access for querying the
chain's state and broadcasting transactions (balances, blobs, etc.) to the
Celestia network. For users, they will need to provide a `–core.ip string`
from a consensus node's URL or IP that populates a default gRPC port at 9090
to their respective DA node.

> **Tip for bridge nodes:** Community RPC endpoints do not guarantee full block downloads. If you are running a bridge node, also run a local [consensus node](/operate/consensus-validators/consensus-node) to download full blocks.

Use one of the `--core.ip` values from the [community consensus endpoints](#community-consensus-endpoints) table above.

## Community RPC endpoints

The RPC endpoint is to allow users to interact with Celestia's nodes by
querying the node's state and broadcasting transactions on the
Celestia network. The default port is 26657.

- `rpc-mocha.pops.one`
- `rpc-1.testnet.celestia.nodes.guru`
- `rpc-2.testnet.celestia.nodes.guru`
- `celestia-testnet-rpc.itrocket.net:443`

For a multi-region view of public consensus RPC endpoints, use
[Cumulo's check_d Endpoint Scan for Mocha](https://cumulo.pro/services/celestia_mocha/rpcscan.php).
It shows endpoint health, block height, historical reliability, and response
latency from probes in the United States, Europe, Canada, and Singapore.

## Community API endpoints

The API endpoint is to allow users to interact with the REST API in Cosmos
SDK which is implemented using gRPC-gateway, which exposes gRPC endpoints
as REST endpoints. This allows for communication with the node using REST
calls, which can be useful if the client does not support gRPC or HTTP2.
The default port is 1317.

- `https://api-mocha.pops.one`
- `https://api-1.testnet.celestia.nodes.guru`
- `https://api-2.testnet.celestia.nodes.guru`
- `https://celestia-testnet-api.itrocket.net`

## Community gRPC endpoints

The gRPC endpoint is to allow users to interact with a Celestia Node using
gRPC, a modern open-source and high-performance RPC framework. The default
port is 9090. In the Cosmos SDK, gRPC is used to define state queries and
broadcast transactions.

- `grpc-mocha.pops.one`
- `grpc-1.testnet.celestia.nodes.guru:10790`
- `grpc-2.testnet.celestia.nodes.guru:10790`
- `celestia-testnet-grpc.itrocket.net:443`

## Community bridge node endpoints

The `mocha-5` DA network is live. Community bridge node endpoints will
be added here as providers make them available.

## Mocha testnet faucet

> **Warning:** Using this faucet does not entitle you to any airdrop or other distribution of mainnet Celestia tokens.

### Discord

You can request from Mocha testnet Faucet on the #mocha-faucet channel on
Celestia's Discord server with the following command:

```text
$request <CELESTIA-ADDRESS>
```

Where `<CELESTIA-ADDRESS>` is a `celestia1******` generated address.

> **Note:** Faucet has a limit of 10 tokens per week per address/Discord ID.

### Web

The web faucet is available at [https://mocha.celenium.io/faucet](https://mocha.celenium.io/faucet).

## Analytics

The following websites provide analytics for Mocha Testnet:

- [https://itrocket.net/services/testnet/celestia/](https://itrocket.net/services/testnet/celestia/) - Monitoring and chain status tools

## Node maps

The following websites provide visual maps of Celestia DA nodes:

- [https://probelab.io/celestia/](https://probelab.io/celestia/) (community contribution)

## Explorers

Most explorers are still indexing `mocha-4` and will switch to `mocha-5`
as they migrate.

There are several explorers you can use for Mocha:

- `https://mintscan.io/celestia-testnet/`
- `https://mocha.celenium.io`
- `https://explorer.nodestake.top/celestia-testnet/`
- `https://stakeflow.io/celestia-testnet`
- `https://testnet.celestia.explorers.guru`
- `https://testnet.itrocket.net/celestia`
- `https://testnet.celestia.valopers.com/`
- `https://explorer.chainroot.io/celestia-testnet-mocha-5`

## Network upgrades

There are a few ways to stay informed about network upgrades on the Mocha testnet:

- Telegram [announcement channel](https://t.me/+smSFIA7XXLU4MjJh)
- Discord [Mocha announcements](https://discord.com/channels/638338779505229824/979037494735691816)

Mocha has activated app version 10. See the
[Mocha-5 upgrade history](/operate/maintenance/network-upgrades#mocha-5) for the
activation height and date, and the [Fibre server guide](/operate/consensus-validators/fibre)
for validator setup and registration.

---
Title: Participate in the Celestia networks
URL: https://docs.celestia.org/operate/networks/overview.md
Source: app/operate/networks/overview/page.mdx
---

# Participate in the Celestia networks

## Mainnet Beta

Celestia's [Mainnet Beta](/operate/networks/mainnet-beta) is the production network
for deploying Mainnet Beta rollups and applications. This marks the
culmination of years of development and community testing. While
the network is stable and continues to receive updates, it remains
experimental and users may experience occasional instability or
reduced performance.

### Compatible software versions for Mainnet Beta

| Software       | Version                                                             |
| -------------- | ------------------------------------------------------------------- |
| celestia-node  | [v0.34.3](https://github.com/celestiaorg/celestia-node/releases/tag/v0.34.3) |
| celestia-app   | [v10.4.0](https://github.com/celestiaorg/celestia-app/releases/tag/v10.4.0)   |

## Testnets

Celestia currently has one public testnet that you can participate in:

### Mocha testnet

[Mocha testnet](/operate/networks/mocha-testnet) is a testnet focused on enabling validators
to test out their infrastructure by running nodes connected to the network. Developers
can also deploy sovereign rollups on Mocha. Breaking network upgrades are coordinated
with the validator community.

### Compatible software versions for Mocha testnet

| Software       | Version                                                                           |
| -------------- | --------------------------------------------------------------------------------- |
| celestia-node  | [v0.34.3-mocha](https://github.com/celestiaorg/celestia-node/releases/tag/v0.34.3-mocha) |
| celestia-app   | [v10.4.0-mocha](https://github.com/celestiaorg/celestia-app/releases/tag/v10.4.0-mocha)   |

## Network upgrades

There are a few ways to stay informed about network upgrades:

- Telegram [announcement channel](https://t.me/+smSFIA7XXLU4MjJh)
- Discord [Mainnet Beta announcements](https://discord.com/channels/638338779505229824/1169237690114388039)
- Discord [Mocha announcements](https://discord.com/channels/638338779505229824/979037494735691816)

See the [network upgrades page](/operate/maintenance/network-upgrades) to learn more
about specific upgrades like the [Ginger network upgrade](/operate/maintenance/network-upgrades#ginger-network-upgrade).