Near RPC Providers

Near JSON RPC Provider compatible with ethers.js

Install

npm i near-rpc-providers

Usage

Node

// JavaScript
const { NearRpcProvider } = require('near-rpc-providers')

// TypeScript
import { NearRpcProvider } from 'near-rpc-providers'

Browser

Include the ESM module (near-rpc-providers.esm.js) and import using:

<script type="module">
  import { NearRpcProvider } from './near-rpc-providers.esm.js'
</script>

API

The NearRpcProvider is an extension over a regular JsonRpcProvider which is a popular method for interacting with the blockchain.

Initializing

// Use a network name of chainId to initialize, see src/networks.ts
const nearRpcProvider = new NearRpcProvider('near')

Methods

Block Number

Returns the block number of the latest block

const blockNumber = await nearRpcProvider.getBlockNumber()

Call a Contract Function

Allows you to call a contract method as a view function.

const contractResponse = await nearRpcProvider.contractCall(
  'example.testnet', 'latest', 'getMessages', 'e30='
)

Get an Account Balance

Returns a BigNumber representing the balance on the provided account

const balance = await nearRpcProvider.getBalance('example.testnet')

Get an Access Key

Returns information about a single access key for given account.

const accessKey = await nearRpcProvider.getAccessKey(
  'example.testnet',
  'ed25519:H9k5eiU4xXS3M4z8HzKJSLaZdqGdGwBG49o7orNC4eZW',
  75866664,
)

Get an Access Key List

Returns all access keys for a given account. You can querying it by finality:

const accessKeyList = await nearRpcProvider.getAccessKeyList('example.testnet', 'latest')

By block_height:

const accessKeyList = await nearRpcProvider.getAccessKeyList('example.testnet', 27912554)

Or by block_hash:

const accessKeyList = await nearRpcProvider.getAccessKeyList(
  'example.testnet', '3Xz2wM9rigMXzA2c5vgCP8wTgFBaePucgUmVYPkMqhRL'
)

Get Block

Use Get Block With Chunk instead of this method.

Get Block With Chunk

Returns block for given finality:

const block = await nearRpcProvider.getBlockWithChunk({
  finality: 'final' })

Or block_id:

const block = await nearRpcProvider.getBlockWithChunk({ 
  block_id: '81k9ked5s34zh13EjJt26mxw5npa485SY4UNoPi6yYLo',
})

Get Chunk Details

Returns details of a specific chunk. You can get the chunk details by chunk_id:

const chunk = await nearRpcProvider.getChunkDetails({
  chunk_id: 'EBM2qg5cGr47EjMPtH88uvmXHDHqmWPzKaQadbWhdw22',
})

Or by block_id and shard_id:

const chunk = await nearRpcProvider.getChunkDetails({
  block_id: 58934027, 
  shard_id: 0,
})

Get Contract Code

Return the code encoded in base64. You can get the contract code by block_hash:

const code = await nearRpcProvider.getCode(
  'example.testnet', '4fzLVR8cfyRDi5hDstYQy73eoxMJdWsH72KM6N9TmYmq'
)

Or by block_tag:

const code = await nearRpcProvider.getCode('example.testnet', 'latest')

Get Contract State

Returns the state of a contract based on the key prefix (base64 encoded). You can get it by block_tag:

const state = await nearRpcProvider.getContractState('example.testnet', 'latest')

By block_height:

const state = await nearRpcProvider.getContractState('example.testnet', 58934027)

Or block_hash:

const state = await nearRpcProvider.getContractState(
  'example.testnet', '3Xz2wM9rigMXzA2c5vgCP8wTgFBaePucgUmVYPkMqhRL'
)

Get Default Provider

Returns the default provider.

const defaultProvider = getDefaultProvider({
  name: 'neartestnet',
  chainId: parseInt(Buffer.from('testnet').toString('hex'), 16),
})

Get Gas Price

Returns a BigNumber representing the current gasPrice

const gasPrice = await nearRpcProvider.getGasPrice()

Get Network Info

Returns the current state of node network connections.

const network = await nearRpcProvider.getNetworkInfo()

Get Validator Status

Returns details and the state of validation on the blockchain. It must be used with an array of block_hash:

const validator = await nearRpcProvider.getValidatorStatus(
  ['FiG2nMjjue3YdgYAyM3ZqWXSaG6RJj5Gk7hvY8vrEoGw']
)

block_height:

const validator = await nearRpcProvider.getValidatorStatus([17791098])

Or null:

const validator = await nearRpcProvider.getValidatorStatus([null])

Send Transaction

Sends a transaction to be executed asynchronously. Returns a transaction that can be waited for using transaction.wait()

const transaction = await nearRpcProvider.sendTransaction(
  'DgAAAHNlbmRlci50ZXN0bmV0AOrmAai64SZOv9e/naX4W15pJx0GAap35wTT1T/DwcbbDwAAAAAAAAAQAAAAcmVjZWl2ZXIudGVzdG5ldNMnL7URB1cxPOu3G8jTqlEwlcasagIbKlAJlF5ywVFLAQAAAAMAAACh7czOG8LTAAAAAAAAAGQcOG03xVSFQFjoagOb4NBBqWhERnnz45LY4+52JgZhm1iQKz7qAdPByrGFDQhQ2Mfga8RlbysuQ8D8LlA6bQE=',
)

const receipt = await tx.wait()

Send

Allows sending a request directly to the NEAR RPC, using the given method and params.

See https://docs.near.org/docs/api/rpc for all available options

const blockResponse = await this.send<BlockRpcResponse>('block', { block_id: params.block_id })

Sign a transaction

Return a transaction signed.

const [hash, signedTransaction] = await getSignedTransaction(nearRpcProvider)

After to get the signed transaction, you'll be able to execute that signed transaction:

const txString = Buffer.from(signedTransaction.encode()).toString('base64')
const response = await nearRpcProvider.sendTransaction(txString)

Running a NEAR network locally

Follow the documentation here to set up a NEAR network locally on your machine using Kurtosis.

Change Log

See Changelog for more information.

Contributing

Contributions welcome! See Contributing.

Collaborators

• Jose Ramirez, Twitter, NPM
• Brian Zuker
• Ana Riera

Acknowledgements

This project was kindly sponsored by Near.

License

Licensed under the MIT - see the LICENSE file for details.