@neuraiproject/neurai-sign-esp32 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 NeuraiProject
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,219 @@
1
+ # neurai-sign-esp32
2
+
3
+ Create and sign Neurai (XNA) transactions via ESP32 hardware wallet.
4
+
5
+ This library handles the full PSBT workflow against a NeuraiHW device:
6
+ build an unsigned PSBT, send it over USB Serial for signing, receive
7
+ the signed PSBT back, finalize it, and extract the raw transaction hex
8
+ ready for broadcast.
9
+
10
+ Uses [bitcoinjs-lib](https://www.npmjs.com/package/bitcoinjs-lib) v7 for
11
+ PSBT construction and the Web Serial API for device communication.
12
+
13
+ ##
14
+
15
+ EXPERIMENTAL.
16
+
17
+ Only XNA (native coin) transfers are supported for now.
18
+ Asset transfers will be added in a future version.
19
+
20
+ ## Install
21
+
22
+ ```
23
+ npm i @neuraiproject/neurai-sign-esp32
24
+ ```
25
+
26
+ ## How to use
27
+
28
+ ### Full transaction flow
29
+
30
+ ```javascript
31
+ import { NeuraiESP32 } from "@neuraiproject/neurai-sign-esp32";
32
+
33
+ const device = new NeuraiESP32();
34
+
35
+ // Connect — opens the browser port selection dialog
36
+ await device.connect();
37
+
38
+ // Get device info (no physical confirmation needed)
39
+ const info = await device.getInfo();
40
+ console.log(info.network); // "Neurai"
41
+ console.log(info.master_fingerprint); // "a1b2c3d4"
42
+
43
+ // Get address and public key (user must press Confirm on device)
44
+ const { address, pubkey, path } = await device.getAddress();
45
+ console.log(address); // "Nxxx..."
46
+
47
+ // Build, sign and finalize in one call
48
+ // Each UTXO must include rawTxHex (full previous tx hex from getrawtransaction)
49
+ const result = await device.signTransaction({
50
+ utxos: [
51
+ {
52
+ txid: "abcd1234....",
53
+ vout: 0,
54
+ scriptPubKey: "76a914...88ac",
55
+ satoshis: 500000000,
56
+ rawTxHex: "0200000001...",
57
+ },
58
+ ],
59
+ outputs: [
60
+ { address: "Nxxx...", value: 100000000 },
61
+ ],
62
+ changeAddress: address,
63
+ });
64
+
65
+ console.log(result.txHex); // raw tx hex, broadcast with sendrawtransaction
66
+ console.log(result.txId); // transaction id
67
+ console.log(result.signedInputs); // number of inputs signed by the device
68
+
69
+ await device.disconnect();
70
+ ```
71
+
72
+ ### Step by step (manual PSBT)
73
+
74
+ If you want to build the PSBT yourself:
75
+
76
+ ```javascript
77
+ import { NeuraiESP32, buildPSBT, finalizePSBT } from "@neuraiproject/neurai-sign-esp32";
78
+
79
+ const device = new NeuraiESP32();
80
+ await device.connect();
81
+
82
+ const info = await device.getInfo();
83
+ const { address, pubkey, path } = await device.getAddress();
84
+
85
+ // 1. Build unsigned PSBT
86
+ const psbtBase64 = buildPSBT({
87
+ network: "xna",
88
+ utxos: [
89
+ {
90
+ txid: "abcd1234....",
91
+ vout: 0,
92
+ scriptPubKey: "76a914...88ac",
93
+ satoshis: 500000000,
94
+ rawTxHex: "0200000001...",
95
+ },
96
+ ],
97
+ outputs: [{ address: "Nxxx...", value: 100000000 }],
98
+ changeAddress: address,
99
+ pubkey: pubkey,
100
+ masterFingerprint: info.master_fingerprint,
101
+ derivationPath: path,
102
+ feeRate: 1024,
103
+ });
104
+
105
+ // 2. Send to device for signing (user confirms with physical button)
106
+ const signed = await device.signPsbt(psbtBase64);
107
+
108
+ // 3. Finalize and extract raw transaction
109
+ const { txHex, txId } = finalizePSBT(signed.psbt, "xna");
110
+ console.log(txHex); // ready for sendrawtransaction
111
+
112
+ await device.disconnect();
113
+ ```
114
+
115
+ ### Get BIP32 extended public key
116
+
117
+ ```javascript
118
+ // Request the account xpub (user must press Confirm on device)
119
+ const bip32 = await device.getBip32Pubkey();
120
+ console.log(bip32.bip32_pubkey); // "xpub6..."
121
+ console.log(bip32.master_fingerprint); // "a1b2c3d4"
122
+ console.log(bip32.path); // "m/44'/1900'/0'"
123
+ ```
124
+
125
+ ### Check Web Serial API support
126
+
127
+ ```javascript
128
+ import { NeuraiESP32 } from "@neuraiproject/neurai-sign-esp32";
129
+
130
+ if (!NeuraiESP32.isSupported()) {
131
+ console.log("Web Serial API not supported. Use Chrome, Edge, or Opera.");
132
+ }
133
+ ```
134
+
135
+ ## UTXO requirements
136
+
137
+ Each UTXO requires the `rawTxHex` field — the full raw hex of the previous
138
+ transaction. This is needed because P2PKH inputs use `nonWitnessUtxo` in the
139
+ PSBT spec. You can get it from your Neurai node:
140
+
141
+ ```javascript
142
+ const rawTxHex = await rpc("getrawtransaction", [txid]);
143
+ ```
144
+
145
+ ## Networks
146
+
147
+ Supported network types:
148
+
149
+ | Network | Coin type | Address prefix |
150
+ |---|---|---|
151
+ | `xna` | 1900 | N (mainnet, recommended) |
152
+ | `xna-test` | 1 | testnet |
153
+ | `xna-legacy` | 0 | N (legacy mainnet) |
154
+ | `xna-legacy-test` | 1 | testnet legacy |
155
+
156
+ ## Chunked serial writes (important)
157
+
158
+ The ESP32 CDC serial buffer can lose data when the host sends a large payload
159
+ in a single write. This is a known issue with USB CDC on ESP32-S3 — the
160
+ firmware's `Serial.read()` loop cannot drain the buffer fast enough if the
161
+ host flushes several kilobytes at once.
162
+
163
+ This library works around the problem by splitting every outgoing message into
164
+ **32-byte chunks** with a **4 ms pause** between each one. This matches the
165
+ approach used in the reference web wallet (`NeuraiHWSerial.writeChunked`).
166
+
167
+ The newline terminator (`\n`) is sent separately after all chunks, so the
168
+ firmware only processes the command once the full JSON has arrived.
169
+
170
+ If you build your own serial transport, make sure to replicate this chunked
171
+ write strategy — otherwise `sign_psbt` commands (which carry large base64
172
+ payloads) will fail silently or produce corrupted data on the device.
173
+
174
+ ## Device protocol
175
+
176
+ The library communicates with NeuraiHW firmware over USB Serial (115200 baud)
177
+ using JSON messages. Supported commands:
178
+
179
+ | Command | Confirmation | Timeout |
180
+ |---|---|---|
181
+ | `info` | None | 5s |
182
+ | `get_address` | Physical button | 30s |
183
+ | `get_bip32_pubkey` | Physical button | 30s |
184
+ | `sign_psbt` | Physical button + TX review | 60s |
185
+
186
+ ## API
187
+
188
+ ### `NeuraiESP32`
189
+
190
+ Main class for device interaction.
191
+
192
+ | Method | Description |
193
+ |---|---|
194
+ | `connect()` | Open USB Serial connection (browser dialog) |
195
+ | `disconnect()` | Close connection |
196
+ | `getInfo()` | Get device info (no confirmation) |
197
+ | `getAddress()` | Get address + pubkey (requires confirmation) |
198
+ | `getBip32Pubkey()` | Get account xpub (requires confirmation) |
199
+ | `signPsbt(base64)` | Sign a PSBT (requires confirmation) |
200
+ | `signTransaction(opts)` | Build + sign + finalize in one call |
201
+
202
+ ### `buildPSBT(options)`
203
+
204
+ Build an unsigned PSBT for P2PKH. Returns base64 string.
205
+
206
+ ### `finalizePSBT(base64, network)`
207
+
208
+ Finalize a signed PSBT. Returns `{ txHex, txId }`.
209
+
210
+ ### `validatePSBT(base64, network)`
211
+
212
+ Check if a PSBT base64 string is parseable. Returns boolean.
213
+
214
+ [Check the TypeScript definitions](./dist/index.d.ts) for all the details.
215
+
216
+ ## Browser support
217
+
218
+ Requires Web Serial API: Chrome 89+, Edge 89+, Opera 75+.
219
+ Firefox and Safari are not supported.