typesutil

README

Typesutils

The typesutils package provides helper methods for working with transactions, especially during testing and debugging.

Subsystems

Typesutils has the following subsystems:

• Minimum Transaction Set
• Transaction Graph

Minimum Transaction Set

Key Files

• minimumtransactionsetexports.go

The minimum transaction set function takes two transaction sets as input. The first is a set of required transactions (often just one transaction), and the second is a set of transactions that may be required dependencies. The function will return a single transaction set which contains all of the required transactions and all of their direct/required dependencies, and no other transactions.

It is fine for the two input sets to contain overlapping transactions, however each set much be independently ordered correctly and valid.

Exports

• MinimizeTransactionSet is an independent function which returns a transaction set that contains all transactions of its first input plus any required dependencies from its second input.

Transaction Graph

Key Files

• transactiongraphexports.go

The Transaction Graph is a tool for building sets of transactions that have specific properties. This can be useful for testing modules such as the transaction pool to see how the transaction pool responds to certain dependency graphs or fee structures. The goal of the transaction graph is to be a much simpler method for constructing elaborate transaction setups vs. constructing these setups by hand.

Note: With the exception of one struct, all of the code in the transaction graph subsystem is exported.

Exports

• SimpleTransaction is an outline of a transaction that should be added to the transaction graph. It has the same field names as a types.Transaction, however they have been greatly simplified to make building transactions easier.
• TransactionGraph is the stateful object that can be used to incrementally build an elaborate transaction graph.
  • TransactionGraph.AddSiacoinSource is a method that allows a source input to be added to the transaction graph. The transactions in the graph will only be valid if they have some base input consisting of pre-existing siacoins, and this method allows the caller to supply such an input. This method can be used as many times as necessary. This method will return an index that tells you how to spend the output within the transaction graph.
  • TransactionGraph.AddTransaction will take a simple transaction as input and compose it into a full, valid transaction within the graph. Basic checking is also performed to ensure that all inputs are valid, and that the input totals match the output totals for the final transaction.
  • TransactionGraph.Transactions will return all of the transactions that have been built to be a part of the transaction graph.
• NewTransactionGraph will initialize and return a TransactionGraph.

Documentation

Index

• Variables
• func MinimumTransactionSet(requiredTxns []types.Transaction, relatedTxns []types.Transaction) []types.Transaction
• func SprintTxnWithObjectIDs(t types.Transaction) string
• type SimpleTransaction
• type TransactionGraph
  • func NewTransactionGraph() *TransactionGraph
  • func (tg *TransactionGraph) AddSiacoinSource(scoid types.SiacoinOutputID, value types.Currency) (int, error)
  • func (tg *TransactionGraph) AddTransaction(st SimpleTransaction) (newSiacoinInputs []int, err error)
  • func (tg *TransactionGraph) Transactions() []types.Transaction

Variables

var (
	// ErrSiacoinSourceAlreadyAdded is the error returned when a user tries to
	// provide the same source siacoin input multiple times.
	ErrSiacoinSourceAlreadyAdded = errors.New("source siacoin input has already been used")

	// ErrSiacoinInputAlreadyUsed warns a user that a siacoin input has already
	// been used in the transaction graph.
	ErrSiacoinInputAlreadyUsed = errors.New("cannot use the same siacoin input twice in a graph")

	// ErrNoSuchSiacoinInput warns a user that they are trying to reference a
	// siacoin input which does not yet exist.
	ErrNoSuchSiacoinInput = errors.New("no siacoin input exists with that index")

	// ErrSiacoinInputsOutputsMismatch warns a user that they have constructed a
	// transaction which does not spend the same amount of siacoins that it
	// consumes.
	ErrSiacoinInputsOutputsMismatch = errors.New("siacoin input value to transaction does not match siacoin output value of transaction")
)

var (
	// AnyoneCanSpendUnlockHash is the unlock hash of unlock conditions that are
	// trivially spendable.
	AnyoneCanSpendUnlockHash types.UnlockHash = types.UnlockConditions{}.UnlockHash()
)

Functions

func MinimumTransactionSet

func MinimumTransactionSet(requiredTxns []types.Transaction, relatedTxns []types.Transaction) []types.Transaction

MinimumTransactionSet takes two transaction sets as input and returns a combined transaction set. The first input is the set of required transactions, which the caller is indicating must all be a part of the final set.The second input is a set of related transactions that the caller believes may contain parent transactions of the required transactions. MinimumCombinedSet will scan through the related transactions and pull in any which are required parents of the required transactions, returning the final result.

The final transaction set which gets returned will contain all of the required transactions, and will contain any of the related transactions which are necessary for the required transactions to be confirmed.

NOTE: Both of the inputs are proper transaction sets. A proper transaction set is already sorted so that no parent comes after a child in the array.

func SprintTxnWithObjectIDs

func SprintTxnWithObjectIDs(t types.Transaction) string

SprintTxnWithObjectIDs creates a string representing this Transaction in human-readable form with all object IDs included to allow for easy dependency matching (by humans) in debug-logs.

Types

type SimpleTransaction

type SimpleTransaction struct {
	SiacoinInputs  []int            // Which inputs to use, by index.
	SiacoinOutputs []types.Currency // The values of each output.

	MinerFees []types.Currency // The fees used.

}

SimpleTransaction specifies what outputs it spends, and what outputs it creates, by index. When passed in TransactionGraph, it will be automatically transformed into a valid transaction.

Currently, there is only support for SiacoinInputs, SiacoinOutputs, and MinerFees, however the code has been structured so that support for Siafunds and FileContracts can be easily added in the future.

type TransactionGraph

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

TransactionGraph is a helper tool to allow a user to easily construct elaborate transaction graphs. The transaction tool will handle creating valid transactions, providing the user with a clean interface for building transactions.

func NewTransactionGraph

func NewTransactionGraph() *TransactionGraph

NewTransactionGraph will return a blank transaction graph that is ready for use.

func (*TransactionGraph) AddSiacoinSource

func (tg *TransactionGraph) AddSiacoinSource(scoid types.SiacoinOutputID, value types.Currency) (int, error)

AddSiacoinSource will add a new source of siacoins to the transaction graph, returning the index that this source can be referenced by. The provided output must have the address AnyoneCanSpendUnlockHash.

The value is used as an input so that the graph can check whether all transactions are spending as many siacoins as they create.

func (*TransactionGraph) AddTransaction

func (tg *TransactionGraph) AddTransaction(st SimpleTransaction) (newSiacoinInputs []int, err error)

AddTransaction will add a new transaction to the transaction graph, following the guide of the input. The indexes of all the outputs created will be returned.

func (*TransactionGraph) Transactions

func (tg *TransactionGraph) Transactions() []types.Transaction

Transactions will return the transactions that were built up in the graph.