@neuraiproject/neurai-sign-esp32 0.4.0 → 0.5.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/README.md +162 -20
- package/dist/NeuraiSignESP32.global.js +649 -73
- package/dist/browser.js +630 -74
- package/dist/index.cjs +649 -73
- package/dist/index.d.ts +319 -14
- package/dist/index.js +630 -74
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Create and sign Neurai (XNA) and asset transactions via ESP32 hardware wallet.
|
|
4
4
|
|
|
5
|
-
This library handles the full PSBT workflow against
|
|
5
|
+
This library handles the full PSBT workflow against an ESP32 hardware wallet:
|
|
6
6
|
build an unsigned PSBT, send it over USB Serial for signing, receive
|
|
7
7
|
the signed PSBT back, finalize it, and extract the raw transaction hex
|
|
8
8
|
ready for broadcast.
|
|
@@ -10,6 +10,11 @@ ready for broadcast.
|
|
|
10
10
|
Uses [bitcoinjs-lib](https://www.npmjs.com/package/bitcoinjs-lib) v7 for
|
|
11
11
|
PSBT construction and the Web Serial API for device communication.
|
|
12
12
|
|
|
13
|
+
It also supports **Post-Quantum (ML-DSA-44 / AuthScript) addresses**: sending to
|
|
14
|
+
PQ addresses (`nq1…`/`tnq1…`) and spending from them. The library auto-detects
|
|
15
|
+
the device mode from `info` and routes accordingly — see
|
|
16
|
+
[Post-Quantum support](#post-quantum-pq--ml-dsa-44-support).
|
|
17
|
+
|
|
13
18
|
##
|
|
14
19
|
|
|
15
20
|
EXPERIMENTAL.
|
|
@@ -19,6 +24,7 @@ This library supports:
|
|
|
19
24
|
- Asset transfers
|
|
20
25
|
- BIP32 account discovery via `get_bip32_pubkey`
|
|
21
26
|
- Message signing (prove address ownership)
|
|
27
|
+
- **Post-Quantum addresses (ML-DSA-44 / AuthScript)** — send to and spend from `nq1…`/`tnq1…`
|
|
22
28
|
|
|
23
29
|
Asset transfers use the same PSBT signing flow as XNA transfers. The transaction
|
|
24
30
|
outputs are still signed from the raw unsigned transaction, while optional
|
|
@@ -196,6 +202,109 @@ console.log(bip32.master_fingerprint); // "a1b2c3d4"
|
|
|
196
202
|
console.log(bip32.path); // "m/44'/1900'/0'"
|
|
197
203
|
```
|
|
198
204
|
|
|
205
|
+
## Post-Quantum (PQ / ML-DSA-44) support
|
|
206
|
+
|
|
207
|
+
The device operates in one mode at a time, declared via `info` on two
|
|
208
|
+
orthogonal axes:
|
|
209
|
+
|
|
210
|
+
- **network**: `mainnet` / `testnet`
|
|
211
|
+
- **key_type**: `legacy` (ECDSA/secp256k1 P2PKH) / `pq` (ML-DSA-44 AuthScript)
|
|
212
|
+
|
|
213
|
+
The library reads `info.key_type` and routes automatically — the same
|
|
214
|
+
`getAddress()` / `signTransaction()` calls work in both modes. PQ uses the
|
|
215
|
+
AuthScript witness-v1 format (`nq1…` mainnet / `tnq1…` testnet), which cannot be
|
|
216
|
+
represented in a PSBT, so spending from PQ uses a raw-transaction transport
|
|
217
|
+
(`sign_tx`) under the hood. See [`docs/pq-protocol-design.md`](./docs/pq-protocol-design.md).
|
|
218
|
+
|
|
219
|
+
> The device exposes **only the public key** of its single address; the library
|
|
220
|
+
> derives the `nq1…`/`tnq1…` address from that pubkey + mode.
|
|
221
|
+
|
|
222
|
+
### Read a PQ address
|
|
223
|
+
|
|
224
|
+
```javascript
|
|
225
|
+
const device = new NeuraiESP32();
|
|
226
|
+
await device.connect();
|
|
227
|
+
|
|
228
|
+
const info = await device.getInfo();
|
|
229
|
+
console.log(info.key_type); // "pq"
|
|
230
|
+
console.log(info.network); // "NeuraiTest"
|
|
231
|
+
|
|
232
|
+
// In PQ mode the device returns only the pubkey; the library derives the address.
|
|
233
|
+
const addr = await device.getAddress(); // requires confirmation on device
|
|
234
|
+
console.log(addr.type); // "pq"
|
|
235
|
+
console.log(addr.address); // "tnq1..."
|
|
236
|
+
console.log(addr.commitment); // 32-byte AuthScript commitment (hex)
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
### Send to a PQ address (from a legacy ECDSA wallet)
|
|
240
|
+
|
|
241
|
+
No special handling is needed: pass a `nq1…`/`tnq1…` destination to
|
|
242
|
+
`signTransaction`/`buildPSBT`. The library encodes the AuthScript output script
|
|
243
|
+
automatically; the ECDSA inputs are still signed via `sign_psbt`.
|
|
244
|
+
|
|
245
|
+
```javascript
|
|
246
|
+
const result = await device.signTransaction({
|
|
247
|
+
utxos: [/* legacy P2PKH UTXOs with rawTxHex */],
|
|
248
|
+
outputs: [{ address: "tnq1...", value: 100000000 }], // PQ destination
|
|
249
|
+
changeAddress: address,
|
|
250
|
+
});
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
### Spend from a PQ address
|
|
254
|
+
|
|
255
|
+
When the device is in PQ mode, `signTransaction` routes to the PQ path
|
|
256
|
+
(`signPqTransaction`): it builds an unsigned raw transaction, sends it with
|
|
257
|
+
per-input metadata via `sign_tx`, and returns the fully-signed transaction.
|
|
258
|
+
Change defaults to the device's own single address.
|
|
259
|
+
|
|
260
|
+
```javascript
|
|
261
|
+
const result = await device.signTransaction({
|
|
262
|
+
utxos: [
|
|
263
|
+
{
|
|
264
|
+
txid: "abcd1234....",
|
|
265
|
+
vout: 0,
|
|
266
|
+
satoshis: 100000000,
|
|
267
|
+
scriptPubKey: "5120<32-byte commitment>", // the PQ address script
|
|
268
|
+
type: "pq",
|
|
269
|
+
// sighashAmount: 0, // use 0 for asset-wrapped inputs
|
|
270
|
+
},
|
|
271
|
+
],
|
|
272
|
+
outputs: [{ address: "tnq1...", value: 50000000 }],
|
|
273
|
+
// changeAddress defaults to the device's PQ address
|
|
274
|
+
});
|
|
275
|
+
|
|
276
|
+
console.log(result.txHex); // signed raw tx, ready to broadcast via the node RPC
|
|
277
|
+
console.log(result.txId);
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
### Verify a device signature (optional)
|
|
281
|
+
|
|
282
|
+
You can independently verify the ML-DSA-44 signature the device produced by
|
|
283
|
+
recomputing the AuthScript sighash and checking it against the pubkey (using
|
|
284
|
+
`@noble/post-quantum`, which is not a runtime dependency of this library):
|
|
285
|
+
|
|
286
|
+
```javascript
|
|
287
|
+
import {
|
|
288
|
+
extractPQWitness,
|
|
289
|
+
pqAuthScriptSighash,
|
|
290
|
+
} from "@neuraiproject/neurai-sign-esp32";
|
|
291
|
+
import { ml_dsa44 } from "@noble/post-quantum/ml-dsa.js";
|
|
292
|
+
|
|
293
|
+
const w = extractPQWitness(result.txHex, 0);
|
|
294
|
+
const sighash = pqAuthScriptSighash({
|
|
295
|
+
tx: result.txHex,
|
|
296
|
+
inputIndex: 0,
|
|
297
|
+
amount: 100000000, // the prevout amount used for that input
|
|
298
|
+
witnessScript: "51", // OP_TRUE (phase 1)
|
|
299
|
+
authType: 1,
|
|
300
|
+
});
|
|
301
|
+
const ok = ml_dsa44.verify(w.signature, sighash, w.pubkey); // verify(sig, msg, pub)
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
[`examples/browser-test.html`](./examples/browser-test.html) demonstrates this
|
|
305
|
+
full flow end-to-end (read PQ address → sign a test transaction → verify the
|
|
306
|
+
ML-DSA-44 signature).
|
|
307
|
+
|
|
199
308
|
### Check Web Serial API support
|
|
200
309
|
|
|
201
310
|
```javascript
|
|
@@ -208,17 +317,25 @@ if (!NeuraiESP32.isSupported()) {
|
|
|
208
317
|
|
|
209
318
|
## Manual browser smoke test
|
|
210
319
|
|
|
211
|
-
There is a
|
|
212
|
-
[`examples/browser-
|
|
213
|
-
|
|
320
|
+
There is a browser demo at
|
|
321
|
+
[`examples/browser-test.html`](./examples/browser-test.html) that imports the
|
|
322
|
+
generated browser ESM bundle from `dist/browser.js`. It reads a PQ address from
|
|
323
|
+
the device and (in PQ mode) signs a test transaction and verifies the ML-DSA-44
|
|
324
|
+
signature.
|
|
214
325
|
|
|
215
326
|
Suggested flow:
|
|
216
327
|
|
|
217
328
|
1. Run `npm run build`.
|
|
218
|
-
2. Serve the repository root over HTTP
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
329
|
+
2. Serve the **repository root** over HTTP (so `dist/` is reachable), for example
|
|
330
|
+
`npx serve .` or `python3 -m http.server 8000`.
|
|
331
|
+
3. Open `http://localhost:8000/examples/browser-test.html` in Chrome or Edge.
|
|
332
|
+
4. Click `Conectar`, pick the port, and confirm on the device. The page shows the
|
|
333
|
+
derived `tnq1…` address.
|
|
334
|
+
5. Click `Firmar transacción de prueba` and confirm on the device. The page signs
|
|
335
|
+
a fictitious transaction and shows `✓ Firma ML-DSA-44 VÁLIDA`.
|
|
336
|
+
|
|
337
|
+
> Serve from the repo root — serving only `examples/` leaves `../dist/browser.js`
|
|
338
|
+
> unreachable and the page cannot load the library.
|
|
222
339
|
|
|
223
340
|
## Build outputs
|
|
224
341
|
|
|
@@ -242,14 +359,20 @@ const rawTxHex = await rpc("getrawtransaction", [txid]);
|
|
|
242
359
|
|
|
243
360
|
## Networks
|
|
244
361
|
|
|
245
|
-
|
|
362
|
+
The public model has two orthogonal axes: **network** (`mainnet`/`testnet`) and
|
|
363
|
+
**key_type** (`legacy`/`pq`). The device declares both via `info`. Internally
|
|
364
|
+
these resolve to a `NetworkType` identifier:
|
|
246
365
|
|
|
247
|
-
|
|
|
248
|
-
|
|
249
|
-
| `xna` | 1900 | N (
|
|
250
|
-
| `xna-test` | 1 | testnet |
|
|
251
|
-
| `xna-
|
|
252
|
-
| `xna-
|
|
366
|
+
| network | key_type | Internal `NetworkType` | Coin type | Address prefix |
|
|
367
|
+
|---|---|---|---|---|
|
|
368
|
+
| mainnet | legacy | `xna` | 1900 | `N…` (P2PKH) |
|
|
369
|
+
| testnet | legacy | `xna-test` | 1 | testnet P2PKH |
|
|
370
|
+
| mainnet | pq | `xna-pq` | 1900 | `nq1…` (AuthScript) |
|
|
371
|
+
| testnet | pq | `xna-pq-test` | 1 | `tnq1…` (AuthScript) |
|
|
372
|
+
|
|
373
|
+
`xna-legacy` / `xna-legacy-test` (coin type 0) remain available for the legacy
|
|
374
|
+
coin-type-0 derivation and are unrelated to `key_type: "legacy"`. Use
|
|
375
|
+
`resolveNetwork(network, keyType)` to map the two axes to a `NetworkType`.
|
|
253
376
|
|
|
254
377
|
## Chunked serial writes (important)
|
|
255
378
|
|
|
@@ -270,7 +393,7 @@ payloads) will fail silently or produce corrupted data on the device.
|
|
|
270
393
|
|
|
271
394
|
## Device protocol
|
|
272
395
|
|
|
273
|
-
The library communicates with
|
|
396
|
+
The library communicates with the ESP32 firmware over USB Serial (115200 baud)
|
|
274
397
|
using JSON messages. Supported commands:
|
|
275
398
|
|
|
276
399
|
| Command | Confirmation | Timeout |
|
|
@@ -279,8 +402,13 @@ using JSON messages. Supported commands:
|
|
|
279
402
|
| `get_address` | Physical button | 30s |
|
|
280
403
|
| `get_bip32_pubkey` | Physical button | 30s |
|
|
281
404
|
| `sign_psbt` | Physical button + TX review | 60s |
|
|
405
|
+
| `sign_tx` (PQ) | Physical button + TX review | per-heartbeat (ML-DSA is slow) |
|
|
282
406
|
| `sign_message` | Physical button | 30s |
|
|
283
407
|
|
|
408
|
+
`info` reports `key_type` (`"legacy"` | `"pq"`). In PQ mode, `get_address`
|
|
409
|
+
returns only the public key (the library derives the address) and signing uses
|
|
410
|
+
`sign_tx` (raw transaction) instead of `sign_psbt`.
|
|
411
|
+
|
|
284
412
|
## API
|
|
285
413
|
|
|
286
414
|
### `NeuraiESP32`
|
|
@@ -291,13 +419,27 @@ Main class for device interaction.
|
|
|
291
419
|
|---|---|
|
|
292
420
|
| `connect()` | Open USB Serial connection (browser dialog) |
|
|
293
421
|
| `disconnect()` | Close connection |
|
|
294
|
-
| `getInfo()` | Get device info (no confirmation) |
|
|
295
|
-
| `getAddress()` | Get address + pubkey (requires confirmation) |
|
|
422
|
+
| `getInfo()` | Get device info incl. `key_type` (no confirmation) |
|
|
423
|
+
| `getAddress()` | Get address + pubkey (requires confirmation); derives the address from the pubkey + mode (legacy or PQ) |
|
|
296
424
|
| `getBip32Pubkey()` | Get account xpub (requires confirmation) |
|
|
297
425
|
| `signPsbt(base64)` | Sign a PSBT (requires confirmation) |
|
|
298
426
|
| `signPsbt(base64, display?)` | Sign a PSBT and optionally send display metadata |
|
|
299
427
|
| `signMessage(message)` | Sign a message to prove address ownership (requires confirmation) |
|
|
300
|
-
| `signTransaction(opts)` | Build + sign + finalize in one call |
|
|
428
|
+
| `signTransaction(opts)` | Build + sign + finalize in one call; auto-routes legacy (PSBT) vs PQ (`sign_tx`) by device mode |
|
|
429
|
+
| `signPqTransaction(opts)` | Spend from a PQ address: build raw tx + sign via `sign_tx` (used internally by `signTransaction` in PQ mode) |
|
|
430
|
+
|
|
431
|
+
### Post-Quantum helpers
|
|
432
|
+
|
|
433
|
+
| Function | Description |
|
|
434
|
+
|---|---|
|
|
435
|
+
| `isPQAddress(addr)` | True for `nq1…`/`tnq1…` AuthScript addresses |
|
|
436
|
+
| `decodeAddress(addr)` | Decode a legacy or PQ address (`{ type, commitment \| hash, … }`) |
|
|
437
|
+
| `encodeDestinationScript(addr)` | Output scriptPubKey for any supported address |
|
|
438
|
+
| `publicKeyToAddress(pubkeyHex, { network, keyType })` | Derive an address from a public key + mode |
|
|
439
|
+
| `resolveNetwork(network, keyType)` | Map the two axes to a `NetworkType` |
|
|
440
|
+
| `buildUnsignedPQTransaction(opts)` | Build the unsigned raw tx + per-input metadata for `sign_tx` |
|
|
441
|
+
| `extractPQWitness(signedTxHex, index?)` | Decode the AuthScript witness (`authType`, `signature`, `pubkey`, `witnessScript`) |
|
|
442
|
+
| `pqAuthScriptSighash(opts)` | Recompute the AuthScript sighash (to verify device signatures) |
|
|
301
443
|
|
|
302
444
|
### `buildPSBT(options)`
|
|
303
445
|
|
|
@@ -315,7 +457,7 @@ Finalize a signed PSBT. Returns `{ txHex, txId }`.
|
|
|
315
457
|
|
|
316
458
|
### `finalizeSignedPSBT(originalPsbtBase64, signedPsbtBase64, network)`
|
|
317
459
|
|
|
318
|
-
Merge a signed PSBT returned by
|
|
460
|
+
Merge a signed PSBT returned by the device with the original PSBT and finalize it.
|
|
319
461
|
This helper also supports the minimal PSBT format returned by `uNeurai`, and
|
|
320
462
|
includes fallback logic for legacy P2PKH finalization used by Neurai.
|
|
321
463
|
|