parser

type ABIAlias ¶

type ABIAlias struct {
	Name             string               `json:"name"`
	TyIdx            int                  `json:"ty_idx"`
	TargetTyIdx      int                  `json:"target_ty_idx"`
	TypeParams       []string             `json:"type_params,omitempty"`
	CustomPackUnpack ABICustomSerializers `json:"custom_pack_unpack,omitempty"`
	Description      string               `json:"description,omitempty"`
}

ABIAlias represents a Tolk type alias. Examples:

> type UserId = int32 A simple alias, target_ty = { kind: 'intN', n: 32 }

> type Maybe<T> = MaybeNothing | MaybeJust<T> A generic alias (has type_params), target_ty = { kind: 'union', variants: ... }

An alias is serialized as its target, unless it has custom serializers in Tolk code.

type ABIAliasInstantiation ¶

type ABIAliasInstantiation struct {
	TyIdx                  int                  `json:"ty_idx"`
	AliasName              string               `json:"alias_name"`
	MonomorphicTargetTyIdx int                  `json:"monomorphic_target_ty_idx"`
	CustomPackUnpack       ABICustomSerializers `json:"custom_pack_unpack,omitempty"`
}

ABIAliasInstantiation is a resolved runtime shape for a generic alias. For example, we have `type Maybe<T> = None | Just<T>`, and somewhere `Maybe<int>` is used. Then `Maybe<int>` is present in `unique_types` as `AliasRef "Maybe" type_args=int", and its instantiated target = "None | Just<int>" exists here. Without monomorphization, client-side cannot reconstruct stack layout in case of generic nullables/unions.

type ABICustomSerializers ¶ added in v1.22.0

type ABICustomSerializers struct {
	PackToBuilder   bool `json:"pack_to_builder"`
	UnpackFromSlice bool `json:"unpack_from_slice"`
}

ABICustomSerializers is present in a struct/alias if that type has custom serializers in Tolk code:

fun SomeType.packToBuilder(self, mutate b: builder) { ... } fun SomeType.unpackFromSlice(mutate s: slice): SomeAlias { ... }

Body of these functions is not a part of ABI (it's arbitrary Tolk code). To make serialization work (e.g., in TypeScript wrappers), one should provide equivalent implementations in a language ABI is applied to.

type ABIDeclaration ¶

type ABIDeclaration struct {
	SumType           ABIDeclarationKind `json:"kind"`
	StructDeclaration ABIStruct
	AliasDeclaration  ABIAlias
	EnumDeclaration   ABIEnum
}

func (d ABIDeclaration) MarshalJSON() ([]byte, error)

func (d *ABIDeclaration) UnmarshalJSON(b []byte) error

type ABIDeclarationKind ¶

type ABIDeclarationKind string

const (
	DeclarationKindStruct ABIDeclarationKind = "struct"
	DeclarationKindAlias  ABIDeclarationKind = "alias"
	DeclarationKindEnum   ABIDeclarationKind = "enum"
)

type ABIEnum ¶

type ABIEnum struct {
	Name             string               `json:"name"`
	TyIdx            int                  `json:"ty_idx"`
	EncodedAsTyIdx   int                  `json:"encoded_as_ty_idx"`
	Members          []ABIEnumMember      `json:"members"`
	CustomPackUnpack ABICustomSerializers `json:"custom_pack_unpack,omitempty"`
	Description      string               `json:"description,omitempty"`
}

ABIEnum represents a Tolk enum. Examples:

> enum Color { Red, Green, Blue } Has 3 members (values '0', '1', '2'), encoded as 'uint2' (auto-calculated by the compiler).

> enum Mode: int8 { User = 0, Admin = 127 } Has 2 members, encoded as 'int8' (specified manually).

type ABIEnumMember ¶

type ABIEnumMember struct {
	Name  string `json:"name"`
	Value BigInt `json:"value"`
}

type ABIExternalMessage ¶

type ABIExternalMessage struct {
	BodyTyIdx int `json:"body_ty_idx"`
}

ABIExternalMessage is "an incoming external message" (handled by `onExternalMessage`). It's either a 'slice' or some struct. Message descriptions live on corresponding declarations.

type ABIGetMethod ¶

type ABIGetMethod struct {
	TVMMethodID int                     `json:"tvm_method_id"`
	Name        string                  `json:"name"`
	Parameters  []ABIGetMethodParameter `json:"parameters"`
	ReturnTyIdx int                     `json:"return_ty_idx"`
	Description string                  `json:"description,omitempty"`
}

ABIGetMethod is a "get method" (aka "contract getter"). In Tolk code, getters are created with `get fun`. Example: > get fun calcData(owner: address): SomeStruct { ... } It has one parameter with ty = { kind: 'address' }, its return_ty is { kind: 'StructRef', struct_name: 'SomeStruct' }. Note, that getters are called off-chain — via the TVM stack, not via serialization. (For instance, they can return 'int' or 'slice', although they are not serializable)

type ABIGetMethodParameter ¶

type ABIGetMethodParameter struct {
	Name        string `json:"name"`
	TyIdx       int    `json:"ty_idx"`
	Description string `json:"description,omitempty"`
}

type ABIIndex ¶

type ABIIndex struct {
	UniqueTypes          []Ty
	StructInstantiations []ABIStructInstantiation
	AliasInstantiations  []ABIAliasInstantiation
	Structs              map[string]ABIStruct
	Aliases              map[string]ABIAlias
	Enums                map[string]ABIEnum
}

func NewABIIndex(abi ContractABI) *ABIIndex

func (idx *ABIIndex) AliasTargetOf(tyIdx int) (targetTyIdx int, uLabelTyIdx *int, err error)

func (idx *ABIIndex) GetAlias(name string) (ABIAlias, error)

func (idx *ABIIndex) GetAliasTarget(name string) (int, error)

func (idx *ABIIndex) MsgName(bodyTyIdx int) (string, error)

func (idx *ABIIndex) RenderTy(tyIdx int) (string, error)

func (idx *ABIIndex) StructFieldsOf(tyIdx int, isForStack bool) ([]FieldView, error)

func (idx *ABIIndex) TyByIdx(tyIdx int) (Ty, error)

func (idx *ABIIndex) TyIdxOf(ty Ty) (int, bool)

type ABIInternalMessage ¶

type ABIInternalMessage struct {
	BodyTyIdx int `json:"body_ty_idx"`
}

ABIInternalMessage is "an incoming internal message" (handled by `onInternalMessage`). In practice, a user describes each message as a struct: > struct (0x12345678) Increment { ... } > struct (0x23456789) Reset { ... } Then, ABI of a contract will contain those two messages: * body_ty = { kind: 'StructRef', struct_name: 'Increment' } * body_ty = { kind: 'StructRef', struct_name: 'Reset' } Theoretically, body_ty can be something else: e.g., instantiation `Transfer<ForwardPayload>`. Message descriptions live on corresponding declarations.

type ABIOutgoingMessage ¶

type ABIOutgoingMessage struct {
	BodyTyIdx int `json:"body_ty_idx"`
}

ABIOutgoingMessage is "an outgoing internal/external message". In Tolk code, those are calls to `createMessage`. Message descriptions live on corresponding declarations.

type ABIStorage ¶

type ABIStorage struct {
	StorageTyIdx             *int `json:"storage_ty_idx,omitempty"`
	StorageAtDeploymentTyIdx *int `json:"storage_at_deployment_ty_idx,omitempty"`
}

ABIStorage defines shape of a storage. Most often, it's a regular struct, serializable into a cell. In the case of NFT, when a storage changes its shape (several fields appear after deployment), the "initial storage" can also be expressed: it's called "storage at deployment". The storage is used to visualize current contract state and to calculate its address. Storage descriptions live on corresponding declarations

type ABIStruct ¶

type ABIStruct struct {
	Name             string               `json:"name"`
	TyIdx            int                  `json:"ty_idx"`
	TypeParams       []string             `json:"type_params,omitempty"`
	Prefix           *Prefix              `json:"prefix,omitempty"`
	Fields           []Field              `json:"fields"`
	CustomPackUnpack ABICustomSerializers `json:"custom_pack_unpack,omitempty"`
	Description      string               `json:"description,omitempty"`
}

ABIStruct represents a Tolk struct. Examples:

> struct Point { x: int, y: int } A simple struct, not serializable (because 'int', not 'int8' or similar)

> struct Wrapper<TItem> { item: TItem } A generic struct (has type_params), fields[0].ty = { kind: 'genericT', name_t: 'TItem' }

> struct (0x12345678) Increment { ... } Has a serialization prefix: prefix_num = 0x12345678, prefix_len = 32

A field can have `@abi.clientType(<type>)` annotation to override how it's rendered in explorers/UI. Then the field has `client_ty_idx` set. It's used for wrappers (serialization), but not for stack.

type ABIStructInstantiation ¶

type ABIStructInstantiation struct {
	TyIdx                  int                  `json:"ty_idx"`
	StructName             string               `json:"struct_name"`
	MonomorphicFieldsTyIdx []int                `json:"monomorphic_fields_ty_idx"`
	CustomPackUnpack       ABICustomSerializers `json:"custom_pack_unpack,omitempty"`
}

ABIStructInstantiation is a resolved runtime shape for a generic struct. For example, we have `struct Wrapper<T> { item: T }`, and somewhere `Wrapper<Point>` is used. Then `Wrapper<Point>` is present in `unique_types` as `StructRef "Wrapper" type_args=Point", and its instantiated fields types = ["Point"] exist here. Without monomorphization, client-side cannot reconstruct stack layout in case of generic nullables/unions.

