Managing Primary Names

Overview

Primary names allow users to set a user-friendly alias for their Arweave wallet address, simplifying how addresses are displayed across applications. This process involves interaction between two separate smart contracts:

1. The AR.IO Contract - which manages the primary name registry and requests
2. The ANT Contract - which controls the specific ArNS name and must approve any primary name requests

The process requires two steps because these are separate contracts:

1. First, a request must be submitted to the AR.IO contract to set a specific ArNS name as the primary name for a wallet
2. Then, the ANT owner must approve this request, confirming that this wallet can use the name as its primary identifier

This two-step verification ensures that both the wallet owner and the ANT owner have authorized the connection.

Setting a Primary Name with arns.app

arns.app is the official ArNS portal from AR.IO. It allows you to manage your ArNS names and set primary names for your wallet addresses.

To set a primary name using arns.app, connect your wallet and navigate to the ArNS name management page.

Simply locate the ArNS name you want to set as primary and click the star icon at the right of the entry. You will then be prompted to accept the cost of setting the name, and the location of the funds to pay for the transaction.

Once the transaction is confirmed, you will be prompted to sign the transaction with your connected wallet. When this is completed, the name will be set as primary for your wallet address, and apps that support primary names will display the name instead of the wallet address.

Setting a Primary Name With the AR.IO SDK

The process of setting a primary name using the AR.IO SDK involves two steps: requesting and approval. This two-step process ensures proper authorization from both the wallet owner and the ANT owner.

Requesting a Primary Name

When requesting a primary name, you're asking to use an ArNS name as the identifier for your wallet address. This requires:

1. The ArNS name to exist
2. Your wallet to submit the request using the requestPrimaryName method
3. The ANT owner's approval

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

async function main() {
    const jwk = JSON.parse(fs.readFileSync("KeyFile.json"));
    const ario = ARIO.init({
        signer: new ArweaveSigner(jwk)
    });

    const { id: txId } = await ario.requestPrimaryName({
        name: 'my-arns-name',
        processId: 'ANT-PROCESS-ID'
    });

    console.log(`Primary name request submitted: ${txId}`);
}

main();

Check Primary Name Requests

The getPrimaryNameRequest method allows you to verify if a primary name request exists and its status. Use this to:

• Verify if your request is pending
• Check if someone has requested to use your ANT's name
• Build UI flows around the request/approval process

const { ARIO } = require("@ar.io/sdk");

async function main() {
    const ario = ARIO.init();
    
    const request = await ario.getPrimaryNameRequest({
        initiator: 'WALLET-ADDRESS' // The wallet address that made the request
    });

    console.log(request);
    // Example response:
    // {
    //   "initiator": "WALLET-ADDRESS",
    //   "name": "arns",
    //   "startTimestamp": 1728067635857,
    //   "endTimestamp": 1735843635857
    // }
}

main();

Approving a Primary Name Request

The ANT owner must approve any requests to use their name as a primary name using the approvePrimaryNameRequest method. This gives ANT owners control over how their names are used as identifiers.

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

async function main() {
    const jwk = JSON.parse(fs.readFileSync("KeyFile.json"));
    const ant = ANT.init({
        signer: new ArweaveSigner(jwk),
        processId: "ANT-PROCESS-ID"
    });

    const { id: txId } = await ant.approvePrimaryNameRequest({
        name: 'my-arns-name',
        address: 'WALLET-ADDRESS',
        ioProcessId: 'ARIO-PROCESS-ID'
    });

    console.log(`Primary name request approved: ${txId}`);
}

main();

Querying Primary Names

The AR.IO SDK provides several methods to query primary names, each serving different use cases:

Get a Single Primary Name

Use getPrimaryName when you need to find the primary name for a specific wallet address. This is particularly useful in applications where you want to display a user-friendly identifier instead of their wallet address.

Common use cases:

• Displaying a user's primary name in a profile or dashboard
• Showing who authored a piece of content
• Making transaction histories more readable

const { ARIO } = require("@ar.io/sdk");

async function main() {
    const ario = ARIO.init();
    
    const primaryName = await ario.getPrimaryName({
        name: 'my-arns-name'
    });

    console.log(primaryName);
}

main();

List All Primary Names

Use getPrimaryNames when fetching all primary names. This is useful when you need to:

• Build a directory of users
• Create search functionality
• Display multiple users in a more readable format
• Map multiple wallet addresses to their friendly names at once

The method supports pagination through a cursor-based system, where the cursor is the last name from your previous request.

const { ARIO } = require("@ar.io/sdk");

async function main() {
    const ario = ARIO.init();
    
    // First page of results
    const firstPage = await ario.getPrimaryNames({
        limit: 10,
        sortBy: 'startTimestamp',
        sortOrder: 'desc'
    });
    
    console.log('First page:', firstPage.items);
    
    if (firstPage.hasMore) {
        // Get next page using the cursor from previous response
        const nextPage = await ario.getPrimaryNames({
            cursor: firstPage.cursor, // Last name from previous request
            limit: 10,
            sortBy: 'startTimestamp',
            sortOrder: 'desc'
        });
        
        console.log('Next page:', nextPage.items);
    }
}

main();

The response includes:

• items: Array of primary names for the current page
• cursor: The last name from the current request, used for getting the next page
• hasMore: Boolean indicating if there are more results available
• totalItems: Total number of primary names matching your query

Best Practices

1. Always verify ownership of both the ArNS name and ANT before attempting to set a primary name
2. Check if a primary name request already exists before submitting a new one
3. Consider implementing error handling for cases where the name or ANT doesn't exist
4. When displaying primary names in your application, always have a fallback to show the wallet address if no primary name exists