README
¶
Celestia Client
A Go client library for interacting with the Celestia network, allowing applications to read data from and submit data to Celestia nodes.
Overview
This client package provides a simplified interface for interacting with Celestia nodes, handling both read operations (via Bridge nodes) and transaction submission (via Core/Consensus nodes).
Features
- Read Operations: Query headers, retrieve blobs, access share data
- Submit Operations: Submit blobs to the Celestia network
- State Management: Check balances, execute transactions
- Keyring Integration: Manage keys for transaction signing
- Flexible Client Modes:
- Read-only mode (Bridge node connection only)
- Full client mode (Bridge + Core node connections)
Installation
go get github.com/celestiaorg/celestia-node/api/client
Usage
Initializing a Client
// Create a keyring
kr, err := client.KeyringWithNewKey(client.KeyringConfig{
KeyName: "my_key",
BackendName: keyring.BackendTest,
}, "./keys")
// Configure the client
cfg := client.Config{
ReadConfig: client.ReadConfig{
BridgeDAAddr: "http://localhost:26658",
DAAuthToken: "your_auth_token",
EnableDATLS: false,
},
SubmitConfig: client.SubmitConfig{
DefaultKeyName: "my_key",
Network: "mocha-4",
CoreGRPCConfig: client.CoreGRPCConfig{
Addr: "celestia-consensus.example.com:9090",
TLSEnabled: true,
AuthToken: "your_core_auth_token",
},
},
}
// Create a full client
celestiaClient, err := client.New(context.Background(), cfg, kr)
Creating a Read-Only Client
readCfg := client.ReadConfig{
BridgeDAAddr: "http://localhost:26658",
DAAuthToken: "your_auth_token",
EnableDATLS: false,
}
readClient, err := client.NewReadClient(context.Background(), readCfg)
Submitting a Blob
namespace := libshare.MustNewV0Namespace([]byte("example"))
blob, err := blob.NewBlob(libshare.ShareVersionZero, namespace, []byte("data"), nil)
height, err := celestiaClient.Blob.Submit(ctx, []*blob.Blob{blob}, nil)
Retrieving a Blob
retrievedBlob, err := celestiaClient.Blob.Get(ctx, height, namespace, blob.Commitment)
data := retrievedBlob.Data()
Checking Balance
balance, err := celestiaClient.State.Balance(ctx)
Configuration
ReadConfig
BridgeDAAddr: Address of the Bridge nodeDAAuthToken: Authentication token for the Bridge nodeEnableDATLS: Enable TLS for Bridge node connection
SubmitConfig
DefaultKeyName: Default key to use for transactionsNetwork: Network name (e.g., "mocha-4", "private")CoreGRPCConfig: Configuration for Core node connection
CoreGRPCConfig
Addr: Address of the Core gRPC serverTLSEnabled: Whether to use TLS for the connectionAuthToken: Authentication token for Core gRPC
Security
- When using authentication tokens, TLS is strongly recommended
- The client will warn if auth tokens are used without TLS
Example
See example.go for a complete example of creating a client, submitting a blob, and retrieving it.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrReadOnlyMode = errors.New("submit is disabled in read only client")
Functions ¶
func KeyringWithNewKey ¶
func KeyringWithNewKey(cfg KeyringConfig, path string) (keyring.Keyring, error)
KeyringWithNewKey is a helper function for easy keyring initialization. It initializes a keyring with the given config and path. It creates a new key if no key is found in the keyring store.
Types ¶
type Client ¶
type Client struct {
Blob blobapi.Module
Header headerapi.Module
State stateapi.Module
Fraud fraudapi.Module
Blobstream blobstreamapi.Module
// contains filtered or unexported fields
}
Client is a simplified Celestia client to submit blobs and interact with DA RPC.
func New ¶
New initializes the Celestia client. It connects to the Celestia consensus nodes and Bridge nodes. Any changes to the keyring are not visible to the client. The client needs to be reinitialized to pick up new keys.
func NewReadClient ¶
func NewReadClient(ctx context.Context, cfg ReadConfig) (*Client, error)
type Config ¶
type Config struct {
ReadConfig ReadConfig
SubmitConfig SubmitConfig
}
Config holds configuration for the Client.
type CoreGRPCConfig ¶
type CoreGRPCConfig struct {
// Addr is the address of the core gRPC server.
Addr string
// TLSEnabled specifies whether the connection is secure or not.
TLSEnabled bool
// AuthToken is the authentication token to be used for gRPC authentication.
// If left empty, the client will not include the authentication token in its requests.
// Note: AuthToken is insecure without TLS
AuthToken string
}
CoreGRPCConfig is the configuration for the core gRPC client.
func (*CoreGRPCConfig) Validate ¶
func (cfg *CoreGRPCConfig) Validate() error
Validate performs basic validation of the config.
type KeyringConfig ¶
KeyringConfig contains configuration parameters for constructing the node's keyring signer.
type ReadConfig ¶
type ReadConfig struct {
// BridgeDAAddr is the address of the bridge node
BridgeDAAddr string
// DAAuthToken sets the value for Authorization http header
DAAuthToken string
// HTTPHeader contains custom headers that will be sent with each request
HTTPHeader http.Header
// EnableDATLS enables TLS for bridge node
EnableDATLS bool
}
Bridge node json-rpc connection config
func (ReadConfig) Validate ¶
func (cfg ReadConfig) Validate() error
type SubmitConfig ¶
type SubmitConfig struct {
DefaultKeyName string
Network p2p.Network
CoreGRPCConfig CoreGRPCConfig
}
func (SubmitConfig) Validate ¶
func (cfg SubmitConfig) Validate() error
Source Files
Directories