@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 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.
@@ -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 { }