nanopay

NanoPay is a Node.js and TypeScript library for the Nano cryptocurrency network. Its README describes two usage modes: a higher-level client for complete workflows and exported functions for step-by-step control. Both share the same Nano cryptography and block builders. Install with npm install nanopay. Version 0.2.0 uses BerryPay's public Nano mainnet RPC when createClient() or createRpcClient() is called without a URL; version 0.1.0 requires an explicit URL. Node.js 22+, ESM, CommonJS, TypeScript, and modern browsers are supported. A browser script bundle exposes NanoPay. Accounts can be created or recovered with createWallet, walletFromSeed, accountFromPrivateKey, and walletFromMnemonic. Native Nano hex seeds use BLAKE2b derivation, while BIP39 mnemonic seeds follow the Nano SLIP-0010 path m/44'/165'/index'. The README warns that users should back up the wallet seed, or the mnemonic and its passphrase, and that a private key controls only one account. Seeds and private keys should be kept out of logs and RPC requests. For sending, receiving, and confirming, createClient returns a client with getBalance, send, waitForConfirmation, receiveAll, and changeRepresentative. The client reads account state, builds a block, signs locally, requests work, verifies it, and submits once. Writes to the same account queue inside a client instance; different accounts and independent reads run concurrently. A status of submitted means the node accepted the block, but waitForConfirmation should be used before treating it as settled. TransactionError retains the exact hash and signed block. ReceiveAllError.completed preserves earlier successful submissions. Writes are not retried automatically, and a submission failure blocks further writes to that account with AccountBlockedError until the failed transaction is reconciled and client.resumeAccount is called. For full control, the library exports generateSeed, derivePrivateKey, derivePublicKey, deriveAddress, buildSendBlock, hashBlock, signHash, attachSignature, getWorkRoot, attachWork, and createRpcClient. The build functions need no private keys. signBlock combines hashing and signing. createSendBlock, createReceiveBlock, and createChangeBlock combine building and signing and return an object with hash and block. These functions do not contact a node. prepareSend, prepareReceive, and prepareChangeRepresentative add ledger reads and return unsigned transactions. External signers implement publicKey and sign(hash). Signatures must use Nano's Ed25519-BLAKE2b, not standard Ed25519-SHA512. Work providers implement work with root, threshold, and signal, and can use local WASM, a GPU service, or a separate work node. Amounts use strings rather than floating-point numbers. nanoToRaw and rawToNano are available, with amount meaning Nano and amountRaw or balanceRaw meaning raw. One Nano is 10^30 raw. Fractional raw and uint128 overflow are rejected. The historical Unit.nano means 10^24 raw, so nanoToRaw should be used for ordinary Nano amounts. Payment links and live confirmations are supported through createPaymentUri, parsePaymentUri, and watchConfirmations. Payment URIs encode raw as required by Nano. WebSocket notifications can repeat, so users should deduplicate by hash. A disconnect, malformed message, or full buffer raises an error. The stream has no automatic reconnect or persistent payment accounting. Focused entry points include nanopay/keys, nanopay/blocks, nanopay/work, nanopay/amounts, nanopay/mnemonic, nanopay/rpc, nanopay/payments, and nanopay/confirmations, each supporting ESM, CommonJS, and TypeScript. The keys entry point contains neither WASM nor the mnemonic word list. The WASM work engine compiles once per realm, isolates concurrent calls, and yields between batches. workerIndex and workerCount partition the nonce space and should be run in separate Workers. Mainnet work is probabilistic; a GPU work service is recommended for sustained workloads. Scope and compatibility: the toolkit covers local accounts, native and mnemonic derivation, state blocks, signing, work, ledger reads, send/receive/change workflows, confirmation tracking, and payment links. client.request and rpc.request expose additional Nano RPC commands supported by the node. It does not run a consensus node, choose a representative, persist or encrypt secrets, manage exchange accounting, or provide a hardware-device transport. New blocks use the state format, while RPC block reads also support historical block contents. Original upstream function names and call signatures are preserved under nanopay/legacy, including deriveSecretKey and the hash-based signBlock. The old nanopay payment-wrapper API is replaced. Development commands include npm ci, npm run check, and npm run bench. Checks cover protocol vectors, workflows, browser and Worker execution, formatting, and installation into a clean npm project. Playwright Chromium can be installed with npx playwright install chromium. npm run build:wasm rebuilds the checked-in binary with LLVM clang and wasm-ld; ordinary builds use the existing binary. NanoPay is GPL-3.0-only and based on nanocurrency-js. Source, build scripts, original notices, and bundled dependency licenses ship with the package.