api

README

near-api-go

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

• Background
• Install
• Usage
• API
• Maintainers
• Contributing
• License

Install

go get github.com/textileio/near-api-go

Usage

Import the required modules.

import (
  api "github.com/textileio/near-api-go"
  "github.com/textileio/near-api-go/keys"
  "github.com/textileio/near-api-go/transaction"
  "github.com/textileio/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/textileio/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

• type CallFunctionOption
  • func CallFunctionWithArgs(args interface{}) CallFunctionOption
  • func CallFunctionWithBlockHash(blockHash string) CallFunctionOption
  • func CallFunctionWithBlockHeight(blockHeight int) CallFunctionOption
  • func CallFunctionWithFinality(finalaity string) CallFunctionOption
• type CallFunctionResponse
• type Cause
• type Change
• type ChangeData
• type Client
  • func NewClient(config *types.Config) (*Client, error)
  • func (c *Client) Account(accountID string) *account.Account
  • func (c *Client) CallFunction(ctx context.Context, accountID string, methodName string, ...) (*CallFunctionResponse, error)
  • func (c *Client) DataChanges(ctx context.Context, accountIDs []string, opts ...DataChangesOption) (*DataChangesResponse, error)
  • func (c *Client) NodeStatus(ctx context.Context) (*NodeStatusResponse, error)
  • func (c *Client) ViewCode(ctx context.Context, accountID string, opts ...ViewCodeOption) (*ViewCodeResponse, error)
• type DataChangesOption
  • func DataChangesWithBlockHash(blockHash string) DataChangesOption
  • func DataChangesWithBlockHeight(blockHeight int) DataChangesOption
  • func DataChangesWithFinality(finalaity string) DataChangesOption
  • func DataChangesWithPrefix(prefix string) DataChangesOption
• type DataChangesResponse
• type NodeStatusResponse
• type SyncInfo
• type ViewCodeOption
  • func ViewCodeWithBlockHash(blockHash string) ViewCodeOption
  • func ViewCodeWithBlockHeight(blockHeight int) ViewCodeOption
  • func ViewCodeWithFinality(finalaity string) ViewCodeOption
• type ViewCodeResponse

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 *types.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) 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 NodeStatusResponse

type NodeStatusResponse struct {
	SyncInfo *SyncInfo `json:"sync_info"`
}

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"`
}

SyncInfo holds information about the sync status of a node.

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.