vmtxbuilder

Documentation

Overview

Package vmtxbuilder implements AnchorTransactionBuilder, a transaction builder used by the VM to construct anchor transaction. The AnchorTransactionBuilder keeps consistent state along operations of adding inputs and adding outputs (`Consume` and `AddOutput`). Total base tokens available to on-chain accounts are kept in the anchor output. The builder automatically maintains `internal` outputs which holds on-chain total balances of native tokens: one UTXO for one non-zero balance of iotago.NativeTokenID. Whenever native tokens are moved to/form the chain, those internal UTXO are updated by consuming input/producing output. The builder automatically ensures necessary minimal storage deposit on each of internal outputs. For this, builder takes base tokens from the total base tokens on the chain or puts them back, depending on the needs of internal outputs. When txbuilder is unable to maintain consistent state, it panics. The following panic code are possible: - ErrProtocolExceptionInputLimitExceeded when maximum number of inputs in the transaction is exceeded - ErrProtocolExceptionOutputLimitExceeded when maximum number of outputs in the transaction is exceeded - ErrProtocolExceptionNumberOfNativeTokensLimitExceeded when number of total different nativeTokenIDs is exceeded - ErrProtocolExceptionNotEnoughFundsForInternalStorageDeposit when total number of base tokens available is not enough for storage deposit of the new internal output - ErrNotEnoughBaseTokensBalance attempt to debit more base tokens than possible - ErrNotEnoughNativeAssetBalance attempt to debit more native tokens than possible - ErrOverflow overflow of arithmetics

Index

• type AccountsContractRead
• type AnchorTransactionBuilder
  • func NewAnchorTransactionBuilder(anchorOutput *iotago.AliasOutput, anchorOutputID iotago.OutputID, ...) *AnchorTransactionBuilder
  • func (txb *AnchorTransactionBuilder) AddOutput(o iotago.Output) int64
  • func (txb *AnchorTransactionBuilder) BuildTransactionEssence(stateMetadata []byte) (*iotago.TransactionEssence, []byte)
  • func (txb *AnchorTransactionBuilder) Clone() *AnchorTransactionBuilder
  • func (txb *AnchorTransactionBuilder) Consume(req isc.OnLedgerRequest) uint64
  • func (txb *AnchorTransactionBuilder) CreateAnchorOutput(stateMetadata []byte) *iotago.AliasOutput
  • func (txb *AnchorTransactionBuilder) CreateNewFoundry(scheme iotago.TokenScheme, metadata []byte) (uint32, uint64)
  • func (txb *AnchorTransactionBuilder) DestroyFoundry(sn uint32) uint64
  • func (txb *AnchorTransactionBuilder) FoundriesToBeUpdated() ([]uint32, []uint32)
  • func (txb *AnchorTransactionBuilder) FoundryOutputsBySN(serNums []uint32) map[uint32]*iotago.FoundryOutput
  • func (txb *AnchorTransactionBuilder) InputsAreFull() bool
  • func (txb *AnchorTransactionBuilder) ModifyNativeTokenSupply(nativeTokenID iotago.NativeTokenID, delta *big.Int) int64
  • func (txb *AnchorTransactionBuilder) MustBalanced()
  • func (txb *AnchorTransactionBuilder) NFTOutputs() []*iotago.NFTOutput
  • func (txb *AnchorTransactionBuilder) NFTOutputsToBeUpdated() (toBeAdded, toBeRemoved []*iotago.NFTOutput)
  • func (txb *AnchorTransactionBuilder) NativeTokenOutputsByTokenIDs(ids []iotago.NativeTokenID) map[iotago.NativeTokenID]*iotago.BasicOutput
  • func (txb *AnchorTransactionBuilder) NativeTokenRecordsToBeUpdated() ([]iotago.NativeTokenID, []iotago.NativeTokenID)
  • func (txb *AnchorTransactionBuilder) SplitAssetsIntoInternalOutputs(req isc.OnLedgerRequest) uint64
  • func (txb *AnchorTransactionBuilder) TotalBaseTokensInOutputs() (uint64, uint64)
• type TransactionTotals
  • func (t *TransactionTotals) BalancedWith(another *TransactionTotals) error

Types

type AccountsContractRead

type AccountsContractRead struct {
	// nativeTokenOutputLoaderFunc loads stored output from the state
	// Should return nil if does not exist
	NativeTokenOutput func(iotago.NativeTokenID) (*iotago.BasicOutput, iotago.OutputID)

	// foundryLoaderFunc returns foundry output and id by its serial number
	// Should return nil if foundry does not exist
	FoundryOutput func(uint32) (*iotago.FoundryOutput, iotago.OutputID)

	// NFTOutput returns the stored NFT output from the state
	// Should return nil if NFT is not accounted for
	NFTOutput func(id iotago.NFTID) (*iotago.NFTOutput, iotago.OutputID)

	// TotalFungibleTokens returns the total base tokens and native tokens accounted by the chain
	TotalFungibleTokens func() *isc.Assets
}

type AnchorTransactionBuilder

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

AnchorTransactionBuilder represents structure which handles all the data needed to eventually build an essence of the anchor transaction

func NewAnchorTransactionBuilder

func NewAnchorTransactionBuilder(
	anchorOutput *iotago.AliasOutput,
	anchorOutputID iotago.OutputID,
	anchorOutputStorageDeposit uint64,
	accounts AccountsContractRead,
) *AnchorTransactionBuilder

NewAnchorTransactionBuilder creates new AnchorTransactionBuilder object

func (*AnchorTransactionBuilder) AddOutput

