@onekeyfe/hd-transport 1.2.0-alpha.2 → 1.2.0-alpha.20

package/src/protocols/v2/session.ts

@@ -1,6 +1,6 @@
 import { PROTOCOL_V2_PACKET_SRC_COMMAND } from '../../constants';
 import { ProtocolV2FrameAssembler, concatUint8Arrays } from './frame-assembler';
-import { nextProtoSeq } from './encode';
+import { ProtocolV2SequenceCursor } from './sequence-cursor';
 import { ProtocolV2 } from '..';
 import * as check from '../../utils/highlevel-checks';
 import { LogBlockCommand } from '../../utils/logBlockCommand';
@@ -13,6 +13,13 @@ export type ProtocolV2Schemas = {
   protocolV2: Root;
 };
 
+export type ProtocolV2CallContext = {
+  messageName: string;
+  timeoutMs?: number;
+  highVolume: boolean;
+  generation: number;
+};
+
 type ProtocolLogger = {
   debug?: (...args: any[]) => void;
   error?: (...args: any[]) => void;
@@ -22,11 +29,17 @@ export type ProtocolV2SessionOptions = {
   schemas: ProtocolV2Schemas;
   router: number;
   packetSrc?: number;
-  writeFrame: (frame: Uint8Array) => Promise<void>;
-  readFrame: () => Promise<Uint8Array>;
+  maxFrameBytes?: number;
+  prepareCall?: (context: ProtocolV2CallContext) => Promise<void> | void;
+  writeFrame: (frame: Uint8Array, context: ProtocolV2CallContext) => Promise<void>;
+  readFrame: (context: ProtocolV2CallContext) => Promise<Uint8Array>;
   logger?: ProtocolLogger;
   logPrefix?: string;
   createTimeoutError?: (name: string, timeoutMs: number) => Error;
+  sequenceCursor?: ProtocolV2SequenceCursor;
+  generation?: number;
+  writeTimeoutMs?: number;
+  deliveryTimeoutMs?: number;
 };
 
 export type ProtocolV2CallOptions = {
@@ -37,6 +50,7 @@ export type ProtocolV2CallOptions = {
 };
 
 export { concatUint8Arrays, ProtocolV2FrameAssembler };
+export { ProtocolV2SequenceCursor };
 
 export function hexToBytes(hex: string): Uint8Array {
   const clean = hex.replace(/\s+/g, '');
@@ -59,15 +73,6 @@ export function bytesToHex(bytes: Uint8Array): string {
     .join('');
 }
 
-// Frame header bytes worth logging: SOF, len lo/hi, header CRC, router, attr, seq.
-// The rest of the frame is protobuf payload and may contain sensitive fields
-// (mnemonic words via WordAck, PINs, seeds via LoadDevice, ...), so raw frame
-// hex logs must never include it.
-const PROTOCOL_V2_DEBUG_HEADER_BYTES = 7;
-const PROTOCOL_V2_DEBUG_ARRAY_ITEMS_LIMIT = 20;
-const PROTOCOL_V2_DEBUG_OBJECT_KEYS_LIMIT = 40;
-const PROTOCOL_V2_DEBUG_STRING_LIMIT = 512;
-const PROTOCOL_V2_DEBUG_DEPTH_LIMIT = 4;
 const HIGH_VOLUME_PROTOCOL_V2_CALLS = new Set([
   ...LogBlockCommand,
   'FilesystemFileRead',
@@ -79,102 +84,6 @@ function shouldReduceProtocolV2Debug(name: string) {
   return HIGH_VOLUME_PROTOCOL_V2_CALLS.has(name);
 }
 
-function frameHeaderDebugHex(frame: Uint8Array): string {
-  // Only the frame header is dumped as hex; the payload is logged separately
-  // in sanitized/structured form (sanitizeProtocolV2DebugPayload).
-  return bytesToHex(frame.slice(0, PROTOCOL_V2_DEBUG_HEADER_BYTES));
-}
-
-function getBinaryByteLength(value: unknown): number | undefined {
-  if (value instanceof ArrayBuffer) {
-    return value.byteLength;
-  }
-
-  if (ArrayBuffer.isView(value)) {
-    return value.byteLength;
-  }
-
-  if (typeof Blob !== 'undefined' && value instanceof Blob) {
-    return value.size;
-  }
-
-  return undefined;
-}
-
-function summarizeRedactedData(value: unknown): string {
-  const byteLength = getBinaryByteLength(value);
-  if (byteLength !== undefined) {
-    return `[redacted data: ${byteLength} bytes]`;
-  }
-
-  if (typeof value === 'string') {
-    return `[redacted data: string length=${value.length}]`;
-  }
-
-  if (Array.isArray(value)) {
-    return `[redacted data: array length=${value.length}]`;
-  }
-
-  if (value && typeof value === 'object') {
-    return `[redacted data: object keys=${Object.keys(value).length}]`;
-  }
-
-  return `[redacted data: ${typeof value}]`;
-}
-
-function sanitizeProtocolV2DebugPayload(value: unknown, key = '', depth = 0): unknown {
-  if (/^(data|payload)$/i.test(key) && value !== null && value !== undefined) {
-    return summarizeRedactedData(value);
-  }
-
-  if (/(passphrase|pin|mnemonic|seed|private)/i.test(key)) {
-    return '[redacted sensitive value]';
-  }
-
-  const byteLength = getBinaryByteLength(value);
-  if (byteLength !== undefined) {
-    return `[binary: ${byteLength} bytes]`;
-  }
-
-  if (typeof value === 'string') {
-    return value.length > PROTOCOL_V2_DEBUG_STRING_LIMIT
-      ? `${value.slice(0, PROTOCOL_V2_DEBUG_STRING_LIMIT)}... (len=${value.length})`
-      : value;
-  }
-
-  if (!value || typeof value !== 'object') {
-    return value;
-  }
-
-  if (depth >= PROTOCOL_V2_DEBUG_DEPTH_LIMIT) {
-    return Array.isArray(value)
-      ? `[array length=${value.length}]`
-      : `[object keys=${Object.keys(value).length}]`;
-  }
-
-  if (Array.isArray(value)) {
-    const items = value
-      .slice(0, PROTOCOL_V2_DEBUG_ARRAY_ITEMS_LIMIT)
-      .map(item => sanitizeProtocolV2DebugPayload(item, key, depth + 1));
-    if (value.length > PROTOCOL_V2_DEBUG_ARRAY_ITEMS_LIMIT) {
-      items.push(`... (${value.length - PROTOCOL_V2_DEBUG_ARRAY_ITEMS_LIMIT} more)`);
-    }
-    return items;
-  }
-
-  const entries = Object.entries(value).slice(0, PROTOCOL_V2_DEBUG_OBJECT_KEYS_LIMIT);
-  const sanitized: Record<string, unknown> = {};
-  entries.forEach(([entryKey, entryValue]) => {
-    sanitized[entryKey] = sanitizeProtocolV2DebugPayload(entryValue, entryKey, depth + 1);
-  });
-  if (Object.keys(value).length > PROTOCOL_V2_DEBUG_OBJECT_KEYS_LIMIT) {
-    sanitized.__truncated__ = `${
-      Object.keys(value).length - PROTOCOL_V2_DEBUG_OBJECT_KEYS_LIMIT
-    } more keys`;
-  }
-  return sanitized;
-}
-
 const COMMON_TERMINAL_RESPONSE_TYPES = new Set([
   'Failure',
   'ButtonRequest',
@@ -229,24 +138,24 @@ export async function withProtocolTimeout<T>(
   }
 }
 
-// Watchdog for the write phase only. Writing a single frame (max 4608 bytes)
-// is a bounded transport operation, unlike the read phase where long-running
-// device operations (firmware install, user confirmation) can legitimately
-// take minutes — so no default timeout is applied to reads.
-export const PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS = 30000;
+// A transport write must never keep the serialized device queue pending forever.
+// Callers must classify a timeout as link-fatal and reset the physical adapter so
+// the losing Promise cannot continue on the next connection generation.
+export const PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS = 30_000;
+export const PROTOCOL_V2_DELIVERY_WATCHDOG_TIMEOUT_MS = 5_000;
 
 export class ProtocolV2Session {
   private readonly options: ProtocolV2SessionOptions;
 
+  private readonly sequenceCursor: ProtocolV2SequenceCursor;
+
   // Serializes call() invocations: responses are matched only by type, so two
   // in-flight calls on the same session would steal each other's responses.
   private pendingCall: Promise<unknown> = Promise.resolve();
 
-  // Per-session sequence counter (1-255, wraps skipping 0).
-  private protoSeq = 0;
-
   constructor(options: ProtocolV2SessionOptions) {
     this.options = options;
+    this.sequenceCursor = options.sequenceCursor ?? new ProtocolV2SequenceCursor();
   }
 
   call(
@@ -271,46 +180,57 @@ export class ProtocolV2Session {
       schemas,
       router,
       packetSrc = PROTOCOL_V2_PACKET_SRC_COMMAND,
+      maxFrameBytes,
+      prepareCall,
       writeFrame,
       readFrame,
       logger,
       logPrefix = 'ProtocolV2',
       createTimeoutError,
+      generation = 0,
+      writeTimeoutMs = PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS,
+      deliveryTimeoutMs = PROTOCOL_V2_DELIVERY_WATCHDOG_TIMEOUT_MS,
     } = this.options;
 
     const shouldReduceDebug = shouldReduceProtocolV2Debug(name);
-    this.protoSeq = nextProtoSeq(this.protoSeq);
+    const callContext: ProtocolV2CallContext = {
+      messageName: name,
+      timeoutMs: callOptions.timeoutMs,
+      highVolume: shouldReduceDebug,
+      generation,
+    };
+    await prepareCall?.(callContext);
+    const protoSeq = this.sequenceCursor.next();
     const frame = ProtocolV2.encodeFrame(schemas, name, data, {
       packetSrc,
       router,
-      seq: this.protoSeq,
-      logger: shouldReduceDebug ? undefined : logger,
-      logPrefix,
-      context: `tx:${name}`,
+      seq: protoSeq,
     });
-    const expectedSeq = frame[6];
+    // Suppress Protocol V2 TX frame logs to avoid excessive transport diagnostics.
+    /*
+    const txMetadata = ProtocolV2.inspectFrame(schemas, frame);
 
     if (!shouldReduceDebug) {
-      logger?.debug?.(
-        `[${logPrefix}] TX payload name=${name}`,
-        sanitizeProtocolV2DebugPayload(data)
-      );
-      logger?.debug?.(
-        `[${logPrefix}] TX frame name=${name} len=${frame.length} router=${frame[4]} attr=${
-          frame[5]
-        } seq=${expectedSeq} headerHex=${frameHeaderDebugHex(frame)}`
+      logger?.debug?.(`[${logPrefix}] TX`, {
+        method: name,
+        type: name,
+        typeId: txMetadata.messageTypeId,
+        seq: txMetadata.seq,
+        bytes: frame.length,
+      });
+    }
+    */
+
+    if (maxFrameBytes !== undefined && frame.length > maxFrameBytes) {
+      throw new Error(
+        `Protocol V2 frame too large for transport: ${frame.length} > ${maxFrameBytes}`
       );
     }
 
-    // Lenient watchdog on the write phase only — see
-    // PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS for the rationale.
     await withProtocolTimeout(
-      writeFrame(frame),
-      PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS,
-      () =>
-        new Error(
-          `Protocol V2 write timeout after ${PROTOCOL_V2_WRITE_WATCHDOG_TIMEOUT_MS}ms for ${name}`
-        )
+      writeFrame(frame, callContext),
+      writeTimeoutMs,
+      () => new Error(`Protocol V2 write timeout after ${writeTimeoutMs}ms for ${name}`)
     );
 
     // Cancellation flag for the read loop: when the response timeout fires,
@@ -318,55 +238,64 @@ export class ProtocolV2Session {
     // consuming frames meant for the next call. The timeout callback flips the
     // flag so the loop exits and discards any late frame.
     const cancellation = { cancelled: false };
+    let resolveDelivery: () => void = () => undefined;
+    let deliveryConfirmed = false;
+    const deliveryPromise = new Promise<void>(resolve => {
+      resolveDelivery = () => {
+        if (deliveryConfirmed) return;
+        deliveryConfirmed = true;
+        resolve();
+      };
+    });
 
     const readResponse = async (): Promise<MessageFromOneKey> => {
       // Some Protocol V2 operations emit progress notifications before the
       // terminal response. Consume those frames here so callers still see a
       // request/terminal-response shaped API.
       while (!cancellation.cancelled) {
-        const rxFrame = await readFrame();
+        const rxFrame = await readFrame(callContext);
         if (cancellation.cancelled) {
           // Timed out while waiting: drop the late frame and stop reading.
           break;
         }
-        if (!shouldReduceDebug) {
-          logger?.debug?.(
-            `[${logPrefix}] RX frame len=${rxFrame.length} router=${rxFrame[4]} attr=${
-              rxFrame[5]
-            } seq=${rxFrame[6]} headerHex=${frameHeaderDebugHex(rxFrame)}`
-          );
-        }
-        const decoded = ProtocolV2.decodeFrame(schemas, rxFrame, {
-          logger: shouldReduceDebug ? undefined : logger,
-          logPrefix,
-          context: `rx:${name}`,
-        });
-        if (!shouldReduceDebug && decoded.seq !== expectedSeq) {
-          logger?.debug?.(
-            `[${logPrefix}] seq differs for ${name}: tx=${expectedSeq}, rx=${decoded.seq}`
-          );
-        }
-        if (!shouldReduceDebug) {
-          logger?.debug?.(
-            `[${logPrefix}] TX name=${name} seq=${expectedSeq} | RX seq=${decoded.seq} messageTypeId=${decoded.messageTypeId} pbPayload=${decoded.pbPayload.length}B`
-          );
-          logger?.debug?.(
-            `[${logPrefix}] RX payload type=${decoded.type} messageTypeId=${decoded.messageTypeId}`,
-            sanitizeProtocolV2DebugPayload(decoded.message)
-          );
-        }
-
-        const response = check.call(decoded);
-        if (callOptions.intermediateTypes?.includes(response.type)) {
-          callOptions.onIntermediateResponse?.(response);
-        } else if (isExpectedTerminalResponse(response, callOptions.expectedTypes)) {
-          return response;
-        } else if (!shouldReduceDebug) {
-          logger?.debug?.(
-            `[${logPrefix}] skip unexpected response for ${name}: expected=${callOptions.expectedTypes?.join(
-              '|'
-            )} got=${response.type}`
-          );
+        const ackSequence = ProtocolV2.getAckSequence(rxFrame);
+        if (ackSequence !== undefined) {
+          if (ackSequence === protoSeq) {
+            resolveDelivery();
+          }
+        } else {
+          // Some firmware versions return the protobuf response without a separate
+          // ACK. Receiving any valid response frame proves that the request arrived.
+          resolveDelivery();
+          // Suppress Protocol V2 RX frame logs to avoid excessive transport diagnostics.
+          /*
+          const rxMetadata = ProtocolV2.inspectFrame(schemas, rxFrame);
+
+          if (!shouldReduceDebug) {
+            logger?.debug?.(`[${logPrefix}] RX`, {
+              method: name,
+              type: rxMetadata.type,
+              typeId: rxMetadata.messageTypeId,
+              seq: rxMetadata.seq,
+              bytes: rxFrame.length,
+            });
+          }
+          */
+
+          const decoded = ProtocolV2.decodeFrame(schemas, rxFrame);
+
+          const response = check.call(decoded);
+          if (callOptions.intermediateTypes?.includes(response.type)) {
+            callOptions.onIntermediateResponse?.(response);
+          } else if (isExpectedTerminalResponse(response, callOptions.expectedTypes)) {
+            return response;
+          } else if (!shouldReduceDebug) {
+            logger?.debug?.(
+              `[${logPrefix}] skip unexpected response for ${name}: expected=${callOptions.expectedTypes?.join(
+                '|'
+              )} got=${response.type}`
+            );
+          }
         }
       }
       // Only reachable after cancellation; the outer promise has already been
@@ -374,7 +303,7 @@ export class ProtocolV2Session {
       throw new Error(`Protocol V2 read loop cancelled after timeout for ${name}`);
     };
 
-    return withProtocolTimeout(
+    const responsePromise = withProtocolTimeout(
       readResponse(),
       callOptions.timeoutMs,
       () =>
@@ -385,6 +314,31 @@ export class ProtocolV2Session {
         cancellation.cancelled = true;
       }
     );
+    const deliverySignal = Promise.race([deliveryPromise, responsePromise.then(() => undefined)]);
+    const deliveryWatchdog = withProtocolTimeout(
+      deliverySignal,
+      deliveryTimeoutMs,
+      () => new Error(`Protocol V2 delivery timeout after ${deliveryTimeoutMs}ms for ${name}`),
+      () => {
+        cancellation.cancelled = true;
+      }
+    );
+
+    try {
+      const firstResult = await Promise.race([
+        deliveryWatchdog.then(() => ({ kind: 'delivered' as const })),
+        responsePromise.then(response => ({ kind: 'response' as const, response })),
+      ]);
+      if (firstResult.kind === 'response') {
+        return firstResult.response;
+      }
+      return await responsePromise;
+    } catch (error) {
+      cancellation.cancelled = true;
+      deliveryWatchdog.catch(() => undefined);
+      responsePromise.catch(() => undefined);
+      throw error;
+    }
   }
 }
 

package/src/protocols/v2/usb-transport-base.ts

@@ -0,0 +1,194 @@
+import { ProtocolV2FrameAssembler } from './frame-assembler';
+import { ProtocolV2LinkManager } from './link-manager';
+
+import type { MessageFromOneKey, TransportCallOptions } from '../../types';
+import type { ProtocolV2CallContext, ProtocolV2Schemas, ProtocolV2SessionOptions } from './session';
+
+export type ProtocolV2UsbTransportBaseOptions = {
+  router: number;
+  maxFrameBytes: number;
+  logPrefix: string;
+};
+
+type ProtocolV2UsbCancellation = {
+  generation: number;
+  reason?: string;
+  promise: Promise<string>;
+  cancel: (reason: string) => void;
+};
+
+export abstract class ProtocolV2UsbTransportBase<Key> {
+  private readonly protocolV2UsbLinks: ProtocolV2LinkManager<Key>;
+
+  private readonly protocolV2UsbAssemblers = new Map<Key, ProtocolV2FrameAssembler>();
+
+  private readonly protocolV2UsbGenerations = new Map<Key, number>();
+
+  private readonly protocolV2UsbCancellations = new Map<Key, ProtocolV2UsbCancellation>();
+
+  private readonly protocolV2UsbOptions: ProtocolV2UsbTransportBaseOptions;
+
+  protected constructor(options: ProtocolV2UsbTransportBaseOptions) {
+    this.protocolV2UsbOptions = options;
+    this.protocolV2UsbLinks = new ProtocolV2LinkManager<Key>({
+      getSchemas: () => this.getProtocolV2UsbSchemas(),
+      classifyError: () => 'link-fatal',
+      onLinkInvalidated: async (key, reason) => {
+        this.protocolV2UsbAssemblers.get(key)?.reset();
+        await this.resetProtocolV2UsbNativeLink(key, reason);
+        await this.onProtocolV2UsbLinkInvalidated(key, reason);
+      },
+    });
+  }
+
+  protected abstract getProtocolV2UsbSchemas(): ProtocolV2Schemas;
+
+  protected abstract getProtocolV2UsbLogger(): ProtocolV2SessionOptions['logger'];
+
+  protected abstract writeProtocolV2UsbPacket(
+    key: Key,
+    frame: Uint8Array,
+    context: ProtocolV2CallContext
+  ): Promise<void>;
+
+  protected abstract readProtocolV2UsbPacket(
+    key: Key,
+    context: ProtocolV2CallContext
+  ): Promise<Uint8Array>;
+
+  protected abstract resetProtocolV2UsbNativeLink(key: Key, reason: string): Promise<void>;
+
+  protected abstract createProtocolV2UsbTimeoutError(name: string, timeoutMs: number): Error;
+
+  protected onProtocolV2UsbLinkInvalidated(_key: Key, _reason: string): Promise<void> | void {
+    // Subclasses may clear protocol caches or emit platform-specific diagnostics.
+  }
+
+  protected async rotateProtocolV2UsbGeneration(key: Key, reason: string): Promise<number> {
+    await this.protocolV2UsbLinks.invalidateLink(key, reason);
+    const generation = (this.protocolV2UsbGenerations.get(key) ?? 0) + 1;
+    this.protocolV2UsbGenerations.set(key, generation);
+    this.protocolV2UsbCancellations.set(key, this.createProtocolV2UsbCancellation(generation));
+    this.protocolV2UsbAssemblers.set(
+      key,
+      new ProtocolV2FrameAssembler(this.protocolV2UsbOptions.maxFrameBytes)
+    );
+    return generation;
+  }
+
+  protected callProtocolV2Usb(
+    key: Key,
+    name: string,
+    data: Record<string, unknown>,
+    options?: TransportCallOptions
+  ): Promise<MessageFromOneKey> {
+    return this.protocolV2UsbLinks.call(
+      key,
+      () => this.createProtocolV2UsbAdapter(key),
+      name,
+      data,
+      options
+    );
+  }
+
+  protected invalidateProtocolV2UsbLink(key: Key, reason: string): Promise<void> {
+    return this.protocolV2UsbLinks.invalidateLink(key, reason);
+  }
+
+  protected invalidateAllProtocolV2UsbLinks(reason: string): Promise<void> {
+    return this.protocolV2UsbLinks.invalidateAllLinks(reason);
+  }
+
+  protected async disposeProtocolV2UsbLinks(reason: string): Promise<void> {
+    await this.protocolV2UsbLinks.dispose(reason);
+    this.protocolV2UsbAssemblers.clear();
+    this.protocolV2UsbGenerations.clear();
+    this.protocolV2UsbCancellations.clear();
+  }
+
+  private createProtocolV2UsbAdapter(key: Key) {
+    const generation = this.protocolV2UsbGenerations.get(key);
+    if (generation === undefined) {
+      throw new Error('Protocol V2 USB generation has not been initialized');
+    }
+    const cancellation = this.protocolV2UsbCancellations.get(key);
+    if (!cancellation || cancellation.generation !== generation) {
+      throw new Error('Protocol V2 USB cancellation state has not been initialized');
+    }
+
+    const assertCurrentGeneration = () => {
+      if (cancellation.reason) {
+        throw new Error(cancellation.reason);
+      }
+      if (this.protocolV2UsbGenerations.get(key) !== generation) {
+        throw new Error('Protocol V2 USB connection generation changed');
+      }
+    };
+
+    return {
+      router: this.protocolV2UsbOptions.router,
+      maxFrameBytes: this.protocolV2UsbOptions.maxFrameBytes,
+      generation,
+      prepareCall: () => {
+        assertCurrentGeneration();
+        this.getProtocolV2UsbAssembler(key).reset();
+      },
+      writeFrame: async (frame: Uint8Array, context: ProtocolV2CallContext) => {
+        assertCurrentGeneration();
+        await this.writeProtocolV2UsbPacket(key, frame, context);
+        assertCurrentGeneration();
+      },
+      readFrame: async (context: ProtocolV2CallContext) => {
+        assertCurrentGeneration();
+        const assembler = this.getProtocolV2UsbAssembler(key);
+        let frame = assembler.push(new Uint8Array(0));
+        while (!frame) {
+          const packetRead = this.readProtocolV2UsbPacket(key, context).then(packet => ({
+            packet,
+          }));
+          const cancelled = cancellation.promise.then(reason => ({ reason }));
+          const result = await Promise.race([packetRead, cancelled]);
+          if ('reason' in result) {
+            throw new Error(result.reason);
+          }
+          assertCurrentGeneration();
+          frame = assembler.push(result.packet);
+        }
+        assertCurrentGeneration();
+        return frame;
+      },
+      reset: (reason: string) => {
+        cancellation.cancel(reason);
+        this.protocolV2UsbAssemblers.get(key)?.reset();
+      },
+      logger: this.getProtocolV2UsbLogger(),
+      logPrefix: this.protocolV2UsbOptions.logPrefix,
+      createTimeoutError: (messageName: string, timeoutMs: number) =>
+        this.createProtocolV2UsbTimeoutError(messageName, timeoutMs),
+    };
+  }
+
+  private getProtocolV2UsbAssembler(key: Key): ProtocolV2FrameAssembler {
+    const assembler = this.protocolV2UsbAssemblers.get(key);
+    if (!assembler) {
+      throw new Error('Protocol V2 USB assembler has not been initialized');
+    }
+    return assembler;
+  }
+
+  private createProtocolV2UsbCancellation(generation: number): ProtocolV2UsbCancellation {
+    let resolveCancellation: (reason: string) => void = () => undefined;
+    const cancellation: ProtocolV2UsbCancellation = {
+      generation,
+      promise: new Promise(resolve => {
+        resolveCancellation = resolve;
+      }),
+      cancel: reason => {
+        if (cancellation.reason) return;
+        cancellation.reason = reason;
+        resolveCancellation(reason);
+      },
+    };
+    return cancellation;
+  }
+}

package/src/serialization/protobuf/decode.ts

@@ -70,7 +70,10 @@ function messageToJSON(Message: Message<Record<string, unknown>>, fields: Type['
     }
     // message type
     else if (field.resolvedType!.fields) {
-      res[key] = messageToJSON(value, field.resolvedType!.fields);
+      // [compatibility]: absent optional sub-messages are not own properties
+      // of the decoded instance, so value is undefined here; decode them to
+      // null, matching the optional primitive-field convention above.
+      res[key] = value == null ? null : messageToJSON(value, (field.resolvedType as Type).fields);
     } else {
       throw new Error(`case not handled: ${key}`);
     }

package/src/serialization/protobuf/messages.ts

@@ -30,7 +30,12 @@ export const createMessageFromName = (messages: protobuf.Root, name: string) =>
 export const createMessageFromType = (messages: protobuf.Root, typeId: number) => {
   const MessageType = messages.lookupEnum('MessageType');
 
-  const messageName = MessageType.valuesById[typeId].replace('MessageType_', '');
+  const rawMessageName = MessageType.valuesById[typeId];
+  if (!rawMessageName) {
+    throw new Error(`MessageType id "${typeId}" is not defined in protobuf schema`);
+  }
+
+  const messageName = rawMessageName.replace('MessageType_', '');
 
   const Message = messages.lookupType(messageName);