TypeScript

TypeScript SDK for issuing and managing tokens on Spark. Requires Node.js v18+.

Getting Started

To get started, follow the steps below.

Want to skip the manual setup? Scaffold a new project instantly:

npx @buildonspark/create-spark-app my-app

Supports React (Vite), Next.js, React Native, Expo, Express, and more.

Install SDK

Install the Spark Issuer SDK packages using your package manager of choice.

npm install @buildonspark/issuer-sdk

yarn add @buildonspark/issuer-sdk

pnpm add @buildonspark/issuer-sdk

Setup Issuer

Create an issuer instance that will be used to interact with the Spark network.

issuer.ts

  import { IssuerSparkWallet } from "@buildonspark/issuer-sdk";

  const { wallet, mnemonic } = await IssuerSparkWallet.initialize({
    mnemonicOrSeed: "optional-mnemonic-or-seed",
    accountNumber: 0, // optional
    options: {
      network: "REGTEST",
    },
  });
  console.log("Wallet initialized successfully:", mnemonic);

Start Building

You’re ready to start building.

app.ts

import { IssuerSparkWallet } from "@buildonspark/issuer-sdk";

async function main() {
  try {
    // Initialize issuer wallet
    const { wallet } = await IssuerSparkWallet.initialize({
      options: { network: "REGTEST" }
    });

    console.log("Issuer wallet created!");
    console.log("Address:", await wallet.getSparkAddress());

    // Create a token
    const { tokenIdentifier, transactionHash } = await wallet.createToken({
      tokenName: "My Token",
      tokenTicker: "MTK",
      decimals: 8,
      maxSupply: BigInt(21000000_00000000), // 21M tokens (with 8 decimals)
      isFreezable: false,
      returnIdentifierForCreate: true,
    });

    console.log("Token created:", tokenIdentifier);
    console.log("Announcement tx:", transactionHash);

    // Mint tokens to yourself
    const mintTxId = await wallet.mintTokens({
      tokenIdentifier,
      tokenAmount: BigInt(1000_00000000), // 1000 tokens (with 8 decimals)
    });
    console.log("Tokens minted:", mintTxId);
  } catch (error) {
    console.error("Error:", error);
  }
}

main();

TypeScript Configuration

tsconfig.json

Create a tsconfig.json file in your project root:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Package.json Scripts

Add TypeScript build scripts to your package.json:

package.json

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/app.js",
    "dev": "ts-node src/app.ts",
    "watch": "tsc --watch"
  }
}

Core Issuer Operations

Initialize an Issuer Wallet

An issuer wallet requires either a mnemonic or raw seed for initialization. The initialize() function accepts both. If no input is given, it will auto-generate a mnemonic and return it.

import { IssuerSparkWallet } from "@buildonspark/issuer-sdk";

// Initialize a new issuer wallet
const { wallet, mnemonic } = await IssuerSparkWallet.initialize({
  mnemonicOrSeed: "optional-mnemonic-or-seed",
  accountNumber: 0, // optional
  options: {
    network: "REGTEST" // or "MAINNET"
  }
});

console.log("Issuer wallet initialized:", mnemonic);

Mnemonic Phrases

A mnemonic is a human-readable encoding of your wallet’s seed. It’s a 12- or 24-word phrase from the BIP-39 wordlist, used to derive the cryptographic keys that control your issuer wallet.

TypeScript Features

Type Safety

The Spark Issuer TypeScript SDK provides full type safety for all issuer operations:

import { IssuerSparkWallet } from "@buildonspark/issuer-sdk";

// TypeScript will provide autocomplete and type checking
const { wallet } = await IssuerSparkWallet.initialize({
  options: { network: "REGTEST" }
});

// All methods are fully typed
const address: string = await wallet.getSparkAddress();
const tokensMetadata = await wallet.getIssuerTokensMetadata();
const tokenIdentifiers = await wallet.getIssuerTokenIdentifiers();

Interface Definitions

Key interfaces used by the Issuer SDK:

// Token creation parameters
interface CreateTokenParams {
  tokenName: string;
  tokenTicker: string;
  decimals: number;
  isFreezable: boolean;
  maxSupply?: bigint; // defaults to 0n (unlimited)
  extraMetadata?: Uint8Array;
  returnIdentifierForCreate?: boolean;
}

// Token metadata returned by getIssuerTokensMetadata()
interface IssuerTokenMetadata {
  rawTokenIdentifier: Uint8Array;
  tokenPublicKey: string;
  tokenName: string;
  tokenTicker: string;
  decimals: number;
  maxSupply: bigint;
  isFreezable: boolean;
  extraMetadata?: Uint8Array;
  bech32mTokenIdentifier: Bech32mTokenIdentifier;
}

// Token distribution stats
interface TokenDistribution {
  totalCirculatingSupply: bigint;
  totalIssued: bigint;
  totalBurned: bigint;
  numHoldingAddress: number;
  numConfirmedTransactions: bigint;
}

Error Handling

The SDK provides typed error classes for better error handling:

import { IssuerSparkWallet } from "@buildonspark/issuer-sdk";
import { SparkError, SparkValidationError } from "@buildonspark/spark-sdk";

const { wallet } = await IssuerSparkWallet.initialize({
  options: { network: "REGTEST" },
});

try {
  await wallet.createToken({
    tokenName: "My Token",
    tokenTicker: "MTK",
    decimals: 8,
    maxSupply: BigInt(21000000_00000000),
    isFreezable: false
  });
} catch (error) {
  if (error instanceof SparkValidationError) {
    console.error('Validation error:', error.message);
  } else if (error instanceof SparkError) {
    console.error('SDK error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Introduction

Installation

Wallet

Token

Data

Tools

Getting Started

TypeScript Configuration

tsconfig.json

Package.json Scripts

Core Issuer Operations

Initialize an Issuer Wallet

Mnemonic Phrases

TypeScript Features

Type Safety

Interface Definitions

Error Handling

​Getting Started

​TypeScript Configuration

​tsconfig.json

​Package.json Scripts

​Core Issuer Operations

​Initialize an Issuer Wallet

​Mnemonic Phrases

​TypeScript Features

​Type Safety

​Interface Definitions

​Error Handling

Getting Started

TypeScript Configuration

tsconfig.json

Package.json Scripts

Core Issuer Operations

Initialize an Issuer Wallet

Mnemonic Phrases

TypeScript Features

Type Safety

Interface Definitions

Error Handling