AR.IO LogoAR.IO Documentation
AR.IO SDKARIO Contract

Arweave Name System (ArNS)

resolveArNSName()

Resolves an ArNS name to the underlying data id stored on the names corresponding ANT id.

Resolving a base name
const ario = ARIO.mainnet();
const record = await ario.resolveArNSName({ name: 'ardrive' });

Output:

{
  "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
  "txId": "kvhEUsIY5bXe0Wu2-YUFz20O078uYFzmQIO-7brv8qw",
  "type": "lease",
  "recordIndex": 0,
  "undernameLimit": 100,
  "owner": "t4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3",
  "name": "ardrive"
}
Resolving an undername
const ario = ARIO.mainnet();
const record = await ario.resolveArNSName({ name: 'logo_ardrive' });

Output:

{
  "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
  "txId": "kvhEUsIY5bXe0Wu2-YUFz20O078uYFzmQIO-7brv8qw",
  "type": "lease",
  "recordIndex": 1,
  "undernameLimit": 100,
  "owner": "t4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3",
  "name": "ardrive"
}

buyRecord()

Purchases a new ArNS record with the specified name, type, processId, and duration.

Note: Requires signer to be provided on ARIO.init to sign the transaction.

Arguments:

  • name - required: the name of the ArNS record to purchase
  • type - required: the type of ArNS record to purchase
  • processId - optional: the process id of an existing ANT process. If not provided, a new ANT process using the provided signer will be spawned, and the ArNS record will be assigned to that process.
  • years - optional: the duration of the ArNS record in years. If not provided and type is lease, the record will be leased for 1 year. If not provided and type is permabuy, the record will be permanently registered.
  • referrer - optional: track purchase referrals for analytics (e.g. my-app.com)
const ario = ARIO.mainnet({ signer });
const record = await ario.buyRecord(
  {
    name: 'ardrive',
    type: 'lease',
    years: 1,
    processId: 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM', // optional: assign to existing ANT process
    referrer: 'my-app.com', // optional: track purchase referrals for analytics
  },
  {
    // optional tags
    tags: [{ name: 'App-Name', value: 'ArNS-App' }],
    onSigningProgress: (step, event) => {
      console.log(`Signing progress: ${step}`);
      if (step === 'spawning-ant') {
        console.log('Spawning ant:', event);
      }
      if (step === 'registering-ant') {
        console.log('Registering ant:', event);
      }
      if (step === 'verifying-state') {
        console.log('Verifying state:', event);
      }
      if (step === 'buying-name') {
        console.log('Buying name:', event);
      }
    },
  },
);

upgradeRecord()

Upgrades an existing leased ArNS record to a permanent ownership. The record must be currently owned by the caller and be of type "lease".

Note: Requires signer to be provided on ARIO.init to sign the transaction.

const ario = ARIO.mainnet({ signer });
const record = await ario.upgradeRecord(
  {
    name: 'ardrive',
    referrer: 'my-app.com', // optional: track purchase referrals for analytics
  },
  {
    // optional tags
    tags: [{ name: 'App-Name', value: 'ArNS-App' }],
  },
);

getArNSRecord()

Retrieves the record info of the specified ArNS name.

const ario = ARIO.mainnet();
const record = await ario.getArNSRecord({ name: 'ardrive' });

Output:

{
  "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
  "endTimestamp": 1752256702026,
  "startTimestamp": 1720720819969,
  "type": "lease",
  "undernameLimit": 100
}

getArNSRecords()

Retrieves all registered ArNS records of the ARIO process, paginated and sorted by the specified criteria. The cursor used for pagination is the last ArNS name from the previous request.

const ario = ARIO.mainnet();
// get the newest 100 names
const records = await ario.getArNSRecords({
  limit: 100,
  sortBy: 'startTimestamp',
  sortOrder: 'desc',
});

Available sortBy options are any of the keys on the record object, e.g. name, processId, endTimestamp, startTimestamp, type, undernames.

Output:

{
  "items": [
    {
      "name": "ao",
      "processId": "eNey-H9RB9uCdoJUvPULb35qhZVXZcEXv8xds4aHhkQ",
      "purchasePrice": 75541282285,
      "startTimestamp": 1720720621424,
      "endTimestamp": 1752256702026,
      "type": "permabuy",
      "undernameLimit": 10
    },
    {
      "name": "ardrive",
      "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
      "endTimestamp": 1720720819969,
      "startTimestamp": 1720720620813,
      "purchasePrice": 75541282285,
      "type": "lease",
      "undernameLimit": 100
    },
    {
      "name": "arweave",
      "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
      "endTimestamp": 1720720819969,
      "startTimestamp": 1720720620800,
      "purchasePrice": 75541282285,
      "type": "lease",
      "undernameLimit": 100
    },
    {
      "name": "ar-io",
      "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
      "endTimestamp": 1720720819969,
      "startTimestamp": 1720720619000,
      "purchasePrice": 75541282285,
      "type": "lease",
      "undernameLimit": 100
    },
    {
      "name": "fwd",
      "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
      "endTimestamp": 1720720819969,
      "startTimestamp": 1720720220811,
      "purchasePrice": 75541282285,
      "type": "lease",
      "undernameLimit": 100
    }
    // ...95 other records
  ],
  "hasMore": true,
  "nextCursor": "fwdresearch",
  "totalItems": 21740,
  "sortBy": "startTimestamp",
  "sortOrder": "desc"
}

getArNSRecordsForAddress()

Retrieves all registered ArNS records of the specified address according to the ANTRegistry access control list, paginated and sorted by the specified criteria. The cursor used for pagination is the last ArNS name from the previous request.

