bios

package module
v0.3.5 Latest Latest
Warning

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

 Go to latest Published: Apr 26, 2018 License: MIT Imports: 21 Imported by: 0

README

EOS.IO Software-based blockchain boot orchestration tool

eos-bios is a command-line tool for people who want to kickstart a blockchain using EOS.IO Software.

It implements the following:

  • Booting a mainnet
  • Booting testnets
  • Booting local development environments
  • Booting consortium or private networks
  • Orchestrates launches with many participants through the Network Discovery Protocol.

This program relies on you publishing a discovery file.

NOTE: Jump directly to the sample configurations if you know what you're doing.

Launch a local node with a single command

Download eos-bios, clone this repo, go to sample_configs/docker:

git clone https://github.com/eoscanada/eos-bios
cd eos-bios/sample_configs/docker
wget https://github.com/eoscanada/eos-bios/releases/download/......tar.gz  # Pick the right one for you
tar -zxvf eos-bios*tar.gz
mv eos-bios_*/eos-bios .

Then run:

./eos-bios boot

Enjoy.

This gives you a fully fledged development environment, a chain loaded with all system contracts, very similar to what you will get on the main network once launched.

The sample configuration sets up a single node, as it doesn't point to other block producer candidates (through the wingmen property).

Boot a network

By tweaking your configuration, you can grow the network. To force the boot operation, run:

./eos-bios boot

Have your friends run:

./eos-bios join --verify

Once your boot call finishes properly, it will display the Kickstart Data that you can provide your friends with. Once they paste that in their terminal, they will join your network.

For this to work, you need to properly configure your config.yaml and have properly disseminated your discovery files, and given the URL to your friends.

Join an existing network

To join a network, tweak your discovery file to point to the network you're trying to join and publish it. Make sure other participants in the network link to your discovery file as their wingmen.

Run:

eos-bios join [--verify]

The --verify option toggles the boot sequence verification.

Orchestrate a community launch

When the time comes to orchestrate a launch, everyone will run:

eos-bios orchestrate

According to an algorithm, and using the network discovery data, each team will be assigned a role deterministically.

You then fall in one of these three categories:

  1. The BIOS Boot node, which will, alone, execute the equivalent of eos-bios boot.
  2. An Appointed Block Producer, which executes the equivalent of eos-bios join --verify
  3. An other participant, which executes the equivalent of eos-bios join

The same hooks are used in boot, join and orchestrate, so get them right and practice.

Install / Download

You can download the latest release here: https://github.com/eoscanada/eos-bios/releases .. it is a single binary that you can download on all major platforms. Simply make executable and run. It has zero dependencies.

Alternatively, you can build from source with:

go get -v github.com/eoscanada/eos-bios/eos-bios

This will install the binary in ~/go/bin provided you have the Go tool installed (quick install at https://golang.org/dl)

Join the discussion

On Telegram through this invite link: https://t.me/joinchat/GSUv1UaI5QIuifHZs8k_eA (EOSIO BIOS Boot channel)

Previous proposition

See the previous proposition in this repo in README.v0.md

TODO

  • Shuffling of the top 5 for Boot selection
  • Wait on Bitcoin Block
    • Add bitcoin_block_height in LaunchData
  • In Orchestrate, compute the LaunchData by the most votes, weighted by the highest Weight

Documentation

Index

Constants

View Source 
const (
	RoleBootNode = Role(iota)
	RoleABP
	RoleParticipant
)

Variables

View Source 
var AN = eos.AN

AN is a shortcut to create an AccountName

View Source 
var ConfiguredHooks = []HookDef{
	HookDef{"init", "Dispatch when we start the program."},
	HookDef{"boot_network", "Dispatched when we are BIOS Node, and our keys and node config is ready. Should trigger a config update and a restart."},
	HookDef{"publish_kickstart_data", "Dispatched with the contents of the (usually encrypted) Kickstart data, to be published to your social / web properties."},
	HookDef{"join_network", "Dispatched anyone joining the network. Could be as an Appointed Block Producer, or simply someone wanting to join the network after boot. It provides at least one p2p_address to connect to."},
	HookDef{"done", "When your process it done"},
}
View Source 
var PN = eos.PN

PN is a shortcut to create a PermissionName

Functions

func ScanLinesUntilBlank 

func ScanLinesUntilBlank() (out string, err error)

Types

type BIOS 

type BIOS struct {
	Network *discovery.Network

	LaunchData   *discovery.LaunchData
	Config       *Config
	API          *eos.API
	Snapshot     Snapshot
	BootSequence []*OperationType

	KickstartData *KickstartData

	// ShuffledProducers is an ordered list of producers according to
	// the shuffled peers.
	ShuffledProducers []*discovery.Peer

	// MyPeers represent the peers my local node will handle. It is
	// plural because when launching a 3-node network, your peer will
	// be cloned a few time to have a full schedule of 21 producers.
	MyPeers []*discovery.Peer

	EphemeralPrivateKey *ecc.PrivateKey
}

func NewBIOS 

func NewBIOS(network *discovery.Network, config *Config, api *eos.API) *BIOS

func (*BIOS) AmIAppointedBlockProducer 

func (b *BIOS) AmIAppointedBlockProducer() bool

func (*BIOS) AmIBootNode 

func (b *BIOS) AmIBootNode() bool

func (*BIOS) DispatchBootNetwork 

func (b *BIOS) DispatchBootNetwork(genesisJSON, publicKey, privateKey string) error

func (*BIOS) DispatchDone 

func (b *BIOS) DispatchDone() error

func (*BIOS) DispatchInit 

func (b *BIOS) DispatchInit() error

func (*BIOS) DispatchJoinNetwork 

func (b *BIOS) DispatchJoinNetwork(kickstart *KickstartData, peerDefs []*discovery.Peer) error

func (*BIOS) DispatchPublishKickstartData 

func (b *BIOS) DispatchPublishKickstartData(kickstartData string) error

func (*BIOS) GenerateEphemeralPrivKey 

func (b *BIOS) GenerateEphemeralPrivKey() (*ecc.PrivateKey, error)

func (*BIOS) GenerateGenesisJSON 

func (b *BIOS) GenerateGenesisJSON(pubKey string) string

func (*BIOS) Init 

func (b *BIOS) Init() error

func (*BIOS) IsAppointedBlockProducer 

func (b *BIOS) IsAppointedBlockProducer(account string) bool

func (*BIOS) IsBootNode 

func (b *BIOS) IsBootNode(account string) bool

func (*BIOS) MyPeer 

func (b *BIOS) MyPeer() (*discovery.Peer, error)

func (*BIOS) MyRole 

func (b *BIOS) MyRole() Role

func (*BIOS) PrintOrderedPeers 

func (b *BIOS) PrintOrderedPeers()

func (*BIOS) RunBootSequence 

func (b *BIOS) RunBootSequence() error

func (*BIOS) RunJoinNetwork added in v0.3.3 

func (b *BIOS) RunJoinNetwork(verify, sabotage bool) error

func (*BIOS) SetKickstartData 

func (b *BIOS) SetKickstartData(ks *KickstartData)

func (*BIOS) StartBoot added in v0.3.3 

func (b *BIOS) StartBoot() error

func (*BIOS) StartJoin added in v0.3.3 

func (b *BIOS) StartJoin(verify bool) error

func (*BIOS) StartOrchestrate added in v0.3.3 

func (b *BIOS) StartOrchestrate() error

type Config 

type Config struct {
	// Producer describes your producing node.
	Peer struct {
		// MyAccount is the name of the `account_name` this producer will be using on chain
		MyAccount string `json:"my_account"`
		// APIAddress is the target API endpoint for the locally booting node, a clean-slate node. It can be routable only from the local machine.
		APIAddress    string   `json:"api_address"`
		APIAddressURL *url.URL `json:"-"`
		// SecretP2PAddress is the endpoint which will be published at the end of the process. Needs to be externally routable.  It must be kept secret for DDoS protection.
		SecretP2PAddress string `json:"secret_p2p_address"`

		// Key you want to register to sign blocks.
		BlockSigningPublicKey ecc.PublicKey `json:"block_signing_public_key"`

		// Private key used to setup your config.ini as an ABP (or as someone joining the network)
		BlockSigningPrivateKeyPath string `json:"block_signing_private_key_path"`

		// Available once loaded successfuly from the previous field's path.
		BlockSigningPrivateKey *ecc.PrivateKey `json:"-"`
	} `json:"producer"`

	// PGP manages the PGP keys, used for the communications channel.
	PGP struct {
		// Program represents the type of program to use (gpg, keybase ?)
		Program string `json:"program"`
		// Path to binary executable.. unless we use in-process cryptography..
		Path string `json:"path"`
	} `json:"pgp"`
}

type GenesisJSON 

type GenesisJSON struct {
	InitialTimestamp string `json:"initial_timestamp"`
	InitialKey       string `json:"initial_key"`
	InitialChainID   string `json:"initial_chain_id"`
}

type HookDef 

type HookDef struct {
	Key  string
	Desc string
}

type KickstartData 

type KickstartData struct {
	BIOSP2PAddress string `json:"bios_p2p_address"`
	PrivateKeyUsed string `json:"private_key_used"`
	PublicKeyUsed  string `json:"public_key_used"`
	GenesisJSON    string `json:"genesis_json"`
}

type OpCreateProducers 

type OpCreateProducers struct {
	// TestnetEnrichProducers will provide each producer account with some EOS, only on testnets.
	TestnetEnrichProducers bool `json:"TESTNET_ENRICH_PRODUCERS"`
}

func (*OpCreateProducers) Actions 

func (op *OpCreateProducers) Actions(b *BIOS) (out []*eos.Action, err error)

func (*OpCreateProducers) ResetTestnetOptions 

func (op *OpCreateProducers) ResetTestnetOptions()

type OpCreateToken 

type OpCreateToken struct {
	Account      eos.AccountName
	Amount       eos.Asset
	CanWhitelist bool `json:"can_whitelist"`
	CanFreeze    bool `json:"can_freeze"`
	CanRecall    bool `json:"can_recall"`
}

func (*OpCreateToken) Actions 

func (op *OpCreateToken) Actions(b *BIOS) (out []*eos.Action, err error)

func (*OpCreateToken) ResetTestnetOptions 

func (op *OpCreateToken) ResetTestnetOptions()

type OpDestroyAccounts 

type OpDestroyAccounts struct {
	Accounts            []eos.AccountName
	TestnetKeepAccounts bool `json:"TESTNET_KEEP_ACCOUNTS"`
}

func (*OpDestroyAccounts) Actions 

func (op *OpDestroyAccounts) Actions(b *BIOS) (out []*eos.Action, err error)

func (*OpDestroyAccounts) ResetTestnetOptions 

func (op *OpDestroyAccounts) ResetTestnetOptions()

type OpInjectSnapshot 

type OpInjectSnapshot struct {
	TestnetTruncateSnapshot int `json:"TESTNET_TRUNCATE_SNAPSHOT"`
}

func (*OpInjectSnapshot) Actions 

func (op *OpInjectSnapshot) Actions(b *BIOS) (out []*eos.Action, err error)

func (*OpInjectSnapshot) ResetTestnetOptions 

func (op *OpInjectSnapshot) ResetTestnetOptions()

type OpIssueToken 

type OpIssueToken struct {
	Account eos.AccountName
	Amount  eos.Asset
	Memo    string
}

func (*OpIssueToken) Actions 

func (op *OpIssueToken) Actions(b *BIOS) (out []*eos.Action, err error)

func (*OpIssueToken) ResetTestnetOptions 

func (op *OpIssueToken) ResetTestnetOptions()

type OpNewAccount 

type OpNewAccount struct {
	Creator    eos.AccountName
	NewAccount eos.AccountName `json:"new_account"`
	Pubkey     string
}

func (*OpNewAccount) Actions 

func (op *OpNewAccount) Actions(b *BIOS) (out []*eos.Action, err error)

func (*OpNewAccount) ResetTestnetOptions 

func (op *OpNewAccount) ResetTestnetOptions()

type OpSetCode 

type OpSetCode struct {
	Account         eos.AccountName
	ContractNameRef string `json:"contract_name_ref"`
}

func (*OpSetCode) Actions 

func (op *OpSetCode) Actions(b *BIOS) ([]*eos.Action, error)

func (*OpSetCode) ResetTestnetOptions 

func (op *OpSetCode) ResetTestnetOptions()

type OpSetPriv 

type OpSetPriv struct {
	Account eos.AccountName
	IsPriv  bool `json:"is_priv"` // unused
}

func (*OpSetPriv) Actions 

func (op *OpSetPriv) Actions(b *BIOS) (out []*eos.Action, err error)

func (*OpSetPriv) ResetTestnetOptions 

func (op *OpSetPriv) ResetTestnetOptions()

type OpSetProds 

type OpSetProds struct{}

func (*OpSetProds) Actions 

func (op *OpSetProds) Actions(b *BIOS) (out []*eos.Action, err error)

func (*OpSetProds) ResetTestnetOptions 

func (op *OpSetProds) ResetTestnetOptions()

type Operation 

type Operation interface {
	Actions(b *BIOS) ([]*eos.Action, error)
	ResetTestnetOptions()
}

type OperationType 

type OperationType struct {
	Op    string
	Label string
	Data  Operation
}

func (*OperationType) UnmarshalJSON 

func (o *OperationType) UnmarshalJSON(data []byte) error

type Role 

type Role int

type Snapshot 

type Snapshot []SnapshotLine

func NewSnapshot 

func NewSnapshot(content []byte) (out Snapshot, err error)

type SnapshotLine 

type SnapshotLine struct {
	EthereumAddress string
	EOSPublicKey    ecc.PublicKey
	Balance         eos.Asset
}

Source Files

View all Source files

Directories

Path Synopsis
cmd

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.