Retrieve a name

In this tutorial we will retrieve the name created in the Register a Name for an Identity tutorial. Additional details regarding identities can be found in the Identity description.

Prerequisites

• General prerequisites (Node.js / Dash SDK installed)

• A configured client: Setup SDK Client

Code

Resolve by Name

name-resolve-by-name.mjs

import { setupDashClient } from '../setupDashClient.mjs';

const { sdk } = await setupDashClient();

const NAME = 'quantumexplorer.dash';

try {
  // Resolve by full name (e.g., myname.dash)
  const result = await sdk.dpns.resolveName(NAME);
  console.log(`Identity ID for "${NAME}": ${result}`);
} catch (e) {
  console.error('Something went wrong:\n', e.message);
}

Example Response

Identity ID for "quantumexplorer.dash": BNnn19SAJZuvsUu787dMzPDXASwuCrm4yQ864tEpQFvo

Get Identity Names

name-get-identity-names.mjs

import { setupDashClient } from '../setupDashClient.mjs';

const { sdk, keyManager } = await setupDashClient();

// Identity ID from the identity create tutorial
let IDENTITY_ID = 'GgZekwh38XcWQTyWWWvmw6CEYFnLU7yiZFPWZEjqKHit';

// Uncomment the line below to use the identity created in the earlier tutorial
// IDENTITY_ID = keyManager.identityId;

try {
  // Retrieve usernames registered to an identity
  const usernames = await sdk.dpns.usernames({ identityId: IDENTITY_ID });
  console.log(`Name(s) retrieved for ${IDENTITY_ID}:\n`, usernames);
} catch (e) {
  console.error('Something went wrong:\n', e.message);
}

Example Response

Name(s) retrieved for GgZekwh38XcWQTyWWWvmw6CEYFnLU7yiZFPWZEjqKHit:
 [ 'Tutorial-Test-000000-backup.dash', 'Tutorial-Test-000000.dash' ]

Search for Name

name-search-by-name.mjs

import { setupDashClient } from '../setupDashClient.mjs';

const { sdk } = await setupDashClient();

const DPNS_CONTRACT_ID = 'GWRSAVFMjXx8HpQFaNJMqBV7MBgMK4br5UESsB4S31Ec';
const PREFIX = 'Tutorial-Test-00';

try {
  // Convert prefix to homograph-safe form for normalized search
  const normalizedPrefix = await sdk.dpns.convertToHomographSafe(PREFIX);

  // Search the DPNS contract for matching names
  const results = await sdk.documents.query({
    dataContractId: DPNS_CONTRACT_ID,
    documentTypeName: 'domain',
    where: [
      ['normalizedParentDomainName', '==', 'dash'],
      ['normalizedLabel', 'startsWith', normalizedPrefix],
    ],
    orderBy: [['normalizedLabel', 'asc']],
  });

  for (const [id, doc] of results) {
    const { label, parentDomainName } = doc.toJSON();
    console.log(`${label}.${parentDomainName} (ID: ${id.toString()})`);
  }
} catch (e) {
  console.error('Something went wrong:\n', e.message);
}

Example Response

Tutorial-Test-000000.dash (ID: E8m6NCCnpschx4WRfk1uLMHqttqMJKPwYt8fWaVSJPrL)
Tutorial-Test-000000-backup.dash (ID: 98bruK9TdJki5xP8BYpmNXqdH9ZHzBD9phwDRzhaJsWF)

What’s Happening

After we initialize the Client, we request a name. The code examples demonstrate the three ways to request a name:

1. Resolve by name. The sdk.dpns.resolveName method takes a single argument: a fully-qualified name (e.g., quantumexplorer.dash). It returns the identity ID that the name resolves to.

2. Get identity names. The sdk.dpns.usernames method takes an object with an identityId property to find all names registered to that identity. It returns an array of fully-qualified names.

3. Search. To search for names by prefix, we query the DPNS contract’s domain documents directly using sdk.documents.query(). The prefix is first converted to a homograph-safe form via sdk.dpns.convertToHomographSafe(). Results are returned as a Map of document IDs to document objects. We call .toJSON() on each document to extract the label and parentDomainName.