Nuklai SDK

A modular interface for interacting with the Nuklai blockchain, built on top of the Avalanche HyperSDK.

📦 Installation

npm install @nuklai/nuklai-sdk
# or
yarn add @nuklai/nuklai-sdk

🚀 Quick Start

import { NuklaiSDK } from "@nuklai/nuklai-sdk";

const sdk = new NuklaiSDK("http://127.0.0.1:9650");
const healthStatus = await sdk.rpcService.validateConnection();

✨ Core Features

• 💰 Asset Management (Fungible/Non-Fungible Tokens)
• 📊 Dataset Creation and Management
• 🏪 Marketplace Operations
• 💳 Transaction Management
• 🔍 Network Status and Health Checks
• 🏛️ Validator Management
• 📈 Staking Operations

📖 Basic Usage

Initialization

import { NuklaiSDK } from "@nuklai/nuklai-sdk";

const sdk = new NuklaiSDK({
  baseApiUrl: "http://127.0.0.1:9650",
});

// Set the signer for transactions
sdk.rpcService.setSigner("your-private-key-here");

Wallet Generation

// Create SDK instance
const sdk = new NuklaiSDK();

// Create a new random wallet
const wallet = sdk.createWallet();
console.log("Wallet address:", wallet.getAddress());

// Get wallet's private key
const privateKey = wallet.getPrivateKey();
console.log("Private key:", privateKey); // Returns the 128-character private key string

// Or import an existing wallet
const importedWallet = sdk.importWalletFromPrivateKey("your-private-key-hex");

// Check wallet connection
if (sdk.isWalletConnected()) {
    // Use wallet features
    const address = sdk.getAddress();
}

Signer

// Using a private key string (old way)
await sdk.rpcService.setSigner(privateKeyString);

// Using a wallet's signer (new way)
await sdk.rpcService.setSigner(wallet.getSigner());

// Using any custom signer that implements SignerIface
await sdk.rpcService.setSigner(customSigner);

Asset Management

// Create a fungible token
const ftResult = await sdk.rpcService.createFTAsset(
  "Test Token",
  "TEST",
  9,
  "metadata",
  BigInt("1000000000000000000"), // Max supply
  "owner-address",
  "admin-address",
  "admin-address",
  "admin-address"
);

// Create an NFT collection
const nftResult = await sdk.rpcService.createNFTAsset(
  "Test NFT",
  "TNFT",
  "metadata",
  BigInt(1000), // Max supply
  "owner-address",
  "admin-address",
  "admin-address",
  "admin-address"
);

Token Operations

// Mint fungible tokens
const mintAmount = BigInt("1000000000000000000"); // 1 token
const mintResult = await sdk.rpcService.mintFTAsset(
  "receiver-address",
  "token-address",
  mintAmount
);

// Mint NFT
const nftMintResult = await sdk.rpcService.mintNFTAsset(
  "nft-collection-address",
  JSON.stringify({
    name: "Test NFT #1",
    description: "First NFT",
    attributes: [],
  }),
  "receiver-address"
);

// Transfer tokens
const transferAmount = BigInt("100000000000000000"); // 0.1 token
const transferResult = await sdk.rpcService.transfer(
  "recipient-address",
  "token-address",
  transferAmount,
  "Transfer memo"
);

Check Address Balance

// Get native NAI token balance
const nativeBalance = await sdk.rpcService.getBalance("address");

// Get any asset balance by passing asset address
const assetBalance = await sdk.rpcService.getBalance("address", "assetAddress");

NOTE: Balance is returned as raw strings without decimal formatting. Use asset decimals info from getAssetInfo() to correctly format & display the balance corectly.

Dataset Operations

// Create a dataset
const result = await sdk.rpcService.createDataset(
  "asset-address",
  "Test Dataset",
  "Description",
  "AI,Testing",
  "MIT",
  "MIT",
  "https://opensource.org/licenses/MIT",
  "metadata",
  true // isCommunityDataset
);

🛠️ Development

Build from source:

yarn
yarn build

Run tests:

yarn test

📝 Examples

The examples/ directory contains sample implementations:

examples/
├── datasets.ts            # Dataset creation and management
├── fungible-tokens.ts     # Fungible Token operations
├── non-fungible-tokens.ts # Non-Fungible Token operations
└── marketplace.ts         # Marketplace interactions

