@quantabit/qbit-chain-sdk 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuantaBit Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,476 @@
+# @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
+
+```bash
+npm install @quantabit/qbit-chain-sdk
+```
+
+## Quick Start
+
+```javascript
+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...` |
+
+```javascript
+// 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
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+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).
+
+```javascript
+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
+
+```javascript
+const tx = new QBitTransaction(conn);
+tx.addInstruction(someInstruction);
+tx.addSigner(extraKeypair);          // additional required signer
+await tx.sendAndConfirm(payer, { feePayer: payer.address });
+```
+
+## Staking
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+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
+
+```javascript
+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:
+
+```javascript
+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:
+
+```javascript
+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:
+
+```javascript
+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:
+
+```javascript
+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:
+
+```javascript
+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](https://qbitchain.io/)
+- Developer Platform: [Developer Platform](https://developer.quantabit.io/)
+- Open Platform: [Open Platform](https://open.quantabit.io/)
+- Payment Platform: [Pay Platform](https://pay.qbitwallet.io/)
+- Feedback: [Feedback](https://xwin.live/qbit)