abi

README

TON contract interface

Overview

You can define schema of contract get-methods and messages going to and from contract in just one JSON schema.

Contract interface

Anton mainly determines contracts by the presence of get-methods in the contract code. But if it is impossible to identify your contracts by only get-methods (as in Telemint NFT collection contracts), you should define contract addresses in the network or a contract code Bag of Cells.

{
   "interface_name": "",  // name of the contract
   "addresses": [],       // optional contract addresses
   "code_boc": "",        // optional contract code BoC
   "definitions": {},     // map definition name to cell schema
   "in_messages": [],     // possible incoming messages schema
   "out_messages": [],    // possible outgoing messages schema
   "get_methods": []      // get-method names, return values and arguments
}

Message schema

Each message schema has operation name, operation code and field definitions. Each field definition has name, TL-B type and format, which shows how to parse cell. Also, it is possible to define similarly described embedded structures in each field in struct_fields.

{
   "op_name": "nft_start_auction",  // operation name
   "op_code": "0x5fcc3d14",         // TL-B constructor prefix code (operation code)
   "body": [
      {                             // fields definitions
         "name": "query_id",        // field name
         "tlb_type": "## 64",       // field TL-B type
         "format": "uint64"         // describes how we should parse the field
      }, 
      {
         "name": "auction_config",
         "tlb_type": "^",
         "format": "struct",
         "struct_fields": [         // fields of inner structure
            {
               "name": "beneficiary_address",
               "tlb_type": "addr",
               "format": "addr"
            }
         ]
      }
   ]
}

Types mapping

While parsing TL-B cells by fields description, we are trying to parse data according to TL-B type and map it into some Golang type or structure. Each TL-B type used in schemas has value equal to the structure tags in tonutils-go. If it is not possible to parse the field using tlb.LoadFromCell, you can define your custom type with LoadFromCell method in abi package (for example, TelemintText) and register it in tlb_types.go.

Accepted TL-B types in tlb_type:

1. ## N - integer with N bits; by default maps to uintX or big.Int
2. ^ - data is stored in the referenced cell; by default maps to cell.Cell or to custom struct, if struct_fields is defined
3. . - inner struct; by default maps to cell.Cell or to custom struct, if struct_fields is defined
4. [TODO] [^]dict N [-> array [^]] - dictionary with key size N, transformation is not supported yet
5. bits N - bit slice N len; by default maps to []byte
6. bool - 1 bit boolean; by default maps to bool
7. addr - ton address; by default maps to addr.Address
8. maybe - reads 1 bit, and loads rest if its 1, can be used in combination with others only; by default maps to cell.Cell or to custom struct, if struct_fields is defined
9. either X Y - reads 1 bit, if its 0 - loads X, if 1 - loads Y; by default maps to cell.Cell or to custom struct, if struct_fields is defined

Accepted types of format:

1. struct - embed structure, maps into structure described by struct_fields
2. bytes - byte slice, maps into []byte
3. bool - boolean (can be used only on tlb_type = bool)
4. uint8, uint16, uint32, uint64 - unsigned integers
5. bigInt - integer with more than 64 bits, maps into big.Int wrapper
6. cell - TL-B cell, maps into cell.Cell
7. dict - TL-B dictionary (hashmap), maps into cell.Dictionary
8. magic - TL-B constructor prefix, must not be used
9. coins - varInt 16, maps into big.Int wrapper
10. addr - TON address, maps into address.Address wrapper
11. [TODO] content_cell - token data as in TEP-64; implementation
12. string - string snake is stored in the cell
13. telemintText - variable length string with this TL-B constructor

Shared TL-B constructors

You can define some cell schema in contract interface definitions field and use it later in messages or contract data schemas.

