api

package module
v0.2.9 Latest Latest
Warning

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

 Go to latest Published: Oct 10, 2021 License: MIT Imports: 10 Imported by: 0

README

near-api-go

standard-readme compliant

A NEAR client written in Go

The goal of this project is to provide a fully featured NEAR cleint in Go. There is support for most NEAR RPC requests, including those that use signed transactions. Of course, there is room for improvement, especially with integration testing and a fully featured KeyStore, so please give it a spin and feel free to open a PR to help us improve the library.

We're currently relying on our fork of go-ethereum's JSON RPC client that adds support for named RPC parameters. That work is pending PR merge into their master branch.

Table of Contents

Install

go get github.com/gateway-fm/near-api-go

Usage

Import the required modules.

import (
  api "github.com/gateway-fm/near-api-go"
  "github.com/gateway-fm/near-api-go/keys"
  "github.com/gateway-fm/near-api-go/transaction"
  "github.com/gateway-fm/near-api-go/types"
  "github.com/ethereum/go-ethereum/rpc"
)

Configure and create an API client.

rpcClient, err := rpc.DialContext(ctx, "https://rpc.testnet.near.org")

keyPair, err := keys.NewKeyPairFromString(
  "ed25519:...",
)

config := &types.Config{
  RPCClient: rpcClient,
  Signer:    keyPair, // Currently we use a key pair directly as a signer.
  NetworkID: "testnet",
}

client, err := api.NewClient(config)

Interact with top level functions like CallFunction, for example. It can be used for calling non-signed "view" functions.

res, err := client.CallFunction(
  ctx,
  "<account id>",
  "myFunction",
  api.CallFunctionWithFinality("final"),
)

Most other functionality is provided by the Account sub module. For example, you can call state-modifying functions that are sent as signed transactions, and even include a deposit while you're at it.

deposit, ok := (&big.Int{}).SetString("1000000000000000000000000", 10)
res, err := client.Account("<client account id>").FunctionCall(
  ctx,
  <contract account id>,
  "myTxnFunction",
  transaction.FunctionCallWithArgs(map[string]interface{}{
    "arg1": value1, 
    "arg2": value2
  }),
  transaction.FunctionCallWithDeposit(*deposit),
)

Check out the API docs to see all that is possible.

API

https://pkg.go.dev/github.com/gateway-fm/near-api-go

Maintainers

@asutula

Contributing

PRs accepted.

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT © 2021 Textile

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CallFunctionOption 

type CallFunctionOption func(*itypes.QueryRequest) error

CallFunctionOption controls the behavior when calling CallFunction.

func CallFunctionWithArgs 

func CallFunctionWithArgs(args interface{}) CallFunctionOption

CallFunctionWithArgs specified the args to call the function with. Should be a JSON encodable object.

func CallFunctionWithBlockHash 

func CallFunctionWithBlockHash(blockHash string) CallFunctionOption

CallFunctionWithBlockHash specifies the block hash to call the function for.

func CallFunctionWithBlockHeight 

func CallFunctionWithBlockHeight(blockHeight int) CallFunctionOption

CallFunctionWithBlockHeight specifies the block height to call the function for.

func CallFunctionWithFinality 

func CallFunctionWithFinality(finalaity string) CallFunctionOption

CallFunctionWithFinality specifies the finality to be used when calling the function.

type CallFunctionResponse 

type CallFunctionResponse struct {
	Result      []byte   `json:"result"`
	Logs        []string `json:"logs"`
	BlockHeight int      `json:"block_height"`
	BlockHash   string   `json:"block_hash"`
}

CallFunctionResponse holds information about the result of a function call.

type Cause 

type Cause struct {
	Type        string `json:"type"`
	ReceiptHash string `json:"receipt_hash"`
}

Cause holds information about the cause of a state change.

type Change 

type Change struct {
	AccountID   string `json:"account_id"`
	KeyBase64   string `json:"key_base64"`
	ValueBase64 string `json:"value_base64"`
}

Change holds information about a state change of a key-value pair.

type ChangeData 

type ChangeData struct {
	Cause  Cause  `json:"cause"`
	Type   string `json:"type"`
	Change Change `json:"change"`
}

ChangeData holds information about a state change.

type Client 

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

Client communicates with the NEAR API.

func NewClient 

func NewClient(config *config.Config) (*Client, error)

NewClient creates a new Client.

func (*Client) Account 

func (c *Client) Account(accountID string) *account.Account

Account provides an API for the provided account ID.

func (*Client) CallFunction 

func (c *Client) CallFunction(
	ctx context.Context,
	accountID string,
	methodName string,
	opts ...CallFunctionOption,
) (*CallFunctionResponse, error)

CallFunction calls a function on a contract.

func (*Client) DataChanges 

func (c *Client) DataChanges(
	ctx context.Context,
	accountIDs []string,
	opts ...DataChangesOption,
) (*DataChangesResponse, error)

DataChanges queries changes to contract data changes.

func (*Client) GetBlockResult added in v0.2.5 

func (c *Client) GetBlockResult(ctx context.Context) (*itypes.BlockResult, error)

func (*Client) GetGasPrice added in v0.2.9 

func (c *Client) GetGasPrice(ctx context.Context, gp *GasPriceOpts) (*itypes.BlockHeader, error)

func (*Client) NetworkInfo 

