npm package: @roninnetwork/rnsjs
Description: RNS javascript library for contract interaction
Latest version: 0.2.3

## 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](https://github.com/ethers-io/ethers.js).

```sh
npm install @roninnetwork/rnsjs ethers
```

### Create an RNS instance

```js
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.

```js
/* 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`.

```js
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:

```js
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