Celestia Node API

Blob

class celestia.node_api.blob.BlobClient(rpc)

Client for interacting with Celestia’s Blob API.

async get(height, namespace, commitment, *, deserializer=None)

Retrieves the blob by commitment under the given namespace and height.

Parameters:

• height (int) – The block height.

• namespace (Namespace) – The namespace of the blob.

• commitment (Commitment) – The commitment of the blob.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

The retrieved blob, or None if not found.

Return type:

Blob | None

async get_all(height, namespace, *namespaces, deserializer=None)

Returns all blobs under the given namespaces at the given height. If all blobs were found without any errors, the user will receive a list of blobs. If the BlobService couldn’t find any blobs under the requested namespaces, the user will receive an empty list of blobs along with an empty error. If some of the requested namespaces were not found, the user will receive all the found blobs and an empty error. If there were internal errors during some of the requests, the user will receive all found blobs along with a combined error message. All blobs will preserve the order of the namespaces that were requested.

Parameters:

• height (int) – The block height.

• namespace (Namespace) – The primary namespace of the blobs.

• namespaces (Namespace) – Additional namespaces to query for blobs.

• deserializer (Callable | None) – Custom deserializer. Defaults to None.

Returns:

The list of blobs or [] if not found.

Return type:

list[Blob]

async get_commitment_proof(height, namespace, commitment, *, deserializer=None)

Generates a commitment proof for a share commitment.

Parameters:

• height (int) – The block height.

• namespace (Namespace) – The namespace of the commitment.

• commitment (Commitment) – The commitment to generate proof for.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

The commitment proof, or None if not found.

Return type:

CommitmentProof | None

async get_proof(height, namespace, commitment, *, deserializer=None)

Retrieves proofs in the given namespaces at the given height by commitment.

Parameters:

• height (int) – The block height.

• namespace (Namespace) – The namespace of the proof.

• commitment (Commitment) – The commitment to generate the proof for.

• deserializer (Callable | None) – Custom deserializer. Defaults to None.

Returns:

A list of proofs or [] if not found.

Return type:

list[Proof]

async included(height, namespace, proof, commitment)

Checks whether a blob’s given commitment(Merkle subtree root) is included at given height and under the namespace.

Parameters:

• height (int) – The block height.

• namespace (Namespace) – The namespace of the blob.

• proof (Proof) – The proof to check.

• commitment (Commitment) – The commitment to check inclusion for.

Returns:

True if included, False otherwise.

Return type:

bool

async submit(blob, *blobs, deserializer=None, **options)

Sends Blobs and reports the height in which they were included. Allows sending multiple Blobs atomically synchronously. Uses default wallet registered on the Node.

Parameters:

• blob (Blob) – The main blob to submit.

• blobs (Blob) – Additional blobs to submit.

• deserializer (Callable | None) – Custom deserializer. Defaults to None.

• options (TxConfig) – Additional configuration options.

Returns:

The result of the submission, including the height.

Return type:

SubmitBlobResult

async subscribe(namespace, *, deserializer=None)

Subscribe to published blobs from the given namespace as they are included.

Parameters:

• namespace (Namespace) – The namespace to subscribe to.

• deserializer (Callable | None) – Custom deserializer. Defaults to None.

Yields:

SubscriptionBlobResult – A result with the blob information.

Das

class celestia.node_api.das.DasClient(rpc)

Client for interacting with Celestia’s Das API.

async sampling_stats(*, deserializer=None)

Returns the current statistics over the DA sampling process.

Parameters:

deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

The current sampling statistics.

Return type:

SamplingStats

async wait_catch_up()

Blocks until DASer finishes catching up to the network head.

Returns:

None

Header

class celestia.node_api.header.HeaderClient(rpc)

Client for interacting with Celestia’s Header API.

async get_by_hash(header_hash, *, deserializer=None)

Returns the header of the given hash from the node’s header store.

Parameters:

• header_hash (str) – The hash of the header to retrieve.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

The retrieved header if found, otherwise None.

Return type:

ExtendedHeader | None

async get_by_height(height, *, deserializer=None)

Returns the ExtendedHeader at the given height if it is currently available.

Parameters:

• height (int) – The height of the header.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

The retrieved header.

Return type:

ExtendedHeader

async get_range_by_height(range_from, range_to, *, deserializer=None)

Returns the given range (from:to) of ExtendedHeaders from the node’s header store and verifies that the returned headers are adjacent to each other.

Parameters:

• range_from (ExtendedHeader) – The starting header.

• range_to (int) – The height of the last header in the range.

• deserializer (Callable | None) – Custom deserializer. Defaults to None.

Returns:

A list of retrieved headers.

Return type:

list[ExtendedHeader]

async local_head(*, deserializer=None)

Returns the ExtendedHeader of the chain head.

Parameters:

deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

The latest known header of the local node.

Return type:

ExtendedHeader

async network_head(*, deserializer=None)

Provides the Syncer’s view of the current network head.

Parameters:

deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

The latest known header of the network.

Return type:

ExtendedHeader

async subscribe(*, deserializer=None)

Subscribes to recent ExtendedHeaders from the network.

Parameters:

deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Yields:

ExtendedHeader | None – The latest headers as they become available.

async sync_state(*, deserializer=None)

Returns the current state of the header Syncer.

Parameters:

deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

The current synchronization state.

Return type:

State

async sync_wait()

Blocks until the header Syncer is synced to network head.

Returns:

None

async wait_for_height(height, *, deserializer=None)

Blocks until the header at the given height has been processed by the store or context deadline is exceeded.

Parameters:

• height (int) – The height of the header to wait for.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

The retrieved header once available.

Return type:

ExtendedHeader

P2P

class celestia.node_api.p2p.P2PClient(rpc)

Client for interacting with Celestia’s P2P API.

async bandwidth_for_peer(peer_id, *, deserializer=None)

Returns a Stats struct with bandwidth metrics associated with the given peer.ID. The metrics returned include all traffic sent / received for the peer, regardless of protocol.

Parameters:

• peer_id (str) – The ID of the peer.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

Bandwidth statistics for the given peer.

Return type:

BandwidthStats

async bandwidth_for_protocol(protocol_id, *, deserializer=None)

Returns a Stats struct with bandwidth metrics associated with the given protocol.ID.

Parameters:

• protocol_id (str) – The protocol ID.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

Bandwidth statistics for the given protocol.

Return type:

BandwidthStats

async bandwidth_stats(*, deserializer=None)

Returns a Stats struct with bandwidth metrics for all data sent/received by the local peer, regardless of protocol or remote peer IDs.

Parameters:

deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

Overall bandwidth statistics.

Return type:

BandwidthStats

async block_peer(peer_id)

Adds a peer to the set of blocked peers and closes any existing connection to that peer.

Parameters:

peer_id (str) – The ID of the peer to block.

async close_peer(peer_id)

Closes the connection to a given peer.

Parameters:

peer_id (str) – The ID of the peer to disconnect from.

async connect(address)

Ensures there is a connection between this host and the peer with given peer.

Parameters:

address (AddrInfo) – Address information of the peer.

async connectedness(peer_id)

Returns a state signaling connection capabilities.

Parameters:

peer_id (str) – The ID of the peer.

Returns:

Connection status with the peer.

Return type:

Connectedness

async info(*, deserializer=None)

Returns address information about the host.

Parameters:

deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

Address information of the local peer.

Return type:

AddrInfo

async is_protected(peer_id, tag)

Returns whether the given peer is protected.

Parameters:

• peer_id (str) – The ID of the peer.

• tag (str) – Protection tag.

Returns:

True if the peer is protected, False otherwise.

Return type:

bool

async list_blocked_peers()

Returns a list of blocked peers.

Returns:

A list of blocked peer IDs.

Return type:

list[str]

async nat_status()

Returns the current NAT status.

Returns:

NAT reachability status.

Return type:

Reachability

async peer_info(peer_id, *, deserializer=None)

Returns a small slice of information Peerstore has on the given peer.

Parameters:

• peer_id (str) – The ID of the peer.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

Address information of the peer.

Return type:

AddrInfo

async peers()

Returns connected peers.

Returns:

List of connected peer IDs.

Return type:

list[str]

