tvm

package
v1.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 14, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source
const (
	DefaultExternalMessageGasMax     = int64(1_000_000)
	DefaultExternalMessageGasCredit  = int64(10_000)
	DefaultInternalMessageGasMax     = int64(1_000_000)
	DefaultTickTockTransactionGasMax = int64(1_000_000)
	InternalMessageGasAmountFactor   = int64(1_000)
)

Variables

View Source
var AllowHigherVersionExecUsingLatest = true

AllowHigherVersionExecUsingLatest allows preparing configs with a global version higher than vm.MaxSupportedGlobalVersion. When enabled, execution uses the latest supported version.

Functions

func AccountRandSeed added in v1.18.0

func AccountRandSeed(blockRandSeed []byte, accountAddr *address.Address) ([]byte, error)

AccountRandSeed derives the per-account random seed from a block-level seed: sha256(block rand seed || rewritten account address). This is the layout used since global version 8; for earlier versions use BlockContext.AccountRandSeed which resolves the version automatically.

Types

type BlockContext added in v1.18.0

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

BlockContext is the per-block execution context: the prepared config plus block-scoped inputs, with the c7 unpacked config tuple built once. It is immutable after construction and safe to share between concurrently executing account lanes.

func (*BlockContext) AccountRandSeed added in v1.18.0

func (b *BlockContext) AccountRandSeed(accountAddr *address.Address) ([]byte, error)

AccountRandSeed derives the per-account random seed for this block: sha256(block rand seed || rewritten account address), using the pre-v8 layout quirk when the config global version requires it. It returns nil when the block has no rand seed. Lanes can compute it once per account and pass it through TransactionOptions.RandSeed.

func (*BlockContext) BlockLT added in v1.18.0

func (b *BlockContext) BlockLT() int64

BlockLT returns the configured block logical time, zero when derived per transaction.

func (*BlockContext) Config added in v1.18.0

Config returns the prepared per-epoch config this context was built from.

func (*BlockContext) Now added in v1.18.0

func (b *BlockContext) Now() uint32

Now returns the resolved block unix time.

func (*BlockContext) UnpackedConfig added in v1.18.0

func (b *BlockContext) UnpackedConfig() (tuple.Tuple, bool)

UnpackedConfig returns the prebuilt c7 unpacked config tuple and whether it is present.

type BlockOptions added in v1.18.0

type BlockOptions struct {
	// Now is the block unix time. When zero, the current wall clock is used.
	Now uint32
	// BlockLT is the block logical time (c7[4]). When zero, it is derived per
	// transaction from the transaction start LT.
	BlockLT int64
	// RandSeed is the block-level random seed. Per-account seeds are derived
	// from it unless TransactionOptions.RandSeed overrides them.
	RandSeed []byte
	// PrevBlocks is the c7 previous-blocks tuple (c7[13]). An empty tuple maps
	// to a null c7 entry.
	PrevBlocks tuple.Tuple
	// GlobalID overrides config param 19 in the c7 unpacked config when
	// non-zero (useful for configs that predate the param).
	GlobalID int32
	// Libraries are block-level library collections available to every
	// transaction of the block (e.g. the masterchain libraries dict).
	Libraries []*cell.Cell
}

BlockOptions carries the per-block execution inputs that cannot be derived from the blockchain config.

type EmulateExternalMessageConfig

type EmulateExternalMessageConfig = MessageEmulationConfig

type EmulateInternalMessageConfig

type EmulateInternalMessageConfig = MessageEmulationConfig

type ExecutionConfig added in v1.18.0

type ExecutionConfig struct {
	AccountRoot                 *cell.Cell
	Libraries                   []*cell.Cell
	SignatureCheckAlwaysSucceed bool
	Config                      *PreparedBlockchainConfig
}

type ExecutionResult

type ExecutionResult struct {
	ExitCode  int64
	GasUsed   int64
	Steps     uint32
	Gas       vm.Gas
	Stack     *vm.Stack
	Code      *cell.Cell
	Data      *cell.Cell
	Actions   *cell.Cell
	Committed bool
	Proof     *cell.Cell
}

type MessageEmulationConfig

type MessageEmulationConfig struct {
	Address                     *address.Address
	Now                         uint32
	BlockLT                     int64
	LogicalTime                 int64
	Balance                     *big.Int
	RandSeed                    []byte
	Config                      *PreparedBlockchainConfig
	IncomingValue               tuple.Tuple
	StorageFees                 int64
	PrevBlocks                  any
	UnpackedConfig              tuple.Tuple
	DuePayment                  any
	PrecompiledGasUsage         *big.Int
	InMsgParams                 tuple.Tuple
	Globals                     map[int]any
	GlobalID                    int32
	Libraries                   []*cell.Cell
	Gas                         vm.Gas
	StopOnAccept                bool
	SignatureCheckAlwaysSucceed bool
	BuildProof                  bool
	AccountRoot                 *cell.Cell
	TraceHook                   vm.TraceHook
}

