Managing Undernames

Overview

ArNS undernames are subdomains of top level ArNS domains. They are separated from the main ArNS domain using an underscore "_" in place of the more typically used dot ".".

Records for undernames can be set using the setRecord method on the AR.IO SDK, or removed by using the removeRecord method. The process for setting/removing a record for an undername vs. a top level ArNS domain is nearly identical, the only difference being the undername parameter. When managing a record on a top level ArNS domain, this must be set to @, while updates to an undername should provide the undername being updated.

Chaining Undernames

Undernames can be created on other undernames, for example ar://og_logo_ardrive. In this example the undername og exists under the undername logo on the ArNS name ardrive.

For the purpose of the undername parameter in the AR.IO SDK, this should be written as a single undername, including the separating underscores:

og_logo

Creating an Undername

There are no special steps required to create an undername (provided the selected ArNS name has available undername space). Simply setting a record for an undername that does not exist will create the undername.

Create an Undername

 const fs = require("fs");
 const { ANT, ArweaveSigner } = require("@ar.io/sdk");

 async function main() {
 const jwk = JSON.parse(fs.readFileSync("KeyFile.json"));
 const ant = ANT.init({
     signer: new ArweaveSigner(jwk),
     processId: "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM"
 });

 const { id: txId } = await ant.setRecord(
         {
             undername: 'brand-new-undername',
             transactionId: '432l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM'
             ttlSeconds: 3600
         },
         // optional additional tags
         { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
     );
 }

 main();

Updating an Undername

If an undername already exists, its record can easily be updated using the same setRecord method.

Update an Undername

 const fs = require("fs");
 const { ANT, ArweaveSigner } = require("@ar.io/sdk");

 async function main() {
 const jwk = JSON.parse(fs.readFileSync("KeyFile.json"));
 const ant = ANT.init({
     signer: new ArweaveSigner(jwk),
     processId: "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM"
 });

 const { id: txId } = await ant.setRecord(
         {
             undername: 'undername-to-update',
             transactionId: '432l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM'
             ttlSeconds: 3600
         },
         // optional additional tags
         { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
     );
 }

 main();

Removing an Undername

An existing undername can be removed by using the removeRecord method on the AR.IO SDK. The undername parameter should be set to the undername being removed.

Remove Undername

 const fs = require("fs");
 const { ANT, ArweaveSigner } = require("@ar.io/sdk");

 async function main() {
 const jwk = JSON.parse(fs.readFileSync("KeyFile.json"));
 const ant = ANT.init({
     signer: new ArweaveSigner(jwk),
     processId: "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM"
 });

 const { id: txId } = await ant.removeRecord(
         {
             undername: 'remove-domain',
         },
         // optional additional tags
         { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
     );
 }

 main();

Increasing Undername Support

By default, ArNS names support up to 10 undernames. This number can be increased, for a fee. This is done using the increaseUndernameLimit method on the ARIO class of the AR.IO SDK, rather than the ANT class. The quantity (qty) parameter specifies the number of ADDITIONAL undernames to be supported. i.e. increasing from 10 undernames to 15 would require the qty parameter set to 5.

Increasing Undername Support

 const fs = require("fs");
 const { ARIO, ArweaveSigner, ARIOToken } = require("@ar.io/sdk");

 async function main() {
 const jwk = JSON.parse(fs.readFileSync("KeyFile.json"));
 const ario = ARIO.init({
     signer: new ArweaveSigner(jwk),
 });

 const { id: txId } = await ario.increaseUndernameLimit(
         {
             name: 'ar-io',
             qty: 5,
         },
         // optional additional tags
         { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
     );
 }

 main();