Skip to main content

rnsjs library reference

Overview​

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

Prerequisites​

Install the rnsjs library along with ethers.js and @ethersproject/providers@5.7.2:

npm install ethers @ethersproject/providers@5.7.2 @roninnetwork/rnsjs

Use rnsjs​

Create an RNS instance​

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

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.getText.batch('test.eth', 'foo'),
  RNSInstance.getAddr.batch('test.eth'),
  RNSInstance.getOwner.batch('test.eth'),
)

/* 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. Otherwise, the default graph is used.

import { RNS } from '@roninnetwork/rnsjs'

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

Use single-call proividers​

If you want to use a specific provider to make a single call occasionally, you can easily do so.

import { RNS } from '@roninnetwork/rnsjs'

const RNSInstance = new RNS()

const callWithProvider = await RNSInstance.withProvider(otherProvider).getText(
  'test.eth',
  'foo',
)

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.

initialProvider​

The initialProvider, and similarly checkInitialProvider are used when creating single-use class instances with withProvider. It allows withProvider to act as a new RNS instance without having to await a promise, which simplifies the API. checkInitialProvider is run on every function call given that it's lightweight.

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 an address record for a specified name.

Input:

  • name: string
  • Target name

Output:

  • string | null
  • Address record value