Arweave Name System Proposal

Document Version History

Version

Date

Release Notes

Version

Date

Release Notes

0.1.5a

June 23, 2022

First version release in support of the ArNS pilot. Includes basic feature set for ArNS and ANTs. Does not include governance, staking, validation or other advanced utilities.

Executive Summary

A decentralized and censorship-resistant naming system that is enabled by AR.IO Gateways and used to connect friendly names to PermaWeb apps, pages and data.

Introduction

Accessing data through Arweave gateways involves formatting a url that is a combination of the gateway DNS name plus an Arweave transaction ID eg.

Https://arweave.net/{transactionId}

Transaction IDs are 43 character identifiers that reference an L1 or Bundled Data Item transaction. When gateways receive these requests for transaction data, they respond first by creating a sandbox domain and prefixing it the url eg

Https://{sandboxDomainPrefix}.arweave.net/{transactionID}

After the redirect happens, the gateway tries to serve the data from the connected CDN, internal caches and even the trusted Arweave nodes via chunk reassembly.

Gateway Friendly Path Support

Arweave Manifests provide Gateways with a mapping of Arweave transaction IDs to friendly paths. This allows web app builders to use these paths in the development of their sites and apps. The Gateway can interpret a manifest and proxy its friendly paths to their Arweave transaction IDs.

Please see the ArDrive knowledgebase to learn more about manifests, the underlying standard, and its use cases. https://ardrive.atlassian.net/wiki/spaces/help/pages/359530513

The Problem

Manifests are a solution for friendly paths, however apps and users still need to remember, bookmark and share the base manifest Arweave transaction ID appended to the gateway URL of their choice eg

Https://arweave.net/{manifestTxId}/foo.jpg

This is cumbersome and almost as if we referenced all websites by their IP address.

Sharing links that contain random 43 character strings can look suspicious to unknowing users, and potentially flag spam filters.

Users and developers can configure their own proxy to redirect a friendly DNS name to an Arweave gateway link, but these are complex and centralized solutions.

Overview

The Arweave Name System is the Smartweave-powered phonebook of the PermaWeb.

This system works similarly to traditional DNS, where a user can purchase a name in a registry and DNS Name servers resolve these names to IP addresses. With ArNS, the registry is decentralized, permanent and stored on Arweave (with Smartweave) and each AR.IO gateway acts as both cache and name resolver. Users can register a name within the ArNS Registry, like my-name and set a pointer to any Arweave Transaction ID. AR.IO Gateways will resolve that name as one of their own subdomains, eg. https://my-name.arweave.net and proxy all requests to the associated Arweave Transaction ID.

This will increase adoption and legitimacy of a permanent web, as users can now reference their Arweave hosted dApps, pages and data using a friendly name.

Arweave Name System Overview

User Story

Here is an example user story of purchasing a name in the Arweave Name System.

  • A user browses to the AR.IO ArNS Portal and searches for the name sam

  • The web app gets the latest AR.IO ArNS Smartweave Contract state and checks if the name is taken.

    • Certain names may be reserved

  • If the name is available, the app shows the user the purchase price for sam in AR.IO tokens and the gas fees paid in AR, and asks the user to provide an initial Arweave Transaction ID eg. tCce4miTTRuDybbuMdLD2voSdrwxOe6nVkzBJRkz-5Q to point the friendly name at.

  • The user decides to purchase the name sam

  • This registration process creates an Arweave Name Token, ANT, with a Record that holds the default subdomain with the desired Arweave Transaction ID that sam will point to.

  • The newly created ANT Smartweave Contract ID is added into the AR.IO ArNS Registry and the user’s AR.IO tokens are spent.

  • AR.IO Network Gateways will continually refresh and locally cache the state of the ArNS Registry in order to proxy friendly name requests to their corresponding ANT Record.

    • ANTs that do now have approved source code will not be resolved by AR.IO Gateways.

  • Instead of browsing to https://arweave.net/tCce4miTTRuDybbuMdLD2voSdrwxOe6nVkzBJRkz-5Q the user can browse to https://sam.arweave.net

  • Any other gateway in the AR.IO network will also support this friendly name being added as a prefix to their own DNS A-Record. For example https://sam.ar.io` or https://sam.bobsgateway.com or https://sam.gatewaydao.io will all resolve the same Arweave Transaction ID referenced in the ANT Record used for sam.

  • The owner of the ANT can update it’s Arweave Transaction ID so the friendly name sam points to updated data if they want. Gateways will read the latest state of the contract and resolve valid updates.

