@neuraiproject/neurai-sign-esp32 0.5.6 → 0.5.8

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 CHANGED
@@ -202,6 +202,103 @@ console.log(bip32.master_fingerprint); // "a1b2c3d4"
202
202
  console.log(bip32.path); // "m/44'/1900'/0'"
203
203
  ```
204
204
 
205
+ ### DePIN chat identity (sign/decrypt on the device)
206
+
207
+ The device holds a **dedicated DePIN chat identity** on BIP44 account `100'`
208
+ (`m/44'/<coin>'/100'/0/0`), separate from the funds account, so a wallet can
209
+ chat over Neurai DePIN messaging without ever exposing its mnemonic. Signing and
210
+ decryption happen **on the chip**.
211
+
212
+ Feature-detect first — `ping()` advertises `capabilities`: `"depin_identity"`
213
+ (identity + session) and `"depin_message"` (on-device `depinSign`/`depinDecrypt`).
214
+
215
+ ```javascript
216
+ const { capabilities = [] } = await device.ping();
217
+ if (!capabilities.includes("depin_identity")) throw new Error("update firmware");
218
+
219
+ // 1) Open a session on the channel token — ONE physical approval on the device.
220
+ // While active the device reveals its identity and auto-signs/decrypts on
221
+ // this channel (bounded by an idle timeout, a hard cap, and a rate limit).
222
+ const session = await device.depinSessionBegin("&NEURAI.CHAT", {
223
+ ttlMinutes: 15, // idle window (1–60, default 15)
224
+ ratePerMin: 100, // in-session sign/decrypt cap (default 100)
225
+ });
226
+ console.log(session.expires_in_s, session.max_session_s, session.rate_per_min);
227
+
228
+ // 2) Read the chat identity (no per-call prompt while the session is open).
229
+ // This is what a hardware wallet uses instead of deriving from a mnemonic.
230
+ const id = await device.getDepinIdentity();
231
+ console.log(id.address, id.pubkey, id.path, id.network); // "xna" | "xna-test"
232
+
233
+ // 3) Sign an outgoing message. The host does the recipient-pubkey ECIES
234
+ // encryption and passes the fields; the device builds the canonical
235
+ // CDepinMessage preimage and returns the DER signature.
236
+ const { signature, op_count } = await device.depinSign({
237
+ token: "&NEURAI.CHAT",
238
+ sender: id.address, // must equal the device's DePIN address
239
+ timestamp: Math.floor(Date.now() / 1000),
240
+ messageType: 1, // 1 = direct (DATA), 2 = group (BROADCAST)
241
+ encryptedPayload: eciesPayloadHex, // built host-side
242
+ });
243
+
244
+ // 4) Decrypt an incoming CDepinMessage addressed to this identity.
245
+ // GCM-authenticated; the sender's signature is verified host-side.
246
+ const { plaintext_b64 } = await device.depinDecrypt(cdepinMessageHex);
247
+
248
+ // 5) End the session when done (also revoked on lock / USB disconnect / timeout).
249
+ await device.depinSessionEnd();
250
+ ```
251
+
252
+ > **Note on time:** the device has no real-time clock, so it does **not** check
253
+ > the freshness of `timestamp` — the host supplies it and the chip only validates
254
+ > the message structure and channel/sender scope.
255
+
256
+ ### Provision an unconfigured device (`setup_seed`)
257
+
258
+ Firmware with the security layer boots **unconfigured** until a seed is stored
259
+ (and **locked** at every boot after that, until the owner enters the PIN on the
260
+ device). Instead of typing 12/24 words with two buttons, a host that holds the
261
+ mnemonic (e.g. it just generated the wallet) can push it over USB:
262
+
263
+ ```javascript
264
+ // 1) Where is the device at?
265
+ const state = await device.getDeviceState(); // "ready" | "locked" | "unconfigured"
266
+
267
+ if (state === "unconfigured") {
268
+ // 2) Send the seed. The owner must physically approve a SUMMARY on the
269
+ // device within 60 s (word count + network + key type — never the words).
270
+ const res = await device.setupSeed({
271
+ mnemonic: "word1 word2 ... word12", // 12 or 24 BIP39 words
272
+ network: "testnet", // REQUIRED: "mainnet" | "testnet"
273
+ keyType: "pq", // REQUIRED: "pq" | "legacy" (pq = testnet-only)
274
+ });
275
+ console.log(res.state); // "pin_required"
276
+
277
+ // 3) The owner now creates the PIN ON THE DEVICE (it never travels over
278
+ // USB). Poll until the seed is encrypted and the keys are derived:
279
+ await device.waitUntilReady(); // default: every 2 s, up to 5 min
280
+ }
281
+
282
+ // 4) Normal operation from here.
283
+ const info = await device.getInfo();
284
+ ```
285
+
286
+ Notes:
287
+
288
+ - `setup_seed` is **only accepted while no encrypted seed is stored** (first
289
+ boot, dev-fallback firmware, or after an on-device wipe). On a configured
290
+ device it throws `"Device already configured: wipe it on-device first"`
291
+ without prompting — it can never overwrite an existing wallet.
292
+ - If the owner rejects (or the 60 s pass) you get `"User cancelled"`; if they
293
+ cancel during PIN entry the device stays unconfigured and you can simply call
294
+ `setupSeed` again.
295
+ - `getDeviceState()` distinguishes `locked` (ask the user to enter the PIN on
296
+ the device) from `unconfigured` (provisioning applies) by parsing the
297
+ firmware's gate errors; it never prompts and is safe to poll.
298
+ - **Security:** the mnemonic transits the host OS and the USB link in
299
+ plaintext — acceptable when this host generated the seed, but entering the
300
+ words directly on the device remains the more private path.
301
+
205
302
  ## Post-Quantum (PQ / ML-DSA-44) support
