@totemsdk/root-identity 1.0.5 → 1.0.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +3 -3
- package/dist/RootIdentityWallet.d.ts +6 -160
- package/dist/RootIdentityWallet.js +11 -366
- package/dist/UnifiedIdentityWallet.d.ts +158 -0
- package/dist/UnifiedIdentityWallet.js +361 -0
- package/dist/index.d.ts +8 -2
- package/dist/index.js +13 -2
- package/dist/types.js +2 -1
- package/package.json +22 -9
- package/src/RootIdentityWallet.ts +0 -435
- package/src/__tests__/watermark.test.ts +0 -83
- package/src/index.ts +0 -15
- package/src/types.ts +0 -39
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 Totem SDK Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -83,6 +83,6 @@ const wallet = RootIdentityWallet.fromPhrase(userInput);
|
|
|
83
83
|
|
|
84
84
|
## See also
|
|
85
85
|
|
|
86
|
-
- [`@totemsdk/core`](
|
|
87
|
-
- [`@totemsdk/wots-lease`](
|
|
88
|
-
- [`@totemsdk/statechain`](
|
|
86
|
+
- [`@totemsdk/core`](https://www.npmjs.com/package/@totemsdk/core) — `createPerAddressTreeKey` used internally for each child
|
|
87
|
+
- [`@totemsdk/wots-lease`](https://www.npmjs.com/package/@totemsdk/wots-lease) — manage signing slot watermarks for each child address
|
|
88
|
+
- [`@totemsdk/statechain`](https://www.npmjs.com/package/@totemsdk/statechain) — transfer assets between addresses off-chain
|
|
@@ -1,164 +1,10 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* RootIdentityWallet —
|
|
2
|
+
* RootIdentityWallet — backward-compatibility re-export.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
* baseSeed (32 bytes)
|
|
7
|
-
* │
|
|
8
|
-
* ├── Slot 0 createPerAddressTreeKey(baseSeed, 0) ← ROOT (signs ownership proofs)
|
|
9
|
-
* ├── Slot 1 createPerAddressTreeKey(baseSeed, 1) ← child 0
|
|
10
|
-
* ├── Slot 2 createPerAddressTreeKey(baseSeed, 2) ← child 1
|
|
11
|
-
* │ …
|
|
12
|
-
* └── Slot 64 createPerAddressTreeKey(baseSeed, 64) ← child 63
|
|
4
|
+
* The implementation has moved to UnifiedIdentityWallet which uses genuine
|
|
5
|
+
* hierarchical key derivation (root_priv_seed → child_seed_i).
|
|
13
6
|
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
* SHA3-256( MiniData(baseSeed) ∥ MiniData(BigInteger(slot)) )
|
|
17
|
-
*
|
|
18
|
-
* Watermarks are tracked in memory. Callers that need persistence should read
|
|
19
|
-
* `getRootUses()` / `getChildUses(index)` after each signing operation and
|
|
20
|
-
* restore them via `setRootUses()` / `setChildUses()` on the next session.
|
|
7
|
+
* All existing call sites should be updated to import UnifiedIdentityWallet
|
|
8
|
+
* directly. This shim is kept only to avoid hard import errors during migration.
|
|
21
9
|
*/
|
|
22
|
-
|
|
23
|
-
import type { WotsProof, OwnershipProof } from './types.js';
|
|
24
|
-
export declare const MAX_CHILD_COUNT = 64;
|
|
25
|
-
export declare class RootIdentityWallet {
|
|
26
|
-
private readonly baseSeed;
|
|
27
|
-
private readonly childCount;
|
|
28
|
-
/** Cached TreeKey instances — created lazily to save memory. */
|
|
29
|
-
private readonly treeKeyCache;
|
|
30
|
-
/**
|
|
31
|
-
* Cached addresses and public keys per slot (slot 0 = root, slot i+1 = child i).
|
|
32
|
-
* Avoids expensive TreeKey regeneration on repeated address lookups.
|
|
33
|
-
*/
|
|
34
|
-
private readonly addressCache;
|
|
35
|
-
private readonly pubKeyCache;
|
|
36
|
-
/** Per-slot watermarks. */
|
|
37
|
-
private rootUses;
|
|
38
|
-
private readonly childUsesMap;
|
|
39
|
-
/**
|
|
40
|
-
* @param baseSeed - 32-byte raw seed (use `RootIdentityWallet.fromPhrase` for mnemonic input)
|
|
41
|
-
* @param childCount - Number of child addresses (1–64, default 64)
|
|
42
|
-
*/
|
|
43
|
-
constructor(baseSeed: Uint8Array, childCount?: number);
|
|
44
|
-
/** Create a wallet from a Minima-compatible BIP39 seed phrase. */
|
|
45
|
-
static fromPhrase(phrase: string, childCount?: number): RootIdentityWallet;
|
|
46
|
-
/** Generate a new random Minima-compatible 24-word seed phrase. */
|
|
47
|
-
static generatePhrase(): string;
|
|
48
|
-
/** Validate a Minima-compatible seed phrase. */
|
|
49
|
-
static validatePhrase(phrase: string): boolean;
|
|
50
|
-
/** Minima address for the root key (slot 0). */
|
|
51
|
-
getRootAddress(): string;
|
|
52
|
-
/** 64-char hex public key for the root key. */
|
|
53
|
-
getRootPublicKey(): string;
|
|
54
|
-
/** Minima address for child `index` (0-based). */
|
|
55
|
-
getChildAddress(index: number): string;
|
|
56
|
-
/** 64-char hex public key for child `index`. */
|
|
57
|
-
getChildPublicKey(index: number): string;
|
|
58
|
-
/** All addresses: root first, then all children in order. */
|
|
59
|
-
getAllAddresses(): string[];
|
|
60
|
-
/** Root address and children as a structured object. */
|
|
61
|
-
getAddressMap(): {
|
|
62
|
-
root: string;
|
|
63
|
-
children: string[];
|
|
64
|
-
};
|
|
65
|
-
/**
|
|
66
|
-
* Sign `message` with the root key.
|
|
67
|
-
* Hashes the message with SHA3-256 before signing — identical to `verifySignatureDetailed`.
|
|
68
|
-
* @throws if root TreeKey is exhausted (262 144 uses)
|
|
69
|
-
*/
|
|
70
|
-
signFromRoot(message: string): WotsProof;
|
|
71
|
-
/**
|
|
72
|
-
* Sign `message` with child key `index` (0-based).
|
|
73
|
-
* Each child maintains its own independent use counter.
|
|
74
|
-
* @throws if child TreeKey is exhausted or index out of range
|
|
75
|
-
*/
|
|
76
|
-
signFromChild(index: number, message: string): WotsProof;
|
|
77
|
-
/**
|
|
78
|
-
* Produce an ownership proof demonstrating that the root key controls all
|
|
79
|
-
* given child addresses.
|
|
80
|
-
*
|
|
81
|
-
* @param childIndices - Which children to include (0-based, order preserved)
|
|
82
|
-
*/
|
|
83
|
-
proveOwnership(childIndices: number[]): OwnershipProof;
|
|
84
|
-
/**
|
|
85
|
-
* Verify an ownership proof produced by `proveOwnership`.
|
|
86
|
-
*
|
|
87
|
-
* Returns `true` only when:
|
|
88
|
-
* - The canonical message is reconstructed correctly (child keys are sorted).
|
|
89
|
-
* - The root WOTS signature validates against the root public key and address.
|
|
90
|
-
* - Every child public key correctly derives the corresponding child address.
|
|
91
|
-
*
|
|
92
|
-
* Pure crypto — no network access required.
|
|
93
|
-
* Always returns `false` (never throws) on malformed or incomplete proof data.
|
|
94
|
-
*/
|
|
95
|
-
static verifyOwnershipProof(proof: OwnershipProof): boolean;
|
|
96
|
-
/**
|
|
97
|
-
* Get (or create and cache) the TreeKey for child `index` (0-based).
|
|
98
|
-
*
|
|
99
|
-
* Callers that need positional watermark control (e.g. `setUses(l1*64+l2)`)
|
|
100
|
-
* can use this to drive WOTS signing directly — the same path the Totem
|
|
101
|
-
* extension uses for transaction signing in RootTree mode.
|
|
102
|
-
*
|
|
103
|
-
* Note: This does NOT advance the high-level `childUsesMap` counter.
|
|
104
|
-
* Call `getChildUses` / `setChildUses` yourself if you need to track uses.
|
|
105
|
-
*/
|
|
106
|
-
getChildTreeKey(index: number): TreeKey;
|
|
107
|
-
/**
|
|
108
|
-
* Get (or create and cache) the root TreeKey (slot 0).
|
|
109
|
-
*
|
|
110
|
-
* Useful for callers that need direct access to the root key's TreeKey
|
|
111
|
-
* object for custom signing operations.
|
|
112
|
-
*/
|
|
113
|
-
getRootTreeKey(): TreeKey;
|
|
114
|
-
/** Number of times the root key has been used (for persistence). */
|
|
115
|
-
getRootUses(): number;
|
|
116
|
-
/** Restore root watermark from a previously persisted value. */
|
|
117
|
-
setRootUses(uses: number): void;
|
|
118
|
-
/** Number of times child `index` has signed (for persistence). */
|
|
119
|
-
getChildUses(index: number): number;
|
|
120
|
-
/** Restore child watermark from a previously persisted value. */
|
|
121
|
-
setChildUses(index: number, uses: number): void;
|
|
122
|
-
/** Number of child addresses configured for this wallet. */
|
|
123
|
-
getChildCount(): number;
|
|
124
|
-
/** Maximum one-time signatures available per slot (3 levels × 64 keys). */
|
|
125
|
-
getMaxUsesPerSlot(): number;
|
|
126
|
-
/**
|
|
127
|
-
* Return a serialisable snapshot of all current watermark counters.
|
|
128
|
-
*
|
|
129
|
-
* Persist the returned object (e.g. to encrypted storage) and pass it back
|
|
130
|
-
* to `restoreWatermarkState()` at the start of the next session so that no
|
|
131
|
-
* one-time-use signing slot is ever reused.
|
|
132
|
-
*
|
|
133
|
-
* @example
|
|
134
|
-
* const state = wallet.getWatermarkState();
|
|
135
|
-
* await storage.set('watermarks', JSON.stringify(state));
|
|
136
|
-
*/
|
|
137
|
-
getWatermarkState(): {
|
|
138
|
-
rootUses: number;
|
|
139
|
-
childUses: Record<number, number>;
|
|
140
|
-
};
|
|
141
|
-
/**
|
|
142
|
-
* Restore watermark counters from a previously persisted snapshot.
|
|
143
|
-
*
|
|
144
|
-
* Call this immediately after constructing the wallet to prevent slot reuse
|
|
145
|
-
* across sessions. All values must be non-negative integers; out-of-range
|
|
146
|
-
* or invalid entries are silently skipped.
|
|
147
|
-
*
|
|
148
|
-
* @example
|
|
149
|
-
* const saved = JSON.parse(await storage.get('watermarks') ?? '{}');
|
|
150
|
-
* wallet.restoreWatermarkState(saved);
|
|
151
|
-
*/
|
|
152
|
-
restoreWatermarkState(state: {
|
|
153
|
-
rootUses?: number;
|
|
154
|
-
childUses?: Record<number, number>;
|
|
155
|
-
}): void;
|
|
156
|
-
private assertChildIndex;
|
|
157
|
-
/**
|
|
158
|
-
* Get or create the TreeKey for a given slot.
|
|
159
|
-
* Also populates address and public key caches on first access.
|
|
160
|
-
*/
|
|
161
|
-
private getOrCreateTreeKey;
|
|
162
|
-
private slotPublicKey;
|
|
163
|
-
private slotAddress;
|
|
164
|
-
}
|
|
10
|
+
export { UnifiedIdentityWallet as RootIdentityWallet, MAX_CHILD_COUNT } from './UnifiedIdentityWallet.js';
|
|
@@ -1,370 +1,15 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.MAX_CHILD_COUNT = exports.RootIdentityWallet = void 0;
|
|
1
4
|
/**
|
|
2
|
-
* RootIdentityWallet —
|
|
5
|
+
* RootIdentityWallet — backward-compatibility re-export.
|
|
3
6
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
* baseSeed (32 bytes)
|
|
7
|
-
* │
|
|
8
|
-
* ├── Slot 0 createPerAddressTreeKey(baseSeed, 0) ← ROOT (signs ownership proofs)
|
|
9
|
-
* ├── Slot 1 createPerAddressTreeKey(baseSeed, 1) ← child 0
|
|
10
|
-
* ├── Slot 2 createPerAddressTreeKey(baseSeed, 2) ← child 1
|
|
11
|
-
* │ …
|
|
12
|
-
* └── Slot 64 createPerAddressTreeKey(baseSeed, 64) ← child 63
|
|
7
|
+
* The implementation has moved to UnifiedIdentityWallet which uses genuine
|
|
8
|
+
* hierarchical key derivation (root_priv_seed → child_seed_i).
|
|
13
9
|
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
* SHA3-256( MiniData(baseSeed) ∥ MiniData(BigInteger(slot)) )
|
|
17
|
-
*
|
|
18
|
-
* Watermarks are tracked in memory. Callers that need persistence should read
|
|
19
|
-
* `getRootUses()` / `getChildUses(index)` after each signing operation and
|
|
20
|
-
* restore them via `setRootUses()` / `setChildUses()` on the next session.
|
|
21
|
-
*/
|
|
22
|
-
import { sha3_256 } from '@noble/hashes/sha3.js';
|
|
23
|
-
import { createPerAddressTreeKey, serializeTreeSignature, verifySignatureDetailed, scriptFromWotsPk, scriptToAddress, bytesToHex, hexToBytes, phraseToSeed, generateSeedPhrase, validatePhrase, } from '@totemsdk/core';
|
|
24
|
-
export const MAX_CHILD_COUNT = 64;
|
|
25
|
-
/**
|
|
26
|
-
* Canonical message prefix for ownership proofs.
|
|
27
|
-
* Bump the version if the message schema ever changes.
|
|
28
|
-
*/
|
|
29
|
-
const OWNERSHIP_OP = 'TOTEM_OWNERSHIP_PROOF_V1';
|
|
30
|
-
// ─────────────────────────────────────────────────────────────────────────────
|
|
31
|
-
// Helpers
|
|
32
|
-
// ─────────────────────────────────────────────────────────────────────────────
|
|
33
|
-
function hashMessage(message) {
|
|
34
|
-
return sha3_256(new TextEncoder().encode(message));
|
|
35
|
-
}
|
|
36
|
-
function addressFromPublicKeyBytes(pkBytes) {
|
|
37
|
-
const script = scriptFromWotsPk(pkBytes);
|
|
38
|
-
return scriptToAddress(script);
|
|
39
|
-
}
|
|
40
|
-
/**
|
|
41
|
-
* Build the deterministic ownership-proof message that the root key signs.
|
|
42
|
-
*
|
|
43
|
-
* Child public keys are sorted lexicographically before serialization so that
|
|
44
|
-
* the same child set always produces the same canonical message regardless of
|
|
45
|
-
* the order in which indices were passed to `proveOwnership`.
|
|
46
|
-
*
|
|
47
|
-
* Field order is intentional — do not reorder without bumping OWNERSHIP_OP.
|
|
10
|
+
* All existing call sites should be updated to import UnifiedIdentityWallet
|
|
11
|
+
* directly. This shim is kept only to avoid hard import errors during migration.
|
|
48
12
|
*/
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
rootAddress,
|
|
53
|
-
childPublicKeys: [...childPublicKeys].sort(),
|
|
54
|
-
timestamp,
|
|
55
|
-
});
|
|
56
|
-
}
|
|
57
|
-
// ─────────────────────────────────────────────────────────────────────────────
|
|
58
|
-
// RootIdentityWallet
|
|
59
|
-
// ─────────────────────────────────────────────────────────────────────────────
|
|
60
|
-
export class RootIdentityWallet {
|
|
61
|
-
// ── Construction ────────────────────────────────────────────────────────────
|
|
62
|
-
/**
|
|
63
|
-
* @param baseSeed - 32-byte raw seed (use `RootIdentityWallet.fromPhrase` for mnemonic input)
|
|
64
|
-
* @param childCount - Number of child addresses (1–64, default 64)
|
|
65
|
-
*/
|
|
66
|
-
constructor(baseSeed, childCount = MAX_CHILD_COUNT) {
|
|
67
|
-
/** Cached TreeKey instances — created lazily to save memory. */
|
|
68
|
-
this.treeKeyCache = new Map();
|
|
69
|
-
/**
|
|
70
|
-
* Cached addresses and public keys per slot (slot 0 = root, slot i+1 = child i).
|
|
71
|
-
* Avoids expensive TreeKey regeneration on repeated address lookups.
|
|
72
|
-
*/
|
|
73
|
-
this.addressCache = new Map();
|
|
74
|
-
this.pubKeyCache = new Map();
|
|
75
|
-
/** Per-slot watermarks. */
|
|
76
|
-
this.rootUses = 0;
|
|
77
|
-
this.childUsesMap = new Map();
|
|
78
|
-
if (baseSeed.length !== 32) {
|
|
79
|
-
throw new Error(`baseSeed must be exactly 32 bytes, got ${baseSeed.length}`);
|
|
80
|
-
}
|
|
81
|
-
if (childCount < 1 || childCount > MAX_CHILD_COUNT) {
|
|
82
|
-
throw new Error(`childCount must be 1–${MAX_CHILD_COUNT}, got ${childCount}`);
|
|
83
|
-
}
|
|
84
|
-
this.baseSeed = baseSeed;
|
|
85
|
-
this.childCount = childCount;
|
|
86
|
-
}
|
|
87
|
-
/** Create a wallet from a Minima-compatible BIP39 seed phrase. */
|
|
88
|
-
static fromPhrase(phrase, childCount = MAX_CHILD_COUNT) {
|
|
89
|
-
return new RootIdentityWallet(phraseToSeed(phrase), childCount);
|
|
90
|
-
}
|
|
91
|
-
/** Generate a new random Minima-compatible 24-word seed phrase. */
|
|
92
|
-
static generatePhrase() {
|
|
93
|
-
return generateSeedPhrase();
|
|
94
|
-
}
|
|
95
|
-
/** Validate a Minima-compatible seed phrase. */
|
|
96
|
-
static validatePhrase(phrase) {
|
|
97
|
-
return validatePhrase(phrase);
|
|
98
|
-
}
|
|
99
|
-
// ── Address accessors ────────────────────────────────────────────────────────
|
|
100
|
-
/** Minima address for the root key (slot 0). */
|
|
101
|
-
getRootAddress() {
|
|
102
|
-
return this.slotAddress(0);
|
|
103
|
-
}
|
|
104
|
-
/** 64-char hex public key for the root key. */
|
|
105
|
-
getRootPublicKey() {
|
|
106
|
-
return this.slotPublicKey(0);
|
|
107
|
-
}
|
|
108
|
-
/** Minima address for child `index` (0-based). */
|
|
109
|
-
getChildAddress(index) {
|
|
110
|
-
this.assertChildIndex(index);
|
|
111
|
-
return this.slotAddress(index + 1);
|
|
112
|
-
}
|
|
113
|
-
/** 64-char hex public key for child `index`. */
|
|
114
|
-
getChildPublicKey(index) {
|
|
115
|
-
this.assertChildIndex(index);
|
|
116
|
-
return this.slotPublicKey(index + 1);
|
|
117
|
-
}
|
|
118
|
-
/** All addresses: root first, then all children in order. */
|
|
119
|
-
getAllAddresses() {
|
|
120
|
-
const out = [this.getRootAddress()];
|
|
121
|
-
for (let i = 0; i < this.childCount; i++) {
|
|
122
|
-
out.push(this.getChildAddress(i));
|
|
123
|
-
}
|
|
124
|
-
return out;
|
|
125
|
-
}
|
|
126
|
-
/** Root address and children as a structured object. */
|
|
127
|
-
getAddressMap() {
|
|
128
|
-
const children = [];
|
|
129
|
-
for (let i = 0; i < this.childCount; i++) {
|
|
130
|
-
children.push(this.getChildAddress(i));
|
|
131
|
-
}
|
|
132
|
-
return { root: this.getRootAddress(), children };
|
|
133
|
-
}
|
|
134
|
-
// ── Signing ─────────────────────────────────────────────────────────────────
|
|
135
|
-
/**
|
|
136
|
-
* Sign `message` with the root key.
|
|
137
|
-
* Hashes the message with SHA3-256 before signing — identical to `verifySignatureDetailed`.
|
|
138
|
-
* @throws if root TreeKey is exhausted (262 144 uses)
|
|
139
|
-
*/
|
|
140
|
-
signFromRoot(message) {
|
|
141
|
-
const treeKey = this.getOrCreateTreeKey(0);
|
|
142
|
-
treeKey.setUses(this.rootUses);
|
|
143
|
-
const sig = treeKey.sign(hashMessage(message));
|
|
144
|
-
this.rootUses++;
|
|
145
|
-
return {
|
|
146
|
-
address: this.getRootAddress(),
|
|
147
|
-
publicKey: this.getRootPublicKey(),
|
|
148
|
-
signature: bytesToHex(serializeTreeSignature(sig)),
|
|
149
|
-
message,
|
|
150
|
-
};
|
|
151
|
-
}
|
|
152
|
-
/**
|
|
153
|
-
* Sign `message` with child key `index` (0-based).
|
|
154
|
-
* Each child maintains its own independent use counter.
|
|
155
|
-
* @throws if child TreeKey is exhausted or index out of range
|
|
156
|
-
*/
|
|
157
|
-
signFromChild(index, message) {
|
|
158
|
-
this.assertChildIndex(index);
|
|
159
|
-
const slot = index + 1;
|
|
160
|
-
const treeKey = this.getOrCreateTreeKey(slot);
|
|
161
|
-
const uses = this.childUsesMap.get(index) ?? 0;
|
|
162
|
-
treeKey.setUses(uses);
|
|
163
|
-
const sig = treeKey.sign(hashMessage(message));
|
|
164
|
-
this.childUsesMap.set(index, uses + 1);
|
|
165
|
-
return {
|
|
166
|
-
address: this.getChildAddress(index),
|
|
167
|
-
publicKey: this.getChildPublicKey(index),
|
|
168
|
-
signature: bytesToHex(serializeTreeSignature(sig)),
|
|
169
|
-
message,
|
|
170
|
-
};
|
|
171
|
-
}
|
|
172
|
-
// ── Ownership proofs ─────────────────────────────────────────────────────────
|
|
173
|
-
/**
|
|
174
|
-
* Produce an ownership proof demonstrating that the root key controls all
|
|
175
|
-
* given child addresses.
|
|
176
|
-
*
|
|
177
|
-
* @param childIndices - Which children to include (0-based, order preserved)
|
|
178
|
-
*/
|
|
179
|
-
proveOwnership(childIndices) {
|
|
180
|
-
if (childIndices.length === 0) {
|
|
181
|
-
throw new Error('childIndices must contain at least one index');
|
|
182
|
-
}
|
|
183
|
-
const seen = new Set();
|
|
184
|
-
for (const idx of childIndices) {
|
|
185
|
-
this.assertChildIndex(idx);
|
|
186
|
-
if (seen.has(idx))
|
|
187
|
-
throw new Error(`Duplicate child index: ${idx}`);
|
|
188
|
-
seen.add(idx);
|
|
189
|
-
}
|
|
190
|
-
const timestamp = new Date().toISOString();
|
|
191
|
-
const childAddresses = childIndices.map(i => this.getChildAddress(i));
|
|
192
|
-
const childPublicKeys = childIndices.map(i => this.getChildPublicKey(i));
|
|
193
|
-
const rootAddress = this.getRootAddress();
|
|
194
|
-
const rootPublicKey = this.getRootPublicKey();
|
|
195
|
-
const message = buildOwnershipMessage(rootAddress, childPublicKeys, timestamp);
|
|
196
|
-
const rootProof = this.signFromRoot(message);
|
|
197
|
-
return { rootAddress, rootPublicKey, childAddresses, childPublicKeys, rootProof, timestamp };
|
|
198
|
-
}
|
|
199
|
-
/**
|
|
200
|
-
* Verify an ownership proof produced by `proveOwnership`.
|
|
201
|
-
*
|
|
202
|
-
* Returns `true` only when:
|
|
203
|
-
* - The canonical message is reconstructed correctly (child keys are sorted).
|
|
204
|
-
* - The root WOTS signature validates against the root public key and address.
|
|
205
|
-
* - Every child public key correctly derives the corresponding child address.
|
|
206
|
-
*
|
|
207
|
-
* Pure crypto — no network access required.
|
|
208
|
-
* Always returns `false` (never throws) on malformed or incomplete proof data.
|
|
209
|
-
*/
|
|
210
|
-
static verifyOwnershipProof(proof) {
|
|
211
|
-
try {
|
|
212
|
-
if (!proof || typeof proof !== 'object')
|
|
213
|
-
return false;
|
|
214
|
-
const { rootAddress, rootPublicKey, childAddresses, childPublicKeys, rootProof, timestamp } = proof;
|
|
215
|
-
if (!rootAddress || !rootPublicKey || !timestamp ||
|
|
216
|
-
!Array.isArray(childAddresses) || !Array.isArray(childPublicKeys) ||
|
|
217
|
-
!rootProof || typeof rootProof.signature !== 'string') {
|
|
218
|
-
return false;
|
|
219
|
-
}
|
|
220
|
-
if (childAddresses.length === 0)
|
|
221
|
-
return false;
|
|
222
|
-
if (childAddresses.length !== childPublicKeys.length)
|
|
223
|
-
return false;
|
|
224
|
-
const canonicalMessage = buildOwnershipMessage(rootAddress, childPublicKeys, timestamp);
|
|
225
|
-
if (rootProof.message !== canonicalMessage)
|
|
226
|
-
return false;
|
|
227
|
-
const sigResult = verifySignatureDetailed(rootAddress, canonicalMessage, rootProof.signature, rootPublicKey);
|
|
228
|
-
if (!sigResult.valid)
|
|
229
|
-
return false;
|
|
230
|
-
for (let i = 0; i < childPublicKeys.length; i++) {
|
|
231
|
-
const pkBytes = hexToBytes(childPublicKeys[i]);
|
|
232
|
-
const derivedAddress = addressFromPublicKeyBytes(pkBytes);
|
|
233
|
-
if (derivedAddress.toLowerCase() !== childAddresses[i].toLowerCase())
|
|
234
|
-
return false;
|
|
235
|
-
}
|
|
236
|
-
return true;
|
|
237
|
-
}
|
|
238
|
-
catch {
|
|
239
|
-
return false;
|
|
240
|
-
}
|
|
241
|
-
}
|
|
242
|
-
// ── TreeKey access (for low-level transaction signing) ───────────────────────
|
|
243
|
-
/**
|
|
244
|
-
* Get (or create and cache) the TreeKey for child `index` (0-based).
|
|
245
|
-
*
|
|
246
|
-
* Callers that need positional watermark control (e.g. `setUses(l1*64+l2)`)
|
|
247
|
-
* can use this to drive WOTS signing directly — the same path the Totem
|
|
248
|
-
* extension uses for transaction signing in RootTree mode.
|
|
249
|
-
*
|
|
250
|
-
* Note: This does NOT advance the high-level `childUsesMap` counter.
|
|
251
|
-
* Call `getChildUses` / `setChildUses` yourself if you need to track uses.
|
|
252
|
-
*/
|
|
253
|
-
getChildTreeKey(index) {
|
|
254
|
-
this.assertChildIndex(index);
|
|
255
|
-
return this.getOrCreateTreeKey(index + 1);
|
|
256
|
-
}
|
|
257
|
-
/**
|
|
258
|
-
* Get (or create and cache) the root TreeKey (slot 0).
|
|
259
|
-
*
|
|
260
|
-
* Useful for callers that need direct access to the root key's TreeKey
|
|
261
|
-
* object for custom signing operations.
|
|
262
|
-
*/
|
|
263
|
-
getRootTreeKey() {
|
|
264
|
-
return this.getOrCreateTreeKey(0);
|
|
265
|
-
}
|
|
266
|
-
// ── Watermark access ─────────────────────────────────────────────────────────
|
|
267
|
-
/** Number of times the root key has been used (for persistence). */
|
|
268
|
-
getRootUses() { return this.rootUses; }
|
|
269
|
-
/** Restore root watermark from a previously persisted value. */
|
|
270
|
-
setRootUses(uses) {
|
|
271
|
-
if (uses < 0)
|
|
272
|
-
throw new Error('uses must be non-negative');
|
|
273
|
-
this.rootUses = uses;
|
|
274
|
-
}
|
|
275
|
-
/** Number of times child `index` has signed (for persistence). */
|
|
276
|
-
getChildUses(index) {
|
|
277
|
-
this.assertChildIndex(index);
|
|
278
|
-
return this.childUsesMap.get(index) ?? 0;
|
|
279
|
-
}
|
|
280
|
-
/** Restore child watermark from a previously persisted value. */
|
|
281
|
-
setChildUses(index, uses) {
|
|
282
|
-
this.assertChildIndex(index);
|
|
283
|
-
if (uses < 0)
|
|
284
|
-
throw new Error('uses must be non-negative');
|
|
285
|
-
this.childUsesMap.set(index, uses);
|
|
286
|
-
}
|
|
287
|
-
/** Number of child addresses configured for this wallet. */
|
|
288
|
-
getChildCount() { return this.childCount; }
|
|
289
|
-
/** Maximum one-time signatures available per slot (3 levels × 64 keys). */
|
|
290
|
-
getMaxUsesPerSlot() { return 64 * 64 * 64; }
|
|
291
|
-
/**
|
|
292
|
-
* Return a serialisable snapshot of all current watermark counters.
|
|
293
|
-
*
|
|
294
|
-
* Persist the returned object (e.g. to encrypted storage) and pass it back
|
|
295
|
-
* to `restoreWatermarkState()` at the start of the next session so that no
|
|
296
|
-
* one-time-use signing slot is ever reused.
|
|
297
|
-
*
|
|
298
|
-
* @example
|
|
299
|
-
* const state = wallet.getWatermarkState();
|
|
300
|
-
* await storage.set('watermarks', JSON.stringify(state));
|
|
301
|
-
*/
|
|
302
|
-
getWatermarkState() {
|
|
303
|
-
const childUses = {};
|
|
304
|
-
for (const [index, uses] of this.childUsesMap) {
|
|
305
|
-
childUses[index] = uses;
|
|
306
|
-
}
|
|
307
|
-
return { rootUses: this.rootUses, childUses };
|
|
308
|
-
}
|
|
309
|
-
/**
|
|
310
|
-
* Restore watermark counters from a previously persisted snapshot.
|
|
311
|
-
*
|
|
312
|
-
* Call this immediately after constructing the wallet to prevent slot reuse
|
|
313
|
-
* across sessions. All values must be non-negative integers; out-of-range
|
|
314
|
-
* or invalid entries are silently skipped.
|
|
315
|
-
*
|
|
316
|
-
* @example
|
|
317
|
-
* const saved = JSON.parse(await storage.get('watermarks') ?? '{}');
|
|
318
|
-
* wallet.restoreWatermarkState(saved);
|
|
319
|
-
*/
|
|
320
|
-
restoreWatermarkState(state) {
|
|
321
|
-
if (typeof state?.rootUses === 'number' && state.rootUses >= 0) {
|
|
322
|
-
this.rootUses = Math.floor(state.rootUses);
|
|
323
|
-
}
|
|
324
|
-
if (state?.childUses && typeof state.childUses === 'object') {
|
|
325
|
-
for (const [key, uses] of Object.entries(state.childUses)) {
|
|
326
|
-
const index = Number(key);
|
|
327
|
-
if (Number.isInteger(index) && index >= 0 && index < this.childCount && typeof uses === 'number' && uses >= 0) {
|
|
328
|
-
this.childUsesMap.set(index, Math.floor(uses));
|
|
329
|
-
}
|
|
330
|
-
}
|
|
331
|
-
}
|
|
332
|
-
}
|
|
333
|
-
// ── Private helpers ──────────────────────────────────────────────────────────
|
|
334
|
-
assertChildIndex(index) {
|
|
335
|
-
if (!Number.isInteger(index) || index < 0 || index >= this.childCount) {
|
|
336
|
-
throw new Error(`Child index ${index} is out of range [0, ${this.childCount - 1}]`);
|
|
337
|
-
}
|
|
338
|
-
}
|
|
339
|
-
/**
|
|
340
|
-
* Get or create the TreeKey for a given slot.
|
|
341
|
-
* Also populates address and public key caches on first access.
|
|
342
|
-
*/
|
|
343
|
-
getOrCreateTreeKey(slot) {
|
|
344
|
-
const cached = this.treeKeyCache.get(slot);
|
|
345
|
-
if (cached)
|
|
346
|
-
return cached;
|
|
347
|
-
const treeKey = createPerAddressTreeKey(this.baseSeed, slot);
|
|
348
|
-
this.treeKeyCache.set(slot, treeKey);
|
|
349
|
-
// Cache address and public key while we have the TreeKey
|
|
350
|
-
const pkBytes = treeKey.getPublicKey();
|
|
351
|
-
const pkHex = bytesToHex(pkBytes);
|
|
352
|
-
this.pubKeyCache.set(slot, pkHex);
|
|
353
|
-
this.addressCache.set(slot, addressFromPublicKeyBytes(pkBytes));
|
|
354
|
-
return treeKey;
|
|
355
|
-
}
|
|
356
|
-
slotPublicKey(slot) {
|
|
357
|
-
const cached = this.pubKeyCache.get(slot);
|
|
358
|
-
if (cached)
|
|
359
|
-
return cached;
|
|
360
|
-
this.getOrCreateTreeKey(slot); // populates both caches
|
|
361
|
-
return this.pubKeyCache.get(slot);
|
|
362
|
-
}
|
|
363
|
-
slotAddress(slot) {
|
|
364
|
-
const cached = this.addressCache.get(slot);
|
|
365
|
-
if (cached)
|
|
366
|
-
return cached;
|
|
367
|
-
this.getOrCreateTreeKey(slot); // populates both caches
|
|
368
|
-
return this.addressCache.get(slot);
|
|
369
|
-
}
|
|
370
|
-
}
|
|
13
|
+
var UnifiedIdentityWallet_js_1 = require("./UnifiedIdentityWallet.js");
|
|
14
|
+
Object.defineProperty(exports, "RootIdentityWallet", { enumerable: true, get: function () { return UnifiedIdentityWallet_js_1.UnifiedIdentityWallet; } });
|
|
15
|
+
Object.defineProperty(exports, "MAX_CHILD_COUNT", { enumerable: true, get: function () { return UnifiedIdentityWallet_js_1.MAX_CHILD_COUNT; } });
|