@quantabit/qbit-chain-sdk

QBit Chain core interaction layer — production-grade blockchain SDK for QBit Chain (Solana-compatible).

Features

• Connection Management — Auto-retry (exponential backoff), Genesis Hash network validation, WebSocket auto-derivation, sdk-config sync
• Key Management — BIP44 (m/44'/766') Ed25519 keypair generation, mnemonic backup, legacy path (m/44'/766') compatibility
• Transactions — QBT transfer, SPL Token transfer (auto ATA creation), batch transfer, multi-signer support, sign/broadcast separation
• SPL Token Lifecycle — Create mint, mint, burn, approve/revoke, freeze/thaw, set authority, close account
• Account Queries — Balance, token holdings, mint info, ATA lookup, transaction history
• Staking — Create stake accounts, delegate/deactivate/withdraw, validator listing
• RPC Utilities — Health check, chain status summary, epoch info, supply, cluster nodes, block queries, performance samples, inflation, devnet airdrop
• Error Handling — 8 specialized error classes with structured codes for precise error recovery
• Real-time Subscriptions — WebSocket account monitoring, program logs, slot changes, signature confirmation
• Token Registry — Built-in metadata (QBT/USDC/USDT/wSOL), auto-discovery, amount formatting
• Transaction Parser — Decode raw transactions into structured events with human-readable summaries
• Program Interaction — PDA derivation, instruction builder, execution/simulation, Borsh serialization helpers
• TypeScript — Complete type definitions (600+ lines)

Installation

npm install @quantabit/qbit-chain-sdk

Quick Start

import { QBitConnection, QBitKeypair, QBitTransaction } from '@quantabit/qbit-chain-sdk';

// Connect to QBit mainnet
const conn = new QBitConnection(); // defaults to mainnet

// Validate network identity (Genesis Hash check)
const { valid } = await conn.validateNetwork();
console.log('Network valid:', valid);

// Generate a keypair (BIP44 path: m/44'/766'/0'/0')
const kp = await QBitKeypair.generate();
console.log('Address:', kp.address);
console.log('Mnemonic:', kp.mnemonic);

// Check balance
const balance = await conn.getBalanceQBT(kp.address);
console.log(`Balance: ${balance} QBT`);

Networks

| Network | RPC Endpoint | Genesis Hash | |---------|-------------|--------------| | Mainnet | https://api.mainnet.qbitchain.io/ | HuM99k8A... | | Devnet | https://api.devnet.qbitchain.io/ | BmBSkzpt... |

// Mainnet (default)
const conn = new QBitConnection();

// Devnet
const conn = new QBitConnection({ network: 'devnet' });

// Custom endpoint
const conn = new QBitConnection({ endpoint: 'https://my-rpc.example.com/' });

// Switch network at runtime
conn.switchNetwork('devnet');

Key Management

import { QBitKeypair, generateMnemonic, validateMnemonic } from '@quantabit/qbit-chain-sdk';

// Generate new keypair with mnemonic (BIP44: m/44'/766'/0'/0')
const kp = await QBitKeypair.generate();

// Legacy path compatibility for existing wallets
const kpLegacy = await QBitKeypair.generate({ useLegacyPath: true }); // m/44'/766'/0'/0'

// Restore from mnemonic
const restored = await QBitKeypair.fromMnemonic('your twelve word mnemonic ...');

// Restore from private key
const fromKey = QBitKeypair.fromPrivateKey('base58PrivateKey...');

// Derive multiple accounts from one mnemonic
const accounts = await QBitKeypair.deriveMultiple(mnemonic, 5);

// Sign a message
const signature = kp.signBase58('Hello QBit');

// Clean up sensitive data
kp.destroy();

Transactions

QBT Transfer

import { QBitTransaction, transferQBT } from '@quantabit/qbit-chain-sdk';

// Quick transfer
const result = await transferQBT(conn, myKeypair, 'ReceiverAddress', 1.5, {
  memo: 'Payment',
});
console.log('Tx:', result.signature);

// Builder pattern
const tx = new QBitTransaction(conn);
tx.transfer(myKeypair.address, 'ReceiverAddress', 1.5);
tx.addMemo('Payment note');
const sig = await tx.sendAndConfirm(myKeypair);

