@neuraiproject/neurai-sign-esp32 0.5.7 → 0.5.9

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,57 @@ 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
+
205
256
  ### Provision an unconfigured device (`setup_seed`)
206
257
 
207
258
  Firmware with the security layer boots **unconfigured** until a seed is stored
@@ -526,6 +577,12 @@ using JSON messages. Supported commands:
526
577
  | `sign_psbt` | Physical button + TX review | 60s |
527
578
  | `sign_tx` (PQ) | Physical button + TX review | per-heartbeat (ML-DSA is slow) |
528
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_decrypt_payload` | None (session-gated, rate-limited) | 30s |
585
+ | `depin_session_end` | None | 10s |
529
586
 
530
587
  `info` reports `key_type` (`"legacy"` | `"pq"`). In PQ mode, `get_address`
531
588
  returns only the public key (the library derives the address) and signing uses
@@ -556,6 +613,12 @@ Main class for device interaction.
556
613
  | `signPsbt(base64)` | Sign a PSBT (requires confirmation) |
557
614
  | `signPsbt(base64, display?)` | Sign a PSBT and optionally send display metadata |
558
615
  | `signMessage(message)` | Sign a message to prove address ownership (requires confirmation) |
616
+ | `depinSessionBegin(token, opts?)` | Open a DePIN chat session on a channel token (one approval); enables identity read + auto sign/decrypt |
617
+ | `getDepinIdentity()` | Read the DePIN chat identity (address + pubkey + path); session-gated, no per-call prompt |
618
+ | `depinSign(params)` | Sign a DePIN message on-device (DER over the canonical CDepinMessage); session-gated, rate-limited |
619
+ | `depinDecrypt(depinMessageHex)` | Decrypt a CDepinMessage addressed to this identity → `plaintext_b64`; session-gated |
620
+ | `depinDecryptPayload(encryptedPayloadHex)` | Decrypt a bare ECIES `encrypted_payload_hex` (decomposed server item) → `plaintext_b64`; session-gated |
621
+ | `depinSessionEnd()` | End the DePIN session (also revoked on lock / disconnect / timeout) |
559
622
  | `signTransaction(opts)` | Build + sign + finalize in one call; auto-routes legacy (PSBT) vs PQ (`sign_tx`) by device mode |
560
623
  | `signPqTransaction(opts)` | Spend from a PQ address: build raw tx + sign via `sign_tx` (used internally by `signTransaction` in PQ mode) |
561
624
 
@@ -592,7 +592,7 @@ var NeuraiSignESP32Bundle = (function () {
592
592
  function requireBuffer () {
593
593
  if (hasRequiredBuffer) return buffer;
594
594
  hasRequiredBuffer = 1;
595
- (function (exports$1) {
595
+ (function (exports) {
596
596
 
597
597
  const base64 = requireBase64Js();
598
598
  const ieee754 = requireIeee754();
@@ -601,12 +601,12 @@ var NeuraiSignESP32Bundle = (function () {
601
601
  ? Symbol['for']('nodejs.util.inspect.custom') // eslint-disable-line dot-notation
602
602
  : null;
603
603
 
604
- exports$1.Buffer = Buffer;
605
- exports$1.SlowBuffer = SlowBuffer;
606
- exports$1.INSPECT_MAX_BYTES = 50;
604
+ exports.Buffer = Buffer;
605
+ exports.SlowBuffer = SlowBuffer;
606
+ exports.INSPECT_MAX_BYTES = 50;
607
607
 
608
608
  const K_MAX_LENGTH = 0x7fffffff;
609
- exports$1.kMaxLength = K_MAX_LENGTH;
609
+ exports.kMaxLength = K_MAX_LENGTH;
610
610
 
611
611
  /**
612
612
  * If `Buffer.TYPED_ARRAY_SUPPORT`:
@@ -1202,7 +1202,7 @@ var NeuraiSignESP32Bundle = (function () {
1202
1202
 
1203
1203
  Buffer.prototype.inspect = function inspect () {
1204
1204
  let str = '';
1205
- const max = exports$1.INSPECT_MAX_BYTES;
1205
+ const max = exports.INSPECT_MAX_BYTES;
1206
1206
  str = this.toString('hex', 0, max).replace(/(.{2})/g, '$1 ').trim();
1207
1207
  if (this.length > max) str += ' ... ';
1208
1208
  return '<Buffer ' + str + '>'
@@ -3438,7 +3438,12 @@ var NeuraiSignESP32Bundle = (function () {
3438
3438
  }
3439
3439
 
3440
3440
  //#region src/storages/globalConfig/globalConfig.ts
3441
- let store$4;
3441
+ const DEFAULT_CONFIG = {
3442
+ lang: void 0,
3443
+ message: void 0,
3444
+ abortEarly: void 0,
3445
+ abortPipeEarly: void 0
3446
+ };
3442
3447
  /**
3443
3448
  * Returns the global configuration.
3444
3449
  *
@@ -3448,12 +3453,7 @@ var NeuraiSignESP32Bundle = (function () {
3448
3453
  */
3449
3454
  /* @__NO_SIDE_EFFECTS__ */
3450
3455
  function getGlobalConfig(config$1) {
3451
- return {
3452
- lang: store$4?.lang,
3453
- message: config$1?.message,
3454
- abortEarly: store$4?.abortEarly,
3455
- abortPipeEarly: store$4?.abortPipeEarly
3456
- };
3456
+ return DEFAULT_CONFIG;
3457
3457
  }
3458
3458
 
3459
3459
  //#endregion
@@ -3563,6 +3563,7 @@ var NeuraiSignESP32Bundle = (function () {
3563
3563
 
3564
3564
  //#endregion
3565
3565
  //#region src/utils/_getStandardProps/_getStandardProps.ts
3566
+ const _standardCache = /* @__PURE__ */ new WeakMap();
3566
3567
  /**
3567
3568
  * Returns the Standard Schema properties.
3568
3569
  *
@@ -3572,13 +3573,18 @@ var NeuraiSignESP32Bundle = (function () {
3572
3573
  */
3573
3574
  /* @__NO_SIDE_EFFECTS__ */
3574
3575
  function _getStandardProps(context) {
3575
- return {
3576
- version: 1,
3577
- vendor: "valibot",
3578
- validate(value$1) {
3579
- return context["~run"]({ value: value$1 }, /* @__PURE__ */ getGlobalConfig());
3580
- }
3581
- };
3576
+ let cached = _standardCache.get(context);
3577
+ if (!cached) {
3578
+ cached = {
3579
+ version: 1,
3580
+ vendor: "valibot",
3581
+ validate(value$1) {
3582
+ return context["~run"]({ value: value$1 }, /* @__PURE__ */ getGlobalConfig());
3583
+ }
3584
+ };
3585
+ _standardCache.set(context, cached);
3586
+ }
3587
+ return cached;
3582
3588
  }
3583
3589
 
3584
3590
  //#endregion
@@ -3713,6 +3719,10 @@ var NeuraiSignESP32Bundle = (function () {
3713
3719
  };
3714
3720
  }
3715
3721
 
3722
+ //#endregion
3723
+ //#region src/const.ts
3724
+ const ABORT_EARLY_CONFIG = { abortEarly: true };
3725
+
3716
3726
  //#endregion
3717
3727
  //#region src/methods/getFallback/getFallback.ts
3718
3728
  /**
@@ -3758,7 +3768,7 @@ var NeuraiSignESP32Bundle = (function () {
3758
3768
  */
3759
3769
  /* @__NO_SIDE_EFFECTS__ */
3760
3770
  function is(schema, input) {
3761
- return !schema["~run"]({ value: input }, { abortEarly: true }).issues;
3771
+ return !schema["~run"]({ value: input }, ABORT_EARLY_CONFIG).issues;
3762
3772
  }
3763
3773
 
3764
3774
  //#endregion
@@ -4170,7 +4180,7 @@ var NeuraiSignESP32Bundle = (function () {
4170
4180
  /* @__NO_SIDE_EFFECTS__ */
4171
4181
  function _subIssues(datasets) {
4172
4182
  let issues;
4173
- if (datasets) for (const dataset of datasets) if (issues) issues.push(...dataset.issues);
4183
+ if (datasets) for (const dataset of datasets) if (issues) for (const issue of dataset.issues) issues.push(issue);
4174
4184
  else issues = dataset.issues;
4175
4185
  return issues;
4176
4186
  }
@@ -4229,7 +4239,7 @@ var NeuraiSignESP32Bundle = (function () {
4229
4239
  * @returns The parsed input.
4230
4240
  */
4231
4241
  function parse(schema, input, config$1) {
4232
- const dataset = schema["~run"]({ value: input }, /* @__PURE__ */ getGlobalConfig(config$1));
4242
+ const dataset = schema["~run"]({ value: input }, /* @__PURE__ */ getGlobalConfig());
4233
4243
  if (dataset.issues) throw new ValiError(dataset.issues);
4234
4244
  return dataset.value;
4235
4245
  }
@@ -13075,6 +13085,108 @@ var NeuraiSignESP32Bundle = (function () {
13075
13085
  this.assertSuccess(response);
13076
13086
  return response;
13077
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
+ * Decrypt a BARE ECIES payload — the `encrypted_payload_hex` a DePIN server
13169
+ * returns per message (and the format of privacy-wrapped `{ encrypted }`
13170
+ * server responses) — without the surrounding CDepinMessage framing. Use this
13171
+ * when you have the decomposed server item rather than a full serialized
13172
+ * message (the common case for a chat client). Returns the plaintext
13173
+ * base64-encoded, or a `not_for_us` device error if not a recipient.
13174
+ * Requires an active session and the `depin_message` capability.
13175
+ */
13176
+ async depinDecryptPayload(encryptedPayloadHex) {
13177
+ const response = await this.serial.sendCommand({ action: "depin_decrypt_payload", encrypted_payload: encryptedPayloadHex }, 35000);
13178
+ this.assertSuccess(response);
13179
+ return response;
13180
+ }
13181
+ /**
13182
+ * End the current DePIN session: auto-sign/decrypt stops and the identity is
13183
+ * no longer revealed until a new {@link depinSessionBegin} approval. Safe to
13184
+ * call with no active session.
13185
+ */
13186
+ async depinSessionEnd() {
13187
+ const response = await this.serial.sendCommand({ action: "depin_session_end" }, 10000);
13188
+ this.assertSuccess(response);
13189
+ }
13078
13190
  async signPsbt(psbtBase64, display) {
13079
13191
  const response = await this.serial.sendCommandFinal({
13080
13192
  action: "sign_psbt",
package/dist/browser.js CHANGED
@@ -589,7 +589,7 @@ var hasRequiredBuffer;
589
589
  function requireBuffer () {
590
590
  if (hasRequiredBuffer) return buffer;
591
591
  hasRequiredBuffer = 1;
592
- (function (exports$1) {
592
+ (function (exports) {
593
593
 
594
594
  const base64 = requireBase64Js();
595
595
  const ieee754 = requireIeee754();
@@ -598,12 +598,12 @@ function requireBuffer () {
598
598
  ? Symbol['for']('nodejs.util.inspect.custom') // eslint-disable-line dot-notation
599
599
  : null;
600
600
 
601
- exports$1.Buffer = Buffer;
602
- exports$1.SlowBuffer = SlowBuffer;
603
- exports$1.INSPECT_MAX_BYTES = 50;
601
+ exports.Buffer = Buffer;
602
+ exports.SlowBuffer = SlowBuffer;
603
+ exports.INSPECT_MAX_BYTES = 50;
604
604
 
605
605
  const K_MAX_LENGTH = 0x7fffffff;
606
- exports$1.kMaxLength = K_MAX_LENGTH;
606
+ exports.kMaxLength = K_MAX_LENGTH;
607
607
 
608
608
  /**
609
609
  * If `Buffer.TYPED_ARRAY_SUPPORT`:
@@ -1199,7 +1199,7 @@ function requireBuffer () {
1199
1199
 
1200
1200
  Buffer.prototype.inspect = function inspect () {
1201
1201
  let str = '';
1202
- const max = exports$1.INSPECT_MAX_BYTES;
1202
+ const max = exports.INSPECT_MAX_BYTES;
1203
1203
  str = this.toString('hex', 0, max).replace(/(.{2})/g, '$1 ').trim();
1204
1204
  if (this.length > max) str += ' ... ';
1205
1205
  return '<Buffer ' + str + '>'
@@ -3435,7 +3435,12 @@ function encode$g(_number) {
3435
3435
  }
3436
3436
 
3437
3437
  //#region src/storages/globalConfig/globalConfig.ts
3438
- let store$4;
3438
+ const DEFAULT_CONFIG = {
3439
+ lang: void 0,
3440
+ message: void 0,
3441
+ abortEarly: void 0,
3442
+ abortPipeEarly: void 0
3443
+ };
3439
3444
  /**
3440
3445
  * Returns the global configuration.
3441
3446
  *
@@ -3445,12 +3450,7 @@ let store$4;
3445
3450
  */
3446
3451
  /* @__NO_SIDE_EFFECTS__ */
3447
3452
  function getGlobalConfig(config$1) {
3448
- return {
3449
- lang: store$4?.lang,
3450
- message: config$1?.message,
3451
- abortEarly: store$4?.abortEarly,
3452
- abortPipeEarly: store$4?.abortPipeEarly
3453
- };
3453
+ return DEFAULT_CONFIG;
3454
3454
  }
3455
3455
 
3456
3456
  //#endregion
@@ -3560,6 +3560,7 @@ function _addIssue(context, label, dataset, config$1, other) {
3560
3560
 
3561
3561
  //#endregion
3562
3562
  //#region src/utils/_getStandardProps/_getStandardProps.ts
3563
+ const _standardCache = /* @__PURE__ */ new WeakMap();
3563
3564
  /**
3564
3565
  * Returns the Standard Schema properties.
3565
3566
  *
@@ -3569,13 +3570,18 @@ function _addIssue(context, label, dataset, config$1, other) {
3569
3570
  */
3570
3571
  /* @__NO_SIDE_EFFECTS__ */
3571
3572
  function _getStandardProps(context) {
3572
- return {
3573
- version: 1,
3574
- vendor: "valibot",
3575
- validate(value$1) {
3576
- return context["~run"]({ value: value$1 }, /* @__PURE__ */ getGlobalConfig());
3577
- }
3578
- };
3573
+ let cached = _standardCache.get(context);
3574
+ if (!cached) {
3575
+ cached = {
3576
+ version: 1,
3577
+ vendor: "valibot",
3578
+ validate(value$1) {
3579
+ return context["~run"]({ value: value$1 }, /* @__PURE__ */ getGlobalConfig());
3580
+ }
3581
+ };
3582
+ _standardCache.set(context, cached);
3583
+ }
3584
+ return cached;
3579
3585
  }
3580
3586
 
3581
3587
  //#endregion
@@ -3710,6 +3716,10 @@ function minValue(requirement, message$1) {
3710
3716
  };
3711
3717
  }
3712
3718
 
3719
+ //#endregion
3720
+ //#region src/const.ts
3721
+ const ABORT_EARLY_CONFIG = { abortEarly: true };
3722
+
3713
3723
  //#endregion
3714
3724
  //#region src/methods/getFallback/getFallback.ts
3715
3725
  /**
@@ -3755,7 +3765,7 @@ function getDefault(schema, dataset, config$1) {
3755
3765
  */
3756
3766
  /* @__NO_SIDE_EFFECTS__ */
3757
3767
  function is(schema, input) {
3758
- return !schema["~run"]({ value: input }, { abortEarly: true }).issues;
3768
+ return !schema["~run"]({ value: input }, ABORT_EARLY_CONFIG).issues;
3759
3769
  }
3760
3770
 
3761
3771
  //#endregion
@@ -4167,7 +4177,7 @@ function tuple(items, message$1) {
4167
4177
  /* @__NO_SIDE_EFFECTS__ */
4168
4178
  function _subIssues(datasets) {
4169
4179
  let issues;
4170
- if (datasets) for (const dataset of datasets) if (issues) issues.push(...dataset.issues);
4180
+ if (datasets) for (const dataset of datasets) if (issues) for (const issue of dataset.issues) issues.push(issue);
4171
4181
  else issues = dataset.issues;
4172
4182
  return issues;
4173
4183
  }
@@ -4226,7 +4236,7 @@ function union(options, message$1) {
4226
4236
  * @returns The parsed input.
4227
4237
  */
4228
4238
  function parse(schema, input, config$1) {
4229
- const dataset = schema["~run"]({ value: input }, /* @__PURE__ */ getGlobalConfig(config$1));
4239
+ const dataset = schema["~run"]({ value: input }, /* @__PURE__ */ getGlobalConfig());
4230
4240
  if (dataset.issues) throw new ValiError(dataset.issues);
4231
4241
  return dataset.value;
4232
4242
  }
@@ -13072,6 +13082,108 @@ class NeuraiESP32 {
13072
13082
  this.assertSuccess(response);
13073
13083
  return response;
13074
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
+ * Decrypt a BARE ECIES payload — the `encrypted_payload_hex` a DePIN server
13166
+ * returns per message (and the format of privacy-wrapped `{ encrypted }`
13167
+ * server responses) — without the surrounding CDepinMessage framing. Use this
13168
+ * when you have the decomposed server item rather than a full serialized
13169
+ * message (the common case for a chat client). Returns the plaintext
13170
+ * base64-encoded, or a `not_for_us` device error if not a recipient.
13171
+ * Requires an active session and the `depin_message` capability.
13172
+ */
13173
+ async depinDecryptPayload(encryptedPayloadHex) {
13174
+ const response = await this.serial.sendCommand({ action: "depin_decrypt_payload", encrypted_payload: encryptedPayloadHex }, 35000);
13175
+ this.assertSuccess(response);
13176
+ return response;
13177
+ }
13178
+ /**
13179
+ * End the current DePIN session: auto-sign/decrypt stops and the identity is
13180
+ * no longer revealed until a new {@link depinSessionBegin} approval. Safe to
13181
+ * call with no active session.
13182
+ */
13183
+ async depinSessionEnd() {
13184
+ const response = await this.serial.sendCommand({ action: "depin_session_end" }, 10000);
13185
+ this.assertSuccess(response);
13186
+ }
13075
13187
  async signPsbt(psbtBase64, display) {
13076
13188
  const response = await this.serial.sendCommandFinal({
13077
13189
  action: "sign_psbt",