ArNS Undernames for Permasite Versioning

Use ArNS undernames to organize and version your permanent website components. Undernames allow you to create sub-domains under your main ArNS name, making it easy to manage different versions, pages, and assets.

What Are Undernames?

Undernames are sub-domains under your main ArNS name that can point to different Arweave transactions. They provide a structured way to organize your permanent website content.

Example structure:

• yourname.arweave.dev - Main site
• v1_yourname.arweave.dev - Version 1
• v2_yourname.arweave.dev - Version 2
• api_yourname.arweave.dev - API endpoints
• docs_yourname.arweave.dev - Documentation

Real-World Example: ArDrive

The ArDrive website uses undernames to organize different components and versions:

{
  "@": {
    "priority": 0,
    "ttlSeconds": 3600,
    "transactionId": "Vrf5_MrC1R-6rAk7o_E52DwOsKhyJmkSUqh0h5q4mDQ",
    "index": 0
  },
  "dapp": {
    "ttlSeconds": 3600,
    "transactionId": "1ubf6cW8T5dYN3COApn8Yii4bA0HKoGeid-z2IjelTo",
    "index": 1
  },
  "home": {
    "ttlSeconds": 900,
    "transactionId": "V9rQR06L1w9eLBHh2lY7o4uaDO6OqBI8j7TM_qjmNfE",
    "index": 2
  },
  "v1_home": {
    "ttlSeconds": 900,
    "transactionId": "YzD_Pm5VAfYpMD3zQCgMUcKKuleGhEH7axlrnrDCKBo",
    "index": 9
  },
  "v2_home": {
    "ttlSeconds": 900,
    "transactionId": "nOXJjj_vk0Dc1yCgdWD8kti_1iHruGzLQLNNBHVpN0Y",
    "index": 10
  },
  "v3_home": {
    "ttlSeconds": 900,
    "transactionId": "YvGRDf0h2F7LCaGPvdH19m5lqbag5DGRnw607ZJ1oUg",
    "index": 11
  }
}

This structure provides:

• @ - Main site (ardrive.arweave.dev)
• dapp - Application interface (dapp_ardrive.arweave.dev)
• home - Homepage (home_ardrive.arweave.dev)
• v1_home - Version 1 homepage (v1_home_ardrive.arweave.dev)
• v2_home - Version 2 homepage (v2_home_ardrive.arweave.dev)
• v3_home - Version 3 homepage (v3_home_ardrive.arweave.dev)

Use Cases for Undernames

1. Website Versioning

Maintain multiple versions:

• v1_yourname.arweave.dev - Previous version
• v2_yourname.arweave.dev - Current version
• beta_yourname.arweave.dev - Beta testing
• staging_yourname.arweave.dev - Staging environment

2. Component Organization

Separate different parts:

• api_yourname.arweave.dev - API endpoints
• docs_yourname.arweave.dev - Documentation
• assets_yourname.arweave.dev - Static assets
• blog_yourname.arweave.dev - Blog content

3. Content Management

Organize by content type:

• home_yourname.arweave.dev - Homepage
• about_yourname.arweave.dev - About page
• contact_yourname.arweave.dev - Contact page
• privacy_yourname.arweave.dev - Privacy policy

Benefits of Undername Versioning

Easy access to versions:

• Users can access any version directly via URL
• No need to remember transaction IDs
• Clear versioning structure

Permanent version history:

• All versions remain accessible forever
• Historical record of your website evolution
• Easy rollback to previous versions

Organized content:

• Logical structure for different components
• Easy to manage and update
• Clear separation of concerns

Transferable with ANT:

• Undernames transfer with the main ArNS name
• Maintain ownership of all versions
• Sell or transfer entire website structure

How to Set Up Undernames

1. Register your main ArNS name:

• Choose your primary name (e.g., myapp)
• Register through ArNS App

2. Create undernames:

• Use the ANT interface to add undernames
• Point each undername to different transaction IDs
• Set appropriate TTL values

3. Deploy different versions:

• Upload each version to Arweave
• Get transaction IDs for each version
• Update undername records

Example Implementation

Deploy version 1:

# Deploy to main site
npx permaweb-deploy --arns-name myapp --deploy-folder ./v1-build

# Deploy to v1 undername
npx permaweb-deploy --arns-name myapp --undername v1 --deploy-folder ./v1-build

Deploy version 2:

# Deploy to main site
npx permaweb-deploy --arns-name myapp --deploy-folder ./v2-build

# Deploy to v2 undername
npx permaweb-deploy --arns-name myapp --undername v2 --deploy-folder ./v2-build

Access different versions:

• myapp.arweave.dev - Current version
• v1_myapp.arweave.dev - Version 1
• v2_myapp.arweave.dev - Version 2

Direct Code Implementation

For more control, you can manage undernames programmatically:

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

async function updateArNSRecord(arnsName, manifestId, undername) {
  // Load your wallet JSON file
  const jwk = JSON.parse(fs.readFileSync("./wallet.json", "utf8"));

  const ario = ARIO.mainnet();
  const pid = await ario.getArNSRecord({ name: arnsName });

  const signer = new ArweaveSigner(jwk);
  const ant = ANT.init({ processId: pid.processId, signer });

  if (undername === "@") {
    return await ant.setBaseNameRecord({
      transactionId: manifestId,
      ttlSeconds: 900,
    });
  } else {
    return await ant.setUndernameRecord({
      undername: undername,
      transactionId: manifestId,
      ttlSeconds: 900,
    });
  }
}

Complete deployment example:

const { TurboFactory } = require("@ardrive/turbo-sdk");
const fs = require("fs");

async function deployWithUndername(arnsName, undername, distFolderPath) {
  // Load your wallet JSON file
  const jwk = JSON.parse(fs.readFileSync("./wallet.json", "utf8"));

  const turbo = TurboFactory.authenticated({ privateKey: jwk });

  const { manifestResponse } = await turbo.uploadFolder({
    folderPath: distFolderPath,
    dataItemOpts: { tags: [{ name: "App-Name", value: "ar.io docs deploy" }] },
    manifestOptions: { fallbackFile: "index.html" },
  });

  await updateArNSRecord(arnsName, manifestResponse.id, undername);
  console.log(
    `Deployed to: https://${arnsName}.ar-io.dev${undername === "@" ? "" : `/${undername}`}`
  );
}

// Usage
await deployWithUndername("myapp", "v1", "./build-v1");

Ready to Version Your Site?