MessageEmulationConfig drives the direct message-emulation entry points (EmulateExternalMessage/EmulateInternalMessage): code is executed with a caller-controlled synthetic c7 context. Config must be a prepared config; the remaining c7 fields override the derived values when set.

type MessageExecutionResult

type MessageExecutionResult struct {
	ExecutionResult
	Accepted bool
}

type OutMessage added in v1.18.0

type OutMessage struct {
	Cell *cell.Cell
	Msg  *tlb.Message
}

OutMessage is an outbound message emitted by a transaction, in creation order. Msg is the parsed form of Cell built during the action phase.

type PreparedAccount added in v1.18.0

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

PreparedAccount is an account state parsed once into the representation the transaction executor needs. Build it with PrepareAccount at lane start; each TransactionExecutionResult carries the follow-up PreparedAccount so consecutive transactions of one account never re-parse state.

func PrepareAccount added in v1.18.0

func PrepareAccount(shard *tlb.ShardAccount, addr *address.Address) (*PreparedAccount, error)

PrepareAccount parses the shard account state exactly once. addr is the account address used for non-existing accounts (a lane always knows its account); it may be nil for existing accounts, whose address comes from the parsed state.

func PrepareParsedAccount added in v1.18.0

func PrepareParsedAccount(shard *tlb.ShardAccount, state *tlb.AccountState, addr *address.Address) (*PreparedAccount, error)

PrepareParsedAccount wraps an already-parsed shard account state; state must be the parsed form of shard.Account.

func (*PreparedAccount) Address added in v1.18.0

func (a *PreparedAccount) Address() *address.Address

Address returns the resolved account address.

func (*PreparedAccount) ShardAccount added in v1.18.0

func (a *PreparedAccount) ShardAccount() *tlb.ShardAccount

ShardAccount returns the shard account this state was prepared from (for results: the post-transaction shard account).

func (*PreparedAccount) ShardAccountCell added in v1.18.0

func (a *PreparedAccount) ShardAccountCell() *cell.Cell

ShardAccountCell serializes the shard account into a cell.

func (*PreparedAccount) State added in v1.18.0

func (a *PreparedAccount) State() *tlb.AccountState

State returns the parsed account state.

type PreparedBlockchainConfig added in v1.18.0

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

PreparedBlockchainConfig is the per-config-epoch execution context: everything the transaction executor needs from the blockchain config, derived once from the config root. It is immutable after PrepareBlockchainConfig returns and safe to share between concurrently executing account lanes.

func MustPrepareBlockchainConfig added in v1.18.0

func MustPrepareBlockchainConfig(configRoot *cell.Cell) *PreparedBlockchainConfig

MustPrepareBlockchainConfig is PrepareBlockchainConfig that panics on error.

func PrepareBlockchainConfig added in v1.18.0

func PrepareBlockchainConfig(configRoot *cell.Cell) (*PreparedBlockchainConfig, error)

PrepareBlockchainConfig derives the immutable per-epoch execution context from a blockchain config root. The global version (config param 8) must be present and within the supported range unless AllowHigherVersionExecUsingLatest is enabled.

func (*PreparedBlockchainConfig) Capabilities added in v1.18.0

func (c *PreparedBlockchainConfig) Capabilities() uint64

Capabilities returns the capability bit set of config param 8.

func (*PreparedBlockchainConfig) GlobalVersion added in v1.18.0

func (c *PreparedBlockchainConfig) GlobalVersion() uint32

GlobalVersion returns the effective global version used for execution.

func (*PreparedBlockchainConfig) NewBlockContext added in v1.18.0

func (c *PreparedBlockchainConfig) NewBlockContext(opts BlockOptions) (*BlockContext, error)

NewBlockContext builds the immutable per-block execution context.

func (*PreparedBlockchainConfig) Root added in v1.18.0

func (c *PreparedBlockchainConfig) Root() *cell.Cell

Root returns the raw config root the context was prepared from.

type PreparedMessage added in v1.18.0

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

PreparedMessage is an inbound message parsed once and reused by the executor without re-parsing.

func PrepareMessage added in v1.18.0

func PrepareMessage(msgCell *cell.Cell) (*PreparedMessage, error)

PrepareMessage parses an inbound message cell once and validates that it can be used as a transaction input.

func PrepareParsedMessage added in v1.18.0

func PrepareParsedMessage(msgCell *cell.Cell, msg *tlb.Message) (*PreparedMessage, error)

PrepareParsedMessage wraps an already-parsed inbound message together with its cell; msg must be the parsed form of msgCell.

func (*PreparedMessage) Cell added in v1.18.0

