rnsjs

Project description

This is a rerefence document for rnsjs—a JavaScript library for interacting with the Ronin Name Service (RNS). With rnsjs, your dApp can support forward resolution (RNS name to Ronin address) and reverse resolution (Ronin address to RNS name).

Who this project is for

This project is intended for dApp developers building on the Ronin blockchain.

Project dependencies

Before using rnsjs, ensure you have:

• Node.js
• npm

Instructions for using rnsjs

Get started with rnsjs by installing the library.

Install the library

Install @roninnetwork/rnsjs, alongside ethers.

npm install @roninnetwork/rnsjs ethers

Create an RNS instance

import { RNS } from '@roninnetwork/rnsjs'
import { JsonRpcProvider } from "@ethersproject/providers"
import { ethers } from 'ethers'

const provider = new JsonRpcProvider(providerUrl) // Use wallet provider if you want

const RNSInstance = new RNS()
await RNSInstance.setProvider(provider, chainId as number)

Batch function calls

The batch function is a significant part of this library. You can use it in a wide range of situations.

Note: Only functions with the GeneratedRawFunction type can be batched together.

/* Batch functions can be called like this, with the function as the first item in an array and the following items being the function's arguments */
const batched = await RNSInstance.batch(
  RNSInstance.getAddr.batch('test.ron'),
)

/* The response is formatted as follows:
  [
    response1,
    response2,
    response3,
    ...etc,
  ]
*/

Use custom graph node URIs

If you want to use your own graph-node URI, such as a local graph-node URI, you can pass it through when creating a new RNS instance. Alternatively, if you don't want to use the graph at all, you can pass through null.

import { RNS } from '@roninnetwork/rnsjs'

/* If you want to use a custom URI */
const RNSInstance = new RNS({
  graphURI: 'http://localhost:8000/subgraphs/name/graphprotocol/rns',
})

/* If you want to disable the graph queries */
const RNSInstance = new RNS({ graphURI: null })

Write transaction options

Some write functions have an options argument that allows you to pass an address or index for an account array to ethers for specifying the signer of the transaction.

Internal structure

Raw functions

Raw functions are crucial to how rnsjs works. You need to define both raw and decode functions in the function file, with the export being an object with those properties.

This way, the encoding and decoding of contract calls can be split, letting you batch multiple calls together.

To call a raw function, the raw and decode functions are stitched together with a provider call. This is done using the importGenerator function, which is explained in the next section.

importGenerator

The importGenerator function generates a wrapped function for any given input.

The result of the wrapped function obfuscates rnsjs processing and exposes a cleaner API to the user and developer.

We do this to achieve the following:

1. Pass through all the required variables for the function.
2. Split individual functions from the main class.
3. Dynamically load functions and their dependencies.
4. Allow each function's dependencies to be imported regularly.
5. Remove duplicate code.
6. Make it easier to isolate errors.
7. Stitch raw and decode functions together.

ContractManager

The contract manager is where all the contracts are dynamically loaded in and resolved based on the network.

A new instance of ContractManager is created every time you switch providers.

GqlManager

The GQL manager is used as to separate the reliance of rnsjs from GQL. It only loads in GQL when it is needed, or not at all if specified in the constructor of the RNS class. Very simply, it just exposes the core functions needed for rnsjs which can then be accessed.

Individual functions

Utils

Utils can be imported as follows:

import { encodeContenthash } from '@roninnetwork/rnsjs'

getName

Gets the primary name for a specified address.

Input:

• address: string
• Target address

Output:

• name: string | null
• Resolved name

getAddr

Gets owner address for a specified name.

Input:

• name: string
• Target name

Output:

• string | null
• Address record value