> For the complete documentation index, see [llms.txt](https://snowball-mns.gitbook.io/snowball/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://snowball-mns.gitbook.io/snowball/decentralized-identity-layer/technical-documentation/typescript-sdk.md).

# 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.

{% hint style="info" %}
This SDK uses CAIP-2 standard for network identification. Make sure to familiarize yourself with CAIP-2 concepts before proceeding.
{% endhint %}

### Overview

MNS SDK leverages the [@snowballmoney/chain-agnostic-utils](https://www.npmjs.com/package/@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:

```bash
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:

```typescript
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:

```typescript
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)**

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

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

**Reverse Resolution (Name to Address)**

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

#### Batch Operations

For better performance when working with multiple identities:

```typescript
// 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:

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

### Error Handling

The SDK provides structured error handling:

```typescript
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

```typescript
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:

```typescript
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](/snowball/decentralized-identity-layer/technical-documentation/caip2.md)
* [Chain Agnostic Utils Documentation](https://www.npmjs.com/package/@snowballmoney/chain-agnostic-utils)

### 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