@totemsdk/wots-lease 0.1.0 → 0.1.2
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 +97 -0
- package/package.json +10 -10
package/README.md
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# @totemsdk/wots-lease
|
|
2
|
+
|
|
3
|
+
**WOTS key safety — prevents catastrophic signature slot reuse.**
|
|
4
|
+
|
|
5
|
+
> ⚠️ **WOTS keys are one-time use.** Reusing a signing slot leaks the private key and permanently destroys the security of that address. This package is the guardian that prevents it from happening.
|
|
6
|
+
|
|
7
|
+
Coordinates key-use watermarks across devices and sessions so no signing slot is ever allocated twice.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @totemsdk/wots-lease
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## What's inside
|
|
16
|
+
|
|
17
|
+
### Core stores
|
|
18
|
+
|
|
19
|
+
| Class | What it does |
|
|
20
|
+
|-------|-------------|
|
|
21
|
+
| `WotsWatermarkStore` | Canonical v3 watermark tracking; `flatIndex` maps `(l1, l2)` → flat slot number |
|
|
22
|
+
| `LeaseJournal` | Append-only audit log of every signing slot allocation |
|
|
23
|
+
|
|
24
|
+
### Provider tiers
|
|
25
|
+
|
|
26
|
+
| Provider | Use case |
|
|
27
|
+
|----------|----------|
|
|
28
|
+
| `LocalLeaseProvider` | Single-device, in-process coordination |
|
|
29
|
+
| `AxiaLeaseProvider` | Cloud-coordinated leases via Axia API |
|
|
30
|
+
| `HybridLeaseProvider` | Local-first with Axia sync fallback |
|
|
31
|
+
| `PersonalLeaseNodeProvider` | Coordinates through your personal lookup node *(ready for implementation)* |
|
|
32
|
+
| `P2PQuorumLeaseProvider` | Multi-device quorum consensus *(stub)* |
|
|
33
|
+
| `OnchainWatermarkProvider` | On-chain watermark anchoring *(stub)* |
|
|
34
|
+
|
|
35
|
+
### Device range splitting
|
|
36
|
+
|
|
37
|
+
```typescript
|
|
38
|
+
import { allocateDeviceRange } from '@totemsdk/wots-lease';
|
|
39
|
+
|
|
40
|
+
// Split 262,144 signing slots across 4 devices without overlap
|
|
41
|
+
const range = allocateDeviceRange({ deviceIndex: 0, totalDevices: 4 });
|
|
42
|
+
// { start: 0, end: 65535 }
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Error types
|
|
46
|
+
|
|
47
|
+
| Error | Meaning |
|
|
48
|
+
|-------|---------|
|
|
49
|
+
| `WatermarkMonotonicityError` | Attempted to use a slot at or before the current watermark |
|
|
50
|
+
| `WatermarkExhaustedError` | All 262,144 signing slots for this address have been used |
|
|
51
|
+
| `DeviceRangeViolationError` | Slot is outside this device's allocated range |
|
|
52
|
+
|
|
53
|
+
## Usage
|
|
54
|
+
|
|
55
|
+
### Local (single device)
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
import { LocalLeaseProvider, WotsWatermarkStore } from '@totemsdk/wots-lease';
|
|
59
|
+
|
|
60
|
+
const store = new WotsWatermarkStore(storageAdapter);
|
|
61
|
+
const provider = new LocalLeaseProvider(store);
|
|
62
|
+
|
|
63
|
+
// Allocate the next available signing slot
|
|
64
|
+
const slot = await provider.allocateSlot({ addressIndex: 0 });
|
|
65
|
+
console.log('Use flat slot:', slot.flatIndex); // e.g. 42
|
|
66
|
+
|
|
67
|
+
// After signing, commit the watermark
|
|
68
|
+
await provider.commitSlot(slot);
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### Hybrid (local + Axia cloud backup)
|
|
72
|
+
|
|
73
|
+
```typescript
|
|
74
|
+
import { HybridLeaseProvider } from '@totemsdk/wots-lease';
|
|
75
|
+
|
|
76
|
+
const provider = new HybridLeaseProvider({
|
|
77
|
+
local: new LocalLeaseProvider(store),
|
|
78
|
+
remote: new AxiaLeaseProvider({ baseUrl: 'https://api.axia.to', projectId: '...' }),
|
|
79
|
+
syncIntervalMs: 60_000,
|
|
80
|
+
});
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### Audit log
|
|
84
|
+
|
|
85
|
+
```typescript
|
|
86
|
+
import { LeaseJournal } from '@totemsdk/wots-lease';
|
|
87
|
+
|
|
88
|
+
const journal = new LeaseJournal(storageAdapter);
|
|
89
|
+
const entries = await journal.getEntries({ addressIndex: 0 });
|
|
90
|
+
entries.forEach(e => console.log(e.flatIndex, e.allocatedAt, e.committedAt));
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## See also
|
|
94
|
+
|
|
95
|
+
- [`@totemsdk/core`](../core) — WOTS primitives this package protects
|
|
96
|
+
- [`@totemsdk/lookup-node`](../lookup-node) — `LeaseCoordinator` for multi-client setups
|
|
97
|
+
- [`@totemsdk/omnia`](../omnia) — integrates wots-lease to protect channel signing slots
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@totemsdk/wots-lease",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "WOTS key-use coordination — canonical v3 watermark, provider-based lease safety layers",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -11,18 +11,13 @@
|
|
|
11
11
|
"import": "./dist/index.js"
|
|
12
12
|
}
|
|
13
13
|
},
|
|
14
|
-
"scripts": {
|
|
15
|
-
"build": "tsc",
|
|
16
|
-
"clean": "rm -rf dist",
|
|
17
|
-
"test": "jest --passWithNoTests"
|
|
18
|
-
},
|
|
19
14
|
"files": [
|
|
20
15
|
"dist",
|
|
21
16
|
"src"
|
|
22
17
|
],
|
|
23
18
|
"dependencies": {
|
|
24
|
-
"@totemsdk/core": "
|
|
25
|
-
"@totemsdk/lookup-protocol": "
|
|
19
|
+
"@totemsdk/core": "1.0.9",
|
|
20
|
+
"@totemsdk/lookup-protocol": "0.1.2"
|
|
26
21
|
},
|
|
27
22
|
"devDependencies": {
|
|
28
23
|
"@noble/hashes": "^1.3.0",
|
|
@@ -38,5 +33,10 @@
|
|
|
38
33
|
"publishConfig": {
|
|
39
34
|
"access": "public"
|
|
40
35
|
},
|
|
41
|
-
"license": "MIT"
|
|
42
|
-
|
|
36
|
+
"license": "MIT",
|
|
37
|
+
"scripts": {
|
|
38
|
+
"build": "tsc",
|
|
39
|
+
"clean": "rm -rf dist",
|
|
40
|
+
"test": "jest --passWithNoTests"
|
|
41
|
+
}
|
|
42
|
+
}
|