# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://snowball-mns.gitbook.io/snowball/decentralized-identity-layer/technical-documentation/typescript-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.