Namespace SDK - Offchain Client

Overview

The namespace-sdk provides an easy-to-use client for managing ENS subnames off-chain. With this SDK, developers can create, update, delete, and query subnames, as well as manage associated records like addresses, text records, and data records.

Namespace Dev Portal

If you've already done this, feel free to skip this step.

To issue subnames, make them resolvable, and get an API key, you need to go to our Dev Portal.

1. Subnames section allows you to create, edit, or update subnames and all of their records (text, addresses, content hash)
2. Resolution section is there for you to update the Resolver contract to Namespace Hybrid resolver so the subnames issued are resolvable in all ENS-supported apps.
3. API Keys section allows you to create and manage API keys for ENS names you're issuing subnames from.

Installation

npm install @namespacesdk/offchain-manager

or using Yarn:

npm install @namespacesdk/offchain-manager

Getting Started

Import the SDK

import { OffchainClient } from '@namespacesdk/offchain-manager';

Initialize the Client

To use the SDK, create an instance of the OffchainClient and set your API key, which you can obtain from https://dev.namespace.ninja.

const client = new OffchainClient();
client.setApiKey('your-ens-name.eth', 'your-api-key');

Subname Management

Create a Subname

import { ChainName } from "@namespacesdk/offchain-manageR"

await client.createSubname({
  parent: 'example.eth',
  label: 'sub',
  addresses: [
    {
      chain: ChainName.Ethereum
      value: "0x123..."
    }
  ],
  texts: [
    {
      key: "avatar",
      value: "https://my_avatar_url"
    }
  ]
});

Update a Subname

await client.updateSubname('sub.example.eth', {
   addresses: [
    {
      chain: ChainName.Ethereum
      value: "0x123..."
    }
  ],
  texts: [
    {
      key: "avatar",
      value: "https://my_avatar_url"
    }
  ]
});

Delete a Subname

await client.deleteSubname('sub.example.eth');

Check if a Subname is Available

const response = await client.isSubnameAvailable('sub.example.eth');
console.log(response.available);

Get a Subname

const subname = await client.getSingleSubname('sub.example.eth');
console.log(subname);

Query Subnames

const subnames = await client.getFilteredSubnames({ parent: 'example.eth' });
console.log(subnames);

Record Management

Add an Address Record

import { ChainName } from "@namespacesdk/offchain-manager"

await client.addAddressRecord('sub.example.eth',  ChainName.Ethereum, '0xYourEthereumAddress');

Delete an Address Record

await client.deleteAddressRecord('sub.example.eth',  ChainName.Base);

Add a Text Record

await client.addTextRecord('sub.example.eth', 'twitter', '@yourhandle');

Delete a Text Record

await client.deleteTextRecord('sub.example.eth', 'twitter');

Retrieve All Text Records

const records = await client.getTextRecords('sub.example.eth');
console.log(records);

Retrieve a Specific Text Record

const record = await client.getTextRecord('sub.example.eth', 'twitter');
console.log(record);

Add a Data Record

await client.addDataRecord('sub.example.eth', 'customData', { key: 'value' });

Delete a Data Record

await client.deleteDataRecord('sub.example.eth', 'customData');

Retrieve All Data Records

const dataRecords = await client.getDataRecords('sub.example.eth');
console.log(dataRecords);

Retrieve a Specific Data Record

const dataRecord = await client.getDataRecord('sub.example.eth', 'customData');
console.log(dataRecord);

API Reference

setApiKey(ensName: string, apiKey: string): void

Sets the API key for authentication.

createSubname(request: CreateSubnameRequest): Promise<void>

Creates a new subname under a parent domain.

updateSubname(subname: string, request: UpdateSubnameRequest): Promise<void>

Updates an existing subname.

deleteSubname(fullSubname: string): Promise<void>

Deletes a subname.

isSubnameAvailable(fullSubname: string): Promise<GetAvailableResponse>

Checks if a subname is available.

getSingleSubname(fullName: string): Promise<SubnameDTO | null>

Retrieves details of a subname.

getFilteredSubnames(query: QuerySubnamesRequest): Promise<PagedResponse<SubnameDTO[]>>

Fetches subnames based on query parameters.

addAddressRecord(subname: string, chain: ChainName, value: string): Promise<void>

Adds an address record to a subname.

deleteAddressRecord(subname: string, chain: ChainName): Promise<void>

Deletes an address record.

addTextRecord(subname: string, key: string, value: string): Promise<void>

Adds a text record to a subname.

deleteTextRecord(subname: string, key: string): Promise<void>

Deletes a text record.

getTextRecords(fullSubname: string): Promise<Record<string, string>>

Retrieves all text records for a subname.

getTextRecord(fullSubname: string, key: string): Promise<GetRecordResponse>

Retrieves a specific text record.

addDataRecord(fullSubname: string, key: string, data: any): Promise<void>

Adds a data record to a subname.

deleteDataRecord(subname: string, key: string): Promise<void>

Deletes a data record.

getDataRecords(fullSubname: string): Promise<Record<string, any>>

Retrieves all data records for a subname.

getDataRecord(fullSubname: string, key: string): Promise<GetRecordResponse>

Retrieves a specific data record.

License

This project is licensed under the MIT License.

Support

For any issues or feature requests, please open an issue on GitHub.

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

Questions? Join our Builders Group chat

Consider joining the Namespace Builders group chat on Telegram if you have any questions, suggestions, feedback, or anything you want to talk about.