wallet

package
v1.14.2 Latest Latest
Warning

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

 Go to latest Published: Dec 17, 2024 License: MIT Imports: 15 Imported by: 15

README

Tools to simplify the deployment and interaction with the wallet smart contract

This library supports:

  1. Address generation from public or private keys for V1-V4 wallets
  2. Message generation for deploying new wallets
  3. Message generation for TON transfer (long comment supported) and custom payload (for V1-V4 supports up to 4 payload messages)

Wallets smart contracts description:

Usage

Example

Documentation

Index

Constants

View Source 
const (
	// DefaultSubWallet is a recommended default value of subWalletID according to
	// https://docs.ton.org/develop/smart-contracts/tutorials/wallet#subwallet-ids.
	DefaultSubWallet       = 698983191
	DefaultMessageLifetime = time.Minute * 3
	DefaultMessageMode     = 3
)
View Source 
const MainnetGlobalID = -239
View Source 
const TestnetGlobalID = -3

Variables

View Source 
var (
	ErrAccountIsFrozen         = fmt.Errorf("account is frozen")
	ErrAccountIsNotInitialized = fmt.Errorf("account is not initialized")
)
View Source 
var ErrBadSignature = errors.New("failed to verify msg signature")
View Source 
var WORDLIST = []string{}/* 2048 elements not displayed */

Functions

func GenerateStateInit added in v1.2.1 

func GenerateStateInit(
	key ed25519.PublicKey,
	ver Version,
	networkGlobalID *int32,
	workchain int,
	subWalletId *uint32,
) (tlb.StateInit, error)

func GenerateWalletAddress 

func GenerateWalletAddress(
	key ed25519.PublicKey,
	ver Version,
	networkGlobalID *int32,
	workchain int,
	subWalletId *uint32,
) (ton.AccountID, error)