async protect(peer_id, tag)

Adds a peer to the list of peers who have a bidirectional peering agreement that they are protected from being trimmed, dropped or negatively scored.

Parameters:

• peer_id (str) – The ID of the peer.

• tag (str) – Protection tag.

async pub_sub_peers(topic)

Returns the peer IDs of the peers joined on the given topic.

Parameters:

topic (str) – The PubSub topic to query.

Returns:

A list of peer IDs that are joined on the specified topic.

Return type:

list[str]

async pub_sub_topics()

Reports current PubSubTopics the node participates in.

Returns:

A list of topic names if available, otherwise None.

Return type:

list[str] | None

async resource_state(*, deserializer=None)

Returns the state of the resource manager.

Parameters:

deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

Resource manager state.

Return type:

ResourceManagerStat

async unblock_peer(peer_id)

Removes a peer from the set of blocked peers.

Parameters:

peer_id (str) – The ID of the peer to unblock.

async unprotect(peer_id, tag)

Removes a peer from the list of peers who have a bidirectional peering agreement that they are protected from being trimmed, dropped or negatively scored, returning a bool representing whether the given peer is protected or not.

Parameters:

• peer_id (str) – The ID of the peer.

• tag (str) – Protection tag.

Returns:

True if the peer remains protected, False otherwise.

Return type:

bool

Share

class celestia.node_api.share.ShareClient(rpc)

Client for interacting with Celestia’s Share API.

async get_available(height)

Subjectively validates if Shares committed to the given ExtendedHeader are available on the Network.

Parameters:

height (int) – The block height.

Returns:

True if shares are available, False otherwise.

Return type:

bool

async get_eds(height, *, deserializer=None)

Gets the full EDS identified by the given extended header.

Parameters:

• height (int) – The block height.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

The retrieved EDS object.

Return type:

ExtendedDataSquare

async get_namespace_data(height, namespace, *, deserializer=None)

Gets all shares from an EDS within the given namespace. Shares are returned in a row-by-row order if the namespace spans multiple rows.

Parameters:

• height (int) – The block height.

• namespace (Namespace) – The namespace identifier.

• deserializer (Callable | None) – Custom deserializer. Defaults to None.

Returns:

A list of NamespaceData objects or [] if not found.

Return type:

list[NamespaceData]

async get_range(height, start, end, *, deserializer=None)

Gets a list of shares and their corresponding proof.

Parameters:

• height (int) – The block height.

• start (int) – The starting index.

• end (int) – The ending index.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

The retrieved range result containing shares and proof.

Return type:

GetRangeResult

async get_samples(header, indices)

Gets sample for given indices.

Parameters:

• header (ExtendedHeader) – The extended header.

• indices (list[SampleCoords]) – A list of sample coordinates.

Returns:

A list of retrieved samples or [] if not found.

Return type:

list[str]

async get_share(height, row, col)

Gets a Share by coordinates in EDS.

Parameters:

• height (int) – The block height.

• row (int) – The row index.

• col (int) – The column index.

Returns:

The retrieved share.

Return type:

str

State

class celestia.node_api.state.StateClient(rpc)

Client for interacting with Celestia’s State API.

async account_address()

Retrieves the address of the node’s account/signer

Returns:

The address of the node’s account.

Return type:

str

async balance(*, deserializer=None)

Retrieves the Celestia coin balance for the node’s account/signer and verifies it against the corresponding block’s AppHash.

Parameters:

deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

The balance of the node’s account.

Return type:

Balance

async balance_for_address(address, *, deserializer=None)

Retrieves the Celestia coin balance for the given address and verifies the returned balance against the corresponding block’s AppHash. NOTE: the balance returned is the balance reported by the block right before the node’s current head (head-1). This is due to the fact that for block N, the block’s AppHash is the result of applying the previous block’s transaction list.

Parameters:

• address (str) – The address to query balance for.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

The balance of the given address.

Return type:

Balance

async begin_redelegate(src_val_addr, dst_val_addr, amount, *, deserializer=None, **config)

Sends a user’s delegated tokens to a new validator for redelegation.

Parameters:

• src_val_addr (str) – Source validator address.

