Celestia

Skill based on celestia-node, generated from sources/celestia. Doc path: sources/celestia/README.md, sources/celestia/docs/adr/, and package doc.go (header, share, das, state).

Celestia-node is the Go implementation of Celestia’s data availability (DA) node types: bridge, full, and light. The DA network wraps celestia-core by consuming or producing ExtendedHeaders and making block data available via share sampling (DAS). Use this skill to operate nodes, query headers/shares/state, submit PayForBlob and other transactions, and reason about P2P discovery and fraud proofs.

Core References

Features

Public API and discovery

Best Practices

Generation Info

• Source: sources/celestia
• Git SHA: 02d826a7801a4d5f22ef03c11522880d0e4cb636
• Generated: 2026-02-24

State Verification

When the node returns balances (or other state) via the State module, results should be verified against the chain. Celestia-node does this by requesting Merkle proofs from celestia-app and verifying them against the latest head’s AppHash.

Why verify

• The StateAccessor may talk to a core endpoint or a P2P state provider. Verification ensures the returned state is consistent with the header chain the node trusts (from the header store).
• The head’s AppHash commits to the state after applying the previous block’s transactions, so verification uses the block height head.Height - 1 for the state query.

Flow

1. Get the latest head from the header store (header.Getter Head / LocalHead). 2. Issue an ABCI request query for the desired key (e.g. bank balance) at height head.Height - 1, with Prove: true. 3. Receive response with value and proof ops (e.g. crypto.ProofOps). 4. Convert proof ops to a Merkle proof (e.g. using ibc-go commitment types or equivalent). 5. Verify membership: proof.VerifyMembership(specs, root, path, value) where root is the head’s AppHash and path is the store key + key.

Example (balance)

• Prefixed key: bank.CreateAccountBalancesPrefix(addr) + bondDenom.
• Path: store/<bank.StoreKey>/key, Data: prefixed key, Height: head.Height - 1, Prove: true.
• After verification, the balance in the response can be trusted relative to the head.

Availability during sync

The Syncer exposes NetworkHead() so state queries can use the current network head for verification even when the node has not finished syncing. This allows the State API to remain available and still return verified state.

Key points

• Always verify state responses against the header store’s head (or network head) AppHash when building trusted clients.
• Use height head.Height - 1 for the state query because AppHash commits to the state after the previous block.
• The public State module (Balance, BalanceForAddress) implements this verification; custom or direct core clients should replicate it if they need the same guarantee.

<!-- Source references:

• sources/celestia/docs/adr/adr-004-state-interaction.md

-->

Headers

The header package handles generating, requesting, syncing, and storing ExtendedHeaders. An ExtendedHeader extends a celestia-core block header with the DataAvailabilityHeader (DAH), ValidatorSet, and Commit so light and full nodes can reconstruct or verify block data via the DAH.

Components

1. core.Listener (bridge only): Listens to celestia-core for blocks, extends them, builds ExtendedHeader, publishes to HeaderSub. 2. p2p.Subscriber: Subscribes to new ExtendedHeaders from the DA network (HeaderSub). 3. p2p.Exchange / core.Exchange: Fetches ExtendedHeaders from DA peers (default for full/light) or from core (bridge only). 4. Syncer: Syncs past and recent ExtendedHeaders from the DA network or a core connection (bridge). 5. Store: Persists ExtendedHeaders for use by DASer and other services.

Bridge flow

1. core.Listener receives blocks from core, validates and extends, generates ExtendedHeader, stores extended block shares, publishes to HeaderSub. 2. Syncer (subscribed to HeaderSub) receives new ExtendedHeaders and stores via Store. Past headers are requested from core via core.Exchange when needed.

Full / Light flow

1. Syncer receives new ExtendedHeaders from HeaderSub. 2. If there is a gap to network head, Syncer requests headers in batches (local head → network head) and appends to Store. 3. DASer and other services read from Store.

Header module API (RPC)

Use these for querying and waiting on headers:

• LocalHead – node’s local chain tip (header store).
• GetByHash / GetByHeight – fetch a single header from the store.
• WaitForHeight – block until the header at the given height is processed or context deadline.
• GetRangeByHeight(from, to) – contiguous range of ExtendedHeaders from the store.
• Subscribe – long-lived subscription channel for newly validated ExtendedHeaders.
• SyncState / SyncWait – syncer status and blocking until synced to network head.
• NetworkHead – syncer’s view of current network head.

Key points

• ExtendedHeader is the unit of work for DAS: it carries the DAH used for share sampling.
• Bridge is the only type that generates ExtendedHeaders; full and light only consume and sync them.
• All node types expose the same Header module; bridge can use core.Exchange for historical sync, full/light use p2p.Exchange.

<!-- Source references:

• sources/celestia/header/doc.go
• sources/celestia/docs/adr/adr-009-public-api.md

-->

Node Types

Celestia-node implements three data availability (DA) node types that form the DA network around celestia-core consensus. All share the same public API surface; implementations differ by resource constraints (e.g. Full vs Light availability).

Bridge

• Role: Relays blocks from the celestia-core consensus network to the DA network.
• Behavior: Connects to a celestia-core node via RPC, listens for blocks, runs ValidateBasic(), extends block data, builds the Data Availability Header (DAH), creates an ExtendedHeader, and publishes it to the HeaderSub gossip topic.
• Sampling: Does not perform DAS; DAS module is stubbed. Exposes the same API as a full node otherwise.
• Use when: You need to feed the DA layer from a trusted core connection (validator or full core node).

Full

• Role: Fully reconstructs and stores blocks by sampling the DA network for shares; serves shares to others.
• Behavior: Subscribes to ExtendedHeaders (e.g. via HeaderSub), runs FullAvailability: samples enough shares to fully repair the block’s data square and stores it.
• Use when: You need full block data and to serve shares to light/full peers.

Light

• Role: Verifies availability of block data by sampling the DA network (no full reconstruction).
• Behavior: Subscribes to ExtendedHeaders, runs LightAvailability: randomly samples a fixed number of shares (e.g. 16) per block—enough to verify availability with high probability when many light nodes sample.
• Use when: You need minimal resource usage and only need to verify data availability.

Quick reference

Usage

Run and init use the same CLI for all types; <node_type> is bridge, full, or light:

celestia <node_type> init
celestia <node_type> start

<!-- Source references:

• https://github.com/celestiaorg/celestia-node (README.md)
• sources/celestia/docs/adr/adr-003-march2022-testnet.md

-->

Shares and Data Availability Sampling

The share package provides retrieval and sampling of block data shares. The das package runs data availability sampling (DAS) over ExtendedHeaders to verify that block data is available on the network.

Share retrieval

• GetSharesByNamespace(ctx, root, nID) – Returns all shares in the block (identified by the data root / DAH) for the given namespace, in row-by-row order. Primary method for fetching application data by namespace.
• GetShare(ctx, root, row, col) – Single share at row/col in the data square identified by root.
• GetEDS(ctx, root) – Full extended data square (EDS) for the given root (full nodes have this after repair).

Availability is defined in the share package: Light samples 16 shares per block to verify availability; Full samples until the block can be fully reconstructed and repaired.

DAS module (RPC)

• Stats() – Returns current DASer sampling stats (e.g. sampled height range, progress).

DAS does not expose per-block control; the node runs DAS automatically on synced headers.

Shares module (RPC)

• GetShare / GetEDS / GetSharesByNamespace – As above, with root from a header’s DAH.
• SharesAvailable(ctx, root) – Subjective check that shares committed to the root are available on the network.
• ProbabilityOfAvailability() – Probability that the data square is available given samples collected (light nodes).

DASer internals (parallelization)

The DASer uses a Coordinator, Workers, Subscriber, and CheckpointStore:

• Coordinator decides which headers to sample next; workers perform sampling in parallel (concurrency limit ~16).
• Subscriber feeds new network head headers; recent heads are prioritized.
• CheckpointStore persists state so DAS resumes after restart. Checkpoints are written periodically and on exit.

Sampling is network-bound; parallel workers improve throughput. Config (e.g. sampling range, concurrency) may be exposed per node type in the future.

Key points

