Skip to main content

Celestia Node RPC CLI tutorial

In this tutorial, we will cover how to use the Celestia Node RPC API to submit and retrieve data (blobs) from the data availability layer by their namespace.

tip

To view a video tutorial for setting up a Celestia light node, click here.

caution

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

Table of contents​

This tutorial is broken up into the following sections:

tip

If you already have a running and funded node, you can skip to the RPC CLI guide section.

Introduction​

Blobs​

Data is posted to Celestia's DA layer by using MsgPayForBlobs transactions to the core network. Read more about MsgPayForBlobs here.

Namespaces​

Celestia partitions the block data into multiple namespaces, one for every application. This allows applications to only download their data, and not the data of other applications. Read more about Namespaced Merkle Trees (NMTs) here.

Hardware requirements​

The following minimum hardware requirements are recommended for running a light node:

  • Memory: 2 GB RAM
  • CPU: Single Core
  • Disk: 25 GB SSD Storage
  • Bandwidth: 56 Kbps for Download/56 Kbps for Upload

Setting up dependencies​

First, make sure to update and upgrade the OS:

sudo apt update && sudo apt upgrade -y

These are essential packages that are necessary to execute many tasks like downloading files, compiling, and monitoring the node:

sudo apt install curl tar wget clang pkg-config libssl-dev jq build-essential git make ncdu -y

Install Golang​

celestia-app and celestia-node are written in Golang so we must install Golang to build and run them.

ver="1.21.1"
cd $HOME
wget "https://golang.org/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"

Now we need to add the /usr/local/go/bin directory to $PATH:

echo "export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin" >> $HOME/.bash_profile
source $HOME/.bash_profile

To check if Go was installed correctly run:

go version

The output should be the version installed:

go version go1.21.1 linux/amd64

Celestia Node​

Install Celestia Node​

Installing celestia-node for the Blockspace Race testnet means installing a specific version to be compatible with the network.

Install the celestia-node binary by running the following commands:

cd $HOME
rm -rf celestia-node
git clone https://github.com/celestiaorg/celestia-node.git
cd celestia-node/
git checkout tags/v0.10.4
make build
make install
make cel-key

Verify that the binary is working and check the version with the celestia version command:

$ celestia version
Semantic version: v0.10.4
Commit: 03ff94a7d779caf1225f3dccb53a68e8f1646dc6
Build Date: Thu Dec 15 10:19:22 PM UTC 2022
System version: amd64/linux
Golang version: go1.21.1

Instantiate a Celestia light node​

Now, let's instantiate a Celestia Light node:

Note: RPC Endpoints are exposed in all celestia-node types such as Light, Bridge and Full Nodes.

celestia light init --p2p.network blockspacerace

Connect to a public core endpoint​

Let's now run the Celestia Light node with a GRPC connection to an example public core endpoint.

Note: You are also encouraged to find a community-run API endpoint and there are several in the Discord. This one is used for demonstration purposes. You can find a list of RPC endpoints here.

celestia light start --core.ip <ip-address> --p2p.network blockspacerace
tip

The --core.ip gRPC port defaults to 9090, so if you do not specify it in the command line, it will default to that port. You can add the port after the IP address or use the --core.grpc.port flag to specify another port if you prefer.

Please refer to the ports section for information on which ports are required to be open on your machine.

For example, your command along with an RPC endpoint might look like this:

celestia light start --core.ip <ip-address> --p2p.network blockspacerace
tip

Please refer to the ports section for information on which ports are required to be open on your machine.

Keys and wallets​

You can create your key for your node by running the following command:

./cel-key add <key_name> --keyring-backend test --node.type light --p2p.network <network>

You can start your light node with the key created above by running the following command:

celestia light start --core.ip <ip-address> --keyring.accname <key_name> <port> --p2p.network blockspacerace
tip

Please refer to the ports section for information on which ports are required to be open on your machine.

Once you start the Light Node, a wallet key will be generated for you. You will need to fund that address with Mocha Testnet or Arabica Devnet tokens to pay for PayForBlob transactions or PayForBlob transactions, respectively.

