@tari-project/ootle-secret-key-wallet 0.1.0
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 +29 -0
- package/README.md +73 -0
- package/dist/index.d.ts +125 -0
- package/dist/index.js +633 -0
- package/package.json +38 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
BSD 3-Clause License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2023, The Tari Developer Community
|
|
4
|
+
All rights reserved.
|
|
5
|
+
|
|
6
|
+
Redistribution and use in source and binary forms, with or without
|
|
7
|
+
modification, are permitted provided that the following conditions are met:
|
|
8
|
+
|
|
9
|
+
1. Redistributions of source code must retain the above copyright notice, this
|
|
10
|
+
list of conditions and the following disclaimer.
|
|
11
|
+
|
|
12
|
+
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
13
|
+
this list of conditions and the following disclaimer in the documentation
|
|
14
|
+
and/or other materials provided with the distribution.
|
|
15
|
+
|
|
16
|
+
3. Neither the name of the copyright holder nor the names of its
|
|
17
|
+
contributors may be used to endorse or promote products derived from
|
|
18
|
+
this software without specific prior written permission.
|
|
19
|
+
|
|
20
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
21
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
22
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
23
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
24
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
25
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
26
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
27
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
28
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
29
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
package/README.md
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# @tari-project/ootle-secret-key-wallet
|
|
2
|
+
|
|
3
|
+
Local in-memory `Signer` for the Tari Ootle SDK, backed by WASM crypto.
|
|
4
|
+
**Testing / scripting use only** — the secret key lives unencrypted in JS
|
|
5
|
+
memory. For production, prefer
|
|
6
|
+
[`@tari-project/ootle-wallet-daemon-signer`](../ootle-wallet-daemon-signer/README.md)
|
|
7
|
+
so the key never enters JavaScript.
|
|
8
|
+
|
|
9
|
+
## Runtime support
|
|
10
|
+
|
|
11
|
+
| Package | Browser | Node ≥ 22 | Notes |
|
|
12
|
+
| --------------------------------------- | ------- | --------- | ----------------------------------------------------- |
|
|
13
|
+
| `@tari-project/ootle-secret-key-wallet` | ✓ | ✓ | Stealth scan/spend needs `randomWithViewKey(network)` |
|
|
14
|
+
|
|
15
|
+
> **Node note:** Node ≥ 22 currently requires
|
|
16
|
+
> `NODE_OPTIONS=--experimental-wasm-modules` when running under `tsx` or plain
|
|
17
|
+
> `node` because this package loads `@tari-project/ootle-wasm` as an ES module.
|
|
18
|
+
> See [`examples/node/README.md`](../../examples/node/README.md) for the
|
|
19
|
+
> rationale and forward plan; every script in `examples/node/` wires the flag
|
|
20
|
+
> into its `pnpm` invocation.
|
|
21
|
+
|
|
22
|
+
> **Stealth note:** Client-side stealth scan / spend requires a `SecretKeyWallet`
|
|
23
|
+
> created with a view key — use `SecretKeyWallet.randomWithViewKey(network)` or
|
|
24
|
+
> `SecretKeyWallet.fromSecretKey(ownerKey, network, viewOnlyKey)`. The stealth
|
|
25
|
+
> API in `@tari-project/ootle` (`decryptOwnedUtxo`, `WalletStealthAuthorizer`)
|
|
26
|
+
> will throw if the wallet was created without a view key. See the canonical
|
|
27
|
+
> usage in [`examples/node/`](../../examples/node/README.md) — the stealth
|
|
28
|
+
> scripts (`stealth:faucet-deposit`, `stealth:to-revealed`, `stealth:to-stealth`,
|
|
29
|
+
> `stealth:spend`) all build their wallets via
|
|
30
|
+
> `SecretKeyWallet.randomWithViewKey(Network.LocalNet)`.
|
|
31
|
+
|
|
32
|
+
## Install
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
pnpm add @tari-project/ootle-secret-key-wallet
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Hello world
|
|
39
|
+
|
|
40
|
+
Generate a fresh wallet with a view-only key and sign a transaction:
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
import { Network } from "@tari-project/ootle";
|
|
44
|
+
import { SecretKeyWallet } from "@tari-project/ootle-secret-key-wallet";
|
|
45
|
+
|
|
46
|
+
// Generate a random wallet with a view-only key (needed for stealth scan/spend).
|
|
47
|
+
const wallet = SecretKeyWallet.randomWithViewKey(Network.LocalNet);
|
|
48
|
+
|
|
49
|
+
console.log(await wallet.getAddress());
|
|
50
|
+
|
|
51
|
+
// Sign a previously-built unsigned transaction:
|
|
52
|
+
const signatures = await wallet.signTransaction(unsignedTx);
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
For a fully-typed account-key restore (no view key needed) use
|
|
56
|
+
`SecretKeyWallet.fromSecretKey(ownerSecretKey, network)`; pair it with a
|
|
57
|
+
`viewOnlySecretKey` to enable stealth.
|
|
58
|
+
|
|
59
|
+
## Deep dive
|
|
60
|
+
|
|
61
|
+
For the `SecretKeyWallet` factory matrix
|
|
62
|
+
(`randomWithViewKey` / `fromSecretKey` / `fromKeypair`) and the
|
|
63
|
+
`EphemeralKeySigner` (one-shot throwaway keys), see the
|
|
64
|
+
[root README's "`@tari-project/ootle-secret-key-wallet`" section](../../README.md#tari-projectootle-secret-key-wallet).
|
|
65
|
+
|
|
66
|
+
## Examples
|
|
67
|
+
|
|
68
|
+
Runnable browser apps and Node scripts live under
|
|
69
|
+
[`examples/`](../../examples/README.md). The
|
|
70
|
+
[`stealth-wallet/`](../../examples/stealth-wallet/) React app and the stealth
|
|
71
|
+
script set under
|
|
72
|
+
[`examples/node/src/stealth/`](../../examples/node/src/stealth/) are the
|
|
73
|
+
canonical references for using this signer with the stealth API.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
import { Network } from '@tari-project/ootle';
|
|
2
|
+
import { Signer } from '@tari-project/ootle';
|
|
3
|
+
import { TransactionSignature } from '@tari-project/ootle-ts-bindings';
|
|
4
|
+
import { UnsignedTransactionV1 } from '@tari-project/ootle-ts-bindings';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* The injected-crypto argument of {@link Signer.addStealthSignature}, derived from the
|
|
8
|
+
* interface so this package never imports the internal `stealth/` module directly.
|
|
9
|
+
*/
|
|
10
|
+
declare type AddStealthSignatureCtx = Parameters<NonNullable<Signer["addStealthSignature"]>>[3];
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* A one-shot signer that generates a fresh throwaway keypair, signs once,
|
|
14
|
+
* and exposes no way to reuse the key. Used for privacy-preserving transactions
|
|
15
|
+
* where the sender wants no link between the transaction and their identity.
|
|
16
|
+
*
|
|
17
|
+
* **No stealth spending support by design.** This signer holds no view key, so it
|
|
18
|
+
* deliberately does **not** implement the optional `Signer.getViewSecret`/
|
|
19
|
+
* `Signer.addStealthSignature` members. Stealth scanning and one-time spend-key signing
|
|
20
|
+
* require a view secret + owner secret pair — use {@link SecretKeyWallet} for that.
|
|
21
|
+
*
|
|
22
|
+
* @example
|
|
23
|
+
* ```ts
|
|
24
|
+
* const signer = EphemeralKeySigner.generate();
|
|
25
|
+
* const signed = await signTransaction([signer], unsignedTx);
|
|
26
|
+
* ```
|
|
27
|
+
*/
|
|
28
|
+
export declare class EphemeralKeySigner implements Signer {
|
|
29
|
+
private readonly secretKey;
|
|
30
|
+
private readonly publicKey;
|
|
31
|
+
readonly address: string;
|
|
32
|
+
private constructor();
|
|
33
|
+
/**
|
|
34
|
+
* Generates a fresh ephemeral keypair. The secret key exists only for the
|
|
35
|
+
* lifetime of this object and is never persisted.
|
|
36
|
+
*
|
|
37
|
+
* The WASM `generateKeypair` already returns 32-byte halves; the explicit
|
|
38
|
+
* assertion is defence-in-depth so an upstream WASM regression surfaces here
|
|
39
|
+
* rather than silently mis-signing further down the line.
|
|
40
|
+
*/
|
|
41
|
+
static generate(network?: Network): EphemeralKeySigner;
|
|
42
|
+
getAddress(): Promise<string>;
|
|
43
|
+
getPublicKey(): Promise<Uint8Array>;
|
|
44
|
+
signTransaction(unsignedTx: UnsignedTransactionV1, sealPublicKey: Uint8Array): Promise<TransactionSignature[]>;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* A local signer that holds a secret key (and optional view-only key) in memory,
|
|
49
|
+
* using the WASM module for transaction hashing and Schnorr signing.
|
|
50
|
+
*
|
|
51
|
+
* For production use, prefer `WalletDaemonSigner` so the secret key never lives
|
|
52
|
+
* in JavaScript memory.
|
|
53
|
+
*
|
|
54
|
+
* Prefer {@link SecretKeyWallet.getViewSecret} for view-secret access;
|
|
55
|
+
* {@link SecretKeyWallet.getViewOnlySecret} is retained for back-compat.
|
|
56
|
+
*/
|
|
57
|
+
export declare class SecretKeyWallet implements Signer {
|
|
58
|
+
private readonly ownerSecretKey;
|
|
59
|
+
private readonly ownerPublicKey;
|
|
60
|
+
private readonly viewOnlySecret;
|
|
61
|
+
private readonly viewOnlyPublicKey;
|
|
62
|
+
readonly network: Network;
|
|
63
|
+
private constructor();
|
|
64
|
+
/**
|
|
65
|
+
* Generates a fresh random account keypair and a separate random view-only key.
|
|
66
|
+
* The view-only key is used for stealth/confidential output scanning.
|
|
67
|
+
* Mirrors `OotleSecretKey { account_secret, view_only_secret }` from ootle-rs.
|
|
68
|
+
*/
|
|
69
|
+
static randomWithViewKey(network: Network): SecretKeyWallet;
|
|
70
|
+
/**
|
|
71
|
+
* Creates a wallet from an existing hex-encoded account secret key.
|
|
72
|
+
* The public key is derived via `wasm.derivePublicKey`.
|
|
73
|
+
*
|
|
74
|
+
* @throws {InvalidArgumentError} if `ownerSecretKey` (or `viewOnlySecret`, when
|
|
75
|
+
* supplied) is not exactly 32 bytes.
|
|
76
|
+
*/
|
|
77
|
+
static fromSecretKey(ownerSecretKey: Uint8Array, network: Network, viewOnlySecret?: Uint8Array): SecretKeyWallet;
|
|
78
|
+
/**
|
|
79
|
+
* Creates a wallet directly from a secret key and its corresponding public key.
|
|
80
|
+
* Use this overload if you already have both keys (e.g. from key storage).
|
|
81
|
+
*
|
|
82
|
+
* @throws {InvalidArgumentError} if `ownerSecretKey`, `ownerPublicKey`, or
|
|
83
|
+
* `viewOnlySecret` (when supplied) is not exactly 32 bytes.
|
|
84
|
+
*/
|
|
85
|
+
static fromKeypair(ownerSecretKey: Uint8Array, ownerPublicKey: Uint8Array, network: Network, viewOnlySecret?: Uint8Array): SecretKeyWallet;
|
|
86
|
+
/**
|
|
87
|
+
* @throws {WalletError} when the view-only key has not been set on this wallet.
|
|
88
|
+
*/
|
|
89
|
+
getAddress(): Promise<string>;
|
|
90
|
+
getPublicKey(): Promise<Uint8Array>;
|
|
91
|
+
/**
|
|
92
|
+
* Returns the view-only secret key, if one was set.
|
|
93
|
+
* Used for stealth/confidential output scanning.
|
|
94
|
+
*
|
|
95
|
+
* @deprecated Use {@link getViewSecret} instead. This method signals a missing
|
|
96
|
+
* view key via a `null` return; `getViewSecret` throws a `WalletError` with
|
|
97
|
+
* an actionable message.
|
|
98
|
+
*/
|
|
99
|
+
getViewOnlySecret(): Uint8Array | null;
|
|
100
|
+
/**
|
|
101
|
+
* Returns the view-only secret for stealth scanning/spending ({@link Signer.getViewSecret}).
|
|
102
|
+
*
|
|
103
|
+
* Intentionally duplicates {@link getViewOnlySecret} (the pre-existing synchronous public
|
|
104
|
+
* accessor): this async method conforms to the `Signer` interface, while the original is
|
|
105
|
+
* kept unchanged to avoid a breaking API change.
|
|
106
|
+
*
|
|
107
|
+
* @throws {WalletError} when no view-only secret is set on this wallet (e.g. a wallet
|
|
108
|
+
* built via {@link fromSecretKey}/{@link fromKeypair} without a view secret).
|
|
109
|
+
*/
|
|
110
|
+
getViewSecret(): Promise<Uint8Array>;
|
|
111
|
+
/**
|
|
112
|
+
* Produces a one-time spend-key signature for a stealth input ({@link Signer.addStealthSignature}).
|
|
113
|
+
*
|
|
114
|
+
* Derives the one-time spend scalar (`c + k`) for the owned stealth UTXO via
|
|
115
|
+
* `stealthDhSecret(network, ownerSecret, publicNonce)`, then signs via the WASM
|
|
116
|
+
* `addTransactionSigner` (same path as {@link signTransaction}).
|
|
117
|
+
*
|
|
118
|
+
* The returned {@link TransactionSignature} carries the one-time spend public key (not the
|
|
119
|
+
* wallet's owner public key) — it authorizes the specific stealth UTXO being spent.
|
|
120
|
+
*/
|
|
121
|
+
addStealthSignature(unsignedJson: string, publicNonce: Uint8Array, sealPublicKey: Uint8Array, ctx: AddStealthSignatureCtx): Promise<TransactionSignature>;
|
|
122
|
+
signTransaction(unsignedTx: UnsignedTransactionV1, sealPublicKey: Uint8Array): Promise<TransactionSignature[]>;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
export { }
|