Introduction to N1TS

Welcome to N1TS or NTS (N1 TypeScript), a powerful platform for building smart contracts using TypeScript on the N1 network.

What is N1TS?

N1TS is a comprehensive TypeScript development environment for building decentralized applications on the N1 blockchain. You use familiar TypeScript syntax to write smart contracts (called ‘apps’ in N1 terminology) that run in a secure, sandboxed environment with automatic state management and built-in token operations.

Under the hood, N1TS provides:

• TypeScript Compilation: Automatic compilation and bundling of your TypeScript code
• Secure Execution: Code runs in a secure, isolated environment
• State Management: Automatic persistence and retrieval of application state
• Token System: Native support for minting, transferring, and managing tokens
• Cross-Cluster Operations: Send tokens and data across different network clusters

Architecture Overview

N1TS provides a complete TypeScript-to-blockchain execution environment:

Your TypeScript Code
        ↓
    N1TS Compiler
        ↓
    Secure Execution
        ↓
    Blockchain State Updates

Main Features

Core Concepts

NApp Base Class

All N1TS applications extend the NApp base class, which provides:

• Automatic State Management: Properties are automatically persisted to blockchain state
• Built-in Methods: Access to blockchain functions and transaction context
• Security: Protected execution environment with validation
• Transaction Context: Access to signer, app admin, timestamp, and other context

Available Functions

N1TS provides these core functions for blockchain operations:

• nread(fieldId, appId?) - Read data from storage
• nwrite(fieldId, value, tag?, secondary_tag?) - Write data to storage
• nmint(totalSupply, admin, meta) - Create new tokens
• nmintEdit(mint, freeSupply, admin, meta) - Edit existing tokens
• ntransfer(origin, destination, mint, amount, args?) - Transfer tokens
• ntransferToCluster(origin, clusterId, mint, amount, args?) - Cross-cluster transfer
• log(...args) - Logging function

Context Methods

Access transaction and app context through these methods:

• this.signer() - Get transaction signer address
• this.appAdmin() - Get app admin address
• this.appId() - Get current app ID
• this.time() - Get current timestamp

// ❌ Wrong: Transaction action with return value
createToken(): string {
  const mintId = nmint(BigInt(1000), this.signer(), "Token");
  return mintId; // This is ignored in transactions!
}
 
// ✅ Correct: Transaction action for state change only
createToken(): void {
  nmint(BigInt(1000), this.signer(), "Token");
  this.log("Token creation initiated");
}
 
// ✅ Correct: Read state via client queries, not actions
// Use client.readField() or app state queries externally

// ❌ Wrong: Direct property initialization (except NMap)
class MyApp extends NApp {
  counter: number = 0; // This doesn't work!
  users: NMap<User> = new NMap<User>(this, 'users'); // ✅ This is correct for NMap
}
 
// ✅ Correct: Initialize properties properly
class MyApp extends NApp {
  counter: number;
  users: NMap<User> = new NMap<User>(this, 'users'); // NMap initialized directly
  
  init(): void {
    this.counter = 0; // Regular properties in init()
  }
}

Execution Model

N1TS apps run with these characteristics:

• Resource Limits: Built-in constraints for security and performance
• Timeout Protection: Execution time limits prevent infinite loops
• Isolated Context: Each transaction runs in complete isolation
• Atomic Operations: All changes succeed together or fail together - no partial writes

Transaction Lifecycle

1. Transaction Received: Network receives signed transaction
2. Validation: Signature and permission validation
3. Execution: Method executed in secure, isolated environment
4. State Commit: All changes written to blockchain state atomically (or all reverted on failure)
5. Response: Success/failure response with transaction logs

Token System

N1TS features a sophisticated native token system:

Key Characteristics

• BigInt Precision: All token amounts use BigInt for arbitrary precision
• Admin-Controlled: Every token has an admin who can modify properties
• Cluster-Aware: Tokens can be transferred across network clusters
• Validation-Heavy: Extensive checks prevent invalid operations
• Event-Logged: All operations are comprehensively logged

Token Operations

• Minting: Create new tokens with nmint(totalSupply, admin, meta)
• Transfers: Move tokens with ntransfer(origin, destination, mint, amount, args?)
• Cross-Cluster: Bridge tokens with ntransferToCluster(origin, clusterId, mint, amount, args?)
• Admin Functions: Edit tokens with nmintEdit(mint, freeSupply, admin, meta)

Data Management

Automatic Persistence

Properties assigned to this are automatically saved:

class MyApp extends NApp {
  counter: number; // ❌ Cannot initialize here: counter: number = 0;
 
  init(): void {
    this.counter = 0; // ✅ Initialize in init() method
  }
 
  increment(): void { // ✅ No return value for transaction actions
    this.counter++; // Automatically persisted
    this.log("Counter incremented to:", this.counter);
  }
}

NMap Collections

For key-value data, use typed NMap collections:

class UserManager extends NApp {
  users: NMap<UserProfile> = new NMap<UserProfile>(this, 'users');
 
  init(): void {
    // Initialize other properties here if needed
  }
 
  createUser(userId: string, profile: UserProfile): void {
    this.users.set(userId, profile, 'user_creation', userId);
  }
}

Pre-Requisite Knowledge

To get the most out of N1TS development:

• TypeScript/JavaScript: Solid understanding of modern TypeScript features
• Blockchain Concepts: Basic understanding of smart contracts and transactions
• Async Programming: Familiarity with async/await and Promises
• State Management: Understanding of application state and persistence

Development Workflow

1. Setup: Install N1TS compiler and SDK packages
2. Write: Create TypeScript app extending NApp class
3. Test: Use built-in testing utilities and mock environments
4. Compile: Generate JavaScript and IDL using N1TS compiler
5. Deploy: Deploy to N1 network using SDK tools
6. Interact: Call app methods using client SDK

Security Model

N1TS provides multiple layers of security:

Permission System

• Protected Fields: Fields starting with _ require admin access
• Token Admin Rights: Token admins can transfer any tokens of that type
• App Admin Controls: Special privileges within app context

Validation Checks

• Balance Verification: Transfers require sufficient token balance
• Permission Validation: Third-party operations require proper authorization
• Input Sanitization: All inputs are validated before processing

Join our Community

If you have questions or want to contribute:

• Discord  - Join our developer community
• GitHub  - Contribute to the codebase
• Documentation - Explore comprehensive guides and examples

Get involved in the N1TS ecosystem and help us build the future of decentralized applications using TypeScript!