You can find the address by running the following command in the celestia-node directory:

./cel-key list --node.type light --keyring-backend test --p2p.network <network>

If you would like to fund your wallet with testnet tokens, head over to either the #mocha-faucet or #arabica-faucet channels on the Celestia Discord.

You can request funds to your wallet address using the following command in Discord:

$request <Wallet-Address>

Where <Wallet-Address> is the celestia1****** address generated when you created the wallet.

With your wallet funded, you can move on to the next step.

RPC CLI guide​

This section of the tutorial will teach you how to interact with a Celestia node's RPC (Remote Procedure Call) API.

First, you will need to install and run celestia-node if you have not already. Open up another terminal window in order to begin querying the API.

The Celestia Node CLI (Command Line Interface) has a rpc subcommand that allows you to interact with the node's RPC API via your terminal.

The format for the rpc subcommand is as follows:

celestia rpc [module] [method] [...args]
tip

The blob module is the only module that uses kebab-case for its methods. The other modules use camelCase.

Setup​

Auth token 🔐​

In order to interact with the API using the rpc subcommand, you will need to set your authentication token.

The --auth TOKEN flag sets the authentication token, otherwise it will read from the environment's CELESTIA_NODE_AUTH_TOKEN variable. If a token is not found, authentication will not be set. And if authentication is not set, the request will fail.

To set your authentication token, you can use the following command. Be sure to replace <node-type> with the type of node and <network> with the network that you are running your node on:

export CELESTIA_NODE_AUTH_TOKEN=$(celestia <node-type> auth admin --p2p.network <network>)

Here's an example of how to set your auth token on a light node on Arabica:

export CELESTIA_NODE_AUTH_TOKEN=$(celestia light auth admin --p2p.network arabica)
Auth token on custom or private network​

This section is for users who are using a CELESTIA_CUSTOM or private network.

tip

If you are using a private and custom network, you will need to set the location of the node store in your auth command:

export CELESTIA_NODE_AUTH_TOKEN=$(celestia light auth admin --p2p.network private --node.store $HOME/.celestia-light-private)

The above is an example from the following custom network set up with:

CELESTIA_CUSTOM=private celestia light init

or

celestia light init --p2p.network private

As an example, this is what a completely custom network would look like:

# Initialize node store
CELESTIA_CUSTOM=robusta-22 celestia light init

# Set auth token
export CELESTIA_NODE_AUTH_TOKEN=$(celestia light auth admin --p2p.network private --node.store $HOME/.celestia-light-robusta-22)

Host URL​

The --host URL flag sets the host address, the default is localhost:26658 over HTTP.

Completions​

If you would like to turn on completions for the Celestia Node CLI rpc subcommand, you can use the following command and follow the instructions in the CLI:

# pick your shell type from the array
celestia completion [bash | fish | powershell | zsh]

If you'd like to see the help menu for your shell, you can then run:

# pick your shell type from the array
celestia completion [bash | fish | powershell | zsh] --help

Submitting data​

In this example, we will be submitting a PayForBlob transaction using our light node.

Some things to consider:

  • PFB is a PayForBlob Message.
  • The endpoint also takes in namespace_id and data values.
  • Namespace ID should be 10 bytes, prefixed by 0x
  • Data should be in hex-encoded bytes of the raw message

We use the following namespace_id of 0x42690c204d39600fddd3 and the data value of 0xf1f20ca8007e910a3bf8b2e61da0f26bca07ef78717a6ea54165f5.

You can generate your own namespace_id and data values using this useful Golang Playground we created here.

Here is an example of the format of the PayForBlob transaction:

celestia rpc blob submit [namespace in hex] [data in hex]

We run the following to submit a blob to the network in hexadecimal format:

celestia rpc blob submit 0x42690c204d39600fddd3 0xf1f20ca8007e910a3bf8b2e61da0f26bca07ef78717a6ea54165f5

We get the following output:

