client

package
v0.78.4 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2021 License: MIT Imports: 29 Imported by: 0

Documentation

Overview

Package client implements NEO-specific JSON-RPC 2.0 client. This package is currently in alpha and is subject to change.

Client

After creating a client instance with or without a ClientConfig you can interact with the NEO blockchain by its exposed methods.

Some of the methods also allow to pass a verbose bool. This will return a more pretty printed response from the server instead of a raw hex string.

TODO: 

Add missing methods to client.
Allow client to connect using client cert.
More in-depth examples.

Supported methods 

getaccountstate
getalltransfertx
getapplicationlog
getassetstate
getbestblockhash
getblock
getblockcount
getblockhash
getblockheader
getblocksysfee
getclaimable
getconnectioncount
getcontractstate
getnep5balances
getnep5transfers
getpeers
getrawmempool
getrawtransaction
getstorage
gettransactionheight
gettxout
getunclaimed
getunspents
getutxotransfers
getvalidators
getversion
invoke
invokefunction
invokescript
sendrawtransaction
submitblock
validateaddress

Unsupported methods 

claimgas
dumpprivkey
getbalance
getmetricblocktimestamp
getnewaddress
getunclaimedgas
getwalletheight
importprivkey
listaddress
listplugins
sendfrom
sendmany
sendtoaddress
Example 
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/nspcc-dev/neo-go/pkg/rpc/client"
)

func main() {
	endpoint := "http://seed5.bridgeprotocol.io:10332"
	opts := client.Options{}

	c, err := client.New(context.TODO(), endpoint, opts)
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}

	if err := c.Ping(); err != nil {
		fmt.Println(err)
		os.Exit(1)
	}

	resp, err := c.GetAccountState("ATySFJAbLW7QHsZGHScLhxq6EyNBxx3eFP")
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
	fmt.Println(resp.ScriptHash)
	fmt.Println(resp.Balances)
}

Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

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

Client represents the middleman for executing JSON RPC calls to remote NEO RPC nodes.

func New 

func New(ctx context.Context, endpoint string, opts Options) (*Client, error)

New returns a new Client ready to use.

func (*Client) CalculateInputs 

func (c *Client) CalculateInputs(address string, asset util.Uint256, cost util.Fixed8) ([]transaction.Input, util.Fixed8, error)

CalculateInputs implements request.BalanceGetter interface and returns inputs array for the specified amount of given asset belonging to specified address. This implementation uses GetUnspents JSON-RPC call internally, so make sure your RPC server supports that.

func (*Client) GetAccountState 

func (c *Client) GetAccountState(address string) (*result.AccountState, error)

GetAccountState returns detailed information about a NEO account.

func (*Client) GetAllTransferTx added in v0.78.0 

func (c *Client) GetAllTransferTx(acc util.Uint160, start, end uint32, limit, page int) ([]result.TransferTx, error)

GetAllTransferTx returns all transfer transactions for a given account within specified timestamps (by block time) with specified output limits and page. It only works with neo-go 0.78.0+ servers.

func (*Client) GetApplicationLog 

func (c *Client) GetApplicationLog(hash util.Uint256) (*result.ApplicationLog, error)

GetApplicationLog returns the contract log based on the specified txid.

func (*Client) GetAssetState 

func (c *Client) GetAssetState(hash util.Uint256) (*result.AssetState, error)

GetAssetState queries the asset information, based on the specified asset number.

func (*Client) GetBestBlockHash 

func (c *Client) GetBestBlockHash() (util.Uint256, error)

GetBestBlockHash returns the hash of the tallest block in the main chain.

func (*Client) GetBlockByHash 

func (c *Client) GetBlockByHash(hash util.Uint256) (*block.Block, error)

GetBlockByHash returns a block by its hash.

func (*Client) GetBlockByHashVerbose 

func (c *Client) GetBlockByHashVerbose(hash util.Uint256) (*result.Block, error)

GetBlockByHashVerbose returns a block wrapper with additional metadata by its hash.