const ario = ARIO.mainnet();
const records = await ario.getArNSRecordsForAddress({
  address: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
  limit: 100,
  sortBy: 'startTimestamp',
  sortOrder: 'desc',
});

Available sortBy options are any of the keys on the record object, e.g. name, processId, endTimestamp, startTimestamp, type, undernames.

Output:

{
  "limit": 1,
  "totalItems": 31,
  "hasMore": true,
  "nextCursor": "ardrive",
  "items": [
    {
      "startTimestamp": 1740009600000,
      "name": "ardrive",
      "endTimestamp": 1777328018367,
      "type": "permabuy",
      "purchasePrice": 0,
      "undernameLimit": 100,
      "processId": "hpF0HdijWlBLFePjWX6u_-Lg3Z2E_PrP_AoaXDVs0bA"
    }
  ],
  "sortOrder": "desc",
  "sortBy": "startTimestamp"
}

increaseUndernameLimit()

Increases the undername support of a domain up to a maximum of 10k. Domains, by default, support up to 10 undernames.

Note: Requires signer to be provided on ARIO.init to sign the transaction.

const ario = ARIO.mainnet({ signer: new ArweaveSigner(jwk) });
const { id: txId } = await ario.increaseUndernameLimit(
  {
    name: 'ar-io',
    qty: 420,
    referrer: 'my-app.com', // optional: track purchase referrals for analytics
  },
  // optional additional tags
  { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
);

extendLease()

Extends the lease of a registered ArNS domain, with an extension of 1-5 years depending on grace period status. Permanently registered domains cannot be extended.

const ario = ARIO.mainnet({ signer: new ArweaveSigner(jwk) });
const { id: txId } = await ario.extendLease(
  {
    name: 'ar-io',
    years: 1,
    referrer: 'my-app.com', // optional: track purchase referrals for analytics
  },
  // optional additional tags
  { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
);

getTokenCost()

Calculates the price in mARIO to perform the interaction in question, eg a 'Buy-Name' interaction, where args are the specific params for that interaction.

const price = await ario
  .getTokenCost({
    intent: 'Buy-Name',
    name: 'ar-io',
    type: 'permabuy',
  })
  .then((p) => new mARIOToken(p).toARIO()); // convert to ARIO for readability

Output:

1642.34

getCostDetails()

Calculates the expanded cost details for the interaction in question, e.g a 'Buy-Name' interaction, where args are the specific params for that interaction. The fromAddress is the address that would be charged for the interaction, and fundFrom is where the funds would be taken from, either balance, stakes, or any.

const costDetails = await ario.getCostDetails({
  intent: 'Buy-Name',
  fromAddress: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
  fundFrom: 'stakes',
  name: 'ar-io',
  type: 'permabuy',
});

Output:

{
  "tokenCost": 2384252273,
  "fundingPlan": {
    "address": "t4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3",
    "balance": 0,
    "stakes": {
      "Rc80LG6h27Y3p9TN6J5hwDeG5M51cu671YwZpU9uAVE": {
        "vaults": [],
        "delegatedStake": 2384252273
      }
    },
    "shortfall": 0
  },
  "discounts": []
}

getDemandFactor()

Retrieves the current demand factor of the network. The demand factor is a multiplier applied to the cost of ArNS interactions based on the current network demand.

const ario = ARIO.mainnet();
const demandFactor = await ario.getDemandFactor();

Output:

1.05256

getArNSReturnedNames()

Retrieves all active returned names of the ARIO process, paginated and sorted by the specified criteria. The cursor used for pagination is the last returned name from the previous request.

const ario = ARIO.mainnet();
const returnedNames = await ario.getArNSReturnedNames({
  limit: 100,
  sortBy: 'endTimestamp',
  sortOrder: 'asc', // return the returned names ending soonest first
});

Output:

{
  "items": [
    {
      "name": "permalink",
      "endTimestamp": 1730985241349,
      "startTimestamp": 1729775641349,
      "baseFee": 250000000,
      "demandFactor": 1.05256,
      "initiator": "GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelVLB6GcRGrHc",
      "settings": {
        "durationMs": 1209600000,
        "decayRate": 0.000000000016847809193121693,
        "scalingExponent": 190,
        "startPriceMultiplier": 50
      }
    }
  ],
  "hasMore": false,
  "totalItems": 1,
  "sortBy": "endTimestamp",
  "sortOrder": "asc"
}

getArNSReturnedName()

Retrieves the returned name data for the specified returned name.

const ario = ARIO.mainnet();
const returnedName = await ario.getArNSReturnedName({ name: 'permalink' });

Output:

{
  "name": "permalink",
  "endTimestamp": 1730985241349,
  "startTimestamp": 1729775641349,
  "baseFee": 250000000,
  "demandFactor": 1.05256,
  "initiator": "GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelVLB6GcRGrHc",
  "settings": {
    "durationMs": 1209600000,
    "decayRate": 0.000000000016847809193121693,
    "scalingExponent": 190,
    "startPriceMultiplier": 50
  }
}

How is this guide?

Gateways

TypeScript/JavaScript SDK for interacting with the AR.IO ecosystem

Epochs

TypeScript/JavaScript SDK for interacting with the AR.IO ecosystem

On this page

resolveArNSName()Resolving a base nameResolving an undernamebuyRecord()upgradeRecord()getArNSRecord()getArNSRecords()getArNSRecordsForAddress()increaseUndernameLimit()extendLease()getTokenCost()getCostDetails()getDemandFactor()getArNSReturnedNames()getArNSReturnedName()