@totemsdk/root-identity 1.0.5 → 1.0.7

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;
-}