Typescript SDK

MNS SDK Guide

The MNS SDK provides a powerful interface for interacting with the MNS. This TypeScript SDK enables seamless resolution between blockchain addresses and human-readable names across different chains.

This SDK uses CAIP-2 standard for network identification. Make sure to familiarize yourself with CAIP-2 concepts before proceeding.

Overview

MNS SDK leverages the @snowballmoney/chain-agnostic-utils package for standardized blockchain network identification, making it easy to work with multiple chains using a consistent format.

Key Features

• Full TypeScript support with comprehensive type definitions

• Cross-chain identity resolution using CAIP-2 standard

• Seamless integration with chain-agnostic-utils

• Support for batch operations

• Built-in error handling

• Automatic caching

• Standardized network identification

Getting Started

Installation

First, install both the SDK and chain-agnostic-utils:

npm install @snowballmoney/mns-sdk @snowballmoney/chain-agnostic-utils
# or
yarn add @snowballmoney/mns-sdk @snowballmoney/chain-agnostic-utils

Basic Usage

Here's a quick example to get you started:

import { SnowstormSDK } from '@snowballmoney/mns-sdk';
import { NETWORKS } from '@snowballmoney/chain-agnostic-utils';

// Initialize the SDK
const sdk = new SnowstormSDK();

// Get an identity name for an address
const identity = await sdk.getIdentityName(
  '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  NETWORKS.MOVEMENT.TESTNET
);

Core Concepts

SDK Configuration

You can customize the SDK behavior during initialization:

import { SnowstormSDK } from '@snowballmoney/mns-sdk';

const sdk = new SnowstormSDK({
  baseUrl: 'https://api.modular.name/api/public', // optional
  timeout: 5000, // optional, defaults to 10000ms
});

Identity Resolution

The SDK supports both forward and reverse resolution:

Forward Resolution (Address to Name)

import { NETWORKS } from '@snowballmoney/chain-agnostic-utils';

const identityName = await sdk.getIdentityName(
  '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  NETWORKS.MOVEMENT.PORTO
);

Reverse Resolution (Name to Address)

const identityAddress = await sdk.getIdentityAddress(
  'alice.snow',
  NETWORKS.MOVEMENT.PORTO
);

Batch Operations

For better performance when working with multiple identities:

// Resolve multiple names at once
const batchNames = await sdk.getIdentityNames({
  addresses: [
    '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    '0x123...',
  ],
  caip2Id: NETWORKS.MOVEMENT.PORTO,
});

Cross-Chain Resolution

You can use wildcard CAIP2 IDs to query across networks:

const allNetworks = await sdk.getIdentityNames({
  addresses: ['0x742d35...'],
  caip2Id: 'move-mvmt:*', // Query all Movement networks
});

Error Handling

The SDK provides structured error handling:

try {
  const identity = await sdk.getIdentityName(address, caip2Id);
} catch (error) {
  if (error instanceof SnowstormError) {
    console.error('API Error:', {
      message: error.message,
      status: error.status,
      code: error.code,
    });
  } else {
    console.error('Unexpected error:', error);
  }
}

API Reference

Methods

Identity Resolution

• getIdentityName(address: string, caip2Id: CAIP2ID): Promise<IdentityName>

• getIdentityAddress(name: string, caip2Id: CAIP2ID): Promise<IdentityAddress>

• getIdentityMetadata(name: string): Promise<IdentityMetadata>

Batch Operations

• getIdentityNames(params: GetIdentityNamesByAddressesRequest): Promise<BatchIdentityNames>

• getIdentityAddresses(params: GetIdentityAddressesByNamesRequest): Promise<BatchIdentityAddresses>

Type Definitions

type CAIP2ID = string; // e.g. "move-mvmt:testnet"

interface IdentityName {
  name: string;
  owner: string;
}

interface IdentityAddress {
  owner: string;
  resolverAddress: string;
  caip2Id?: CAIP2ID;
  subIdentities?: SubIdentity[];
}

interface IdentityMetadata {
  metadata: Array<{
    key: string;
    value: string;
  }>;
}

Best Practices

1. Use Network Constants Always use the NETWORKS constant from chain-agnostic-utils for consistent network identification.

2. Batch Operations When working with multiple identities, prefer batch operations over individual queries.

3. Error Handling Implement proper error handling using the SnowstormError class.

4. Caching Considerations The SDK includes built-in caching. Consider cache duration when implementing time-sensitive features.

Common Issues and Solutions

Network Identification

If you're experiencing issues with network identification, make sure you're using the correct CAIP2 ID format. Refer to the CAIP-2 documentation for details.

Timeout Errors

If you're experiencing timeout issues, adjust the timeout in the SDK configuration:

const sdk = new SnowstormSDK({
  timeout: 10000, // 10 seconds
});

Batch Operation Limits

Be aware of batch operation limits when using getIdentityNames or getIdentityAddresses. It's recommended to keep batch sizes reasonable.

Related Documentation

• CAIP-2 Implementation Guide

• Chain Agnostic Utils Documentation

Need Help?

If you have any questions or need support:

1. Check the Common Issues section

2. Review the CAIP-2 documentation

3. Submit an issue on our GitHub repository