@neuraiproject/neurai-sign-esp32 0.5.6 → 0.5.7

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,52 @@ console.log(bip32.master_fingerprint); // "a1b2c3d4"
202
202
  console.log(bip32.path); // "m/44'/1900'/0'"
203
203
  ```
204
204
 
205
+ ### Provision an unconfigured device (`setup_seed`)
206
+
207
+ Firmware with the security layer boots **unconfigured** until a seed is stored
208
+ (and **locked** at every boot after that, until the owner enters the PIN on the
209
+ device). Instead of typing 12/24 words with two buttons, a host that holds the
210
+ mnemonic (e.g. it just generated the wallet) can push it over USB:
211
+
212
+ ```javascript
213
+ // 1) Where is the device at?
214
+ const state = await device.getDeviceState(); // "ready" | "locked" | "unconfigured"
215
+
216
+ if (state === "unconfigured") {
217
+ // 2) Send the seed. The owner must physically approve a SUMMARY on the
218
+ // device within 60 s (word count + network + key type — never the words).
219
+ const res = await device.setupSeed({
220
+ mnemonic: "word1 word2 ... word12", // 12 or 24 BIP39 words
221
+ network: "testnet", // REQUIRED: "mainnet" | "testnet"
222
+ keyType: "pq", // REQUIRED: "pq" | "legacy" (pq = testnet-only)
223
+ });
224
+ console.log(res.state); // "pin_required"
225
+
226
+ // 3) The owner now creates the PIN ON THE DEVICE (it never travels over
227
+ // USB). Poll until the seed is encrypted and the keys are derived:
228
+ await device.waitUntilReady(); // default: every 2 s, up to 5 min
229
+ }
230
+
231
+ // 4) Normal operation from here.
232
+ const info = await device.getInfo();
233
+ ```
234
+
235
+ Notes:
236
+
237
+ - `setup_seed` is **only accepted while no encrypted seed is stored** (first
238
+ boot, dev-fallback firmware, or after an on-device wipe). On a configured
239
+ device it throws `"Device already configured: wipe it on-device first"`
240
+ without prompting — it can never overwrite an existing wallet.
241
+ - If the owner rejects (or the 60 s pass) you get `"User cancelled"`; if they
242
+ cancel during PIN entry the device stays unconfigured and you can simply call
243
+ `setupSeed` again.
244
+ - `getDeviceState()` distinguishes `locked` (ask the user to enter the PIN on
245
+ the device) from `unconfigured` (provisioning applies) by parsing the
246
+ firmware's gate errors; it never prompts and is safe to poll.
247
+ - **Security:** the mnemonic transits the host OS and the USB link in
248
+ plaintext — acceptable when this host generated the seed, but entering the
249
+ words directly on the device remains the more private path.
250
+
205
251
  ## Post-Quantum (PQ / ML-DSA-44) support
206
252
 
207
253
  The device operates in one mode at a time, declared via `info` on two
@@ -474,6 +520,7 @@ using JSON messages. Supported commands:
474
520
  | Command | Confirmation | Timeout |
475
521
  |---|---|---|
476
522
  | `info` | None | 5s |
523
+ | `setup_seed` | Physical button (summary on screen) | 60s approval + on-device PIN entry |
477
524
  | `get_address` | Physical button | 30s |
478
525
  | `get_bip32_pubkey` | Physical button | 30s |
479
526
  | `sign_psbt` | Physical button + TX review | 60s |
@@ -484,6 +531,11 @@ using JSON messages. Supported commands:
484
531
  returns only the public key (the library derives the address) and signing uses
485
532
  `sign_tx` (raw transaction) instead of `sign_psbt`.
486
533
 
534
+ While the device is **locked** (encrypted seed stored, PIN pending) or
535
+ **unconfigured** (no seed), the firmware rejects every command except
536
+ `setup_seed` with a distinct error message; `getDeviceState()` parses those
537
+ into `"locked"` / `"unconfigured"`.
538
+
487
539
  ## API
488
540
 
489
541
  ### `NeuraiESP32`
@@ -495,6 +547,9 @@ Main class for device interaction.
495
547
  | `connect()` | Open USB Serial connection (browser dialog) |
496
548
  | `disconnect()` | Close connection |
497
549
  | `ping()` | Detect/handshake the device (no confirmation, no wallet-identifying data) — use this to enumerate devices |
550
+ | `getDeviceState()` | `"ready"` \| `"locked"` \| `"unconfigured"` — safe to poll, no confirmation |
551
+ | `setupSeed({ mnemonic, network, keyType })` | Provision an unconfigured device with a host-held seed (owner approves on device, then sets the PIN there) |
552
+ | `waitUntilReady(opts?)` | Poll until the device is operational (after `setupSeed` PIN entry or unlock) |
498
553
  | `getInfo()` | Get device info incl. `key_type` (**requires confirmation** on consent-model firmware) |
499
554
  | `getAddress()` | Get address + pubkey (requires confirmation); derives the address from the pubkey + mode (legacy or PQ) |
500
555
  | `getBip32Pubkey()` | Get account xpub (requires confirmation) |
@@ -592,7 +592,7 @@ var NeuraiSignESP32Bundle = (function () {
592
592
  function requireBuffer () {
593
593
  if (hasRequiredBuffer) return buffer;
594
594
  hasRequiredBuffer = 1;
595
- (function (exports) {
595
+ (function (exports$1) {
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.Buffer = Buffer;
605
- exports.SlowBuffer = SlowBuffer;
606
- exports.INSPECT_MAX_BYTES = 50;
604
+ exports$1.Buffer = Buffer;
605
+ exports$1.SlowBuffer = SlowBuffer;
606
+ exports$1.INSPECT_MAX_BYTES = 50;
607
607
 
608
608
  const K_MAX_LENGTH = 0x7fffffff;
609
- exports.kMaxLength = K_MAX_LENGTH;
609
+ exports$1.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.INSPECT_MAX_BYTES;
1205
+ const max = exports$1.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,12 +3438,7 @@ var NeuraiSignESP32Bundle = (function () {
3438
3438
  }
3439
3439
 
3440
3440
  //#region src/storages/globalConfig/globalConfig.ts
3441
- const DEFAULT_CONFIG = {
3442
- lang: void 0,
3443
- message: void 0,
3444
- abortEarly: void 0,
3445
- abortPipeEarly: void 0
3446
- };
3441
+ let store$4;
3447
3442
  /**
3448
3443
  * Returns the global configuration.
3449
3444
  *
@@ -3453,7 +3448,12 @@ var NeuraiSignESP32Bundle = (function () {
3453
3448
  */
3454
3449
  /* @__NO_SIDE_EFFECTS__ */
3455
3450
  function getGlobalConfig(config$1) {
3456
- return DEFAULT_CONFIG;
3451
+ return {
3452
+ lang: store$4?.lang,
3453
+ message: config$1?.message,
3454
+ abortEarly: store$4?.abortEarly,
3455
+ abortPipeEarly: store$4?.abortPipeEarly
3456
+ };
3457
3457
  }
3458
3458
 
3459
3459
  //#endregion
@@ -3563,7 +3563,6 @@ var NeuraiSignESP32Bundle = (function () {
3563
3563
 
3564
3564
  //#endregion
3565
3565
  //#region src/utils/_getStandardProps/_getStandardProps.ts
3566
- const _standardCache = /* @__PURE__ */ new WeakMap();
3567
3566
  /**
3568
3567
  * Returns the Standard Schema properties.
3569
3568
  *
@@ -3573,18 +3572,13 @@ var NeuraiSignESP32Bundle = (function () {
3573
3572
  */
3574
3573
  /* @__NO_SIDE_EFFECTS__ */
3575
3574
  function _getStandardProps(context) {
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;
3575
+ return {
3576
+ version: 1,
3577
+ vendor: "valibot",
3578
+ validate(value$1) {
3579
+ return context["~run"]({ value: value$1 }, /* @__PURE__ */ getGlobalConfig());
3580
+ }
3581
+ };
3588
3582
  }
3589
3583
 
3590
3584
  //#endregion
@@ -3719,10 +3713,6 @@ var NeuraiSignESP32Bundle = (function () {
3719
3713
  };
3720
3714
  }
3721
3715
 
3722
- //#endregion
3723
- //#region src/const.ts
3724
- const ABORT_EARLY_CONFIG = { abortEarly: true };
3725
-
3726
3716
  //#endregion
3727
3717
  //#region src/methods/getFallback/getFallback.ts
3728
3718
  /**
@@ -3768,7 +3758,7 @@ var NeuraiSignESP32Bundle = (function () {
3768
3758
  */
3769
3759
  /* @__NO_SIDE_EFFECTS__ */
3770
3760
  function is(schema, input) {
3771
- return !schema["~run"]({ value: input }, ABORT_EARLY_CONFIG).issues;
3761
+ return !schema["~run"]({ value: input }, { abortEarly: true }).issues;
3772
3762
  }
3773
3763
 
3774
3764
  //#endregion
@@ -4180,7 +4170,7 @@ var NeuraiSignESP32Bundle = (function () {
4180
4170
  /* @__NO_SIDE_EFFECTS__ */
4181
4171
  function _subIssues(datasets) {
4182
4172
  let issues;
4183
- if (datasets) for (const dataset of datasets) if (issues) for (const issue of dataset.issues) issues.push(issue);
4173
+ if (datasets) for (const dataset of datasets) if (issues) issues.push(...dataset.issues);
4184
4174
  else issues = dataset.issues;
4185
4175
  return issues;
4186
4176
  }
@@ -4239,7 +4229,7 @@ var NeuraiSignESP32Bundle = (function () {
4239
4229
  * @returns The parsed input.
4240
4230
  */
4241
4231
  function parse(schema, input, config$1) {
4242
- const dataset = schema["~run"]({ value: input }, /* @__PURE__ */ getGlobalConfig());
4232
+ const dataset = schema["~run"]({ value: input }, /* @__PURE__ */ getGlobalConfig(config$1));
4243
4233
  if (dataset.issues) throw new ValiError(dataset.issues);
4244
4234
  return dataset.value;
4245
4235
  }
@@ -12950,6 +12940,85 @@ var NeuraiSignESP32Bundle = (function () {
12950
12940
  this.assertSuccess(response);
12951
12941
  return response;
12952
12942
  }
12943
+ /**
12944
+ * Coarse device state, derived from `ping` and the firmware's gate errors:
12945
+ * `ready` (keys derived, normal commands work), `locked` (encrypted seed
12946
+ * stored, PIN not entered yet — ask the user to unlock on the device) or
12947
+ * `unconfigured` (no seed stored — {@link setupSeed} or the on-device wizard
12948
+ * applies). Safe to poll; never prompts on the device.
12949
+ *
12950
+ * Firmware predating the security layer answers `ping` successfully in every
12951
+ * state, so it reports `ready`.
12952
+ */
12953
+ async getDeviceState() {
12954
+ const response = await this.serial.sendCommand({ action: "ping" }, 5000);
12955
+ if (response.status !== "error") {
12956
+ return "ready";
12957
+ }
12958
+ const message = (response.message ?? "").toLowerCase();
12959
+ if (message.includes("locked"))
12960
+ return "locked";
12961
+ if (message.includes("not configured"))
12962
+ return "unconfigured";
12963
+ throw new Error(`Device error: ${response.message}`);
12964
+ }
12965
+ /**
12966
+ * Provision an UNCONFIGURED device with a host-held mnemonic (`setup_seed`).
12967
+ *
12968
+ * The firmware only accepts this while **no encrypted seed is stored** (first
12969
+ * boot, dev-fallback mode, or after a wipe + reboot); on a configured device
12970
+ * it errors without prompting. The owner must physically approve a summary on
12971
+ * the device (word count + network + key type — the words are NEVER shown)
12972
+ * within 60 s, and then creates the PIN **on the device**: the PIN never
12973
+ * travels over USB. The seed transits the host and the USB link in plaintext
12974
+ * by design (this host generated it) — on-device entry remains the more
12975
+ * private path.
12976
+ *
12977
+ * Resolves with `{ state: "pin_required" }` once the owner approves. The
12978
+ * protocol has no push events, so detect completion by polling — see
12979
+ * {@link waitUntilReady}. If the owner cancels the PIN entry afterwards, the
12980
+ * device stays unconfigured and `setupSeed` can simply be called again.
12981
+ */
12982
+ async setupSeed(options) {
12983
+ // Client-side pre-checks for fast feedback; the device re-validates
12984
+ // everything (including the BIP39 checksum) authoritatively.
12985
+ const words = options.mnemonic.trim().split(/\s+/).filter(Boolean);
12986
+ if (words.length !== 12 && words.length !== 24) {
12987
+ throw new Error("Mnemonic must be 12 or 24 words");
12988
+ }
12989
+ if (options.keyType === "pq" && options.network !== "testnet") {
12990
+ throw new Error("PQ key type requires testnet");
12991
+ }
12992
+ // 60 s on-device approval window + margin.
12993
+ const response = await this.serial.sendCommand({
12994
+ action: "setup_seed",
12995
+ mnemonic: words.join(" "),
12996
+ network: options.network,
12997
+ key_type: options.keyType,
12998
+ }, 70000);
12999
+ this.assertSuccess(response);
13000
+ return response;
13001
+ }
13002
+ /**
13003
+ * Poll {@link getDeviceState} until the device reports `ready` — i.e. the
13004
+ * owner finished creating the PIN after {@link setupSeed} (or unlocked the
13005
+ * device) and the keys are derived. Resolves with the final state; throws on
13006
+ * timeout.
13007
+ */
13008
+ async waitUntilReady(options) {
13009
+ const pollMs = options?.pollMs ?? 2000;
13010
+ const timeoutMs = options?.timeoutMs ?? 300000;
13011
+ const start = Date.now();
13012
+ for (;;) {
13013
+ const state = await this.getDeviceState();
13014
+ if (state === "ready")
13015
+ return state;
13016
+ if (Date.now() - start > timeoutMs) {
13017
+ throw new Error(`Timed out waiting for device (last state: ${state})`);
13018
+ }
13019
+ await new Promise((resolve) => setTimeout(resolve, pollMs));
13020
+ }
13021
+ }
12953
13022
  /**
12954
13023
  * Read the device's wallet info (network, key_type, master fingerprint, address,
12955
13024
  * pubkey). As of the consent-model firmware this REQUIRES on-device approval and
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) {
592
+ (function (exports$1) {
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.Buffer = Buffer;
602
- exports.SlowBuffer = SlowBuffer;
603
- exports.INSPECT_MAX_BYTES = 50;
601
+ exports$1.Buffer = Buffer;
602
+ exports$1.SlowBuffer = SlowBuffer;
603
+ exports$1.INSPECT_MAX_BYTES = 50;
604
604
 
605
605
  const K_MAX_LENGTH = 0x7fffffff;
606
- exports.kMaxLength = K_MAX_LENGTH;
606
+ exports$1.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.INSPECT_MAX_BYTES;
1202
+ const max = exports$1.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,12 +3435,7 @@ function encode$g(_number) {
3435
3435
  }
3436
3436
 
3437
3437
  //#region src/storages/globalConfig/globalConfig.ts
3438
- const DEFAULT_CONFIG = {
3439
- lang: void 0,
3440
- message: void 0,
3441
- abortEarly: void 0,
3442
- abortPipeEarly: void 0
3443
- };
3438
+ let store$4;
3444
3439
  /**
3445
3440
  * Returns the global configuration.
3446
3441
  *
@@ -3450,7 +3445,12 @@ const DEFAULT_CONFIG = {
3450
3445
  */
3451
3446
  /* @__NO_SIDE_EFFECTS__ */
3452
3447
  function getGlobalConfig(config$1) {
3453
- return DEFAULT_CONFIG;
3448
+ return {
3449
+ lang: store$4?.lang,
3450
+ message: config$1?.message,
3451
+ abortEarly: store$4?.abortEarly,
3452
+ abortPipeEarly: store$4?.abortPipeEarly
3453
+ };
3454
3454
  }
3455
3455
 
3456
3456
  //#endregion
@@ -3560,7 +3560,6 @@ 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();
3564
3563
  /**
3565
3564
  * Returns the Standard Schema properties.
3566
3565
  *
@@ -3570,18 +3569,13 @@ const _standardCache = /* @__PURE__ */ new WeakMap();
3570
3569
  */
3571
3570
  /* @__NO_SIDE_EFFECTS__ */
3572
3571
  function _getStandardProps(context) {
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;
3572
+ return {
3573
+ version: 1,
3574
+ vendor: "valibot",
3575
+ validate(value$1) {
3576
+ return context["~run"]({ value: value$1 }, /* @__PURE__ */ getGlobalConfig());
3577
+ }
3578
+ };
3585
3579
  }
3586
3580
 
3587
3581
  //#endregion
@@ -3716,10 +3710,6 @@ function minValue(requirement, message$1) {
3716
3710
  };
3717
3711
  }
3718
3712
 
3719
- //#endregion
3720
- //#region src/const.ts
3721
- const ABORT_EARLY_CONFIG = { abortEarly: true };
3722
-
3723
3713
  //#endregion
3724
3714
  //#region src/methods/getFallback/getFallback.ts
3725
3715
  /**
@@ -3765,7 +3755,7 @@ function getDefault(schema, dataset, config$1) {
3765
3755
  */
3766
3756
  /* @__NO_SIDE_EFFECTS__ */
3767
3757
  function is(schema, input) {
3768
- return !schema["~run"]({ value: input }, ABORT_EARLY_CONFIG).issues;
3758
+ return !schema["~run"]({ value: input }, { abortEarly: true }).issues;
3769
3759
  }
3770
3760
 
3771
3761
  //#endregion
@@ -4177,7 +4167,7 @@ function tuple(items, message$1) {
4177
4167
  /* @__NO_SIDE_EFFECTS__ */
4178
4168
  function _subIssues(datasets) {
4179
4169
  let issues;
4180
- if (datasets) for (const dataset of datasets) if (issues) for (const issue of dataset.issues) issues.push(issue);
4170
+ if (datasets) for (const dataset of datasets) if (issues) issues.push(...dataset.issues);
4181
4171
  else issues = dataset.issues;
4182
4172
  return issues;
4183
4173
  }
@@ -4236,7 +4226,7 @@ function union(options, message$1) {
4236
4226
  * @returns The parsed input.
4237
4227
  */
4238
4228
  function parse(schema, input, config$1) {
4239
- const dataset = schema["~run"]({ value: input }, /* @__PURE__ */ getGlobalConfig());
4229
+ const dataset = schema["~run"]({ value: input }, /* @__PURE__ */ getGlobalConfig(config$1));
4240
4230
  if (dataset.issues) throw new ValiError(dataset.issues);
4241
4231
  return dataset.value;
4242
4232
  }
@@ -12947,6 +12937,85 @@ class NeuraiESP32 {
12947
12937
  this.assertSuccess(response);
12948
12938
  return response;
12949
12939
  }
12940
+ /**
12941
+ * Coarse device state, derived from `ping` and the firmware's gate errors:
12942
+ * `ready` (keys derived, normal commands work), `locked` (encrypted seed
12943
+ * stored, PIN not entered yet — ask the user to unlock on the device) or
12944
+ * `unconfigured` (no seed stored — {@link setupSeed} or the on-device wizard
12945
+ * applies). Safe to poll; never prompts on the device.
12946
+ *
12947
+ * Firmware predating the security layer answers `ping` successfully in every
12948
+ * state, so it reports `ready`.
12949
+ */
12950
+ async getDeviceState() {
12951
+ const response = await this.serial.sendCommand({ action: "ping" }, 5000);
12952
+ if (response.status !== "error") {
12953
+ return "ready";
12954
+ }
12955
+ const message = (response.message ?? "").toLowerCase();
12956
+ if (message.includes("locked"))
12957
+ return "locked";
12958
+ if (message.includes("not configured"))
12959
+ return "unconfigured";
12960
+ throw new Error(`Device error: ${response.message}`);
12961
+ }
12962
+ /**
12963
+ * Provision an UNCONFIGURED device with a host-held mnemonic (`setup_seed`).
12964
+ *
12965
+ * The firmware only accepts this while **no encrypted seed is stored** (first
12966
+ * boot, dev-fallback mode, or after a wipe + reboot); on a configured device
12967
+ * it errors without prompting. The owner must physically approve a summary on
12968
+ * the device (word count + network + key type — the words are NEVER shown)
12969
+ * within 60 s, and then creates the PIN **on the device**: the PIN never
12970
+ * travels over USB. The seed transits the host and the USB link in plaintext
12971
+ * by design (this host generated it) — on-device entry remains the more
12972
+ * private path.
12973
+ *
12974
+ * Resolves with `{ state: "pin_required" }` once the owner approves. The
12975
+ * protocol has no push events, so detect completion by polling — see
12976
+ * {@link waitUntilReady}. If the owner cancels the PIN entry afterwards, the
12977
+ * device stays unconfigured and `setupSeed` can simply be called again.
12978
+ */
12979
+ async setupSeed(options) {
12980
+ // Client-side pre-checks for fast feedback; the device re-validates
12981
+ // everything (including the BIP39 checksum) authoritatively.
12982
+ const words = options.mnemonic.trim().split(/\s+/).filter(Boolean);
12983
+ if (words.length !== 12 && words.length !== 24) {
12984
+ throw new Error("Mnemonic must be 12 or 24 words");
12985
+ }
12986
+ if (options.keyType === "pq" && options.network !== "testnet") {
12987
+ throw new Error("PQ key type requires testnet");
12988
+ }
12989
+ // 60 s on-device approval window + margin.
12990
+ const response = await this.serial.sendCommand({
12991
+ action: "setup_seed",
12992
+ mnemonic: words.join(" "),
12993
+ network: options.network,
12994
+ key_type: options.keyType,
12995
+ }, 70000);
12996
+ this.assertSuccess(response);
12997
+ return response;
12998
+ }
12999
+ /**
13000
+ * Poll {@link getDeviceState} until the device reports `ready` — i.e. the
13001
+ * owner finished creating the PIN after {@link setupSeed} (or unlocked the
13002
+ * device) and the keys are derived. Resolves with the final state; throws on
13003
+ * timeout.
13004
+ */
13005
+ async waitUntilReady(options) {
13006
+ const pollMs = options?.pollMs ?? 2000;
13007
+ const timeoutMs = options?.timeoutMs ?? 300000;
13008
+ const start = Date.now();
13009
+ for (;;) {
13010
+ const state = await this.getDeviceState();
13011
+ if (state === "ready")
13012
+ return state;
13013
+ if (Date.now() - start > timeoutMs) {
13014
+ throw new Error(`Timed out waiting for device (last state: ${state})`);
13015
+ }
13016
+ await new Promise((resolve) => setTimeout(resolve, pollMs));
13017
+ }
13018
+ }
12950
13019
  /**
12951
13020
  * Read the device's wallet info (network, key_type, master fingerprint, address,
12952
13021
  * pubkey). As of the consent-model firmware this REQUIRES on-device approval and