Operators & Nodes

validator

Manage validator registration, committee membership, and reporting.

Note

State-modifying subcommands accept transaction processing arguments.

make-validator-info

Generate validator key files and metadata.

soma validator make-validator-info <HOST_NAME> [COMMISSION_RATE]

Argument	Type	Required	Description
host_name	string	Yes	Hostname for the validator
commission_rate	u16	No	Commission rate in basis points (default from config)

Generates the following files in the current directory:

File	Description
protocol.key	Protocol keypair
account.key	Account keypair
network.key	Network keypair
worker.key	Worker keypair
validator.info	Signed validator metadata (used with join-committee)

soma validator make-validator-info validator.example.com 200

join-committee

Request to join the validator committee.

soma validator join-committee <VALIDATOR_INFO_PATH>

Argument	Type	Required	Description
validator-info-path	path	Yes	Path to validator.info file

soma validator join-committee ./validator.info

leave-committee

Request to leave the validator committee. Takes effect at end of current epoch.

soma validator leave-committee

soma validator leave-committee

list

List all active and pending validators.

soma validator list

display-metadata

Display validator metadata.

soma validator display-metadata [VALIDATOR_ADDRESS]

Argument	Type	Required	Description
validator-address	SomaAddress	No	Validator address (defaults to active address)

soma validator display-metadata

soma validator display-metadata 0xVAL...

update-metadata

Update validator metadata. Changes take effect next epoch.

soma validator update-metadata <SUBCOMMAND> <VALUE>

Available subcommands:

Subcommand	Value type	Description
network-address	address	Update network address
primary-address	address	Update primary address
p2p-address	address	Update P2P address
network-pub-key	path	Update network public key from file
worker-pub-key	path	Update worker public key from file
protocol-pub-key	path	Update protocol public key from file

soma validator update-metadata network-address /dns/validator.example.com/tcp/8080/http

soma validator update-metadata protocol-pub-key ./new-protocol.key

set-commission-rate

Set validator commission rate. Takes effect next epoch.

soma validator set-commission-rate <COMMISSION_RATE>

Argument	Type	Required	Description
commission-rate	u16	Yes	Commission rate in basis points (max 10000)

soma validator set-commission-rate 500

report-validator

Report a misbehaving validator.

soma validator report-validator <REPORTEE_ADDRESS> [OPTIONS]

Argument	Type	Required	Description
reportee-address	SomaAddress	Yes	Address of the validator to report
--undo-report	flag	No	Undo a previous report

soma validator report-validator 0xVAL...

soma validator report-validator 0xVAL... --undo-report

report-model

Report a model (validators only). If 2f+1 validators report a model at an epoch boundary, the model is slashed.

soma validator report-model <MODEL_ID> [OPTIONS]

Argument	Type	Required	Description
model-id	ObjectID	Yes	Model object ID to report
--undo-report	flag	No	Undo a previous report

soma validator report-model 0xMODEL...

soma validator report-model 0xMODEL... --undo-report

start

Start nodes and services.

localnet

Start a local development network.

soma start localnet [OPTIONS]

Argument	Type	Required	Description
--network.config	path	No	Path to network config
--force-regenesis	flag	No	Force regenesis even if state exists
--fullnode-rpc-port	u16	No	RPC port for the fullnode (default 9000)
--epoch-duration-ms	u64	No	Epoch duration in milliseconds
--data-ingestion-dir	path	No	Directory for data ingestion
--no-full-node	flag	No	Skip starting a fullnode
--committee-size	u64	No	Number of validators in the committee
--log-level	string	No	Log level (default info)
--with-faucet	string	No	Start faucet at host:port
--no-faucet	flag	No	Do not start faucet
--no-scoring	flag	No	Do not start scoring service
--small-model	flag	No	Use small model for scoring

soma start localnet

soma start localnet --force-regenesis --epoch-duration-ms 10000 --with-faucet 127.0.0.1:9123

validator

Start a validator node from a config file.

soma start validator --config <PATH>

Argument	Type	Required	Description
-c, --config	path	Yes	Path to validator configuration file

soma start validator --config ./validator-config.yaml

faucet

Start a standalone faucet server.

soma start faucet [OPTIONS]

Argument	Type	Required	Description
--port	u16	No	Port to listen on
--host	string	No	Host to bind to (default 0.0.0.0)
--amount	u64	No	Amount in shannons per coin
--num-coins	u64	No	Number of coins to dispense per request
--config-dir	path	No	Path to SOMA config directory

soma start faucet --port 9123

scoring

Start the scoring service.

soma start scoring [OPTIONS]

Argument	Type	Required	Description
--host	string	No	Host to bind to (default 0.0.0.0)
--port	u16	No	Port to listen on (default 9124)
--data-dir	path	No	Data directory for scoring state
--small-model	flag	No	Use a smaller model for testing
--device	string	No	Compute device: cpu, wgpu, or cuda (default wgpu)

soma start scoring

soma start scoring --device cuda --port 9124

network

Inspect local network configuration.

soma network [OPTIONS]

Argument	Type	Required	Description
--network.config	path	No	Path to network config file
-d, --dump-addresses	flag	No	Dump validator addresses

soma network

soma network --dump-addresses

genesis

Bootstrap and initialize a new network.

soma genesis [OPTIONS]

Argument	Type	Required	Description
--from-config	path	No	Create genesis from an existing config
--write-config	path	No	Write configuration to file without building genesis
--working-dir	path	No	Working directory for genesis output
--force	flag	No	Overwrite existing genesis state
--epoch-duration-ms	u64	No	Epoch duration in milliseconds
--with-faucet	flag	No	Include faucet in genesis
--committee-size	u64	No	Number of validators

soma genesis --working-dir ./genesis-output --committee-size 4

soma genesis --from-config ./genesis-config.yaml --force

ceremony

Coordinate a multi-validator genesis ceremony for network launches.

soma genesis ceremony [OPTIONS]

Used to coordinate genesis across multiple validator operators. Each participant runs the ceremony command to contribute their validator information, and the coordinator assembles the final genesis state.

keytool

Low-level keystore operations.

generate

Generate a new keypair.

soma keytool generate <KEY_SCHEME> [DERIVATION_PATH] [WORD_LENGTH]

Argument	Type	Required	Description
key-scheme	string	Yes	Signing scheme (ed25519, secp256k1, secp256r1)
derivation-path	string	No	BIP-44 derivation path
word-length	string	No	Mnemonic word count

soma keytool generate ed25519

import

Import a key from a mnemonic or private key.

soma keytool import [--alias <ALIAS>] <INPUT_STRING> <KEY_SCHEME> [DERIVATION_PATH]

Argument	Type	Required	Description
input-string	string	Yes	Mnemonic phrase or private key
key-scheme	string	Yes	Signing scheme
--alias	string	No	Alias for the imported key
derivation-path	string	No	BIP-44 derivation path

soma keytool import "word1 word2 ... word12" ed25519 --alias imported-key

export

Export a private key from the keystore.

soma keytool export --key-identity <IDENTITY>

Argument	Type	Required	Description
--key-identity	string	Yes	Address or alias of the key to export

Danger

This outputs the raw private key. Never share it or store it in plaintext.

list

List all keys in the keystore.

soma keytool list [OPTIONS]

Argument	Type	Required	Description
--sort-by-alias	flag	No	Sort output by alias

soma keytool list

Additional keytool subcommands

Subcommand	Description
update-alias	Update the alias for a key
decode-or-verify-tx	Decode or verify a transaction
decode-multi-sig	Decode a multi-sig transaction
load-keypair	Load a keypair from a file
multi-sig-address	Derive a multi-sig address
multi-sig-combine-partial-sig	Combine partial signatures for multi-sig

completions

Generate shell completion scripts.

Bash

soma completions bash > ~/.local/share/bash-completion/completions/soma

Zsh

soma completions zsh > ~/.zfunc/_soma

Fish

soma completions fish > ~/.config/fish/completions/soma.fish