chain

package
v1.22.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 3, 2026 License: BSD-3-Clause Imports: 49 Imported by: 0

Documentation

Overview

Package chain provides chain configuration management with an overlay model.

Config precedence (highest → lowest):

  1. CLI flags / inline JSON
  2. Per-run overrides (in run dir)
  3. User global chain configs (~/.lux/chains/<chain-id>/config.json)
  4. Built-in defaults

The run directory chainConfigs are treated as rendered output, not source.

Package chain provides chain deployment and management utilities.

Package chain provides chain deployment and management utilities.

Package chain provides chain deployment and management utilities.

Index

Constants

View Source 
const (
	WriteReadReadPerms = 0o644
	// ChainHealthTimeout is the maximum time to wait for a newly deployed chain to become healthy
	// For local networks (5 nodes on localhost), chains should be healthy in <10s
	ChainHealthTimeout = 10 * time.Second
	// LocalNetworkHealthTimeout is for checking if the network itself is running
	LocalNetworkHealthTimeout = 5 * time.Second
	// BlockchainCreationTimeout is the maximum time to wait for CreateChains RPC call
	// This involves a P-chain transaction, subnet creation, and chain creation
	// On a fresh network, this can take up to 30s for consensus to be reached
	BlockchainCreationTimeout = 30 * time.Second
)

Chain deployment constants.

View Source 
const (
	// PChainID is the well-known P-Chain blockchain ID (all 1s with LpoYY suffix)
	PChainID = "11111111111111111111111111111111LpoYY"
)

Well-known chain IDs

Variables

View Source 
var ErrNoSubnetAuthKeysInWallet = errors.New("auth wallet does not contain subnet auth keys")

ErrNoSubnetAuthKeysInWallet indicates the wallet doesn't contain required subnet auth keys.

Functions

func CheckNodeIsInSubnetPendingValidators 

func CheckNodeIsInSubnetPendingValidators(subnetID ids.ID, nodeID string) (bool, error)

CheckNodeIsInSubnetPendingValidators checks if a node is in the pending validators for a subnet.

func CopySubnetChainConfigsToNetwork 

func CopySubnetChainConfigsToNetwork(app *application.Lux, networkDir string) error

CopySubnetChainConfigsToNetwork copies chain configs from ~/.lux/subnets/<name>/ to each node's chainConfigs/<blockchainID>/ directory. This is necessary because evm requires genesis.json in the chain config directory for initialization. The canonical source is always ~/.lux/subnets/<name>/ and this function ensures the running network nodes have access to these configs.

func DefaultEVMConfig 

func DefaultEVMConfig() map[string]interface{}

DefaultEVMConfig returns the default EVM chain configuration with admin API enabled. This applies to all EVM chains including C-chain and deployed chains.

func EnsureNetworkRunDir 

func EnsureNetworkRunDir(baseRunsDir, network string) (string, error)

EnsureNetworkRunDir ensures a network run directory exists. If "current" symlink exists, reuses it. Otherwise creates a new timestamped run. Use `lux network clean` to wipe and start fresh.

func GetCurrentSupply 

func GetCurrentSupply(subnetID ids.ID) error

GetCurrentSupply prints the current supply of a subnet.

func GetDefaultSubnetAirdropKeyInfo 

func GetDefaultSubnetAirdropKeyInfo(_ *application.Lux, _ string) (string, string, string, error)

GetDefaultSubnetAirdropKeyInfo returns the default airdrop key information for a subnet.

func GetFirstEndpoint 

func GetFirstEndpoint(clusterInfo *rpcpb.ClusterInfo, chain string) string

GetFirstEndpoint get a human readable endpoint for the given chain

func GetLocallyDeployedNetIDs 

func GetLocallyDeployedNetIDs(app *application.Lux) ([]string, error)

GetLocallyDeployedNetIDs returns a list of net IDs for locally deployed nets This is used for auto-tracking nets when starting the local network

func GetLocallyDeployedSubnetIDs 

func GetLocallyDeployedSubnetIDs(app *application.Lux) ([]string, error)

GetLocallyDeployedSubnetIDs returns a list of subnet IDs for locally deployed subnets This is used for auto-tracking subnets when starting the local network Deprecated: Use GetLocallyDeployedNetIDs instead

func GetLocallyDeployedSubnets 

func GetLocallyDeployedSubnets() (map[string]struct{}, error)

