@totemsdk/root-identity 1.0.6 → 1.0.8

package/dist/RootIdentityWallet.d.ts

@@ -1,164 +1,10 @@
 /**
- * RootIdentityWallet — single root identity controlling up to 64 on-chain addresses.
+ * RootIdentityWallet — backward-compatibility re-export.
  *
- * 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
+ * The implementation has moved to UnifiedIdentityWallet which uses genuine
+ * hierarchical key derivation (root_priv_seed → child_seed_i).
  *
- * 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.
+ * All existing call sites should be updated to import UnifiedIdentityWallet
+ * directly. This shim is kept only to avoid hard import errors during migration.
  */
-import { type TreeKey } from '@totemsdk/core';
-import type { WotsProof, OwnershipProof } from './types.js';
-export declare const MAX_CHILD_COUNT = 64;
-export declare class RootIdentityWallet {
-    private readonly baseSeed;
-    private readonly childCount;
-    /** Cached TreeKey instances — created lazily to save memory. */
-    private readonly treeKeyCache;
-    /**
-     * 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;
-    private readonly pubKeyCache;
-    /** Per-slot watermarks. */
-    private rootUses;
-    private readonly childUsesMap;
-    /**
-     * @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);
-    /** Create a wallet from a Minima-compatible BIP39 seed phrase. */
-    static fromPhrase(phrase: string, childCount?: number): RootIdentityWallet;
-    /** Generate a new random Minima-compatible 24-word seed phrase. */
-    static generatePhrase(): string;
-    /** Validate a Minima-compatible seed phrase. */
-    static validatePhrase(phrase: string): boolean;
-    /** Minima address for the root key (slot 0). */
-    getRootAddress(): string;
-    /** 64-char hex public key for the root key. */
-    getRootPublicKey(): string;
-    /** Minima address for child `index` (0-based). */
-    getChildAddress(index: number): string;
-    /** 64-char hex public key for child `index`. */
-    getChildPublicKey(index: number): string;
-    /** All addresses: root first, then all children in order. */
-    getAllAddresses(): string[];
-    /** Root address and children as a structured object. */
-    getAddressMap(): {
-        root: string;
-        children: string[];
-    };
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /** Number of times the root key has been used (for persistence). */
-    getRootUses(): number;
-    /** Restore root watermark from a previously persisted value. */
-    setRootUses(uses: number): void;
-    /** Number of times child `index` has signed (for persistence). */
-    getChildUses(index: number): number;
-    /** Restore child watermark from a previously persisted value. */
-    setChildUses(index: number, uses: number): void;
-    /** Number of child addresses configured for this wallet. */
-    getChildCount(): number;
-    /** Maximum one-time signatures available per slot (3 levels × 64 keys). */
-    getMaxUsesPerSlot(): number;
-    /**
-     * 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>;
-    };
-    /**
-     * 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;
-    private assertChildIndex;
-    /**
-     * Get or create the TreeKey for a given slot.
-     * Also populates address and public key caches on first access.
-     */
-    private getOrCreateTreeKey;
-    private slotPublicKey;
-    private slotAddress;
-}
+export { UnifiedIdentityWallet as RootIdentityWallet, MAX_CHILD_COUNT } from './UnifiedIdentityWallet.js';

package/dist/RootIdentityWallet.js

@@ -1,374 +1,15 @@
 "use strict";
-/**
- * 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.
- */
 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.
- */
-const OWNERSHIP_OP = 'TOTEM_OWNERSHIP_PROOF_V1';
-// ─────────────────────────────────────────────────────────────────────────────
-// Helpers
-// ─────────────────────────────────────────────────────────────────────────────
-function hashMessage(message) {
-    return (0, sha3_js_1.sha3_256)(new TextEncoder().encode(message));
-}
-function addressFromPublicKeyBytes(pkBytes) {
-    const script = (0, core_1.scriptFromWotsPk)(pkBytes);
-    return (0, core_1.scriptToAddress)(script);
-}
+exports.MAX_CHILD_COUNT = exports.RootIdentityWallet = void 0;
 /**
- * Build the deterministic ownership-proof message that the root key signs.
+ * RootIdentityWallet — backward-compatibility re-export.
  *
- * 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`.
+ * The implementation has moved to UnifiedIdentityWallet which uses genuine
+ * hierarchical key derivation (root_priv_seed → child_seed_i).
  *
- * Field order is intentional — do not reorder without bumping OWNERSHIP_OP.
+ * All existing call sites should be updated to import UnifiedIdentityWallet
+ * directly. This shim is kept only to avoid hard import errors during migration.
  */
