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.init({ rpc });
const record = await ario.resolveArNSName({ name: "ardrive" });

Output:

{
  "name": "ardrive",
  "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
  "txId": "kvhEUsIY5bXe0Wu2-YUFz20O078uYFzmQIO-7brv8qw",
  "type": "lease",
  "ttlSeconds": 3600,
  "undernameLimit": 100
}
Resolving an undername
const ario = ARIO.init({ rpc });
const record = await ario.resolveArNSName({ name: "logo_ardrive" });

Output:

{
  "name": "ardrive",
  "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
  "txId": "kvhEUsIY5bXe0Wu2-YUFz20O078uYFzmQIO-7brv8qw",
  "type": "lease",
  "ttlSeconds": 3600,
  "undernameLimit": 100
}

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.init({ rpc, rpcSubscriptions, 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.init({ rpc, rpcSubscriptions, 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.init({ rpc });
const record = await ario.getArNSRecord({ name: "ardrive" });

Output:

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

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.init({ rpc });
// 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.init({ rpc });
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.init({ rpc, rpcSubscriptions, signer });
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.init({ rpc, rpcSubscriptions, signer });
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.

On Solana, the result also includes a gasEstimate — the total SOL (in lamports) the wallet needs to execute the intent: transaction fees (quoted from recent on-chain prioritization fees) plus rent-exempt deposits for the accounts the flow creates. For Buy-Name that covers both transactions (ANT spawn + buy) and the rent for the spawned asset/PDAs and the ArNS record; first-time buyers with no ACL accounts yet are quoted the ACL bootstrap rent as well (pass fromAddress so that check can be made). The fee side is a conservative upper bound: the write path tightens the compute-unit limit from a pre-send simulation, so the landed fee is usually lower.

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

Output:

{
  "tokenCost": 1907401818,
  "discounts": [
    {
      "name": "Gateway Operator",
      "discountTotal": 476850455,
      "multiplier": 0.8
    }
  ],
  "gasEstimate": {
    "totalLamports": 14679680,
    "feeLamports": 23000,
    "baseFeeLamports": 15000,
    "priorityFeeLamports": 8000,
    "rentLamports": 14656680,
    "rentReclaimedLamports": 0,
    "priorityFeeMicroLamports": 10000,
    "computeUnitLimit": 400000,
    "signatureCount": 3,
    "transactionCount": 2
  }
}

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.init({ rpc });
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.init({ rpc });
const returnedNames = await ario.getArNSReturnedNames({
  limit: 100,
  sortBy: "endTimestamp",
  sortOrder: "asc", // return the returned names ending soonest first
});

Output:

{
  "items": [
    {
      "name": "permalink",
      "startTimestamp": 1729775641349,
      "endTimestamp": 1730985241349,
      "initiator": "GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelVLB6GcRGrHc",
      "premiumMultiplier": 50
    }
  ],
  "hasMore": false,
  "totalItems": 1,
  "limit": 100,
  "sortBy": "endTimestamp",
  "sortOrder": "asc"
}

getArNSReturnedName()

Retrieves the returned name data for the specified returned name.

const ario = ARIO.init({ rpc });
const returnedName = await ario.getArNSReturnedName({ name: "permalink" });

Output:

{
  "name": "permalink",
  "startTimestamp": 1729775641349,
  "endTimestamp": 1730985241349,
  "initiator": "GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelVLB6GcRGrHc",
  "premiumMultiplier": 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()