actor

Documentation

Overview

Package actor provides a way to change chain state via RPC client.

This layer builds on top of the basic RPC client and simplifies creating, signing and sending transactions to the network (since that's the only way chain state is changed). It's generic enough to be used for any contract that you may want to invoke and contract-specific functions can build on top of it.

Index

• type Actor
  • func New(ra RPCActor, signers []SignerAccount) (*Actor, error)
  • func NewSimple(ra RPCActor, acc *wallet.Account) (*Actor, error)
  • func (a *Actor) CalculateNetworkFee(tx *transaction.Transaction) (int64, error)
  • func (a *Actor) CalculateValidUntilBlock() (uint32, error)
  • func (a *Actor) GetBlockCount() (uint32, error)
  • func (a *Actor) GetNetwork() netmode.Magic
  • func (a *Actor) GetVersion() result.Version
  • func (a *Actor) MakeCall(contract util.Uint160, method string, params ...interface{}) (*transaction.Transaction, error)
  • func (a *Actor) MakeRun(script []byte) (*transaction.Transaction, error)
  • func (a *Actor) MakeTunedCall(contract util.Uint160, method string, attrs []transaction.Attribute, ...) (*transaction.Transaction, error)
  • func (a *Actor) MakeTunedRun(script []byte, attrs []transaction.Attribute, ...) (*transaction.Transaction, error)
  • func (a *Actor) MakeUncheckedRun(script []byte, sysfee int64, attrs []transaction.Attribute, ...) (*transaction.Transaction, error)
  • func (a *Actor) MakeUnsignedCall(contract util.Uint160, method string, attrs []transaction.Attribute, ...) (*transaction.Transaction, error)
  • func (a *Actor) MakeUnsignedRun(script []byte, attrs []transaction.Attribute) (*transaction.Transaction, error)
  • func (a *Actor) MakeUnsignedUncheckedRun(script []byte, sysFee int64, attrs []transaction.Attribute) (*transaction.Transaction, error)
  • func (a *Actor) Send(tx *transaction.Transaction) (util.Uint256, uint32, error)
  • func (a *Actor) SendCall(contract util.Uint160, method string, params ...interface{}) (util.Uint256, uint32, error)
  • func (a *Actor) SendRun(script []byte) (util.Uint256, uint32, error)
  • func (a *Actor) SendTunedCall(contract util.Uint160, method string, attrs []transaction.Attribute, ...) (util.Uint256, uint32, error)
  • func (a *Actor) SendTunedRun(script []byte, attrs []transaction.Attribute, ...) (util.Uint256, uint32, error)
  • func (a *Actor) SendUncheckedRun(script []byte, sysfee int64, attrs []transaction.Attribute, ...) (util.Uint256, uint32, error)
  • func (a *Actor) Sign(tx *transaction.Transaction) error
  • func (a *Actor) SignAndSend(tx *transaction.Transaction) (util.Uint256, uint32, error)
• type RPCActor
• type SignerAccount
• type TransactionCheckerModifier
• type TransactionModifier

Types

type Actor

type Actor struct {
	invoker.Invoker
	// contains filtered or unexported fields
}

Actor keeps a connection to the RPC endpoint and allows to perform state-changing actions (via transactions that can also be created without sending them to the network) on behalf of a set of signers. It also provides an Invoker interface to perform test calls with the same set of signers.

func New

func New(ra RPCActor, signers []SignerAccount) (*Actor, error)

New creates an Actor instance using the specified RPC interface and the set of signers with corresponding accounts. Every transaction created by this Actor will have this set of signers and all communication will be performed via this RPC. Upon Actor instance creation a GetVersion call is made and the result of it is cached forever (and used for internal purposes).

func NewSimple

func NewSimple(ra RPCActor, acc *wallet.Account) (*Actor, error)

NewSimple makes it easier to create an Actor for the most widespread case when transactions have only one signer that uses CalledByEntry scope. When other scopes or multiple signers are needed use New.

func (*Actor) CalculateNetworkFee

func (a *Actor) CalculateNetworkFee(tx *transaction.Transaction) (int64, error)

CalculateNetworkFee wraps RPCActor's CalculateNetworkFee, making it available to Actor users directly. It returns network fee value for the given transaction.

func (*Actor) CalculateValidUntilBlock

func (a *Actor) CalculateValidUntilBlock() (uint32, error)

CalculateValidUntilBlock returns correct ValidUntilBlock value for a new transaction relative to the current blockchain height. It uses "height + number of validators + 1" formula suggesting shorter transaction lifetime than the usual "height + MaxValidUntilBlockIncrement" approach. Shorter lifetime can be useful to control transaction acceptance wait time because it can't be added into a block after ValidUntilBlock.

func (*Actor) GetBlockCount

func (a *Actor) GetBlockCount() (uint32, error)

GetBlockCount wraps RPCActor's GetBlockCount, making it available to Actor users directly. It returns current number of blocks in the chain.

func (*Actor) GetNetwork

func (a *Actor) GetNetwork() netmode.Magic

GetNetwork is a convenience method that returns the network's magic number.

func (*Actor) GetVersion

func (a *Actor) GetVersion() result.Version

GetVersion returns version data from the RPC endpoint.

func (*Actor) MakeCall

func (a *Actor) MakeCall(contract util.Uint160, method string, params ...interface{}) (*transaction.Transaction, error)

MakeCall creates a transaction that calls the given method of the given contract with the given parameters. Test call is performed and checked for HALT status, if more checks are needed or transaction should have some additional attributes use MakeTunedCall.

func (*Actor) MakeRun

func (a *Actor) MakeRun(script []byte) (*transaction.Transaction, error)

MakeRun creates a transaction with the given executable script. Test invocation of this script is performed and expected to end up in HALT state. If more checks are needed or transaction should have some additional attributes use MakeTunedRun.

func (*Actor) MakeTunedCall

func (a *Actor) MakeTunedCall(contract util.Uint160, method string, attrs []transaction.Attribute, txHook TransactionCheckerModifier, params ...interface{}) (*transaction.Transaction, error)

MakeTunedCall creates a transaction with the given attributes that calls the given method of the given contract with the given parameters. It's filtered through the provided callback (see TransactionCheckerModifier documentation), so the process can be aborted and transaction can be modified before signing. If no callback is given then the result is checked for HALT state.

func (*Actor) MakeTunedRun

func (a *Actor) MakeTunedRun(script []byte, attrs []transaction.Attribute, txHook TransactionCheckerModifier) (*transaction.Transaction, error)

MakeTunedRun creates a transaction with the given attributes that executes the given script. It's filtered through the provided callback (see TransactionCheckerModifier documentation), so the process can be aborted and transaction can be modified before signing. If no callback is given then the result is checked for HALT state.

func (*Actor) MakeUncheckedRun

func (a *Actor) MakeUncheckedRun(script []byte, sysfee int64, attrs []transaction.Attribute, txHook TransactionModifier) (*transaction.Transaction, error)

MakeUncheckedRun creates a transaction with the given attributes that executes the given script and is expected to use up to sysfee GAS for its execution. The transaction is filtered through the provided callback (see TransactionModifier documentation), so the process can be aborted and transaction can be modified before signing. This method is mostly useful when test invocation is already performed and the script and required system fee values are already known.

func (*Actor) MakeUnsignedCall

func (a *Actor) MakeUnsignedCall(contract util.Uint160, method string, attrs []transaction.Attribute, params ...interface{}) (*transaction.Transaction, error)

MakeUnsignedCall creates an unsigned transaction with the given attributes that calls the given method of the given contract with the given parameters. Test-invocation is performed and is expected to end up in HALT state, the transaction returned has correct SystemFee and NetworkFee values.

func (*Actor) MakeUnsignedRun

func (a *Actor) MakeUnsignedRun(script []byte, attrs []transaction.Attribute) (*transaction.Transaction, error)

MakeUnsignedRun creates an unsigned transaction with the given attributes that executes the given script. Test-invocation is performed and is expected to end up in HALT state, the transaction returned has correct SystemFee and NetworkFee values.

func (*Actor) MakeUnsignedUncheckedRun

func (a *Actor) MakeUnsignedUncheckedRun(script []byte, sysFee int64, attrs []transaction.Attribute) (*transaction.Transaction, error)

MakeUnsignedUncheckedRun creates an unsigned transaction containing the given script with the system fee value and attributes. It's expected to be used when test invocation is already done and the script and system fee value are already known to be good, so it doesn't do test invocation internally. But it fills Signers with Actor's signers, calculates proper ValidUntilBlock and NetworkFee values. The resulting transaction can be changed in its Nonce, SystemFee, NetworkFee and ValidUntilBlock values and then be signed and sent or exchanged via context.ParameterContext.

func (*Actor) Send

func (a *Actor) Send(tx *transaction.Transaction) (util.Uint256, uint32, error)

Send allows to send arbitrary prepared transaction to the network. It returns transaction hash and ValidUntilBlock value.

func (*Actor) SendCall

func (a *Actor) SendCall(contract util.Uint160, method string, params ...interface{}) (util.Uint256, uint32, error)

SendCall creates a transaction that calls the given method of the given contract with the given parameters (see also MakeCall) and sends it to the network.

func (*Actor) SendRun

func (a *Actor) SendRun(script []byte) (util.Uint256, uint32, error)

SendRun creates a transaction with the given executable script (see also MakeRun) and sends it to the network.

func (*Actor) SendTunedCall

func (a *Actor) SendTunedCall(contract util.Uint160, method string, attrs []transaction.Attribute, txHook TransactionCheckerModifier, params ...interface{}) (util.Uint256, uint32, error)

SendTunedCall creates a transaction that calls the given method of the given contract with the given parameters (see also MakeTunedCall) and attributes, allowing to check for execution results of this call and modify transaction before it's signed; this transaction is then sent to the network.

func (*Actor) SendTunedRun

func (a *Actor) SendTunedRun(script []byte, attrs []transaction.Attribute, txHook TransactionCheckerModifier) (util.Uint256, uint32, error)

SendTunedRun creates a transaction with the given executable script and attributes, allowing to check for execution results of this script and modify transaction before it's signed (see also MakeTunedRun). This transaction is then sent to the network.

func (*Actor) SendUncheckedRun

func (a *Actor) SendUncheckedRun(script []byte, sysfee int64, attrs []transaction.Attribute, txHook TransactionModifier) (util.Uint256, uint32, error)

SendUncheckedRun creates a transaction with the given executable script and attributes that can use up to sysfee GAS for its execution, allowing to modify this transaction before it's signed (see also MakeUncheckedRun). This transaction is then sent to the network.

func (*Actor) Sign

func (a *Actor) Sign(tx *transaction.Transaction) error

Sign adds signatures to arbitrary transaction using Actor signers wallets. Most of the time it shouldn't be used directly since it'll be successful only if the transaction is made using the same set of accounts as the one used for Actor creation.

func (*Actor) SignAndSend

func (a *Actor) SignAndSend(tx *transaction.Transaction) (util.Uint256, uint32, error)

SignAndSend signs arbitrary transaction (see also Sign) and sends it to the network.

type RPCActor

type RPCActor interface {
	invoker.RPCInvoke

	CalculateNetworkFee(tx *transaction.Transaction) (int64, error)
	GetBlockCount() (uint32, error)
	GetVersion() (*result.Version, error)
	SendRawTransaction(tx *transaction.Transaction) (util.Uint256, error)
}

RPCActor is an interface required from the RPC client to successfully create and send transactions.

type SignerAccount

type SignerAccount struct {
	Signer  transaction.Signer
	Account *wallet.Account
}

SignerAccount represents combination of the transaction.Signer and the corresponding wallet.Account. It's used to create and sign transactions, each transaction has a set of signers that must witness the transaction with their signatures.

type TransactionCheckerModifier

type TransactionCheckerModifier func(r *result.Invoke, t *transaction.Transaction) error

TransactionCheckerModifier is a callback that receives the result of test-invocation and the transaction that can perform the same invocation on chain. This callback is accepted by methods that create transactions, it can examine both arguments and return an error if there is anything wrong there which will abort the creation process. Notice that when used this callback is completely responsible for invocation result checking, including checking for HALT execution state (so if you don't check for it in a callback you can send a transaction that is known to end up in FAULT state). It can also modify the transaction (see TransactionModifier).

type TransactionModifier

type TransactionModifier func(t *transaction.Transaction) error

TransactionModifier is a callback that receives the transaction before it's signed from a method that creates signed transactions. It can check fees and other fields of the transaction and return an error if there is anything wrong there which will abort the creation process. It also can modify Nonce, SystemFee, NetworkFee and ValidUntilBlock values taking full responsibility on the effects of these modifications (smaller fee values, too low or too high ValidUntilBlock or bad Nonce can render transaction invalid). Modifying other fields is not supported. Mostly it's useful for increasing fee values since by default they're just enough for transaction to be successfully accepted and executed.