Integrate RNS in your app

Overview

This guide explains how to integrate the Ronin Name Service (RNS) in your app. A successful integration allows your app to look up a Ronin address for user's RNS name, and to fetch the RNS name for a user's Ronin address. Depending on your platform, you can integrate RNS in two ways:

• Using the rnsjs library (for JavaScript clients).
• Interacting with the RNS controller directly (for all other platforms).

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

Integrate RNS

Instantiate the RNS registry contract

To begin interacting with RNS, your app needs to get a reference to the RNS registry by instantiating the RNS Unified contract.

The following example uses rnsjs to set up the RNS instance, resolve jihoz.ron to the owner's address, and then in reverse: the address to the RNS name.

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

const providerUrl = "https://api-gateway.skymavis.com/rpc?apikey=" + process.env.SM_API_KEY // Use your app's API key in the Developer Console
const chainId = 2020

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

const RNSInstance = new RNS();

(async () => {
    await RNSInstance.setProvider(provider, chainId as number)

    const nameToAddress = await RNSInstance.getAddr('jihoz.ron')

    console.log(`jihoz.ron address: ${nameToAddress}`)

    const addressToName = await RNSInstance.getName(nameToAddress)

    console.log(`${nameToAddress} name: ${addressToName!.name}`)

})()

If you don't use the rnsjs library, then you can instantiate the RNS Unified contract using the interface definition. To find addresses for the contract, see Deployments.

Support name resolution

Forward resolution

Many types of data can be associated with names, but cryptocurrency addresses are the most common.

Using the rnsjs library, you can resolve an RNS name to a Ronin address in the following way:

var address = await rns.getAddr('jihoz.ron');

When interacting with the RNS Unified contract directly, you can resolve an RNS name to a Ronin address in the following way:

1. Hash the name—see Namehashing for details.
2. Call ownerOf() on RNS Unified, passing in the output of step 1. This returns the address of the name.

Reverse resolution

Forward resolution maps a name to an address, while reverse resolution maps an address back to its primary name. This allows apps to display primary RNS names instead of hexadecimal Ronin addresses. If a given address has no primary name, display the address as before.

Reverse resolution is accomplished through the special-purpose domain addr.reverse and the resolver function name(). The addr.reverse domain is owned by a special-purpose registrar contract that allocates domains to the owner of the matching address. For instance, the address 0xbd4bf317da1928cc2f9f4da9006401f3944a0ab5 can claim the name bd4bf317da1928cc2f9f4da9006401f3944a0ab5.addr.reverse and configure a resolver and records on it. The resolver supports the name() function, which returns the primary name associated with that address.

The rnsjs library provides a feature for reverse resolution:

const address = '0xbd4bf317da1928cc2f9f4da9006401f3944a0ab5';
let rnsName = null;
({ name: rnsName } = await rns.getName(address))
rnsName = null;

Reverse resolution without a library follows the same pattern as forward resolution:

1. Get the resolver for bd4bf317da1928cc2f9f4da9006401f3944a0ab5.addr.reverse, where bd4bf317da1928cc2f9f4da9006401f3944a0ab5 is the address you want to reverse-resolve.
2. Using the name resolver interface, call the name() function on that resolver.

See also

• Frontend design guidelines