SPL Token Transfer

import { QBitTransaction, transferToken } from '@quantabit/qbit-chain-sdk';

// Auto-creates recipient ATA if needed
const result = await transferToken(
  conn, myKeypair,
  'ReceiverAddress',
  'TokenMintAddress',
  1000000,  // raw amount
  9,        // decimals
);

Batch Transfer

const tx = new QBitTransaction(conn);
tx.batchTransfer(myKeypair.address, [
  { to: 'Address1', amountQBT: 1.0 },
  { to: 'Address2', amountQBT: 2.0 },
  { to: 'Address3', amountQBT: 3.0 },
]);
await tx.sendAndConfirm(myKeypair);

Transaction Simulation

const tx = new QBitTransaction(conn);
tx.transfer(from, to, 1.0);
const sim = await tx.simulate(myKeypair);
console.log('Fee:', sim.estimatedFee, 'Units:', sim.unitsConsumed);
console.log('Logs:', sim.logs);

SPL Token Lifecycle

Beyond transfers, the SDK provides the full token lifecycle. All operations broadcast via HTTP polling confirmation (no WebSocket dependency).

import {
  createMint, getOrCreateTokenAccount, mintTo, burn,
  approve, revoke, freezeAccount, thawAccount,
  setAuthority, closeTokenAccount,
} from '@quantabit/qbit-chain-sdk';

// Issue a new token (6 decimals). payer becomes mint + freeze authority by default.
const { mint } = await createMint(conn, payer, { decimals: 6 });

// Ensure a recipient has an associated token account
const { address } = await getOrCreateTokenAccount(conn, payer, mint, recipientAddress);

// Mint 1000 tokens (raw = 1000 * 10^6); recipient ATA is auto-created if missing
await mintTo(conn, mintAuthority, mint, recipientAddress, 1000 * 1e6);

// Burn tokens from the owner's ATA
await burn(conn, owner, mint, 500 * 1e6, { decimals: 6 });

// Delegate / revoke spending authority
await approve(conn, owner, mint, delegateAddress, 100 * 1e6);
await revoke(conn, owner, mint);

// Freeze / thaw (requires freeze authority)
await freezeAccount(conn, freezeAuthority, mint, ownerAddress);
await thawAccount(conn, freezeAuthority, mint, ownerAddress);

// Renounce mint authority permanently (newAuthority = null)
await setAuthority(conn, mintAuthority, mint, 'MintTokens', null);

// Close an empty token account and reclaim rent
await closeTokenAccount(conn, owner, mint, rentDestination);

Multi-signer Transactions

const tx = new QBitTransaction(conn);
tx.addInstruction(someInstruction);
tx.addSigner(extraKeypair);          // additional required signer
await tx.sendAndConfirm(payer, { feePayer: payer.address });

Staking

import {
  createStakeAccount, delegate, deactivate, withdrawStake,
  getStakeActivation, getValidators,
} from '@quantabit/qbit-chain-sdk';

// List validators
const validators = await getValidators(conn);
console.log('Active validators:', validators.current.length);

// Create stake account and delegate
const stake = await createStakeAccount(conn, myKeypair, validatorVotePubkey, 10);
console.log('Stake account:', stake.stakeAccount);

// Check activation status
const activation = await getStakeActivation(conn, stake.stakeAccount);
console.log('State:', activation.state); // 'activating' -> 'active'

// Deactivate and withdraw
await deactivate(conn, myKeypair, stake.stakeAccount);
await withdrawStake(conn, myKeypair, stake.stakeAccount, myKeypair.address);

Chain Status

import { getChainStatus, getChainHealth } from '@quantabit/qbit-chain-sdk';

// Quick health check
const health = await getChainHealth(); // 'ok'

// Full chain status (single call)
const status = await getChainStatus();
// {
//   health: 'ok',
//   network: 'mainnet',
//   version: '4.0.0-beta.6',
//   epoch: 13,
//   blockHeight: 394991,
//   totalSupplyQBT: 10000010011.175579,
//   circulatingQBT: 10000010011.175579,
//   slotProgress: '52.8%',
// }

Connection Options