{
   "interface_name": "telemint_nft_item",
   "addresses": [
      "EQAOQdwdw8kGftJCSFgOErM1mBjYPe4DBPq8-AhF6vr9si5N",
      "EQCA14o1-VWhS2efqoh_9M1b_A9DtKTuoqfmkn83AbJzwnPi"
   ],
   "definitions": {
      "auction_config": [
         {
            "name": "beneficiary_address",
            "tlb_type": "addr"
         }
      ]
   },
   "in_messages": [
      {
         "op_name": "teleitem_start_auction",
         "op_code": "0x487a8e81",
         "body": [
            {
               "name": "query_id",
               "tlb_type": "## 64"
            },
            {
               "name": "auction_config",
               "tlb_type": "^",
               "format": "auction_config"
            }
         ]
      }
   ]
}

Get-methods

Each get-method consists of name (which is then used to get method_id), arguments and return values.

{
   "interface_name": "jetton_minter",
   "get_methods": [
      {
         "name": "get_wallet_address",          // get-method name
         "arguments": [
            {
               "name": "owner_address",         // argument name
               "stack_type": "slice",
               "format": "addr"
            }
         ],
         "return_values": [
            {
               "name": "jetton_wallet_address", // return value name
               "stack_type": "slice",           // type we load
               "format": "addr"                 // type we parse into
            }
         ]
      },
      {
         "name": "get_jetton_data",
         "return_values": [
            {
               "name": "total_supply",
               "stack_type": "int",
               "format": "bigInt"
            },
            {
               "name": "mintable",
               "stack_type": "int",
               "format": "bool"
            },
            {
               "name": "admin_address",
               "stack_type": "slice",
               "format": "addr"
            }
         ]
      }
   ]
}

Accepted argument stack types:

1. int - integer; by default maps from big.Int
2. cell - map from BoC
3. slice - cell slice

Accepted return values stack types:

1. int - integer; by default maps into big.Int
2. cell - map to BoC
3. slice - load slice
4. [TODO] tuple

Accepted types to map from or into in format field:

1. addr - MsgAddress slice type
2. bool - map int to boolean
3. uint8, uint16, uint32, uint64 - map int to an unsigned integer
4. bigInt - map integer bigger than 64 bits
5. string - load string snake from cell
6. content - load TEP-64 standard token data into nft.ContentAny

Known contracts

1. TEP-62 NFT Standard: interfaces, description, contract code
2. TEP-74 Fungible tokens (Jettons) standard: interfaces, description, contract code
3. TEP-81 DNS contracts: interface, description
4. TEP-85 NFT SBT tokens: interfaces, description
5. Telemint contracts: interfaces, contract code
6. Getgems contracts: contract code
7. Wallets: interfaces, tonweb
8. STON.fi DEX: architecture, contract code
9. Megaton.fi DEX: architecture
10. Tonpay: go-sdk, js-sdk

Documentation

Index

• Variables
• func GetMethodHashes(code *cell.Cell) ([]int32, error)
• func HasGetMethod(code *cell.Cell, getMethodName string) bool
• func MethodNameHash(name string) int32
• type ContractName
• type Emulator
  • func NewEmulator(addr *address.Address, code, data, cfg *cell.Cell) (*Emulator, error)
  • func (e *Emulator) RunGetMethod(ctx context.Context, method string, args VmStack, retDesc []VmValueDesc) (ret VmStack, err error)
• type GetMethodDesc
• type InterfaceDesc
  • func (i *InterfaceDesc) RegisterDefinitions() error
• type OperationDesc
  • func NewOperationDesc(x any) (*OperationDesc, error)
  • func (d *OperationDesc) New() (any, error)
• type StackType
• type StringSnake
  • func (x *StringSnake) LoadFromCell(loader *cell.Slice) error
• type TLBFieldDesc
• type TLBFieldsDesc
  • func NewTLBDesc(x any) (TLBFieldsDesc, error)
  • func (d TLBFieldsDesc) New() (any, error)
• type TelemintText
  • func (x *TelemintText) LoadFromCell(loader *cell.Slice) error
