@totemsdk/core 1.0.6 → 1.0.8

package/README.md

@@ -0,0 +1,90 @@
+# @totemsdk/core
+
+**The cryptographic engine — every other package depends on this.**
+
+Zero production dependencies (only `@noble/hashes` as a peer). Provides quantum-resistant WOTS signatures, hierarchical TreeKey address derivation, BIP39 seed phrases, Merkle Mountain Range proofs, and byte-exact Minima Java-compatible transaction serialization.
+
+## Install
+
+```bash
+npm install @totemsdk/core @noble/hashes
+```
+
+## What's inside
+
+| Module | What it does |
+|--------|-------------|
+| **WOTS** | `wotsKeypairFromSeed`, `wotsSign`, `wotsVerify`, `wotsPkFromSig` — quantum-resistant Winternitz One-Time Signatures |
+| **TreeKey** | `createPerAddressTreeKey`, `verifyTreeSignature` — 3-level hierarchical signing trees; one seed → many signing addresses |
+| **BIP39** | `generateSeedPhrase`, `validatePhrase`, `phraseToSeed` — 24-word mnemonic generation and recovery |
+| **MMR** | Full Merkle Mountain Range proof construction and verification for Minima's UTXO set |
+| **Serialization** | `serializeCoin`, `serializeTransaction`, `computeTransactionDigest`, `buildMinimaCoin` — byte-identical to the Minima Java node |
+| **Verification** | `verifySignatureDetailed`, `verifyTreeSignatureDetailed` — server-side auth helpers |
+| **Lease/Watermark** | `LeaseStore`, `WatermarkStore`, `LeaseMonitor` — WOTS key-use accounting to prevent catastrophic key reuse |
+| **TransactionService** | High-level prepare → sign → finalize lifecycle with receipt tracking |
+| **MINIMA_CONSTANTS** | Canonical chain parameters (`WOTS_W=8`, `MAX_SIGNATURES=262144`, `ADDRESS_PREFIX="Mx"`) |
+
+## Usage
+
+### WOTS keypair and signing
+
+```typescript
+import { wotsKeypairFromSeed, wotsSign, wotsVerify } from '@totemsdk/core';
+
+const seed = crypto.getRandomValues(new Uint8Array(32));
+const keypair = wotsKeypairFromSeed(seed, 0);
+
+// Sign — each (seed, index) pair is one-time use
+const signature = wotsSign(seed, 0, message);
+
+// Verify
+const ok = wotsVerify(signature, message, keypair.pk);
+```
+
+### Per-address TreeKey (matches Minima Wallet.java)
+
+```typescript
+import { createPerAddressTreeKey } from '@totemsdk/core';
+
+// One independent 3-level tree per address index (0–63)
+const treeKey = createPerAddressTreeKey(baseSeed, 0);
+
+// Convert watermark (l1, l2) to a flat counter
+const uses = l1 * 64 + l2;
+treeKey.setUses(uses);
+const { signature, publicKey, proofs } = treeKey.sign(data);
+```
+
+### Address derivation and verification
+
+```typescript
+import { scriptToAddress, publicKeyToScript, verifySignature } from '@totemsdk/core';
+
+const script   = publicKeyToScript(publicKeyHex);
+const address  = scriptToAddress(script); // "Mx..."
+
+const ok = verifySignature(address, message, signatureHex, publicKeyHex);
+```
+
+### Replay-safe challenge/response
+
+```typescript
+import { createChallenge, validateChallenge } from '@totemsdk/core';
+
+// Server: create a challenge
+const challenge = createChallenge('my-dapp.example.com');
+
+// Server: validate before accepting a signature
+const { valid, error } = validateChallenge(challenge, {
+  maxAgeMs: 5 * 60 * 1000,
+  expectedDomain: 'my-dapp.example.com',
+});
+```
+
+## See also
+
+- [`@totemsdk/connect`](../connect) — dApp gateway built on top of core
+- [`@totemsdk/node`](../node) — core wired for Node.js server-side use
+- [`@totemsdk/wots-lease`](../wots-lease) — cloud-coordinated WOTS key safety
+- [`@totemsdk/tx-builder`](../tx-builder) — full transaction construction
+- [`@totemsdk/root-identity`](../root-identity) — multi-address identity from one seed

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { LeaseStore, WatermarkStore, LeaseMonitor, prepareLease, finalizeLease,
 export { TransactionService, TransactionLifecycle, TransactionLifecycleError, WatermarkExhaustedError, TransactionReceiptStore, type TransactionServiceConfig, type WotsSigningDependencies, type TransactionLifecycleConfig, type WatermarkSyncFunction, type PrepareResult, type TransactionReceiptStoreConfig, type PrepareRequest, type PrepareResponse, type SignRequest, type SignResult, type HierarchicalWitnessBundle, type WitnessBundle, type FinalizeRequest, type FinalizeResponse, type TransactionMetadata, type TransactionReceipt, type TransactionError, } from './tx/index.js';
 export type { WotsIndices } from './tx/index.js';
 export * from './utils.js';
-export { F, hex, fromHex, u16be, u32be, assert32, h, prfChainSeed, toWinternitzDigits, baseWWithChecksum, derivePKdigest, wotsKeypairFromSeed, wotsSign, wotsSignLegacy, wotsPkFromSig, wotsVerify, wotsPublicKeyFromSeed, type WotsKeypair, type WotsSignature, } from './wots.js';
+export { F, hex, fromHex, u16be, u32be, assert32, h, prfChainSeed, toWinternitzDigits, baseWWithChecksum, derivePKdigest, wotsKeypairFromSeed, wotsSign, wotsSignLegacy, wotsPkFromSig, wotsVerify, wotsVerifyDigest, wotsPublicKeyFromSeed, type WotsKeypair, type WotsSignature, } from './wots.js';
 export * from './params.js';
 export { serializeMiniNumber, serializeMiniData, hashAllObjects, deriveChainSeedJava, deriveChildTreeSeedJava, hashObject, serializeMiniNumberZERO, serializeMiniNumberONE, writeHashToStream, javaHashAllObjects, indexToMiniDataBytes, derivePerAddressSeed, createMMREntryNumber, serializeMMREntryNumber, serializeMMRData, serializeMMREntry, precomputeTransactionCoinID, type MMREntryNumber as JavaMMREntryNumber, type MMRData as JavaMMRData, type MMREntry as JavaMMREntry, } from './javaStreamables.js';
 export { TreeKey, type KeyGenProgress, type ProgressCallback, TreeKeyNode, verifyTreeSignature, serializeTreeSignature, deserializeTreeSignature, getRootPublicKey, DEFAULT_KEYS_PER_LEVEL, DEFAULT_LEVELS, type SignatureProof, type TreeSignature, createPerAddressTreeKey, createPerAddressTreeKeyAsync, deriveAddressPublicKey, getPerAddressPublicKey, } from './treekey.js';

package/dist/index.js

@@ -13,7 +13,7 @@ export { TransactionService, TransactionLifecycle, TransactionLifecycleError, Wa
 // Utilities first (canonical concatBytes source)
 export * from './utils.js';
 // WOTS Signatures - wots.concatBytes is intentionally shadowed by utils.concatBytes above
-export { F, hex, fromHex, u16be, u32be, assert32, h, prfChainSeed, toWinternitzDigits, baseWWithChecksum, derivePKdigest, wotsKeypairFromSeed, wotsSign, wotsSignLegacy, wotsPkFromSig, wotsVerify, wotsPublicKeyFromSeed, } from './wots.js';
+export { F, hex, fromHex, u16be, u32be, assert32, h, prfChainSeed, toWinternitzDigits, baseWWithChecksum, derivePKdigest, wotsKeypairFromSeed, wotsSign, wotsSignLegacy, wotsPkFromSig, wotsVerify, wotsVerifyDigest, wotsPublicKeyFromSeed, } from './wots.js';
 // WOTS Params (from params.ts, imported by wots.ts)
 export * from './params.js';
 // Java-Compatible Serialization Helpers (for Minima-compatible seed derivation)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totemsdk/core",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Core cryptographic primitives for Totem SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -28,12 +28,6 @@
     },
     "./test-vectors.json": "./test-vectors.json"
   },
-  "scripts": {
-    "build": "tsc",
-    "clean": "rm -rf dist",
-    "test": "jest --passWithNoTests",
-    "gen:pkdigest": "node scripts/gen_wots_pkdigest_vectors.cjs"
-  },
   "files": [
     "dist",
     "src",
@@ -62,5 +56,11 @@
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "jest --passWithNoTests",
+    "gen:pkdigest": "node scripts/gen_wots_pkdigest_vectors.cjs"
+  }
+}

package/src/index.ts

@@ -81,6 +81,7 @@ export {
   wotsSignLegacy,
   wotsPkFromSig,
   wotsVerify,
+  wotsVerifyDigest,
   wotsPublicKeyFromSeed,
   type WotsKeypair,
   type WotsSignature,