NApp Class

The NApp class is the base building block for creating apps on N1 using TypeScript. It provides a state management system with automatic persistence and transaction handling. All NTS apps on N1 need to inherit from this class.

Usage

Creating an Application

To create an App, extend the NApp class:

import { NApp } from "@n1xyz/nts-compiler";
 
class MyApp extends NApp {}

Creating State

The NMap class is a specialized key-value type for N1 applications that provides persistent storage with automatic state management. It’s designed to work seamlessly with the NApp class to store and manage data.

import { NMap } from "@n1xyz/nts-compiler";
 
class MyApp extends NApp {
  private messages = new NMap<string>(this, "messages");
 
  // the rest of your code...
}

Creating Actions

Actions are methods/ functions that can be called on your App by users. When sending a transaction to the N1 network, the user specifies the action they want to call.

To create an action, you need to expose it using the createExecutableFunctions utility. If you don’t expose the action, it will not be callable by users.

Don’t forget to import createExecutableFunctions from the @n1xyz/nts-sdk package.

import { createExecutableFunctions, NApp } from "@n1xyz/nts-compiler";
 
export class MyApp extends NApp {
  private messages = new NMap<string>(this, "messages");
 
  setMessage(message: string): void {
    this.messages.set(this.signer(), message);
  }
}
 
export const { setMessage } = createExecutableFunctions(MyApp);

Using system Actions

The NApp class provides several system actions that come prebuilt. These system actions can’t be modified, but can be used in your App. System actions are prefixed with an underscore _.

// Import the system actions
import {
  _mint,
  _mintTransfer,
  _transfer,
  _withdraw,
  createExecutableFunctions,
  NApp,
} from "@n1xyz/nts-compiler";
 
class MyApp extends NApp {
  withdraw(
    amount: string | number | bigint,
    mint: string,
    destinationAppId: string,
    receiverOpt?: string
  ) {
    // Call the system actions directly within your own actions
    _withdraw(BigInt(amount), mint, destinationAppId, receiverOpt);
  }
 
  mintTransfer(
    amount: string | number | bigint,
    mint: string,
    destination: string
  ) {
    _mintTransfer(BigInt(amount), mint, destination);
  }
 
  mint(totalSupply: string | number | bigint, admin: string, meta: any) {
    _mint(BigInt(totalSupply), admin, meta);
  }
 
  transfer(amount: string | number | bigint, mint: string, receiver: string) {
    _transfer(BigInt(amount), mint, receiver);
  }
 
  /*
  Your code here
  */
}
 
export const { mint, transfer, withdraw, mintTransfer } =
  createExecutableFunctions(Counter);

API Reference

System Actions

_getBalance

function _getBalance(mint: string, address: string): bigint;

Gets the token balance for a specific address and mint.

• mint: The mint address of the token
• address: The user address to check the balance for
• Returns: The balance as a BigInt

_deposit

function _deposit(
  amount: string | number | bigint,
  mint: string,
  args: { receiver: string }
): void;

Deposits tokens into a user’s balance. The args parameter must be a JSON string containing a “receiver” field.

• amount: Amount to deposit (will be converted to BigInt)
• mint: The mint address of the token
• args: Object containing a “receiver” field specifying who receives the deposit

_withdraw

function _withdraw(
  amount: bigint,
  mint: string,
  destinationAppId: string,
  receiverOpt?: string,
  senderOpt?: string
): void;

Withdraws tokens from a user’s balance and sends them to another app.

• amount: Amount to withdraw
• mint: The mint address of the token
• destinationAppId: The app ID to send the tokens to
• receiverOpt: Optional receiver address (defaults to transaction signer)
• senderOpt: Optional sender address (defaults to transaction signer)

_withdrawToCluster

function _withdrawToCluster(
  amount: bigint,
  mint: string,
  destinationClusterId: string,
  receiverOpt?: string,
  senderOpt?: string
): void;

Withdraws tokens from a user’s balance and sends them to another cluster.

• amount: Amount to withdraw
• mint: The mint address of the token
• destinationClusterId: The cluster ID to send the tokens to
• receiverOpt: Optional receiver address (defaults to transaction signer)
• senderOpt: Optional sender address (defaults to transaction signer)

_mintTransfer

function _mintTransfer(amount: bigint, mint: string, destination: string): void;

Transfers tokens from the mint admin’s balance to a destination address. Can only be called by the mint admin.

• amount: Amount to transfer
• mint: The mint address of the token
• destination: The destination address to receive the tokens

_mint

function _mint(totalSupply: bigint, admin: string, meta: any): string;

Creates a new token mint with specified total supply and admin.

• totalSupply: Total supply of the token
• admin: Address of the mint admin
• meta: Metadata for the token
• Returns: The new mint address

_transfer

function _transfer(
  amount: bigint,
  mint: string,
  receiver: string,
  senderOpt?: string
): void;

Transfers tokens between user addresses.

• amount: Amount to transfer
• mint: The mint address of the token
• receiver: The receiving address
• senderOpt: Optional sender address (defaults to transaction signer)

_getMintAdmin

function _getMintAdmin(mint: string): string;

Gets the admin address for a specific mint.

• mint: The mint address of the token
• Returns: The admin address

_getAdminSupply

function _getAdminSupply(mint: string): bigint;

Gets the remaining admin supply for a specific mint.

• mint: The mint address of the token
• Returns: The admin supply as a BigInt

Utility Functions

createExecutableFunctions

export function createExecutableFunctions<T extends NApp>(
  AppClass: Constructor<T>
): Record<string, Function>;

Exposes methods in the App as executable actions that can be called by users.