Integrate your wallet with RNS

The first thing you need to do is to register the name of your wallet now! Search for it here:


This tutorial has been created to be used with the RNS JS library. The library needs Web3 to be instantiated, so if you already use Web3, welcome to the journey!
If not, don't worry, you are still able to check out our smart contracts architecture and interact directly with them, it's easy! We are working to port this library for different clients.

Use domains instead of addresses within your app

A fundamental goal of RNS is to simplify blockchain user experience! Instead of typing addresses, why not let your users type domains? This is so much simpler!

Use domains for Rootstock (RSK) Addresses

The following code snippet is a method that receives a domain and returns an address. You can use it in your wallet inputs, allowing users to enter domains instead of addresses.

const getAddressFromDomain = async (domain) => {
    const address = await rns.addr(domain);
    return address;

Use domains in other blockchains

You can even use domains on different networks, like Bitcoin, Litecoin, and more! The multi-coin resolution can be integrated as easily as:

const getAddressFromDomain = async (domain, coinId) => {
    const address = await rns.addr(domain, coinId);
    return address;

The coin ID should match the one in SLIP-0044.

Set address resolution

Sometimes a user may choose to change their address, or your wallet may choose to do so for privacy purposes. It is important to keep the domain's address resolution updated.

Set Rootstock (RSK) addresses

Just make sure that the current user address is the owner of the domain, then copy the method placed below.

const setAddressForDomain = async (domain, newAddress) => {
    await rns.setAddr(domain, newAddress);

Take into account that this method submits a transaction, so it will spend some gas.

Set other blockchain addresses

The implementation of this method in the RNS JS library is in progress, and you can check its status here. If you do not wish to wait, you can interact directly with the contracts. Check out this article about multichain resolution.

Register subdomains for newcomers

There are several options to register subdomains for your users. The main thing you need to know is that the only payment needed is the transaction fee. Subdomains are completely free! The owner of a domain decides when, how, and who receives subdomains.

But before registering a subdomain, you need to make sure that the subdomain is available. Let's code a bit.

Install dependencies

npm i web3 @rsksmart/rns

Instantiate the library

import Web3 from 'web3';
import RNS from '@rsksmart/rns';

const web3Instance = new Web3(web3.currentProvider);
const rns = new RNS(web3Instance);

Check subdomain availability

const available = await rns.subdomains.available('mywallet.rsk', 'alice');

If the subdomain is available, we can create it. Take a look at these different options:

Create a backend

This method is the simplest one for end users, because you will pay the transaction fees.

Just need to create a service that will register subdomains on demand. It means that once a user creates a wallet, your app will dispatch a request to your server (who hosts a private key with funds) and that server will register domains by sending a transaction to a registrar contract. Check out this example of the API and contract implementations, which even includes a sample front end.

Here's the checklist of the things you should do to complete this solution

  • Register a domain -- Use the RNS Manager!
  • Create the subdomain registrar smart contract, with a whitelist -- example
  • Deploy the subdomain registrar, and whitelist the registrant address.
  • Transfer your domain ownership to the contract.
  • Create a backend to support masive registrations! -- sample here
  • Use that backend from your front end :smile_cat: -- another sample here
Take into account that this solution is a centralized solution, your server is a single point of failure.

Develop a smart contract

This method is fully decentralized, and is oriented towards advanced users because they are in charge of paying the transaction fee.

You just need to develop a registrar smart contract (find an example here) that will be the owner of your domain. Thus that contract is the owner, it is allowed to create subdomains under your wallet domain. So, once the user creates a wallet, your app will prompt him/her to create a subdomain by just submitting a transaction.

Here's the checklist of the things you should do to complete this solution

  • Register a domain -- Use the RNS Manager!
  • Create an open subdomain registrar smart contract -- example
  • Deploy the subdomain registrar.
  • Transfer your domain ownership to the contract.
  • Use the smart contract from the front-end :smile_cat:

Batch subdomain registration

This solution is more complicated. We have a tool which registers multiple subdomains using fewer transactions, and thus incurs lower costs.

This method needs a trigger that will activate the batch subdomain tool. You will also need to store in some place all the subdomains that should be created at the same time. We provide an example of that tool here.

You will also need to consider on the client side that the delay of this method could be long. Have creativity! We receive all your ideas on how to entertain the user while waiting to publish them in our articles.

Here's the checklist of the things you should do to acquire this solution

Create more subdomains

The RNS Registry is a tree of nodes (more information). Each node owner governs the node, thus if you are the owner of mywallet.rsk, you are able to create new domains for your users under your node. Let's assume you've created a new domain called alice.mywallet.rsk and have given the ownership of that new node to Alice. Only Alice is allowed to create new nodes under her node, and you can help her to do that! To do so, you need to provide that service within your wallet by using the following code snippet.

const domain = 'alice.mywallet.rsk';
const label = 'savings';
const aliceAddress = await rns.addr('alice.mywallet.rsk');
const newAddress = theOneAliceChose;

const createSubdomain = async (domain, label, aliceAddress, address) => {
    return rns.create(domain, label, aliceAddress, address);

This will create a new domain called savings.allice.mywallet.rsk that will point to address. The owner of this new domain will be alice.mywallet.rsk.

Take into account that alice.mywallet.rsk should sign the transaction because she is the owner of the parent domain. If mywallet.rsk attempts to sign the transaction, it would fail, because it is not the owner of the parent domain.

Receive updates

Get the latest updates from the Rootstock ecosystem