nep17

Documentation

Overview

Package nep17 contains RPC wrappers to work with NEP-17 contracts.

Safe methods are encapsulated into TokenReader structure while Token provides various methods to perform the only NEP-17 state-changing call, Transfer.

Index

• type Actor
• type Invoker
• type Token
  • func New(actor Actor, hash util.Uint160) *Token
• type TokenReader
  • func NewReader(invoker Invoker, hash util.Uint160) *TokenReader
• type TokenWriter
  • func (t *TokenWriter) MultiTransfer(params []TransferParameters) (util.Uint256, uint32, error)
  • func (t *TokenWriter) MultiTransferTransaction(params []TransferParameters) (*transaction.Transaction, error)
  • func (t *TokenWriter) MultiTransferUnsigned(params []TransferParameters) (*transaction.Transaction, error)
  • func (t *TokenWriter) Transfer(from util.Uint160, to util.Uint160, amount *big.Int, data any) (util.Uint256, uint32, error)
  • func (t *TokenWriter) TransferTransaction(from util.Uint160, to util.Uint160, amount *big.Int, data any) (*transaction.Transaction, error)
  • func (t *TokenWriter) TransferUnsigned(from util.Uint160, to util.Uint160, amount *big.Int, data any) (*transaction.Transaction, error)
• type TransferEvent
  • func TransferEventsFromApplicationLog(log *result.ApplicationLog) ([]*TransferEvent, error)
  • func (e *TransferEvent) FromStackItem(item *stackitem.Array) error
• type TransferParameters

Examples

• Token
• TokenReader

Types

type Actor

type Actor interface {
	Invoker

	MakeRun(script []byte) (*transaction.Transaction, error)
	MakeUnsignedRun(script []byte, attrs []transaction.Attribute) (*transaction.Transaction, error)
	SendRun(script []byte) (util.Uint256, uint32, error)
}

Actor is used by Token to create and send transactions.

type Invoker

type Invoker interface {
	neptoken.Invoker
}

Invoker is used by TokenReader to call various safe methods.

type Token

type Token struct {
	TokenReader
	TokenWriter
}

Token provides full NEP-17 interface, both safe and state-changing methods.

Example

package main

import (
	"context"
	"math/big"

	"github.com/nspcc-dev/neo-go/pkg/encoding/address"
	"github.com/nspcc-dev/neo-go/pkg/rpcclient"
	"github.com/nspcc-dev/neo-go/pkg/rpcclient/actor"
	"github.com/nspcc-dev/neo-go/pkg/rpcclient/nep17"
	"github.com/nspcc-dev/neo-go/pkg/util"
	"github.com/nspcc-dev/neo-go/pkg/wallet"
)

func main() {
	// No error checking done at all, intentionally.
	w, _ := wallet.NewWalletFromFile("somewhere")
	defer w.Close()

	c, _ := rpcclient.New(context.Background(), "url", rpcclient.Options{})

	// Create a simple CalledByEntry-scoped actor (assuming there is an account
	// inside the wallet).
	a, _ := actor.NewSimple(c, w.Accounts[0])

	// NEP-17 contract hash.
	nep17Hash := util.Uint160{9, 8, 7}

	// Create a complete NEP-17 contract representation.
	n17 := nep17.New(a, nep17Hash)

	tgtAcc, _ := address.StringToUint160("NdypBhqkz2CMMnwxBgvoC9X2XjKF5axgKo")

	// Send a transaction that transfers one token to another account.
	txid, vub, _ := n17.Transfer(a.Sender(), tgtAcc, big.NewInt(1), nil)
	_ = txid
	_ = vub
}

func New

func New(actor Actor, hash util.Uint160) *Token

New creates an instance of Token for contract with the given hash using the given Actor.

type TokenReader

type TokenReader struct {
	neptoken.Base
}

TokenReader represents safe (read-only) methods of NEP-17 token. It can be used to query various data.

Example

package main

import (
	"context"

	"github.com/nspcc-dev/neo-go/pkg/encoding/address"
	"github.com/nspcc-dev/neo-go/pkg/rpcclient"
	"github.com/nspcc-dev/neo-go/pkg/rpcclient/invoker"
	"github.com/nspcc-dev/neo-go/pkg/rpcclient/nep17"
	"github.com/nspcc-dev/neo-go/pkg/util"
)