{
  "result": {
    "uint64": 219832,
    "commitment": "t7sRPeQVT3jEMlDnhDVU6jxB/FNhhyl6b6wl3+0ENZ0="
  }
}

We can also use a string of text as the data value, which will be converted to base64. Here is an example of the format:

celestia rpc blob submit [namespace in hex] '[data]'

And an example to submit "gm" as the plain-text data:

celestia rpc blob submit 0x42690c204d39600fddd3 'gm'

Output:

{
  "result": {
    "uint64": 219832,
    "commitment": "IXg+08HV5RsPF3Lle8PH+B2TUGsGUsBiseflxh6wB5E="
  }
}

If you notice from the above output, it returns a result of 272667 which we will use for the next command. The result corresponds to the height of the block in which the transaction was included.

submit arguments​

Using the rpc subcommand, you can submit a blob to the network using the submit method.

The arguments for submit are parsed specially, to improve UX.

submit can be done in a few ways:

  • The namespace ID can be encoded as either hex or base64
  • The blob can be hex (0x...), base64 ("..."), or a normal string which will be encoded to base64 ('Hello There!')

Retrieving data​

After submitting your PFB transaction, upon success, the node will return the block height for which the PFB transaction was included. You can then use that block height and the namespace ID with which you submitted your PFB transaction to get your message shares (data) returned to you. In this example, the block height we got was 219832 which we will use for the following command. Read more about shares in the Celestia Specs.

Here is what an example of the format of the get command looks like:

celestia rpc blob get [block height] [namespace in hex] [committment from output above]

Here is an example command to retrieve the data from above, on arabica-10:

celestia rpc blob get 219832 0x42690c204d39600fddd3 IXg+08HV5RsPF3Lle8PH+B2TUGsGUsBiseflxh6wB5E=

Will generate the following output:

{
  "result": {
    "namespace": "AAAAAAAAAAAAAAAAAAAAAAAAAEJpDCBNOWAP3dM=",
    "data": "gm",
    "share_version": 0,
    "commitment": "IXg+08HV5RsPF3Lle8PH+B2TUGsGUsBiseflxh6wB5E="
  }
}

The output here is base64 decoded to plain-text.

To see the base64 response, use the --base64 flag set to TRUE (--base64=TRUE):

celestia rpc blob get 219832 0x42690c204d39600fddd3 IXg+08HV5RsPF3Lle8PH+B2TUGsGUsBiseflxh6wB5E= --base64=TRUE

The response will look similar to this:

{
  "result": {
    "namespace": "AAAAAAAAAAAAAAAAAAAAAAAAAEJpDCBNOWAP3dM=",
    "data": "Z20=",
    "share_version": 0,
    "commitment": "IXg+08HV5RsPF3Lle8PH+B2TUGsGUsBiseflxh6wB5E="
  }
}

To get all blobs in the namespace at the block height, use get-all instead of get:

celestia rpc blob get-all 219832 0x42690c204d39600fddd3

This will return the following:

{
  "result": [
    {
      "namespace": "AAAAAAAAAAAAAAAAAAAAAAAAAEJpDCBNOWAP3dM=",
      "data": "gm",
      "share_version": 0,
      "commitment": "IXg+08HV5RsPF3Lle8PH+B2TUGsGUsBiseflxh6wB5E="
    }
  ]
}

To display the response in base64, use:

celestia rpc blob get-all 219832 0x42690c204d39600fddd3 --base64=TRUE

Which will return:

{
  "result": [
    {
      "namespace": "AAAAAAAAAAAAAAAAAAAAAAAAAEJpDCBNOWAP3dM=",
      "data": "gm",
      "share_version": 0,
      "commitment": "IXg+08HV5RsPF3Lle8PH+B2TUGsGUsBiseflxh6wB5E="
    }
  ]
}

Setting the gas fee and limit​

tip

These flags are only currently live on celestia-node versions v0.11.0-rc13 and higher. They are also optional to use with blob.submit.

To set the gas fee and limit, you can use the --fee and --gas.limit flags respectively when submitting data using the RPC CLI.

