@onekeyfe/hd-transport 1.2.8-alpha.9 → 1.2.9

package/src/protocols/v2/session.ts

@@ -1,5 +1,6 @@
 import {
   PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS,
+  PROTOCOL_V2_FILE_WRITE_PIPELINE_WINDOW,
   PROTOCOL_V2_PACKET_SRC_COMMAND,
 } from '../../constants';
 import { ProtocolV2FrameAssembler, concatUint8Arrays } from './frame-assembler';
@@ -9,13 +10,18 @@ import {
   createProtocolV2LinkDisabledError,
   isProtocolV2LinkDisabledError,
   isProtocolV2LinkDisabledFailure,
+  isProtocolV2LinkError,
 } from './errors';
 import { ProtocolV2 } from '..';
 import * as check from '../../utils/highlevel-checks';
 import { LogBlockCommand } from '../../utils/logBlockCommand';
 
 import type { Root } from 'protobufjs/light';
-import type { MessageFromOneKey, TransportWriteMetrics } from '../../types';
+import type {
+  MessageFromOneKey,
+  ProtocolV2FileWritePipeline,
+  TransportWriteMetrics,
+} from '../../types';
 
 export * from './errors';
 
@@ -62,6 +68,7 @@ export type ProtocolV2CallOptions = {
   returnAfterWrite?: boolean;
   onResponseAfterWrite?: (response: MessageFromOneKey) => void;
   writeWithResponse?: boolean;
+  fileWritePipeline?: ProtocolV2FileWritePipeline;
 };
 
 export { concatUint8Arrays, ProtocolV2FrameAssembler };
@@ -214,6 +221,30 @@ export async function withProtocolTimeout<T>(
   }
 }
 