type ABIThrownError ¶

type ABIThrownError struct {
	Kind        ABIThrownErrorKind `json:"kind"`
	Name        string             `json:"name,omitempty"`
	Description string             `json:"description,omitempty"`
	ErrCode     int                `json:"err_code"`
}

ABIThrownError is an errCode fired by `throw` or `assert` in Tolk code. Example: > assert (valid) throw ErrCodes.NoAccess; Then { kind: 'enum_member', name: 'ErrCodes.NoAccess', err_code: 123 } exists. Description is `///` comment in Tolk code above a constant or an enum member.

type ABIThrownErrorKind ¶

type ABIThrownErrorKind string

const (
	ABIThrownError_PlainInt   ABIThrownErrorKind = "plain_int"
	ABIThrownError_Constant   ABIThrownErrorKind = "constant"
	ABIThrownError_EnumMember ABIThrownErrorKind = "enum_member"
)

type AliasRef ¶

type AliasRef struct {
	AliasName     string `json:"alias_name"`
	TypeArgsTyIdx []int  `json:"type_args_ty_idx,omitempty"`
}

type ArrayOf ¶ added in v1.22.0

type ArrayOf struct {
	InnerTyIdx int `json:"inner_ty_idx"`
}

type BigInt ¶

type BigInt struct {
	big.Int
}