You can run all examples at once using:

yarn examples

Or run individual examples:

ts-node --esm examples/fungible-tokens.ts
ts-node --esm examples/non-fungible-tokens.ts

📚 API Reference

All methods are accessible through the sdk.rpcService instance. Below is a comprehensive reference of available methods grouped by their functionality.

Network Operations

Method	Description	Parameters	Returns
validateConnection()	Checks node connectivity	None	Promise<boolean>
getEmissionInfo()	Retrieves emission statistics	None	Promise<ActionOutput>
getAllValidators()	Lists all validators	None	Promise<ActionOutput>
getStakedValidators()	Lists validators with stake	None	Promise<ActionOutput>
getValidatorStake(nodeID)	Gets specific validator stake	nodeID: string	Promise<ActionOutput>

Asset Management

Fungible Token Methods

Method	Description	Parameters	Returns
createFTAsset()	Creates a new Fungible Token	- name: string - symbol: string - decimals: number - metadata: string - maxSupply: bigint - mintAdmin: string - pauseAdmin: string - freezeAdmin: string - kycAdmin: string	Promise<TxResult>
mintFTAsset()	Mints Fungible Tokens	- to: string - assetAddress: string - amount: bigint	Promise<TxResult>
transfer()	Transfers tokens	- to: string - assetAddress: string - value: bigint - memo: string	Promise<TxResult>

Non-Fungible Token Methods

Method	Description	Parameters	Returns
createNFTAsset()	Creates an NFT collection	- name: string - symbol: string - metadata: string - maxSupply: bigint - mintAdmin: string - pauseAdmin: string - freezeAdmin: string - kycAdmin: string	Promise<TxResult>
mintNFTAsset()	Mints a new NFT	- assetAddress: string - metadata: string - to: string	Promise<TxResult>

Dataset & Marketplace Operations

Dataset Methods

Method	Description	Parameters	Returns
createDataset()	Creates a new dataset	- assetAddress: string - name: string - description: string - categories: string - licenseName: string - licenseSymbol: string - licenseURL: string - metadata: string - isCommunityDataset: boolean	Promise<TxResult>
updateDataset()	Updates dataset info	- datasetAddress: string - name: string - description: string - categories: string - licenseName: string - licenseSymbol: string - licenseURL: string - isCommunityDataset: boolean	Promise<TxResult>
getDatasetInfo()	Gets dataset details	datasetID: string	Promise<ActionOutput>

Marketplace Methods

Method	Description	Parameters	Returns
publishDatasetToMarketplace()	Lists dataset on marketplace	- datasetAddress: string - paymentAssetAddress: string - datasetPricePerBlock: number	Promise<TxResult>
subscribeDatasetMarketplace()	Subscribes to dataset	- marketplaceAssetAddress: string - paymentAssetAddress: string - numBlocksToSubscribe: number	Promise<TxResult>
claimMarketplacePayment()	Claims marketplace earnings	- marketplaceAssetAddress: string - paymentAssetAddress: string	Promise<TxResult>

Query Methods

Method	Description	Parameters	Returns
getBalance()	Get's address balance	address: string	Promise<string>
getAssetInfo()	Get's asset details	assetAddress: string	Promise<ActionOutput>
getDatasetBalance()	Get's dataset balance	- address: string - assetID: string	Promise<ActionOutput>
getDatasetNFTInfo()	Get's NFT details	nftID: string	Promise<ActionOutput>
getPendingContributions()	Lists pending contributions	datasetID: string	Promise<ActionOutput>
getPrivateKey()	Get's wallet's private key	None	string
getAddress()	Get's wallet's address	None	string
getPublicKey()	Get's wallet's public key	None	string

Usage Example

Creating and minting a fungible token

// Create a FT
const ftResult = await sdk.rpcService.createFTAsset(
  "Test Token",
  "TEST",
  9,
  "metadata",
  BigInt("1000000000000000000"),
  "owner-address",
  "admin-address",
  "admin-address",
  "admin-address"
);

// After creation, mint some tokens
const mintResult = await sdk.rpcService.mintFTAsset(
  "receiver-address",
  ftResult.result[0].asset_address,
  BigInt("1000000000000000000")
);

📄 License

MIT License - see LICENSE for details.