attacher

README

The package attacher contains core functions dedicated to the construction of the UTXO tangle.

Each transaction if first parsed and then is attached to the UTXO tangle. The attachment process means solidification of the past cone of the transactions and checking validity of it:

• Solidification: making sure all transactions in the past cone are valid
• Determining the baseline of the sequencer transaction: solidification of the whole transaction path which leads to the baseline branch
• Transaction is solid when it is rooted (with terminal outputs belonging to the ledger state):
  • in the baseline branch for sequencer transactions
  • in any branch for non-sequencer transactions
• Each transaction is validated by running all validation scripts for all outputs (consumed/inputs and produced ones) upon solidification
• Each sequencer transaction is checked for absence of conflicts (double_spends) in the past cone in the context of the baseline state.
• Each non-sequencer transaction is checked for absence of conflict in the past cone when tagged-along a particular sequencer transaction
• Sequencer transaction is GOOD when it is solid, validated and does not contain conflicts in the past cone, otherwise it is marked BAD
• Solid and validated non-sequencer transaction is always UNDEFINED, otherwise it is BAD

The construction of the UTXO tangle is highly parallel. Each sequencer transaction is attached by separate goroutine: the attacher.

The milestone attacher handles all main tasks of the sequencer transaction: pulls missing inputs from other nodes, determines baseline, validates the output scripts.

The milestone attacher finishes the task and leaves go routine by:

• marking sequencer transaction as GOOD
• marking sequencer transaction as BAD
• persisting the ledger state into the DB for GOOD branch transactions
• leaving with BAD in case of solidification timeout or global shutdown

The incremental attacher is a utility for the sequencer. It allows construction of the past cone by incrementally adding consumed and endorsed inputs and controlling consistency of the past cone.

Documentation

Index

• Constants
• Variables
• func AttachOutputID(oid ledger.OutputID, env Environment, opts ...AttachTxOption) vertex.WrappedOutput
• func AttachOutputWithID(o *ledger.OutputWithID, env Environment, opts ...AttachTxOption) (vertex.WrappedOutput, error)
• func AttachTransaction(tx *transaction.Transaction, env Environment, opts ...AttachTxOption) (vid *vertex.WrappedTx)
• func AttachTransactionFromBytes(txBytes []byte, env Environment, opts ...AttachTxOption) (*vertex.WrappedTx, error)
• func AttachTxID(txid ledger.TransactionID, env Environment, opts ...AttachTxOption) (vid *vertex.WrappedTx)
• func InvalidateTxID(txid ledger.TransactionID, env Environment, reason error) *vertex.WrappedTx
• func WithEnforceTimestampBeforeRealTime(options *_attacherOptions)
• type AttachTxOption
  • func WithAttachmentCallback(fun func(vid *vertex.WrappedTx, err error)) AttachTxOption
  • func WithAttachmentDepth(depth int) AttachTxOption
  • func WithContext(ctx context.Context) AttachTxOption
  • func WithInvokedBy(name string) AttachTxOption
  • func WithTransactionMetadata(metadata *txmetadata.TransactionMetadata) AttachTxOption
• type Environment
• type Flags
  • func (f Flags) FlagsUp(fl Flags) bool
  • func (f Flags) String() string
• type IncrementalAttacher
  • func NewIncrementalAttacher(name string, env Environment, targetTs ledger.Time, ...) (*IncrementalAttacher, error)
  • func (a *IncrementalAttacher) AccumulatedCoverage() uint64
  • func (a *IncrementalAttacher) AdjustCoverage()
  • func (a *IncrementalAttacher) BaselineBranch() *vertex.WrappedTx
  • func (a *IncrementalAttacher) Close()
  • func (a *IncrementalAttacher) Completed() bool
  • func (a *IncrementalAttacher) Endorsing() []*vertex.WrappedTx
  • func (a *IncrementalAttacher) Extending() vertex.WrappedOutput
  • func (a *IncrementalAttacher) FinalSupply() uint64
  • func (a *IncrementalAttacher) InsertEndorsement(endorsement *vertex.WrappedTx) error
  • func (a *IncrementalAttacher) InsertTagAlongInput(wOut vertex.WrappedOutput) (bool, error)
  • func (a *IncrementalAttacher) IsClosed() bool
  • func (a *IncrementalAttacher) IsCoverageAdjusted() bool
  • func (a *IncrementalAttacher) MakeSequencerTransaction(seqName string, privateKey ed25519.PrivateKey, ...) (*transaction.Transaction, error)
  • func (a *IncrementalAttacher) Name() string
  • func (a *IncrementalAttacher) NumInputs() int
  • func (a *IncrementalAttacher) SetTraceAttacher(name string)
  • func (a *IncrementalAttacher) SlotInflation() uint64
  • func (a *IncrementalAttacher) TargetTs() ledger.Time
  • func (a *IncrementalAttacher) Tracef(traceLabel string, format string, args ...any)
