@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 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
@@ -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 minimal browser smoke harness at
212
- [`examples/browser-smoke.html`](/home/mark/src/AAA-experimento/neurai-sign-esp32/examples/browser-smoke.html)
213
- that imports the generated browser ESM bundle from `dist/browser.js`.
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, for example `python3 -m http.server 8000`.
219
- 3. Open `http://localhost:8000/examples/browser-smoke.html` in Chrome or Edge.
220
- 4. Confirm the startup checks render in the page.
221
- 5. Click `Request Serial Port` and verify the port picker, `getInfo()` response and clean disconnect.
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
- 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:
246
365
 
247
- | Network | Coin type | Address prefix |
248
- |---|---|---|
249
- | `xna` | 1900 | N (mainnet, recommended) |
250
- | `xna-test` | 1 | testnet |
251
- | `xna-legacy` | 0 | N (legacy mainnet) |
252
- | `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`.
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 NeuraiHW firmware over USB Serial (115200 baud)
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 NeuraiHW with the original PSBT and finalize it.
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