206
303
 
207
304
  The device operates in one mode at a time, declared via `info` on two
@@ -474,16 +571,27 @@ using JSON messages. Supported commands:
474
571
  | Command | Confirmation | Timeout |
475
572
  |---|---|---|
476
573
  | `info` | None | 5s |
574
+ | `setup_seed` | Physical button (summary on screen) | 60s approval + on-device PIN entry |
477
575
  | `get_address` | Physical button | 30s |
478
576
  | `get_bip32_pubkey` | Physical button | 30s |
479
577
  | `sign_psbt` | Physical button + TX review | 60s |
480
578
  | `sign_tx` (PQ) | Physical button + TX review | per-heartbeat (ML-DSA is slow) |
481
579
  | `sign_message` | Physical button | 30s |
580
+ | `depin_session_begin` | Physical button (channel token on screen) | 30s |
581
+ | `get_depin_identity` | None (session-gated) | 10s |
582
+ | `depin_sign` | None (session-gated, rate-limited) | 30s |
583
+ | `depin_decrypt` | None (session-gated, rate-limited) | 30s |
584
+ | `depin_session_end` | None | 10s |
482
585
 
483
586
  `info` reports `key_type` (`"legacy"` | `"pq"`). In PQ mode, `get_address`
484
587
  returns only the public key (the library derives the address) and signing uses
485
588
  `sign_tx` (raw transaction) instead of `sign_psbt`.
486
589
 
590
+ While the device is **locked** (encrypted seed stored, PIN pending) or
591
+ **unconfigured** (no seed), the firmware rejects every command except
592
+ `setup_seed` with a distinct error message; `getDeviceState()` parses those
593
+ into `"locked"` / `"unconfigured"`.
594
+
487
595
  ## API
488
596
 
489
597
  ### `NeuraiESP32`
@@ -495,12 +603,20 @@ Main class for device interaction.
495
603
  | `connect()` | Open USB Serial connection (browser dialog) |
496
604
  | `disconnect()` | Close connection |
497
605
  | `ping()` | Detect/handshake the device (no confirmation, no wallet-identifying data) — use this to enumerate devices |
606
+ | `getDeviceState()` | `"ready"` \| `"locked"` \| `"unconfigured"` — safe to poll, no confirmation |
607
+ | `setupSeed({ mnemonic, network, keyType })` | Provision an unconfigured device with a host-held seed (owner approves on device, then sets the PIN there) |
608
+ | `waitUntilReady(opts?)` | Poll until the device is operational (after `setupSeed` PIN entry or unlock) |
498
609
  | `getInfo()` | Get device info incl. `key_type` (**requires confirmation** on consent-model firmware) |