GetLocallyDeployedSubnets returns the locally deployed subnets. Returns an error if the server cannot be contacted.

func GetLocallyDeployedSubnetsFromFile 

func GetLocallyDeployedSubnetsFromFile(app *application.Lux) ([]string, error)

GetLocallyDeployedSubnetsFromFile reads the list of locally deployed subnets from file.

func GetPublicSubnetValidators 

func GetPublicSubnetValidators(subnetID ids.ID, network models.Network) ([]platformvm.ClientPermissionlessValidator, error)

GetPublicSubnetValidators returns the validators for a subnet on a public network.

func GetSubnetValidators 

func GetSubnetValidators(subnetID ids.ID) ([]platformvm.ClientPermissionlessValidator, error)

GetSubnetValidators returns the validators for a subnet.

func HasEndpoints 

func HasEndpoints(clusterInfo *rpcpb.ClusterInfo) bool

HasEndpoints returns true if cluster info contains custom blockchains

func IsSubnetValidator 

func IsSubnetValidator(subnetID ids.ID, nodeID ids.NodeID, network models.Network) (bool, error)

IsSubnetValidator checks if a node is a validator for the given subnet.

func IssueAddPermissionlessValidatorTx 

func IssueAddPermissionlessValidatorTx(
	kc keychain.Keychain,
	subnetID ids.ID,
	nodeID ids.NodeID,
	stakeAmount uint64,
	assetID ids.ID,
	startTime uint64,
	endTime uint64,
) (ids.ID, error)

IssueAddPermissionlessValidatorTx issues an add permissionless validator transaction.

func IssueRemoveSubnetValidatorTx 

func IssueRemoveSubnetValidatorTx(kc keychain.Keychain, subnetID ids.ID, nodeID ids.NodeID) (ids.ID, error)

IssueRemoveSubnetValidatorTx issues a remove subnet validator transaction.

func IssueTransformSubnetTx 

func IssueTransformSubnetTx(
	elasticSubnetConfig climodels.ElasticChainConfig,
	kc keychain.Keychain,
	_ ids.ID,
	tokenName string,
	tokenSymbol string,
	maxSupply uint64,
) (ids.ID, ids.ID, error)

IssueTransformSubnetTx transforms a subnet to a permissionless elastic subnet.

func PrepareCanonicalChainConfigs 

func PrepareCanonicalChainConfigs(app *application.Lux) (string, error)

PrepareCanonicalChainConfigs creates the canonical chain configs directory at ~/.lux/chains/ with subdirectories for each locally deployed subnet's blockchain ID. This directory can be passed to nodes via --chain-config-dir flag so all nodes share the same chain configs from a single source. Returns the canonical chain configs directory path.

func SetDefaultSnapshot 

func SetDefaultSnapshot(snapshotsDir string, force bool) error

SetDefaultSnapshot initializes the default snapshot with the bootstrap snapshot archive. If force flag is set to true, it overwrites the default snapshot if it exists.

func ValidateSubnetNameAndGetChains 

func ValidateSubnetNameAndGetChains(subnetName string) error

ValidateSubnetNameAndGetChains validates a subnet name and returns chain information

func WaitForChainHealthyWithTimeout added in v1.21.40 

func WaitForChainHealthyWithTimeout(
	cli client.Client,
	chainName string,
	timeout time.Duration,
	rootDir string,
	backendLogDir string,
) (*rpcpb.ClusterInfo, error)

WaitForChainHealthyWithTimeout waits for a chain to become healthy with a specific timeout. Returns an error with helpful diagnostics if the chain fails to become healthy.

func WaitForHealthy 

func WaitForHealthy(
	ctx context.Context,
	cli client.Client,
) (*rpcpb.ClusterInfo, error)

WaitForHealthy polls continuously until the network is ready to be used

Types

type Config 

type Config struct {
	// contains filtered or unexported fields
}

Config represents a chain configuration with overlay support

func NewConfig 

func NewConfig(app *application.Lux, chainID string) *Config

NewConfig creates a new chain config for the given chain ID

func NewConfigWithAlias 

func NewConfigWithAlias(app *application.Lux, chainID, alias string) *Config

NewConfigWithAlias creates a config with both chain ID and human-readable alias

func (*Config) Effective 

func (c *Config) Effective() map[string]interface{}

Effective returns the effective configuration by merging all layers