• dst_val_addr (str) – Destination validator address.

• amount (int) – Amount to redelegate.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

• **config (TxConfig) – Additional transaction configuration.

Returns:

Transaction response.

Return type:

TXResponse

async cancel_unbonding_delegation(val_addr, amount, height, *, deserializer=None, **config)

Cancels a user’s pending undelegation from a validator.

Parameters:

• val_addr (str) – Validator address.

• amount (int) – Amount to cancel unbonding.

• height (int) – Block height at which unbonding was initiated.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

• **config (TxConfig) – Additional transaction configuration.

Returns:

Transaction response.

Return type:

TXResponse

async delegate(del_addr, amount, *, deserializer=None, **config)

Sends a user’s liquid tokens to a validator for delegation.

Parameters:

• del_addr (str) – Delegator address.

• amount (int) – Amount to delegate.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

• **config (TxConfig) – Additional transaction configuration.

Returns:

Transaction response.

Return type:

TXResponse

async grant_fee(grantee, amount, *, deserializer=None, **config)

Grants a fee allowance to the specified grantee.

Parameters:

• grantee (str) – Address of the grantee.

• amount (int) – Amount of fee allowance.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

• **config (TxConfig) – Additional transaction configurations.

Returns:

Response of the grant fee transaction.

Return type:

TXResponse

async query_delegation(val_addr, *, deserializer=None)

Retrieves the delegation information between a delegator and a validator.

Parameters:

• val_addr (str) – Validator address.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

Delegation information.

Return type:

QueryDelegationResponse

async query_redelegations(src_val_addr, dst_val_addr, *, deserializer=None)

Retrieves the status of the redelegations between a delegator and a validator.

Parameters:

• src_val_addr (str) – Source validator address.

• dst_val_addr (str) – Destination validator address.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

Redelegation details.

Return type:

QueryRedelegationResponse

async query_unbonding(val_addr, *, deserializer=None)

Retrieves the unbonding status between a delegator and a validator.

Parameters:

• val_addr (str) – Validator address.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

Returns:

Unbonding status.

Return type:

QueryUnbondingDelegationResponse

async revoke_grant_fee(grantee, *, deserializer=None, **config)

Revokes a previously granted fee allowance.

Parameters:

• grantee (str) – Address of the grantee whose allowance is being revoked.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

• **config (TxConfig) – Additional transaction configurations.

Returns:

Response of the revoke grant fee transaction.

Return type:

TXResponse

async submit_pay_for_blob(blob, *blobs, **config)

Builds, signs and submits a PayForBlob transaction.

Parameters:

• blob (Blob) – The first blob to be included in the transaction.

• *blobs (Blob) – Additional blobs.

• **config (TxConfig) – Additional transaction configurations.

Returns:

Transaction ID of the submitted PayForBlob transaction.

Return type:

int

async transfer(to, amount, *, deserializer=None, **config)

Sends the given amount of coins from default wallet of the node to the given account address.

Parameters:

• to (str) – Recipient address.

• amount (int) – Amount to transfer.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

• **config (TxConfig) – Additional transaction configuration.

Returns:

Transaction response.

Return type:

TXResponse

async undelegate(del_addr, amount, *, deserializer=None, **config)

Undelegates a user’s delegated tokens, unbonding them from the current validator.

Parameters:

• del_addr (str) – Delegator address.

• amount (int) – Amount to undelegate.

• deserializer (Callable | None) – Custom deserializer. Defaults to deserializer().

• **config (TxConfig) – Additional transaction configurations.

Returns:

Response of the undelegation transaction.

Return type:

TXResponse

Fraud

class celestia.node_api.fraud.FraudClient(rpc)

Client for interacting with Celestia’s Fraud API.

async get(proof_type)

Fetches fraud proofs from the disk by its type.

Parameters:

proof_type (str) – The type of fraud proof to retrieve.

Returns:

A list of fraud proofs.

Return type:

list[dict[str, str]]

async subscribe(proof_type)

Allows to subscribe on a Proof pub sub topic by its type.

Parameters:

proof_type (str) – The type of fraud proof to subscribe to.

Yields:

dict[str, str] – A dictionary containing fraud proof data.