GenerateWalletAddress Generate wallet address from known workchain, public key and version. subWalletId is only used in V3 and V4 wallets. Use nil for default value. The version number is associated with a specific implementation of the wallet code (https://github.com/toncenter/tonweb/blob/master/src/contract/wallet/WalletSources.md)

func GetCodeByVer 

func GetCodeByVer(ver Version) *boc.Cell

func GetCodeHashByVer 

func GetCodeHashByVer(ver Version) tlb.Bits256

func GetW5BetaExtensionsList added in v1.9.0 

func GetW5BetaExtensionsList(state tlb.ShardAccount) (map[ton.AccountID]struct{}, error)

GetW5BetaExtensionsList returns a list of wallet v5 beta extensions added to a specific wallet.

func GetW5R1ExtensionsList added in v1.9.0 

func GetW5R1ExtensionsList(state tlb.ShardAccount, workchain int) (map[ton.AccountID]struct{}, error)

GetW5R1ExtensionsList returns a list of wallet v5 extensions added to a specific wallet.

func IsMessageModeSet added in v1.1.2 

func IsMessageModeSet(modeValue int, mode MessageMode) bool

func MessageV5VerifySignature added in v1.7.0 

func MessageV5VerifySignature(msgBody boc.Cell, publicKey ed25519.PublicKey) error

func NewWalletV5Beta added in v1.8.16 

func NewWalletV5Beta(version Version, publicKey ed25519.PublicKey, opts Options) *walletV5Beta

func NewWalletV5R1 added in v1.9.0 

func NewWalletV5R1(publicKey ed25519.PublicKey, opts Options) *walletV5R1

func RandomSeed added in v1.0.1 

func RandomSeed() string

func SeedToPrivateKey 

func SeedToPrivateKey(seed string) (ed25519.PrivateKey, error)

func VerifySignature added in v1.2.1 

func VerifySignature(ver Version, msg *boc.Cell, publicKey ed25519.PublicKey) error

VerifySignature checks whether the given message (tlb.Message) represented as a cell was signed by the given public key of a wallet contract. On success, it returns nil. Otherwise, it returns an error.

Types

type ContractDeploy added in v1.11.2 

type ContractDeploy struct {
	Workchain int32
	Code      any
	Data      any
	Body      any
	Amount    tlb.Grams
}

func (ContractDeploy) ToInternal added in v1.11.2 

func (cd ContractDeploy) ToInternal() (tlb.Message, uint8, error)

type DataHighloadV2 added in v1.9.0 

type DataHighloadV2 struct {
	SubWalletId     uint32
	LastCleanedTime uint64
	PublicKey       tlb.Bits256
	Queries         tlb.HashmapE[tlb.Uint64, tlb.Any]
}

DataHighloadV2 represents data of a highload-wallet contract.

type DataV1V2 

type DataV1V2 struct {
	Seqno     uint32
	PublicKey tlb.Bits256
}

type DataV3 

type DataV3 struct {
	Seqno       uint32
	SubWalletId uint32
	PublicKey   tlb.Bits256
}

type DataV4 

type DataV4 struct {
	Seqno       uint32
	SubWalletId uint32
	PublicKey   tlb.Bits256
	PluginDict  tlb.HashmapE[tlb.Bits264, tlb.Any] // TODO: find type and check size
}

type DataV5Beta added in v1.9.0 

type DataV5Beta struct {
	Seqno      tlb.Uint33
	WalletID   WalletV5ID
	PublicKey  tlb.Bits256
	Extensions tlb.HashmapE[tlb.Bits256, tlb.Uint8]
}

type DataV5R1 added in v1.9.0 

type DataV5R1 struct {
	IsSignatureAllowed bool
	Seqno              uint32
	WalletID           uint32
	PublicKey          tlb.Bits256
	Extensions         tlb.HashmapE[tlb.Bits256, tlb.Uint1]
}

type HighloadV2Message added in v1.2.1 

type HighloadV2Message struct {
	SubWalletId    uint32
	BoundedQueryID uint64
	RawMessages    PayloadHighload
}

func DecodeHighloadV2Message added in v1.4.2 

func DecodeHighloadV2Message(msg *boc.Cell) (*HighloadV2Message, error)

type Message 

type Message struct {
	Amount  tlb.Grams
	Address ton.AccountID
	Body    *boc.Cell
	Code    *boc.Cell
	Data    *boc.Cell
	Bounce  bool
	Mode    uint8
}

func (Message) ToInternal added in v1.0.1 

func (m Message) ToInternal() (message tlb.Message, mode uint8, err error)

type MessageConfig added in v1.8.0 

type MessageConfig struct {
	Seqno      uint32
	ValidUntil time.Time
	V5MsgType  V5MsgType
}

type MessageConfigV5 added in v1.8.0 

type MessageConfigV5 struct {
	MsgType V5MsgType
}

type MessageMode added in v1.1.2 

type MessageMode int
const (
	// AttachAllRemainingBalance means that a wallet will transfer all the remaining balance to the destination
	// instead of the value originally indicated in the message.
	AttachAllRemainingBalance MessageMode = 128
	// AttachAllRemainingBalanceOfInboundMessage means that
	// a wallet will transfer all the remaining value of the inbound message in addition to the value initially indicated
	// in the new message
	AttachAllRemainingBalanceOfInboundMessage MessageMode = 64
	// DestroyAccount means that current account must be destroyed if its resulting balance is zero (often used with Mode 128).
	DestroyAccount MessageMode = 32
)

For detailed information about message modes take a look at https://docs.ton.org/develop/smart-contracts/messages.

type MessageV3 

type MessageV3 struct {
	SubWalletId uint32
	ValidUntil  uint32
	Seqno       uint32
	RawMessages PayloadV1toV4
}

func DecodeMessageV3 added in v1.2.1 

func DecodeMessageV3(msg *boc.Cell) (*MessageV3, error)

type MessageV4 

type MessageV4 struct {
	// Op: 0 - simple send, 1 - deploy and install plugin, 2 - install plugin, 3 - remove plugin
	SubWalletId uint32
	ValidUntil  uint32
	Seqno       uint32
	Op          int8
	RawMessages PayloadV1toV4
}

func DecodeMessageV4 added in v1.2.1 

func DecodeMessageV4(msg *boc.Cell) (*MessageV4, error)

type MessageV5 added in v1.7.0 

type MessageV5 struct {
	tlb.SumType
	// SignedInternal is an internal message authenticated by a signature.
	SignedInternal *struct {
		WalletId        uint32
		ValidUntil      uint32
		Seqno           uint32
		Actions         *W5Actions         `tlb:"maybe^"`
		ExtendedActions *W5ExtendedActions `tlb:"maybe"`
		Signature       tlb.Bits512
	} `tlbSumType:"#73696e74"`
	// SignedExternal is an external message authenticated by a signature.
	SignedExternal *struct {
		WalletId        uint32
		ValidUntil      uint32
		Seqno           uint32
		Actions         *W5Actions         `tlb:"maybe^"`
		ExtendedActions *W5ExtendedActions `tlb:"maybe"`
		Signature       tlb.Bits512
	} `tlbSumType:"#7369676e"`
	ExtensionAction *struct {
		QueryID         uint64
		Actions         *W5Actions         `tlb:"maybe^"`
		ExtendedActions *W5ExtendedActions `tlb:"maybe"`
	} `tlbSumType:"#6578746e"`
}

MessageV5 is a message format used by wallet v5.

func DecodeMessageV5 added in v1.7.0 

func DecodeMessageV5(msg *boc.Cell) (*MessageV5, error)

func (*MessageV5) RawMessages added in v1.7.0 

func (m *MessageV5) RawMessages() []RawMessage

type MessageV5Beta added in v1.9.0 

type MessageV5Beta struct {
	tlb.SumType
	// SignedInternal is an internal message authenticated by a signature.
	SignedInternal struct {
		WalletId   tlb.Bits80
		ValidUntil uint32
		Seqno      uint32
		Op         bool
		Signature  tlb.Bits512
		Actions    W5Actions `tlb:"^"`
	} `tlbSumType:"#73696e74"`
	// SignedExternal is an external message authenticated by a signature.
	SignedExternal struct {
		WalletId   tlb.Bits80
		ValidUntil uint32
		Seqno      uint32
		Op         bool
		Signature  tlb.Bits512
		Actions    W5Actions `tlb:"^"`
	} `tlbSumType:"#7369676e"`
}

MessageV5Beta is a message format used by wallet v5 beta.

func DecodeMessageV5Beta added in v1.9.0 

func DecodeMessageV5Beta(msg *boc.Cell) (*MessageV5Beta, error)

func (*MessageV5Beta) RawMessages added in v1.9.0 

func (m *MessageV5Beta) RawMessages() []RawMessage

type NextMsgParams added in v1.8.16 

type NextMsgParams struct {
	Seqno uint32
	Init  *tlb.StateInit
}

type Option added in v1.8.0 

type Option func(*Options)

func WithMessageLifetime added in v1.8.0 

func WithMessageLifetime(lifetime time.Duration) Option

func WithNetworkGlobalID added in v1.8.0 

func WithNetworkGlobalID(id int32) Option

func WithSubWalletID added in v1.8.0 

func WithSubWalletID(id uint32) Option

func WithWorkchain added in v1.8.0 

func WithWorkchain(workchain int) Option

type Options added in v1.8.0 

type Options struct {
	NetworkGlobalID *int32
	Workchain       *int
	SubWalletID     *uint32
	PublicKey       *ed25519.PublicKey
	PrivateKey      *ed25519.PrivateKey
	MsgLifetime     time.Duration
}

type PayloadHighload added in v1.2.1 

type PayloadHighload []RawMessage

func (PayloadHighload) MarshalTLB added in v1.2.1 

func (p PayloadHighload) MarshalTLB(c *boc.Cell, encoder *tlb.Encoder) error

func (*PayloadHighload) UnmarshalTLB added in v1.4.2 

func (p *PayloadHighload) UnmarshalTLB(c *boc.Cell, decoder *tlb.Decoder) error

type PayloadV1toV4 

type PayloadV1toV4 []RawMessage

func (PayloadV1toV4) MarshalTLB 

func (p PayloadV1toV4) MarshalTLB(c *boc.Cell, encoder *tlb.Encoder) error

func (*PayloadV1toV4) UnmarshalTLB 

func (p *PayloadV1toV4) UnmarshalTLB(c *boc.Cell, decoder *tlb.Decoder) error

type RawMessage 

type RawMessage struct {
	Message *boc.Cell
	Mode    byte
}

RawMessage when received by a wallet contract will be resent as an outgoing message.

func ExtractRawMessages added in v1.1.1 

func ExtractRawMessages(ver Version, msg *boc.Cell) ([]RawMessage, error)

ExtractRawMessages extracts a list of RawMessages from an external message.

type Sendable added in v1.0.1 

type Sendable interface {
	ToInternal() (tlb.Message, uint8, error)
}

type SignedMsgBody added in v1.2.1 

type SignedMsgBody struct {
	Sign    tlb.Bits512
	Message tlb.Any
}

SignedMsgBody represents an external message's body sent by an offchain application to a wallet contract. The signature is created using the wallet's private key. So the wallet will verify that it is the recipient of the payload and accept the payload.

func (*SignedMsgBody) Verify added in v1.2.1 

func (body *SignedMsgBody) Verify(publicKey ed25519.PublicKey) error

type SimpleMockBlockchain 

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

SimpleMockBlockchain Very simple mock. It does not provide blockchain logic for calculating state and seqno for different addresses. Only for internal tests and demonstration purposes.

func NewMockBlockchain 

func NewMockBlockchain(seqno uint32, state tlb.ShardAccount) (*SimpleMockBlockchain, chan []byte)

func (*SimpleMockBlockchain) GetAccountState 

func (b *SimpleMockBlockchain) GetAccountState(ctx context.Context, accountID ton.AccountID) (tlb.ShardAccount, error)

func (*SimpleMockBlockchain) GetSeqno 

func (b *SimpleMockBlockchain) GetSeqno(ctx context.Context, account ton.AccountID) (uint32, error)

func (*SimpleMockBlockchain) SendMessage added in v1.0.1 

func (b *SimpleMockBlockchain) SendMessage(ctx context.Context, payload []byte) (uint32, error)

type SimpleTransfer added in v1.0.1 

type SimpleTransfer struct {
	Amount     tlb.Grams
	Address    ton.AccountID
	Comment    string
	Bounceable bool
}

func (SimpleTransfer) ToInternal added in v1.0.1 

func (m SimpleTransfer) ToInternal() (message tlb.Message, mode uint8, err error)

type TextComment 

type TextComment string

func (TextComment) MarshalTLB 

func (t TextComment) MarshalTLB(c *boc.Cell, encoder *tlb.Encoder) error

func (*TextComment) UnmarshalTLB 

func (t *TextComment) UnmarshalTLB(c *boc.Cell, decoder *tlb.Decoder) error

type V5MsgType added in v1.8.0 

type V5MsgType uint32
const (
	V5MsgTypeSignedInternal  V5MsgType = 0x73696e74
	V5MsgTypeSignedExternal  V5MsgType = 0x7369676e
	V5MsgTypeExtensionAction V5MsgType = 0x6578746e
)

type Version 

type Version int
const (
	V1R1 Version = iota
	V1R2
	V1R3
	V2R1
	V2R2
	V3R1
	V3R2
	V3R2Lockup
	V4R1
	V4R2
	V5Beta
	V5R1
	HighLoadV1R1
	HighLoadV1R2
	HighLoadV2
	HighLoadV2R1
	HighLoadV2R2
)

func GetVerByCodeHash 

func GetVerByCodeHash(hash tlb.Bits256) (Version, bool)

GetVerByCodeHash returns (Version, true) if there is code with the given hash. Otherwise, it returns (0, false).

func GetWalletVersion added in v1.4.2 

func GetWalletVersion(state tlb.ShardAccount, msg tlb.Message) (Version, bool, error)

GetWalletVersion returns a wallet version by the given state of an account and an incoming message to the account. An incoming message is needed in case when a wallet has not been initialized yet. In this case, we take its code from the message's StateInit.

func VersionFromString added in v1.12.0 

func VersionFromString(s string) (Version, error)

func (Version) ToString 

func (v Version) ToString() string

type W5Actions added in v1.9.0 

type W5Actions []W5SendMessageAction

func (W5Actions) MarshalTLB added in v1.9.0 

func (l W5Actions) MarshalTLB(c *boc.Cell, encoder *tlb.Encoder) error

func (*W5Actions) UnmarshalTLB added in v1.9.0 

func (l *W5Actions) UnmarshalTLB(c *boc.Cell, decoder *tlb.Decoder) error

type W5ExtendedAction added in v1.9.0 

type W5ExtendedAction struct {
	SumType      tlb.SumType
	AddExtension *struct {
		Addr tlb.MsgAddress
	} `tlbSumType:"add_extension#02"`
	RemoveExtension *struct {
		Addr tlb.MsgAddress
	} `tlbSumType:"remove_extension#03"`
	SetSignatureAllowed *struct {
		Allowed bool
	} `tlbSumType:"set_signature_allowed#04"`
}

type W5ExtendedActions added in v1.9.0 

type W5ExtendedActions []W5ExtendedAction

func (W5ExtendedActions) MarshalTLB added in v1.9.0 

func (extendedActions W5ExtendedActions) MarshalTLB(c *boc.Cell, encoder *tlb.Encoder) error

func (*W5ExtendedActions) UnmarshalTLB added in v1.9.0 

func (extendedActions *W5ExtendedActions) UnmarshalTLB(c *boc.Cell, decoder *tlb.Decoder) error

type W5SendMessageAction added in v1.9.0 

type W5SendMessageAction struct {
	Magic tlb.Magic `tlb:"#0ec3c86d"`
	Mode  uint8
	Msg   *boc.Cell `tlb:"^"`
}

type Wallet 

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

func DefaultWalletFromSeed 

func DefaultWalletFromSeed(seed string, blockchain blockchain) (Wallet, error)

func New added in v1.0.1 

func New(key ed25519.PrivateKey, ver Version, blockchain blockchain, opts ...Option) (Wallet, error)

New Fill new Wallet struct from known workchain, public key and version. subWalletId is only used in V3 and V4 wallets. Use nil for default value. The version number is associated with a specific implementation of the wallet code (https://github.com/toncenter/tonweb/blob/master/src/contract/wallet/WalletSources.md)

func (*Wallet) CreateMessageBody added in v1.8.0 

func (w *Wallet) CreateMessageBody(msgConfig MessageConfig, messages ...Sendable) (*boc.Cell, error)

func (*Wallet) GetAddress 

func (w *Wallet) GetAddress() ton.AccountID

GetAddress returns current wallet address but you can also call function GenerateWalletAddress which returns same address but doesn't require blockchain connection for calling

func (*Wallet) GetBalance 

func (w *Wallet) GetBalance(ctx context.Context) (uint64, error)

GetBalance Gets actual TON balance for wallet

func (*Wallet) RawSend 

func (w *Wallet) RawSend(
	ctx context.Context,
	seqno uint32,
	validUntil time.Time,
	internalMessages []RawMessage,
	init *tlb.StateInit,
) error

RawSend Generates a signed external message for wallet with custom internal messages, seqno, TTL and init The payload is serialized into bytes and sent by the method SendRawMessage

func (*Wallet) RawSendV2 added in v1.2.0 

func (w *Wallet) RawSendV2(
	ctx context.Context,
	seqno uint32,
	validUntil time.Time,
	internalMessages []RawMessage,
	init *tlb.StateInit,
	waitingConfirmation time.Duration,
) (ton.Bits256, error)

func (*Wallet) Send added in v1.0.1 

func (w *Wallet) Send(ctx context.Context, messages ...Sendable) error

Send Generates a signed external message for wallet with custom internal messages and default TTL Gets actual seqno and attach init for wallet if it needed The payload is serialized into bytes and sent by the method SendRawMessage

func (*Wallet) SendV2 added in v1.2.0 

func (w *Wallet) SendV2(ctx context.Context, waitingConfirmation time.Duration, messages ...Sendable) (ton.Bits256, error)

func (*Wallet) StateInit added in v1.8.0 

func (w *Wallet) StateInit() (*tlb.StateInit, error)

type WalletV5ID added in v1.7.1 

type WalletV5ID struct {
	NetworkGlobalID uint32
	Workchain       uint8
	WalletVersion   uint8
	SubWalletID     uint32
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.