sharding

Documentation

Index

• Constants
• Variables
• func NewIndexHashedNodesCoordinator(shardConsensusGroupSize int, metaConsensusGroupSize int, hasher hashing.Hasher, ...) (*indexHashedNodesCoordinator, error)
• func NewMultiShardCoordinator(numberOfShards, selfId uint32) (*multiShardCoordinator, error)
• func NewValidator(stake *big.Int, rating int32, pubKey []byte, address []byte) (*validator, error)
• type Coordinator
• type Genesis
  • func NewGenesisConfig(genesisFilePath string) (*Genesis, error)
  • func (g *Genesis) InitialNodesBalances(shardCoordinator Coordinator, adrConv state.AddressConverter) (map[string]*big.Int, error)
• type InitialBalance
• type InitialNode
• type NodeInfo
  • func (ni *NodeInfo) Address() []byte
  • func (ni *NodeInfo) AssignedShard() uint32
  • func (ni *NodeInfo) PubKey() []byte
• type NodesCoordinator
• type NodesSetup
  • func NewNodesSetup(nodesFilePath string, numOfNodes uint64) (*NodesSetup, error)
  • func (ns *NodesSetup) GetShardIDForPubKey(pubKey []byte) (uint32, error)
  • func (ns *NodesSetup) InitialNodesInfo() map[uint32][]*NodeInfo
  • func (ns *NodesSetup) InitialNodesInfoForShard(shardId uint32) ([]*NodeInfo, error)
  • func (ns *NodesSetup) InitialNodesPubKeys() map[uint32][]string
  • func (ns *NodesSetup) InitialNodesPubKeysForShard(shardId uint32) ([]string, error)
  • func (ns *NodesSetup) NumberOfShards() uint32
• type OneShardCoordinator
  • func (osc *OneShardCoordinator) CommunicationIdentifier(destShardID uint32) string
  • func (osc *OneShardCoordinator) ComputeId(address state.AddressContainer) uint32
  • func (osc *OneShardCoordinator) IsInterfaceNil() bool
  • func (osc *OneShardCoordinator) NumberOfShards() uint32
  • func (osc *OneShardCoordinator) SameShard(firstAddress, secondAddress state.AddressContainer) bool
  • func (osc *OneShardCoordinator) SelfId() uint32
• type PublicKeysSelector
• type Validator

Constants

const MetachainShardId = uint32(0xFFFFFFFF)

MetachainShardId will be used to identify a shard ID as metachain

Variables

var ErrCouldNotParseAddress = errors.New("could not parse node's address")

ErrCouldNotParseAddress signals that a given address could not be parsed

var ErrCouldNotParsePubKey = errors.New("could not parse node's public key")

ErrCouldNotParsePubKey signals that a given public key could not be parsed

var ErrEligibleSelectionMismatch = errors.New("invalid eligible validator selection")

ErrEligibleSelectionMismatch signals a mismatch between the eligible list and the group selection bitmap

var ErrEligibleTooFewSelections = errors.New("too few selections for consensus group")

ErrEligibleTooFewSelections signals an invalid selection for consensus group

var ErrEligibleTooManySelections = errors.New("too many selections for consensus group")

ErrEligibleTooManySelections signals an invalid selection for consensus group

var ErrInvalidConsensusGroupSize = errors.New("invalid consensus group size")

ErrInvalidConsensusGroupSize signals that the consensus size is invalid (e.g. value is negative)

var ErrInvalidNumberOfShards = errors.New("the number of shards must be greater than zero")

ErrInvalidNumberOfShards signals that an invalid number of shards was passed to the sharding registry

var ErrInvalidShardId = errors.New("shard id must be smaller than the total number of shards")

ErrInvalidShardId signals that an invalid shard is was passed

var ErrMinNodesPerShardSmallerThanConsensusSize = errors.New("minimum nodes per shard is smaller than consensus group size")

ErrMinNodesPerShardSmallerThanConsensusSize signals that an invalid min nodes per shard has been provided

var ErrNegativeOrZeroConsensusGroupSize = errors.New("negative or zero consensus group size")

ErrNegativeOrZeroConsensusGroupSize signals that an invalid consensus group size has been provided

var ErrNegativeStake = errors.New("negative stake")

ErrNegativeStake signals that the stake is negative

var ErrNilAddress = errors.New("nil address")

ErrNilAddress signals that the address is nil

var ErrNilAddressConverter = errors.New("trying to set nil address converter")

ErrNilAddressConverter signals that a nil address converter has been provided

var ErrNilHasher = errors.New("nil hasher")

ErrNilHasher signals that a nil hasher has been provided

var ErrNilInputNodesMap = errors.New("nil input nodes map")

ErrNilInputNodesMap signals that a nil nodes map was provided

var ErrNilPubKey = errors.New("nil public key")

ErrNilPubKey signals that the public key is nil

var ErrNilRandomness = errors.New("nil randomness source")

ErrNilRandomness signals that a nil randomness source has been provided

var ErrNilShardCoordinator = errors.New("trying to set nil shard coordinator")

ErrNilShardCoordinator signals that a nil shard coordinator has been provided

var ErrNilStake = errors.New("nil stake")

ErrNilStake signals that a nil stake structure has been provided

var ErrNoPubKeys = errors.New("no public keys defined")

ErrNoPubKeys signals an error when public keys are missing

var ErrNodesSizeSmallerThanMinNoOfNodes = errors.New("length of nodes defined is smaller than min nodes per shard required")

ErrNodesSizeSmallerThanMinNoOfNodes signals that there are not enough nodes defined in genesis file

var ErrPublicKeyNotFoundInGenesis = errors.New("public key is not valid, it is missing from genesis file")

ErrPublicKeyNotFoundInGenesis signals an error when the public key is not in genesis file

var ErrShardIdOutOfRange = errors.New("shard id out of range")

ErrShardIdOutOfRange signals an error when shard id is out of range

var ErrSmallMetachainEligibleListSize = errors.New("small metachain eligible list size")

ErrSmallMetachainEligibleListSize signals that the eligible validators list's size is less than the consensus size

var ErrSmallShardEligibleListSize = errors.New("small shard eligible list size")

ErrSmallShardEligibleListSize signals that the eligible validators list's size is less than the consensus size

var ErrValidatorNotFound = errors.New("validator not found")

ErrValidatorNotFound signals that the validator has not been found

Functions

func NewIndexHashedNodesCoordinator

func NewIndexHashedNodesCoordinator(
	shardConsensusGroupSize int,
	metaConsensusGroupSize int,
	hasher hashing.Hasher,
	shardId uint32,
	nbShards uint32,
	nodes map[uint32][]Validator,
) (*indexHashedNodesCoordinator, error)

NewIndexHashedNodesCoordinator creates a new index hashed group selector

func NewMultiShardCoordinator

func NewMultiShardCoordinator(numberOfShards, selfId uint32) (*multiShardCoordinator, error)

NewMultiShardCoordinator returns a new multiShardCoordinator and initializes the masks

func NewValidator

func NewValidator(stake *big.Int, rating int32, pubKey []byte, address []byte) (*validator, error)

NewValidator creates a new instance of a validator

Types

type Coordinator

type Coordinator interface {
	NumberOfShards() uint32
	ComputeId(address state.AddressContainer) uint32
	SelfId() uint32
	SameShard(firstAddress, secondAddress state.AddressContainer) bool
	CommunicationIdentifier(destShardID uint32) string
	IsInterfaceNil() bool
}

Coordinator defines what a shard state coordinator should hold

type Genesis

type Genesis struct {
	InitialBalances []*InitialBalance `json:"initialBalances"`
}

Genesis hold data for decoded data from json file

func NewGenesisConfig

func NewGenesisConfig(genesisFilePath string) (*Genesis, error)

NewGenesisConfig creates a new decoded genesis structure from json config file

func (*Genesis) InitialNodesBalances

func (g *Genesis) InitialNodesBalances(shardCoordinator Coordinator, adrConv state.AddressConverter) (map[string]*big.Int, error)

InitialNodesBalances - gets the initial balances of the nodes

type InitialBalance

type InitialBalance struct {
	PubKey  string `json:"pubkey"`
	Balance string `json:"balance"`
	// contains filtered or unexported fields
}

InitialBalance holds data from json and decoded data from genesis process

type InitialNode

type InitialNode struct {
	PubKey  string `json:"pubkey"`
	Address string `json:"address"`
	NodeInfo
}

InitialNode holds data from json

type NodeInfo

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

NodeInfo holds node info

func (*NodeInfo) Address

func (ni *NodeInfo) Address() []byte

Address gets the node address

func (*NodeInfo) AssignedShard

func (ni *NodeInfo) AssignedShard() uint32

AssignedShard gets the node assigned shard

func (*NodeInfo) PubKey

func (ni *NodeInfo) PubKey() []byte

PubKey gets the node public key

type NodesCoordinator

type NodesCoordinator interface {
	PublicKeysSelector
	SetNodesPerShards(nodes map[uint32][]Validator) error
	ComputeValidatorsGroup(randomness []byte, round uint64, shardId uint32) (validatorsGroup []Validator, err error)
	GetValidatorWithPublicKey(publicKey []byte) (validator Validator, shardId uint32, err error)
	IsInterfaceNil() bool
}

NodesCoordinator defines the behaviour of a struct able to do validator group selection

type NodesSetup

type NodesSetup struct {
	StartTime          int64  `json:"startTime"`
	RoundDuration      uint64 `json:"roundDuration"`
	ConsensusGroupSize uint32 `json:"consensusGroupSize"`
	MinNodesPerShard   uint32 `json:"minNodesPerShard"`

	MetaChainConsensusGroupSize uint32 `json:"metaChainConsensusGroupSize"`
	MetaChainMinNodes           uint32 `json:"metaChainMinNodes"`

	InitialNodes []*InitialNode `json:"initialNodes"`
	// contains filtered or unexported fields
}

NodesSetup hold data for decoded data from json file

func NewNodesSetup

func NewNodesSetup(nodesFilePath string, numOfNodes uint64) (*NodesSetup, error)

NewNodesSetup creates a new decoded nodes structure from json config file

func (*NodesSetup) GetShardIDForPubKey

func (ns *NodesSetup) GetShardIDForPubKey(pubKey []byte) (uint32, error)

GetShardIDForPubKey returns the allocated shard ID from public key

func (*NodesSetup) InitialNodesInfo

func (ns *NodesSetup) InitialNodesInfo() map[uint32][]*NodeInfo

InitialNodesInfo - gets initial nodes info

func (*NodesSetup) InitialNodesInfoForShard

func (ns *NodesSetup) InitialNodesInfoForShard(shardId uint32) ([]*NodeInfo, error)

InitialNodesInfoForShard - gets initial nodes info for shard

func (*NodesSetup) InitialNodesPubKeys

func (ns *NodesSetup) InitialNodesPubKeys() map[uint32][]string

InitialNodesPubKeys - gets initial nodes public keys

func (*NodesSetup) InitialNodesPubKeysForShard

func (ns *NodesSetup) InitialNodesPubKeysForShard(shardId uint32) ([]string, error)

InitialNodesPubKeysForShard - gets initial nodes public keys for shard

func (*NodesSetup) NumberOfShards

func (ns *NodesSetup) NumberOfShards() uint32

NumberOfShards returns the calculated number of shards

type OneShardCoordinator

type OneShardCoordinator struct{}

OneShardCoordinator creates a shard coordinator object

func (*OneShardCoordinator) CommunicationIdentifier

func (osc *OneShardCoordinator) CommunicationIdentifier(destShardID uint32) string

CommunicationIdentifier returns the identifier between current shard ID and destination shard ID for this implementation, it will always return "_0" as there is a single shard

func (*OneShardCoordinator) ComputeId

func (osc *OneShardCoordinator) ComputeId(address state.AddressContainer) uint32

ComputeId gets shard for the given address

func (*OneShardCoordinator) IsInterfaceNil

func (osc *OneShardCoordinator) IsInterfaceNil() bool

IsInterfaceNil returns true if there is no value under the interface

func (*OneShardCoordinator) NumberOfShards

func (osc *OneShardCoordinator) NumberOfShards() uint32

NumberOfShards gets number of shards

func (*OneShardCoordinator) SameShard

func (osc *OneShardCoordinator) SameShard(firstAddress, secondAddress state.AddressContainer) bool

SameShard returns weather two addresses belong to the same shard

func (*OneShardCoordinator) SelfId

func (osc *OneShardCoordinator) SelfId() uint32

SelfId gets shard of the current node

type PublicKeysSelector

type PublicKeysSelector interface {
	GetValidatorsIndexes(publicKeys []string) []uint64
	GetAllValidatorsPublicKeys() map[uint32][][]byte
	GetSelectedPublicKeys(selection []byte, shardId uint32) (publicKeys []string, err error)
	GetValidatorsPublicKeys(randomness []byte, round uint64, shardId uint32) ([]string, error)
	GetValidatorsRewardsAddresses(randomness []byte, round uint64, shardId uint32) ([]string, error)
}

PublicKeysSelector allows retrieval of eligible validators public keys

type Validator

type Validator interface {
	Stake() *big.Int
	Rating() int32
	PubKey() []byte
	Address() []byte
}

Validator defines a node that can be allocated to a shard for participation in a consensus group as validator or block proposer