Benefits

A permanent, AR.IO Gateway-resolved list of censorship-resistant names helps create a new type of data moat and network effect for AR.IO. The overall registry value gets stronger the more users use it and the more gateway operators resolve the names.

ArNS can also grant additional utility to the AR.IO token, since purchasing an ArNS name must require spending the token. ArNS creates a strong reason for users and apps to choose AR.IO Gateways vs others that do not have this similar on-chain name resolution service.

Users can register ArNS names for their own purposes or for speculation. Since ArNS Records point to ANTs (non-fungible Arweave Name Tokens), users can trade them on marketplaces or even create advanced name leasing models.

The gas fees needed to create and manage ANT Records is much cheaper compared to other blockchains, as are the gas fees to register a name in the ArNS Registry.

In the future, other types of NFT contracts can be used instead of ANTs to manage the ArNS Records. This could include the ability for Profit Sharing Communities to vote on Record changes, or other parameters that could be included to facilitate advanced

ArNS can also form the basis of the friendly names used within the ar:// protocol. With the help of a browser integration or add in, users could be able to connect to the PermaWeb using ar://sam

Test Smartweave Contracts

Two test Smartweave contracts can be used to enable the Arweave Name System for beta testing within the AR.IO Community.

  1. Arweave Name System (ArNS) Smartweave Contract

  2. Arweave Name Token (ANT) Smartweave Contract

Test ArNS Smartweave Contract

This contract will contain the necessary features, rules and parameters needed to support the Arweave Name System and it’s underlying Registry.

The Arweave Name System Registry is a list of all of the valid, purchased friendly names and their Arweave Name Token (ANT) Smart contract addresses. Purchasing a name requires spending ArNS tokens. Names with fewer characters have a higher cost to purchase. The price of names is set within the contract itself. Once the user purchases a name, it is added to the ArNS Registry along with a pointer to its Arweave Name Token Smart Contract address. Names that have already been purchased are not allowed to be purchased again.

There is no auction needed to purchase a name, and all purchases are final and with no ending term.

There are no reserved names other than www during the ArNS Pilot.

The ArNS Smartweave Contract owning wallet can modify any existing name, set the name prices, evolve the source code for the contract or mint new tokens as needed. These centralized controls are only required for this Pilot phase, and can be replaced with community governance mechanisms.

Read Actions

balance - gets the the amount of tokens held by a wallet address.

record - gets the Smartweave Contract address for a friendly name

Write Actions

addANTSourceCodeTx - adds a new Smartweave Source Code Transaction ID for a white listed ANT contract, executable by contract owner only

removeANTSourceCodeTx - removes an existing whitelisted Smartweave Source Code Transaction ID for an ANT contract, executable by contract owner only

mintTokens - creates a new quantity of ArNS tokens used to purchase ArNS Names in the test Pilot, executable by contract owner only

setFees - modifies the fees, denominated in ArNS Tokens, for purchasing friendly names in the test Pilot, executable by contract owner only

  • Fees from characters 1-20 must be set at the same time

  • Fees must be positive numbers greater than 0

transferTokens - move tokens from one wallet to another

  • The caller must own the amount of tokens being transferred

