@neuraiproject/neurai-sign-esp32 0.4.0 → 0.5.5
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 +244 -23
- package/dist/NeuraiSignESP32.global.js +839 -215
- package/dist/browser.js +820 -216
- package/dist/index.cjs +841 -215
- package/dist/index.d.ts +449 -28
- package/dist/index.js +820 -216
- package/dist/react-native.d.ts +787 -0
- package/dist/react-native.js +13354 -0
- package/package.json +8 -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,99 @@ 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.
|
|
339
|
+
|
|
340
|
+
## React Native / Android USB
|
|
341
|
+
|
|
342
|
+
The same library drives a NeuraiHW device from a React Native app over USB-C on
|
|
343
|
+
**Android** (iOS does not expose generic USB serial to apps). The device class
|
|
344
|
+
talks to a small transport interface, so the only platform-specific part is
|
|
345
|
+
moving raw bytes — all protocol logic (the 256-byte / 8 ms chunked writes, line
|
|
346
|
+
buffering, JSON parsing, timeouts) is shared.
|
|
347
|
+
|
|
348
|
+
The package does **not** depend on any native USB module. You adapt your chosen
|
|
349
|
+
module (e.g. `react-native-usb-serialport-for-android`, `react-native-serialport`,
|
|
350
|
+
or your own TurboModule) to the tiny `IUsbSerialDriver` interface and pass it in.
|
|
351
|
+
|
|
352
|
+
```ts
|
|
353
|
+
import {
|
|
354
|
+
createNeuraiESP32OverUsb,
|
|
355
|
+
bytesToBase64,
|
|
356
|
+
base64ToBytes,
|
|
357
|
+
type IUsbSerialDriver,
|
|
358
|
+
} from "@neuraiproject/neurai-sign-esp32/react-native";
|
|
359
|
+
|
|
360
|
+
// Adapt your native module here. This sketch assumes a module that exchanges
|
|
361
|
+
// data as base64 strings (the common case on Android).
|
|
362
|
+
const usbDriver: IUsbSerialDriver = {
|
|
363
|
+
async open({ baudRate }) {
|
|
364
|
+
const native = await MyUsbModule.open({ baudRate }); // your module
|
|
365
|
+
return {
|
|
366
|
+
write: (data) => native.send(bytesToBase64(data)),
|
|
367
|
+
onReceive: (handler) => {
|
|
368
|
+
const sub = native.onData((b64: string) => handler(base64ToBytes(b64)));
|
|
369
|
+
return { remove: () => sub.remove() };
|
|
370
|
+
},
|
|
371
|
+
close: () => native.close(),
|
|
372
|
+
};
|
|
373
|
+
},
|
|
374
|
+
};
|
|
375
|
+
|
|
376
|
+
const device = createNeuraiESP32OverUsb(usbDriver);
|
|
377
|
+
await device.connect();
|
|
378
|
+
const info = await device.getInfo();
|
|
379
|
+
const { address } = await device.getAddress(); // user confirms on the device
|
|
380
|
+
const result = await device.signTransaction({ utxos, outputs, changeAddress: address });
|
|
381
|
+
console.log(result.txHex);
|
|
382
|
+
await device.disconnect();
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
From here the API is identical to the browser flow (`getInfo`, `getAddress`,
|
|
386
|
+
`signTransaction`, `signMessage`, `getBip32Pubkey`, PQ support…).
|
|
387
|
+
|
|
388
|
+
### Building a custom transport
|
|
389
|
+
|
|
390
|
+
`createNeuraiESP32OverUsb` is sugar over the same building blocks the Web Serial
|
|
391
|
+
transport uses. To target any other platform, implement `IByteChannel` (four
|
|
392
|
+
methods: `isOpen`, `onData`, `open`, `write`, `close`) and wrap it in a
|
|
393
|
+
`SerialProtocol`:
|
|
394
|
+
|
|
395
|
+
```ts
|
|
396
|
+
import { NeuraiESP32, SerialProtocol, type IByteChannel } from "@neuraiproject/neurai-sign-esp32";
|
|
397
|
+
|
|
398
|
+
class MyByteChannel implements IByteChannel { /* … */ }
|
|
399
|
+
|
|
400
|
+
const device = new NeuraiESP32({ transport: new SerialProtocol(new MyByteChannel()) });
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
You do **not** need to replicate the chunked-write workaround in your channel —
|
|
404
|
+
`SerialProtocol` handles it for every transport.
|
|
405
|
+
|
|
406
|
+
### Android setup notes
|
|
407
|
+
|
|
408
|
+
- Add `<uses-feature android:name="android.hardware.usb.host" />` to the app
|
|
409
|
+
manifest, and request runtime USB permission for the device.
|
|
410
|
+
- The ESP32-S3 enumerates with USB vendor id `0x303a` (and CDC bridges such as
|
|
411
|
+
`0x10c4`, `0x1a86`, `0x0403`, `0x067b` for other boards).
|
|
412
|
+
- Open the port at **115200** baud, 8-N-1.
|
|
222
413
|
|
|
223
414
|
## Build outputs
|
|
224
415
|
|
|
@@ -227,8 +418,9 @@ After `npm run build`, the package publishes:
|
|
|
227
418
|
- `dist/index.js`: primary ESM entry
|
|
228
419
|
- `dist/index.cjs`: CommonJS entry
|
|
229
420
|
- `dist/browser.js`: explicit browser ESM entry
|
|
421
|
+
- `dist/react-native.js`: React Native entry (no Web Serial; adds the USB transport)
|
|
230
422
|
- `dist/NeuraiSignESP32.global.js`: IIFE bundle exposing `globalThis.NeuraiSignESP32`
|
|
231
|
-
- `dist/index.d.ts`: public types
|
|
423
|
+
- `dist/index.d.ts` / `dist/react-native.d.ts`: public types
|
|
232
424
|
|
|
233
425
|
## UTXO requirements
|
|
234
426
|
|
|
@@ -242,14 +434,20 @@ const rawTxHex = await rpc("getrawtransaction", [txid]);
|
|
|
242
434
|
|
|
243
435
|
## Networks
|
|
244
436
|
|
|
245
|
-
|
|
437
|
+
The public model has two orthogonal axes: **network** (`mainnet`/`testnet`) and
|
|
438
|
+
**key_type** (`legacy`/`pq`). The device declares both via `info`. Internally
|
|
439
|
+
these resolve to a `NetworkType` identifier:
|
|
246
440
|
|
|
247
|
-
|
|
|
248
|
-
|
|
249
|
-
| `xna` | 1900 | N (
|
|
250
|
-
| `xna-test` | 1 | testnet |
|
|
251
|
-
| `xna-
|
|
252
|
-
| `xna-
|
|
441
|
+
| network | key_type | Internal `NetworkType` | Coin type | Address prefix |
|
|
442
|
+
|---|---|---|---|---|
|
|
443
|
+
| mainnet | legacy | `xna` | 1900 | `N…` (P2PKH) |
|
|
444
|
+
| testnet | legacy | `xna-test` | 1 | testnet P2PKH |
|
|
445
|
+
| mainnet | pq | `xna-pq` | 1900 | `nq1…` (AuthScript) |
|
|
446
|
+
| testnet | pq | `xna-pq-test` | 1 | `tnq1…` (AuthScript) |
|
|
447
|
+
|
|
448
|
+
`xna-legacy` / `xna-legacy-test` (coin type 0) remain available for the legacy
|
|
449
|
+
coin-type-0 derivation and are unrelated to `key_type: "legacy"`. Use
|
|
450
|
+
`resolveNetwork(network, keyType)` to map the two axes to a `NetworkType`.
|
|
253
451
|
|
|
254
452
|
## Chunked serial writes (important)
|
|
255
453
|
|
|
@@ -270,7 +468,7 @@ payloads) will fail silently or produce corrupted data on the device.
|
|
|
270
468
|
|
|
271
469
|
## Device protocol
|
|
272
470
|
|
|
273
|
-
The library communicates with
|
|
471
|
+
The library communicates with the ESP32 firmware over USB Serial (115200 baud)
|
|
274
472
|
using JSON messages. Supported commands:
|
|
275
473
|
|
|
276
474
|
| Command | Confirmation | Timeout |
|
|
@@ -279,8 +477,13 @@ using JSON messages. Supported commands:
|
|
|
279
477
|
| `get_address` | Physical button | 30s |
|
|
280
478
|
| `get_bip32_pubkey` | Physical button | 30s |
|
|
281
479
|
| `sign_psbt` | Physical button + TX review | 60s |
|
|
480
|
+
| `sign_tx` (PQ) | Physical button + TX review | per-heartbeat (ML-DSA is slow) |
|
|
282
481
|
| `sign_message` | Physical button | 30s |
|
|
283
482
|
|
|
483
|
+
`info` reports `key_type` (`"legacy"` | `"pq"`). In PQ mode, `get_address`
|
|
484
|
+
returns only the public key (the library derives the address) and signing uses
|
|
485
|
+
`sign_tx` (raw transaction) instead of `sign_psbt`.
|
|
486
|
+
|
|
284
487
|
## API
|
|
285
488
|
|
|
286
489
|
### `NeuraiESP32`
|
|
@@ -291,13 +494,27 @@ Main class for device interaction.
|
|
|
291
494
|
|---|---|
|
|
292
495
|
| `connect()` | Open USB Serial connection (browser dialog) |
|
|
293
496
|
| `disconnect()` | Close connection |
|
|
294
|
-
| `getInfo()` | Get device info (no confirmation) |
|
|
295
|
-
| `getAddress()` | Get address + pubkey (requires confirmation) |
|
|
497
|
+
| `getInfo()` | Get device info incl. `key_type` (no confirmation) |
|
|
498
|
+
| `getAddress()` | Get address + pubkey (requires confirmation); derives the address from the pubkey + mode (legacy or PQ) |
|
|
296
499
|
| `getBip32Pubkey()` | Get account xpub (requires confirmation) |
|
|
297
500
|
| `signPsbt(base64)` | Sign a PSBT (requires confirmation) |
|
|
298
501
|
| `signPsbt(base64, display?)` | Sign a PSBT and optionally send display metadata |
|
|
299
502
|
| `signMessage(message)` | Sign a message to prove address ownership (requires confirmation) |
|
|
300
|
-
| `signTransaction(opts)` | Build + sign + finalize in one call |
|
|
503
|
+
| `signTransaction(opts)` | Build + sign + finalize in one call; auto-routes legacy (PSBT) vs PQ (`sign_tx`) by device mode |
|
|
504
|
+
| `signPqTransaction(opts)` | Spend from a PQ address: build raw tx + sign via `sign_tx` (used internally by `signTransaction` in PQ mode) |
|
|
505
|
+
|
|
506
|
+
### Post-Quantum helpers
|
|
507
|
+
|
|
508
|
+
| Function | Description |
|
|
509
|
+
|---|---|
|
|
510
|
+
| `isPQAddress(addr)` | True for `nq1…`/`tnq1…` AuthScript addresses |
|
|
511
|
+
| `decodeAddress(addr)` | Decode a legacy or PQ address (`{ type, commitment \| hash, … }`) |
|
|
512
|
+
| `encodeDestinationScript(addr)` | Output scriptPubKey for any supported address |
|
|
513
|
+
| `publicKeyToAddress(pubkeyHex, { network, keyType })` | Derive an address from a public key + mode |
|
|
514
|
+
| `resolveNetwork(network, keyType)` | Map the two axes to a `NetworkType` |
|
|
515
|
+
| `buildUnsignedPQTransaction(opts)` | Build the unsigned raw tx + per-input metadata for `sign_tx` |
|
|
516
|
+
| `extractPQWitness(signedTxHex, index?)` | Decode the AuthScript witness (`authType`, `signature`, `pubkey`, `witnessScript`) |
|
|
517
|
+
| `pqAuthScriptSighash(opts)` | Recompute the AuthScript sighash (to verify device signatures) |
|
|
301
518
|
|
|
302
519
|
### `buildPSBT(options)`
|
|
303
520
|
|
|
@@ -315,7 +532,7 @@ Finalize a signed PSBT. Returns `{ txHex, txId }`.
|
|
|
315
532
|
|
|
316
533
|
### `finalizeSignedPSBT(originalPsbtBase64, signedPsbtBase64, network)`
|
|
317
534
|
|
|
318
|
-
Merge a signed PSBT returned by
|
|
535
|
+
Merge a signed PSBT returned by the device with the original PSBT and finalize it.
|
|
319
536
|
This helper also supports the minimal PSBT format returned by `uNeurai`, and
|
|
320
537
|
includes fallback logic for legacy P2PKH finalization used by Neurai.
|
|
321
538
|
|
|
@@ -327,5 +544,9 @@ Check if a PSBT base64 string is parseable. Returns boolean.
|
|
|
327
544
|
|
|
328
545
|
## Browser support
|
|
329
546
|
|
|
330
|
-
|
|
331
|
-
Firefox and Safari are not supported.
|
|
547
|
+
The default transport requires the Web Serial API: Chrome 89+, Edge 89+,
|
|
548
|
+
Opera 75+. Firefox and Safari are not supported.
|
|
549
|
+
|
|
550
|
+
For non-browser platforms (React Native / Android USB, Node test doubles, …)
|
|
551
|
+
inject a custom transport instead — see
|
|
552
|
+
[React Native / Android USB](#react-native--android-usb).
|