func (txb *AnchorTransactionBuilder) AddOutput(o iotago.Output) int64

AddOutput adds an information about posted request. It will produce output Return adjustment needed for the L2 ledger (adjustment on base tokens related to storage deposit)

func (*AnchorTransactionBuilder) BuildTransactionEssence

func (txb *AnchorTransactionBuilder) BuildTransactionEssence(stateMetadata []byte) (*iotago.TransactionEssence, []byte)

BuildTransactionEssence builds transaction essence from tx builder data

func (*AnchorTransactionBuilder) Clone

func (txb *AnchorTransactionBuilder) Clone() *AnchorTransactionBuilder

Clone clones the AnchorTransactionBuilder object. Used to snapshot/recover

func (*AnchorTransactionBuilder) Consume

func (txb *AnchorTransactionBuilder) Consume(req isc.OnLedgerRequest) uint64

Consume adds an input to the transaction. It panics if transaction cannot hold that many inputs All explicitly consumed inputs will hold fixed index in the transaction It updates total assets held by the chain. So it may panic due to exceed output counts Returns the amount of baseTokens needed to cover SD costs for the NTs/NFT contained by the request output

func (*AnchorTransactionBuilder) CreateAnchorOutput

func (txb *AnchorTransactionBuilder) CreateAnchorOutput(stateMetadata []byte) *iotago.AliasOutput

func (*AnchorTransactionBuilder) CreateNewFoundry

func (txb *AnchorTransactionBuilder) CreateNewFoundry(
	scheme iotago.TokenScheme,
	metadata []byte,
) (uint32, uint64)

func (*AnchorTransactionBuilder) DestroyFoundry

func (txb *AnchorTransactionBuilder) DestroyFoundry(sn uint32) uint64

DestroyFoundry destroys existing foundry. Return storage deposit

func (*AnchorTransactionBuilder) FoundriesToBeUpdated

func (txb *AnchorTransactionBuilder) FoundriesToBeUpdated() ([]uint32, []uint32)

func (*AnchorTransactionBuilder) FoundryOutputsBySN

func (txb *AnchorTransactionBuilder) FoundryOutputsBySN(serNums []uint32) map[uint32]*iotago.FoundryOutput

func (*AnchorTransactionBuilder) InputsAreFull

func (txb *AnchorTransactionBuilder) InputsAreFull() bool

InputsAreFull returns if transaction cannot hold more inputs

func (*AnchorTransactionBuilder) ModifyNativeTokenSupply

func (txb *AnchorTransactionBuilder) ModifyNativeTokenSupply(nativeTokenID iotago.NativeTokenID, delta *big.Int) int64

ModifyNativeTokenSupply inflates the supply is delta > 0, shrinks if delta < 0 returns adjustment of the storage deposit.

func (*AnchorTransactionBuilder) MustBalanced

func (txb *AnchorTransactionBuilder) MustBalanced()

MustBalanced asserts that the txb is balanced (intputs/outputs) and is consistent with L2 IMPORTANT: must be executed after `BuildTransactionEssence`, so that txb.resultAnchorOutput is calculated

func (*AnchorTransactionBuilder) NFTOutputs

func (txb *AnchorTransactionBuilder) NFTOutputs() []*iotago.NFTOutput

func (*AnchorTransactionBuilder) NFTOutputsToBeUpdated

func (txb *AnchorTransactionBuilder) NFTOutputsToBeUpdated() (toBeAdded, toBeRemoved []*iotago.NFTOutput)

func (*AnchorTransactionBuilder) NativeTokenOutputsByTokenIDs

func (txb *AnchorTransactionBuilder) NativeTokenOutputsByTokenIDs(ids []iotago.NativeTokenID) map[iotago.NativeTokenID]*iotago.BasicOutput

func (*AnchorTransactionBuilder) NativeTokenRecordsToBeUpdated

func (txb *AnchorTransactionBuilder) NativeTokenRecordsToBeUpdated() ([]iotago.NativeTokenID, []iotago.NativeTokenID)

func (*AnchorTransactionBuilder) SplitAssetsIntoInternalOutputs

func (txb *AnchorTransactionBuilder) SplitAssetsIntoInternalOutputs(req isc.OnLedgerRequest) uint64

SplitAssetsIntoInternalOutputs splits the native Tokens/NFT from a given (request) output. returns the resulting outputs and the list of new outputs (some of the native tokens might already have an accounting output owned by the chain, so we don't need new outputs for those)

func (*AnchorTransactionBuilder) TotalBaseTokensInOutputs

func (txb *AnchorTransactionBuilder) TotalBaseTokensInOutputs() (uint64, uint64)

TotalBaseTokensInOutputs returns (a) total base tokens owned by SCs and (b) total base tokens locked as storage deposit

type TransactionTotals

type TransactionTotals struct {
	// does not include internal storage deposits
	TotalBaseTokensInL2Accounts uint64
	// internal storage deposit
	TotalBaseTokensInStorageDeposit uint64
	// balances of native tokens (in all inputs/outputs). In the tx builder only loaded those which are needed
	NativeTokenBalances map[iotago.NativeTokenID]*big.Int
	// token supplies in foundries
	TokenCirculatingSupplies map[iotago.NativeTokenID]*big.Int
	// base tokens sent out by the transaction
	SentOutBaseTokens uint64
	// Sent out native tokens by the transaction
	SentOutTokenBalances map[iotago.NativeTokenID]*big.Int
}

func (*TransactionTotals) BalancedWith

func (t *TransactionTotals) BalancedWith(another *TransactionTotals) error