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

Ready to Version Your Site?

Want to learn more? Check out ArNS Primary Names for identity management.

Need deployment help? See Hosting Decentralized Websites for setup guides.

Want to trade domains? Explore ArNS Marketplace for buying and selling.