const conn = new QBitConnection({
  network: 'mainnet',             // 'mainnet' | 'devnet' | 'testnet'
  endpoint: 'https://...',        // custom RPC endpoint
  commitment: 'confirmed',        // 'processed' | 'confirmed' | 'finalized'
  timeoutMs: 30000,               // request timeout
  autoValidate: true,             // auto-validate Genesis Hash on connect
  onConnect: ({ endpoint }) => {},
  onDisconnect: ({ error }) => {},
  onNetworkMismatch: ({ expected, actual }) => {},
});

// Network validation
const result = await conn.validateNetwork();
if (!result.valid) {
  console.error('Wrong network!', result);
}

Constants

import {
  QBIT_COIN_TYPE,     // 766
  GENESIS_HASH,       // { mainnet, devnet }
  CHAIN_ENDPOINTS,    // { mainnet, devnet, testnet }
  CHAIN_PROGRAMS,     // System, Token, Stake, Vote, DID, etc.
  CHAIN_PARAMS,       // slot duration, epoch size, token decimals
  LAMPORTS_PER_QBT,   // 1_000_000_000
} from '@quantabit/qbit-chain-sdk';

Error Handling

Structured error hierarchy for precise error recovery:

import {
  QBitError,                    // Base error
  QBitRpcError,                 // RPC communication errors
  QBitNetworkError,             // Connection/timeout errors
  QBitNetworkMismatchError,     // Genesis Hash mismatch
  QBitTransactionError,         // Transaction build/sign/send errors
  QBitInsufficientFundsError,   // Balance too low
  QBitAccountNotFoundError,     // Account does not exist
  QBitTokenError,               // SPL Token errors
  QBitKeypairError,             // Invalid mnemonic/key
  ERROR_CODES,                  // Error code constants
} from '@quantabit/qbit-chain-sdk';

try {
  await transferQBT(conn, myKeypair, 'ReceiverAddress', 100);
} catch (err) {
  if (err instanceof QBitInsufficientFundsError) {
    console.log(`Need ${err.details.required}, have ${err.details.available}`);
  } else if (err instanceof QBitNetworkError) {
    console.log('Network issue, retrying...');
  } else if (err instanceof QBitRpcError) {
    console.log('RPC error:', err.rpcCode, err.method);
  }
}

Real-time Subscriptions

WebSocket-based event streaming:

import { QBitSubscription } from '@quantabit/qbit-chain-sdk';

const sub = new QBitSubscription(conn);

// Watch balance changes
const id1 = sub.onAccountChange('Address...', (info) => {
  console.log('Balance changed:', info.lamports);
});

// Watch program logs (e.g., Token events)
const id2 = sub.onProgramLogs('TokenProgramId', (log) => {
  console.log('Token event:', log.signature);
});

// Watch slot progression
sub.onSlotChange(({ slot }) => console.log('Slot:', slot));

// Track transaction confirmation
sub.onSignature('TxSignature...', (info) => {
  console.log(info.confirmed ? 'Confirmed!' : 'Failed');
});

// Cleanup
sub.unsubscribe(id1);   // cancel specific
sub.unsubscribeAll();    // cancel all
sub.destroy();           // alias for unsubscribeAll

Token Registry

Built-in metadata for known tokens + auto-discovery:

import { TokenRegistry, getTokenRegistry, KNOWN_TOKENS } from '@quantabit/qbit-chain-sdk';

// Static reference
console.log(KNOWN_TOKENS.QBT.decimals);  // 9
console.log(KNOWN_TOKENS.USDC.decimals); // 6

// Registry with chain connection (for auto-discovery)
const registry = getTokenRegistry(conn);

// Built-in tokens
const qbt = registry.getToken('native'); // { symbol: 'QBT', decimals: 9, ... }

// Auto-discover unknown token from chain
const info = await registry.resolveToken('MintAddress...');

// Register custom token
registry.register({
  address: 'CustomMint...',
  symbol: 'MYTOKEN',
  name: 'My Token',
  decimals: 8,
});

// Format amounts
registry.formatWithSymbol('native', 2000000000); // "2.0000 QBT"

// Search
const stables = registry.search('usd'); // [USDC, USDT]

Transaction Parser

Decode on-chain transactions into human-readable events:

import { TransactionParser } from '@quantabit/qbit-chain-sdk';