func main() {
	// No error checking done at all, intentionally.
	c, _ := rpcclient.New(context.Background(), "url", rpcclient.Options{})

	// Safe methods are reachable with just an invoker, no need for an account there.
	inv := invoker.New(c, nil)

	// NEP-17 contract hash.
	nep17Hash := util.Uint160{9, 8, 7}

	// And a reader interface.
	n17 := nep17.NewReader(inv, nep17Hash)

	// Get the metadata. Even though these methods are implemented in neptoken package,
	// they're available for NEP-17 wrappers.
	symbol, _ := n17.Symbol()
	supply, _ := n17.TotalSupply()
	_ = symbol
	_ = supply

	// Account hash we're interested in.
	accHash, _ := address.StringToUint160("NdypBhqkz2CMMnwxBgvoC9X2XjKF5axgKo")

	// Get account balance.
	balance, _ := n17.BalanceOf(accHash)
	_ = balance
}

func NewReader

func NewReader(invoker Invoker, hash util.Uint160) *TokenReader

NewReader creates an instance of TokenReader for contract with the given hash using the given Invoker.

type TokenWriter

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

TokenWriter contains NEP-17 token methods that change state. It's not meant to be used directly (Token that includes it is more convenient) and just separates one set of methods from another to simplify reusing this package for other contracts that extend NEP-17 interface.

func (*TokenWriter) MultiTransfer

func (t *TokenWriter) MultiTransfer(params []TransferParameters) (util.Uint256, uint32, error)

MultiTransfer is not a real NEP-17 method, but rather a convenient way to perform multiple transfers (usually from a single account) in one transaction. It accepts a set of parameters, creates a script that calls `transfer` as many times as needed (with ASSERTs added, so if any of these transfers fail whole transaction (with all transfers) fails). The values returned are the same as in Transfer.

func (*TokenWriter) MultiTransferTransaction

func (t *TokenWriter) MultiTransferTransaction(params []TransferParameters) (*transaction.Transaction, error)

MultiTransferTransaction is similar to MultiTransfer, but returns the same values as TransferTransaction (signed transaction that is not yet sent).

func (*TokenWriter) MultiTransferUnsigned

func (t *TokenWriter) MultiTransferUnsigned(params []TransferParameters) (*transaction.Transaction, error)

MultiTransferUnsigned is similar to MultiTransfer, but returns the same values as TransferUnsigned (not yet signed transaction).

func (*TokenWriter) Transfer

func (t *TokenWriter) Transfer(from util.Uint160, to util.Uint160, amount *big.Int, data any) (util.Uint256, uint32, error)

Transfer creates and sends a transaction that performs a `transfer` method call using the given parameters and checks for this call result, failing the transaction if it's not true. The returned values are transaction hash, its ValidUntilBlock value and an error if any.

func (*TokenWriter) TransferTransaction

func (t *TokenWriter) TransferTransaction(from util.Uint160, to util.Uint160, amount *big.Int, data any) (*transaction.Transaction, error)

TransferTransaction creates a transaction that performs a `transfer` method call using the given parameters and checks for this call result, failing the transaction if it's not true. This transaction is signed, but not sent to the network, instead it's returned to the caller.

func (*TokenWriter) TransferUnsigned

func (t *TokenWriter) TransferUnsigned(from util.Uint160, to util.Uint160, amount *big.Int, data any) (*transaction.Transaction, error)

TransferUnsigned creates a transaction that performs a `transfer` method call using the given parameters and checks for this call result, failing the transaction if it's not true. This transaction is not signed and just returned to the caller.

type TransferEvent

type TransferEvent struct {
	From   util.Uint160
	To     util.Uint160
	Amount *big.Int
}

TransferEvent represents a Transfer event as defined in the NEP-17 standard.

func TransferEventsFromApplicationLog

func TransferEventsFromApplicationLog(log *result.ApplicationLog) ([]*TransferEvent, error)

TransferEventsFromApplicationLog retrieves all emitted TransferEvents from the provided result.ApplicationLog.

func (*TransferEvent) FromStackItem

func (e *TransferEvent) FromStackItem(item *stackitem.Array) error

FromStackItem converts provided stackitem.Array to TransferEvent or returns an error if it's not possible to do to so.

type TransferParameters

type TransferParameters struct {
	From   util.Uint160
	To     util.Uint160
	Amount *big.Int
	Data   any
}

TransferParameters is a set of parameters for `transfer` method.