TypeScript Client

️⚠️

NTS is in active development and currently unstable. It is open to select early developers for exploration but is not yet suitable for production use. Follow developer updates for the latest changes, as performance is not at production level.

The TypeScript client provides a comprehensive library for interacting with NTS apps on the N1 network. It handles transaction execution, data reading/writing, app management, and token operations through a type-safe interface.

Installation


npm install @n1xyz/nts-sdk

Initialization


import { NAppClient } from "@n1xyz/nts-sdk";
 
// Initialize the client with required parameters
const client = new NAppClient(
  "https://network-rpc-url.com", // NTS network URL
  "your-app-id", // App ID
  appIdl, // App IDL (Interface Description Language)
  walletPublicKey, // Wallet public key as Uint8Array
  sessionPublicKey, // Optional: Session public key as Uint8Array
  signMessageWithSessionKey // Optional: Function to sign messages with session key
);

Core Features

Action Execution

The client automatically creates proxy methods for all actions defined in your app’s IDL. You can call these methods directly:


// If your IDL defines an action "transfer(amount: bigint, recipient: string)"
const result = await client.transfer(BigInt(1000), "recipient-address");
 
// The result includes transaction details
console.log(result.transactionId); // Transaction ID
console.log(result.success); // Transaction success status
console.log(result.logs); // Transaction logs
console.log(result.transactionWrites); // Data changes from transaction

App Information


// Get app's IDL
const idl = client.getIdl();
 
// List available actions
const actions = client.getActions();
 
// Get signature for specific action
const signature = client.getActionSignature("actionName");
 
// Get app metadata
const metadata = await client.getMetadata();
 
// Get app code
const code = await client.getCode();

Data Operations


// Get all fields
const allFields = await client.getFields();
 
// Get fields by tag
const taggedFields = await client.getFieldsByTag("tag-name");
 
// Read specific field
const fieldValue = await client.readField("field-id");

Transaction History


// Get app transactions
const transactions = await client.getTransactions();
// With pagination
const moreTx = await client.getTransactions("last-tx-id");
 
// Get specific transaction
const tx = await client.getTransaction("transaction-id");

Token Operations


// Get user balances for this app
const userBalances = await client.getUserBalances("user-address");
 
// Get all app balances
const appBalances = await client.getBalances();

Session Management


// Validate session key
const isValid = await client.validateSessionKey("session-key", "public-key");

Error Handling

The client includes built-in error handling for network requests, transaction processing, and argument validation:


try {
  // Actions will validate arguments against IDL
  const result = await client.transfer(BigInt(1000), "recipient");
} catch (error) {
  console.error("Error executing transfer:", error);
}

Types

The client exports several TypeScript types for better development experience:


interface TransactionResult {
  transactionId: string;
  createdAt: string;
  appId: string;
  transactionData: TransactionData;
  transactionWrites: TransactionWrite[];
  action: string;
  caller: string;
  success: boolean;
  logs: string[];
}
 
interface TransactionWrite {
  tag: string;
  value: any;
  fieldId: string;
}
 
interface AppData {
  app_id: string;
  field_id: string;
  value: any;
  tag: string;
}
 
interface Balance {
  mint: string;
  balance: string;
  appId: string;
  appType: "ono" | "cluster";
  clusterAppId?: string;
}