499
610
  | `getAddress()` | Get address + pubkey (requires confirmation); derives the address from the pubkey + mode (legacy or PQ) |
500
611
  | `getBip32Pubkey()` | Get account xpub (requires confirmation) |
501
612
  | `signPsbt(base64)` | Sign a PSBT (requires confirmation) |
502
613
  | `signPsbt(base64, display?)` | Sign a PSBT and optionally send display metadata |
503
614
  | `signMessage(message)` | Sign a message to prove address ownership (requires confirmation) |
615
+ | `depinSessionBegin(token, opts?)` | Open a DePIN chat session on a channel token (one approval); enables identity read + auto sign/decrypt |
616
+ | `getDepinIdentity()` | Read the DePIN chat identity (address + pubkey + path); session-gated, no per-call prompt |
617
+ | `depinSign(params)` | Sign a DePIN message on-device (DER over the canonical CDepinMessage); session-gated, rate-limited |
618
+ | `depinDecrypt(depinMessageHex)` | Decrypt a CDepinMessage addressed to this identity → `plaintext_b64`; session-gated |
619
+ | `depinSessionEnd()` | End the DePIN session (also revoked on lock / disconnect / timeout) |
504
620
  | `signTransaction(opts)` | Build + sign + finalize in one call; auto-routes legacy (PSBT) vs PQ (`sign_tx`) by device mode |
505
621
  | `signPqTransaction(opts)` | Spend from a PQ address: build raw tx + sign via `sign_tx` (used internally by `signTransaction` in PQ mode) |
506
622
 