-function buildOwnershipMessage(rootAddress, childPublicKeys, timestamp) {
-    return JSON.stringify({
-        op: OWNERSHIP_OP,
-        rootAddress,
-        childPublicKeys: [...childPublicKeys].sort(),
-        timestamp,
-    });
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// 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 = exports.MAX_CHILD_COUNT) {
-        /** Cached TreeKey instances — created lazily to save memory. */
-        this.treeKeyCache = 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.
-         */
-        this.addressCache = new Map();
-        this.pubKeyCache = new Map();
-        /** Per-slot watermarks. */
-        this.rootUses = 0;
-        this.childUsesMap = new Map();
-        if (baseSeed.length !== 32) {
-            throw new Error(`baseSeed must be exactly 32 bytes, got ${baseSeed.length}`);
-        }
-        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 = 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 (0, core_1.generateSeedPhrase)();
-    }
-    /** Validate a Minima-compatible seed phrase. */
-    static validatePhrase(phrase) {
-        return (0, core_1.validatePhrase)(phrase);
-    }
-    // ── Address accessors ────────────────────────────────────────────────────────
-    /** Minima address for the root key (slot 0). */
-    getRootAddress() {
-        return this.slotAddress(0);
-    }
-    /** 64-char hex public key for the root key. */
-    getRootPublicKey() {
-        return this.slotPublicKey(0);
-    }
-    /** Minima address for child `index` (0-based). */
-    getChildAddress(index) {
-        this.assertChildIndex(index);
-        return this.slotAddress(index + 1);
-    }
-    /** 64-char hex public key for child `index`. */
-    getChildPublicKey(index) {
-        this.assertChildIndex(index);
-        return this.slotPublicKey(index + 1);
-    }
-    /** All addresses: root first, then all children in order. */
-    getAllAddresses() {
-        const out = [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() {
-        const children = [];
-        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) {
-        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: (0, core_1.bytesToHex)((0, core_1.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, message) {
-        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: (0, core_1.bytesToHex)((0, core_1.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) {
-        if (childIndices.length === 0) {
-            throw new Error('childIndices must contain at least one index');
-        }
-        const seen = new Set();
-        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) {
-        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 = (0, core_1.verifySignatureDetailed)(rootAddress, canonicalMessage, rootProof.signature, rootPublicKey);
-            if (!sigResult.valid)
-                return false;
-            for (let i = 0; i < childPublicKeys.length; i++) {
-                const pkBytes = (0, core_1.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) {
-        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() {
-        return this.getOrCreateTreeKey(0);
-    }
-    // ── Watermark access ─────────────────────────────────────────────────────────
-    /** Number of times the root key has been used (for persistence). */
-    getRootUses() { return this.rootUses; }
-    /** Restore root watermark from a previously persisted value. */
-    setRootUses(uses) {
-        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) {
-        this.assertChildIndex(index);
-        return this.childUsesMap.get(index) ?? 0;
-    }
-    /** Restore child watermark from a previously persisted value. */
-    setChildUses(index, uses) {
-        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() { return this.childCount; }
-    /** Maximum one-time signatures available per slot (3 levels × 64 keys). */
-    getMaxUsesPerSlot() { 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() {
-        const childUses = {};
-        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) {
-        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 ──────────────────────────────────────────────────────────
-    assertChildIndex(index) {
-        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.
-     */
-    getOrCreateTreeKey(slot) {
-        const cached = this.treeKeyCache.get(slot);
-        if (cached)
-            return cached;
-        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 = (0, core_1.bytesToHex)(pkBytes);
-        this.pubKeyCache.set(slot, pkHex);
-        this.addressCache.set(slot, addressFromPublicKeyBytes(pkBytes));
-        return treeKey;
-    }
-    slotPublicKey(slot) {
-        const cached = this.pubKeyCache.get(slot);
-        if (cached)
-            return cached;
-        this.getOrCreateTreeKey(slot); // populates both caches
-        return this.pubKeyCache.get(slot);
-    }
-    slotAddress(slot) {
-        const cached = this.addressCache.get(slot);
-        if (cached)
-            return cached;
-        this.getOrCreateTreeKey(slot); // populates both caches
-        return this.addressCache.get(slot);
-    }
-}
-exports.RootIdentityWallet = RootIdentityWallet;
+var UnifiedIdentityWallet_js_1 = require("./UnifiedIdentityWallet.js");
+Object.defineProperty(exports, "RootIdentityWallet", { enumerable: true, get: function () { return UnifiedIdentityWallet_js_1.UnifiedIdentityWallet; } });
+Object.defineProperty(exports, "MAX_CHILD_COUNT", { enumerable: true, get: function () { return UnifiedIdentityWallet_js_1.MAX_CHILD_COUNT; } });