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.
To view a video tutorial for setting up a Celestia light node, click here.
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:
- Introduction
- Hardware requirements
- Setting up dependencies
- Install and run Celestia Node
- RPC CLI guide
- Additional resources
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:
- APT
- YUM
sudo apt update && sudo apt upgrade -y
sudo yum update
These are essential packages that are necessary to execute many tasks like downloading files, compiling, and monitoring the node:
- APT
- YUM
- Mac (Apple)
- Mac (Intel)
sudo apt install curl tar wget clang pkg-config libssl-dev jq build-essential git make ncdu -y
sudo yum install curl tar wget clang pkg-config libssl-dev jq build-essential git make ncdu -y
🍺 Installing Homebrew
Homebrew is a package manager for macOS and Linux and will allow you to install your dependencies.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Be sure to run the commands in the output that are similar to:
==> Next steps:
- Run these three commands in your terminal to add Homebrew to your PATH:
echo '# Set PATH, MANPATH, etc., for Homebrew.' >> /Users/joshstein/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/joshstein/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
🗄 Install wget and jq
Using Homebrew, in your terminal:
brew install wget && brew install jq
wget is an internet file retriever and jq is a lightweight command-line JSON processor.
🍺 Installing Homebrew
Homebrew is a package manager for macOS and Linux and will allow you to install your dependencies.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Be sure to run the commands in the output that are similar to:
==> Next steps:
- Run these three commands in your terminal to add Homebrew to your PATH:
echo '# Set PATH, MANPATH, etc., for Homebrew.' >> /Users/joshstein/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/joshstein/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
🗄 Install wget and jq
Using Homebrew, in your terminal:
brew install wget && brew install jq
wget is an internet file retriever and jq is a lightweight command-line JSON processor.
Install Golang
celestia-app
and celestia-node
are written in Golang
so we must install Golang to build and run them.
- Blockspace Race
- Mocha
- Arabica 🏗️
- Ubuntu (AMD)
- Ubuntu (ARM)
- Mac (Apple)
- Mac (Intel)
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"
ver="1.21.1"
cd $HOME
wget "https://golang.org/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"
ver="1.21.1"
cd $HOME
wget "https://golang.org/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"
ver="1.21.1"
cd $HOME
wget "https://golang.org/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"
Now we need to add the /usr/local/go/bin
directory to $PATH
:
- bash
- zsh
echo "export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin" >> $HOME/.bash_profile
source $HOME/.bash_profile
echo "export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin" >> $HOME/.zshrc
source $HOME/.zshrc
To check if Go was installed correctly run:
go version
The output should be the version installed:
- Ubuntu (AMD)
- Ubuntu (ARM)
- Mac (Apple)
- Mac (Intel)
go version go1.21.1 linux/amd64
go version go1.21.1 linux/arm64
go version go1.21.1 darwin/arm64
go version go1.21.1 darwin/amd64
- Ubuntu (AMD)
- Ubuntu (ARM)
- Mac (Apple)
- Mac (Intel)
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"
ver="1.21.1"
cd $HOME
wget "https://golang.org/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"
ver="1.21.1"
cd $HOME
wget "https://golang.org/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"
ver="1.21.1"
cd $HOME
wget "https://golang.org/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"
Now we need to add the /usr/local/go/bin
directory to $PATH
:
- bash
- zsh
echo "export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin" >> $HOME/.bash_profile
source $HOME/.bash_profile
echo "export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin" >> $HOME/.zshrc
source $HOME/.zshrc
To check if Go was installed correctly run:
go version
The output should be the version installed:
- Ubuntu (AMD)
- Ubuntu (ARM)
- Mac (Apple)
- Mac (Intel)
go version go1.21.1 linux/amd64
go version go1.21.1 linux/arm64
go version go1.21.1 darwin/arm64
go version go1.21.1 darwin/amd64
- Ubuntu (AMD)
- Ubuntu (ARM)
- Mac (Apple)
- Mac (Intel)
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"
ver="1.21.1"
cd $HOME
wget "https://golang.org/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"
ver="1.21.1"
cd $HOME
wget "https://golang.org/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"
ver="1.21.1"
cd $HOME
wget "https://golang.org/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"
Now we need to add the /usr/local/go/bin
directory to $PATH
:
- bash
- zsh
echo "export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin" >> $HOME/.bash_profile
source $HOME/.bash_profile
echo "export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin" >> $HOME/.zshrc
source $HOME/.zshrc
To check if Go was installed correctly run:
go version
The output should be the version installed:
- Ubuntu (AMD)
- Ubuntu (ARM)
- Mac (Apple)
- Mac (Intel)
go version go1.21.1 linux/amd64
go version go1.21.1 linux/arm64
go version go1.21.1 darwin/arm64
go version go1.21.1 darwin/amd64
Celestia Node
Install Celestia Node
- Blockspace Race
- Mocha
- Arabica 🏗️
- Ubuntu (AMD)
- Ubuntu (ARM)
- Mac (Apple)
- Mac (Intel)
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
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: arm64/linux
Golang version: go1.21.1
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 go-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: arm64/darwin
Golang version: go1.21.1
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 go-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/darwin
Golang version: go1.21.1
- Ubuntu (AMD)
- Ubuntu (ARM)
- Mac (Apple)
- Mac (Intel)
Installing celestia-node
for Mocha 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.11.0-rc13
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.11.0-rc13
Commit: 8ca777e1a3f04b7d0494e3bae8a1c1bcf68c5d8c
Build Date: Thu Dec 15 10:19:22 PM UTC 2022
System version: amd64/linux
Golang version: go1.21.1
Installing celestia-node
for Mocha 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.11.0-rc13
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.11.0-rc13
Commit: 8ca777e1a3f04b7d0494e3bae8a1c1bcf68c5d8c
Build Date: Thu Dec 15 10:19:22 PM UTC 2022
System version: arm64/linux
Golang version: go1.21.1
Installing celestia-node
for Mocha 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.11.0-rc13
make build
make go-install
make cel-key
Verify that the binary is working and check the version with the celestia
version
command:
$ celestia version
Semantic version: v0.11.0-rc13
Commit: 8ca777e1a3f04b7d0494e3bae8a1c1bcf68c5d8c
Build Date: Thu Dec 15 10:19:22 PM UTC 2022
System version: arm64/darwin
Golang version: go1.21.1
Installing celestia-node
for Mocha 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.11.0-rc13
make build
make go-install
make cel-key
Verify that the binary is working and check the version with the celestia
version
command:
$ celestia version
Semantic version: v0.11.0-rc13
Commit: 8ca777e1a3f04b7d0494e3bae8a1c1bcf68c5d8c
Build Date: Thu Dec 15 10:19:22 PM UTC 2022
System version: amd64/darwin
Golang version: go1.21.1
- Ubuntu (AMD)
- Ubuntu (ARM)
- Mac (Apple)
- Mac (Intel)
Installing celestia-node
for Arabica Devnet 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.11.0-rc13
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.11.0-rc13
Commit: 8ca777e1a3f04b7d0494e3bae8a1c1bcf68c5d8c
Build Date: Thu Dec 15 10:19:22 PM UTC 2022
System version: amd64/linux
Golang version: go1.21.1
Installing celestia-node
for Arabica Devnet 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.11.0-rc13
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.11.0-rc13
Commit: 8ca777e1a3f04b7d0494e3bae8a1c1bcf68c5d8c
Build Date: Thu Dec 15 10:19:22 PM UTC 2022
System version: arm64/linux
Golang version: go1.21.1
Installing celestia-node
for Arabica Devnet 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.11.0-rc13
make build
make go-install
make cel-key
Verify that the binary is working and check the version with the celestia
version
command:
$ celestia version
Semantic version: v0.11.0-rc13
Commit: 8ca777e1a3f04b7d0494e3bae8a1c1bcf68c5d8c
Build Date: Thu Dec 15 10:19:22 PM UTC 2022
System version: arm64/darwin
Golang version: go1.21.1
Installing celestia-node
for Arabica Devnet 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.11.0-rc13
make build
make go-install
make cel-key
Verify that the binary is working and check the version with the celestia
version
command:
$ celestia version
Semantic version: v0.11.0-rc13
Commit: 8ca777e1a3f04b7d0494e3bae8a1c1bcf68c5d8c
Build Date: Thu Dec 15 10:19:22 PM UTC 2022
System version: amd64/darwin
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.
- Blockspace Race
- Mocha
- Arabica 🏗️
celestia light init --p2p.network blockspacerace
celestia light init
celestia light init --p2p.network arabica
Connect to a public core endpoint
- Blockspace Race
- Mocha
- Arabica 🏗️
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
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.
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 mocha
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.
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 arabica
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:
- Blockspace Race
- Mocha
- Arabica 🏗️
celestia light start --core.ip <ip-address> --p2p.network blockspacerace
Please refer to the ports section for information on which ports are required to be open on your machine.
celestia light start --core.ip rpc-mocha.pops.one --p2p.network mocha
Please refer to the ports section for information on which ports are required to be open on your machine.
celestia light start --core.ip consensus-full.celestia-arabica-10.com --p2p.network arabica
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:
- Blockspace Race
- Mocha
- Arabica 🏗️
celestia light start --core.ip <ip-address> --keyring.accname <key_name> <port> --p2p.network blockspacerace
Please refer to the ports section for information on which ports are required to be open on your machine.
celestia light start --core.ip <ip-address> --keyring.accname <key_name> --p2p.network mocha
Please refer to the ports section for information on which ports are required to be open on your machine.
celestia light start --core.ip <ip-address> --keyring.accname <key_name> --p2p.network arabica
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]
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.
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
anddata
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
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
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.