{"id":29068889,"url":"https://github.com/aspectron/kaspa-wallet-worker","last_synced_at":"2025-10-04T05:05:50.000Z","repository":{"id":74497207,"uuid":"331193255","full_name":"aspectron/kaspa-wallet-worker","owner":"aspectron","description":"Kaspa Wallet Web Worker (allows Kaspa Wallet to run inside of a NodeJs or Browser web worker)","archived":false,"fork":false,"pushed_at":"2025-04-23T09:21:17.000Z","size":77,"stargazers_count":0,"open_issues_count":0,"forks_count":4,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-07-06T22:05:04.085Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aspectron.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-01-20T04:34:17.000Z","updated_at":"2025-04-23T09:21:21.000Z","dependencies_parsed_at":"2025-06-27T11:09:37.224Z","dependency_job_id":"ec286c34-cdee-473d-8ae7-079649cfdc64","html_url":"https://github.com/aspectron/kaspa-wallet-worker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aspectron/kaspa-wallet-worker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aspectron%2Fkaspa-wallet-worker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aspectron%2Fkaspa-wallet-worker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aspectron%2Fkaspa-wallet-worker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aspectron%2Fkaspa-wallet-worker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aspectron","download_url":"https://codeload.github.com/aspectron/kaspa-wallet-worker/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aspectron%2Fkaspa-wallet-worker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278266896,"owners_count":25958733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-27T11:09:34.322Z","updated_at":"2025-10-04T05:05:49.975Z","avatar_url":"https://github.com/aspectron.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Kaspa Wallet Worker\r\n======================\r\n\r\nKaspa Wallet implements Wallet functionality for the [Kaspa Network](https://github.com/kaspanet/kaspad)\r\n\r\nKaspa Wallet is implemented in TypeScript and can be used server-side (NodeJs) and client-side (browser)\r\n\r\n**PLEASE NOTE: This project is under heavy development**\r\n\r\nComponents\r\n----------\r\n\r\nKaspa Wallet uses the following modules:\r\n\r\n  * [kaspa-grpc](https://github.com/aspectron/kaspa-grpc) - provides gRPC bindings for `kaspad`\r\n  * [kaspa-grpc-node](https://github.com/aspectron/kaspa-grph-node) - gRPC transport for server-side (NodeJs)\r\n  * [kaspa-grpc-web](https://github.com/aspectron/kaspa-grpc-web) - gRPC transport for client-side (browsers)\r\n  * [kaspacore-lib](https://github.com/aspectron/kaspacore-lib) - Kaspa UTXO and transaction data structures\r\n\r\nApplications built on top of Kaspa Wallet Framework:\r\n\r\n  * [kaspa-faucet](https://github.com/aspectron/kaspa-faucet) - Kaspa faucet website\r\n  * [kaspa-wallet-cli](https://github.com/aspectron/kaspa-wallet-cli) - command-line wallet\r\n  * [KDX](https://github.com/aspectron/kdx) - Kaspa desktop wallet\r\n\r\n**PLEASE NOTE:** all Kaspa applications and libraries are under heavy development\r\n\r\nKaspa Wallet Framework\r\n----------------------\r\n\r\nBefore you can use Kaspa Wallet, you need to initialize the framework. Framework initialization loads various dependencies such as `secp256k1-wasm` and `blake2b-wasm` modules use in the underlying transaction cryptography.\r\n\r\n```js\r\nconst { Wallet, initKaspaFramework } = require('@kaspa/wallet');\r\nconst { RPC } = require('@kaspa/grpc-node');\r\n\r\n(async () =\u003e { \r\n  await initKaspaFramework();\r\n  ...\r\n})();\r\n```\r\n\r\nCreating a wallet\r\n-----------------\r\n\r\nNetwork types are identified by address prefixes:\r\n  * `kaspa` (Mainnet)\r\n  * `kaspatest` (Testnet)\r\n  * `kaspadev` (Devnet)\r\n  * `kaspasim` (Simnet)\r\n\r\nWallet class can be created using two static functions:\r\n```ts\r\nstatic fromMnemonic(\r\n  seedPhrase: string, \r\n  networkOptions: NetworkOptions, \r\n  options: WalletOptions = {}): Wallet { }\r\n\r\nstatic async import(\r\n  password: string, \r\n  encryptedMnemonic: string, \r\n  networkOptions: NetworkOptions, \r\n  options: WalletOptions = {}): Promise \u003cWallet\u003e { }\r\n```\r\n\r\nWallet creation functions accept following configuration objects:\r\n\r\n```ts\r\nexport interface WalletOptions{\r\n  skipSyncBalance?:boolean;           // do not perform balance sync\r\n  addressDiscoveryExtent?:number;     // address derivation scan (default 128)\r\n  syncOnce?:boolean;                  // 'sync-and-exit' (true) or 'monitoring' mode\r\n  logLevel?:string;                   // wallet log level\r\n  disableAddressDerivation?:boolean;  // disable address derivation and discovery\r\n}\r\n\r\nexport interface NetworkOptions{\r\n  network:Network;                    // network: kaspa, kaspatest, kaspadev, kaspasim\r\n  rpc?:IRPC;                          // gRPC interface (must be bound to transport before use)\r\n}\r\n```\r\n\r\nFollowing options are important:\r\n- `addressDiscoveryExtent` - the number of HD address derivations to scan forward from the last known used address\r\n- `syncOnce` - allows wallet to be started temporarily, without starting monitoring services\r\n- `disableAddressDerivation` - starts wallet in a single-address mode, where receive address and change address will always be the first receive address generated from the private key.\r\n\r\nCreating from Mnemonic:\r\n```js\r\nconst network = \"kaspatest\";\r\nconst { port } = Wallet.networkTypes[kaspatest].port; // default port for testnet\r\nconst rpc = new RPC({ clientConfig:{ host : '127.0.0.1:'+port } });\r\n\r\nWallet.fromMnemonic(\r\n    \"user mnemonic string\",\r\n    { network, rpc },\r\n    {disableAddressDerivation:true}\r\n);\r\n```\r\n\r\nCreating new wallet instance with dynamically generated mnemonic:\r\n```js\r\nconst wallet = new Wallet(null, null, {network, rpc});\r\nconst encryptedMnemonic = await wallet.export(cmd.password);\r\nconsole.log('mnemonic:',wallet.mnemonic);\r\nconsole.log('encrypted mnemonic:',encryptedMnemonic);\r\n```\r\n\r\nRestoring from encrypted mnemonic:\r\n```js\r\nconst password = \"user password\";\r\nconst encryptedMnemonic = \"previously encrypted mnemonic\";\r\nlet wallet = await Wallet.import(password, encryptedMnemonic, { network, rpc })\r\n```\r\n\r\nLogging and debugging\r\n---------------------\r\n\r\nWallet class contains an integrated logger that can be set to one of the following levels: `error`, `warn`, `info`, `verbose`, `debug`.\r\nThe default log level is `info`.  You can set the log level to `verbose` to see internal wallet data processing activity.\r\n\r\nWallet log level can be supplied as a part of `WalletOptions` (describe above) or set at runtime as follows:\r\n```js\r\nwallet.setLogLevel('verbose');\r\n```\r\n\r\nSynchronizing a wallet\r\n------------------------\r\n\r\nThe function `Wallet::sync(once?:boolean)` can be used to perform wallet synchronization. Wallet synchronization\r\nwill connect to `kaspad` and scan available UTXO entries for wallet addresses, update the wallet\r\nbalance and if `once` is true, exit or if `once` is false, start wallet monitoring services.\r\n\r\nWhen operating with monitoring enabled, wallet will retain connection to `kaspad` and dynamically\r\nupdate wallet UTXO entries as well as balances.\r\n\r\n- `wallet.sync()` - starts the wallet in monitoring mode\r\n- `wallet.sync(true)` - performs a single-time synchronization\r\n\r\nSending transactions\r\n--------------------\r\n\r\n`submitTransaction()` function can be used to create transactions on the Kaspa network:\r\n```js\r\nasync submitTransaction(txParamsArg: TxSend): Promise \u003c TxResp | null \u003e {\r\n  // ...\r\n}\r\n```\r\nThis function accepts `TxSend` object on input and returns a `Promise\u003cTxResp\u003e` object:\r\n\r\n```ts\r\nexport interface TxSend {\r\n  toAddr: string;\r\n  amount: number;\r\n  fee: number;\r\n  changeAddrOverride? : string;\r\n  networkFeeMax?:number;\r\n}\r\n```\r\n- `toAddr` - Destination address\r\n- `amount` - Amount of KAS in base units\r\n- `fee` - Transaction priority fee\r\n- `changeAddrOverride` - (optional) Allows you to supply your own address for the change transaction\r\n- `networkFeeMax` - (optional) Allows you to set an upper bound for automatic network (data storage) fee calculation.  Kaspa Wallet will automatically calculate appropriate fees and add them to the transaction based on the transaction size. This feature is disabled if the property is omitted or set to zero.\r\n\r\n\r\n```ts\r\nexport interface TxResp {\r\n  txid: string;\r\n  rpctx?: string; // reserved\r\n}\r\n```\r\n- `txid` - Generated transaction id\r\n\r\n```js\r\ntry {\r\n  let response = await this.wallet.submitTransaction({\r\n      address, // destination address\r\n      amount,  // amount in base units\r\n      fee,     // user fees\r\n  });\r\n  if(!response)\r\n    console.log('general error');  // if kaspad returns null (should never occur)\r\n  else\r\n    console.log('success:', txid);\r\n} catch(ex) {\r\n  console.log('error:',ex.toString());\r\n}\r\n\r\n```\r\n\r\nOn failure, `submitTransaction()` rejects with and error indicating the reason for failure.\r\n\r\nWallet balance\r\n--------------\r\n\r\nWallet retains 2 types of balances:\r\n- *available* - balance contains KAS ready to be spent, comprised of UTXO records with block maturity blue score over 100.\r\n- *pending* - balance contains newly received transactions with UTXO block maturity less than 100.  Upon each UTXO maturity balance is relocated from pending to available.\r\n\r\n`Wallet::balance` is an object containing the following properties that are updated during wallet operation:\r\n```js\r\nwallet.balance = {\r\n  available: 5150000000000,\r\n  pending: 247500000000,\r\n  total: 5397500000000\r\n}\r\n```\r\n\r\nWallet events\r\n-------------\r\n\r\n`Wallet::on(subject, (data) =\u003e { ... })` allows for event handler registration.\r\nSimilarly to NodeJs `EventEmitter` you can unregister events by supplying original \r\ncallback to `Wallet::removeEventListener(subject, handler)` as follows:\r\n\r\n```js\r\nconst balanceHandler = (balance)=\u003e{ console.log(balance); }\r\nwallet.on('balance-update', balanceHandler);\r\nwallet.removeEventListener('balance-update', balanceHandler);\r\n```\r\n\r\nFollowing events are emitted by the Wallet class:\r\n\r\n- `api-online` - gPRC API is online\r\n- `api-offline` - gRPC API is offline\r\n- `sync-start` - wallet sync started (occurs each time gRPC API connects or re-connects)\r\n- `sync-finish` - wallet sync finished\r\n- `ready` - wallet is ready for use (sent after sync-finish, event data contains the balance object)\r\n- `blue-score-changed` - indicates Kaspa blue score change (new block generation)\r\n- `utxo-change` - signaled when UTXO is added or removed from the wallet UTXO set\r\n- `balance-update` - indicates wallet balance change (event data contains the balance object)\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faspectron%2Fkaspa-wallet-worker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faspectron%2Fkaspa-wallet-worker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faspectron%2Fkaspa-wallet-worker/lists"}