@neuraiproject/neurai-sign-esp32 0.6.0 → 0.7.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 +246 -35
- package/dist/NeuraiSignESP32.global.js +1443 -496
- package/dist/browser.js +1433 -496
- package/dist/index.cjs +1452 -495
- package/dist/index.d.cts +1517 -0
- package/dist/index.d.ts +380 -55
- package/dist/index.js +1433 -496
- package/dist/react-native.d.ts +380 -55
- package/dist/react-native.js +1433 -496
- package/package.json +19 -9
package/README.md
CHANGED
|
@@ -11,9 +11,16 @@ 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
13
|
It also supports **Post-Quantum (ML-DSA-44 / AuthScript) addresses**: sending to
|
|
14
|
-
PQ
|
|
15
|
-
the device mode from `info` and routes accordingly — see
|
|
16
|
-
[Post-Quantum support](#post-quantum-pq--ml-dsa-44-support).
|
|
14
|
+
them and spending from the device's PQ address (`nc1p…`/`tnc1p…`). The library
|
|
15
|
+
auto-detects the device mode from `info` and routes accordingly — see
|
|
16
|
+
[Post-Quantum support](#post-quantum-pq--ml-dsa-44-support). Outputs can pay to
|
|
17
|
+
every Neurai address type — see [Address types](#address-types).
|
|
18
|
+
|
|
19
|
+
> **0.7.0 follows the new Neurai address types** (node Neurai-DePIN,
|
|
20
|
+
> `@neuraiproject/neurai-key` 5): the device's PQ address is now encoded as
|
|
21
|
+
> `nc1p…`/`tnc1p…` (it used to be `nq1p…`/`tnq1p…`, which the node rejects) and
|
|
22
|
+
> `nq1…`/`tnq1…` now means strict ECDSA witness v3. See
|
|
23
|
+
> [Upgrading to 0.7.0](#upgrading-to-070).
|
|
17
24
|
|
|
18
25
|
##
|
|
19
26
|
|
|
@@ -24,7 +31,9 @@ This library supports:
|
|
|
24
31
|
- Asset transfers
|
|
25
32
|
- BIP32 account discovery via `get_bip32_pubkey`
|
|
26
33
|
- Message signing (prove address ownership)
|
|
27
|
-
- **Post-Quantum addresses (ML-DSA-44 / AuthScript)** — send to and spend from `
|
|
34
|
+
- **Post-Quantum addresses (ML-DSA-44 / AuthScript)** — send to and spend from `nc1p…`/`tnc1p…`
|
|
35
|
+
- Sending to every Neurai address type: Legacy P2PKH, `nc1p…`, `pq1z…`, `nq1r…`
|
|
36
|
+
- Strict ECDSA witness v3 (`nq1r…`) inputs through `sign_psbt` (firmware built with uNeurai >= 0.2.0)
|
|
28
37
|
|
|
29
38
|
Asset transfers use the same PSBT signing flow as XNA transfers. The transaction
|
|
30
39
|
outputs are still signed from the raw unsigned transaction, while optional
|
|
@@ -345,9 +354,9 @@ await identity.session.ensure({ minRemainingSeconds: 60 });
|
|
|
345
354
|
> `depin_sign_auth` and session permissions are **not implemented in current
|
|
346
355
|
> firmware yet** — the contract they must satisfy is specified, and exercised
|
|
347
356
|
> by a cryptographically faithful device mock, in this package's tests.
|
|
348
|
-
> `@neuraiproject/neurai-depin-msg@3.1.
|
|
349
|
-
> this repository from scratch or publishing `neurai-sign-esp32@0.
|
|
350
|
-
> package has no runtime dependency on `neurai-depin-msg`; it is a `^3.1.
|
|
357
|
+
> `@neuraiproject/neurai-depin-msg@3.1.2` must be published before installing
|
|
358
|
+
> this repository from scratch or publishing `neurai-sign-esp32@0.7.0`. The
|
|
359
|
+
> package has no runtime dependency on `neurai-depin-msg`; it is a `^3.1.2`
|
|
351
360
|
> development dependency used only by the integration tests. The package gate
|
|
352
361
|
> validates the adapter from a clean `neurai-sign-esp32` tarball.
|
|
353
362
|
|
|
@@ -407,12 +416,22 @@ orthogonal axes:
|
|
|
407
416
|
|
|
408
417
|
The library reads `info.key_type` and routes automatically — the same
|
|
409
418
|
`getAddress()` / `signTransaction()` calls work in both modes. PQ uses the
|
|
410
|
-
AuthScript witness-v1 format (`
|
|
411
|
-
|
|
412
|
-
(`sign_tx`) under the
|
|
419
|
+
generic AuthScript witness-v1 format (`nc1p…` mainnet / `tnc1p…` testnet;
|
|
420
|
+
authType `0x01`, witnessScript `OP_TRUE`), which cannot be represented in a
|
|
421
|
+
PSBT, so spending from PQ uses a raw-transaction transport (`sign_tx`) under the
|
|
422
|
+
hood. See [`docs/pq-protocol-design.md`](./docs/pq-protocol-design.md).
|
|
413
423
|
|
|
414
424
|
> The device exposes **only the public key** of its single address; the library
|
|
415
|
-
> derives the `
|
|
425
|
+
> derives the `nc1p…`/`tnc1p…` address from that pubkey + mode. The firmware
|
|
426
|
+
> sends `auth_type` / `witness_script` in snake_case; `getAddress()` returns them
|
|
427
|
+
> as `authType` / `witnessScript`.
|
|
428
|
+
|
|
429
|
+
> Firmware built against uNeurai < 0.2.0 still reports its address as
|
|
430
|
+
> `nq1p…`/`tnq1p…` in `info`; `getInfo()` / `getAddress()` re-encode it to the
|
|
431
|
+
> valid `nc1p…`/`tnc1p…` form (same scriptPubKey), so it keeps working as a
|
|
432
|
+
> change address. The strict PQ family (witness v2, `pq1z…`) is not produced by
|
|
433
|
+
> the current firmware; `sign_tx` refuses v2/v3 prevouts before contacting the
|
|
434
|
+
> device.
|
|
416
435
|
|
|
417
436
|
### Read a PQ address
|
|
418
437
|
|
|
@@ -427,20 +446,22 @@ console.log(info.network); // "NeuraiTest"
|
|
|
427
446
|
// In PQ mode the device returns only the pubkey; the library derives the address.
|
|
428
447
|
const addr = await device.getAddress(); // requires confirmation on device
|
|
429
448
|
console.log(addr.type); // "pq"
|
|
430
|
-
console.log(addr.address); // "
|
|
449
|
+
console.log(addr.address); // "tnc1p..."
|
|
431
450
|
console.log(addr.commitment); // 32-byte AuthScript commitment (hex)
|
|
432
451
|
```
|
|
433
452
|
|
|
434
453
|
### Send to a PQ address (from a legacy ECDSA wallet)
|
|
435
454
|
|
|
436
|
-
No special handling is needed: pass
|
|
437
|
-
`
|
|
438
|
-
|
|
455
|
+
No special handling is needed: pass any AuthScript destination (`tnc1p…`,
|
|
456
|
+
`tpq1z…`, `tnq1r…`, or the mainnet forms) to `signTransaction`/`buildPSBT`. The
|
|
457
|
+
library encodes the output script (`OP_1`/`OP_2`/`OP_3` `0x20 <commitment>`)
|
|
458
|
+
automatically and checks that the address belongs to the PSBT's chain; the
|
|
459
|
+
ECDSA inputs are still signed via `sign_psbt`.
|
|
439
460
|
|
|
440
461
|
```javascript
|
|
441
462
|
const result = await device.signTransaction({
|
|
442
463
|
utxos: [/* legacy P2PKH UTXOs with rawTxHex */],
|
|
443
|
-
outputs: [{ address: "
|
|
464
|
+
outputs: [{ address: "tnc1p...", value: 100000000 }], // PQ destination
|
|
444
465
|
changeAddress: address,
|
|
445
466
|
});
|
|
446
467
|
```
|
|
@@ -459,12 +480,12 @@ const result = await device.signTransaction({
|
|
|
459
480
|
txid: "abcd1234....",
|
|
460
481
|
vout: 0,
|
|
461
482
|
satoshis: 100000000,
|
|
462
|
-
scriptPubKey: "5120<32-byte commitment>", // the PQ address script
|
|
483
|
+
scriptPubKey: "5120<32-byte commitment>", // the PQ address script (witness v1)
|
|
463
484
|
type: "pq",
|
|
464
485
|
// sighashAmount: 0, // use 0 for asset-wrapped inputs
|
|
465
486
|
},
|
|
466
487
|
],
|
|
467
|
-
outputs: [{ address: "
|
|
488
|
+
outputs: [{ address: "tnc1p...", value: 50000000 }],
|
|
468
489
|
// changeAddress defaults to the device's PQ address
|
|
469
490
|
});
|
|
470
491
|
|
|
@@ -496,6 +517,24 @@ const sighash = pqAuthScriptSighash({
|
|
|
496
517
|
const ok = ml_dsa44.verify(w.signature, sighash, w.pubkey); // verify(sig, msg, pub)
|
|
497
518
|
```
|
|
498
519
|
|
|
520
|
+
`pqAuthScriptSighash` computes the generic witness-v1 sighash by default. The
|
|
521
|
+
strict families use a different preimage (the witness version byte is written
|
|
522
|
+
before `authType`, and the scriptCode is always `OP_TRUE`); a v1-style
|
|
523
|
+
signature is **not** valid for them:
|
|
524
|
+
|
|
525
|
+
```javascript
|
|
526
|
+
import { strictAuthScriptSighash } from "@neuraiproject/neurai-sign-esp32";
|
|
527
|
+
|
|
528
|
+
// Strict PQ v2 (pq1z…) or strict ECDSA v3 (nq1r…) input
|
|
529
|
+
const h = strictAuthScriptSighash({ tx, inputIndex: 0, amount, witnessVersion: 2 });
|
|
530
|
+
// witness: [authType, sig||hashType, pubkey, 0x51] (v2: authType 0x01 + 0x05||pq_pubkey,
|
|
531
|
+
// v3: authType 0x02 + compressed secp256k1 pubkey)
|
|
532
|
+
```
|
|
533
|
+
|
|
534
|
+
The current firmware signs witness v1 only (`sign_tx`) and, with uNeurai >=
|
|
535
|
+
0.2.0, strict ECDSA v3 inputs through `sign_psbt`; the strict sighash is here so
|
|
536
|
+
hosts can verify or build strict spends (and for future firmware).
|
|
537
|
+
|
|
499
538
|
[`examples/browser-test.html`](./examples/browser-test.html) demonstrates this
|
|
500
539
|
full flow end-to-end (read PQ address → sign a test transaction → verify the
|
|
501
540
|
ML-DSA-44 signature).
|
|
@@ -525,7 +564,7 @@ Suggested flow:
|
|
|
525
564
|
`npx serve .` or `python3 -m http.server 8000`.
|
|
526
565
|
3. Open `http://localhost:8000/examples/browser-test.html` in Chrome or Edge.
|
|
527
566
|
4. Click `Conectar`, pick the port, and confirm on the device. The page shows the
|
|
528
|
-
derived `
|
|
567
|
+
derived `tnc1p…` address.
|
|
529
568
|
5. Click `Firmar transacción de prueba` and confirm on the device. The page signs
|
|
530
569
|
a fictitious transaction and shows `✓ Firma ML-DSA-44 VÁLIDA`.
|
|
531
570
|
|
|
@@ -615,7 +654,14 @@ After `npm run build`, the package publishes:
|
|
|
615
654
|
- `dist/browser.js`: explicit browser ESM entry
|
|
616
655
|
- `dist/react-native.js`: React Native entry (no Web Serial; adds the USB transport)
|
|
617
656
|
- `dist/NeuraiSignESP32.global.js`: IIFE bundle exposing `globalThis.NeuraiSignESP32`
|
|
618
|
-
- `dist/index.d.ts` / `dist/react-native.d.ts`: public types
|
|
657
|
+
- `dist/index.d.ts` / `dist/react-native.d.ts`: public types (ESM)
|
|
658
|
+
- `dist/index.d.cts`: the same types for `require` (CommonJS)
|
|
659
|
+
|
|
660
|
+
`npm run test:types` compiles the consumers in `types-test/` (ESM, CommonJS,
|
|
661
|
+
browser and React Native) against the built declarations in NodeNext, Node16
|
|
662
|
+
and Bundler. `npm run test:package` packs the tarball, installs it in a clean
|
|
663
|
+
project and checks runtime and types there, with TypeScript 5.3 too (the
|
|
664
|
+
oldest release the declarations support).
|
|
619
665
|
|
|
620
666
|
## UTXO requirements
|
|
621
667
|
|
|
@@ -633,17 +679,67 @@ The public model has two orthogonal axes: **network** (`mainnet`/`testnet`) and
|
|
|
633
679
|
**key_type** (`legacy`/`pq`). The device declares both via `info`. Internally
|
|
634
680
|
these resolve to a `NetworkType` identifier:
|
|
635
681
|
|
|
636
|
-
| network | key_type | Internal `NetworkType` | Coin type | Address prefix |
|
|
637
|
-
|
|
638
|
-
| mainnet | legacy | `xna` | 1900 | `N…` (P2PKH) |
|
|
639
|
-
| testnet | legacy | `xna-test` | 1 |
|
|
640
|
-
| mainnet | pq | `xna-pq` | 1900 | `
|
|
641
|
-
| testnet | pq | `xna-pq-test` | 1 | `
|
|
682
|
+
| network | key_type | Internal `NetworkType` | Coin type | Address prefix | neurai-key 5 name |
|
|
683
|
+
|---|---|---|---|---|---|
|
|
684
|
+
| mainnet | legacy | `xna` | 1900 | `N…` (P2PKH) | `xna-legacy` |
|
|
685
|
+
| testnet | legacy | `xna-test` | 1 | `t…` (P2PKH) | `xna-legacy-test` |
|
|
686
|
+
| mainnet | pq | `xna-pq` | 1900 | `nc1p…` (AuthScript v1) | `xna-authscript` |
|
|
687
|
+
| testnet | pq | `xna-pq-test` | 1 | `tnc1p…` (AuthScript v1) | `xna-authscript-test` |
|
|
642
688
|
|
|
643
689
|
`xna-legacy` / `xna-legacy-test` (coin type 0) remain available for the legacy
|
|
644
|
-
coin-type-0 derivation and are unrelated to `key_type: "legacy"
|
|
690
|
+
coin-type-0 derivation and are unrelated to `key_type: "legacy"` (neurai-key 5
|
|
691
|
+
calls the mainnet one `xna-old-legacy`). Use
|
|
645
692
|
`resolveNetwork(network, keyType)` to map the two axes to a `NetworkType`.
|
|
646
693
|
|
|
694
|
+
### Naming differences with `@neuraiproject/neurai-key` 5
|
|
695
|
+
|
|
696
|
+
This package's `NetworkType` names predate neurai-key 5 and keep their meaning.
|
|
697
|
+
Three of them are spelled like key-5 networks that mean something else:
|
|
698
|
+
|
|
699
|
+
| name | here | in neurai-key 5 |
|
|
700
|
+
|---|---|---|
|
|
701
|
+
| `xna` | Legacy P2PKH, coin type 1900 | strict ECDSA witness v3 (`nq1r…`) |
|
|
702
|
+
| `xna-legacy` | Legacy P2PKH, coin type 0 | Legacy P2PKH, coin type 1900 |
|
|
703
|
+
| `xna-pq` | AuthScript v1 with a PQ key (`nc1p…`) | strict PQ witness v2 (`pq1z…`) |
|
|
704
|
+
|
|
705
|
+
- `getNetwork()` also accepts the key-5 names that are unambiguous here:
|
|
706
|
+
`xna-old-legacy` (= `xna-legacy`), `xna-authscript` / `xna-authscript-test`
|
|
707
|
+
(= `xna-pq` / `xna-pq-test`).
|
|
708
|
+
- `fromNeuraiKeyNetwork(name)` translates a key-5 name with key-5 semantics
|
|
709
|
+
(`"xna-legacy"` → `"xna"`, …) and throws a descriptive error for the key-5
|
|
710
|
+
families the device flows do not produce (`xna`/`xna-test`: strict ECDSA,
|
|
711
|
+
`xna-pq`/`xna-pq-test`: strict PQ).
|
|
712
|
+
- The DePIN identity is always Legacy P2PKH (`m/44'/1900'/100'/0/0`, or
|
|
713
|
+
`m/44'/1'/100'/0/0` on testnet), i.e. neurai-key 5 `xna-legacy` /
|
|
714
|
+
`xna-legacy-test`; the node's DePIN messaging does not accept witness
|
|
715
|
+
addresses.
|
|
716
|
+
|
|
717
|
+
## Address types
|
|
718
|
+
|
|
719
|
+
| Family | Witness | HRP (main / test) | scriptPubKey | authType | witnessScript | neurai-key 5 |
|
|
720
|
+
|---|---|---|---|---|---|---|
|
|
721
|
+
| Legacy P2PKH | — | Base58 `N…` / `t…` | `76a914…88ac` | — | — | `xna-legacy`, `xna-old-legacy` |
|
|
722
|
+
| Generic AuthScript | v1 | `nc` / `tnc` → `nc1p…` | `51 20 <C>` | any | any | `xna-authscript` |
|
|
723
|
+
| Strict PQ (ML-DSA-44) | v2 | `pq` / `tpq` → `pq1z…` | `52 20 <C>` | `0x01` | `0x51` (fixed) | `xna-pq` |
|
|
724
|
+
| Strict ECDSA (secp256k1) | v3 | `nq` / `tnq` → `nq1r…` | `53 20 <C>` | `0x02` | `0x51` (fixed) | `xna` |
|
|
725
|
+
|
|
726
|
+
`C = taggedHash("NeuraiAuthScript", witnessVersion || auth_descriptor || SHA256(witnessScript))`.
|
|
727
|
+
|
|
728
|
+
- `decodeAddress()` follows the node: Bech32m first (any case, only these
|
|
729
|
+
HRP/version pairs), Base58 otherwise. `nq1p…`/`tnq1p…` (the old witness-v1
|
|
730
|
+
encoding) is rejected with a hint to use `nc1p…`/`tnc1p…`. The result keeps
|
|
731
|
+
`type: "pq"` for every Bech32m address (as before) and adds `family`
|
|
732
|
+
(`"authscript"` | `"pq"` | `"ecdsa"`), `witnessVersion` and `network`.
|
|
733
|
+
- `encodeDestinationScript()` emits `OP_1`/`OP_2`/`OP_3 0x20 <C>`.
|
|
734
|
+
- **Activation:** the strict families (v2/v3) are active only on regtest for
|
|
735
|
+
now. Before activation the node refuses `pq1…`/`nq1…` addresses because an
|
|
736
|
+
`OP_2`/`OP_3` output is anyone-can-spend there. The library cannot know the
|
|
737
|
+
activation state of the target chain: do not pay to v2/v3 addresses where
|
|
738
|
+
they are not active.
|
|
739
|
+
- PSBT inputs: P2PKH, or strict ECDSA v3 prevouts (the finalizer builds the
|
|
740
|
+
witness `[0x02, sig, pubkey, 0x51]`; needs firmware with uNeurai >= 0.2.0).
|
|
741
|
+
Generic v1 and strict v2 inputs cannot go through a PSBT.
|
|
742
|
+
|
|
647
743
|
## Chunked serial writes (important)
|
|
648
744
|
|
|
649
745
|
The ESP32 CDC serial buffer can lose data when the host sends a large payload
|
|
@@ -685,8 +781,9 @@ using JSON messages. Supported commands:
|
|
|
685
781
|
| `depin_session_end` | None (session-key gated) | 10s |
|
|
686
782
|
|
|
687
783
|
`info` reports `key_type` (`"legacy"` | `"pq"`). In PQ mode, `get_address`
|
|
688
|
-
returns only the public key
|
|
689
|
-
`sign_tx` (raw transaction) instead of
|
|
784
|
+
returns only the public key plus `auth_type` / `witness_script` (the library
|
|
785
|
+
derives the address) and signing uses `sign_tx` (raw transaction) instead of
|
|
786
|
+
`sign_psbt`. `sign_tx` signs generic AuthScript v1 inputs only.
|
|
690
787
|
|
|
691
788
|
While the device is **locked** (encrypted seed stored, PIN pending) or
|
|
692
789
|
**unconfigured** (no seed), the firmware rejects every command except
|
|
@@ -730,18 +827,27 @@ Main class for device interaction.
|
|
|
730
827
|
|
|
731
828
|
| Function | Description |
|
|
732
829
|
|---|---|
|
|
733
|
-
| `
|
|
734
|
-
| `
|
|
830
|
+
| `isWitnessAddress(addr)` | True for valid `nc1p…`/`pq1z…`/`nq1r…` (and testnet) AuthScript addresses |
|
|
831
|
+
| `isPQAddress(addr)` | Deprecated alias of `isWitnessAddress` (true for every AuthScript family, not only ML-DSA keys) |
|
|
832
|
+
| `getAddressFamily(addr)` | `"legacy"` \| `"authscript"` \| `"pq"` \| `"ecdsa"` |
|
|
833
|
+
| `decodeAddress(addr)` | Decode any address (`{ type, family, witnessVersion, network, commitment \| hash, … }`) |
|
|
735
834
|
| `encodeDestinationScript(addr)` | Output scriptPubKey for any supported address |
|
|
736
|
-
| `publicKeyToAddress(pubkeyHex, { network, keyType })` | Derive an address from a public key + mode |
|
|
835
|
+
| `publicKeyToAddress(pubkeyHex, { network, keyType, witnessVersion? })` | Derive an address from a public key + mode (`pq`: v1 `nc1p…` by default, `witnessVersion: 2` for `pq1z…`) |
|
|
836
|
+
| `pqAddressFromPublicKey(pubkey, params)` | PQ address in the family of `params` (`getPQNetworkParams(network, 1 \| 2)`) |
|
|
837
|
+
| `ecdsaAddressFromPublicKey(pubkey33, network)` | Strict ECDSA v3 address (`nq1r…`/`tnq1r…`) |
|
|
838
|
+
| `authScriptCommitment(opts)` / `pqCommitment` / `ecdsaCommitment` | Versioned AuthScript commitments |
|
|
839
|
+
| `normalizeDeviceAuthScriptAddress(addr)` | Re-encode a pre-0.2.0 firmware `nq1p…`/`tnq1p…` address as `nc1p…`/`tnc1p…` |
|
|
737
840
|
| `resolveNetwork(network, keyType)` | Map the two axes to a `NetworkType` |
|
|
738
|
-
| `
|
|
841
|
+
| `fromNeuraiKeyNetwork(name)` | Translate a neurai-key 5 network name to a `NetworkType` |
|
|
842
|
+
| `buildUnsignedPQTransaction(opts)` | Build the unsigned raw tx + per-input metadata for `sign_tx` (witness v1 prevouts only) |
|
|
739
843
|
| `extractPQWitness(signedTxHex, index?)` | Decode the AuthScript witness (`authType`, `signature`, `pubkey`, `witnessScript`) |
|
|
740
|
-
| `pqAuthScriptSighash(opts)` | Recompute the AuthScript sighash (to verify device signatures) |
|
|
844
|
+
| `pqAuthScriptSighash(opts)` | Recompute the AuthScript sighash (to verify device signatures); witness v1 by default, `witnessVersion: 2 \| 3` for strict |
|
|
845
|
+
| `strictAuthScriptSighash(opts)` | Strict v2 / v3 sighash (`… locktime \|\| witnessVersion \|\| authType \|\| hashType`) |
|
|
741
846
|
|
|
742
847
|
### `buildPSBT(options)`
|
|
743
848
|
|
|
744
|
-
Build an unsigned PSBT for P2PKH.
|
|
849
|
+
Build an unsigned PSBT for P2PKH (and strict ECDSA v3) inputs. Outputs may pay
|
|
850
|
+
to any Neurai address type. Returns base64 string.
|
|
745
851
|
|
|
746
852
|
### `buildPSBTFromRawTransaction(options)`
|
|
747
853
|
|
|
@@ -773,3 +879,108 @@ Opera 75+. Firefox and Safari are not supported.
|
|
|
773
879
|
For non-browser platforms (React Native / Android USB, Node test doubles, …)
|
|
774
880
|
inject a custom transport instead — see
|
|
775
881
|
[React Native / Android USB](#react-native--android-usb).
|
|
882
|
+
|
|
883
|
+
|
|
884
|
+
## Exact amounts (0.6.1)
|
|
885
|
+
|
|
886
|
+
`IUTXO.satoshis`, `IPQUTXO.satoshis`, output `value`, PQ `amount` and
|
|
887
|
+
`sighashAmount` accept `bigint`, integer strings, or safe integer numbers. These
|
|
888
|
+
are **raw protocol units**, not decimal XNA or asset units. Values must be
|
|
889
|
+
non-negative and no greater than `2100000000000000000n`. Already unsafe numbers
|
|
890
|
+
are rejected; converting a rounded number to bigint cannot restore its digits.
|
|
891
|
+
|
|
892
|
+
```ts
|
|
893
|
+
const output = { address: destination, value: 10000000000000001n };
|
|
894
|
+
// The same exact amount can be passed as value: '10000000000000001'.
|
|
895
|
+
```
|
|
896
|
+
|
|
897
|
+
Both high-level builders sum funds, calculate change and subtract fees in bigint.
|
|
898
|
+
`feeRate` accepts a number or decimal string in satoshis per byte. Fractional
|
|
899
|
+
rates are multiplied exactly and rounded upward to a whole satoshi once.
|
|
900
|
+
|
|
901
|
+
Asset transactions prepared externally should use `buildPSBTFromRawTransaction`
|
|
902
|
+
(legacy) or `signPqRawTransaction` (PQ). Their asset payload quantities remain
|
|
903
|
+
encoded in the transaction bytes at scale 10^8, independent of asset divisibility.
|
|
904
|
+
The high-level address/value output builders construct XNA payment outputs;
|
|
905
|
+
they do not create asset transfer payloads. For asset-wrapped PQ inputs, pass
|
|
906
|
+
`amount: 0` to the raw signing API, or `sighashAmount: 0` when using the builder.
|
|
907
|
+
An asset quantity must never count toward XNA funding: an explicit zero prevout
|
|
908
|
+
value contributes zero to fees and payment funding, so separate XNA inputs are
|
|
909
|
+
required.
|
|
910
|
+
|
|
911
|
+
Display metadata uses decimal **strings** for large asset quantities and fees:
|
|
912
|
+
|
|
913
|
+
```ts
|
|
914
|
+
const display = buildAssetTransferDisplayMetadata({
|
|
915
|
+
assetName: 'LARGE',
|
|
916
|
+
assetAmount: '100000000.00000001',
|
|
917
|
+
destinationAddress: destination,
|
|
918
|
+
feeAmount: '0.00000249',
|
|
919
|
+
});
|
|
920
|
+
```
|
|
921
|
+
|
|
922
|
+
Plain strings retain their formatting. Invalid amounts, excess decimals and
|
|
923
|
+
unsafe large fractional numbers are rejected instead of silently rounded.
|
|
924
|
+
Direct signing calls validate display amounts too.
|
|
925
|
+
|
|
926
|
+
Before handing `sign_tx` to a transport, the library encodes safe raw amounts as
|
|
927
|
+
JSON numbers and larger ones as integer strings. Custom transports must preserve
|
|
928
|
+
those strings. The reviewed firmware reads `amount` using ArduinoJson
|
|
929
|
+
`as<unsigned long long>()`, which supports exact integer strings. Its local
|
|
930
|
+
ArduinoJson parser was checked on the host up to MAX_MONEY; this does not replace
|
|
931
|
+
an on-device signing and display check of the firmware installed on your ESP32.
|
|
932
|
+
No global bigint JSON serializer is required.
|
|
933
|
+
|
|
934
|
+
## Upgrading to 0.7.0
|
|
935
|
+
|
|
936
|
+
0.7.0 follows the address types of the Neurai node (Neurai-DePIN) and
|
|
937
|
+
`@neuraiproject/neurai-key` 5.
|
|
938
|
+
|
|
939
|
+
Breaking changes:
|
|
940
|
+
|
|
941
|
+
- **PQ addresses are encoded as `nc1p…` / `tnc1p…`.** `neuraiPQMainnet` /
|
|
942
|
+
`neuraiPQTestnet` (and `getPQNetworkParams`) use the HRPs `nc` / `tnc`, so
|
|
943
|
+
`publicKeyToAddress(…, { keyType: "pq" })`, `pqAddressFromPublicKey` and
|
|
944
|
+
`getAddress()` return `nc1p…` / `tnc1p…`. The scriptPubKey (`5120<C>`) and the
|
|
945
|
+
commitment did not change: funds on an old `nq1p…` / `tnq1p…` address are
|
|
946
|
+
reachable through the re-encoded address.
|
|
947
|
+
- **`nq1…` / `tnq1…` is the strict ECDSA family now.** `decodeAddress` rejects
|
|
948
|
+
the old witness-v1 `nq1p…` / `tnq1p…` form (with a hint), like the node, and
|
|
949
|
+
so do `encodeDestinationScript`, `buildPSBT` and `buildUnsignedPQTransaction`.
|
|
950
|
+
- `isPQAddress` validates the address (Bech32m checksum, canonical HRP/version
|
|
951
|
+
pair) instead of matching the `nq1` / `tnq1` prefix, and is true for every
|
|
952
|
+
AuthScript family. It is deprecated in favour of `isWitnessAddress` /
|
|
953
|
+
`getAddressFamily`. Base58 addresses that start with `NQ1…` are no longer
|
|
954
|
+
misclassified.
|
|
955
|
+
- `buildPSBT` checks that an AuthScript destination belongs to the PSBT's chain
|
|
956
|
+
(a testnet address in an `xna` PSBT throws) and estimates AuthScript outputs
|
|
957
|
+
at 43 bytes.
|
|
958
|
+
- `pqAuthScriptSighash` throws for a sighash type other than `SIGHASH_ALL` and
|
|
959
|
+
for version-3 transactions (it used to return a hash the device and node would
|
|
960
|
+
not agree with); `buildUnsignedPQTransaction` and `signPqRawTransaction`
|
|
961
|
+
reject strict v2/v3 prevouts and version-3 transactions.
|
|
962
|
+
|
|
963
|
+
Type declarations: `require` now gets CommonJS declarations
|
|
964
|
+
(`dist/index.d.cts`). Up to 0.6.1 it got the ESM `dist/index.d.ts`, and a
|
|
965
|
+
CommonJS project compiled with `moduleResolution` `node16` failed with TS1471.
|
|
966
|
+
bitcoinjs-lib only ships ESM declarations, so `dist/index.d.cts` imports its
|
|
967
|
+
types with a `resolution-mode` attribute: the declarations need TypeScript 5.3
|
|
968
|
+
or later.
|
|
969
|
+
|
|
970
|
+
Additions: `strictAuthScriptSighash` and `pqAuthScriptSighash({ witnessVersion })`,
|
|
971
|
+
`AUTHSCRIPT_FAMILIES`, `isWitnessAddress`, `getAddressFamily`,
|
|
972
|
+
`ecdsaAddressFromPublicKey`, `authScriptCommitment`, `ecdsaCommitment`,
|
|
973
|
+
`normalizeDeviceAuthScriptAddress`, `fromNeuraiKeyNetwork`, the strict PQ
|
|
974
|
+
params `neuraiPQStrictMainnet` / `neuraiPQStrictTestnet`, v3 PSBT finalization,
|
|
975
|
+
and the snake_case `auth_type` / `witness_script` fields of `get_address`, which
|
|
976
|
+
are now read (they used to be ignored).
|
|
977
|
+
|
|
978
|
+
### Testing against a node
|
|
979
|
+
|
|
980
|
+
`npm test` runs the unit tests (vectors from a Neurai-DePIN regtest node are in
|
|
981
|
+
`src/pq-address.fixtures.ts`). `src/node-regtest.integration.test.ts` is an
|
|
982
|
+
opt-in end-to-end check: set `NEURAI_REGTEST_CLI` to the `neurai-cli` command of
|
|
983
|
+
a regtest node that knows the `nc` / `pq` / `nq` families and it funds v1, v2
|
|
984
|
+
and v3 addresses derived by the library, signs spends with software keys
|
|
985
|
+
standing in for the device, and checks them with `testmempoolaccept`.
|
|
986
|
+
|