@snowballmoney/mns-sdk v1.0.3

Snowstorm SDK

A TypeScript SDK for interacting with the Snowstorm naming service API. Snowstorm is a modular naming service that allows resolution between blockchain addresses and human-readable names across different chains. It uses @snowballmoney/chain-agnostic-utils for standardized blockchain network identification.

Features

• Full TypeScript support with type definitions
• Cross-chain identity resolution using CAIP-2 standard
• Integration with @snowballmoney/chain-agnostic-utils for network identification
• Batch operations support
• Automatic error handling
• Caching support
• CAIP2 standard compliance

Installation

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

Quick Start

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 using CAIP2 network ID
const identity = await sdk.getIdentityName(
  '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  NETWORKS.MOVEMENT.TESTNET
);

Usage

Initialization

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

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

Single Resolution

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

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

// Get address by identity name
const identityAddress = await sdk.getIdentityAddress(
  'alice.snow',
  NETWORKS.MOVEMENT.TESTNET
);

// Get identity metadata
const metadata = await sdk.getIdentityMetadata('alice.snow');

Batch Operations

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

// Batch resolve names for multiple addresses
const batchNames = await sdk.getIdentityNames({
  addresses: [
    '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    '0x123...',
  ],
  caip2Id: NETWORKS.MOVEMENT.TESTNET,
});

// Batch resolve addresses for multiple names
const batchAddresses = await sdk.getIdentityAddresses({
  names: ['alice.snow', 'bob.snow'],
  caip2Id: NETWORKS.MOVEMENT.TESTNET,
});

Using Wildcard CAIP2 IDs

You can use wildcard CAIP2 IDs to query across all networks in a namespace:

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

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

Error Handling

The SDK provides a custom SnowstormError class for proper 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

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

Get the identity name associated with an address.

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

Get the address associated with an identity name.

getIdentityMetadata(name: string): Promise<IdentityMetadata>

Get metadata associated with an identity.

getIdentityNames(params: GetIdentityNamesByAddressesRequest): Promise<BatchIdentityNames>

Batch resolve names for multiple addresses.

getIdentityAddresses(params: GetIdentityAddressesByNamesRequest): Promise<BatchIdentityAddresses>

Batch resolve addresses for multiple names.

Types

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;
  }>;
}

CAIP2 ID Format

CAIP2 IDs follow the format: namespace:reference

The SDK uses @snowballmoney/chain-agnostic-utils for standardized network identification. Examples:

• move-mvmt:testnet - Movement testnet
• move-mvmt:mainnet - Movement mainnet
• move-mvmt:* - All Movement networks

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Generate documentation
npm run docs

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License - see the LICENSE file for details.