• type VmStack
• type VmValue
• type VmValueDesc

Variables

var ErrWrongValueFormat = errors.New("wrong value for this format")

Functions

func GetMethodHashes

func GetMethodHashes(code *cell.Cell) ([]int32, error)

func HasGetMethod

func HasGetMethod(code *cell.Cell, getMethodName string) bool

func MethodNameHash

func MethodNameHash(name string) int32

Types

type ContractName

type ContractName string

type Emulator

type Emulator struct {
	Emulator  *tvm.Emulator
	AccountID tongo.AccountID
}

func NewEmulator

func NewEmulator(addr *address.Address, code, data, cfg *cell.Cell) (*Emulator, error)

func (*Emulator) RunGetMethod

func (e *Emulator) RunGetMethod(ctx context.Context, method string, args VmStack, retDesc []VmValueDesc) (ret VmStack, err error)

type GetMethodDesc

type GetMethodDesc struct {
	Name         string        `json:"name"`
	Arguments    []VmValueDesc `json:"arguments,omitempty"`
	ReturnValues []VmValueDesc `json:"return_values"`
}

type InterfaceDesc

type InterfaceDesc struct {
	Name         ContractName             `json:"interface_name"`
	Addresses    []*addr.Address          `json:"addresses,omitempty"`
	CodeBoc      string                   `json:"code_boc,omitempty"`
	Definitions  map[string]TLBFieldsDesc `json:"definitions,omitempty"`
	InMessages   []OperationDesc          `json:"in_messages,omitempty"`
	OutMessages  []OperationDesc          `json:"out_messages,omitempty"`
	GetMethods   []GetMethodDesc          `json:"get_methods,omitempty"`
	ContractData TLBFieldsDesc            `json:"contract_data,omitempty"`
}

func (*InterfaceDesc) RegisterDefinitions

func (i *InterfaceDesc) RegisterDefinitions() error

type OperationDesc

type OperationDesc struct {
	Name string        `json:"op_name"`
	Code string        `json:"op_code"`
	Body TLBFieldsDesc `json:"body"`
}

func NewOperationDesc

func NewOperationDesc(x any) (*OperationDesc, error)

func (*OperationDesc) New

func (d *OperationDesc) New() (any, error)

type StackType

type StackType string

const (
	VmInt   StackType = "int"
	VmCell  StackType = "cell"
	VmSlice StackType = "slice"
)

const (
	VmAddrSlice   StackType = "addr"
	VmBool        StackType = "bool"
	VmBigInt      StackType = "bigInt"
	VmStringCell  StackType = "string"
	VmContentCell StackType = "content"
)

formats

type StringSnake

type StringSnake string

func (*StringSnake) LoadFromCell

func (x *StringSnake) LoadFromCell(loader *cell.Slice) error

type TLBFieldDesc

type TLBFieldDesc struct {
	Name   string        `json:"name"`
	Type   string        `json:"tlb_type"`
	Format string        `json:"format"`
	Fields TLBFieldsDesc `json:"struct_fields,omitempty"` // Format = "struct"
}

type TLBFieldsDesc

type TLBFieldsDesc []TLBFieldDesc

func NewTLBDesc

func NewTLBDesc(x any) (TLBFieldsDesc, error)

func (TLBFieldsDesc) New

func (d TLBFieldsDesc) New() (any, error)

type TelemintText

type TelemintText struct {
	Len  uint8  // ## 8
	Text string // bits (len * 8)
}

func (*TelemintText) LoadFromCell

func (x *TelemintText) LoadFromCell(loader *cell.Slice) error

type VmStack

type VmStack []VmValue

type VmValue

type VmValue struct {
	VmValueDesc
	Payload any
}

type VmValueDesc

type VmValueDesc struct {
	Name      string    `json:"name"`
	StackType StackType `json:"stack_type"`
	Format    StackType `json:"format"`
}