@totemsdk/root-identity 1.0.4 → 1.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Totem SDK Contributors
+
+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

@@ -83,6 +83,6 @@ const wallet = RootIdentityWallet.fromPhrase(userInput);
 
 ## See also
 
-- [`@totemsdk/core`](../core) — `createPerAddressTreeKey` used internally for each child
-- [`@totemsdk/wots-lease`](../wots-lease) — manage signing slot watermarks for each child address
-- [`@totemsdk/statechain`](../statechain) — transfer assets between addresses off-chain
+- [`@totemsdk/core`](https://www.npmjs.com/package/@totemsdk/core) — `createPerAddressTreeKey` used internally for each child
+- [`@totemsdk/wots-lease`](https://www.npmjs.com/package/@totemsdk/wots-lease) — manage signing slot watermarks for each child address
+- [`@totemsdk/statechain`](https://www.npmjs.com/package/@totemsdk/statechain) — transfer assets between addresses off-chain

package/dist/RootIdentityWallet.js

@@ -1,3 +1,4 @@
+"use strict";
 /**
  * RootIdentityWallet — single root identity controlling up to 64 on-chain addresses.
  *
@@ -19,9 +20,11 @@
  * `getRootUses()` / `getChildUses(index)` after each signing operation and
  * restore them via `setRootUses()` / `setChildUses()` on the next session.
  */
-import { sha3_256 } from '@noble/hashes/sha3.js';
-import { createPerAddressTreeKey, serializeTreeSignature, verifySignatureDetailed, scriptFromWotsPk, scriptToAddress, bytesToHex, hexToBytes, phraseToSeed, generateSeedPhrase, validatePhrase, } from '@totemsdk/core';
-export const MAX_CHILD_COUNT = 64;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RootIdentityWallet = exports.MAX_CHILD_COUNT = void 0;
+const sha3_js_1 = require("@noble/hashes/sha3.js");
+const core_1 = require("@totemsdk/core");
+exports.MAX_CHILD_COUNT = 64;
 /**
  * Canonical message prefix for ownership proofs.
  * Bump the version if the message schema ever changes.
@@ -31,11 +34,11 @@ const OWNERSHIP_OP = 'TOTEM_OWNERSHIP_PROOF_V1';
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
 function hashMessage(message) {
-    return sha3_256(new TextEncoder().encode(message));
+    return (0, sha3_js_1.sha3_256)(new TextEncoder().encode(message));
 }
 function addressFromPublicKeyBytes(pkBytes) {
-    const script = scriptFromWotsPk(pkBytes);
-    return scriptToAddress(script);
+    const script = (0, core_1.scriptFromWotsPk)(pkBytes);
+    return (0, core_1.scriptToAddress)(script);
 }
 /**
  * Build the deterministic ownership-proof message that the root key signs.
@@ -57,13 +60,13 @@ function buildOwnershipMessage(rootAddress, childPublicKeys, timestamp) {
 // ─────────────────────────────────────────────────────────────────────────────
 // RootIdentityWallet
 // ─────────────────────────────────────────────────────────────────────────────
-export class RootIdentityWallet {
+class RootIdentityWallet {
     // ── Construction ────────────────────────────────────────────────────────────
     /**
      * @param baseSeed   - 32-byte raw seed (use `RootIdentityWallet.fromPhrase` for mnemonic input)
      * @param childCount - Number of child addresses (1–64, default 64)
      */
-    constructor(baseSeed, childCount = MAX_CHILD_COUNT) {
+    constructor(baseSeed, childCount = exports.MAX_CHILD_COUNT) {
         /** Cached TreeKey instances — created lazily to save memory. */
         this.treeKeyCache = new Map();
         /**
@@ -78,23 +81,23 @@ export class RootIdentityWallet {
         if (baseSeed.length !== 32) {
             throw new Error(`baseSeed must be exactly 32 bytes, got ${baseSeed.length}`);
         }
-        if (childCount < 1 || childCount > MAX_CHILD_COUNT) {
-            throw new Error(`childCount must be 1–${MAX_CHILD_COUNT}, got ${childCount}`);
+        if (childCount < 1 || childCount > exports.MAX_CHILD_COUNT) {
+            throw new Error(`childCount must be 1–${exports.MAX_CHILD_COUNT}, got ${childCount}`);
         }
         this.baseSeed = baseSeed;
         this.childCount = childCount;
     }
     /** Create a wallet from a Minima-compatible BIP39 seed phrase. */
-    static fromPhrase(phrase, childCount = MAX_CHILD_COUNT) {
-        return new RootIdentityWallet(phraseToSeed(phrase), childCount);
+    static fromPhrase(phrase, childCount = exports.MAX_CHILD_COUNT) {
+        return new RootIdentityWallet((0, core_1.phraseToSeed)(phrase), childCount);
     }
     /** Generate a new random Minima-compatible 24-word seed phrase. */
     static generatePhrase() {
-        return generateSeedPhrase();
+        return (0, core_1.generateSeedPhrase)();
     }
     /** Validate a Minima-compatible seed phrase. */
     static validatePhrase(phrase) {
-        return validatePhrase(phrase);
+        return (0, core_1.validatePhrase)(phrase);
     }
     // ── Address accessors ────────────────────────────────────────────────────────
     /** Minima address for the root key (slot 0). */
@@ -145,7 +148,7 @@ export class RootIdentityWallet {
         return {
             address: this.getRootAddress(),
             publicKey: this.getRootPublicKey(),
-            signature: bytesToHex(serializeTreeSignature(sig)),
+            signature: (0, core_1.bytesToHex)((0, core_1.serializeTreeSignature)(sig)),
             message,
         };
     }
@@ -165,7 +168,7 @@ export class RootIdentityWallet {
         return {
             address: this.getChildAddress(index),
             publicKey: this.getChildPublicKey(index),
-            signature: bytesToHex(serializeTreeSignature(sig)),
+            signature: (0, core_1.bytesToHex)((0, core_1.serializeTreeSignature)(sig)),
             message,
         };
     }
@@ -224,11 +227,11 @@ export class RootIdentityWallet {
             const canonicalMessage = buildOwnershipMessage(rootAddress, childPublicKeys, timestamp);
             if (rootProof.message !== canonicalMessage)
                 return false;
-            const sigResult = verifySignatureDetailed(rootAddress, canonicalMessage, rootProof.signature, rootPublicKey);
+            const sigResult = (0, core_1.verifySignatureDetailed)(rootAddress, canonicalMessage, rootProof.signature, rootPublicKey);
             if (!sigResult.valid)
                 return false;
             for (let i = 0; i < childPublicKeys.length; i++) {
-                const pkBytes = hexToBytes(childPublicKeys[i]);
+                const pkBytes = (0, core_1.hexToBytes)(childPublicKeys[i]);
                 const derivedAddress = addressFromPublicKeyBytes(pkBytes);
                 if (derivedAddress.toLowerCase() !== childAddresses[i].toLowerCase())
                     return false;
@@ -344,11 +347,11 @@ export class RootIdentityWallet {
         const cached = this.treeKeyCache.get(slot);
         if (cached)
             return cached;
-        const treeKey = createPerAddressTreeKey(this.baseSeed, slot);
+        const treeKey = (0, core_1.createPerAddressTreeKey)(this.baseSeed, slot);
         this.treeKeyCache.set(slot, treeKey);
         // Cache address and public key while we have the TreeKey
         const pkBytes = treeKey.getPublicKey();
-        const pkHex = bytesToHex(pkBytes);
+        const pkHex = (0, core_1.bytesToHex)(pkBytes);
         this.pubKeyCache.set(slot, pkHex);
         this.addressCache.set(slot, addressFromPublicKeyBytes(pkBytes));
         return treeKey;
@@ -368,3 +371,4 @@ export class RootIdentityWallet {
         return this.addressCache.get(slot);
     }
 }
+exports.RootIdentityWallet = RootIdentityWallet;

package/dist/index.js

@@ -1,3 +1,4 @@
+"use strict";
 /**
  * @module @totemsdk/root-identity
  *
@@ -10,4 +11,8 @@
  *  - Privacy-preserving KYC (selective disclosure)
  *  - NFT / token ownership linking
  */
-export { RootIdentityWallet, MAX_CHILD_COUNT } from './RootIdentityWallet.js';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_CHILD_COUNT = exports.RootIdentityWallet = void 0;
+var RootIdentityWallet_js_1 = require("./RootIdentityWallet.js");
+Object.defineProperty(exports, "RootIdentityWallet", { enumerable: true, get: function () { return RootIdentityWallet_js_1.RootIdentityWallet; } });
+Object.defineProperty(exports, "MAX_CHILD_COUNT", { enumerable: true, get: function () { return RootIdentityWallet_js_1.MAX_CHILD_COUNT; } });

package/dist/types.js

@@ -1,4 +1,5 @@
+"use strict";
 /**
  * Wire types for @totemsdk/root-identity
  */
-export {};
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@totemsdk/root-identity",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Single root identity controlling up to 64 on-chain addresses — all cryptographically linked via full independent 3-level TreeKeys",
-  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -16,10 +15,11 @@
   },
   "files": [
     "dist",
-    "src"
+    "README.md",
+    "LICENSE"
   ],
   "peerDependencies": {
-    "@noble/hashes": ">=1.3.0",
+    "@noble/hashes": "^2.0.0",
     "@totemsdk/core": ">=1.0.1"
   },
   "peerDependenciesMeta": {
@@ -38,27 +38,40 @@
     "access": "public"
   },
   "devDependencies": {
-    "@noble/hashes": "^1.3.0",
+    "@noble/hashes": "^2.2.0",
     "@types/jest": "^29.0.0",
     "@types/node": "^20.0.0",
     "jest": "^29.0.0",
     "ts-jest": "^29.0.0",
     "typescript": "^5.0.0",
-    "@totemsdk/core": "1.0.9"
+    "@totemsdk/core": "1.0.10"
   },
   "keywords": [
     "totem",
+    "totemsdk",
     "minima",
     "blockchain",
+    "quantum-resistant",
     "wots",
+    "kissvm",
+    "utxo",
     "identity",
-    "quantum-resistant",
+    "did",
     "chain-of-custody",
     "dao-attestation",
     "kyc"
   ],
-  "author": "Totem",
+  "author": "Totem SDK",
   "license": "MIT",
+  "homepage": "https://totemsdk.com",
+  "bugs": {
+    "url": "https://github.com/MrGheek/axia-totem/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrGheek/axia-totem.git",
+    "directory": "packages/totem-sdk/packages/root-identity"
+  },
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",

package/src/RootIdentityWallet.ts

@@ -1,435 +0,0 @@
-/**
- * RootIdentityWallet — single root identity controlling up to 64 on-chain addresses.
- *
- * Architecture
- * ────────────
- *  baseSeed (32 bytes)
- *    │
- *    ├── Slot 0  createPerAddressTreeKey(baseSeed, 0)   ← ROOT (signs ownership proofs)
- *    ├── Slot 1  createPerAddressTreeKey(baseSeed, 1)   ← child 0
- *    ├── Slot 2  createPerAddressTreeKey(baseSeed, 2)   ← child 1
- *    │   …
- *    └── Slot 64 createPerAddressTreeKey(baseSeed, 64)  ← child 63
- *
- * Each slot gets a full independent 3-level TreeKey (64³ = 262 144 one-time signatures).
- * Derivation matches Minima Wallet.java exactly:
- *   SHA3-256( MiniData(baseSeed) ∥ MiniData(BigInteger(slot)) )
- *
- * Watermarks are tracked in memory.  Callers that need persistence should read
- * `getRootUses()` / `getChildUses(index)` after each signing operation and
- * restore them via `setRootUses()` / `setChildUses()` on the next session.
- */
-
-import { sha3_256 } from '@noble/hashes/sha3.js';
-import {
-  createPerAddressTreeKey,
-  serializeTreeSignature,
-  verifySignatureDetailed,
-  scriptFromWotsPk,
-  scriptToAddress,
-  bytesToHex,
-  hexToBytes,
-  phraseToSeed,
-  generateSeedPhrase,
-  validatePhrase,
-  type TreeKey,
-} from '@totemsdk/core';
-import type { WotsProof, OwnershipProof } from './types.js';
-
-export const MAX_CHILD_COUNT = 64;
-
-/**
- * Canonical message prefix for ownership proofs.
- * Bump the version if the message schema ever changes.
- */
-const OWNERSHIP_OP = 'TOTEM_OWNERSHIP_PROOF_V1';
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Helpers
-// ─────────────────────────────────────────────────────────────────────────────
-
-function hashMessage(message: string): Uint8Array {
-  return sha3_256(new TextEncoder().encode(message));
-}
-
-function addressFromPublicKeyBytes(pkBytes: Uint8Array): string {
-  const script = scriptFromWotsPk(pkBytes);
-  return scriptToAddress(script);
-}
-
-/**
- * Build the deterministic ownership-proof message that the root key signs.
- *
- * Child public keys are sorted lexicographically before serialization so that
- * the same child set always produces the same canonical message regardless of
- * the order in which indices were passed to `proveOwnership`.
- *
- * Field order is intentional — do not reorder without bumping OWNERSHIP_OP.
- */
-function buildOwnershipMessage(
-  rootAddress: string,
-  childPublicKeys: string[],
-  timestamp: string
-): string {
-  return JSON.stringify({
-    op: OWNERSHIP_OP,
-    rootAddress,
-    childPublicKeys: [...childPublicKeys].sort(),
-    timestamp,
-  });
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// RootIdentityWallet
-// ─────────────────────────────────────────────────────────────────────────────
-
-export class RootIdentityWallet {
-  private readonly baseSeed: Uint8Array;
-  private readonly childCount: number;
-
-  /** Cached TreeKey instances — created lazily to save memory. */
-  private readonly treeKeyCache: Map<number, TreeKey> = new Map();
-
-  /**
-   * Cached addresses and public keys per slot (slot 0 = root, slot i+1 = child i).
-   * Avoids expensive TreeKey regeneration on repeated address lookups.
-   */
-  private readonly addressCache: Map<number, string> = new Map();
-  private readonly pubKeyCache: Map<number, string> = new Map();
-
-  /** Per-slot watermarks. */
-  private rootUses: number = 0;
-  private readonly childUsesMap: Map<number, number> = new Map();
-
-  // ── Construction ────────────────────────────────────────────────────────────
-
-  /**
-   * @param baseSeed   - 32-byte raw seed (use `RootIdentityWallet.fromPhrase` for mnemonic input)
-   * @param childCount - Number of child addresses (1–64, default 64)
-   */
-  constructor(baseSeed: Uint8Array, childCount: number = MAX_CHILD_COUNT) {
-    if (baseSeed.length !== 32) {
-      throw new Error(`baseSeed must be exactly 32 bytes, got ${baseSeed.length}`);
-    }
-    if (childCount < 1 || childCount > MAX_CHILD_COUNT) {
-      throw new Error(`childCount must be 1–${MAX_CHILD_COUNT}, got ${childCount}`);
-    }
-    this.baseSeed = baseSeed;
-    this.childCount = childCount;
-  }
-
-  /** Create a wallet from a Minima-compatible BIP39 seed phrase. */
-  static fromPhrase(phrase: string, childCount: number = MAX_CHILD_COUNT): RootIdentityWallet {
-    return new RootIdentityWallet(phraseToSeed(phrase), childCount);
-  }
-
-  /** Generate a new random Minima-compatible 24-word seed phrase. */
-  static generatePhrase(): string {
-    return generateSeedPhrase();
-  }
-
-  /** Validate a Minima-compatible seed phrase. */
-  static validatePhrase(phrase: string): boolean {
-    return validatePhrase(phrase);
-  }
-
-  // ── Address accessors ────────────────────────────────────────────────────────
-
-  /** Minima address for the root key (slot 0). */
-  getRootAddress(): string {
-    return this.slotAddress(0);
-  }
-
-  /** 64-char hex public key for the root key. */
-  getRootPublicKey(): string {
-    return this.slotPublicKey(0);
-  }
-
-  /** Minima address for child `index` (0-based). */
-  getChildAddress(index: number): string {
-    this.assertChildIndex(index);
-    return this.slotAddress(index + 1);
-  }
-
-  /** 64-char hex public key for child `index`. */
-  getChildPublicKey(index: number): string {
-    this.assertChildIndex(index);
-    return this.slotPublicKey(index + 1);
-  }
-
-  /** All addresses: root first, then all children in order. */
-  getAllAddresses(): string[] {
-    const out: string[] = [this.getRootAddress()];
-    for (let i = 0; i < this.childCount; i++) {
-      out.push(this.getChildAddress(i));
-    }
-    return out;
-  }
-
-  /** Root address and children as a structured object. */
-  getAddressMap(): { root: string; children: string[] } {
-    const children: string[] = [];
-    for (let i = 0; i < this.childCount; i++) {
-      children.push(this.getChildAddress(i));
-    }
-    return { root: this.getRootAddress(), children };
-  }
-
-  // ── Signing ─────────────────────────────────────────────────────────────────
-
-  /**
-   * Sign `message` with the root key.
-   * Hashes the message with SHA3-256 before signing — identical to `verifySignatureDetailed`.
-   * @throws if root TreeKey is exhausted (262 144 uses)
-   */
-  signFromRoot(message: string): WotsProof {
-    const treeKey = this.getOrCreateTreeKey(0);
-    treeKey.setUses(this.rootUses);
-    const sig = treeKey.sign(hashMessage(message));
-    this.rootUses++;
-    return {
-      address: this.getRootAddress(),
-      publicKey: this.getRootPublicKey(),
-      signature: bytesToHex(serializeTreeSignature(sig)),
-      message,
-    };
-  }
-
-  /**
-   * Sign `message` with child key `index` (0-based).
-   * Each child maintains its own independent use counter.
-   * @throws if child TreeKey is exhausted or index out of range
-   */
-  signFromChild(index: number, message: string): WotsProof {
-    this.assertChildIndex(index);
-    const slot = index + 1;
-    const treeKey = this.getOrCreateTreeKey(slot);
-    const uses = this.childUsesMap.get(index) ?? 0;
-    treeKey.setUses(uses);
-    const sig = treeKey.sign(hashMessage(message));
-    this.childUsesMap.set(index, uses + 1);
-    return {
-      address: this.getChildAddress(index),
-      publicKey: this.getChildPublicKey(index),
-      signature: bytesToHex(serializeTreeSignature(sig)),
-      message,
-    };
-  }
-
-  // ── Ownership proofs ─────────────────────────────────────────────────────────
-
-  /**
-   * Produce an ownership proof demonstrating that the root key controls all
-   * given child addresses.
-   *
-   * @param childIndices - Which children to include (0-based, order preserved)
-   */
-  proveOwnership(childIndices: number[]): OwnershipProof {
-    if (childIndices.length === 0) {
-      throw new Error('childIndices must contain at least one index');
-    }
-    const seen = new Set<number>();
-    for (const idx of childIndices) {
-      this.assertChildIndex(idx);
-      if (seen.has(idx)) throw new Error(`Duplicate child index: ${idx}`);
-      seen.add(idx);
-    }
-
-    const timestamp = new Date().toISOString();
-    const childAddresses = childIndices.map(i => this.getChildAddress(i));
-    const childPublicKeys = childIndices.map(i => this.getChildPublicKey(i));
-    const rootAddress = this.getRootAddress();
-    const rootPublicKey = this.getRootPublicKey();
-
-    const message = buildOwnershipMessage(rootAddress, childPublicKeys, timestamp);
-    const rootProof = this.signFromRoot(message);
-
-    return { rootAddress, rootPublicKey, childAddresses, childPublicKeys, rootProof, timestamp };
-  }
-
-  /**
-   * Verify an ownership proof produced by `proveOwnership`.
-   *
-   * Returns `true` only when:
-   * - The canonical message is reconstructed correctly (child keys are sorted).
-   * - The root WOTS signature validates against the root public key and address.
-   * - Every child public key correctly derives the corresponding child address.
-   *
-   * Pure crypto — no network access required.
-   * Always returns `false` (never throws) on malformed or incomplete proof data.
-   */
-  static verifyOwnershipProof(proof: OwnershipProof): boolean {
-    try {
-      if (!proof || typeof proof !== 'object') return false;
-
-      const { rootAddress, rootPublicKey, childAddresses, childPublicKeys, rootProof, timestamp } = proof;
-
-      if (
-        !rootAddress || !rootPublicKey || !timestamp ||
-        !Array.isArray(childAddresses) || !Array.isArray(childPublicKeys) ||
-        !rootProof || typeof rootProof.signature !== 'string'
-      ) {
-        return false;
-      }
-
-      if (childAddresses.length === 0) return false;
-      if (childAddresses.length !== childPublicKeys.length) return false;
-
-      const canonicalMessage = buildOwnershipMessage(rootAddress, childPublicKeys, timestamp);
-      if (rootProof.message !== canonicalMessage) return false;
-
-      const sigResult = verifySignatureDetailed(rootAddress, canonicalMessage, rootProof.signature, rootPublicKey);
-      if (!sigResult.valid) return false;
-
-      for (let i = 0; i < childPublicKeys.length; i++) {
-        const pkBytes = hexToBytes(childPublicKeys[i]);
-        const derivedAddress = addressFromPublicKeyBytes(pkBytes);
-        if (derivedAddress.toLowerCase() !== childAddresses[i].toLowerCase()) return false;
-      }
-
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  // ── TreeKey access (for low-level transaction signing) ───────────────────────
-
-  /**
-   * Get (or create and cache) the TreeKey for child `index` (0-based).
-   *
-   * Callers that need positional watermark control (e.g. `setUses(l1*64+l2)`)
-   * can use this to drive WOTS signing directly — the same path the Totem
-   * extension uses for transaction signing in RootTree mode.
-   *
-   * Note: This does NOT advance the high-level `childUsesMap` counter.
-   * Call `getChildUses` / `setChildUses` yourself if you need to track uses.
-   */
-  getChildTreeKey(index: number): TreeKey {
-    this.assertChildIndex(index);
-    return this.getOrCreateTreeKey(index + 1);
-  }
-
-  /**
-   * Get (or create and cache) the root TreeKey (slot 0).
-   *
-   * Useful for callers that need direct access to the root key's TreeKey
-   * object for custom signing operations.
-   */
-  getRootTreeKey(): TreeKey {
-    return this.getOrCreateTreeKey(0);
-  }
-
-  // ── Watermark access ─────────────────────────────────────────────────────────
-
-  /** Number of times the root key has been used (for persistence). */
-  getRootUses(): number { return this.rootUses; }
-
-  /** Restore root watermark from a previously persisted value. */
-  setRootUses(uses: number): void {
-    if (uses < 0) throw new Error('uses must be non-negative');
-    this.rootUses = uses;
-  }
-
-  /** Number of times child `index` has signed (for persistence). */
-  getChildUses(index: number): number {
-    this.assertChildIndex(index);
-    return this.childUsesMap.get(index) ?? 0;
-  }
-
-  /** Restore child watermark from a previously persisted value. */
-  setChildUses(index: number, uses: number): void {
-    this.assertChildIndex(index);
-    if (uses < 0) throw new Error('uses must be non-negative');
-    this.childUsesMap.set(index, uses);
-  }
-
-  /** Number of child addresses configured for this wallet. */
-  getChildCount(): number { return this.childCount; }
-
-  /** Maximum one-time signatures available per slot (3 levels × 64 keys). */
-  getMaxUsesPerSlot(): number { return 64 * 64 * 64; }
-
-  /**
-   * Return a serialisable snapshot of all current watermark counters.
-   *
-   * Persist the returned object (e.g. to encrypted storage) and pass it back
-   * to `restoreWatermarkState()` at the start of the next session so that no
-   * one-time-use signing slot is ever reused.
-   *
-   * @example
-   * const state = wallet.getWatermarkState();
-   * await storage.set('watermarks', JSON.stringify(state));
-   */
-  getWatermarkState(): { rootUses: number; childUses: Record<number, number> } {
-    const childUses: Record<number, number> = {};
-    for (const [index, uses] of this.childUsesMap) {
-      childUses[index] = uses;
-    }
-    return { rootUses: this.rootUses, childUses };
-  }
-
-  /**
-   * Restore watermark counters from a previously persisted snapshot.
-   *
-   * Call this immediately after constructing the wallet to prevent slot reuse
-   * across sessions.  All values must be non-negative integers; out-of-range
-   * or invalid entries are silently skipped.
-   *
-   * @example
-   * const saved = JSON.parse(await storage.get('watermarks') ?? '{}');
-   * wallet.restoreWatermarkState(saved);
-   */
-  restoreWatermarkState(state: { rootUses?: number; childUses?: Record<number, number> }): void {
-    if (typeof state?.rootUses === 'number' && state.rootUses >= 0) {
-      this.rootUses = Math.floor(state.rootUses);
-    }
-    if (state?.childUses && typeof state.childUses === 'object') {
-      for (const [key, uses] of Object.entries(state.childUses)) {
-        const index = Number(key);
-        if (Number.isInteger(index) && index >= 0 && index < this.childCount && typeof uses === 'number' && uses >= 0) {
-          this.childUsesMap.set(index, Math.floor(uses));
-        }
-      }
-    }
-  }
-
-  // ── Private helpers ──────────────────────────────────────────────────────────
-
-  private assertChildIndex(index: number): void {
-    if (!Number.isInteger(index) || index < 0 || index >= this.childCount) {
-      throw new Error(`Child index ${index} is out of range [0, ${this.childCount - 1}]`);
-    }
-  }
-
-  /**
-   * Get or create the TreeKey for a given slot.
-   * Also populates address and public key caches on first access.
-   */
-  private getOrCreateTreeKey(slot: number): TreeKey {
-    const cached = this.treeKeyCache.get(slot);
-    if (cached) return cached;
-    const treeKey = createPerAddressTreeKey(this.baseSeed, slot);
-    this.treeKeyCache.set(slot, treeKey);
-    // Cache address and public key while we have the TreeKey
-    const pkBytes = treeKey.getPublicKey();
-    const pkHex = bytesToHex(pkBytes);
-    this.pubKeyCache.set(slot, pkHex);
-    this.addressCache.set(slot, addressFromPublicKeyBytes(pkBytes));
-    return treeKey;
-  }
-
-  private slotPublicKey(slot: number): string {
-    const cached = this.pubKeyCache.get(slot);
-    if (cached) return cached;
-    this.getOrCreateTreeKey(slot); // populates both caches
-    return this.pubKeyCache.get(slot)!;
-  }
-
-  private slotAddress(slot: number): string {
-    const cached = this.addressCache.get(slot);
-    if (cached) return cached;
-    this.getOrCreateTreeKey(slot); // populates both caches
-    return this.addressCache.get(slot)!;
-  }
-}

package/src/__tests__/watermark.test.ts

@@ -1,83 +0,0 @@
-/**
- * RootIdentityWallet watermark persistence tests
- *
- * Verifies that getWatermarkState() / restoreWatermarkState() correctly
- * snapshot and restore per-slot counters across simulated sessions.
- */
-
-import { RootIdentityWallet } from '../RootIdentityWallet.js';
-
-const SEED_32 = new Uint8Array(32).fill(0xab);
-
-describe('RootIdentityWallet — getWatermarkState / restoreWatermarkState', () => {
-  it('initial state has rootUses=0 and empty childUses', () => {
-    const wallet = new RootIdentityWallet(SEED_32, 4);
-    const state = wallet.getWatermarkState();
-    expect(state.rootUses).toBe(0);
-    expect(Object.keys(state.childUses)).toHaveLength(0);
-  });
-
-  it('records root uses after signing', () => {
-    const wallet = new RootIdentityWallet(SEED_32, 4);
-    wallet.signFromRoot('hello');
-    wallet.signFromRoot('world');
-    const state = wallet.getWatermarkState();
-    expect(state.rootUses).toBe(2);
-  });
-
-  it('records child uses per index independently', () => {
-    const wallet = new RootIdentityWallet(SEED_32, 4);
-    wallet.signFromChild(0, 'msg-a');
-    wallet.signFromChild(2, 'msg-b');
-    wallet.signFromChild(2, 'msg-c');
-    const state = wallet.getWatermarkState();
-    expect(state.childUses[0]).toBe(1);
-    expect(state.childUses[1]).toBeUndefined();
-    expect(state.childUses[2]).toBe(2);
-    expect(state.childUses[3]).toBeUndefined();
-  });
-
-  it('restores watermarks across session boundary', () => {
-    const wallet1 = new RootIdentityWallet(SEED_32, 4);
-    wallet1.signFromRoot('r1');
-    wallet1.signFromRoot('r2');
-    wallet1.signFromChild(1, 'c1');
-    wallet1.signFromChild(1, 'c2');
-    wallet1.signFromChild(1, 'c3');
-    const snapshot = wallet1.getWatermarkState();
-
-    const wallet2 = new RootIdentityWallet(SEED_32, 4);
-    wallet2.restoreWatermarkState(snapshot);
-
-    expect(wallet2.getRootUses()).toBe(2);
-    expect(wallet2.getChildUses(1)).toBe(3);
-    expect(wallet2.getChildUses(0)).toBe(0);
-  });
-
-  it('restoreWatermarkState ignores out-of-range child indices', () => {
-    const wallet = new RootIdentityWallet(SEED_32, 2);
-    wallet.restoreWatermarkState({ rootUses: 5, childUses: { 0: 3, 99: 7, 1: 1 } });
-    expect(wallet.getRootUses()).toBe(5);
-    expect(wallet.getChildUses(0)).toBe(3);
-    expect(wallet.getChildUses(1)).toBe(1);
-  });
-
-  it('restoreWatermarkState ignores negative values', () => {
-    const wallet = new RootIdentityWallet(SEED_32, 2);
-    wallet.restoreWatermarkState({ rootUses: -1, childUses: { 0: -5 } });
-    expect(wallet.getRootUses()).toBe(0);
-    expect(wallet.getChildUses(0)).toBe(0);
-  });
-
-  it('round-trips through JSON serialization', () => {
-    const wallet1 = new RootIdentityWallet(SEED_32, 4);
-    wallet1.signFromRoot('x');
-    wallet1.signFromChild(3, 'y');
-    const json = JSON.stringify(wallet1.getWatermarkState());
-
-    const wallet2 = new RootIdentityWallet(SEED_32, 4);
-    wallet2.restoreWatermarkState(JSON.parse(json));
-    expect(wallet2.getRootUses()).toBe(1);
-    expect(wallet2.getChildUses(3)).toBe(1);
-  });
-});

package/src/index.ts

@@ -1,15 +0,0 @@
-/**
- * @module @totemsdk/root-identity
- *
- * Single root identity controlling up to 64 on-chain Minima addresses,
- * all cryptographically linked via full independent 3-level WOTS TreeKeys.
- *
- * Use cases:
- *  - Chain-of-custody proofs
- *  - DAO multi-address attestation
- *  - Privacy-preserving KYC (selective disclosure)
- *  - NFT / token ownership linking
- */
-
-export { RootIdentityWallet, MAX_CHILD_COUNT } from './RootIdentityWallet.js';
-export type { WotsProof, OwnershipProof } from './types.js';

package/src/types.ts

@@ -1,39 +0,0 @@
-/**
- * Wire types for @totemsdk/root-identity
- */
-
-/**
- * A single WOTS signing proof tied to an on-chain address.
- *
- * Both `signature` and `publicKey` are lower-case hex strings (no 0x prefix).
- * `message` is the exact UTF-8 string that was signed so callers can
- * reconstruct the SHA3-256 digest independently.
- */
-export interface WotsProof {
-  address: string;
-  publicKey: string;
-  signature: string;
-  message: string;
-}
-
-/**
- * Ownership proof demonstrating that a root key controls a set of child addresses.
- *
- * The root key signs a canonical JSON message that includes all child public keys
- * and a timestamp, allowing third parties to verify the claim without any
- * interaction with the blockchain.
- *
- * Verification steps:
- * 1. Rebuild the canonical message from `rootAddress`, `childPublicKeys`, and `timestamp`.
- * 2. Verify `rootProof.signature` over that message with `rootProof.publicKey`.
- * 3. For each `(childPublicKeys[i], childAddresses[i])` pair confirm the address
- *    is correctly derived from the public key.
- */
-export interface OwnershipProof {
-  rootAddress: string;
-  rootPublicKey: string;
-  childAddresses: string[];
-  childPublicKeys: string[];
-  rootProof: WotsProof;
-  timestamp: string;
-}