const parser = new TransactionParser(conn);

// Parse single transaction
const parsed = await parser.parse('TxSignature...');
console.log(parsed.type);     // 'transfer' | 'token_transfer' | 'stake_delegate' | ...
console.log(parsed.summary);  // '转账 1.5 QBT → 8DjJ...DtMc'
console.log(parsed.fee);      // fee in lamports
console.log(parsed.events);   // structured event list
console.log(parsed.programs); // [{ address, name: 'System' }]

// Parse recent transactions for an address
const history = await parser.parseRecentForAddress('Address...', 20);
history.forEach(tx => {
  console.log(`${tx.summary} | ${tx.success ? '✅' : '❌'}`);
});

Program Interaction

DApp developer toolkit for custom program calls:

import { ProgramHelper } from '@quantabit/qbit-chain-sdk';

const helper = new ProgramHelper(conn, 'YourProgramId...');

// Find PDA
const [pda, bump] = helper.findPDA(['user', userPubkey.toBuffer()]);
console.log('PDA:', pda.toBase58(), 'bump:', bump);

// Build instruction
const ix = helper.buildInstruction(
  Buffer.from([1, 0, 0, 0]),  // instruction discriminator
  [
    { pubkey: userPubkey, isSigner: true, isWritable: true },
    { pubkey: pda, isSigner: false, isWritable: true },
  ]
);

// Simulate before sending
const sim = await helper.simulate(signer, [ix]);
console.log('Logs:', sim.logs, 'Error:', sim.err);

// Execute
const sig = await helper.execute(signer, [ix]);

// Query program accounts
const accounts = await helper.getAccounts({ dataSize: 128 });

// Borsh serialization helpers
const data = Buffer.concat([
  ProgramHelper.encodeU32(1),           // instruction index
  ProgramHelper.encodeU64(1000000000n), // amount
  ProgramHelper.encodeString('hello'),  // string field
]);

API Summary

| Module | Exports | |--------|---------| | Connection | QBitConnection, getDefaultConnection, resetDefaultConnection, withRetry | | Keypair | QBitKeypair, generateMnemonic, mnemonicToKeypair, validateMnemonic, verifySignature | | Transaction | QBitTransaction, transferQBT, transferToken, estimateTransactionFee | | Token | createMint, getOrCreateTokenAccount, mintTo, burn, approve, revoke, freezeAccount, thawAccount, setAuthority, closeTokenAccount, getTokenAccountDelegation | | Account | getAccountInfo, getBalance, getTokenAccounts, getTokenMintInfo, getAssociatedTokenAccount, getTransactionHistory, getStakeAccounts | | Stake | createStakeAccount, delegate, deactivate, withdrawStake, getStakeActivation, getValidators | | RPC | getChainHealth, getChainVersion, getBlockHeight, getSlot, getEpochInfo, getLatestBlockhash, getGenesisHash, getSupply, getClusterNodes, getVoteAccounts, getTransactionCount, getBlock, getBlockTime, getBlocks, getRecentPerformanceSamples, getInflationRate, requestAirdrop, validateNetwork, getChainStatus | | Errors | QBitError, QBitRpcError, QBitNetworkError, QBitNetworkMismatchError, QBitTransactionError, QBitInsufficientFundsError, QBitAccountNotFoundError, QBitTokenError, QBitKeypairError, ERROR_CODES | | Subscription | QBitSubscription | | Token Registry | TokenRegistry, getTokenRegistry, KNOWN_TOKENS | | TX Parser | TransactionParser | | Program | ProgramHelper | | Constants | CHAIN_ENDPOINTS, CHAIN_PROGRAMS, CHAIN_PARAMS, GENESIS_HASH, QBIT_COIN_TYPE, LAMPORTS_PER_QBT, DEFAULT_CONFIRM_OPTIONS, TIMEOUT, RETRY | | Utils | qbtToLamports, lamportsToQbt, formatQbt, isValidAddress, shortenAddress, toPublicKey |

License

MIT © QuantaBit Team

🌐 Brand & Links

• Official Mainnet: QuantaBit Chain
• Developer Platform: Developer Platform
• Open Platform: Open Platform
• Payment Platform: Pay Platform
• Feedback: Feedback