@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 +21 -0
- package/README.md +219 -0
- package/dist/index.cjs +576 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.ts +235 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.mjs +558 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +50 -0
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.
|