buyRecord - spend ArNS tokens to purchase a friendly name

  • The name must not already be taken

  • Valid names include only numbers 0-9, characters a-z, dashes and underscores.

    • dashes and underscores cannot be trailing characters

    • dashes and underscores cannot used in single character domains

    • 1 character minimum, 20 character maximum

  • A name must not already be reserved, like www

  • Record Price is determined by the amount of characters in the name

  • Record Price is hardcoded and the caller must have the amount of tokens to spend

  • Must include a valid Smartweave Contract address of 43 characters that includes only numbers 0-9, characters a-z, dashes and underscores.

evolve - upgrades the ArNS contract to a new version of source code, executable by contract owner only

  • New source code must be uploaded to Arweave

  • Only the contract source code is updated, the state remains the same

Initial State

A new Smartweave contract requires an initial state which outlines its variables and their initial values. The following is the ArNS initial-state.json used for the ArNS Pilot. It contains a starting balance of 10,000,000,000,000 (ten trillion) tokens, some approved ANT Source Code transactions and fee listing.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 { "ticker": "ARNS-TEST", "name": "Arweave Name System Registry Test v0.1.5", "owner": "", "evolve": null, "records": {}, "balances": { "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ": 10000000000000 }, "approvedANTSourceCodeTxs": [ "7hL0La2KMapdJI6yIGnb4f4IjvhlGQyXnqpWc0i0d_w", "cNr6JPVu3rEOwIbdnu3lVipz9pwY5Pps9mxHSW7Jdtk" ], "fees": { "1": 4218750000, "2": 1406250000, "3": 468750000, "4": 156250000, "5": 62500000, "6": 25000000, "7": 10000000, "8": 5000000, "9": 1000000, "10": 500000, "11": 450000, "12": 400000, "13": 350000, "14": 300000, "15": 250000, "16": 200000, "17": 175000, "18": 150000, "19": 125000, "20": 100000 } }

State Interface

