@totemsdk/root-identity 1.0.3 → 1.0.5
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/README.md +88 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# @totemsdk/root-identity
|
|
2
|
+
|
|
3
|
+
**One seed → up to 64 blockchain addresses, all cryptographically provable as one identity.**
|
|
4
|
+
|
|
5
|
+
`RootIdentityWallet` generates a hierarchy of up to 64 independent TreeKey addresses from a single root seed. Each child has its own full 3-level TreeKey (not shallow derivations that weaken each other), and zero-knowledge-style ownership proofs let you prove that a set of addresses share one root — without revealing the root itself.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @totemsdk/root-identity
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## What's inside
|
|
14
|
+
|
|
15
|
+
| Export | What it does |
|
|
16
|
+
|--------|-------------|
|
|
17
|
+
| `RootIdentityWallet` | Generates and manages up to 64 independent child addresses |
|
|
18
|
+
| `MAX_CHILD_COUNT` | `64` — maximum child addresses per wallet |
|
|
19
|
+
| `WotsProof` | *(type only)* Proof that a signing key belongs to a specific child address |
|
|
20
|
+
| `OwnershipProof` | *(type only)* Proof that multiple addresses share the same root — without revealing the root |
|
|
21
|
+
|
|
22
|
+
### `RootIdentityWallet` API
|
|
23
|
+
|
|
24
|
+
| Member | Type | What it does |
|
|
25
|
+
|--------|------|-------------|
|
|
26
|
+
| `new RootIdentityWallet(baseSeed, childCount?)` | constructor | Create from a raw 32-byte seed |
|
|
27
|
+
| `RootIdentityWallet.fromPhrase(phrase, childCount?)` | static method | Create from a BIP39 mnemonic (synchronous) |
|
|
28
|
+
| `RootIdentityWallet.generatePhrase()` | static method | Generate a fresh 24-word mnemonic string |
|
|
29
|
+
| `RootIdentityWallet.validatePhrase(phrase)` | static method | Check if a phrase is valid BIP39 |
|
|
30
|
+
| `RootIdentityWallet.verifyOwnershipProof(proof)` | static method | Verify an `OwnershipProof` without the root seed |
|
|
31
|
+
|
|
32
|
+
### Use cases
|
|
33
|
+
|
|
34
|
+
- **Chain-of-custody proofs** — prove an item passed through a series of addresses you control
|
|
35
|
+
- **DAO multi-address attestation** — vote or attest with multiple addresses, provably from one member
|
|
36
|
+
- **Privacy-preserving KYC** — selectively disclose which addresses belong to a verified identity
|
|
37
|
+
- **NFT / token ownership linking** — prove that assets across multiple addresses belong to one owner
|
|
38
|
+
|
|
39
|
+
## Usage
|
|
40
|
+
|
|
41
|
+
### Create a wallet and derive addresses
|
|
42
|
+
|
|
43
|
+
```typescript
|
|
44
|
+
import { RootIdentityWallet } from '@totemsdk/root-identity';
|
|
45
|
+
|
|
46
|
+
// Generate a fresh 24-word phrase
|
|
47
|
+
const phrase = RootIdentityWallet.generatePhrase();
|
|
48
|
+
console.log('Root phrase (store securely!):', phrase);
|
|
49
|
+
|
|
50
|
+
// Restore from phrase (synchronous)
|
|
51
|
+
const wallet = RootIdentityWallet.fromPhrase(phrase);
|
|
52
|
+
|
|
53
|
+
// Or create from a raw seed directly
|
|
54
|
+
// const wallet = new RootIdentityWallet(baseSeedBytes);
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### Get child addresses
|
|
58
|
+
|
|
59
|
+
```typescript
|
|
60
|
+
const addr0 = wallet.getChildAddress(0);
|
|
61
|
+
const addr1 = wallet.getChildAddress(1);
|
|
62
|
+
console.log('Address 0:', addr0); // "Mx..."
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### Prove shared ownership
|
|
66
|
+
|
|
67
|
+
```typescript
|
|
68
|
+
// Prove that child addresses 0 and 2 belong to the same root identity
|
|
69
|
+
const proof = wallet.proveOwnership([0, 2]);
|
|
70
|
+
|
|
71
|
+
// Anyone can verify this proof without learning the root seed
|
|
72
|
+
const ok = RootIdentityWallet.verifyOwnershipProof(proof);
|
|
73
|
+
console.log('Valid:', ok);
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Validate a phrase before using it
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
const valid = RootIdentityWallet.validatePhrase(userInput);
|
|
80
|
+
if (!valid) throw new Error('Invalid seed phrase');
|
|
81
|
+
const wallet = RootIdentityWallet.fromPhrase(userInput);
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## See also
|
|
85
|
+
|
|
86
|
+
- [`@totemsdk/core`](../core) — `createPerAddressTreeKey` used internally for each child
|
|
87
|
+
- [`@totemsdk/wots-lease`](../wots-lease) — manage signing slot watermarks for each child address
|
|
88
|
+
- [`@totemsdk/statechain`](../statechain) — transfer assets between addresses off-chain
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@totemsdk/root-identity",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.5",
|
|
4
4
|
"description": "Single root identity controlling up to 64 on-chain addresses — all cryptographically linked via full independent 3-level TreeKeys",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -44,7 +44,7 @@
|
|
|
44
44
|
"jest": "^29.0.0",
|
|
45
45
|
"ts-jest": "^29.0.0",
|
|
46
46
|
"typescript": "^5.0.0",
|
|
47
|
-
"@totemsdk/core": "1.0.
|
|
47
|
+
"@totemsdk/core": "1.0.9"
|
|
48
48
|
},
|
|
49
49
|
"keywords": [
|
|
50
50
|
"totem",
|