Learn more about gas fees and limits here.

To set the fee of 10000 utia, use the --fee 10000 flag:

celestia rpc blob submit 0x42690c204d39600fddd3 'gm' --fee 10000

To set a gas limit of 100000, use the --gas.limit 100000 flag:

celestia rpc blob submit 0x42690c204d39600fddd3 'gm' --gas.limit 100000

To set a fee of 10000 utia and gas limit of 100000, use the --fee 10000 --gas.limit 100000 flags:

celestia rpc blob submit 0x42690c204d39600fddd3 'gm' --fee 10000 --gas.limit 100000

You will receive the height and committment of the block in which the transaction was included for these three examples:

{
  "result": {
    "height": 62562,
    "commitment": "IXg+08HV5RsPF3Lle8PH+B2TUGsGUsBiseflxh6wB5E="
  }
}

Examples​

Check your balance​

Let's query our node for the balance of its default account (which is the account associated with the CELESTIA_NODE_AUTH_TOKEN key we generated above):

celestia rpc state Balance

The response will look similar to:

{
  "jsonrpc": "2.0",
  "result": {
    "denom": "utia",
    "amount": "172118057"
  },
  "id": 1
}

Check the balance of another address​

Here is an example of the format of the BalanceForAddress command:

celestia rpc state BalanceForAddress [address]

Let's query our node for the balance of another address:

celestia rpc state BalanceForAddress celestia10rtd9lhel2cuh6c659l25yncl6atcyt37umard

The response will be the balance of the address you queried:

{
  "jsonrpc": "2.0",
  "result": {
    "denom": "utia",
    "amount": "1000000"
  },
  "id": 1
}

Get your node ID​

This is an RPC call in order to get your node's peerId information:

celestia rpc p2p Info

The node ID is in the ID value from the response:

{
  "jsonrpc": "2.0",
  "result": {
    "ID": "12D3KooWFFhCaAqY56oEqY3pLZUdLsv4RYAfVWKATZRepUPdosLp",
    "Addrs": [
      "/ip4/10.0.0.171/tcp/2121",
      "/ip4/10.0.0.171/udp/2121/quic-v1",
      "/ip4/71.200.65.106/tcp/25630",
      "/ip4/71.200.65.106/udp/25630/quic-v1",
      "/ip6/::1/tcp/2121",
      "/ip6/::1/udp/2121/quic-v1"
    ]
  },
  "id": 1
}

Get your account address​

This is an RPC call in order to get your node's account address:

celestia rpc state AccountAddress

Response:

{
  "jsonrpc": "2.0",
  "result": "celestia1znk24rh52pgcd9z5x2x42jztjh6raaaphuvrt3",
  "id": 1
}

Get block header by height​

Here is an example of the format of the GetByHeight command:

celestia rpc header GetByHeight [height]

Now, let's get the block header information.

Here we will get the header from Block 1:

celestia rpc header GetByHeight 1

It will output something like this:

{
  "jsonrpc": "2.0",
  "result": {
    "header": {
      "version": {
        "block": "11",
        "app": "1"
      },
      "chain_id": "arabica-10",
      "height": "1",
      "time": "2023-06-27T13:02:39.741743Z",
      "last_block_id": {
        "hash": "",
        "parts": {
          "total": 0,
          "hash": ""
        }
      },
      "last_commit_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
      "data_hash": "3D96B7D238E7E0456F6AF8E7CDF0A67BD6CF9C2089ECB559C659DCAA1F880353",
      "validators_hash": "6363C68770C200FD794445668F9B18F5B1DD1125180D6E8D5AB004F7DD7A0F48",
      "next_validators_hash": "6363C68770C200FD794445668F9B18F5B1DD1125180D6E8D5AB004F7DD7A0F48",
      "consensus_hash": "048091BC7DDC283F77BFBF91D73C44DA58C3DF8A9CBC867405D8B7F3DAADA22F",
      "app_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
      "last_results_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
      "evidence_hash": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
      "proposer_address": "91E04695CF9CF531BC0891E7B1D602B3E8022C86"
    },
    "validator_set": {
      "validators": [
        {
          "address": "91E04695CF9CF531BC0891E7B1D602B3E8022C86",
          "pub_key": {
            "type": "tendermint/PubKeyEd25519",
            "value": "9aNBAxno1B4X5LR2qY5qWqwrMNOzejkctXwzq9BExsg="
          },
          "voting_power": "500000000",
          "proposer_priority": "0"
        }
      ],
      "proposer": {
        "address": "91E04695CF9CF531BC0891E7B1D602B3E8022C86",
        "pub_key": {
          "type": "tendermint/PubKeyEd25519",
          "value": "9aNBAxno1B4X5LR2qY5qWqwrMNOzejkctXwzq9BExsg="
        },
        "voting_power": "500000000",
        "proposer_priority": "0"
      }
    },
    "commit": {
      "height": 1,
      "round": 0,
      "block_id": {
        "hash": "7A5FABB19713D732D967B1DA84FA0DF5E87A7B62302D783F78743E216C1A3550",
        "parts": {
          "total": 1,
          "hash": "D85C907CE660878A8203AC74BAA147CCC1F87114B45B568B72AD207B62AFE45E"
        }
      },
      "signatures": [
        {
          "block_id_flag": 2,
          "validator_address": "91E04695CF9CF531BC0891E7B1D602B3E8022C86",
          "timestamp": "2023-06-30T08:40:19.299137127Z",
          "signature": "qmaEzrnbtgEXCRYc8pCvGRbS+uMuknIBoRAE4qyE7oSgWCRwBVYS/oPReXQLg9ER1oEY1De4MkWvMjlFnQOOCg=="
        }
      ]
    },
    "dah": {
      "row_roots": [
        "//////////////////////////////////////7//////////////////////////////////////huZWOTTDmD36N1F75A9BshxNlRasCnNpQiWqIhdVHcU",
        "/////////////////////////////////////////////////////////////////////////////5iieeroHBMfF+sER3JpvROIeEJZjbY+TRE0ntADQLL3"
      ],
      "column_roots": [
        "//////////////////////////////////////7//////////////////////////////////////huZWOTTDmD36N1F75A9BshxNlRasCnNpQiWqIhdVHcU",
        "/////////////////////////////////////////////////////////////////////////////5iieeroHBMfF+sER3JpvROIeEJZjbY+TRE0ntADQLL3"
      ]
    }
  },
  "id": 1
}

More examples​

Query node information:​

celestia rpc node Info

Get data availability sampler stats:​

celestia rpc das SamplingStats

Transfer balance of utia to another account​

First, set your address as a variable:

export ADDRESS=celestia1c425ckmve2489atttx022qpc02gxspa29wmh0d

Then, transfer the amount of tokens that you would like, while setting the recipient's address, gas fee, and gasLimit. This is what the format will look like:

celestia rpc state Transfer $ADDRESS [amount in utia] [gas fee in utia] [gas fee in utia]

Here is an example, sending 0.1 TIA, with a gas fee of 0.008 TIA, and a gas limit of 0.08 TIA:

celestia rpc state Transfer $ADDRESS 100000 8000 80000

If you'd just like to return the transaction hash, you can use jq:

celestia rpc state Transfer $ADDRESS 100000 8000 80000 | jq .result.txhash

Additional resources​

Post an SVG as a PFB​

If you'd like to create your own SVG, post it to Celestia, and retrieve it, you can check out the Base64 SVG Tutorial.

Golang guide​

If you're interested in interacting with the node's API in Go (client.go), you can use the da-rpc-client-tutorial repo.

Troubleshooting​

tip

If you encounter an error like:

"rpc error: code = NotFound desc = account celestia1krkle0n547u0znz3unnln8paft2dq4z3rznv86 not found"

It is possible that the account you are trying to submit a PayForBlob from doesn't have testnet tokens yet. Ensure the testnet faucet has funded your account with tokens and then try again.