func (*Client) GetBlockByIndex 

func (c *Client) GetBlockByIndex(index uint32) (*block.Block, error)

GetBlockByIndex returns a block by its height.

func (*Client) GetBlockByIndexVerbose 

func (c *Client) GetBlockByIndexVerbose(index uint32) (*result.Block, error)

GetBlockByIndexVerbose returns a block wrapper with additional metadata by its height. NOTE: to get transaction.ID and transaction.Size, use t.Hash() and io.GetVarSize(t) respectively.

func (*Client) GetBlockCount 

func (c *Client) GetBlockCount() (uint32, error)

GetBlockCount returns the number of blocks in the main chain.

func (*Client) GetBlockHash 

func (c *Client) GetBlockHash(index uint32) (util.Uint256, error)

GetBlockHash returns the hash value of the corresponding block, based on the specified index.

func (*Client) GetBlockHeader 

func (c *Client) GetBlockHeader(hash util.Uint256) (*block.Header, error)

GetBlockHeader returns the corresponding block header information from serialized hex string according to the specified script hash.

func (*Client) GetBlockHeaderVerbose 

func (c *Client) GetBlockHeaderVerbose(hash util.Uint256) (*result.Header, error)

GetBlockHeaderVerbose returns the corresponding block header information from Json format string according to the specified script hash.

func (*Client) GetBlockSysFee 

func (c *Client) GetBlockSysFee(index uint32) (util.Fixed8, error)

GetBlockSysFee returns the system fees of the block, based on the specified index.

func (*Client) GetBlockTransferTxByHash added in v0.78.2 

func (c *Client) GetBlockTransferTxByHash(hash util.Uint256) ([]result.TransferTx, error)

GetBlockTransferTxByHash returns all transfer transactions from a block. It only works with neo-go 0.79.0+ servers.

func (*Client) GetBlockTransferTxByIndex added in v0.78.2 

func (c *Client) GetBlockTransferTxByIndex(index uint32) ([]result.TransferTx, error)

GetBlockTransferTxByIndex returns all transfer transactions from a block. It only works with neo-go 0.79.0+ servers.

func (*Client) GetClaimable 

func (c *Client) GetClaimable(address string) (*result.ClaimableInfo, error)

GetClaimable returns tx outputs which can be claimed.

func (*Client) GetConnectionCount 

func (c *Client) GetConnectionCount() (int, error)

GetConnectionCount returns the current number of connections for the node.

func (*Client) GetContractState 

func (c *Client) GetContractState(hash util.Uint160) (*result.ContractState, error)

GetContractState queries contract information, according to the contract script hash.

func (*Client) GetNEP5Balances 

func (c *Client) GetNEP5Balances(address util.Uint160) (*result.NEP5Balances, error)

GetNEP5Balances is a wrapper for getnep5balances RPC.

func (*Client) GetNEP5Transfers 

func (c *Client) GetNEP5Transfers(address string, start, stop *uint32, limit, page *int) (*result.NEP5Transfers, error)

GetNEP5Transfers is a wrapper for getnep5transfers RPC. Address parameter is mandatory, while all the others are optional. Start and stop parameters are supported since neo-go 0.77.0 and limit and page since neo-go 0.78.0. These parameters are positional in the JSON-RPC call, you can't specify limit and not specify start/stop for example.

func (*Client) GetPeers 

func (c *Client) GetPeers() (*result.GetPeers, error)

GetPeers returns the list of nodes that the node is currently connected/disconnected from.

func (*Client) GetProof added in v0.76.0 

func (c *Client) GetProof(root util.Uint256, sc util.Uint160, key []byte) (*result.GetProof, error)

GetProof returns proof that key belongs to a contract sc state rooted at root.

func (*Client) GetRawMemPool 

func (c *Client) GetRawMemPool() ([]util.Uint256, error)

GetRawMemPool returns the list of unconfirmed transactions in memory.

func (*Client) GetRawTransaction 

func (c *Client) GetRawTransaction(hash util.Uint256) (*transaction.Transaction, error)

GetRawTransaction returns a transaction by hash.

func (*Client) GetRawTransactionVerbose 

func (c *Client) GetRawTransactionVerbose(hash util.Uint256) (*result.TransactionOutputRaw, error)

GetRawTransactionVerbose returns a transaction wrapper with additional metadata by transaction's hash. NOTE: to get transaction.ID and transaction.Size, use t.Hash() and io.GetVarSize(t) respectively.

func (*Client) GetStateHeight added in v0.76.0 

func (c *Client) GetStateHeight() (*result.StateHeight, error)

GetStateHeight returns current block and state height.

func (*Client) GetStateRootByHash added in v0.76.0 

func (c *Client) GetStateRootByHash(h util.Uint256) (*state.MPTRootState, error)

GetStateRootByHash returns state root for the given block hash.

func (*Client) GetStateRootByHeight added in v0.76.0 

func (c *Client) GetStateRootByHeight(h uint32) (*state.MPTRootState, error)

GetStateRootByHeight returns state root for the given height.

func (*Client) GetStorage 

func (c *Client) GetStorage(hash util.Uint160, key []byte) ([]byte, error)

GetStorage returns the stored value, according to the contract script hash and the stored key.

func (*Client) GetTransactionHeight 

func (c *Client) GetTransactionHeight(hash util.Uint256) (uint32, error)

GetTransactionHeight returns the block index in which the transaction is found.

func (*Client) GetTxOut 

func (c *Client) GetTxOut(hash util.Uint256, num int) (*result.TransactionOutput, error)

GetTxOut returns the corresponding unspent transaction output information (returned change), based on the specified hash and index.

func (*Client) GetUTXOTransfers added in v0.78.0 

func (c *Client) GetUTXOTransfers(address string, start, stop *uint32, limit, page *int) (*result.GetUTXO, error)

GetUTXOTransfers is a wrapper for getutxoransfers RPC. Address parameter is mandatory, while all the others are optional. It's only supported since neo-go 0.77.0 with limit and page parameters only since neo-go 0.78.0. These parameters are positional in the JSON-RPC call, you can't specify limit and not specify start/stop for example.

func (*Client) GetUnclaimed 

func (c *Client) GetUnclaimed(address string) (*result.Unclaimed, error)

GetUnclaimed returns unclaimed GAS amount of the specified address.

func (*Client) GetUnspents 

func (c *Client) GetUnspents(address string) (*result.Unspents, error)

GetUnspents returns UTXOs for the given NEO account.

func (*Client) GetValidators 

func (c *Client) GetValidators() ([]result.Validator, error)

GetValidators returns the current NEO consensus nodes information and voting status.

func (*Client) GetVersion 

func (c *Client) GetVersion() (*result.Version, error)

GetVersion returns the version information about the queried node.

func (*Client) Invoke 

func (c *Client) Invoke(script string, params []smartcontract.Parameter, hashesForVerifying []util.Uint160) (*result.Invoke, error)

Invoke returns the results after calling the smart contract scripthash with the given parameters. NOTE: this is test invoke and will not affect the blockchain.

func (*Client) InvokeFunction 

func (c *Client) InvokeFunction(script, operation string, params []smartcontract.Parameter, hashesForVerifying []util.Uint160) (*result.Invoke, error)

InvokeFunction returns the results after calling the smart contract scripthash with the given operation and parameters. NOTE: this is test invoke and will not affect the blockchain.

func (*Client) InvokeScript 

func (c *Client) InvokeScript(script string, hashesForVerifying []util.Uint160) (*result.Invoke, error)

InvokeScript returns the result of the given script after running it true the VM. NOTE: This is a test invoke and will not affect the blockchain.

func (*Client) NEP5BalanceOf 

func (c *Client) NEP5BalanceOf(tokenHash util.Uint160) (int64, error)

NEP5BalanceOf invokes `balanceOf` NEP5 method on a specified contract.

func (*Client) NEP5Decimals 

func (c *Client) NEP5Decimals(tokenHash util.Uint160) (int64, error)

NEP5Decimals invokes `decimals` NEP5 method on a specified contract.

func (*Client) NEP5Name 

func (c *Client) NEP5Name(tokenHash util.Uint160) (string, error)

NEP5Name invokes `name` NEP5 method on a specified contract.

func (*Client) NEP5Symbol 

func (c *Client) NEP5Symbol(tokenHash util.Uint160) (string, error)

NEP5Symbol invokes `symbol` NEP5 method on a specified contract.

func (*Client) NEP5TokenInfo 

func (c *Client) NEP5TokenInfo(tokenHash util.Uint160) (*wallet.Token, error)

NEP5TokenInfo returns full NEP5 token info.

func (*Client) NEP5TotalSupply 

func (c *Client) NEP5TotalSupply(tokenHash util.Uint160) (int64, error)

NEP5TotalSupply invokes `totalSupply` NEP5 method on a specified contract.

func (*Client) Ping 

func (c *Client) Ping() error

Ping attempts to create a connection to the endpoint. and returns an error if there is one.

func (*Client) SendRawTransaction 

func (c *Client) SendRawTransaction(rawTX *transaction.Transaction) error

SendRawTransaction broadcasts a transaction over the NEO network. The given hex string needs to be signed with a keypair. When the result of the response object is true, the TX has successfully been broadcasted to the network.

func (*Client) SetWIF 

func (c *Client) SetWIF(wif string) error

SetWIF decodes given WIF and adds some wallet data to client. Useful for RPC calls that require an open wallet.

func (*Client) SignAndPushInvocationTx 

func (c *Client) SignAndPushInvocationTx(script []byte, acc *wallet.Account, sysfee util.Fixed8, netfee util.Fixed8) (util.Uint256, error)

SignAndPushInvocationTx signs and pushes given script as an invocation transaction using given wif to sign it and spending the amount of gas specified. It returns a hash of the invocation transaction and an error.

func (*Client) SubmitBlock 

func (c *Client) SubmitBlock(b block.Block) error

SubmitBlock broadcasts a raw block over the NEO network.

func (*Client) TransferAsset 

func (c *Client) TransferAsset(asset util.Uint256, address string, amount util.Fixed8) (util.Uint256, error)

TransferAsset sends an amount of specific asset to a given address. This call requires open wallet. (`wif` key in client struct.) If response.Result is `true` then transaction was formed correctly and was written in blockchain.

func (*Client) TransferNEP5 

func (c *Client) TransferNEP5(acc *wallet.Account, to util.Uint160, token *wallet.Token, amount int64, gas util.Fixed8) (util.Uint256, error)

TransferNEP5 creates an invocation transaction that invokes 'transfer' method on a given token to move specified amount of NEP5 assets (in FixedN format using contract's number of decimals) to given account.

func (*Client) ValidateAddress 

func (c *Client) ValidateAddress(address string) error

ValidateAddress verifies that the address is a correct NEO address.

func (*Client) VerifyProof added in v0.76.0 

func (c *Client) VerifyProof(root util.Uint256, proof *result.ProofWithKey) (*result.VerifyProof, error)

VerifyProof verifies keyed proof for the state with the specified root.

func (*Client) WIF 

func (c *Client) WIF() keys.WIF

WIF returns WIF structure associated with the client.

type NeoScanBalance 

type NeoScanBalance struct {
	Balance []*Unspent
	Address string
}

NeoScanBalance is a struct of NeoScan response to 'get_balance' request

type NeoScanServer 

type NeoScanServer struct {
	URL  string // "protocol://host:port/"
	Path string // path to API endpoint without wallet address
}

NeoScanServer stores NEOSCAN URL and API path.

func (NeoScanServer) CalculateInputs 

func (s NeoScanServer) CalculateInputs(address string, assetIDUint util.Uint256, cost util.Fixed8) ([]transaction.Input, util.Fixed8, error)

CalculateInputs creates input transactions for the specified amount of given asset belonging to specified address.

func (NeoScanServer) GetBalance 

func (s NeoScanServer) GetBalance(address string) ([]*Unspent, error)

GetBalance performs a request to get balance for the address specified.

type Notification added in v0.75.0 

type Notification struct {
	Type  response.EventID
	Value interface{}
}

Notification represents server-generated notification for client subscriptions. Value can be one of block.Block, result.ApplicationLog, result.NotificationEvent or transaction.Transaction based on Type.

type Options 

type Options struct {
	// Balancer is an implementation of request.BalanceGetter interface,
	// if not set then the default Client's implementation will be used, but
	// it relies on server support for `getunspents` RPC call which is
	// standard for neo-go, but only implemented as a plugin for C# node. So
	// you can override it here to use NeoScanServer for example.
	Balancer request.BalanceGetter

	// Cert is a client-side certificate, it doesn't work at the moment along
	// with the other two options below.
	Cert           string
	Key            string
	CACert         string
	DialTimeout    time.Duration
	RequestTimeout time.Duration
}

Options defines options for the RPC client. All values are optional. If any duration is not specified a default of 4 seconds will be used.

type Unspent 

type Unspent struct {
	Unspent state.UnspentBalances
	Asset   string      // "NEO" / "GAS"
	Amount  util.Fixed8 // total unspent of this asset
}

Unspent stores Unspents per asset

type WSClient added in v0.75.0 

type WSClient struct {
	Client
	// Notifications is a channel that is used to send events received from
	// server. Client's code is supposed to be reading from this channel if
	// it wants to use subscription mechanism, failing to do so will cause
	// WSClient to block even regular requests. This channel is not buffered.
	// In case of protocol error or upon connection closure this channel will
	// be closed, so make sure to handle this.
	Notifications chan Notification
	// contains filtered or unexported fields
}

WSClient is a websocket-enabled RPC client that can be used with appropriate servers. It's supposed to be faster than Client because it has persistent connection to the server and at the same time is exposes some functionality that is only provided via websockets (like event subscription mechanism).

func NewWS added in v0.75.0 

func NewWS(ctx context.Context, endpoint string, opts Options) (*WSClient, error)

NewWS returns a new WSClient ready to use (with established websocket connection). You need to use websocket URL for it like `ws://1.2.3.4/ws`.

func (*WSClient) Close added in v0.75.0 

func (c *WSClient) Close()

Close closes connection to the remote side rendering this client instance unusable.

func (*WSClient) SubscribeForExecutionNotifications added in v0.75.0 

func (c *WSClient) SubscribeForExecutionNotifications(contract *util.Uint160) (string, error)

SubscribeForExecutionNotifications adds subscription for notifications generated during transaction execution to this instance of client. It can be filtered by contract's hash (that emits notifications), nil value puts no such restrictions.

func (*WSClient) SubscribeForNewBlocks added in v0.75.0 

func (c *WSClient) SubscribeForNewBlocks() (string, error)

SubscribeForNewBlocks adds subscription for new block events to this instance of client.

func (*WSClient) SubscribeForNewTransactions added in v0.75.0 

func (c *WSClient) SubscribeForNewTransactions(txType *transaction.TXType) (string, error)

SubscribeForNewTransactions adds subscription for new transaction events to this instance of client. It can be filtered by transaction type, nil value is treated as missing filter.

func (*WSClient) SubscribeForTransactionExecutions added in v0.75.0 

func (c *WSClient) SubscribeForTransactionExecutions(state *string) (string, error)

SubscribeForTransactionExecutions adds subscription for application execution results generated during transaction execution to this instance of client. Can be filtered by state (HALT/FAULT) to check for successful or failing transactions, nil value means no filtering.

func (*WSClient) Unsubscribe added in v0.75.0 

func (c *WSClient) Unsubscribe(id string) error

Unsubscribe removes subscription for given event stream.

func (*WSClient) UnsubscribeAll added in v0.75.0 

func (c *WSClient) UnsubscribeAll() error

UnsubscribeAll removes all active subscriptions of current client.

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.