tvm

package
v1.0.4 Latest Latest
Warning

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

Go to latest
Published: Apr 24, 2026 License: MIT Imports: 18 Imported by: 21

Documentation

Index

Constants

View Source
const (
	AddressLength     = 36
	AddressDataLength = 32
	ZeroAddressStr    = "0:0000000000000000000000000000000000000000000000000000000000000000"
)
View Source
const (
	KeyUINT8   = 8
	KeyUINT256 = 256
)
View Source
const (
	SizeUINT8   = 8
	SizeUINT32  = 32
	SizeUINT64  = 64
	SizeUINT128 = 128
	SizeUINT160 = 160
	SizeUINT256 = 256
)
View Source
const BitLenOpcode = 32
View Source
const DefaultTonHlWalletAddress = "-1:5ee77ced0b7ae6ef88ab3f4350d8872c64667ffbe76073455215d3cdfab3294b"

NOTE: Prefunded high-load wallet from MyLocalTon pre-funded wallet, that can send up to 254 messages per 1 external message https://docs.ton.org/v3/documentation/smart-contracts/contracts-specs/highload-wallet#highload-wallet-v2

View Source
const DefaultTonHlWalletMnemonic = "" /* 157-byte string literal not displayed */

Variables

View Source
var (
	ZeroAddress = address.MustParseRawAddr(ZeroAddressStr)

	// Dummy address for Wrapped TON as there is no Wrapped native available yet. We use 0x1, it is an internal value for native token. Can't be 0x0 because the CCIP plugin throws on zero addresses
	TonTokenAddr = address.MustParseRawAddr("0:0000000000000000000000000000000000000000000000000000000000000001")

	// Dummy address for LINK Jetton until we deploy real one
	LinkTokenAddr = address.MustParseRawAddr("0:0000000000000000000000000000000000000000000000000000000000000002")
)
View Source
var EmptyCell = cell.BeginCell().EndCell()

EmptyCell is an empty TVM cell - BOC: "te6cckEBAQEAAgAAAEysuc0="

View Source
var TLBMapKeyStorage = uint64(hash.CRC32("RESERVED_KEY_Storage"))

reserved key for storage special opcode

Functions

func CallGetter

func CallGetter[A any, R any](
	ctx context.Context,
	client ton.APIClientWrapped,
	block *ton.BlockIDExt,
	contractAddr *address.Address,
	getter Getter[A, R],
	input ...A,
) (R, error)

CallGetter executes the provided getter using the supplied arguments of type A and decodes the result into type R. With no arguments it issues the request without parameters, while a single argument is encoded (using the getter's encoder when provided, otherwise the DefaultArgsEncoder).

func CallGetterLatest

func CallGetterLatest[A any, R any](
	ctx context.Context,
	client ton.APIClientWrapped,
	contractAddr *address.Address,
	getter Getter[A, R],
	input ...A,
) (R, error)

CallGetterLatest executes the provided getter with the latest masterchain block

func CellEquals

func CellEquals(a, b *cell.Cell) bool

CellEquals compares two cells for equality by comparing their hashes. It treats nil cells as equal.

func ExtractMagic

func ExtractMagic(rt reflect.Type) (uint64, error)

func ExtractMagicFromValue

func ExtractMagicFromValue(v any) (uint64, error)

func ExtractOpcode

func ExtractOpcode(body *cell.Cell) (uint32, error)

ExtractOpcode extracts the opcode from the message body cell.

func FetchResult deprecated

func FetchResult(
	ctx context.Context,
	client ton.APIClientWrapped,
	block *ton.BlockIDExt,
	contractAddr *address.Address,
	sourceStruct ResultGetter,
	opts []interface{},
) error

FetchResult fetches and unmarshals the result of a getter method using the ResultGetter interface. The getter method name is obtained from the sourceStruct itself, eliminating the need for a central registry.

Deprecated: Use the new Getter[A, R] pattern instead. For example:

result, err := client.RunGetMethod(ctx, block, contractAddr, getter.Name, args...)
if err != nil {
    return err
}
value, err := getter.Decoder.Decode(result)

func LoadFromResult deprecated

func LoadFromResult(v ResultUnmarshaler, res *ton.ExecutionResult) error

LoadFromResult unmarshals an execution result into a ResultUnmarshaler.

Deprecated: Use Getter[A, R] and ResultDecoder[T] instead.

func LoadMagic

func LoadMagic(tag string) (uint64, error)

Notice: vendoring github:xssnick/tonutils-go tlb package

func MakeDict

func MakeDict[T any](m map[*big.Int]T, keySz uint) (*cell.Dictionary, error)

func MakeDictFrom

func MakeDictFrom[T any](data []T, keySz uint) (*cell.Dictionary, error)

func MustExtractMagic

func MustExtractMagic(rt reflect.Type) uint64

func MyLocalTONWalletDefault

func MyLocalTONWalletDefault(client ton.APIClientWrapped) (*wallet.Wallet, error)

NOTE: Prefunded high-load wallet from MyLocalTon pre-funded wallet, that can send up to 254 messages per 1 external message https://docs.ton.org/v3/documentation/smart-contracts/contracts-specs/highload-wallet#highload-wallet-v2

func NewExitCodeInRange

func NewExitCodeInRange[E ~int32](ec E, ecMin int32, ecMax int32) (E, error)

func NewExitCodeInSet

func NewExitCodeInSet[E ~int32](ec E, set []E) (E, error)

func NewInitializedWallet

func NewInitializedWallet(ctx context.Context, funder *wallet.Wallet, w *wallet.Wallet, amount tlb.Coins) error

NewInitializedWallet creates and deploys a new wallet by first funding it from funder and then sending a self-transfer internal message with a non-zero amount to trigger the wallet's state initialization.

func NewRandomHighloadV3TestWallet

func NewRandomHighloadV3TestWallet(client ton.APIClientWrapped) (*wallet.Wallet, error)

func NewRandomTestWallet

func NewRandomTestWallet(client ton.APIClientWrapped, version wallet.VersionConfig, option wallet.Option) (*wallet.Wallet, error)

func NewRandomV5R1TestWallet

func NewRandomV5R1TestWallet(api wallet.TonAPI, networkGlobalID int32) (*wallet.Wallet, error)

NewRandomV5R1TestWallet creates a new random wallet for testing purposes.

func RandomQueryID

func RandomQueryID() (uint64, error)

Types

type ArgsEncoder

type ArgsEncoder[A any] interface {
	Encode(A) ([]any, error)
}

ArgsEncoder defines the interface for types that can encode arguments of type A into a slice of any values.

func DefaultArgsEncoder

func DefaultArgsEncoder[A any]() ArgsEncoder[A]

DefaultArgsEncoder returns an ArgsEncoder that derives the parameter slice from the provided value using reflection. Scalars become a single-element slice, structs are flattened across exported fields (respecting `tvm:"-"`), slices/arrays expand per element except for byte-like sequences which are passed through as-is, and pointers are forwarded without dereferencing (nil pointers encode as a single nil argument).

func NewArgsEncoder

func NewArgsEncoder[A any](encodeFn func(A) ([]any, error)) ArgsEncoder[A]

NewArgsEncoder creates a new ArgsEncoder[A] using the provided encode function.

type ContractTLBRegistry

type ContractTLBRegistry map[string]TLBMap

ContractTLBRegistry is a registry of TL-B types for decoding contract storage, messages, and events.

It maps contract types (string) to their corresponding TLBMap.

func (ContractTLBRegistry) Lookup

func (r ContractTLBRegistry) Lookup(contract string, opcode uint64) (any, bool)

Lookup retrieves the TL-B type for the given contract and opcode.

func (ContractTLBRegistry) LookupByOpcode

func (r ContractTLBRegistry) LookupByOpcode(opcode uint64) (any, bool)

LookupByOpcode retrieves the TL-B type for the given opcode across all registered contracts (snapshot).

func (ContractTLBRegistry) Snapshot

func (r ContractTLBRegistry) Snapshot() TLBMap

SnapshotTLBMap creates a combined TLBMap from all registered contract types. This is useful for decoding messages when the contract type is not known in advance. Duplicate opcodes will be overwritten by the last occurrence, order is not guaranteed.

type ExitCode

type ExitCode int32

This code is returned by smart contracts to indicate the reason for transaction failure or abnormal termination. For a comprehensive and up-to-date list of exit codes, refer to: - Tact documentation: https://docs.tact-lang.org/book/exit-codes/ - TON documentation: https://docs.ton.org/v3/documentation/tvm/tvm-exit-codes

const (
	ExitCodeSuccess                                                                  ExitCode = 0   // Standard successful execution exit code.
	ExitCodeSuccessVariant                                                           ExitCode = 1   // Alternative successful execution exit code. Reserved, but does not occur.
	ExitCodeStackUnderflow                                                           ExitCode = 2   // Stack underflow.
	ExitCodeStackOverflow                                                            ExitCode = 3   // Stack overflow.
	ExitCodeIntegerOverflow                                                          ExitCode = 4   // Integer overflow.
	ExitCodeIntegerOutOfExpectedRange                                                ExitCode = 5   // Range check error — an integer is out of its expected range.
	ExitCodeInvalidOpcode                                                            ExitCode = 6   // Invalid TVM opcode.
	ExitCodeTypeCheckError                                                           ExitCode = 7   // Type check error.
	ExitCodeCellOverflow                                                             ExitCode = 8   // Cell overflow.
	ExitCodeCellUnderflow                                                            ExitCode = 9   // Cell underflow.
	ExitCodeDictionaryError                                                          ExitCode = 10  // Dictionary error.
	ExitCodeUnknownError                                                             ExitCode = 11  // Described in TVM docs as “Unknown error, may be thrown by user programs.”
	ExitCodeFatalError                                                               ExitCode = 12  // Fatal error. Thrown by TVM in situations deemed impossible.
	ExitCodeOutOfGasError                                                            ExitCode = 13  // Out of gas error.
	ExitCodeOutOfGasErrorVariant                                                     ExitCode = -14 // Same as 13. Negative, so that it cannot be faked.
	ExitCodeVirtualizationError                                                      ExitCode = 14  // VM virtualization error. Reserved, but never thrown.
	ExitCodeActionListIsInvalid                                                      ExitCode = 32  // Action list is invalid.
	ExitCodeActionListIsTooLong                                                      ExitCode = 33  // Action list is too long.
	ExitCodeActionIsInvalidOrNotSupported                                            ExitCode = 34  // Action is invalid or not supported.
	ExitCodeInvalidSourceAddressInOutboundMessage                                    ExitCode = 35  // Invalid source address in outbound message.
	ExitCodeInvalidDestinationAddressInOutboundMessage                               ExitCode = 36  // Invalid destination address in outbound message.
	ExitCodeNotEnoughToncoin                                                         ExitCode = 37  // Not enough Toncoin.
	ExitCodeNotEnoughExtraCurrencies                                                 ExitCode = 38  // Not enough extra currencies.
	ExitCodeOutboundMessageDoesNotFitIntoACellAfterRewriting                         ExitCode = 39  // Outbound message does not fit into a cell after rewriting.
	ExitCodeCannotProcessAMessage                                                    ExitCode = 40  // Cannot process a message — not enough funds, the message is too large, or its Merkle depth is too big.
	ExitCodeLibraryReferenceIsNull                                                   ExitCode = 41  // Library reference is null during library change action.
	ExitCodeLibraryChangeActionError                                                 ExitCode = 42  // Library change action error.
	ExitCodeExceededMaximumNumberOfCellsInTheLibraryOrTheMaximumDepthOfTheMerkleTree ExitCode = 43  // Exceeded the maximum number of cells in the library or the maximum depth of the Merkle tree.
	ExitCodeAccountStateSizeExceededLimits                                           ExitCode = 50  // Account state size exceeded limits.

	ExitCodeTolkUnmatchedOpcode ExitCode = 63 // Tolk compiler: Unmatched opcode. Thrown by Tolk when it receives an opcode that it does not recognize.

	ExitCodeNullReferenceException         ExitCode = 128 // Tact compiler: Null reference exception. Configurable since Tact 1.6.
	ExitCodeInvalidSerializationPrefix     ExitCode = 129 // Tact compiler: Invalid serialization prefix.
	ExitCodeTactInvalidIncomingMessage     ExitCode = 130 // Tact compiler: Invalid incoming message — there is no receiver for the opcode of the received message.
	ExitCodeTactConstraintsError           ExitCode = 131 // Tact compiler: Constraints error. Reserved, but never thrown.
	ExitCodeTactAccessDenied               ExitCode = 132 // Tact compiler: Access denied — someone other than the owner sent a message to the contract.
	ExitCodeTactContractStopped            ExitCode = 133 // Tact compiler: Contract stopped.
	ExitCodeTactInvalidArgument            ExitCode = 134 // Tact compiler: Invalid argument.
	ExitCodeTactCodeOfAContractWasNotFound ExitCode = 135 // Tact compiler: Code of a contract was not found.
	ExitCodeTactInvalidStandardAddress     ExitCode = 136 // Tact compiler: Invalid standard address.
	ExitCodeTactNotABasechainAddress       ExitCode = 138 // Tact compiler: Not a basechain address. Available since Tact 1.6.3.

	ExitCodeComputeSkipReasonNoState   ExitCode = -1 // This is not a real exit code. It is used to mark a tx where the ComputePhase was Skipped due to 'No State': The smart contract has no state.
	ExitCodeComputeSkipReasonBadState  ExitCode = -2 // This is not a real exit code. It is used to mark a tx where the ComputePhase was Skipped due to 'Bad State': fixed_prefix_length field has an invalid value or the StateInit provided in the incoming message does not match account's address.
	ExitCodeComputeSkipReasonNoGas     ExitCode = -3 // This is not a real exit code. It is used to mark a tx where the ComputePhase was Skipped due to 'No Gas': The incoming message did not provide enough TON to cover the gas required to execute the smart contract.
	ExitCodeComputeSkipReasonSuspended ExitCode = -4 // This is not a real exit code. It is used to mark a tx where the ComputePhase was Skipped due to 'Suspended': The address is suspended; execution is disabled (used to limit early miner accounts).
)

func (ExitCode) Describe

func (c ExitCode) Describe() string

Describe provides human-readable descriptions for common TON Virtual Machine (TVM) exit codes.

func (ExitCode) NewFrom

func (ExitCode) NewFrom(ec ExitCode) (ExitCode, error)

func (ExitCode) String

func (i ExitCode) String() string

type ExitCodeCodecInt

type ExitCodeCodecInt[E ~int32] interface {
	NewFrom(code ExitCode) (E, error)
}
var ExitCodeCodec ExitCodeCodecInt[ExitCode] = ExitCode(-1)

type Getter

type Getter[A any, R any] struct {
	Name    string
	Encoder ArgsEncoder[A]   // encoder for input arguments of type A
	Decoder ResultDecoder[R] // decoder for output results of type R
}

Getter represents a getter method for a contract binding.

It includes the method name, an optional encoder for input arguments of type A, and a decoder for output results of type R.

func NewNoArgsGetter

func NewNoArgsGetter[R any](opts NoArgsOpts[R]) Getter[NoArgs, R]

NewNoArgsGetter creates a new Getter[NoArgs, R] for a getter method that takes no arguments.

type MethodGetter deprecated

type MethodGetter interface {
	GetterMethodName() string
}

MethodGetter provides the getter method name for a contract binding type.

Deprecated: Use Getter[A, R] instead.

type NoArgs

type NoArgs struct{}

NoArgs is used to represent a getter method without input arguments.

type NoArgsOpts

type NoArgsOpts[R any] struct {
	Name    string
	Decoder ResultDecoder[R]
}

type ResultDecoder

type ResultDecoder[T any] interface {
	Decode(*ton.ExecutionResult) (T, error)
}

ResultDecoder defines the interface for types that can decode execution results into a specific type T.

func NewResultDecoder

func NewResultDecoder[T any](decodeFn func(*ton.ExecutionResult) (T, error)) ResultDecoder[T]

NewResultDecoder creates a new ResultDecoder[T] using the provided decode function.

type ResultGetter deprecated

type ResultGetter interface {
	ResultUnmarshaler
	MethodGetter
}

ResultGetter combines the ability to unmarshal results with knowledge of which getter to call. Types implementing this interface can be used with FetchResult for a simplified API.

Deprecated: Use Getter[A, R] instead.

type ResultUnmarshaler deprecated

type ResultUnmarshaler interface {
	UnmarshalResult(*ton.ExecutionResult) error
}

ResultUnmarshaler defines the interface for types that can unmarshal execution results from TON client RPC calls.

Deprecated: Use ResultDecoder[T] and Getter[A, R] instead.

type TLBMap

type TLBMap map[uint64]any

tvm.TLBMap is a map of opcodes to their corresponding TL-B types.

func MustNewTLBMap

func MustNewTLBMap(types []any) TLBMap

func NewTLBMap

func NewTLBMap(types []any) (TLBMap, error)

NewTLBMap creates a map of TL-B magic numbers (opcodes) to their corresponding types from a set of TL-B annotated struct instances.

func (TLBMap) MustWithStorageType

func (m TLBMap) MustWithStorageType(storage any) TLBMap

func (TLBMap) WithStorageType

func (m TLBMap) WithStorageType(storage any) (TLBMap, error)

Jump to

Keyboard shortcuts

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