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 ¶
- Variables
- type AnchorTransactionBuilder
- func (txb *AnchorTransactionBuilder) AddOutput(o iotago.Output) int64
- func (txb *AnchorTransactionBuilder) AssertConsistentWithL2Totals(l2Totals *isc.Assets, checkpoint string)
- func (txb *AnchorTransactionBuilder) BuildTransactionEssence(l1Commitment *state.L1Commitment) (*iotago.TransactionEssence, []byte)
- func (txb *AnchorTransactionBuilder) Clone() *AnchorTransactionBuilder
- func (txb *AnchorTransactionBuilder) Consume(req isc.OnLedgerRequest) int64
- 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) InternalNativeTokenBalances() (map[iotago.NativeTokenID]*big.Int, map[iotago.NativeTokenID]*big.Int)
- func (txb *AnchorTransactionBuilder) ModifyNativeTokenSupply(nativeTokenID iotago.NativeTokenID, delta *big.Int) int64
- func (txb *AnchorTransactionBuilder) MustBalanced(checkpoint string)
- 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) String() string
- func (txb *AnchorTransactionBuilder) TotalBaseTokensInL2Accounts() uint64
- func (txb *AnchorTransactionBuilder) TotalBaseTokensInOutputs() (uint64, uint64)
- func (txb *AnchorTransactionBuilder) Totals() (*TransactionTotals, *TransactionTotals, error)
- type NFTOutputLoader
- type TransactionTotals
Constants ¶
This section is empty.
Variables ¶
var DebugTxBuilder = true
Functions ¶
This section is empty.
Types ¶
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, tokenBalanceLoader nativeTokenOutputLoaderFunc, foundryLoader foundryLoaderFunc, nftLoader NFTOutputLoader, storageDepositAssumptions *transaction.StorageDepositAssumption, ) *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) AssertConsistentWithL2Totals ¶
func (txb *AnchorTransactionBuilder) AssertConsistentWithL2Totals(l2Totals *isc.Assets, checkpoint string)
func (*AnchorTransactionBuilder) BuildTransactionEssence ¶
func (txb *AnchorTransactionBuilder) BuildTransactionEssence(l1Commitment *state.L1Commitment) (*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) int64
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 delta of base tokens needed to adjust the common account due to storage deposit requirement for internal UTXOs NOTE: if call panics with ErrNotEnoughFundsForInternalStorageDeposit, the state of the builder becomes inconsistent It means, in the caller context it should be rolled back altogether
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) InternalNativeTokenBalances ¶
func (txb *AnchorTransactionBuilder) InternalNativeTokenBalances() (map[iotago.NativeTokenID]*big.Int, map[iotago.NativeTokenID]*big.Int)
InternalNativeTokenBalances returns internally maintained balances of native tokens in inputs and
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(checkpoint string)
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) String ¶
func (txb *AnchorTransactionBuilder) String() string
func (*AnchorTransactionBuilder) TotalBaseTokensInL2Accounts ¶
func (txb *AnchorTransactionBuilder) TotalBaseTokensInL2Accounts() uint64
TotalBaseTokensInL2Accounts returns number of on-chain base tokens. It does not include minimum storage deposit needed for anchor output and other internal UTXOs
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
func (*AnchorTransactionBuilder) Totals ¶
func (txb *AnchorTransactionBuilder) Totals() (*TransactionTotals, *TransactionTotals, error)
Totals check consistency. If input total equals with output totals, returns (base tokens total, native token totals, true) Otherwise returns (0, nil, false)
type NFTOutputLoader ¶
NFTOutputLoader externally supplied function which returns the stored NFT output from the state Should return nil if NFT is not accounted for
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