nodebuilder

Documentation

Index

• Constants
• Variables
• func ConstructModule(tp node.Type, network p2p.Network, cfg *Config, store Store) fx.Option
• func DiscoverOpened() (string, error)
• func Init(cfg Config, path string, tp node.Type) error
• func IsInit(path string) bool
• func IsOpened(path string) (bool, error)
• func RemoveConfig(path string) (err error)
• func Reset(path string, tp node.Type) error
• func SaveConfig(path string, cfg *Config) error
• func UpdateConfig(tp node.Type, path string) (err error)
• func WithBootstrappers(peers p2p.Bootstrappers) fx.Option
• func WithMetrics(metricOpts []otlpmetrichttp.Option, nodeType node.Type) fx.Option
• func WithNetwork(net p2p.Network) fx.Option
• func WithPyroscope(endpoint string, nodeType node.Type) fx.Option
• func WithTraces(opts []otlptracehttp.Option, pyroOpts []otelpyroscope.Option) fx.Option
• type Config
  • func DefaultConfig(tp node.Type) *Config
  • func LoadConfig(path string) (*Config, error)
  • func (cfg *Config) Decode(r io.Reader) error
  • func (cfg *Config) Encode(w io.Writer) error
• type ConfigLoader
• type Node
  • func New(tp node.Type, network p2p.Network, store Store, options ...fx.Option) (*Node, error)
  • func NewWithConfig(tp node.Type, network p2p.Network, store Store, cfg *Config, ...) (*Node, error)
  • func TestNode(t *testing.T, tp node.Type, opts ...fx.Option) *Node
  • func TestNodeWithConfig(t *testing.T, tp node.Type, cfg *Config, opts ...fx.Option) *Node
  • func (n *Node) Run(ctx context.Context) error
  • func (n *Node) Start(ctx context.Context) error
  • func (n *Node) Stop(ctx context.Context) error
• type Store
  • func MockStore(t *testing.T, cfg *Config) Store
  • func NewMemStore() Store
  • func OpenStore(path string, ring keyring.Keyring) (Store, error)

Constants

const TestKeyringName = "test_celes"

Variables

var (
	// ErrOpened is thrown on attempt to open already open/in-use Store.
	ErrOpened = errors.New("node: store is in use")
	// ErrNotInited is thrown on attempt to open Store without initialization.
	ErrNotInited = errors.New("node: store is not initialized")
	// ErrNoOpenStore is thrown when no opened Store is found, indicating that no node is running.
	ErrNoOpenStore = errors.New("no opened Node Store found (no node is running)")
)

var DefaultNodeStorePath = func(tp, network string) (string, error) {
	home := os.Getenv("CELESTIA_HOME")

	if home == "" {
		var err error
		home, err = os.UserHomeDir()
		if err != nil {
			return "", err
		}
	}
	if network == p2p.Mainnet.String() {
		return fmt.Sprintf("%s/.celestia-%s", home, strings.ToLower(tp)), nil
	}

	return fmt.Sprintf(
		"%s/.celestia-%s-%s",
		home,
		strings.ToLower(tp),
		strings.ToLower(network),
	), nil
}

DefaultNodeStorePath constructs the default node store path using the given node type and network.

var PackageToAPI = map[string]interface{}{
	"fraud":  &fraud.API{},
	"state":  &state.API{},
	"share":  &share.API{},
	"header": &header.API{},
	"das":    &das.API{},
	"p2p":    &p2p.API{},
	"blob":   &blob.API{},
	"node":   &node.API{},
}

PackageToAPI maps a package to its API struct. Currently only used for method discovery for openrpc spec generation

var PrintKeyringInfo = true

PrintKeyringInfo whether to print keyring information during init.

Functions

func ConstructModule

func ConstructModule(tp node.Type, network p2p.Network, cfg *Config, store Store) fx.Option

func DiscoverOpened

func DiscoverOpened() (string, error)

DiscoverOpened finds a path of an opened Node Store and returns its path. If multiple nodes are running, it only returns the path of the first found node. Network is favored over node type.

Network preference order: Mainnet, Mocha, Arabica, Private, Custom Type preference order: Bridge, Full, Light

func Init

func Init(cfg Config, path string, tp node.Type) error

Init initializes the Node FileSystem Store for the given Node Type 'tp' in the directory under 'path'.

func IsInit

func IsInit(path string) bool

IsInit checks whether FileSystem Store was setup under given 'path'. If any required file/subdirectory does not exist, then false is reported.

func IsOpened

func IsOpened(path string) (bool, error)

IsOpened checks if the Store is opened in a directory by checking its file lock.

func RemoveConfig

func RemoveConfig(path string) (err error)

RemoveConfig removes the Config from the given store path.

func Reset

func Reset(path string, tp node.Type) error

Reset removes all data from the datastore and dagstore directories. It leaves the keystore and config intact.

func SaveConfig

func SaveConfig(path string, cfg *Config) error

SaveConfig saves Config 'cfg' under the given 'path'.

func UpdateConfig

func UpdateConfig(tp node.Type, path string) (err error)

UpdateConfig loads the node's config and applies new values from the default config of the given node type, saving the newly updated config into the node's config path.

func WithBootstrappers

func WithBootstrappers(peers p2p.Bootstrappers) fx.Option

WithBootstrappers sets custom bootstrap peers.

func WithMetrics

func WithMetrics(metricOpts []otlpmetrichttp.Option, nodeType node.Type) fx.Option