• type SequencerCommandParser

Constants

const (
	TraceTagAttach             = "attach"
	TraceTagAttachOutput       = "attachOutput"
	TraceTagAttachVertex       = "attachVertexUnwrapped"
	TraceTagCoverageAdjustment = "adjust"
)

const TraceTagAttachEndorsements = "attachEndorsements"

const (
	TraceTagAttachMilestone = "milestone"
)

const TraceTagIncrementalAttacher = "incAttach"

const TraceTagMarkDefUndef = "markDefUndef"

const TraceTagPull = "pull"

const TraceTagSolidifySequencerBaseline = "seqBase"

Variables

var ErrPastConeNotSolidYet = errors.New("past cone not solid yet")

var ErrSolidificationDeadline = errors.New("solidification deadline")

Functions

func AttachOutputID

func AttachOutputID(oid ledger.OutputID, env Environment, opts ...AttachTxOption) vertex.WrappedOutput

func AttachOutputWithID

func AttachOutputWithID(o *ledger.OutputWithID, env Environment, opts ...AttachTxOption) (vertex.WrappedOutput, error)

func AttachTransaction

func AttachTransaction(tx *transaction.Transaction, env Environment, opts ...AttachTxOption) (vid *vertex.WrappedTx)

AttachTransaction attaches new incoming transaction. For sequencer transaction it starts milestoneAttacher routine which manages solidification pulling until transaction becomes solid or stopped by the context

func AttachTransactionFromBytes

func AttachTransactionFromBytes(txBytes []byte, env Environment, opts ...AttachTxOption) (*vertex.WrappedTx, error)

AttachTransactionFromBytes used for testing

func AttachTxID

func AttachTxID(txid ledger.TransactionID, env Environment, opts ...AttachTxOption) (vid *vertex.WrappedTx)

AttachTxID ensures the txid is on the MemDAG It load existing branches but does not pull anything

func InvalidateTxID

func InvalidateTxID(txid ledger.TransactionID, env Environment, reason error) *vertex.WrappedTx

InvalidateTxID marks existing vertex as BAD or creates new BAD

func WithEnforceTimestampBeforeRealTime

func WithEnforceTimestampBeforeRealTime(options *_attacherOptions)

Types

type AttachTxOption

type AttachTxOption func(*_attacherOptions)

func WithAttachmentCallback

func WithAttachmentCallback(fun func(vid *vertex.WrappedTx, err error)) AttachTxOption

func WithAttachmentDepth

func WithAttachmentDepth(depth int) AttachTxOption

func WithContext

func WithContext(ctx context.Context) AttachTxOption

func WithInvokedBy

func WithInvokedBy(name string) AttachTxOption

func WithTransactionMetadata

func WithTransactionMetadata(metadata *txmetadata.TransactionMetadata) AttachTxOption

type Environment

type Environment interface {
	global.NodeGlobal

	GossipAttachedTransaction(tx *transaction.Transaction, metadata *txmetadata.TransactionMetadata)
	ParseMilestoneData(msVID *vertex.WrappedTx) *ledger.MilestoneData
	// contains filtered or unexported methods
}

type Flags

type Flags uint8

func (Flags) FlagsUp

func (f Flags) FlagsUp(fl Flags) bool

func (Flags) String

func (f Flags) String() string

type IncrementalAttacher

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

