Lumina Blockchain JavaScript SDK 💎

The official JavaScript/TypeScript SDK for the Lumina Blockchain. Build powerful dApps, automated bots, and manage high-performance wallets with ease.

Features 🚀

• HD Wallet Support: Standard bip39 mnemonic with SLIP-0010 derivation.
• Gasless Transactions: Native Fee Payer support for sponsored transactions.
• Developer Utilities: Precision handling for LUM units (18 decimals).
• Fast & Lightweight: Built on top of noble-hashes and tweetnacl.

Installation 📦

npm install lumina-blockchain-sdk

Quick Start ⚡

Initialize Wallet

import { LuminaWallet, LuminaUtils } from 'lumina-blockchain-sdk';

// From Mnemonic (HD Wallet)
const mnemonic = "abandon abandon abandon ...";
const wallet = LuminaWallet.fromMnemonic(mnemonic, 0); // Account index 0

console.log("Address:", wallet.getAddress());

Sending a Simple Transaction

import { LuminaClient, LuminaWallet } from 'lumina-blockchain-sdk';

const client = new LuminaClient('https://mainnet.lumina.org');
const wallet = new LuminaWallet('YOUR_PRIVATE_KEY');

const result = await client.sendTransaction(
  wallet,
  'lumina1receiver...',
  '1.5' // Sending 1.5 LUM
);

console.log("TX Hash:", result.hash);

Gasless Transaction (Sponsored) 🛡️

Lumina allows a third-party wallet to pay for transaction fees.

// 1. User signs the intent
const tx = userWallet.signTransaction(
  receiverAddr, 
  "10.0", 
  nonce, 
  [], 
  sponsorWallet.getAddress() // Tell the node who is paying
);

// 2. Sponsor signs as Fee Payer
const finalizedTx = sponsorWallet.signAsFeePayer(tx);

// 3. Submit to network
const result = await client.sendTransaction(finalizedTx);

Utilities & Unit Conversion 🛠️

import { LuminaUtils } from 'lumina-blockchain-sdk';

// LUM to Smallest Units (Lumlets)
const units = LuminaUtils.toUnits("1.25"); // Returns BigInt 1250000000000000000n

// Units to LUM String
const lumStr = LuminaUtils.toLumina(units); // "1.25"

// Formatting Address
const displayAddr = LuminaUtils.formatAddress("lumina1rfdmv92qtyr843q8mz50cgz84kxrkgndgjyl4k");
// Result: lumina1rfdmv92...yl4k

API Reference 📚

LuminaWallet

• static fromMnemonic(mnemonic, index = 0)
• static createRandom()
• getAddress()
• signTransaction(to, amount, nonce, data, feePayer)
• signAsFeePayer(signedTx)

LuminaUtils

• toUnits(lumAmount)
• toLumina(unitAmount)
• isValidAddress(address)
• formatAddress(address, chars = 4)

LuminaClient

• getBalance(address) - Mengambil saldo dan nonce akun.
• getTransaction(hash) - Mengambil detail transaksi berdasarkan hash.
• sendTransaction(signedTx) - Mengirimkan transaksi yang telah ditandatangani ke jaringan.
• estimateFee(data) - Mendapatkan estimasi biaya (fee) berdasarkan ukuran payload data.
• Kueri Blok & Explorer:
  • getLatestBlock() - Mendapatkan blok terbaru.
  • getRecentBlocks() - Mendapatkan daftar blok-blok terbaru.
  • getRecentTxs() - Mendapatkan transaksi-transaksi terbaru.
  • getBlocks(limit, offset) - Mendapatkan daftar blok terpaginasi.
  • getBlock(height) - Mendapatkan detail blok berdasarkan nomor tinggi blok.
  • getBlockEvents(height) - Mendapatkan daftar log event pada blok tertentu.
• Kueri Akun & Mempool:
  • getTopAccounts() - Mendapatkan daftar akun dengan saldo teratas.
  • getAllTransactions() - Mendapatkan semua transaksi.
  • getMempoolByAddress(address) - Mendapatkan transaksi pending di mempool untuk alamat tertentu.
  • getRecentMempool() - Mendapatkan daftar transaksi terbaru di mempool.
  • getTransactionsByAddress(address, page, limit) - Mendapatkan histori transaksi suatu alamat.
  • getInternalTxsByAddress(address, page, limit) - Mendapatkan histori transaksi internal smart contract suatu alamat.
  • getTokens(address) - Mendapatkan token-token yang dimiliki suatu alamat.
• Kueri Smart Contract:
  • getContractMetadata(address) - Mendapatkan metadata lengkap (ABI, nama, dll) smart contract.
  • getContractStorage(address) - Mendapatkan seluruh penyimpanan (storage) smart contract.
  • getContractEvents(address, limit) - Mendapatkan event log yang dipancarkan oleh smart contract.
  • getContractCall(address, method, args) - Melakukan view-call (read-only) ke smart contract secara lokal tanpa mengirim transaksi.
  • getContractBytecode(address) - Mendapatkan bytecode WASM dari smart contract.
• Kueri Node & Database:
  • getNetworkStats() - Mendapatkan statistik jaringan (tinggi blok terbaru, jumlah transaksi, TPS, dll).
  • getNetworkPeers() - Mendapatkan daftar node peer yang terhubung.
  • globalSearch(query) - Melakukan pencarian global (blok, transaksi, atau alamat).
  • getDbTrees() - Mendapatkan daftar tree RocksDB node.
  • getDbKeys(tree) - Mendapatkan daftar key dalam tree database tertentu.
  • getDbGet(tree, key) - Mendapatkan nilai dari key tertentu dalam database.
  • getHealth() - Memeriksa status kesehatan node.

LuminaWsClient (Real-time WebSocket Pub/Sub) 📡

Kelas baru untuk melakukan langganan data real-time berbasis JSON-RPC 2.0 WebSockets. Sangat berguna untuk bot, dApp, explorer, dan notifikasi instan.

import { LuminaWsClient } from 'lumina-blockchain-sdk';

const wsClient = new LuminaWsClient('ws://127.0.0.1:9098');

// 1. Langganan blok baru (newHeads)
const subHeads = await wsClient.subscribeNewHeads((block) => {
  console.log("Blok baru terbentuk! Tinggi:", block.height, "Hash:", block.block_hash);
});

// 2. Langganan transaksi mempool baru (pendingTransactions)
const subPending = await wsClient.subscribePendingTransactions((txHash) => {
  console.log("Transaksi pending masuk mempool:", txHash);
});

// 3. Langganan transaksi untuk alamat tertentu (addressTransactions)
const subAddr = await wsClient.subscribeAddressTransactions("lumina1address...", (tx) => {
  console.log("Aktivitas transaksi alamat terdeteksi:", tx);
});

// 4. Langganan event log dari contract (logs)
const subLogs = await wsClient.subscribeLogs({ address: "lumina1contract..." }, (log) => {
  console.log("Log smart contract baru:", log);
});

// Membersihkan / berhenti berlangganan
await wsClient.unsubscribe(subHeads);

// Menutup koneksi WebSocket
wsClient.close();

Security 🔐

This SDK uses Ed25519 for signatures and BLAKE3 for hashing, ensuring the highest level of security and performance.

Built with ❤️ for the Lumina Ecosystem.