README ¶
Gossamer cmd
Package
This package encapsulates the entry point to Gossamer - it uses the popular
cli
package from urfave
to expose a command-line
interface (CLI). The Gossamer CLI accepts several subcommands, each of which is associated with an "action"; these
subcommands and their corresponding actions are defined in main.go
. When the Gossamer CLI is executed
without a subcommand, the gossamerAction
is invoked.
Actions & Subcommands
What follows is a list of the Gossamer subcommands, as well as an overview of some of the flags/parameters they accept.
The flags/parameters that the Gossamer CLI supports are defined in flags.go
. For an exhaustive reference
of the Gossamer CLI capabilities, follow the installation instructions and execute
./bin/gossamer --help
.
Default Command
This is the default Gossamer execution method, which invokes the gossamerAction
function defined in
main.go
- it will launch a Gossamer blockchain client. The details of how Gossamer orchestrates a
blockchain client are described below in the Client Components section.
--basepath
- the path to the directory where Gossamer will store its data--chain
- specifies the chain configuration that the Gossamer host node should load--key
- specifies a test keyring account to use (e.g.--key=alice
)--log
- supports levelscrit
(silent),error
,warn
,info
,debug
, andtrce
(detailed), default isinfo
--name
- node name, as it will appear in, e.g., telemetry
Init Subcommand
This subcommand accepts a genesis configuration file and uses it to initialise the Gossamer node and its state. The
init
subcommand invokes the initAction
function defined in main.go
.
--genesis
- path to the "compiled" genesis configuration file that should be used to initialise the Gossamer node and its state
Account Subcommand
The account
subcommand provides the user with capabilities related to generating and using ed25519
, secp256k1
, and
sr25519
account keys, and managing the keys present in the
Gossamer keystore. The accountAction
function is defined in account.go; it is an interface
to the capabilities defined in the lib/crypto
and lib/keystore
packages.
This subcommand provides capabilities that are similar to
Parity's Subkey utility.
--generate
- creates a new key pair; specify--ed25519
,--secp256k1
, or--sr25519
(default)--list
- lists the keys in the Gossamer keystore--password
- allows the user to provide a password to either encrypt a generated key or unlock the Gossamer keystore
Import Runtime Subcommand
This subcommand takes a Wasm runtime binary and uses it to generate a
genesis configuration file; it does not require any flags, but
expects the path to a Wasm file to be provided as a command-line parameter (example:
./bin/gossamer import-runtime runtime.wasm > genesis.json
). The import-runtime
subcommand invokes the
importRuntimeAction
function defined in main.go
.
Build Spec Subcommand
This subcommand allows the user to "compile" a human-readable Gossamer genesis configuration file into a format that the
Gossamer node can consume. If the --genesis
parameter is not provided, the generated genesis configuration will
represent the Gossamer default configuration. The build-spec
subcommand invokes the buildSpecAction
function defined
in main.go
.
--genesis
- path to the human-readable configuration file that should be compiled into a format that Gossamer can consume--raw
- when this flag is present, the output will be a raw genesis spec described as a JSON document
Import State Subcommand
The import-state
subcommand allows a user to seed Gossamer storage with key-value pairs in the form
of a JSON file. The input for this subcommand can be retrieved from
the state_getPairs
RPC endpoint.
The importStateAction
function is defined in main.go
.
--first-slot
- the first BABE slot, which can be found by checking the BABE pre-runtime digest for a chain's first block after its genesis block (e.g. Polkadot on Polkascan)--header
- path to a JSON file that describes the block header corresponding to the given state--state
- path to a JSON file that contains the key-value pairs with which to seed Gossamer storage
Export Subcommand
The export
subcommand transforms a genesis configuration and Gossamer state into a TOML configuration file. This
subcommand invokes the exportAction
function defined in export.go
.
--config
- path to a TOML configuration file (e.g. those defined in thechain
directory)--basepath
- path to the Gossamer data directory that defines the state to export
Client Components
In its default method of execution, Gossamer orchestrates a number of modular services that run
concurrently as goroutines and work together to implement the protocols of
a blockchain network. Alongside these services, Gossamer manages a keystore, a runtime, and
monitoring utilities, all of which are described in greater detail below. The entry point to the Gossamer
blockchain client capabilities is the gossamerAction
function that is defined in main.go, which in turn
invokes the NewNode
function in dot/node.go. NewNode
calls into functions that are defined in
dot/services.go and starts the services that power a Gossamer node.
Services & Capabilities
What follows is a list that describes the services and capabilities that inform a Gossamer blockchain client:
State
This service is a wrapper around an instance of chaindb
, a key-value database
that is built on top of BadgerDB from Dgraph. The state
service provides storage capabilities for the other Gossamer services - each service is assigned a prefix that is added
to its storage keys. The state service is defined in dot/state/service.go.
Network
The network service, which is defined in dot/network/service.go, is built on top of
the Go implementation of the libp2p
protocol. This
service manages a libp2p
"host", a peer-to-peer networking term for a network participant that is providing both
client and server capabilities to a peer-to-peer network. Gossamer's network service manages the discovery of other
hosts as well as the connections with these hosts that allow Gossamer to communicate with its network peers.
Digest Handler
The digest handler (dot/digest/digest.go) manages the verification of the digests that are present in block headers.
Consensus
The BABE and GRANDPA services work together to provide Gossamer with its hybrid consensus capabilities. The term "hybrid consensus" refers to the fact that block production is decoupled from block finalisation. Block production is handled by the BABE service, which is defined in lib/babe/babe.go; block finalisation is handled by the GRANDPA service, which is defined in lib/grandpa/grandpa.go.
Sync
This service is concerned with keeping Gossamer in sync with a blockchain - it implements a "bootstrap" mode, to download and verify blocks that are part of an existing chain's history, and a "tip-syncing" mode that manages the multiple candidate forks that may exist at the head of a live chain. The sync service makes use of a block verification utility that implements BABE logic and is used by Gossamer to verify blocks that were produced by other other nodes in the network. The sync service is defined in dot/sync/syncer.go.
RPC
This service, which is defined in dot/rpc/service.go, exposes a JSON-RPC interface that is used by client applications like Polkadot JS Apps UI. The RPC interface is used to interact with Gossamer to perform administrative tasks such as key management, as well as for interacting with the runtime by querying storage and submitting transactions, and inspecting the chain's history.
System
The system service is defined in dot/system/service.go and exposes metadata about the Gossamer system, such as the names and versions of the protocols that it implements.
Core
As its name implies, the core service (dot/core/service.go) encapsulates a range of capabilities that are central to the functioning of a Gossamer node. In general, the core service is a type of dispatcher that coordinates interactions between services, e.g. writing blocks to the database, reloading the runtime when its definition is updated, etc.
Keystore
The Gossamer keystore (lib/keystore) is used for managing the public/private cryptographic key
pairs that are used for participating in a blockchain network. Public keys are used to identify network participants;
network participants use their private keys to sign messages in order to authorise privileged actions. In addition to
informing the Gossamer blockchain client capabilities, the Gossamer keystore is accessible by way of the account
subcommand. The Gossamer keystore manages a number of key types, some of which are listed below:
babe
- this key is used for signing messages related to the BABE block production algorithmgran
- the GRANDPA key is used for participating in GRANDPA block finalisationimon
- the name of this key is a reference to "ImOnline", which is an online message that Gossamer nodes use to report liveliness
Runtime
In addition to the above-described services, Gossamer hosts a Wasm execution environment that is used to manage an upgradeable blockchain runtime. The runtime must be implemented in Wasm, and must expose an interface that is specified in lib/runtime/interface.go. The runtime defines the blockchain's state transition function, and the various Gossamer services consume this capability in order to author blocks, as well as to verify blocks that were authored by network peers. The runtime is dependent on a Wasm host interface, which Gossamer implements and is defined in lib/runtime/wasmer/exports.go.
Monitoring
Gossamer publishes telemetry data and also includes an embedded Prometheus server that reports metrics. The metrics
capabilities are defined in the dot/metrics package and build on
the metrics library that is included with Go Ethereum.
The default listening address for Prometheus metrics is localhost:9876
, and Gossamer allows the user to configure this parameter with the
--metrics-address
command-line parameter. The Gossamer telemetry server publishes telemetry data that is compatible with
Polkadot Telemetry and
its helpful UI.
Documentation ¶
There is no documentation for this package.