func (*Config) EffectiveJSON 

func (c *Config) EffectiveJSON() (string, error)

EffectiveJSON returns the effective config as formatted JSON

func (*Config) EnableAdmin 

func (c *Config) EnableAdmin()

EnableAdmin ensures admin API is enabled in the config

func (*Config) LoadGlobal 

func (c *Config) LoadGlobal() error

LoadGlobal loads the global config from ~/.lux/chains/<chainID>/config.json

func (*Config) Render 

func (c *Config) Render(runDir string) error

Render writes the config to the specified run directory's chainConfigs

func (*Config) SaveGlobal 

func (c *Config) SaveGlobal() error

SaveGlobal saves the effective config as the global config

func (*Config) SetCLIOverride 

func (c *Config) SetCLIOverride(key string, value interface{})

SetCLIOverride sets a CLI override for specific keys

func (*Config) SetCLIOverrides 

func (c *Config) SetCLIOverrides(overrides map[string]interface{})

SetCLIOverrides sets multiple CLI overrides

type DeploymentError added in v1.21.42 

type DeploymentError struct {
	ChainName string
	Cause     error
	// NetworkHealthy indicates if the primary network is still running after the failure
	NetworkHealthy bool
	// Recoverable indicates if the error can be fixed and retried
	Recoverable bool
	// Suggestion provides actionable guidance to fix the issue
	Suggestion string
}

DeploymentError represents a chain deployment failure that does NOT crash the network. The network remains running and can accept new deployments.

func NewRecoverableDeploymentError added in v1.21.42 

func NewRecoverableDeploymentError(chainName string, cause error, suggestion string) *DeploymentError

NewRecoverableDeploymentError creates a deployment error that can be retried

func (*DeploymentError) Error added in v1.21.42 

func (e *DeploymentError) Error() string

func (*DeploymentError) Unwrap added in v1.21.42 

func (e *DeploymentError) Unwrap() error

type LocalDeployer 

type LocalDeployer struct {
	// contains filtered or unexported fields
}

LocalDeployer handles local chain deployment.

func NewLocalDeployer 

func NewLocalDeployer(app *application.Lux, luxVersion string, vmBin string) *LocalDeployer

NewLocalDeployer creates a new LocalDeployer instance.

func NewLocalDeployerForNetwork added in v1.21.42 

func NewLocalDeployerForNetwork(app *application.Lux, luxVersion, vmBin, networkType string) *LocalDeployer

NewLocalDeployerForNetwork creates a deployer for a specific network type

func (*LocalDeployer) BackendStartedHere 

func (d *LocalDeployer) BackendStartedHere() bool

BackendStartedHere returns true if the backend was started by this run, or false if it found it there already

func (*LocalDeployer) DeployBlockchain 

func (d *LocalDeployer) DeployBlockchain(chain string, chainGenesis []byte) (ids.ID, ids.ID, error)

DeployBlockchain deploys a blockchain to the local network

func (*LocalDeployer) DeployToLocalNetwork 

func (d *LocalDeployer) DeployToLocalNetwork(chain string, chainGenesis []byte, genesisPath string) (ids.ID, ids.ID, error)

DeployToLocalNetwork deploys to an already running network. It does NOT start the network - use 'lux network start' first.

func (*LocalDeployer) SetupLocalEnv 

func (d *LocalDeployer) SetupLocalEnv() (string, error)

SetupLocalEnv also does some heavy lifting: * sets up default snapshot if not installed * checks if node is installed in the local binary path * if not, it downloads it and installs it (os - and archive dependent) * returns the location of the node path

func (*LocalDeployer) StartServer 

func (d *LocalDeployer) StartServer() error

StartServer starts the gRPC server for the deployer's network type. If no network type is set, defaults to mainnet for backward compatibility.

func (*LocalDeployer) StartServerForNetwork added in v1.21.42 

func (d *LocalDeployer) StartServerForNetwork(networkType string) error

StartServerForNetwork starts the gRPC server for a specific network type.

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager handles chain configuration for a network run

func NewManager 

func NewManager(app *application.Lux) *Manager

NewManager creates a new chain config manager

func (*Manager) AddChain 

func (m *Manager) AddChain(chainID string) *Config

AddChain adds a chain configuration to the manager

func (*Manager) AddChainWithAlias 

func (m *Manager) AddChainWithAlias(chainID, alias string) *Config

AddChainWithAlias adds a chain with both ID and alias

func (*Manager) EnableAdminAll 

func (m *Manager) EnableAdminAll()

EnableAdminAll enables admin API on all chains

func (*Manager) GetConfig 

func (m *Manager) GetConfig(chainIDOrAlias string) *Config

GetConfig returns the config for a chain (by ID or alias)

func (*Manager) LoadDeployedChains 

func (m *Manager) LoadDeployedChains() error

LoadDeployedChains discovers and loads configs for all deployed chains

func (*Manager) RenderAll 

func (m *Manager) RenderAll(runDir string) error

RenderAll renders all chain configs to the run directory

func (*Manager) ToNetrunnerMap 

func (m *Manager) ToNetrunnerMap() map[string]string

ToNetrunnerMap converts configs to the format expected by netrunner's WithChainConfigs

type PublicDeployer 

type PublicDeployer struct {
	LocalDeployer
	// contains filtered or unexported fields
}

PublicDeployer handles chain deployment to public networks.

func NewPublicDeployer 

func NewPublicDeployer(app *application.Lux, usingLedger bool, kc keychain.Keychain, network models.Network) *PublicDeployer

NewPublicDeployer creates a new PublicDeployer instance.

func (*PublicDeployer) AddValidator 

func (d *PublicDeployer) AddValidator(
	controlKeys []string,
	subnetAuthKeysStrs []string,
	subnetID ids.ID,
	nodeID ids.NodeID,
	weight uint64,
	startTime time.Time,
	duration time.Duration,
) (bool, *txs.Tx, []string, error)

AddValidator adds a subnet validator to the given subnetID. It creates an add subnet validator tx, signs it with the wallet, and if fully signed, issues it. If partially signed, returns the tx for additional signatures.

func (*PublicDeployer) Commit 

func (d *PublicDeployer) Commit(
	tx *txs.Tx,
) (ids.ID, error)

Commit issues a fully signed transaction to the network.

func (*PublicDeployer) ConvertL1 

func (d *PublicDeployer) ConvertL1(
	controlKeys []string,
	subnetAuthKeysStrs []string,
	subnetID ids.ID,
	blockchainID ids.ID,
	managerAddress ethcommon.Address,
	validators []interface{},
) (bool, ids.ID, *txs.Tx, []string, error)

ConvertL1 converts a subnet to an L1 (LP99)

func (*PublicDeployer) CreateAssetTx 

func (d *PublicDeployer) CreateAssetTx(
	subnetID ids.ID,
	tokenName string,
	tokenSymbol string,
	denomination byte,
	initialState map[uint32][]verify.State,
) (ids.ID, error)

CreateAssetTx creates a new asset on the X-Chain.

func (*PublicDeployer) DeployBlockchain 

func (d *PublicDeployer) DeployBlockchain(
	controlKeys []string,
	subnetAuthKeysStrs []string,
	subnetID ids.ID,
	chain string,
	genesis []byte,
) (bool, ids.ID, *txs.Tx, []string, error)

DeployBlockchain creates a blockchain for the given subnet. It creates a create blockchain tx and sets the change output owner to be a wallet address (if not, it may go to any other subnet auth address).

func (*PublicDeployer) DeploySubnet 

func (d *PublicDeployer) DeploySubnet(
	controlKeys []string,
	threshold uint32,
) (ids.ID, error)

DeploySubnet creates a subnet using the given control keys and threshold.

func (*PublicDeployer) ExportToPChainTx 

func (d *PublicDeployer) ExportToPChainTx(
	subnetID ids.ID,
	subnetAssetID ids.ID,
	owner *secp256k1fx.OutputOwners,
	assetAmount uint64,
) (ids.ID, error)

ExportToPChainTx exports assets from X-Chain to P-Chain.

func (*PublicDeployer) ImportFromXChain 

func (d *PublicDeployer) ImportFromXChain(
	subnetID ids.ID,
	owner *secp256k1fx.OutputOwners,
) (ids.ID, error)

ImportFromXChain imports assets from X-Chain to P-Chain.

func (*PublicDeployer) IncreaseValidatorPChainBalance 

func (d *PublicDeployer) IncreaseValidatorPChainBalance(
	_ ids.ID,
	balance uint64,
) error

IncreaseValidatorPChainBalance increases a validator's balance on P-chain.

func (*PublicDeployer) RegisterL1Validator 

func (d *PublicDeployer) RegisterL1Validator(
	balance uint64,
	_ signer.ProofOfPossession,
	_ []byte,
) (ids.ID, ids.ID, error)

RegisterL1Validator registers a validator on the P-Chain for an L1 subnet.

func (*PublicDeployer) RemoveValidator 

func (d *PublicDeployer) RemoveValidator(
	controlKeys []string,
	subnetAuthKeysStrs []string,
	subnetID ids.ID,
	nodeID ids.NodeID,
) (bool, *txs.Tx, []string, error)

RemoveValidator removes a subnet validator from the given subnet. It verifies that the wallet is one of the subnet auth keys (so as to sign the tx). If operation is multisig (len(subnetAuthKeysStrs) > 1), it creates a remove subnet validator tx and sets the change output owner to be a wallet address.

func (*PublicDeployer) Sign 

func (d *PublicDeployer) Sign(
	tx *txs.Tx,
	subnetAuthKeysStrs []string,
	subnet ids.ID,
) error

Sign signs a transaction with the wallet's keys.

func (*PublicDeployer) TransformSubnetTx 

func (d *PublicDeployer) TransformSubnetTx(
	controlKeys []string,
	subnetAuthKeysStrs []string,
	elasticSubnetConfig climodels.ElasticChainConfig,
	subnetID ids.ID,
	subnetAssetID ids.ID,
) (bool, ids.ID, *txs.Tx, []string, error)

TransformSubnetTx transforms a subnet to a permissionless elastic subnet.

type Publisher 

type Publisher interface {
	// Publish commits and pushes subnet and VM YAML configurations to the repository.
	Publish(r *git.Repository, subnetName, vmName string, subnetYAML []byte, vmYAML []byte) error
	// GetRepo returns the git repository, cloning it if necessary.
	GetRepo() (*git.Repository, error)
}

Publisher defines the interface for publishing subnet and VM configurations to a git repository.

func NewPublisher 

func NewPublisher(repoDir, repoURL, alias string) Publisher

NewPublisher creates a new Publisher instance for the given repository.

type RunManager 

type RunManager struct {
	// contains filtered or unexported fields
}

RunManager manages network run directories with stable symlinks

func NewRunManager 

func NewRunManager(app *application.Lux, profile string) *RunManager

NewRunManager creates a new run manager for the given profile

func (*RunManager) ChainConfigDir 

func (r *RunManager) ChainConfigDir(nodeNum int) (string, error)

ChainConfigDir returns the chain config directory for a node

func (*RunManager) CleanOldRuns 

func (r *RunManager) CleanOldRuns(keep int) error

CleanOldRuns removes old run directories, keeping the N most recent 

func (r *RunManager) CurrentLink() string

CurrentLink returns the path to the "current" symlink

func (*RunManager) CurrentRunDir 

func (r *RunManager) CurrentRunDir() (string, error)

CurrentRunDir returns the actual run directory that "current" points to

func (*RunManager) EnsureRunDir 

func (r *RunManager) EnsureRunDir(fresh, newRun bool) (string, error)

EnsureRunDir ensures a run directory exists with the following behavior: - Default (fresh=false, newRun=false): Reuse current symlink target if it exists - fresh=true: Wipe current target and recreate empty - newRun=true: Create new timestamped directory and update current symlink

func (*RunManager) ListRuns 

func (r *RunManager) ListRuns() ([]string, error)

ListRuns returns all run directories for this profile

func (*RunManager) NodeDir 

func (r *RunManager) NodeDir(nodeNum int) (string, error)

NodeDir returns the directory for a specific node in the current run

func (*RunManager) ProfileDir 

func (r *RunManager) ProfileDir() string

ProfileDir returns the base directory for this profile

func (*RunManager) SetCurrent 

func (r *RunManager) SetCurrent(runDir string) error

SetCurrent updates the "current" symlink to point to the specified run

type WarpSpec 

type WarpSpec struct {
	SkipWarpDeploy               bool
	SkipRelayerDeploy            bool
	WarpVersion                  string
	RelayerVersion               string
	RelayerBinPath               string
	RelayerLogLevel              string
	MessengerContractAddressPath string
	MessengerDeployerAddressPath string
	MessengerDeployerTxPath      string
	FundedAddress                string
	RegistryBydecodePath         string
}

WarpSpec contains configuration for Warp deployments

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.