swell

package
v0.0.0-...-69f1810 Latest Latest
Warning

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

 Go to latest Published: Feb 9, 2024 License: Apache-2.0 Imports: 18 Imported by: 0

README

SWELL

Swell protocol defines the rules that a given set of validating nodes must follow to mint a given number of blocks and define the new pool of validating nodes responsible for minting

** Definition

A token is a public key associated to a Ed25518 Elliptic-curve cryptography

A node is a piece software running on a resolvable address that communicates with other nodes and (optionally) to external servers assciated to a token. All messages send from a node to its peers is signed against this token.

** PARAMETERS

W = Number of blocks minted within a checksum window
T = Time interval between blocks
P = Number of slots for nodes in the checksum window. A node can be granted more
    than one spot. W must be divisble by P
C = Numer of slots for nodes in a consesus pool. A noda can be granted more than
    one spot.

----+----+----+----+----+----+----+----+====+====+====+====+xxxx+----+----+----+
              |                        |                   |    |
              checksum             checkpoint N            |    checksum 
              window N         checksum for the state      |    window N +1
                              at end of the checkpoint     | 
                              block must be calculated.    |
                                                           |
                                                    last block for
                                                      publishing 
                                                    naked checksum

Epoch 0 is the epoch of a genesis block that defines the initial state of the network.

The first checksum window

Documentation

Index

Constants

View Source 
const BlockInterval = time.Second
View Source 
const CandidateMsg byte = 200

Variables

This section is empty.

Functions

func BroadcastPercolationRule 

func BroadcastPercolationRule(nodecount int) socket.PercolationRule

func ConnectRandomValidator 

func ConnectRandomValidator(hostname string, credentials crypto.PrivateKey, validators []socket.TokenAddr) *socket.SignedConnection

func ConnectToTrustedGateway 

func ConnectToTrustedGateway(ctx context.Context, config ValidatorConfig) error

func FullSyncValidatorNode 

func FullSyncValidatorNode(ctx context.Context, config ValidatorConfig, sync socket.TokenAddr, standby chan *StandByNode) error

FullSyncValidatorNode tries to gather information from a given validator to form a new non-validating node. This is used to bootstrap a new node from scratch. A standy node just keep in sync with the network and cannot be a candidate to participate in consensus. Standby nodes have no relay and no admin interface.

func NewGenesisNode 

func NewGenesisNode(ctx context.Context, wallet crypto.PrivateKey, config ValidatorConfig)

NewGenesisNode creates a new blockchain from genesis state (associated to the given wallet), and starts a validating node interacting with the given relay network.

func ParseCommitee 

func ParseCommitee(bytes []byte) ([]crypto.Token, []socket.TokenAddr)

func ReadMessages 

func ReadMessages(cancel context.CancelFunc, conn ReaderShutdowner) chan *chain.SealedBlock

ReadMessages reads block event from the provided connection and returns a channel for new sealed blocks derived from those events. The go-routine terminates either by the context, if there is an error on the connection or if it receives a MsgSyncError message (which is uses by the validator on the other side of the connection to tell that it is not capable of providing the requested information).

func RetrieveBlock 

func RetrieveBlock(epoch uint64, hash crypto.Hash, order []*socket.BufferedMultiChannel) chan *chain.SealedBlock

RetriveBlock is called by a validator that is not in posession of a block compatible with the bft consensus hash. It will try to retrive such block from other nodes in the sequence given by the order parameter. It returns a channel to a selaed block. TODO: it does nothing when the block is not found.

func RunNonValidatorNode 

func RunNonValidatorNode(w *Window, conn *socket.SignedConnection, candidate bool)

RunNonValidatingNode engine runs the underlying swell node as a non validating node. This means that it is receiving block events from a connection to a relay network from one or more validators. If candidate is true the node will try to become a validator for the next window. The responsability for the permission to become a validator is left to the holder of the node credentials.

func RunReplicaWindow 

func RunReplicaWindow(ctx context.Context, w *Window, finished chan uint64) chan *chain.SealedBlock

func RunValidator 

func RunValidator(c *Window)

Node must be a member of Committee. It starts the execution of the block formation for the window. RunValidatingNode engine runs the underlying swell node as a validating node. This means that it is receiving blocks throught the gossip network of validators and at those assigned epochs joins the consensus committes over the hash of the block. Honest validators should have a relay network somewhat open so that others can send actions to the node and listen to newly minted blocks.

Types

type BlockConsensusConfirmation 

type BlockConsensusConfirmation struct {
	Epoch  uint64
	Status bool
}

type CandidateStatus 

type CandidateStatus struct {
	Dressed bool
	Naked   bool
}

type ChecksumWindowValidators 

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

ChecksumWindowValidators defines the order of tokens for the current checksum window and the weight of each token.

type Committee 

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

func LaunchValidatorPool 

func LaunchValidatorPool(ctx context.Context, validators []socket.TokenAddr, credentials crypto.PrivateKey, hostname string) *Committee

func SingleCommittee 

func SingleCommittee(credentials crypto.PrivateKey, hostname string) *Committee

func (*Committee) PrepareNext 

func (v *Committee) PrepareNext(validators []socket.TokenAddr) *Committee

func (*Committee) Serialize 

func (c *Committee) Serialize() []byte

type Permission 

type Permission interface {
	Punish(duplicates *bft.Duplicate, weights map[crypto.Token]int) map[crypto.Token]uint64
	DeterminePool(chain *chain.Blockchain, candidates []crypto.Token) map[crypto.Token]int
}

Permission is an interface that defines the rules for a validator

type ReaderShutdowner 

type ReaderShutdowner interface {
	Read() ([]byte, error)
	Shutdown()
}