@@ -12950,6 +12950,85 @@ var NeuraiSignESP32Bundle = (function () {
12950
12950
  this.assertSuccess(response);
12951
12951
  return response;
12952
12952
  }
12953
+ /**
12954
+ * Coarse device state, derived from `ping` and the firmware's gate errors:
12955
+ * `ready` (keys derived, normal commands work), `locked` (encrypted seed
12956
+ * stored, PIN not entered yet — ask the user to unlock on the device) or
12957
+ * `unconfigured` (no seed stored — {@link setupSeed} or the on-device wizard
12958
+ * applies). Safe to poll; never prompts on the device.
12959
+ *
12960
+ * Firmware predating the security layer answers `ping` successfully in every
12961
+ * state, so it reports `ready`.
12962
+ */
12963
+ async getDeviceState() {
12964
+ const response = await this.serial.sendCommand({ action: "ping" }, 5000);
12965
+ if (response.status !== "error") {
12966
+ return "ready";
12967
+ }
12968
+ const message = (response.message ?? "").toLowerCase();
12969
+ if (message.includes("locked"))
12970
+ return "locked";
12971
+ if (message.includes("not configured"))
12972
+ return "unconfigured";
12973
+ throw new Error(`Device error: ${response.message}`);
12974
+ }
12975
+ /**
12976
+ * Provision an UNCONFIGURED device with a host-held mnemonic (`setup_seed`).
12977
+ *
12978
+ * The firmware only accepts this while **no encrypted seed is stored** (first
12979
+ * boot, dev-fallback mode, or after a wipe + reboot); on a configured device
12980
+ * it errors without prompting. The owner must physically approve a summary on
12981
+ * the device (word count + network + key type — the words are NEVER shown)
12982
+ * within 60 s, and then creates the PIN **on the device**: the PIN never
12983
+ * travels over USB. The seed transits the host and the USB link in plaintext
12984
+ * by design (this host generated it) — on-device entry remains the more
12985
+ * private path.
12986
+ *
12987
+ * Resolves with `{ state: "pin_required" }` once the owner approves. The
12988
+ * protocol has no push events, so detect completion by polling — see
12989
+ * {@link waitUntilReady}. If the owner cancels the PIN entry afterwards, the
12990
+ * device stays unconfigured and `setupSeed` can simply be called again.
12991
+ */
12992
+ async setupSeed(options) {
12993
+ // Client-side pre-checks for fast feedback; the device re-validates
12994
+ // everything (including the BIP39 checksum) authoritatively.
12995
+ const words = options.mnemonic.trim().split(/\s+/).filter(Boolean);
12996
+ if (words.length !== 12 && words.length !== 24) {
12997
+ throw new Error("Mnemonic must be 12 or 24 words");
12998
+ }
12999
+ if (options.keyType === "pq" && options.network !== "testnet") {
13000
+ throw new Error("PQ key type requires testnet");
13001
+ }
13002
+ // 60 s on-device approval window + margin.
13003
+ const response = await this.serial.sendCommand({
13004
+ action: "setup_seed",
13005
+ mnemonic: words.join(" "),
13006
+ network: options.network,
13007
+ key_type: options.keyType,
13008
+ }, 70000);
13009
+ this.assertSuccess(response);
13010
+ return response;
13011
+ }
13012
+ /**
13013
+ * Poll {@link getDeviceState} until the device reports `ready` — i.e. the
13014
+ * owner finished creating the PIN after {@link setupSeed} (or unlocked the
13015
+ * device) and the keys are derived. Resolves with the final state; throws on
13016
+ * timeout.
13017
+ */
13018
+ async waitUntilReady(options) {
13019
+ const pollMs = options?.pollMs ?? 2000;
13020
+ const timeoutMs = options?.timeoutMs ?? 300000;
13021
+ const start = Date.now();
13022
+ for (;;) {
13023
+ const state = await this.getDeviceState();
13024
+ if (state === "ready")
13025
+ return state;
13026
+ if (Date.now() - start > timeoutMs) {
13027
+ throw new Error(`Timed out waiting for device (last state: ${state})`);
13028
+ }
13029
+ await new Promise((resolve) => setTimeout(resolve, pollMs));
13030
+ }
13031
+ }
12953
13032
  /**
12954
13033
  * Read the device's wallet info (network, key_type, master fingerprint, address,
12955
13034
  * pubkey). As of the consent-model firmware this REQUIRES on-device approval and
@@ -13006,6 +13085,94 @@ var NeuraiSignESP32Bundle = (function () {
13006
13085
  this.assertSuccess(response);
13007
13086
  return response;
13008
13087
  }
13088
+ // ─── DePIN chat identity (hw-depin-protocol) ───────────────────────────────
13089
+ // The device holds a dedicated DePIN chat identity (BIP44 account 100') so a
13090
+ // wallet can chat over DePIN without ever exposing its mnemonic. All calls
13091
+ // below require the device unlocked (PIN entered on-device) and, except the
13092
+ // session opener, an active session. Feature-detect with `ping().capabilities`
13093
+ // ("depin_identity" for identity+session, "depin_message" for sign/decrypt).
13094
+ /**
13095
+ * Open a DePIN chat session on a channel token. Prompts the owner for ONE
13096
+ * physical approval; while active the device reveals its DePIN identity and
13097
+ * auto-signs/decrypts on that channel without a per-message prompt, bounded by
13098
+ * an idle timeout, a hard cap, and a per-minute rate limit. The session is
13099
+ * revoked on timeout, device lock, or USB disconnect.
13100
+ *
13101
+ * @param token Channel token (soulbound `&…` asset name) to scope the session.
13102
+ * @param options `ttlMinutes` idle window (1–60, default 15); `ratePerMin`
13103
+ * in-session sign/decrypt cap (default 100).
13104
+ */
13105
+ async depinSessionBegin(token, options) {
13106
+ const command = {
13107
+ action: "depin_session_begin",
13108
+ token,
13109
+ };
13110
+ if (options?.ttlMinutes !== undefined)
13111
+ command.ttl_minutes = options.ttlMinutes;
13112
+ if (options?.ratePerMin !== undefined)
13113
+ command.rate_per_min = options.ratePerMin;
13114
+ // Waits on a physical approval (up to ~30 s), like getInfo/getAddress.
13115
+ const response = await this.serial.sendCommand(command, 35000);
13116
+ this.assertSuccess(response);
13117
+ return response;
13118
+ }
13119
+ /**
13120
+ * Read the device's DePIN chat identity (address + compressed pubkey + BIP44
13121
+ * path). Requires an active session; no per-call prompt. This is the fix for
13122
+ * the hardware-wallet DePIN spinner: instead of deriving the identity from a
13123
+ * mnemonic the device doesn't expose, the wallet obtains it from the device.
13124
+ */
13125
+ async getDepinIdentity() {
13126
+ const response = await this.serial.sendCommand({ action: "get_depin_identity" }, 10000);
13127
+ this.assertSuccess(response);
13128
+ return response;
13129
+ }
13130
+ /**
13131
+ * Sign a DePIN chat message on the device. The host performs the recipient
13132
+ * public-key ECIES encryption and passes the resulting fields; the device
13133
+ * assembles the canonical CDepinMessage preimage and returns the DER
13134
+ * signature. `sender` MUST equal the device's DePIN address and `token` the
13135
+ * active session channel (the device rejects otherwise). Requires an active
13136
+ * session and the `depin_message` capability.
13137
+ *
13138
+ * @param params.messageType 1 = direct (DATA), 2 = group (BROADCAST).
13139
+ * @param params.encryptedPayload Hex ECIES payload built host-side.
13140
+ */
13141
+ async depinSign(params) {
13142
+ const response = await this.serial.sendCommand({
13143
+ action: "depin_sign",
13144
+ token: params.token,
13145
+ sender: params.sender,
13146
+ timestamp: params.timestamp,
13147
+ message_type: params.messageType,
13148
+ encrypted_payload: params.encryptedPayload,
13149
+ }, 35000);
13150
+ this.assertSuccess(response);
13151
+ return response;
13152
+ }
13153
+ /**
13154
+ * Decrypt a full serialized CDepinMessage addressed to this device, returning
13155
+ * the plaintext base64-encoded. GCM-authenticated; the sender's signature is
13156
+ * verified host-side (it needs the sender's on-chain pubkey). Returns a
13157
+ * `not_for_us` device error if this identity is not among the recipients.
13158
+ * Requires an active session and the `depin_message` capability.
13159
+ *
13160
+ * @param depinMessageHex Hex of the complete serialized CDepinMessage.
13161
+ */
13162
+ async depinDecrypt(depinMessageHex) {
13163
+ const response = await this.serial.sendCommand({ action: "depin_decrypt", depin_message: depinMessageHex }, 35000);
13164
+ this.assertSuccess(response);
13165
+ return response;
13166
+ }
13167
+ /**
13168
+ * End the current DePIN session: auto-sign/decrypt stops and the identity is
13169
+ * no longer revealed until a new {@link depinSessionBegin} approval. Safe to
13170
+ * call with no active session.
13171
+ */
13172
+ async depinSessionEnd() {
13173
+ const response = await this.serial.sendCommand({ action: "depin_session_end" }, 10000);
13174
+ this.assertSuccess(response);
13175
+ }
13009
13176
  async signPsbt(psbtBase64, display) {
13010
13177
  const response = await this.serial.sendCommandFinal({
13011
13178
  action: "sign_psbt",
package/dist/browser.js CHANGED
@@ -12947,6 +12947,85 @@ class NeuraiESP32 {
12947
12947
  this.assertSuccess(response);
12948
12948
  return response;
12949
12949
  }
12950
+ /**
12951
+ * Coarse device state, derived from `ping` and the firmware's gate errors:
12952
+ * `ready` (keys derived, normal commands work), `locked` (encrypted seed
12953
+ * stored, PIN not entered yet — ask the user to unlock on the device) or
12954
+ * `unconfigured` (no seed stored — {@link setupSeed} or the on-device wizard
12955
+ * applies). Safe to poll; never prompts on the device.
12956
+ *
12957
+ * Firmware predating the security layer answers `ping` successfully in every
12958
+ * state, so it reports `ready`.
12959
+ */
12960
+ async getDeviceState() {
12961
+ const response = await this.serial.sendCommand({ action: "ping" }, 5000);
12962
+ if (response.status !== "error") {
12963
+ return "ready";
12964
+ }
12965
+ const message = (response.message ?? "").toLowerCase();
12966
+ if (message.includes("locked"))
12967
+ return "locked";
12968
+ if (message.includes("not configured"))
12969
+ return "unconfigured";
12970
+ throw new Error(`Device error: ${response.message}`);
12971
+ }
12972
+ /**
12973
+ * Provision an UNCONFIGURED device with a host-held mnemonic (`setup_seed`).
12974
+ *
12975
+ * The firmware only accepts this while **no encrypted seed is stored** (first
12976
+ * boot, dev-fallback mode, or after a wipe + reboot); on a configured device
12977
+ * it errors without prompting. The owner must physically approve a summary on
12978
+ * the device (word count + network + key type — the words are NEVER shown)
12979
+ * within 60 s, and then creates the PIN **on the device**: the PIN never
12980
+ * travels over USB. The seed transits the host and the USB link in plaintext
12981
+ * by design (this host generated it) — on-device entry remains the more
12982
+ * private path.
12983
+ *
12984
+ * Resolves with `{ state: "pin_required" }` once the owner approves. The
12985
+ * protocol has no push events, so detect completion by polling — see
12986
+ * {@link waitUntilReady}. If the owner cancels the PIN entry afterwards, the
12987
+ * device stays unconfigured and `setupSeed` can simply be called again.
12988
+ */
12989
+ async setupSeed(options) {
12990
+ // Client-side pre-checks for fast feedback; the device re-validates
12991
+ // everything (including the BIP39 checksum) authoritatively.
12992
+ const words = options.mnemonic.trim().split(/\s+/).filter(Boolean);
12993
+ if (words.length !== 12 && words.length !== 24) {
12994
+ throw new Error("Mnemonic must be 12 or 24 words");
12995
+ }
12996
+ if (options.keyType === "pq" && options.network !== "testnet") {
12997
+ throw new Error("PQ key type requires testnet");
12998
+ }
12999
+ // 60 s on-device approval window + margin.
13000
+ const response = await this.serial.sendCommand({
13001
+ action: "setup_seed",
13002
+ mnemonic: words.join(" "),
13003
+ network: options.network,
13004
+ key_type: options.keyType,
13005
+ }, 70000);
13006
+ this.assertSuccess(response);
13007
+ return response;
13008
+ }
13009
+ /**
13010
+ * Poll {@link getDeviceState} until the device reports `ready` — i.e. the
13011
+ * owner finished creating the PIN after {@link setupSeed} (or unlocked the
13012
+ * device) and the keys are derived. Resolves with the final state; throws on
13013
+ * timeout.
13014
+ */
13015
+ async waitUntilReady(options) {
13016
+ const pollMs = options?.pollMs ?? 2000;
13017
+ const timeoutMs = options?.timeoutMs ?? 300000;
13018
+ const start = Date.now();
13019
+ for (;;) {
13020
+ const state = await this.getDeviceState();
13021
+ if (state === "ready")
13022
+ return state;
13023
+ if (Date.now() - start > timeoutMs) {
13024
+ throw new Error(`Timed out waiting for device (last state: ${state})`);
13025
+ }
13026
+ await new Promise((resolve) => setTimeout(resolve, pollMs));
13027
+ }
13028
+ }
12950
13029
  /**
12951
13030
  * Read the device's wallet info (network, key_type, master fingerprint, address,
12952
13031
  * pubkey). As of the consent-model firmware this REQUIRES on-device approval and
@@ -13003,6 +13082,94 @@ class NeuraiESP32 {
13003
13082
  this.assertSuccess(response);
13004
13083
  return response;
13005
13084
  }
13085
+ // ─── DePIN chat identity (hw-depin-protocol) ───────────────────────────────
13086
+ // The device holds a dedicated DePIN chat identity (BIP44 account 100') so a
13087
+ // wallet can chat over DePIN without ever exposing its mnemonic. All calls
13088
+ // below require the device unlocked (PIN entered on-device) and, except the
13089
+ // session opener, an active session. Feature-detect with `ping().capabilities`
13090
+ // ("depin_identity" for identity+session, "depin_message" for sign/decrypt).
13091
+ /**
13092
+ * Open a DePIN chat session on a channel token. Prompts the owner for ONE
13093
+ * physical approval; while active the device reveals its DePIN identity and
13094
+ * auto-signs/decrypts on that channel without a per-message prompt, bounded by
13095
+ * an idle timeout, a hard cap, and a per-minute rate limit. The session is
13096
+ * revoked on timeout, device lock, or USB disconnect.
13097
+ *
13098
+ * @param token Channel token (soulbound `&…` asset name) to scope the session.
13099
+ * @param options `ttlMinutes` idle window (1–60, default 15); `ratePerMin`
13100
+ * in-session sign/decrypt cap (default 100).
13101
+ */
13102
+ async depinSessionBegin(token, options) {
13103
+ const command = {
13104
+ action: "depin_session_begin",
13105
+ token,
13106
+ };
13107
+ if (options?.ttlMinutes !== undefined)
13108
+ command.ttl_minutes = options.ttlMinutes;
13109
+ if (options?.ratePerMin !== undefined)
13110
+ command.rate_per_min = options.ratePerMin;
13111
+ // Waits on a physical approval (up to ~30 s), like getInfo/getAddress.
13112
+ const response = await this.serial.sendCommand(command, 35000);
13113
+ this.assertSuccess(response);
13114
+ return response;
13115
+ }
13116
+ /**
13117
+ * Read the device's DePIN chat identity (address + compressed pubkey + BIP44
13118
+ * path). Requires an active session; no per-call prompt. This is the fix for
13119
+ * the hardware-wallet DePIN spinner: instead of deriving the identity from a
13120
+ * mnemonic the device doesn't expose, the wallet obtains it from the device.
13121
+ */
13122
+ async getDepinIdentity() {
13123
+ const response = await this.serial.sendCommand({ action: "get_depin_identity" }, 10000);
13124
+ this.assertSuccess(response);
13125
+ return response;
13126
+ }
13127
+ /**
13128
+ * Sign a DePIN chat message on the device. The host performs the recipient
13129
+ * public-key ECIES encryption and passes the resulting fields; the device
13130
+ * assembles the canonical CDepinMessage preimage and returns the DER
13131
+ * signature. `sender` MUST equal the device's DePIN address and `token` the
13132
+ * active session channel (the device rejects otherwise). Requires an active
13133
+ * session and the `depin_message` capability.
13134
+ *
13135
+ * @param params.messageType 1 = direct (DATA), 2 = group (BROADCAST).
13136
+ * @param params.encryptedPayload Hex ECIES payload built host-side.
13137
+ */
13138
+ async depinSign(params) {
13139
+ const response = await this.serial.sendCommand({
13140
+ action: "depin_sign",
13141
+ token: params.token,
13142
+ sender: params.sender,
13143
+ timestamp: params.timestamp,
13144
+ message_type: params.messageType,
13145
+ encrypted_payload: params.encryptedPayload,
13146
+ }, 35000);
13147
+ this.assertSuccess(response);
13148
+ return response;
13149
+ }
13150
+ /**
13151
+ * Decrypt a full serialized CDepinMessage addressed to this device, returning
13152
+ * the plaintext base64-encoded. GCM-authenticated; the sender's signature is
13153
+ * verified host-side (it needs the sender's on-chain pubkey). Returns a
13154
+ * `not_for_us` device error if this identity is not among the recipients.
13155
+ * Requires an active session and the `depin_message` capability.
13156
+ *
13157
+ * @param depinMessageHex Hex of the complete serialized CDepinMessage.
13158
+ */
13159
+ async depinDecrypt(depinMessageHex) {
13160
+ const response = await this.serial.sendCommand({ action: "depin_decrypt", depin_message: depinMessageHex }, 35000);
13161
+ this.assertSuccess(response);
13162
+ return response;
13163
+ }
13164
+ /**
13165
+ * End the current DePIN session: auto-sign/decrypt stops and the identity is
13166
+ * no longer revealed until a new {@link depinSessionBegin} approval. Safe to
13167
+ * call with no active session.
13168
+ */
13169
+ async depinSessionEnd() {
13170
+ const response = await this.serial.sendCommand({ action: "depin_session_end" }, 10000);
13171
+ this.assertSuccess(response);
13172
+ }
13006
13173
  async signPsbt(psbtBase64, display) {
13007
13174
  const response = await this.serial.sendCommandFinal({
13008
13175
  action: "sign_psbt",