IncrementalAttacher is used by the sequencer to build a sequencer milestone transaction by adding new tag-along inputs one-by-one. It ensures the past cone is conflict-free It is used to generate the transaction and after that it is discarded

func NewIncrementalAttacher

func NewIncrementalAttacher(name string, env Environment, targetTs ledger.Time, extend vertex.WrappedOutput, endorse ...*vertex.WrappedTx) (*IncrementalAttacher, error)

func (*IncrementalAttacher) AccumulatedCoverage

func (a *IncrementalAttacher) AccumulatedCoverage() uint64

func (*IncrementalAttacher) AdjustCoverage

func (a *IncrementalAttacher) AdjustCoverage()

func (*IncrementalAttacher) BaselineBranch

func (a *IncrementalAttacher) BaselineBranch() *vertex.WrappedTx

func (*IncrementalAttacher) Close

func (a *IncrementalAttacher) Close()

Close releases all references of vertices. Incremental attacher must be closed before disposing it, otherwise memDAG starts leaking vertices. Repetitive closing has no effect TODO some kind of checking if it is closed after some time

func (*IncrementalAttacher) Completed

func (a *IncrementalAttacher) Completed() bool

Completed returns true is past cone is all solid and consistent (no conflicts) For incremental attacher it may happen (in theory) that some outputs need re-pull, if unlucky. The owner of the attacher will have to dismiss the attacher and try again later

func (*IncrementalAttacher) Endorsing

func (a *IncrementalAttacher) Endorsing() []*vertex.WrappedTx

func (*IncrementalAttacher) Extending

func (a *IncrementalAttacher) Extending() vertex.WrappedOutput

func (*IncrementalAttacher) FinalSupply

func (a *IncrementalAttacher) FinalSupply() uint64

func (*IncrementalAttacher) InsertEndorsement

func (a *IncrementalAttacher) InsertEndorsement(endorsement *vertex.WrappedTx) error

InsertEndorsement preserves consistency in case of failure

func (*IncrementalAttacher) InsertTagAlongInput

func (a *IncrementalAttacher) InsertTagAlongInput(wOut vertex.WrappedOutput) (bool, error)

InsertTagAlongInput inserts tag along input. In case of failure return false and attacher state with vertex references remains consistent

func (*IncrementalAttacher) IsClosed

func (a *IncrementalAttacher) IsClosed() bool

func (*IncrementalAttacher) IsCoverageAdjusted

func (a *IncrementalAttacher) IsCoverageAdjusted() bool

IsCoverageAdjusted for consistency assertions

func (*IncrementalAttacher) MakeSequencerTransaction

func (a *IncrementalAttacher) MakeSequencerTransaction(seqName string, privateKey ed25519.PrivateKey, cmdParser SequencerCommandParser) (*transaction.Transaction, error)

MakeSequencerTransaction creates sequencer transaction from the incremental attacher. Increments slotInflation by the amount inflated in the transaction

func (*IncrementalAttacher) Name

func (a *IncrementalAttacher) Name() string

func (*IncrementalAttacher) NumInputs

func (a *IncrementalAttacher) NumInputs() int

func (*IncrementalAttacher) SetTraceAttacher

func (a *IncrementalAttacher) SetTraceAttacher(name string)

func (*IncrementalAttacher) SlotInflation

func (a *IncrementalAttacher) SlotInflation() uint64

func (*IncrementalAttacher) TargetTs

func (a *IncrementalAttacher) TargetTs() ledger.Time

func (*IncrementalAttacher) Tracef

func (a *IncrementalAttacher) Tracef(traceLabel string, format string, args ...any)

type SequencerCommandParser

type SequencerCommandParser interface {
	// ParseSequencerCommandToOutput analyzes consumed output for sequencer command and produces
	// one or several outputs as an effect of the command. Returns:
	// - nil, nil if a syntactically valid sequencer command is not detected  in the inputs
	// - nil, err if a syntactically valid command can be detected, however it contains errors
	// - list of outputs, nil if it is a success
	ParseSequencerCommandToOutput(input *ledger.OutputWithID) ([]*ledger.Output, error)
}