ist

Documentation

Overview

Package ist provides the Internal State Transition (IST) mechanism for Vochain. The IST is responsible for modifying the Vochain's state based on actions scheduled to be executed at specific heights. This ensures accurate, tamper-proof results through consensus among nodes.

The Internal State Transition Controller (ISTC) is the main component of this package. It schedules and executes IST actions at specified heights. Actions include computing results, committing results, and ending processes.

The package contains the following types:

- Controller: the IST controller. - Actions: a model to store the list of IST actions for a specific height. - Action: a model to store the IST actions.

IST actions are encoded and decoded using the Gob encoding package. The encoding and decoding functions are provided by the Actions type.

The Controller struct provides methods for scheduling, rescheduling, and committing IST actions. When committing an action, it performs the necessary operations depending on the type of action, such as computing results, committing results, or ending processes. It also provides methods to store and retrieve data from the no-state, which is a separate key-value store that holds non-consensus-critical data.

Constants used in the package are:

- BlocksToWaitForResultsFactor: a factor used to compute the height at which the results will be committed to the state. - ExtraWaitSecondsForResults: the number of extra seconds to wait for results.

Technical decisions taken in the code include:

- Implementing a separate no-state key-value store for non-consensus-critical data storage. - Computing results in a separate goroutine to avoid blocking state transitions. - Including a mechanism for rescheduling actions in case of missing keys or other issues.

Index

• Constants
• Variables
• type Action
• type ActionID
• type Actions
• type Controller
  • func NewISTC(s *state.State) *Controller
  • func (c *Controller) Actions(height uint32) (Actions, error)
  • func (c *Controller) Commit(height uint32) error
  • func (c *Controller) Reschedule(id []byte, oldHeight, newHeight uint32) error
  • func (c *Controller) Schedule(height uint32, id []byte, action Action) error

Constants

const (
	// BlocksToWaitForResults is the factor used to compute the
	// height at which the results will be committed to the state.
	// Note that changing this factor might break consensus and backwards
	// compatibility.
	BlocksToWaitForResults = 2
)

Variables

var ActionsToString = map[ActionID]string{
	ActionCommitResults:        "commit-results",
	ActionEndProcess:           "end-process",
	ActionUpdateValidatorScore: "update-validator-score",
}

ActionsToString translates the action identifiers to its corresponding human friendly string.

Types

type Action

type Action struct {
	ID                ActionID
	ElectionID        []byte
	Attempts          uint32
	ValidatorVotes    [][]byte
	ValidatorProposer []byte
}

Action is the model used to store the IST actions into state.

type ActionID

type ActionID int32

ActionID is the type used to identify the IST actions.

const (
	// ActionCommitResults schedules the commit of the results to the state.
	ActionCommitResults ActionID = iota
	// ActionEndProcess sets a process as ended. It schedules ActionComputeResults.
	ActionEndProcess
	// ActionUpdateValidatorScore updates the validator score (votes and proposer) in the state.
	ActionUpdateValidatorScore
)

type Actions

type Actions map[string]Action

Actions is the model used to store the list of IST actions for a specific height into state.

type Controller

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

Controller is the internal state transition controller.

func NewISTC

func NewISTC(s *state.State) *Controller

NewISTC creates a new ISTC. The ISTC is the controller of the internal state transitions. It schedule actions to be executed at a specific height that will modify the state.

func (*Controller) Actions

func (c *Controller) Actions(height uint32) (Actions, error)

Actions returns the IST actions scheduled for the given height. If no actions are scheduled, it returns an empty IstActions.

func (*Controller) Commit

func (c *Controller) Commit(height uint32) error

Commit executes the IST actions scheduled for the given height.

func (*Controller) Reschedule

func (c *Controller) Reschedule(id []byte, oldHeight, newHeight uint32) error

Reschedule reschedules an IST action to the given new height.

func (*Controller) Schedule

func (c *Controller) Schedule(height uint32, id []byte, action Action) error

Schedule schedules an IST action to be executed at the given height.