@knuth/js-wasm 2.11.0 → 3.0.0

package/LICENSE.md

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2016-present Knuth Project developers.
+Copyright (c) 2009-2021 The Bitcoin developers
+Copyright (c) 2009-2017 The Bitcoin Core developers
+
+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

@@ -6,7 +6,7 @@
 [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge)](LICENSE.md)
 <a target="_blank" href="https://t.me/knuth_cash">![Telegram](https://img.shields.io/badge/telegram-chat-blue.svg?logo=telegram&style=for-the-badge)</a>
 
-**Knuth JS-WASM** brings the power of a full Bitcoin Cash node to JavaScript through WebAssembly. Build wallets, validate addresses, create transactions, and more — all running natively in the browser or Node.js.
+**Knuth JS-WASM** provides Bitcoin Cash primitives through WebAssembly. Build wallets, validate addresses and work with transactions in browsers and Node.js. Version 3.0.0 uses KTH 1.5.2 and Emscripten 6.0.13.
 
 ## Installation
 
@@ -16,22 +16,37 @@ npm install @knuth/js-wasm
 
 ## Quick Start
 
-```typescript
-import { PaymentAddress, Wallet, Kth } from '@knuth/js-wasm';
+Load the WebAssembly module before calling native-backed APIs:
 
-// Check library info
-const config = Kth.getLibconfig();
-console.log(`Knuth WASM v${config.wasmLibraryVersion}`);
+```javascript
+const { loadLib, PaymentAddress, Kth } = require('@knuth/js-wasm');
 
-// Validate and convert addresses
-const addr = PaymentAddress.fromString('bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a');
-if (addr) {
-    console.log(`Cash Address: ${addr.encodedCashAddr()}`);
-    console.log(`Legacy: ${addr.encodedLegacy()}`);
-    console.log(`CashTokens: ${addr.encodedCashTokens()}`);
+async function main() {
+    await loadLib(
+        require.resolve('@knuth/js-wasm/src/kth.wasm'),
+        require.resolve('@knuth/js-wasm')
+    );
+    console.log(Kth.getLibconfig().cppapiVersion); // 1.5.2
+
+    const address = PaymentAddress.fromString('bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a');
+    if (address) {
+        console.log(address.encodedLegacy());
+    }
 }
+
+main().catch(console.error);
 ```
 
+The following examples assume `loadLib()` has completed.
+
+## Migrating to 3.0.0
+
+- Use `ScriptFlags` / `ScriptUpgrades` and `bigint` for current script flags; for example, `script.toString(ScriptFlags.noRules)`.
+- Construct wallets with `new Wallet(mnemonic, path, network)` or a seed. Release their native state with `wallet.dispose()`.
+- Token amounts and satoshi values use `bigint`. Invalid token factories can return no native handle.
+- APIs returning native handles transfer ownership as described by their declarations. Release owned handles with `free()` when finished.
+- Recompile TypeScript consumers against the declarations shipped with this version.
+
 ## Features
 
 ### Address Handling
@@ -67,17 +82,18 @@ const mnemonic = ['word1', 'word2', 'word3', '...', 'word12'];
 const derivationPath = "m/44'/145'/0'/0";
 const network = 'MAINNET';
 
-const wallet = Wallet.fromMnemonic(mnemonic, derivationPath, network);
+const wallet = new Wallet(mnemonic, derivationPath, network);
 
 // Get a single address
-const address = await wallet.getAddress(0);
+const address = wallet.getAddress(0);
 console.log(address.encoded()); // bitcoincash:qr9sawzzmstkluq9nqefsu7eqya4zk2w7udune2pmf
 
 // Get multiple addresses
-const addresses = await wallet.getAddresses(5);
+const addresses = wallet.getAddresses(5);
 addresses.forEach((addr, i) => {
     console.log(`[${i}]: ${addr.encoded()}`);
 });
+wallet.dispose();
 ```
 
 ### Transactions
@@ -103,16 +119,16 @@ if (tx) {
 Work with Bitcoin scripts:
 
 ```typescript
-import { Script, hexStrToBytes } from '@knuth/js-wasm';
+import { Script, ScriptFlags, hexStrToBytes } from '@knuth/js-wasm';
 
 // Parse a P2PKH script
 const scriptBytes = hexStrToBytes('76a91406ccef231c2db72526df9338894ccf9355e8f12188ac');
 const script = Script.fromData(scriptBytes, false);
 
 if (script) {
-    console.log(`Type: ${script.type}`);           // pay_public_key_hash
+    console.log(`Type: ${script.pattern()}`);           // pay_public_key_hash
     console.log(`Size: ${script.serializedSize}`); // 25
-    console.log(script.toString(0));               // dup hash160 [...] equalverify checksig
+    console.log(script.toString(ScriptFlags.noRules));               // dup hash160 [...] equalverify checksig
 }
 
 // Create scripts from string
@@ -139,7 +155,7 @@ const hash160 = HashFunctions.hash160(message); // SHA256 + RIPEMD160
 Parse transactions with fungible and non-fungible tokens:
 
 ```typescript
-import { Transaction, hexStrToBytes, encodeHash } from '@knuth/js-wasm';
+import { Transaction, TokenDataFungible, hexStrToBytes, encodeHash } from '@knuth/js-wasm';
 
 const tx = Transaction.fromData(hexStrToBytes(tokenTxHex));
 if (tx && tx.outputs) {
@@ -149,7 +165,7 @@ if (tx && tx.outputs) {
         console.log(`Category: ${encodeHash(output.tokenData.category)}`);
         console.log(`Kind: ${output.tokenData.kind}`); // 'fungible' or 'non_fungible'
 
-        if (output.tokenData.kind === 'fungible') {
+        if (output.tokenData.data instanceof TokenDataFungible) {
             console.log(`Amount: ${output.tokenData.data.amount}`);
         }
     }
@@ -187,21 +203,41 @@ Try it in your browser at [kth.cash](https://kth.cash/#wasm-demo) — no install
 ## Browser Usage
 
 ```html
-<script src="https://unpkg.com/@knuth/js-wasm/src/kth.js"></script>
+<script src="https://unpkg.com/@knuth/js-wasm@3.0.0/src/kth.js"></script>
 <script>
-    // Wait for WASM to load
-    Module.onRuntimeInitialized = () => {
-        const addr = PaymentAddress.fromString('bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a');
-        console.log(addr.encodedLegacy());
-    };
+    const { loadLib, PaymentAddress } = __KTH_MODULE__;
+    loadLib(
+        'https://unpkg.com/@knuth/js-wasm@3.0.0/src/kth.wasm',
+        'https://unpkg.com/@knuth/js-wasm@3.0.0/src/kth.js'
+    ).then(() => {
+        const address = PaymentAddress.fromString('bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a');
+        if (address) console.log(address.encodedLegacy());
+    }).catch(console.error);
 </script>
 ```
 
 ## Requirements
 
-- Node.js 16+ or modern browser with WebAssembly support
+- Node.js 22+ or a modern browser with WebAssembly support
 - ES2020+ (uses BigInt for satoshi values)
 
+## Development and releases
+
+```sh
+yarn install --frozen-lockfile
+npm run tscheck
+npm test
+npm run check:package
+```
+
+CI validates Node.js 22, 24 and 26. Package checks load the packed runtime and compile a TypeScript consumer against its
+declarations. Pull requests and pushes to master run validation only.
+
+To publish a version, update `package.json`, merge the reviewed change with passing CI, then publish a GitHub release
+whose tag is `v<package version>`. The release workflow validates the tagged package before publishing to npm with OIDC
+trusted publishing and provenance. Draft and prerelease releases do not publish to npm. The trusted publisher uses
+the existing `.github/workflows/kth.yml` workflow.
+
 ## Issues
 
 Please report issues in our [main repository](https://github.com/k-nuth/kth/issues).

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@knuth/js-wasm",
-    "version": "2.11.0",
+    "version": "3.0.0",
     "publishConfig": {
         "access": "public"
     },
-    "description": "",
+    "description": "Bitcoin Cash WebAssembly library for browsers and Node.js",
     "main": "src/kth.js",
     "files": [
         "src/kth.js",
@@ -14,7 +14,7 @@
     ],
     "types": "types/wasm/bootloader.d.ts",
     "devDependencies": {
-        "@stylistic/eslint-plugin" : "2.10.1",
+        "@stylistic/eslint-plugin": "2.10.1",
         "@types/file-saver": "^2.0.7",
         "@types/jest": "^29.5.14",
         "@typescript-eslint/eslint-plugin": "^8.14.0",
@@ -29,20 +29,25 @@
         "ts-transformer-keys": "^0.4.4",
         "typescript": "^5.6.3",
         "webpack": "^5.96.1",
-        "webpack-cli": "^5.1.4"
+        "webpack-cli": "^5.1.4",
+        "@types/node": "^22.10.0"
     },
     "scripts": {
-        "test": "jest --runInBand --verbose"
+        "test": "jest --runInBand --verbose",
+        "tscheck": "tsc --project tsconfig.test.json --noEmit",
+        "check:package": "node .github/scripts/check-package.cjs"
     },
     "repository": {
         "type": "git",
         "url": "git+https://github.com/k-nuth/js-wasm.git"
     },
-
     "author": "Knuth Developers",
     "license": "MIT",
     "bugs": {
         "url": "https://github.com/k-nuth/kth/issues"
     },
-    "homepage": "https://github.com/k-nuth"
+    "homepage": "https://github.com/k-nuth",
+    "engines": {
+        "node": ">=22"
+    }
 }