proposals

README

Proposals

Overview

The proposal type - proposals.Proposal - is utilized to represent a block proposal. It contains information about the total gas utilization, block size, number of transactions, raw transactions, and much more. It is recommended that you read the proposal construction and verification section before continuing.

Proposal

After a given lane executes its PrepareLaneHandler or ProcessLaneHandler, it will return a set of transactions that need to be added to the current proposal that is being constructed. To update the proposal, Update is called with the lane that needs to add transactions to the proposal as well as the transactions that need to be added.

Proposals are updated iff:

1. The total gas utilization of the partial proposal (i.e. the transactions it wants to add) are under the limits allocated for the lane and are less than the maximum gas utilization of the proposal.
2. The total size in bytes of the partial proposal is under the limits allocated for the lane and is less than the maximum size of the proposal.
3. The transactions have not already been added to the proposal.
4. The lane has not already attempted to add transactions to the proposal.

If any of these conditions fail, the proposal will not be updated and the transactions will not be added to the proposal. The lane will be marked as having attempted to add transactions to the proposal.

The proposal is responsible for determining the LaneLimits for a given lane. The LaneLimits are the maximum gas utilization and size in bytes that a given lane can utilize in a block proposal. This is a function of the max gas utilization and size defined by the application, the current gas utilization and size of the proposal, and the MaxBlockSpace allocated to the lane as defined by its LaneConfig. To read more about how LaneConfigs are defined, please visit the lane config section or see an example implementation in app.go.

Documentation

Index

• Constants
• func GetBlockLimits(ctx sdk.Context) (int64, uint64)
• type Lane
• type LaneLimits
• type Proposal
  • func NewProposal(logger log.Logger, maxBlockSize int64, maxGasLimit uint64) Proposal
  • func NewProposalWithContext(ctx sdk.Context, logger log.Logger) Proposal
  • func (p *Proposal) Contains(txHash string) bool
  • func (p *Proposal) GetLaneLimits(ratio math.LegacyDec) LaneLimits
  • func (p *Proposal) GetProposalWithInfo() ([][]byte, error)
  • func (p *Proposal) UpdateProposal(lane Lane, partialProposal []utils.TxWithInfo) error

Constants

const (
	// MaxUint64 is the maximum value of a uint64.
	MaxUint64 = 1<<64 - 1
)

Functions

func GetBlockLimits

func GetBlockLimits(ctx sdk.Context) (int64, uint64)

GetBlockLimits retrieves the maximum number of bytes and gas limit allowed in a block.

Types

type Lane

type Lane interface {
	Name() string
	GetMaxBlockSpace() math.LegacyDec
}

Lane defines the contract interface for a lane.

type LaneLimits

type LaneLimits struct {
	// MaxTxBytes is the maximum number of bytes allowed in the partial proposal.
	MaxTxBytes int64
	// MaxGasLimit is the maximum gas limit allowed in the partial proposal.
	MaxGasLimit uint64
}

LaneLimits defines the constraints for a partial proposal. Each lane must only propose transactions that satisfy these constraints. Otherwise, the partial proposal update will be rejected.

type Proposal

type Proposal struct {
	Logger log.Logger

	// Txs is the list of transactions in the proposal.
	Txs [][]byte
	// Cache is a cache of the selected transactions in the proposal.
	Cache map[string]struct{}
	// Info contains information about the state of the proposal.
	Info types.ProposalInfo
}

Proposal defines a block proposal type.

func NewProposal

func NewProposal(logger log.Logger, maxBlockSize int64, maxGasLimit uint64) Proposal

NewProposal returns a new empty proposal. Any transactions added to the proposal will be subject to the given max block size and max gas limit.

func NewProposalWithContext

func NewProposalWithContext(ctx sdk.Context, logger log.Logger) Proposal

NewProposalWithContext returns a new empty proposal.

func (*Proposal) Contains

func (p *Proposal) Contains(txHash string) bool

Contains returns true if the proposal contains the given transaction.

func (*Proposal) GetLaneLimits

func (p *Proposal) GetLaneLimits(ratio math.LegacyDec) LaneLimits

GetLaneLimits returns the maximum number of bytes and gas limit that can be included/consumed in the proposal for the given block space ratio. Lane's must first call this function to determine the maximum number of bytes and gas limit they can include in the proposal before constructing a partial proposal.

func (*Proposal) GetProposalWithInfo

func (p *Proposal) GetProposalWithInfo() ([][]byte, error)

GetProposalWithInfo returns all of the transactions in the proposal along with information about the lanes that built the proposal.

NOTE: This is currently not used in production but likely will be once ABCI 3.0 is released.

func (*Proposal) UpdateProposal

func (p *Proposal) UpdateProposal(lane Lane, partialProposal []utils.TxWithInfo) error

UpdateProposal updates the proposal with the given transactions and lane limits. There are a few invariants that are checked:

1. The total size of the proposal must be less than the maximum number of bytes allowed.
2. The total size of the partial proposal must be less than the maximum number of bytes allowed for the lane.
3. The total gas limit of the proposal must be less than the maximum gas limit allowed.
4. The total gas limit of the partial proposal must be less than the maximum gas limit allowed for the lane.
5. The lane must not have already prepared a partial proposal.
6. The transaction must not already be in the proposal.