BigInt wraps big.Int for JSON marshaling with string-number supports

func (b BigInt) MarshalJSON() ([]byte, error)

func (b *BigInt) UnmarshalJSON(p []byte) error

type BitsN ¶

type BitsN struct {
	N int `json:"n"`
}

type CellOf ¶

type CellOf struct {
	InnerTyIdx int `json:"inner_ty_idx"`
}

type ContractABI ¶

type ContractABI struct {
	ABISchemaVersion string `json:"abi_schema_version,omitempty"`
	ContractName     string `json:"contract_name"`
	Author           string `json:"author,omitempty"`
	Version          string `json:"version,omitempty"`
	Description      string `json:"description,omitempty"`

	UniqueTypes          []Ty                     `json:"unique_types"`
	StructInstantiations []ABIStructInstantiation `json:"struct_instantiations"`
	AliasInstantiations  []ABIAliasInstantiation  `json:"alias_instantiations"`
	Declarations         []ABIDeclaration         `json:"declarations"`

	Storage          ABIStorage           `json:"storage"`
	IncomingMessages []ABIInternalMessage `json:"incoming_messages"`
	IncomingExternal []ABIExternalMessage `json:"incoming_external"`
	OutgoingMessages []ABIOutgoingMessage `json:"outgoing_messages"`
	EmittedEvents    []ABIOutgoingMessage `json:"emitted_events"`
	GetMethods       []ABIGetMethod       `json:"get_methods"`
	ThrownErrors     []ABIThrownError     `json:"thrown_errors"`

	CompilerName    string `json:"compiler_name"`
	CompilerVersion string `json:"compiler_version"`
}

ContractABI is a final result — the ABI of a TON smart contract.

Partially, its properties may be specified by a user manually: > contract MyName { > author: "Dima" > incomingMessages: SomeUnion > }

Partially, its properties are automatically calculated by the compiler: - outgoingMessages, via the calls to `createMessage` - thrownErrors, via `throw` and `assert` statements - getMethods, essentially `get fun`

Doc comments from Tolk code come as descriptions: > /// Desc of struct > struct SomeOutgoingMessage { > /// Desc of field > field: int32 > }

While collecting messages/getters/etc., the compiler gathers unique_types and emits them separately. They are referred to as `body_ty_idx`, `return_ty_idx`, etc.

type EnumRef ¶

type EnumRef struct {
	EnumName string `json:"enum_name"`
}

type Field ¶

type Field struct {
	Name        string `json:"name"`
	TyIdx       int    `json:"ty_idx"`
	ClientTyIdx *int   `json:"client_ty_idx,omitempty"`
	Description string `json:"description,omitempty"`
}

type FieldView ¶

type FieldView struct {
	Field
	ULabelTyIdx *int
}

type GenericT ¶

type GenericT struct {
	NameT string `json:"name_t"`
}

type IntN ¶

type IntN struct {
	N int `json:"n"`
}