func (c *Client) NetworkInfo(ctx context.Context) (*models.NetworkInfo, error)

NetworkInfo returns the current state of node network connections (active peers, transmitted data, etc.)

func (*Client) NodeStatus 

func (c *Client) NodeStatus(ctx context.Context) (*NodeStatusResponse, error)

NodeStatus returns the node status.

func (*Client) ViewCode 

func (c *Client) ViewCode(ctx context.Context, accountID string, opts ...ViewCodeOption) (*ViewCodeResponse, error)

ViewCode returns the smart contract code for the provided account id.

type DataChangesOption 

type DataChangesOption func(*itypes.ChangesRequest)

DataChangesOption controls behavior when calling DataChanges.

func DataChangesWithBlockHash 

func DataChangesWithBlockHash(blockHash string) DataChangesOption

DataChangesWithBlockHash specifies the block id to query data changes for.

func DataChangesWithBlockHeight 

func DataChangesWithBlockHeight(blockHeight int) DataChangesOption

DataChangesWithBlockHeight specifies the block id to query data changes for.

func DataChangesWithFinality 

func DataChangesWithFinality(finalaity string) DataChangesOption

DataChangesWithFinality specifies the finality to be used when querying data changes.

func DataChangesWithPrefix 

func DataChangesWithPrefix(prefix string) DataChangesOption

DataChangesWithPrefix sets the data key prefix to query for.

type DataChangesResponse 

type DataChangesResponse struct {
	BlockHash string       `json:"block_hash"`
	Changes   []ChangeData `json:"changes"`
}

DataChangesResponse holds information about all data changes in a block.

type EpochKickout 

type EpochKickout struct {
	AccountID string                 `json:"account_id"`
	Reason    map[string]interface{} `json:"reason"`
}

EpochKickout struct

type Fisherman 

type Fisherman struct {
	AccountID string `json:"account_id"`
	PublicKey string `json:"public_key"`
	Stake     string `json:"stake"`
}

Fisherman struct

type GasPriceOpts added in v0.2.9 

type GasPriceOpts struct {
	Blockheight int64
	Blockhash   string
}

type NodeStatusResponse 

type NodeStatusResponse struct {
	ChainID    string     `json:"chain_id"`
	RPCAddr    string     `json:"rpc_addr"`
	SyncInfo   SyncInfo   `json:"sync_info"`
	Validators Validators `json:"validators"`
	Version    Version    `json:"version"`
}

NodeStatusResponse holds information about node status.

type SyncInfo 

type SyncInfo struct {
	LatestBlockHash   string `json:"latest_block_hash"`
	LatestBlockHeight int    `json:"latest_block_height"`
	// TODO: make this time.Time and use custom json conversion.
	LatestBlockTime string `json:"latest_block_time"`
	LatestStateRoot string `json:"latest_state_root"`
	Syncing         bool   `json:"syncing"`
}

SyncInfo holds information about the sync status of a node.

type Validator 

type Validator struct {
	AccountID         string  `json:"account_id"`
	IsSlashed         bool    `json:"is_slashed"`
	ExpectedBlocksNum int64   `json:"num_expected_blocks,omitempty"`
	ProducedBlocksNum int64   `json:"num_produced_blocks,omitempty"`
	PublicKey         string  `json:"public_key,omitempty"`
	Shards            []int64 `json:"shards,omitempty"`
	Stake             string  `json:"stake,omitempty"`
}

Validator struct

type Validators 

type Validators []Validator

Validators array

type ValidatorsResponse 

type ValidatorsResponse struct {
	CurrentFishermans []Fisherman    `json:"current_fishermen,omitempty"`
	NextFishermans    []Fisherman    `json:"next_fishermen,omitempty"`
	CurrentValidators Validators     `json:"current_validators,omitempty"`
	NextValidators    Validators     `json:"next_validators,omitempty"`
	CurrentProposal   string         `json:"current_proposal,omitempty"`
	EpochStartHeight  int64          `json:"epoch_start_height"`
	PrevEpochKickout  []EpochKickout `json:"prev_epoch_kickout"`
}

ValidatorsResponse struct

type Version 

type Version struct {
	Build   string `json:"build"`
	Version string `json:"version"`
}

Version struct

type ViewCodeOption 

type ViewCodeOption func(*itypes.QueryRequest)

ViewCodeOption controls the behavior when calling ViewCode.

func ViewCodeWithBlockHash 

func ViewCodeWithBlockHash(blockHash string) ViewCodeOption

ViewCodeWithBlockHash specifies the block hash to call the function for.

func ViewCodeWithBlockHeight 

func ViewCodeWithBlockHeight(blockHeight int) ViewCodeOption

ViewCodeWithBlockHeight specifies the block height to call the function for.

func ViewCodeWithFinality 

func ViewCodeWithFinality(finalaity string) ViewCodeOption

ViewCodeWithFinality specifies the finality to be used when calling the function.

type ViewCodeResponse 

type ViewCodeResponse struct {
	CodeBase64  string `json:"code_base64"`
	Hash        string `json:"hash"`
	BlockHeight int    `json:"block_height"`
	BlockHash   string `json:"block_hash"`
}

ViewCodeResponse holds information about contract code.

Source Files

View all Source files

Directories

Path Synopsis
hash
key
signature

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.