@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 +195 -15
- package/dist/NeuraiSignESP32.global.js +13238 -0
- package/dist/browser.js +13196 -0
- package/dist/index.cjs +12834 -393
- package/dist/index.d.ts +425 -51
- package/dist/index.js +13196 -0
- package/package.json +23 -13
- package/dist/index.cjs.map +0 -1
- package/dist/index.d.ts.map +0 -1
- package/dist/index.mjs +0 -772
- package/dist/index.mjs.map +0 -1
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
|
|
@@ -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
|
-
|
|
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
|
-
|
|
|
209
|
-
|
|
210
|
-
| `xna` | 1900 | N (
|
|
211
|
-
| `xna-test` | 1 | testnet |
|
|
212
|
-
| `xna-
|
|
213
|
-
| `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`.
|
|
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
|
-
**
|
|
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
|
|
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
|
|
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
|
|