+const resolveProtocolV2CallTimeoutMs = (timeoutMs?: number) =>
+  timeoutMs && timeoutMs > 0 ? timeoutMs : PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS;
+
+function parseFileWriteChunk(request: Record<string, unknown>) {
+  const file = request.file as
+    | { path?: unknown; offset?: unknown; total_size?: unknown; data?: { byteLength?: unknown } }
+    | undefined;
+  const offset = Number(file?.offset);
+  const totalSize = Number(file?.total_size);
+  const length = Number(file?.data?.byteLength);
+  if (
+    typeof file?.path !== 'string' ||
+    !Number.isSafeInteger(offset) ||
+    offset < 0 ||
+    !Number.isSafeInteger(totalSize) ||
+    !Number.isSafeInteger(length) ||
+    length <= 0 ||
+    offset + length > totalSize
+  ) {
+    throw new Error('Protocol V2 file write pipeline chunk is invalid');
+  }
+  return { path: file.path, offset, end: offset + length, totalSize };
+}
+
 export class ProtocolV2Session {
   private readonly options: ProtocolV2SessionOptions;
 
@@ -293,28 +324,46 @@ export class ProtocolV2Session {
     return result;
   }
 
+  private reportWriteCompleted(
+    callOptions: ProtocolV2CallOptions,
+    writeStartedAt: number,
+    frameBytes: number
+  ) {
+    try {
+      callOptions.onWriteCompleted?.({
+        elapsedMs: Math.max(Date.now() - writeStartedAt, 0),
+        frameBytes,
+      });
+    } catch (error) {
+      const { logger, logPrefix = 'ProtocolV2' } = this.options;
+      logger?.error?.(`${logPrefix} write metrics callback failed: ${String(error)}`);
+    }
+  }
+
+  private createCallTimeoutError(name: string, timeoutMs: number): Error {
+    const { createTimeoutError } = this.options;
+    return createTimeoutError
+      ? createTimeoutError(name, timeoutMs)
+      : new Error(`Protocol V2 response timeout after ${timeoutMs}ms for ${name}`);
+  }
+
   private executeCall(
     name: string,
     data: Record<string, unknown>,
     callOptions: ProtocolV2CallOptions
   ): Promise<MessageFromOneKey> {
+    if (callOptions.fileWritePipeline) {
+      return this.executeFileWritePipeline(name, data, callOptions, callOptions.fileWritePipeline);
+    }
     const {
-      schemas,
-      router,
-      packetSrc = PROTOCOL_V2_PACKET_SRC_COMMAND,
-      maxFrameBytes,
       prepareCall,
       writeFrame,
       readFrame,
       logger,
       logPrefix = 'ProtocolV2',
-      createTimeoutError,
       generation = 0,
     } = this.options;
-    const timeoutMs =
-      callOptions.timeoutMs && callOptions.timeoutMs > 0
-        ? callOptions.timeoutMs
-        : PROTOCOL_V2_DEFAULT_RESPONSE_TIMEOUT_MS;
+    const timeoutMs = resolveProtocolV2CallTimeoutMs(callOptions.timeoutMs);
     const abortController = new AbortController();
 
     const shouldReduceDebug = shouldReduceProtocolV2Debug(name);
@@ -335,29 +384,11 @@ export class ProtocolV2Session {
       if (!this.pendingResponseAfterWrite) {
         await prepareCall?.(baseCallContext);
       }
-      const protoSeq = this.sequenceCursor.next();
-      const frame = ProtocolV2.encodeFrame(schemas, name, data, {
-        packetSrc,
-        router,
-        seq: protoSeq,
-      });
-
-      if (maxFrameBytes !== undefined && frame.length > maxFrameBytes) {
-        throw new Error(
-          `Protocol V2 frame too large for transport: ${frame.length} > ${maxFrameBytes}`
-        );
-      }
+      const { seq: protoSeq, frame } = this.encodeRequestFrame(name, data);
 
       const writeStartedAt = Date.now();
       await this.serializeWrite(() => writeFrame(frame, baseCallContext));
-      try {
-        callOptions.onWriteCompleted?.({
-          elapsedMs: Math.max(Date.now() - writeStartedAt, 0),
-          frameBytes: frame.byteLength,
-        });
-      } catch (error) {
-        logger?.error?.(`${logPrefix} write metrics callback failed: ${String(error)}`);
-      }
+      this.reportWriteCompleted(callOptions, writeStartedAt, frame.byteLength);
 
       if (callOptions.returnAfterWrite) {
         if (callOptions.expectedTypes?.length) {
@@ -376,68 +407,8 @@ export class ProtocolV2Session {
         const rxFrame = await readFrame(baseCallContext);
         if (abortController.signal.aborted) break;
 
-        let header: ReturnType<typeof ProtocolV2.inspectFrameHeader>;
-        try {
-          header = ProtocolV2.inspectFrameHeader(rxFrame);
-        } catch (cause) {
-          throw new ProtocolV2LinkError(
-            'frame',
-            `Protocol V2 frame validation failed: ${getErrorMessage(cause)}`,
-            cause
-          );
-        }
-        if (header.router !== router) {
-          throw new ProtocolV2LinkError(
-            'router',
-            `Protocol V2 router mismatch: expected ${router}, got ${header.router}`
-          );
-        }
-        if (header.packetSrc !== packetSrc) {
-          throw new ProtocolV2LinkError(
-            'packet-source',
-            `Protocol V2 packet source mismatch: expected ${packetSrc}, got ${header.packetSrc}`
-          );
-        }
-
-        let isAck: boolean;
-        try {
-          isAck = ProtocolV2.isAckFrame(rxFrame);
-        } catch (cause) {
-          throw new ProtocolV2LinkError(
-            'frame',
-            `Protocol V2 ACK validation failed: ${getErrorMessage(cause)}`,
-            cause
-          );
-        }
-        if (isAck) {
-          if (header.seq !== protoSeq) {
-            throw new ProtocolV2LinkError(
-              'ack-sequence',
-              `Protocol V2 ACK sequence mismatch: expected ${protoSeq}, got ${header.seq}`
-            );
-          }
-        } else {
-          let decoded: ReturnType<typeof ProtocolV2.decodeFrame>;
-          try {
-            decoded = ProtocolV2.decodeFrame(schemas, rxFrame);
-          } catch (cause) {
-            throw new ProtocolV2LinkError(
-              'frame',
-              `Protocol V2 frame decode failed: ${getErrorMessage(cause)}`,
-              cause
-            );
-          }
-          // Firmware owns one TX sequence across all channels and packet sources,
-          // so frames routed elsewhere create valid gaps in this session.
-          if (this.lastResponseSequence === decoded.seq) {
-            throw new ProtocolV2LinkError(
-              'response-sequence',
-              `Protocol V2 duplicate response sequence: ${decoded.seq}`
-            );
-          }
-          this.lastResponseSequence = decoded.seq;
-
-          const response = check.call(decoded);
+        const response = this.parseResponseFrame(rxFrame, [protoSeq]);
+        if (response) {
           const { pendingResponseAfterWrite } = this;
           let belongsToWriteOnlyCall = false;
           if (pendingResponseAfterWrite) {
@@ -477,15 +448,274 @@ export class ProtocolV2Session {
     return withProtocolTimeout(
       runCall(),
       timeoutMs,
-      () =>
-        createTimeoutError
-          ? createTimeoutError(name, timeoutMs)
-          : new Error(`Protocol V2 response timeout after ${timeoutMs}ms for ${name}`),
+      () => this.createCallTimeoutError(name, timeoutMs),
       () => {
         abortController.abort();
       }
     );
   }
+
+  private encodeRequestFrame(name: string, data: Record<string, unknown>) {
+    const {
+      schemas,
+      router,
+      packetSrc = PROTOCOL_V2_PACKET_SRC_COMMAND,
+      maxFrameBytes,
+    } = this.options;
+    const seq = this.sequenceCursor.next();
+    const frame = ProtocolV2.encodeFrame(schemas, name, data, { packetSrc, router, seq });
+    if (maxFrameBytes !== undefined && frame.length > maxFrameBytes) {
+      throw new Error(
+        `Protocol V2 frame too large for transport: ${frame.length} > ${maxFrameBytes}`
+      );
+    }
+    return { seq, frame };
+  }
+
+  /**
+   * Validates one received frame for this session. Returns undefined for an ACK of one of
+   * `ackSequences`, otherwise the decoded response.
+   */
+  private parseResponseFrame(
+    rxFrame: Uint8Array,
+    ackSequences: readonly number[]
+  ): MessageFromOneKey | undefined {
+    const { schemas, router, packetSrc = PROTOCOL_V2_PACKET_SRC_COMMAND } = this.options;
+    let header: ReturnType<typeof ProtocolV2.inspectFrameHeader>;
+    try {
+      header = ProtocolV2.inspectFrameHeader(rxFrame);
+    } catch (cause) {
+      throw new ProtocolV2LinkError(
+        'frame',
+        `Protocol V2 frame validation failed: ${getErrorMessage(cause)}`,
+        cause
+      );
+    }
+    if (header.router !== router) {
+      throw new ProtocolV2LinkError(
+        'router',
+        `Protocol V2 router mismatch: expected ${router}, got ${header.router}`
+      );
+    }
+    if (header.packetSrc !== packetSrc) {
+      throw new ProtocolV2LinkError(
+        'packet-source',
+        `Protocol V2 packet source mismatch: expected ${packetSrc}, got ${header.packetSrc}`
+      );
+    }
+
+    let isAck: boolean;
+    try {
+      isAck = ProtocolV2.isAckFrame(rxFrame);
+    } catch (cause) {
+      throw new ProtocolV2LinkError(
+        'frame',
+        `Protocol V2 ACK validation failed: ${getErrorMessage(cause)}`,
+        cause
+      );
+    }
+    if (isAck) {
+      if (!ackSequences.includes(header.seq)) {
+        throw new ProtocolV2LinkError(
+          'ack-sequence',
+          `Protocol V2 ACK sequence mismatch: expected ${ackSequences.join('|')}, got ${header.seq}`
+        );
+      }
+      return undefined;
+    }
+
+    let decoded: ReturnType<typeof ProtocolV2.decodeFrame>;
+    try {
+      decoded = ProtocolV2.decodeFrame(schemas, rxFrame);
+    } catch (cause) {
+      throw new ProtocolV2LinkError(
+        'frame',
+        `Protocol V2 frame decode failed: ${getErrorMessage(cause)}`,
+        cause
+      );
+    }
+    // Firmware owns one TX sequence across all channels and packet sources,
+    // so frames routed elsewhere create valid gaps in this session.
+    if (this.lastResponseSequence === decoded.seq) {
+      throw new ProtocolV2LinkError(
+        'response-sequence',
+        `Protocol V2 duplicate response sequence: ${decoded.seq}`
+      );
+    }
+    this.lastResponseSequence = decoded.seq;
+    return check.call(decoded);
+  }
+
+  /**
+   * Writes one file as ordered FilesystemFileWrite chunks while keeping up to
+   * PROTOCOL_V2_FILE_WRITE_PIPELINE_WINDOW chunks in flight. Firmware still processes and
+   * answers every chunk in order, so responses are matched to chunks by position. Upstream
+   * bootloaders append at their own cursor without checking the request offset, so the echoed
+   * offset is what exposes a lost chunk. A device Failure, or `next` returning undefined, stops
+   * sending; the remaining in-flight responses are drained so the link stays usable.
+   */
+  private async executeFileWritePipeline(
+    name: string,
+    data: Record<string, unknown>,
+    callOptions: ProtocolV2CallOptions,
+    pipeline: ProtocolV2FileWritePipeline
+  ): Promise<MessageFromOneKey> {
+    if (name !== 'FilesystemFileWrite') {
+      throw new Error(`Protocol V2 file write pipeline does not support ${name}`);
+    }
+    if (this.pendingResponseAfterWrite) {
+      throw new Error('Protocol V2 file write pipeline cannot start while a response is pending');
+    }
+    const { prepareCall, writeFrame, readFrame, generation = 0 } = this.options;
+    const timeoutMs = resolveProtocolV2CallTimeoutMs(callOptions.timeoutMs);
+    const abortController = new AbortController();
+    const context: ProtocolV2CallContext = {
+      messageName: name,
+      timeoutMs,
+      highThroughput: true,
+      ...(callOptions.writeWithResponse === undefined
+        ? {}
+        : { writeWithResponse: callOptions.writeWithResponse }),
+      generation,
+      signal: abortController.signal,
+    };
+    // Transport errors and timeouts propagate unchanged: each transport classifies its own.
+    let transportFailure: unknown;
+    // One file can take far longer than one chunk, so the watchdog bounds each step instead.
+    const withStepTimeout = <T>(promise: Promise<T>, stepTimeoutMs = timeoutMs) =>
+      withProtocolTimeout(
+        promise,
+        stepTimeoutMs,
+        () => this.createCallTimeoutError(name, timeoutMs),
+        () => {
+          abortController.abort();
+        }
+      ).catch((error: unknown) => {
+        transportFailure = error;
+        throw error;
+      });
+    // ACKs and skipped frames must not extend the wait for an in-flight chunk's response.
+    let progressDeadline = 0;
+    const markProgress = () => {
+      progressDeadline = Date.now() + timeoutMs;
+    };
+
+    const inFlight: Array<{ seq: number; offset: number; end: number }> = [];
+    let path: string | undefined;
+    let totalSize: number | undefined;
+    let nextOffset: number | undefined;
+    let sourceDone = false;
+    let failure: MessageFromOneKey | undefined;
+    let lastConfirmed: MessageFromOneKey | undefined;
+
+    const sendChunk = async (request: Record<string, unknown>) => {
+      const chunk = parseFileWriteChunk(request);
+      if (path !== undefined && (chunk.path !== path || chunk.totalSize !== totalSize)) {
+        throw new Error('Protocol V2 file write pipeline chunk belongs to a different file');
+      }
+      if (nextOffset !== undefined && chunk.offset !== nextOffset) {
+        throw new Error(
+          `Protocol V2 file write pipeline chunk out of order: expected offset ${nextOffset}, got ${chunk.offset}`
+        );
+      }
+      path = chunk.path;
+      totalSize = chunk.totalSize;
+      nextOffset = chunk.end;
+
+      const { seq, frame } = this.encodeRequestFrame(name, request);
+      const writeStartedAt = Date.now();
+      await withStepTimeout(this.serializeWrite(() => writeFrame(frame, context)));
+      inFlight.push({ seq, offset: chunk.offset, end: chunk.end });
+      markProgress();
+      this.reportWriteCompleted(callOptions, writeStartedAt, frame.byteLength);
+    };
+    const sendNextChunk = async () => {
+      const request = await pipeline.next();
+      if (!request) {
+        sourceDone = true;
+        return;
+      }
+      await sendChunk(request);
+    };
+
+    await withStepTimeout(Promise.resolve().then(() => prepareCall?.(context)));
+    try {
+      await sendChunk(data);
+      while (!sourceDone && inFlight.length < PROTOCOL_V2_FILE_WRITE_PIPELINE_WINDOW) {
+        await sendNextChunk();
+      }
+
+      while (inFlight.length > 0) {
+        // Floor at 1 ms: withProtocolTimeout treats 0 as "no timeout", so an expired deadline
+        // must still time out.
+        const rxFrame = await withStepTimeout(
+          readFrame(context),
+          Math.max(progressDeadline - Date.now(), 1)
+        );
+        const response = this.parseResponseFrame(
+          rxFrame,
+          inFlight.map(item => item.seq)
+        );
+        if (!response) {
+          // ACK of an in-flight chunk; its FilesystemFile response follows.
+        } else if (response.type === 'FilesystemFile') {
+          const [expected] = inFlight;
+          const { message } = response;
+          if (
+            Number(message.processed_byte) !== expected.end ||
+            message.path !== path ||
+            Number(message.offset) !== expected.offset ||
+            Number(message.total_size) !== totalSize
+          ) {
+            throw new ProtocolV2LinkError(
+              'frame',
+              `Protocol V2 file write response does not match chunk ${expected.offset}-${
+                expected.end
+              }: got offset ${String(message.offset)} processed_byte ${String(
+                message.processed_byte
+              )}`
+            );
+          }
+          inFlight.shift();
+          markProgress();
+          if (!failure) {
+            lastConfirmed = response;
+            pipeline.onResponse(response);
+            if (!sourceDone) {
+              await sendNextChunk();
+            }
+          }
+        } else if (response.type === 'Failure') {
+          inFlight.shift();
+          markProgress();
+          failure = failure ?? response;
+          sourceDone = true;
+        } else if (COMMON_TERMINAL_RESPONSE_TYPES.has(response.type)) {
+          throw new ProtocolV2LinkError(
+            'frame',
+            `Protocol V2 file write pipeline received unexpected ${response.type}`
+          );
+        }
+      }
+    } catch (error) {
+      // Unread responses of in-flight chunks would answer the next call on this link, so a
+      // session or caller error raised with chunks in flight must invalidate it.
+      if (inFlight.length === 0 || error === transportFailure || isProtocolV2LinkError(error)) {
+        throw error;
+      }
+      throw new ProtocolV2LinkError(
+        'frame',
+        `Protocol V2 file write pipeline aborted with chunks in flight: ${getErrorMessage(error)}`,
+        error
+      );
+    }
+
+    const terminal = failure ?? lastConfirmed;
+    if (!terminal) {
+      throw new ProtocolV2LinkError('frame', 'Protocol V2 file write pipeline ended unconfirmed');
+    }
+    return terminal;
+  }
 }
 
 export async function probeProtocolV2({

package/src/types/messages.ts

@@ -4554,6 +4554,28 @@ export enum CommandFlags {
   Factory_Only = 1,
 }
 
+export enum Enum_CanonicalBitcoinNetwork {
+  BITCOIN_MAINNET = 0,
+  BITCOIN_TESTNET = 1,
+  BITCOIN_SIGNET = 2,
+  BITCOIN_REGTEST = 3,
+}
+export type CanonicalBitcoinNetwork = keyof typeof Enum_CanonicalBitcoinNetwork;
+
+// BabylonDeriveContextHash
+export type BabylonDeriveContextHash = {
+  address_n: number[];
+  script_type: InputScriptType;
+  app_name: string;
+  context: string;
+  network: CanonicalBitcoinNetwork;
+};
+
+// BabylonDerivedContextHash
+export type BabylonDerivedContextHash = {
+  secret: string;
+};
+
 export type TextMemo = {
   text: string;
 };
@@ -4658,6 +4680,70 @@ export type UiAnimationRequest = {
   type?: UiAnimationType;
 };
 
+export enum ZcashAddressType {
+  UNIFIED_ORCHARD_P2PKH = 0,
+  TRANSPARENT_P2PKH = 1,
+  UNIFIED_ORCHARD = 2,
+}
+
+export enum ZcashAddressScope {
+  EXTERNAL = 0,
+  INTERNAL = 1,
+}
+
+// ZcashGetAddress
+export type ZcashGetAddress = {
+  address_n: number[];
+  show_display?: boolean;
+  include_seed_fingerprint?: boolean;
+  diversifier_index?: number;
+  address_type?: ZcashAddressType;
+  scope?: ZcashAddressScope;
+};
+
+// ZcashAddress
+export type ZcashAddress = {
+  address: string;
+  seed_fingerprint?: string;
+};
+
+// ZcashGetFullViewingKey
+export type ZcashGetFullViewingKey = {
+  address_n: number[];
+};
+
+// ZcashFullViewingKey
+export type ZcashFullViewingKey = {
+  ufvk: string;
+};
+
+// ZcashSignPczt
+export type ZcashSignPczt = {
+  pczt_length: number;
+  pczt_initial_chunk: string;
+};
+
+// ZcashPcztChunkRequest
+export type ZcashPcztChunkRequest = {
+  chunk_length: number;
+};
+
+// ZcashPcztChunkAck
+export type ZcashPcztChunkAck = {
+  data_chunk: string;
+};
+
+// ZcashSignedPczt
+export type ZcashSignedPczt = {
+  pczt_length: number;
+  pczt_initial_chunk: string;
+};
+
+// ZcashSignedPcztChunkRequest
+export type ZcashSignedPcztChunkRequest = {
+  chunk_length: number;
+};
+
 // experimental_message
 export type experimental_message = {};
 
@@ -5949,6 +6035,8 @@ export type MessageType = {
   TronSignMessage: TronSignMessage;
   TronMessageSignature: TronMessageSignature;
   facotry: facotry;
+  BabylonDeriveContextHash: BabylonDeriveContextHash;
+  BabylonDerivedContextHash: BabylonDerivedContextHash;
   TextMemo: TextMemo;
   RefundMemo: RefundMemo;
   CoinPurchaseMemo: CoinPurchaseMemo;
@@ -5964,6 +6052,15 @@ export type MessageType = {
   UnlockPath: UnlockPath;
   UnlockedPathRequest: UnlockedPathRequest;
   UiAnimationRequest: UiAnimationRequest;
+  ZcashGetAddress: ZcashGetAddress;
+  ZcashAddress: ZcashAddress;
+  ZcashGetFullViewingKey: ZcashGetFullViewingKey;
+  ZcashFullViewingKey: ZcashFullViewingKey;
+  ZcashSignPczt: ZcashSignPczt;
+  ZcashPcztChunkRequest: ZcashPcztChunkRequest;
+  ZcashPcztChunkAck: ZcashPcztChunkAck;
+  ZcashSignedPczt: ZcashSignedPczt;
+  ZcashSignedPcztChunkRequest: ZcashSignedPcztChunkRequest;
   experimental_message: experimental_message;
   experimental_field: experimental_field;
   ProtocolInfoRequest: ProtocolInfoRequest;

package/src/types/transport.ts

@@ -34,6 +34,12 @@ export type OneKeyDeviceInfoWithSession = OneKeyUsbDeviceInfo & {
 export type OneKeyMobileDeviceInfo = {
   id: string;
   name: string | null;
+  /**
+   * Color letter of the serial number ('A'-'Z') from the Pro2 / Neo BLE advertisement,
+   * possibly seen in an earlier scan. Set by the React Native and Electron BLE
+   * transports; absent when unknown.
+   */
+  bleColorCode?: string;
 };
 
 export type OneKeyDeviceInfoBase = {
@@ -70,6 +76,19 @@ export type TransportWriteMetrics = {
   frameBytes: number;
 };
 
+/**
+ * Supplies the remaining chunks of one file for an ordered FilesystemFileWrite pipeline.
+ * The call's request data is the first chunk; `next` returns the following chunk in offset
+ * order, or undefined to stop. The call then resolves with the last confirmation (or the
+ * device Failure), so the caller must check `processed_byte` for completeness. Callbacks
+ * should not throw: an error escapes with chunks still in flight and invalidates the link.
+ */
+export type ProtocolV2FileWritePipeline = {
+  next: () => Promise<Record<string, unknown> | undefined>;
+  /** Called for each chunk after the device confirms it, in offset order. */
+  onResponse: (response: MessageFromOneKey) => void;
+};
+
 export type TransportCallOptions = {
   timeoutMs?: number;
   expectedTypes?: string[];
@@ -83,6 +102,12 @@ export type TransportCallOptions = {
   onResponseAfterWrite?: (response: MessageFromOneKey) => void;
   /** Prefer acknowledged BLE characteristic writes for this call when supported. */
   writeWithResponse?: boolean;
+  /**
+   * Protocol V2 only: keep up to PROTOCOL_V2_FILE_WRITE_PIPELINE_WINDOW ordered
+   * FilesystemFileWrite frames of one file in flight within this call. `timeoutMs`
+   * bounds each frame write and each response instead of the whole file.
+   */
+  fileWritePipeline?: ProtocolV2FileWritePipeline;
 };
 
 type ITransportInitFn = (