func (m *PreparedMessage) Cell() *cell.Cell

Cell returns the raw message cell.

func (*PreparedMessage) Message added in v1.18.0

func (m *PreparedMessage) Message() *tlb.Message

Message returns the parsed message.

type TVM

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

func NewTVM

func NewTVM() *TVM

func (*TVM) CheckExternalMessageAccepted added in v1.18.0

func (tvm *TVM) CheckExternalMessageAccepted(block *BlockContext, acc *PreparedAccount, msg *PreparedMessage, opts TransactionOptions) (bool, error)

CheckExternalMessageAccepted runs only the transaction compute path needed to decide whether an inbound external message reaches accept.

func (*TVM) EmulateExternalMessage

func (tvm *TVM) EmulateExternalMessage(code, data *cell.Cell, msg *tlb.ExternalMessage, cfg EmulateExternalMessageConfig) (*MessageExecutionResult, error)

func (*TVM) EmulateInternalMessage

func (tvm *TVM) EmulateInternalMessage(code, data, body *cell.Cell, amount uint64, cfg EmulateInternalMessageConfig) (*MessageExecutionResult, error)

func (*TVM) EmulateTickTockTransaction

func (tvm *TVM) EmulateTickTockTransaction(block *BlockContext, acc *PreparedAccount, isTock bool, opts TransactionOptions) (*TransactionExecutionResult, error)

EmulateTickTockTransaction executes a tick or tock system transaction of a masterchain special account.

func (*TVM) EmulateTransaction

func (tvm *TVM) EmulateTransaction(block *BlockContext, acc *PreparedAccount, msg *PreparedMessage, opts TransactionOptions) (*TransactionExecutionResult, error)

EmulateTransaction executes an ordinary transaction of acc with the inbound message msg. The result feeds the next transaction of the same account through NextAccount and AccountStorageStat.

func (*TVM) Execute

func (tvm *TVM) Execute(code, data *cell.Cell, c7 tuple.Tuple, gas vm.Gas, stack *vm.Stack, cfg ExecutionConfig) (*ExecutionResult, error)

func (*TVM) ExecuteGetMethod added in v1.18.0

func (tvm *TVM) ExecuteGetMethod(code, data *cell.Cell, c7 tuple.Tuple, gas vm.Gas, stack *vm.Stack, cfg ExecutionConfig) (*ExecutionResult, error)

type TransactionExecutionResult

type TransactionExecutionResult struct {
	ExecutionResult
	Accepted        bool
	TransactionCell *cell.Cell
	// NextAccount is the resulting account state, prepared to feed the next
	// transaction of the same account without any re-parsing.
	NextAccount *PreparedAccount
	// OutMessages are the emitted outbound messages in creation order,
	// including the bounce message when one was produced.
	OutMessages []OutMessage
	// EndLT is the logical time after the transaction (start LT + 1 + number
	// of emitted messages).
	EndLT uint64
	// AccountStorageStat is the account storage-stat dictionary to pass to the
	// next transaction of the same account.
	AccountStorageStat *cell.Cell
}

func (*TransactionExecutionResult) ParseTransaction added in v1.18.0

func (r *TransactionExecutionResult) ParseTransaction() (*tlb.Transaction, error)

ParseTransaction parses the built transaction cell into its tlb form. The executor itself never needs the parsed transaction, so the parse is done on demand only.

type TransactionOptions added in v1.18.0

type TransactionOptions struct {
	// LogicalTime is the minimal logical time of the transaction. The
	// effective start LT also respects the account's last transaction LT and
	// the inbound message LT. Zero derives it from the account state.
	LogicalTime int64
	// RandSeed is the per-account random seed (c7[6]) as raw bytes. When
	// empty, it is derived from the block rand seed and the account address
	// (see BlockContext.AccountRandSeed).
	RandSeed []byte
	// Gas overrides the config-derived gas limits when non-zero.
	Gas vm.Gas
	// AccountStorageStat is the account storage-stat dictionary carried in
	// from the previous transaction result of the same account.
	AccountStorageStat *cell.Cell
	// BuildProof builds a Merkle usage proof over the account state covering
	// the compute-phase reads (returned in ExecutionResult.Proof).
	BuildProof bool
	// SignatureCheckAlwaysSucceed makes signature checks succeed unconditionally
	// (fee estimation flows).
	SignatureCheckAlwaysSucceed bool
	// TraceHook observes VM execution.
	TraceHook vm.TraceHook
}

TransactionOptions carries the genuinely per-transaction execution inputs. Everything else lives in BlockContext (per block) and PreparedBlockchainConfig (per config epoch).

Directories

Path Synopsis
internal
bls12381
Package bls12381 provides bilinear pairings using the BLS12-381 curve.
Package bls12381 provides bilinear pairings using the BLS12-381 curve.
op
vm

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL