rpc

package
v0.61.1-pre Latest Latest
Warning

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

 Go to latest Published: Nov 1, 2019 License: MIT Imports: 30 Imported by: 0

Documentation

Overview

Package rpc implements NEO-specific JSON-RPC 2.0 client and server. 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.

An example: 

  endpoint := "http://seed5.bridgeprotocol.io:10332"
  opts := rpc.ClientOptions{}

  client, err := rpc.NewClient(context.TODO(), endpoint, opts)
  if err != nil {
	  log.Fatal(err)
  }

  if err := client.Ping(); err != nil {
	  log.Fatal(err)
  }

  resp, err := client.GetAccountState("ATySFJAbLW7QHsZGHScLhxq6EyNBxx3eFP")
  if err != nil {
	  log.Fatal(err)
  }
  log.Println(resp.Result.ScriptHash)
  log.Println(resp.Result.Balances)

TODO: 

Merge structs so can be used by both server and client.
Add missing methods to client.
Allow client to connect using client cert.
More in-depth examples.

Supported methods 

getblock
getaccountstate
invokescript
invokefunction
sendrawtransaction
invoke
getrawtransaction

Unsupported methods 

validateaddress
getblocksysfee
getcontractstate
getrawmempool
getstorage
submitblock
gettxout
getassetstate
getpeers
getversion
getconnectioncount
getblockhash
getblockcount
getbestblockhash

Server

The server is written to support as much of the JSON-RPC 2.0 Spec as possible. The server is run as part of the node currently.

TODO: 

Implement HTTPS server.
Add remaining methods (Documented below).
Add Swagger spec and test using dredd in circleCI.

Example call

An example would be viewing the version of the node: 

$ curl -X POST -d '{"jsonrpc": "2.0", "method": "getversion", "params": [], "id": 1}' http://localhost:20332

which would yield the response: 

{
  "jsonrpc" : "2.0",
    "id" : 1,
    "result" : {
      "port" : 20333,
      "useragent" : "/NEO-GO:0.36.0-dev/",
      "nonce" : 9318417
    }
}

Unsupported methods 

getblocksysfee
getcontractstate (needs to be implemented in pkg/core/blockchain.go)
getrawmempool (needs to be implemented on in pkg/network/server.go)
getrawtransaction (needs to be implemented in pkg/core/blockchain.go)
getstorage (lacks VM functionality)
gettxout (needs to be implemented in pkg/core/blockchain.go)
invoke (lacks VM functionality)
invokefunction (lacks VM functionality)
invokescript (lacks VM functionality)
sendrawtransaction (needs to be implemented in pkg/core/blockchain.go)
submitblock (needs to be implemented in pkg/core/blockchain.go)

Index

Constants

This section is empty.

Variables

View Source 
var GlobalAssets = map[string]string{
	"c56f33fc6ecfcd0c225c4ab356fee59390af8560be0e930faebe74a6daff7c9b": "NEO",
	"602c79718b16e442de58778e148d0b1084e3b2dffd5de6b7b16cee7969282de7": "GAS",
}

GlobalAssets stores a map of asset IDs to user-friendly strings ("NEO"/"GAS").

Functions

func CreateRawContractTransaction 

func CreateRawContractTransaction(params ContractTxParams) (*transaction.Transaction, error)

CreateRawContractTransaction returns contract-type Transaction built from specified parameters.

func GetInvocationScript 

func GetInvocationScript(tx *transaction.Transaction, wif keys.WIF) ([]byte, error)

GetInvocationScript returns NEO VM script containing transaction signature.

Types

type Account 

type Account struct {
	Version    int    `json:"version"`
	ScriptHash string `json:"script_hash"`
	Frozen     bool
	// TODO: need to check this field out.
	Votes    []interface{}
	Balances []*Balance
}

Account represents details about a NEO account.

type AccountStateResponse 

type AccountStateResponse struct {
	Result *Account `json:"result"`
	// contains filtered or unexported fields
}

AccountStateResponse holds the getaccountstate response.

type Balance 

type Balance struct {
	Asset string `json:"asset"`
	Value string `json:"value"`
}

Balance represents details about a NEO account balance.

type BalanceGetter 

type BalanceGetter interface {
	// 		parameters
	// address: 	base58-encoded address assets would be transferred from
	// assetID: 	asset identifier
	// amount: 		an asset amount to spend
	// 		return values
	// inputs: 		UTXO's for the preparing transaction
	// total: 		summarized asset amount from all the `inputs`
	// error: 		error would be considered in the caller function
	CalculateInputs(address string, assetID util.Uint256, amount util.Fixed8) (inputs []transaction.Input, total util.Fixed8, err error)
}

BalanceGetter is an interface supporting CalculateInputs() method.

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 NewClient 

func NewClient(ctx context.Context, endpoint string, opts ClientOptions) (*Client, error)

NewClient returns a new Client ready to use.

func (*Client) Balancer 

func (c *Client) Balancer() BalanceGetter

Balancer is a getter for balance field.

func (*Client) Client 

func (c *Client) Client() *http.Client

Client is a getter for client field.

func (*Client) GetAccountState 

func (c *Client) GetAccountState(address string) (*AccountStateResponse, error)

GetAccountState returns detailed information about a NEO account.

func (*Client) Invoke 

func (c *Client) Invoke(script string, params []smartcontract.Parameter) (*InvokeScriptResponse, error)

Invoke returns the results after calling the smart contract scripthash with the given parameters.

func (*Client) InvokeFunction 

func (c *Client) InvokeFunction(script, operation string, params []smartcontract.Parameter) (*InvokeScriptResponse, 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) (*InvokeScriptResponse, 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) 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) SendToAddress 

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

SendToAddress 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) SetBalancer 

func (c *Client) SetBalancer(b BalanceGetter)

SetBalancer is a setter for balance field.

func (*Client) SetClient 

func (c *Client) SetClient(cli *http.Client)

SetClient is a setter for client field.

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) WIF 

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

WIF returns WIF structure associated with the client.

type ClientOptions 

type ClientOptions struct {
	Cert        string
	Key         string
	CACert      string
	DialTimeout time.Duration
	Client      *http.Client
	// Version is the version of the client that will be send
	// along with the request body. If no version is specified
	// the default version (currently 2.0) will be used.
	Version string
}

ClientOptions defines options for the RPC client. All Values are optional. If any duration is not specified a default of 3 seconds will be used.

type ContractTxParams 

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

ContractTxParams contains parameters for tx to transfer assets; includes parameters duplication `sendtoaddress` RPC call params and also some utility data;

type Error 

type Error struct {
	Code     int64  `json:"code"`
	HTTPCode int    `json:"-"`
	Cause    error  `json:"-"`
	Message  string `json:"message"`
	Data     string `json:"data,omitempty"`
}

Error object for outputting JSON-RPC 2.0 errors.

func NewInternalServerError 

func NewInternalServerError(data string, cause error) *Error

NewInternalServerError creates a new error with code -32603.

func NewInvalidParamsError 

func NewInvalidParamsError(data string, cause error) *Error

NewInvalidParamsError creates a new error with code -32602.

func NewInvalidRequestError 

func NewInvalidRequestError(data string, cause error) *Error

NewInvalidRequestError creates a new error with code -32600.

func NewMethodNotFoundError 

func NewMethodNotFoundError(data string, cause error) *Error

NewMethodNotFoundError creates a new error with code -32601.

func NewParseError 

func NewParseError(data string, cause error) *Error

NewParseError creates a new error with code -32700.:%s

func (Error) Error 

func (e Error) Error() string

Error implements the error interface.

type GetRawTxResponse 

type GetRawTxResponse struct {
	Error  *Error         `json:"error"`
	Result *RawTxResponse `json:"result"`
	// contains filtered or unexported fields
}

GetRawTxResponse represents verbose output of `getrawtransaction` RPC call.

type InvokeResult 

type InvokeResult struct {
	State       vm.State `json:"state"`
	GasConsumed string   `json:"gas_consumed"`
	Script      string   `json:"script"`
	Stack       []StackParam
}

InvokeResult represents the outcome of a script that is executed by the NEO VM.

type InvokeScriptResponse 

type InvokeScriptResponse struct {
	Error  *Error        `json:"error,omitempty"`
	Result *InvokeResult `json:"result,omitempty"`
	// contains filtered or unexported fields
}

InvokeScriptResponse stores response for the invoke script call.

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 Param 

type Param struct {
	StringVal string
	IntVal    int
	Type      string
	RawValue  interface{}
}

Param represents a param either passed to the server or to send to a server using the client.

func (Param) String 

func (p Param) String() string

type Params 

type Params []Param

Params represents the JSON-RPC params.

func (*Params) UnmarshalJSON 

func (p *Params) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the Unmarshaller interface.

func (Params) Value 

func (p Params) Value(index int) (*Param, error)

Value returns the param struct for the given index if it exists.

func (Params) ValueAt 

func (p Params) ValueAt(index int) (*Param, bool)

ValueAt returns the param struct for the given index if it exists.

func (Params) ValueAtAndType 

func (p Params) ValueAtAndType(index int, valueType string) (*Param, bool)

ValueAtAndType returns the param struct at the given index if it exists and matches the given type.

func (Params) ValueWithType 

func (p Params) ValueWithType(index int, valType string) (*Param, error)

ValueWithType returns the param struct at the given index if it exists and matches the given type.

type RawTxResponse 

type RawTxResponse struct {
	TxResponse
	BlockHash     string `json:"blockhash"`
	Confirmations uint   `json:"confirmations"`
	BlockTime     uint   `json:"blocktime"`
}

RawTxResponse stores transaction with blockchain metadata to be sent as a response.

type Request 

type Request struct {
	JSONRPC   string          `json:"jsonrpc"`
	Method    string          `json:"method"`
	RawParams json.RawMessage `json:"params,omitempty"`
	RawID     json.RawMessage `json:"id,omitempty"`
	// contains filtered or unexported fields
}

Request represents a standard JSON-RPC 2.0 request: http://www.jsonrpc.org/specification#request_object.

func NewRequest 

func NewRequest(corsWorkaround bool) *Request

NewRequest creates a new Request struct.

func (*Request) DecodeData 

func (r *Request) DecodeData(data io.ReadCloser) error

DecodeData decodes the given reader into the the request struct.

func (*Request) Params 

func (r *Request) Params() (*Params, error)

Params takes a slice of any type and attempts to bind the params to it.

func (Request) WriteErrorResponse 

func (r Request) WriteErrorResponse(w http.ResponseWriter, err error)

WriteErrorResponse writes an error response to the ResponseWriter.

func (Request) WriteResponse 

func (r Request) WriteResponse(w http.ResponseWriter, result interface{})

WriteResponse encodes the response and writes it to the ResponseWriter.

type Response 

type Response struct {
	JSONRPC string          `json:"jsonrpc"`
	Result  interface{}     `json:"result,omitempty"`
	Error   *Error          `json:"error,omitempty"`
	ID      json.RawMessage `json:"id,omitempty"`
}

Response represents a standard JSON-RPC 2.0 response: http://www.jsonrpc.org/specification#response_object.

type SendToAddressResponse 

type SendToAddressResponse struct {
	Error  *Error `json:"error"`
	Result *TxResponse
	// contains filtered or unexported fields
}

SendToAddressResponse stores response for the sendtoaddress call.

type Server 

type Server struct {
	*http.Server
	// contains filtered or unexported fields
}

Server represents the JSON-RPC 2.0 server.

func NewServer 

func NewServer(chain core.Blockchainer, conf config.RPCConfig, coreServer *network.Server) Server

NewServer creates a new Server struct.

func (*Server) Shutdown 

func (s *Server) Shutdown() error

Shutdown overrides the http.Server Shutdown method.

func (*Server) Start 

func (s *Server) Start(errChan chan error)

Start creates a new JSON-RPC server listening on the configured port.

type StackParam 

type StackParam struct {
	Type  StackParamType `json:"type"`
	Value interface{}    `json:"value"`
}

StackParam represent a stack parameter.

func (StackParam) TryParse 

func (p StackParam) TryParse(dest interface{}) error

TryParse converts one StackParam into something more appropriate.

func (*StackParam) UnmarshalJSON 

func (p *StackParam) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON implements Unmarshaler interface.

type StackParamType 

type StackParamType int

StackParamType represents different types of stack values. 

const (
	Unknown          StackParamType = -1
	Signature        StackParamType = 0x00
	Boolean          StackParamType = 0x01
	Integer          StackParamType = 0x02
	Hash160          StackParamType = 0x03
	Hash256          StackParamType = 0x04
	ByteArray        StackParamType = 0x05
	PublicKey        StackParamType = 0x06
	String           StackParamType = 0x07
	Array            StackParamType = 0x10
	InteropInterface StackParamType = 0xf0
	Void             StackParamType = 0xff
)

All possible StackParamType values are listed here.

func StackParamTypeFromString 

func StackParamTypeFromString(s string) (StackParamType, error)

StackParamTypeFromString converts string into the StackParamType.

func (StackParamType) String 

func (t StackParamType) String() string

String implements the stringer interface.

func (*StackParamType) UnmarshalJSON 

func (t *StackParamType) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON sets StackParamType from JSON-encoded data.

type StackParams 

type StackParams []StackParam

StackParams is an array of StackParam (TODO: drop it?).

func (StackParams) TryParseArray 

func (p StackParams) TryParseArray(vals ...interface{}) error

TryParseArray converts an array of StackParam into an array of more appropriate things.

type TxResponse 

type TxResponse struct {
	TxID       string                  `json:"txid"`
	Size       int                     `json:"size"`
	Type       string                  `json:"type"` // todo: convert to TransactionType
	Version    int                     `json:"version"`
	Attributes []transaction.Attribute `json:"attributes"`
	Vins       []Vin                   `json:"vin"`
	Vouts      []Vout                  `json:"vout"`
	SysFee     int                     `json:"sys_fee"`
	NetFee     int                     `json:"net_fee"`
	Scripts    []transaction.Witness   `json:"scripts"`
}

TxResponse stores transaction to be sent as a response.

type UTXO 

type UTXO struct {
	Value util.Fixed8
	TxID  util.Uint256
	N     uint16
}

UTXO stores unspent TX output for some transaction.

type Unspent 

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

Unspent stores Unspents per asset

type Unspents 

type Unspents []UTXO

Unspents is a slice of UTXOs (TODO: drop it?).

func (Unspents) Len 

func (us Unspents) Len() int

functions for sorting array of `Unspents`

func (Unspents) Less 

func (us Unspents) Less(i, j int) bool

func (Unspents) Swap 

func (us Unspents) Swap(i, j int)

type Vin 

type Vin struct {
	TxID string `json:"txid"`
	Vout int    `json:"vout"`
}

Vin represents JSON-serializable tx input.

type Vout 

type Vout struct {
	N       int    `json:"n"`
	Asset   string `json:"asset"`
	Value   int    `json:"value"`
	Address string `json:"address"`
}

Vout represents JSON-serializable tx output.

Source Files

View all Source files

Directories

Path Synopsis

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.