@neuraiproject/neurai-sign-esp32 0.3.2 → 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 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 a NeuraiHW device:
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
@@ -31,6 +37,21 @@ asset name, transferred amount, destination address, and fee more clearly.
31
37
  npm i @neuraiproject/neurai-sign-esp32
32
38
  ```
33
39
 
40
+ For browser-specific consumption you can also import the explicit browser entry:
41
+
42
+ ```javascript
43
+ import { NeuraiESP32 } from "@neuraiproject/neurai-sign-esp32/browser";
44
+ ```
45
+
46
+ For classic HTML pages without ESM imports, load the global bundle:
47
+
48
+ ```html
49
+ <script src="./dist/NeuraiSignESP32.global.js"></script>
50
+ <script>
51
+ const device = new window.NeuraiSignESP32.NeuraiESP32();
52
+ </script>
53
+ ```
54
+
34
55
  ## How to use
35
56
 
36
57
  ### Full transaction flow
@@ -181,6 +202,109 @@ console.log(bip32.master_fingerprint); // "a1b2c3d4"
181
202
  console.log(bip32.path); // "m/44'/1900'/0'"
182
203
  ```
183
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
+
184
308
  ### Check Web Serial API support
185
309
 
186
310
  ```javascript
@@ -191,6 +315,38 @@ if (!NeuraiESP32.isSupported()) {
191
315
  }
192
316
  ```
193
317
 
318
+ ## Manual browser smoke test
319
+
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.
325
+
326
+ Suggested flow:
327
+
328
+ 1. Run `npm run build`.
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.
339
+
340
+ ## Build outputs
341
+
342
+ After `npm run build`, the package publishes:
343
+
344
+ - `dist/index.js`: primary ESM entry
345
+ - `dist/index.cjs`: CommonJS entry
346
+ - `dist/browser.js`: explicit browser ESM entry
347
+ - `dist/NeuraiSignESP32.global.js`: IIFE bundle exposing `globalThis.NeuraiSignESP32`
348
+ - `dist/index.d.ts`: public types
349
+
194
350
  ## UTXO requirements
195
351
 
196
352
  Each UTXO requires the `rawTxHex` field — the full raw hex of the previous
@@ -203,14 +359,20 @@ const rawTxHex = await rpc("getrawtransaction", [txid]);
203
359
 
204
360
  ## Networks
205
361
 
206
- Supported network types:
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:
207
365
 
208
- | Network | Coin type | Address prefix |
209
- |---|---|---|
210
- | `xna` | 1900 | N (mainnet, recommended) |
211
- | `xna-test` | 1 | testnet |
212
- | `xna-legacy` | 0 | N (legacy mainnet) |
213
- | `xna-legacy-test` | 1 | testnet legacy |
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`.
214
376
 
215
377
  ## Chunked serial writes (important)
216
378
 
@@ -220,8 +382,7 @@ firmware's `Serial.read()` loop cannot drain the buffer fast enough if the
220
382
  host flushes several kilobytes at once.
221
383
 
222
384
  This library works around the problem by splitting every outgoing message into
223
- **32-byte chunks** with a **4 ms pause** between each one. This matches the
224
- approach used in the reference web wallet (`NeuraiHWSerial.writeChunked`).
385
+ **256-byte chunks** with a **8 ms pause** between each one.
225
386
 
226
387
  The newline terminator (`\n`) is sent separately after all chunks, so the
227
388
  firmware only processes the command once the full JSON has arrived.
@@ -232,7 +393,7 @@ payloads) will fail silently or produce corrupted data on the device.
232
393
 
233
394
  ## Device protocol
234
395
 
235
- The library communicates with NeuraiHW firmware over USB Serial (115200 baud)
396
+ The library communicates with the ESP32 firmware over USB Serial (115200 baud)
236
397
  using JSON messages. Supported commands:
237
398
 
238
399
  | Command | Confirmation | Timeout |
@@ -241,8 +402,13 @@ using JSON messages. Supported commands:
241
402
  | `get_address` | Physical button | 30s |
242
403
  | `get_bip32_pubkey` | Physical button | 30s |
243
404
  | `sign_psbt` | Physical button + TX review | 60s |
405
+ | `sign_tx` (PQ) | Physical button + TX review | per-heartbeat (ML-DSA is slow) |
244
406
  | `sign_message` | Physical button | 30s |
245
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
+
246
412
  ## API
247
413
 
248
414
  ### `NeuraiESP32`
@@ -253,13 +419,27 @@ Main class for device interaction.
253
419
  |---|---|
254
420
  | `connect()` | Open USB Serial connection (browser dialog) |
255
421
  | `disconnect()` | Close connection |
256
- | `getInfo()` | Get device info (no confirmation) |
257
- | `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) |
258
424
  | `getBip32Pubkey()` | Get account xpub (requires confirmation) |
259
425
  | `signPsbt(base64)` | Sign a PSBT (requires confirmation) |
260
426
  | `signPsbt(base64, display?)` | Sign a PSBT and optionally send display metadata |
261
427
  | `signMessage(message)` | Sign a message to prove address ownership (requires confirmation) |
262
- | `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) |
263
443
 
264
444
  ### `buildPSBT(options)`
265
445
 
@@ -277,7 +457,7 @@ Finalize a signed PSBT. Returns `{ txHex, txId }`.
277
457
 
278
458
  ### `finalizeSignedPSBT(originalPsbtBase64, signedPsbtBase64, network)`
279
459
 
280
- Merge a signed PSBT returned by NeuraiHW with the original PSBT and finalize it.
460
+ Merge a signed PSBT returned by the device with the original PSBT and finalize it.
281
461
  This helper also supports the minimal PSBT format returned by `uNeurai`, and
282
462
  includes fallback logic for legacy P2PKH finalization used by Neurai.
283
463