type LispListOf ¶ added in v1.22.0

type LispListOf struct {
	InnerTyIdx int `json:"inner_ty_idx"`
}

type MapKV ¶ added in v1.22.0

type MapKV struct {
	KeyTyIdx   int `json:"key_ty_idx"`
	ValueTyIdx int `json:"value_ty_idx"`
}

type Nullable ¶

type Nullable struct {
	InnerTyIdx  int `json:"inner_ty_idx"`
	StackTypeId int `json:"stack_type_id,omitempty"`
	StackWidth  int `json:"stack_width,omitempty"`
}

type Prefix ¶

type Prefix struct {
	PrefixNum int `json:"prefix_num"`
	PrefixLen int `json:"prefix_len"`
}

type ShapedTuple ¶ added in v1.22.0

type ShapedTuple struct {
	ItemsTyIdx []int `json:"items_ty_idx"`
}

type StructRef ¶

type StructRef struct {
	StructName    string `json:"struct_name"`
	TypeArgsTyIdx []int  `json:"type_args_ty_idx,omitempty"`
}

type Tensor ¶

type Tensor struct {
	ItemsTyIdx []int `json:"items_ty_idx"`
}

type Ty ¶

type Ty struct {
	SumType     TyKind `json:"kind"`
	IntN        *IntN
	UintN       *UintN
	VarIntN     *VarIntN
	VarUintN    *VarUintN
	BitsN       *BitsN
	Nullable    *Nullable
	CellOf      *CellOf
	ArrayOf     *ArrayOf
	LispListOf  *LispListOf
	Tensor      *Tensor
	ShapedTuple *ShapedTuple
	MapKV       *MapKV
	EnumRef     *EnumRef
	StructRef   *StructRef
	AliasRef    *AliasRef
	GenericT    *GenericT
	Union       *Union
}

func (t *Ty) GetFixedSize() (int, bool)

func (t *Ty) MarshalJSON() ([]byte, error)

func (t *Ty) UnmarshalJSON(b []byte) error

type TyKind ¶ added in v1.22.0

type TyKind = string

const (
	TyKindInt         TyKind = "int"
	TyKindIntN        TyKind = "intN"
	TyKindUintN       TyKind = "uintN"
	TyKindVarIntN     TyKind = "varintN"
	TyKindVarUintN    TyKind = "varuintN"
	TyKindCoins       TyKind = "coins"
	TyKindBool        TyKind = "bool"
	TyKindCell        TyKind = "cell"
	TyKindBuilder     TyKind = "builder"
	TyKindSlice       TyKind = "slice"
	TyKindString      TyKind = "string"
	TyKindRemaining   TyKind = "remaining"
	TyKindAddress     TyKind = "address"
	TyKindAddressOpt  TyKind = "addressOpt"
	TyKindAddressExt  TyKind = "addressExt"
	TyKindAddressAny  TyKind = "addressAny"
	TyKindBitsN       TyKind = "bitsN"
	TyKindNullLiteral TyKind = "nullLiteral"
	TyKindCallable    TyKind = "callable"
	TyKindVoid        TyKind = "void"
	TyKindUnknown     TyKind = "unknown"
	TyKindNullable    TyKind = "nullable"
	TyKindCellOf      TyKind = "cellOf"
	TyKindArrayOf     TyKind = "arrayOf"
	TyKindLispListOf  TyKind = "lispListOf"
	TyKindTensor      TyKind = "tensor"
	TyKindShapedTuple TyKind = "shapedTuple"
	TyKindMapKV       TyKind = "mapKV"
	TyKindEnumRef     TyKind = "EnumRef"
	TyKindStructRef   TyKind = "StructRef"
	TyKindAliasRef    TyKind = "AliasRef"
	TyKindGenericT    TyKind = "genericT"
	TyKindUnion       TyKind = "union"
)

type UintN ¶

type UintN struct {
	N int `json:"n"`
}

type Union ¶

type Union struct {
	Variants   []UnionVariant `json:"variants"`
	StackWidth int            `json:"stack_width,omitempty"`
}

type UnionVariant ¶

type UnionVariant struct {
	VariantTyIdx     int  `json:"variant_ty_idx"`
	PrefixNum        int  `json:"prefix_num"`
	PrefixLen        int  `json:"prefix_len"`
	IsPrefixImplicit bool `json:"is_prefix_implicit,omitempty"`
	StackTypeId      int  `json:"stack_type_id,omitempty"`
	StackWidth       int  `json:"stack_width,omitempty"`
}

type VarIntN ¶

type VarIntN struct {
	N int `json:"n"`
}

type VarUintN ¶

type VarUintN struct {
	N int `json:"n"`
}