type StandByNode 

type StandByNode struct {
	Blockchain *chain.Blockchain

	LastEvents *util.Await
	// contains filtered or unexported fields
}

func RunReplicaNode 

func RunReplicaNode(w *Window, conn *socket.SignedConnection) *StandByNode

type SwellNetworkConfiguration 

type SwellNetworkConfiguration struct {
	NetworkHash      crypto.Hash   // there should be a unique hash for each network
	MaxPoolSize      int           // max number of validator in each hash consensus pool
	MaxCommitteeSize int           // max number of validators in the checksum window
	BlockInterval    time.Duration // time duration for each block
	ChecksumWindow   int           // number of blocks in the checksum window
	Permission       Permission    // permission rules to be a validator in the network
}

SwellNetrworkConfiguration defines the parameters for the unerlying crypto network running the swell protocol.

type SwellNode 

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

SwellNode is the basic structure to run a swell node either as a validator, as a candidate validator or simplu as an iddle observer. the internal clock of the node is used to determine the current epoch of the breeze network. It can be optionally linked to a relay node to communicate with the ouside world. Relay network is used to gather proposed actions through the actions gateway and to send block events to other interested parties. Honest validator must keep the relay network open with and adequate firewall rule. Swell protocol does not dictate rules for the realy network nonetheless.

func (*SwellNode) AdminReport 

func (s *SwellNode) AdminReport() string

func (*SwellNode) PurgeAction 

func (s *SwellNode) PurgeAction(hash crypto.Hash)

Permanently exlude action from the underluing action store.

func (*SwellNode) PurgeActions 

func (s *SwellNode) PurgeActions(actions *chain.ActionArray)

func (*SwellNode) ServeAdmin 

func (s *SwellNode) ServeAdmin(ctx context.Context)

func (*SwellNode) TimeStampBlock 

func (s *SwellNode) TimeStampBlock(epoch uint64) time.Time

func (*SwellNode) Timer 

func (s *SwellNode) Timer(epoch uint64) *time.Timer

type TokenHash 

type TokenHash struct {
	Token crypto.Token
	Hash  crypto.Hash
}

type TokenHashArray 

type TokenHashArray []TokenHash

func (TokenHashArray) Len 

func (h TokenHashArray) Len() int

func (TokenHashArray) Less 

func (h TokenHashArray) Less(i, j int) bool

func (TokenHashArray) Swap 

func (h TokenHashArray) Swap(i, j int)

type ValidatorConfig 

type ValidatorConfig struct {
	Credentials crypto.PrivateKey
	WalletPath  string
	SwellConfig SwellNetworkConfiguration
	//Actions        *store.ActionStore
	Relay          *relay.Node
	Admin          *admin.Administration
	Hostname       string
	TrustedGateway []socket.TokenAddr
}

ValidatorConfig defines the configuration for a validator node.

type Window 

type Window struct {
	Start     uint64
	End       uint64
	Committee *Committee
	Node      *SwellNode
	// contains filtered or unexported fields
}

Window is a given sequence of blocks from Start to End under responsability of the Committee to produce blocks for the SwellNode instance

func (*Window) AddSealedBlock 

func (w *Window) AddSealedBlock(sealed *chain.SealedBlock)

AddSealedBlock incorporates a sealed block into the node's blockchain.

func (*Window) BuildBlock 

func (w *Window) BuildBlock(epoch uint64, pool *bft.Pooling) bool

BuildBlock build a new block according to the available state of the swell node at the calling of this method. The block is broadcasted to the gossip network and the pool consensus committee is launched. Once terminated the node cast a proposal for the given hash on the pool network.

func (*Window) BuildSoloBLock 

func (w *Window) BuildSoloBLock(epoch uint64) bool

BuildSoloBLock builds a block in the case where the node is the sole partipant in the validating network. In this case all the extra burden can be eliminated and the node can build, seal, commit and broadcast a block in a single step.

func (*Window) CanPrepareNextWindow 

func (w *Window) CanPrepareNextWindow() bool

func (Window) CanPublishStatement 

func (c Window) CanPublishStatement(epoch uint64) bool

func (*Window) DressedChecksumStatement 

func (w *Window) DressedChecksumStatement(epoch uint64) *chain.ChecksumStatement

func (*Window) Finished 

func (w *Window) Finished() bool

func (*Window) IsPoolMember 

func (w *Window) IsPoolMember(epoch uint64) bool

IsPoolMember returns true if the node is a member of the current consensus committe for the given epoch.

func (*Window) ListenToBlock 

func (w *Window) ListenToBlock(leader *socket.BufferedMultiChannel, others []*socket.BufferedMultiChannel, pool *bft.Pooling) bool

ListenToBlock listens to the block events from the gossip network and upon receiving a swal informs the pool consensus committee about the hash of the proposed block. If the pool returns a valid consensus the block is added as a sealed block to the node. In case the swell node is not in posession of a block with the consensus hash it tries to get that block from other nodes of the gossip network.

func (*Window) NakedChecksumWindow 

func (w *Window) NakedChecksumWindow(epoch uint64) *chain.ChecksumStatement

func (*Window) PrepareNewWindow 

func (w *Window) PrepareNewWindow()

func (*Window) RunEpoch 

func (w *Window) RunEpoch(epoch uint64)

Node keeps forming blocks either proposing its own blocks or validating others nodes proposals. In due time node re-arranges validator pool. Uppon exclusion a node can transition to a listener node.

func (*Window) StartNewBlock 

func (w *Window) StartNewBlock(epoch uint64) *chain.BlockBuilder

type WindowWithValidators 

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

type WindowWithWorker 

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

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.