WithMetrics enables metrics exporting for the node.

func WithNetwork

func WithNetwork(net p2p.Network) fx.Option

WithNetwork specifies the Network to which the Node should connect to. WARNING: Use this option with caution and never run the Node with different networks over the same persisted Store.

func WithPyroscope

func WithPyroscope(endpoint string, nodeType node.Type) fx.Option

WithPyroscope enables pyroscope profiling for the node.

func WithTraces

func WithTraces(opts []otlptracehttp.Option, pyroOpts []otelpyroscope.Option) fx.Option

Types

type Config

type Config struct {
	Node    node.Config
	Core    core.Config
	State   state.Config
	P2P     p2p.Config
	RPC     rpc.Config
	Gateway gateway.Config
	Share   share.Config
	Header  header.Config
	DASer   das.Config `toml:",omitempty"`
	Pruner  pruner.Config
}

Config is main configuration structure for a Node. It combines configuration units for all Node subsystems.

func DefaultConfig

func DefaultConfig(tp node.Type) *Config

DefaultConfig provides a default Config for a given Node Type 'tp'. NOTE: Currently, configs are identical, but this will change.

func LoadConfig

func LoadConfig(path string) (*Config, error)

LoadConfig loads Config from the given 'path'.

func (*Config) Decode

func (cfg *Config) Decode(r io.Reader) error

Decode decodes a Config from a given reader r.

func (*Config) Encode

func (cfg *Config) Encode(w io.Writer) error

Hint: use 'ast' package. Encode encodes a given Config into w.

type ConfigLoader

type ConfigLoader func() (*Config, error)

ConfigLoader defines a function that loads a config from any source.

type Node

type Node struct {
	fx.In `ignore-unexported:"true"`

	Type          node.Type
	Network       p2p.Network
	Bootstrappers p2p.Bootstrappers
	Config        *Config
	AdminSigner   jwt.Signer

	// rpc components
	RPCServer     *rpc.Server     // not optional
	GatewayServer *gateway.Server `optional:"true"`

	// block store
	EDSStore *eds.Store `optional:"true"`

	// p2p components
	Host         host.Host
	ConnGater    *conngater.BasicConnectionGater
	Routing      routing.PeerRouting
	DataExchange exchange.Interface
	BlockService blockservice.BlockService
	// p2p protocols
	PubSub *pubsub.PubSub
	// services
	ShareServ  share.Module  // not optional
	HeaderServ header.Module // not optional
	StateServ  state.Module  // not optional
	FraudServ  fraud.Module  // not optional
	BlobServ   blob.Module   // not optional
	DASer      das.Module    // not optional
	AdminServ  node.Module   // not optional
	DAMod      da.Module     // not optional
	// contains filtered or unexported fields
}

Node represents the core structure of a Celestia node. It keeps references to all Celestia-specific components and services in one place and provides flexibility to run a Celestia node in different modes. Currently supported modes: * Bridge * Light * Full

func New

func New(tp node.Type, network p2p.Network, store Store, options ...fx.Option) (*Node, error)

New assembles a new Node with the given type 'tp' over Store 'store'.

func NewWithConfig

func NewWithConfig(tp node.Type, network p2p.Network, store Store, cfg *Config, options ...fx.Option) (*Node, error)

NewWithConfig assembles a new Node with the given type 'tp' over Store 'store' and a custom config.

func TestNode

func TestNode(t *testing.T, tp node.Type, opts ...fx.Option) *Node

func TestNodeWithConfig

func TestNodeWithConfig(t *testing.T, tp node.Type, cfg *Config, opts ...fx.Option) *Node

func (*Node) Run

func (n *Node) Run(ctx context.Context) error

Run is a Start which blocks on the given context 'ctx' until it is canceled. If canceled, the Node is still in the running state and should be gracefully stopped via Stop.

func (*Node) Start

func (n *Node) Start(ctx context.Context) error

Start launches the Node and all its components and services.

func (*Node) Stop

func (n *Node) Stop(ctx context.Context) error

Stop shuts down the Node, all its running Modules/Services and returns. Canceling the given context earlier 'ctx' unblocks the Stop and aborts graceful shutdown forcing remaining Modules/Services to close immediately.

type Store

type Store interface {
	// Path reports the FileSystem path of Store.
	Path() string

	// Keystore provides a Keystore to access keys.
	Keystore() (keystore.Keystore, error)

	// Datastore provides a Datastore - a KV store for arbitrary data to be stored on disk.
	Datastore() (datastore.Batching, error)

	// Config loads the stored Node config.
	Config() (*Config, error)

	// PutConfig alters the stored Node config.
	PutConfig(*Config) error

	// Close closes the Store freeing up acquired resources and locks.
	Close() error
}

Store encapsulates storage for the Node. Basically, it is the Store of all Stores. It provides access for the Node data stored in root directory e.g. '~/.celestia'.

func MockStore

func MockStore(t *testing.T, cfg *Config) Store

MockStore provides mock in memory Store for testing purposes.

func NewMemStore

func NewMemStore() Store

NewMemStore creates an in-memory Store for Node. Useful for testing.

func OpenStore

func OpenStore(path string, ring keyring.Keyring) (Store, error)

OpenStore creates new FS Store under the given 'path'. To be opened the Store must be initialized first, otherwise ErrNotInited is thrown. OpenStore takes a file Lock on directory, hence only one Store can be opened at a time under the given 'path', otherwise ErrOpened is thrown.