This Arweave Name System Smartweave Contract uses the following interface used for reading and writing the contract state

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 export interface ArNSState { ticker: string; // A short token symbol, shown in block explorers and marketplaces name: string; // The friendly name of the token, shown in block explorers and marketplaces owner: string; // The owner of this contract who can execute specific methods evolve: string; // The new Smartweave Source Code transaction to evolve this contract to records: { // A list of all friendly names and their corresponding ANT adresses [name: string]: string; } balances: { // A list of all outstanding, positive, token balances [address: string]: number; }; fees: { // A list of all fees for purchasing ArNS names [nameLength: string]: number; }; approvedANTSourceCodeTxs: string[]; // An array of Smartweave Source Code transactions for whitelisted ANTs }

Arweave Name Token Smartweave Contract

To establish ownership of a Record in the ArNS Registry, each record contains both a friendly name and a reference to an Arweave Name Token, or ANT. This is a new kind of Smartweave Contract that acts like a Profit Sharing Token and gives its owner the ability to update the Arweave Transaction ID that the friendly name points to.

The ANT Smartweave contract is standardized contract that contains the specific ArNS Record specification required by AR.IO Gateways who resolve ArNS names and their Arweave Transaction IDs. It also contains other basic functionality to establish ownership and the ability to transfer and update the Arweave Transaction ID.

ANTs should not contain evolution functionality, as all Source Code Transactions must be approved and whitelisted first in the ArNS Registry.

Secondary markets could be created by ecosystem partners that facilitate the trade of these ANTs. Additionally, tertiary markets could be created that could support the leasing of these friendly names to other users.

Arweave Network Token Record Specification

The ArNS Record Specification for an Arweave Name Token is as follows. ANTs that do not follow this spec will not be resolved by AR.IO Gateways.

1 2 3 4 5   "records": [     {       "subDomain": "@",       "transactionId": "43_character_arweave_transaction_id"     }

In the future, this ArNS Record Specification can be embedded in Profit Sharing Community contracts, allowing DAO votes to transfer the ANT or modify its transactionId.

Read

balance - gets the the amount of tokens held by a wallet address.

  • By default, there is only 1 token created per ArNS NFT Smartweave Contract

Write

transferTokens - move tokens from one wallet to another

  • The caller must own the ANT being transferred and have a balance of 1

setName - Sets the friendly name of the ANT

  • The caller must own the ANT being updated

setRecord - Creates a new ANT Record with subdomain or overwrites an existing one

  • Uses subdomain as the primary identifier for a record

  • @ is used to indicate the root of the subdomain.

  • Other valid subdomains only include numbers 0-9, characters a-z, period, dashes and underscores

    • Sub-subdomains are not currently working in the ArNS Pilot phase.

  • The caller must own the ANT being updated

setTicker - updates the short ticker used by market places and blocker explorers

  • No ticker standard currently, but the ticker should be all caps and short

  • The caller must own the ANT being updated

removeRecord - removes a ANT Record for a given subdomain

  • The caller must own the ANT being updated

Initial State

A new Smartweave contract requires an initial state which outlines its variables and their initial values. The following is an example of what a base template ANT initial-state.json could look like with a default subdomain for the root of the friendly name, denoted with @.

1 2 3 4 5 6 7 8 9 10 11 { "ticker": "ANT-SOURCE", "name": "Arweave Name Token Source Contract v0.1.5", "owner": "", "records": { "@": "" }, "balances": { "": 0 } }

State Interface

The Arweave Name Token Smartweave Contract uses the following interface for reading and writing the contract state

1 2 3 4 5 6 7 8 9 10 11 export interface ANTState { ticker: string; // A short token symbol, shown in block explorers and marketplaces name: string; // The friendly name of the token, shown in block explorers and marketplaces owner: string; // The owner of this contract who can execute specific methods records: { // A list of all subdomains and their corresponding Arweave Transaction IDs [subDomain: string]: string }; balances: { // A list of all outstanding, positive, token balances [address: string]: number; }; }

Gateway Name Resolution

AR.IO Gateways are already configured for HTTPS:// and wildcard certificates to support subdomains, however by default, they will not resolve and proxy subdomains to specific Arweave transactions.

A new service must be built that caches the latest state of the involved Smartweave contracts, performs lookups of names when they are requested, and resolve them to Arweave transaction IDs.

  • Use smartweave-js to get the latest ArNS Smartweave Contract state, get each registered friendly name and ANT, and store in a local database.

  • Get the ANT’s Source Code Transaction using GQL and evaluate it against the ArNS white list of approved ANT Source Code Transactions and reject registered ANTs that do not have approved code.

  • Use smartweave-js to get the latest ANT Smartweave Contract state for each found registered ANT, and store its latest list of subDomains and transactionIds

  • Remove ArNS Records in the local database that are no longer found.

  • Remove ANT Subdomains in the local database that are no longer found.

When a user requests the gateway to serve an ArNS name, like https://sam.arweave.net it must respond with the transactionId stored in the local database for that friendly name, and follow the standard get-data code path for serving Arweave transactions.

In order to support sub-subdomains, special Multi-domain Wildcard SSL Certificates must be used, which are not currently available on the existing Gateways. Sub-subdomains are not supported in the ArNS Pilot.

Examples

Pilot Deployment

An Arweave Name System Pilot deployment was performed to test the user and developer experience, collect feedback on both the Registry and ANT specifications, while building excitement for AR.IO.

https://viewblock.io/arweave/address/bLAgYxAdX2Ry-nt6aH2ixgvJXbpsEYm28NgJgyqfs-U

Contract Source: https://github.com/ar-io/arns-pilot

It uses the following Arweave Name Token template to register friendly names

https://viewblock.io/arweave/address/ACpV_CzOfNxh8LhPM-FMcsLNpVYcy-KyTzEQ1UD5avg

Contract Source: https://github.com/ar-io/ant-pilot

For example, an ArDrive token was created with the friendly name ardrive and can be accessed at https://ardrive.arweave.dev

https://viewblock.io/arweave/address/XYIy7LWVl_-EOQvWlgpVASxtOTH6ihVqF3QddoRJZr4?tab=state

The above github repositories also contain tooling scripts to create tokens, buy names, transfer tokens and other read and write operations needed to support ArNS.

References