• Use GetSharesByNamespace for application-level blob retrieval by namespace ID.
• Light nodes only verify availability (SharesAvailable, ProbabilityOfAvailability); full nodes can return GetEDS and full shares after repair.
• DAS runs automatically; use Stats() to monitor progress.

<!-- Source references:

• sources/celestia/share/doc.go
• sources/celestia/das/doc.go
• sources/celestia/docs/adr/adr-009-public-api.md
• sources/celestia/docs/adr/adr-012-daser-parallelization.md

-->

State and Transactions

The state package defines how celestia-node accesses chain state and submits transactions. The public API is the StateModule (and embedded StakingModule); implementations use a StateAccessor (Core, P2P, or future local).

StateModule (RPC)

• AccountAddress – Node’s account/signer address.
• Balance – Celestia balance for the node’s account, verified against the head’s AppHash.
• BalanceForAddress(ctx, addr) – Balance for a given address, also verified.
• SubmitTx(ctx, tx) – Submit a raw transaction; blocks until included in a block.
• SubmitPayForBlob(ctx, nID, data, config) – Build, sign, and submit a PayForBlob transaction for the given namespace and data.
• Transfer(ctx, to, amount, config) – Send coins from the node’s wallet to an address.

StakingModule (embedded in StateModule)

• Delegate / BeginRedelegate / Undelegate / CancelUnbondingDelegation – Staking operations with optional TxConfig.
• QueryDelegation / QueryRedelegations / QueryUnbonding – Query delegation state for a delegator/validator.

All state-modifying methods accept an optional state.TxConfig for gas/fee and other options.

StateAccessor implementations

• CoreAccess: gRPC connection to a celestia-core node. Used when a core endpoint is configured at init.
• P2PAccess: Discovers state-providing nodes (e.g. bridge) via P2P and sends state requests over libp2p streams. Bridge runs a StateProvider that proxies to its core connection.
• Local (future): Full nodes may serve state locally from applied blocks.

Availability during sync

StateService is available while the node is syncing. The Syncer exposes NetworkHead() so state can be queried against the current network head even if the node has not finished syncing; balance verification uses the head’s AppHash (see best-practices).

Key points

• Use SubmitPayForBlob for posting blobs to a namespace; use GetSharesByNamespace (Shares module) to read them back.
• Balances are verified against the latest head’s AppHash via Merkle proofs when using the public State API.
• Bridge nodes act as state providers for P2P state access; light/full nodes typically use Core or P2P accessor.

<!-- Source references:

• sources/celestia/state/doc.go
• sources/celestia/docs/adr/adr-009-public-api.md
• sources/celestia/docs/adr/adr-004-state-interaction.md

-->

Fraud Proofs

The Fraud service handles fraud proof types (currently Bad Encoding, BEFP). Full nodes generate BEFPs when block reconstruction fails verification; they broadcast the proof and all nodes that receive and validate it halt dependent services (DAS, Syncer, SubmitTx). Light and bridge nodes subscribe to BEFP and halt on valid proof.

Bad Encoding Fraud Proof (BEFP)

• When: A full node gets ErrByzantineData from rsmt2d during block repair (recovered data does not match row/column roots in the DAH).
• Content: Height, header hash, row/column index, axis (row/col), and shares with Merkle proofs for the verified shares in that row/column.
• Flow: Full node creates the proof, broadcasts via Fraud Broadcaster (pubsub); all nodes subscribed to the BEFP topic receive it, verify it, and if valid store it and halt DAS, Syncer, and SubmitTx.

Verification (light nodes)

On receiving a BEFP:

1. Verify Merkle proofs for the included shares. 2. Reconstruct the row or column from BadEncodingProof.Shares, compute its Merkle root (same as rsmt2d), and compare with the root in the ExtendedHeader’s DAH. If roots match, the BEFP is invalid.

Storage and startup

• Valid BEFPs are stored in the datastore (e.g. path fraud/badEncodingProof, keyed by block hash).
• On startup, the node checks for any stored BEFP; if present, it does not start (node remains halted).

Fraud sync

For nodes that start after a BEFP was already broadcast:

• Light nodes (and similar) wait for new connections to full/bridge peers (share discovery).
• They send a small number of requests (e.g. 5) to new peers for a fraud proof.
• If a proof is received, it is validated and propagated to local subscriptions so services halt. Invalid proofs result in the remote peer being blacklisted.
• Full and bridge nodes register a stream handler to respond to fraud proof requests.

Bridge behavior

Bridge nodes subscribe to the BEFP topic like light nodes. On receiving a valid BEFP they shut down dependent services, including broadcasting new ExtendedHeaders.

Fraud module API

• Subscribe(proofType) – Subscribe to a proof type (registers pubsub validator).
• List() – Currently subscribed proof types.
• Get(proofType) – Return stored proofs of that type.

<!-- Source references:

• sources/celestia/docs/adr/adr-006-fraud-service.md
• sources/celestia/docs/adr/adr-003-march2022-testnet.md

-->

P2P Discovery

Discovery lets light and full nodes find and connect to full nodes on the DA network. Full nodes advertise themselves; light and bridge nodes discover and connect to them. Connections to discovered full nodes are protected from trimming via tagging.

Namespace and limits

• Discovery uses the full topic/namespace: nodes advertise or discover peers that provide full-node capability (share serving).
• peersLimit (e.g. 3): Maximum number of discovered full-node peers to keep in the set.
• peerWeight (e.g. 1000): Tag weight for discovered full nodes so the ConnManager does not trim them.

Full nodes

1. On startup, advertise self on the DHT under the full namespace so others can find this node. 2. Discover other full nodes and connect to them; on successful connection, tag the peer and add to the limited set. 3. If connection fails, drop the discovered peer.

Bridge nodes

• Behave like full nodes for discovery: advertise at full and actively discover/connect to full nodes.
• Bridges do not sample (they get blocks from core), but connecting to full nodes improves topology so full nodes have more peers with shares for EDS repair.

Light nodes

1. Discover full nodes via DHT at full namespace using the discoverer interface. 2. On discovering a peer, attempt connection; on success, tag peer and add to the set; otherwise drop. 3. Rely on these connections for share sampling (DAS) and state (if using P2P state access).

Implementation note

Discovery combines advertise and discover services and stores active peers in a limitedSet (thread-safe, max size). The libp2p Host is used to connect to discovered peers; Tag Peer ensures ConnManager does not garbage-collect these connections.

<!-- Source references:

• sources/celestia/docs/adr/adr-008-p2p-discovery.md

-->

Public API

Celestia-node exposes a module-centric public API. All DA node types (bridge, full, light) implement the same set of modules; differences are in implementation (e.g. Full vs Light availability). The API is designed to be ergonomic, embeddable (library-style Node construction), and language-agnostic over RPC.

Modules overview

NodeModule

• Info – Administrative node information.
• LogLevelSet(name, level) – Set log level for a component.
• AuthVerify(token) – Permissions for a token.
• AuthNew(perms) – Create a new signed token with given permissions.

P2P module (excerpt)

• Info / Peers / PeerInfo – Host and peer addressing.
• Connect / ClosePeer / Connectedness / NATStatus – Connection management.
• BlockPeer / UnblockPeer / ListBlockedPeers – Blocklist.
• MutualAdd / MutualRm / IsMutual – Bidirectional protected peers (tagged).
• BandwidthStats / BandwidthForPeer / BandwidthForProtocol – Bandwidth metrics.
• ResourceState – Resource manager state.
• PubSubPeers(topic) – Peers on a given topic.

Fraud module

• Subscribe(proofType) – Subscribe to a fraud proof type (e.g. bad encoding).
• List() – Proof types currently subscribed.
• Get(proofType) – Stored fraud proofs of that type.

Metrics module

• List – Registered meters.
• Enable / Disable – Toggle a meter.
• ExportTo(endpoint) – Export metrics to an endpoint.

Design goals

• Unified: Same API across node types; implementation differences (e.g. availability) are internal.
• Embeddable: Construct a Node with options; no framework mandate.
• Language-agnostic: Easy to mirror module interfaces in other languages via RPC clients.

Public RPC docs: <https://node-rpc-docs.celestia.org/>.

<!-- Source references:

• sources/celestia/docs/adr/adr-009-public-api.md

-->