@onekeyfe/hd-transport 1.1.34-alpha.2 → 1.1.34-alpha.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hd-transport",
-  "version": "1.1.34-alpha.2",
+  "version": "1.1.34-alpha.3",
   "description": "Transport layer abstractions and utilities for OneKey hardware SDK.",
   "author": "OneKey",
   "homepage": "https://github.com/OneKeyHQ/hardware-js-sdk#readme",
@@ -16,7 +16,7 @@
     "test": "jest",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
-    "update:protobuf": "./scripts/protobuf-build.sh"
+    "update-protobuf": "./scripts/protobuf-build.sh"
   },
   "devDependencies": {
     "@types/bytebuffer": "^5.0.42",
@@ -28,5 +28,5 @@
     "long": "^4.0.0",
     "protobufjs": "^6.11.2"
   },
-  "gitHead": "dee167c35d191f3f4e02c4cb6228e1f926f929ec"
+  "gitHead": "3688bc8495eeb2ffd5616270d13fa29e8967623a"
 }

package/scripts/protobuf-patches/TxInputType.js

@@ -29,6 +29,7 @@ type CommonTxInputType = {|
     witness?: string, // used by EXTERNAL, depending on script_pubkey
     ownership_proof?: string, // used by EXTERNAL, depending on script_pubkey
     commitment_data?: string, // used by EXTERNAL, depending on ownership_proof
+    coinjoin_flags?: number, // Protocol V2 only (CoinJoin)
 |};
 
 export type TxInputType =

package/scripts/protobuf-patches/index.js

@@ -116,6 +116,7 @@ const TYPE_PATCH = {
   'Features.onekey_se03_state': 'string | null',
   'Features.onekey_se04_state': 'string | null',
   'HDNodePathType.node': 'HDNodeType | string',
+  'FilesystemFile.data': 'Buffer | ArrayBuffer | Uint8Array | string',
   'FirmwareUpload.payload': 'Buffer | ArrayBuffer',
   'EthereumGetAddress.encoded_network': 'ArrayBuffer',
   'EthereumDefinitions.encoded_network': 'ArrayBuffer',
@@ -207,6 +208,7 @@ const TYPE_PATCH = {
   'TonSignMessage.fwd_fee': UINT_TYPE,
   'TonSignMessage.expire_at': UINT_TYPE,
   'TonSignMessage.ext_ton_amount': UINT_TYPE,
+  'TonSignData.timestamp': UINT_TYPE,
   'TonSignProof.expire_at': UINT_TYPE,
   'TonSignData.timestamp': UINT_TYPE,
 };

package/scripts/protobuf-types.js

@@ -6,9 +6,33 @@
 const fs = require('fs');
 const path = require('path');
 
-const json = require('../messages.json');
 const { RULE_PATCH, TYPE_PATCH, DEFINITION_PATCH, SKIP, UINT_TYPE } = require('./protobuf-patches');
 
+const readJson = filePath => JSON.parse(fs.readFileSync(filePath, 'utf8'));
+
+const localMessagesJsonPath = path.join(__dirname, '../messages.json');
+const coreMessagesJsonPath = path.join(__dirname, '../../core/src/data/messages/messages.json');
+const json = readJson(
+  fs.existsSync(localMessagesJsonPath) ? localMessagesJsonPath : coreMessagesJsonPath
+);
+const optionalJsonFiles = ['../messages-protocol-v2.json'];
+const OPTIONAL_DUPLICATE_TYPE_ALIASES = {
+  DeviceInfo: 'ProtocolV2DeviceInfo',
+};
+const OPTIONAL_NESTED_TYPE_ALIASES = [
+  { parent: 'Failure', name: 'FailureType', alias: 'ProtocolV2FailureType' },
+  { parent: 'Features', name: 'Capability', alias: 'ProtocolV2Capability' },
+];
+const messageTypeAliases = {};
+const skipMessageTypeKeys = new Set(Object.values(OPTIONAL_DUPLICATE_TYPE_ALIASES));
+
+// V1/V2 duplicate-type merge bookkeeping.
+// When the same top-level type exists in both schemas with a different shape we emit
+// the union of both sides instead of silently keeping the V1 definition only.
+const mergedRuleOverrides = {}; // `${Type}.${field}` -> 'optional'
+const mergedTypeOverrides = {}; // `${Type}.${field}` -> 'v1JsType | v2JsType'
+const duplicateTypeMergeReport = []; // { name, diffs: string[] }
+
 const args = process.argv.slice(2);
 
 const isTypescript = args.includes('typescript');
@@ -26,6 +50,8 @@ const FIELD_TYPES = {
 
 const types = []; // { type: 'enum | message', name: string, value: string[], exact?: boolean };
 
+const hasParsedType = name => types.some(t => t && t.name === name);
+
 // enums used as keys (string), used as values (number) by default
 const ENUM_KEYS = [
   'InputScriptType',
@@ -40,6 +66,7 @@ const ENUM_KEYS = [
   'ButtonRequestType',
   'PinMatrixRequestType',
   'WordRequestType',
+  'ProtocolV2Capability',
 ];
 
 const parseEnumTypescript = (itemName, item) => {
@@ -114,8 +141,9 @@ const useDefinition = def => {
   return clean.replace(/\/\/ @typescript-variant(.*)/, '').replace(/\/\/ @flowtype-variant:/, '');
 };
 
-const parseMessage = (messageName, message, depth = 0) => {
+const parseMessage = (messageName, message, depth = 0, skipExisting = false) => {
   if (messageName === 'google') return;
+  if (!depth && skipExisting && hasParsedType(messageName)) return;
   const value = [];
   // add comment line
   if (!depth) value.push(`// ${messageName}`);
@@ -123,7 +151,9 @@ const parseMessage = (messageName, message, depth = 0) => {
 
   // declare nested values
   if (message.nested) {
-    Object.keys(message.nested).map(item => parseMessage(item, message.nested[item], depth + 1));
+    Object.keys(message.nested).map(item =>
+      parseMessage(item, message.nested[item], depth + 1, skipExisting)
+    );
   }
 
   if (message.values) {
@@ -145,11 +175,15 @@ const parseMessage = (messageName, message, depth = 0) => {
       Object.keys(message.fields).forEach(fieldName => {
         const field = message.fields[fieldName];
         const fieldKey = `${messageName}.${fieldName}`;
-        // find patch for "rule"
-        const fieldRule = RULE_PATCH[fieldKey] || field.rule;
+        // find patch for "rule" (hand-written patches win over V1/V2 merge overrides)
+        const fieldRule = RULE_PATCH[fieldKey] || mergedRuleOverrides[fieldKey] || field.rule;
         const rule = fieldRule === 'required' || fieldRule === 'repeated' ? ': ' : '?: ';
-        // find patch for "type"
-        let type = TYPE_PATCH[fieldKey] || FIELD_TYPES[field.type] || field.type;
+        // find patch for "type" (hand-written patches win over V1/V2 merge overrides)
+        let type =
+          TYPE_PATCH[fieldKey] ||
+          mergedTypeOverrides[fieldKey] ||
+          FIELD_TYPES[field.type] ||
+          field.type;
         // automatically convert all amount and fee fields to UINT_TYPE
         if (['amount', 'fee'].includes(fieldName)) {
           type = UINT_TYPE;
@@ -176,8 +210,163 @@ const parseMessage = (messageName, message, depth = 0) => {
   });
 };
 
+const jsFieldType = protoType => FIELD_TYPES[protoType] || protoType;
+
+// Merge a duplicate Protocol V2 definition into its V1 counterpart (in-memory only,
+// messages.json / messages-protocol-v2.json on disk stay untouched).
+// Strategy:
+// - messages: emit the union of both sides' fields; a field present on one side only
+//   becomes optional
+// - field type conflict: emit a union type and warn
+// - field rule conflict (required/optional/repeated): keep the V1 rule and warn
+// - enums: emit the union of members; member value conflicts keep the V1 value and warn
+// - nested types are merged recursively
+const mergeDuplicateDefinition = (typeName, base, extra, diffs) => {
+  if (base.values || extra.values) {
+    if (!base.values || !extra.values) {
+      diffs.push('! kind conflict (enum vs message), keeping V1 definition');
+      console.warn(
+        `[protobuf-types] duplicate type "${typeName}" is an enum on one side and a message on the other, keeping V1`
+      );
+      return;
+    }
+    Object.entries(extra.values).forEach(([memberName, memberValue]) => {
+      if (!(memberName in base.values)) {
+        base.values[memberName] = memberValue;
+        diffs.push(`+ enum member ${memberName} = ${memberValue} (V2 only)`);
+      } else if (base.values[memberName] !== memberValue) {
+        diffs.push(
+          `! enum member ${memberName} value conflict: V1=${base.values[memberName]} V2=${memberValue}, keeping V1`
+        );
+        console.warn(
+          `[protobuf-types] enum "${typeName}.${memberName}" value differs between V1 (${base.values[memberName]}) and V2 (${memberValue}), keeping V1`
+        );
+      }
+    });
+    return;
+  }
+
+  if (extra.nested) {
+    base.nested = base.nested || {};
+    Object.keys(extra.nested).forEach(nestedName => {
+      if (base.nested[nestedName]) {
+        mergeDuplicateDefinition(
+          nestedName,
+          base.nested[nestedName],
+          extra.nested[nestedName],
+          diffs
+        );
+      } else {
+        base.nested[nestedName] = extra.nested[nestedName];
+        diffs.push(`+ nested type ${nestedName} (V2 only)`);
+      }
+    });
+  }
+
+  const extraFields = extra.fields || {};
+  if (!Object.keys(extraFields).length && !base.fields) return;
+  base.fields = base.fields || {};
+  const baseFields = base.fields;
+
+  Object.entries(extraFields).forEach(([fieldName, field]) => {
+    const fieldKey = `${typeName}.${fieldName}`;
+    if (!(fieldName in baseFields)) {
+      baseFields[fieldName] = field;
+      // field exists in V2 only -> always optional in the merged interface
+      if (field.rule) mergedRuleOverrides[fieldKey] = 'optional';
+      diffs.push(
+        `+ field ${fieldName}?: ${jsFieldType(field.type)}${
+          field.rule === 'repeated' ? '[]' : ''
+        } (V2 only, marked optional)`
+      );
+      return;
+    }
+    const baseField = baseFields[fieldName];
+    if (baseField.type !== field.type) {
+      const baseJsType = jsFieldType(baseField.type);
+      const extraJsType = jsFieldType(field.type);
+      if (baseJsType !== extraJsType) {
+        mergedTypeOverrides[fieldKey] = `${baseJsType} | ${extraJsType}`;
+        diffs.push(
+          `! field ${fieldName} type conflict: V1=${baseField.type} V2=${field.type}, emitting union ${baseJsType} | ${extraJsType}`
+        );
+        console.warn(
+          `[protobuf-types] field "${fieldKey}" type differs between V1 (${baseField.type}) and V2 (${field.type}), emitting union type`
+        );
+      }
+    }
+    if ((baseField.rule || 'optional') !== (field.rule || 'optional')) {
+      diffs.push(
+        `! field ${fieldName} rule conflict: V1=${baseField.rule || 'optional'} V2=${
+          field.rule || 'optional'
+        }, keeping V1`
+      );
+    }
+  });
+
+  Object.entries(baseFields).forEach(([fieldName, field]) => {
+    if (fieldName in extraFields) return;
+    const fieldKey = `${typeName}.${fieldName}`;
+    // field exists in V1 only -> always optional in the merged interface
+    if (field.rule && !mergedRuleOverrides[fieldKey]) {
+      mergedRuleOverrides[fieldKey] = 'optional';
+      diffs.push(`~ field ${fieldName} (V1 only): ${field.rule} -> optional`);
+    } else {
+      diffs.push(`~ field ${fieldName} (V1 only, already optional)`);
+    }
+  });
+};
+
+// Pass 1 (before parsing): merge duplicate V2 definitions into the V1 schema so the
+// generated interfaces contain the union of both protocols' fields. Previously the V2
+// side of a duplicate type was silently dropped, hiding V2-only fields/enum members.
+const optionalJsons = [];
+optionalJsonFiles.forEach(jsonFile => {
+  const jsonPath = path.join(__dirname, jsonFile);
+  if (!fs.existsSync(jsonPath)) return;
+  const optionalJson = readJson(jsonPath);
+  OPTIONAL_NESTED_TYPE_ALIASES.forEach(({ parent, name, alias }) => {
+    const definition = optionalJson.nested[parent]?.nested?.[name];
+    if (definition) optionalJson.nested[alias] = definition;
+  });
+  optionalJsons.push(optionalJson);
+  Object.keys(optionalJson.nested).forEach(e => {
+    if (!json.nested[e]) return; // V2-only type, parsed after the V1 pass below
+    if (OPTIONAL_DUPLICATE_TYPE_ALIASES[e]) return; // kept as a separate aliased type
+    if (SKIP.includes(e)) return; // custom/hand-written definitions (MessageType, TxInput, ...)
+    const diffs = [];
+    mergeDuplicateDefinition(e, json.nested[e], optionalJson.nested[e], diffs);
+    if (diffs.length) duplicateTypeMergeReport.push({ name: e, diffs });
+  });
+});
+
+// Explicit drift report: every merged duplicate type and its V1/V2 differences.
+if (duplicateTypeMergeReport.length) {
+  console.log(
+    `[protobuf-types] ${duplicateTypeMergeReport.length} duplicate V1/V2 type(s) differ and were merged (field union):`
+  );
+  duplicateTypeMergeReport.forEach(({ name, diffs }) => {
+    console.log(`  - ${name}`);
+    diffs.forEach(diff => console.log(`      ${diff}`));
+  });
+}
+
 // top level messages and nested messages
-Object.keys(json.nested).map(e => parseMessage(e, json.nested[e]));
+Object.keys(json.nested).forEach(e => parseMessage(e, json.nested[e]));
+
+// Pass 2: aliased duplicates (e.g. DeviceInfo -> ProtocolV2DeviceInfo) and V2-only types
+optionalJsons.forEach(optionalJson => {
+  Object.keys(optionalJson.nested).forEach(e => {
+    const alias = hasParsedType(e) ? OPTIONAL_DUPLICATE_TYPE_ALIASES[e] : undefined;
+    if (alias) {
+      parseMessage(alias, optionalJson.nested[e]);
+      messageTypeAliases[e] = [e, alias];
+      return;
+    }
+    if (json.nested[e]) return; // duplicate type, already merged into the V1 definition
+    parseMessage(e, optionalJson.nested[e], 0, true);
+  });
+});
 
 // types needs reordering (used before defined)
 const ORDER = {
@@ -226,10 +415,14 @@ if (!isTypescript) {
   types
     .flatMap(t => (t && t.type === 'message' ? [t] : []))
     .forEach(t => {
+      if (skipMessageTypeKeys.has(t.name)) return;
+      const messageTypeValue = messageTypeAliases[t.name]
+        ? messageTypeAliases[t.name].join(' | ')
+        : t.name;
       if (t.exact) {
-        lines.push(`    ${t.name}: $Exact<${t.name}>;`);
+        lines.push(`    ${t.name}: $Exact<${messageTypeValue}>;`);
       } else {
-        lines.push(`    ${t.name}: ${t.name};`);
+        lines.push(`    ${t.name}: ${messageTypeValue};`);
       }
       // lines.push('    ' + t.name + ': $Exact<' + t.name + '>;');
     });
@@ -244,11 +437,18 @@ export type MessageResponse<T: MessageKey> = {
     message: $ElementType<MessageType, T>;
 };
 
-export type TypedCall = <T: MessageKey, R: MessageKey>(
+export type TypedCall = {
+  <T: MessageKey, R: $ReadOnlyArray<MessageKey>>(
+    type: T,
+    resType: R,
+    message?: $ElementType<MessageType, T>
+  ): Promise<MessageResponse<$ElementType<R, number>>>;
+  <T: MessageKey, R: MessageKey>(
     type: T,
     resType: R,
     message?: $ElementType<MessageType, T>
-) => Promise<MessageResponse<R>>;
+  ): Promise<MessageResponse<R>>;
+};
 `);
 } else {
   lines.push('// custom connect definitions');
@@ -256,7 +456,11 @@ export type TypedCall = <T: MessageKey, R: MessageKey>(
   types
     .flatMap(t => (t && t.type === 'message' ? [t] : []))
     .forEach(t => {
-      lines.push(`    ${t.name}: ${t.name};`);
+      if (skipMessageTypeKeys.has(t.name)) return;
+      const messageTypeValue = messageTypeAliases[t.name]
+        ? messageTypeAliases[t.name].join(' | ')
+        : t.name;
+      lines.push(`    ${t.name}: ${messageTypeValue};`);
     });
   lines.push('};');
 
@@ -269,11 +473,22 @@ export type MessageResponse<T extends MessageKey> = {
     message: MessageType[T];
 };
 
-export type TypedCall = <T extends MessageKey, R extends MessageKey>(
-    type: T,
-    resType: R,
-    message?: MessageType[T],
-) => Promise<MessageResponse<R>>;
+export type MessageResponseMap = {
+    [K in MessageKey]: MessageResponse<K>;
+};
+
+export type TypedCall = {
+    <T extends MessageKey, R extends readonly MessageKey[]>(
+        type: T,
+        resType: R,
+        message?: MessageType[T],
+    ): Promise<MessageResponseMap[R[number]]>;
+    <T extends MessageKey, R extends MessageKey>(
+        type: T,
+        resType: R,
+        message?: MessageType[T],
+    ): Promise<MessageResponse<R>>;
+};
 `);
 }
 

package/src/constants.ts

@@ -1,8 +1,50 @@
-export const MESSAGE_TOP_CHAR = 0x003f;
-export const MESSAGE_HEADER_BYTE = 0x23;
-export const HEADER_SIZE = 1 + 1 + 4 + 2;
-export const BUFFER_SIZE = 63;
+// ---- Protocol V1 (Pro1 / Touch / Mini / Classic) ----
+
+/** Protocol V1 USB report marker, ASCII `?`. */
+export const PROTOCOL_V1_REPORT_ID = 0x3f;
+
+/** Protocol V1 envelope marker, ASCII `#`. */
+export const PROTOCOL_V1_HEADER_BYTE = 0x23;
+
+/** Protocol V1 payload bytes per chunk after the report marker. */
+export const PROTOCOL_V1_CHUNK_PAYLOAD_SIZE = 63;
+
+/** Protocol V1 USB packet length: report marker plus chunk payload. */
+export const PROTOCOL_V1_USB_PACKET_SIZE = PROTOCOL_V1_CHUNK_PAYLOAD_SIZE + 1;
+
+/** Protocol V1 message metadata: two-byte type plus four-byte payload length. */
+export const PROTOCOL_V1_MESSAGE_HEADER_SIZE = 2 + 4;
+
+/** Protocol V1 envelope metadata: `##`, message type, and payload length. */
+export const PROTOCOL_V1_ENVELOPE_HEADER_SIZE = 1 + 1 + PROTOCOL_V1_MESSAGE_HEADER_SIZE;
+
+// ---- Protocol V2 (Pro2 USB / BLE transports) ----
+
+/** Maximum V2 frame length, including header, 4000-byte payload, protobuf overhead, and CRC. */
+export const PROTOCOL_V2_FRAME_MAX_BYTES = 4608;
+
+/** FilesystemFileWrite chunk size over WebUSB. */
+export const PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE = 4000;
+
+/** FilesystemFileWrite chunk size over BLE. */
+export const PROTOCOL_V2_BLE_FILE_CHUNK_SIZE = 1800;
+
+/** BLE FilesystemFileRead chunk size, limited by the Pro2 1024-byte UART TX buffer. */
+export const PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE = 900;
+
+/** Pro2 BLE/UART RX FIFO must hold a complete Proto Link frame. */
+export const PROTOCOL_V2_BLE_FRAME_MAX_BYTES = 2048;
+
+/** @deprecated Use the transport-specific WebUSB or BLE file chunk constant. */
+export const PROTOCOL_V2_FILE_CHUNK_SIZE = PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE;
+
 /**
- * exclude ?##
+ * Protocol V2 routing channel. USB reaches the main MCU directly, while BLE routes
+ * through the BLE coprocessor UART bridge.
  */
-export const COMMON_HEADER_SIZE = 6;
+export const PROTOCOL_V2_CHANNEL_USB = 0;
+export const PROTOCOL_V2_CHANNEL_BLE_UART = 1;
+export const PROTOCOL_V2_CHANNEL_SOCKET = 2;
+
+/** packet_src for protobuf commands; firmware routes zero to the protobuf dispatcher. */
+export const PROTOCOL_V2_PACKET_SRC_COMMAND = 0;

package/src/index.ts

@@ -1,14 +1,28 @@
 import * as protobuf from 'protobufjs/light';
-import * as Long from 'long';
+import Long from 'long';
 
 import {
-  buildBuffers,
-  buildEncodeBuffers,
-  buildOne,
-  decodeProtocol,
+  createMessageFromName,
+  createMessageFromType,
+  decodeProtobuf,
+  encodeProtobuf,
   parseConfigure,
-  receiveOne,
 } from './serialization';
+import { PROTOCOL_V2_SYS_MESSAGE_THRESHOLD, ProtocolV1, ProtocolV2 } from './protocols';
+import * as protocolV2Codec from './protocols/v2';
+import { ProtocolV2LinkManager } from './protocols/v2/link-manager';
+import { ProtocolV2UsbTransportBase } from './protocols/v2/usb-transport-base';
+import {
+  ProtocolV2FrameAssembler,
+  ProtocolV2SequenceCursor,
+  ProtocolV2Session,
+  bytesToHex,
+  concatUint8Arrays,
+  getErrorMessage,
+  hexToBytes,
+  probeProtocolV2,
+  withProtocolTimeout,
+} from './protocols/v2/session';
 import * as check from './utils/highlevel-checks';
 
 protobuf.util.Long = Long;
@@ -21,10 +35,12 @@ export type {
   OneKeyMobileDeviceInfo,
   OneKeyDeviceInfoWithSession,
   MessageFromOneKey,
+  TransportCallOptions,
   LowlevelTransportSharedPlugin,
   LowLevelDevice,
   OneKeyDeviceInfoBase,
   OneKeyDeviceCommType,
+  ProtocolType,
 } from './types';
 
 export { Messages } from './types';
@@ -32,13 +48,33 @@ export * from './types/messages';
 export * from './utils/logBlockCommand';
 
 export * from './constants';
+export * from './protocols';
+export * as protocolV1 from './protocols/v1';
+export * as protocolV2 from './protocols/v2';
+export * from './protocols/v2/session';
+export * from './protocols/v2/link-manager';
+export * from './protocols/v2/usb-transport-base';
 
 export default {
   check,
-  buildOne,
-  buildBuffers,
-  buildEncodeBuffers,
-  receiveOne,
   parseConfigure,
-  decodeProtocol,
+  protocolV2: protocolV2Codec,
+  ProtocolV1,
+  ProtocolV2,
+  PROTOCOL_V2_SYS_MESSAGE_THRESHOLD,
+  ProtocolV2FrameAssembler,
+  ProtocolV2LinkManager,
+  ProtocolV2SequenceCursor,
+  ProtocolV2Session,
+  ProtocolV2UsbTransportBase,
+  bytesToHex,
+  concatUint8Arrays,
+  createMessageFromName,
+  createMessageFromType,
+  encodeProtobuf,
+  decodeProtobuf,
+  getErrorMessage,
+  hexToBytes,
+  probeProtocolV2,
+  withProtocolTimeout,
 };

package/src/protocols/index.ts

@@ -0,0 +1,124 @@
+import ByteBuffer from 'bytebuffer';
+
+import { encodeEnvelopeMessage, encodeMessageChunks, encodeTransportPackets } from './v1/packets';
+import { decodeFirstChunk } from './v1/decode';
+import { decodeMessage as decodeV1Message } from './v1/receive';
+import { createMessageFromName, createMessageFromType } from '../serialization/protobuf/messages';
+import { encode as encodeProtobuf } from '../serialization/protobuf/encode';
+import { decode as decodeProtobuf } from '../serialization/protobuf/decode';
+import { decodeFrame as decodeV2Frame, encodeProtobufFrame, isAckFrame } from './v2';
+
+import type { Root } from 'protobufjs/light';
+
+export const PROTOCOL_V2_SYS_MESSAGE_THRESHOLD = 60000;
+
+type ProtocolV2Schemas = {
+  protocolV1: Root;
+  protocolV2: Root;
+};
+
+type ProtocolV2FrameOptions = {
+  packetSrc?: number;
+  router?: number;
+  /** Sequence number (1-255). Managed per-session by ProtocolV2Session. */
+  seq?: number;
+};
+
+const resolveProtocolV2EncodeSchema = (name: string, schemas: ProtocolV2Schemas) => {
+  try {
+    schemas.protocolV2.lookupType(name);
+    return schemas.protocolV2;
+  } catch {
+    throw new Error(`Protocol V2 message "${name}" is not defined in Protocol V2 schema`);
+  }
+};
+
+const PROTOCOL_V2_LEGACY_DECODE_ALLOWLIST = new Set([
+  'Failure',
+  'ButtonRequest',
+  'EntropyRequest',
+  'PinMatrixRequest',
+  'PassphraseRequest',
+  'Deprecated_PassphraseStateRequest',
+  'WordRequest',
+]);
+
+const createProtocolV2MessageFromType = (messageTypeId: number, schemas: ProtocolV2Schemas) => {
+  try {
+    return createMessageFromType(schemas.protocolV2, messageTypeId);
+  } catch (protocolV2Error) {
+    let legacyMessage: ReturnType<typeof createMessageFromType>;
+    try {
+      legacyMessage = createMessageFromType(schemas.protocolV1, messageTypeId);
+    } catch {
+      throw protocolV2Error;
+    }
+    if (PROTOCOL_V2_LEGACY_DECODE_ALLOWLIST.has(legacyMessage.messageName)) {
+      return legacyMessage;
+    }
+    throw protocolV2Error;
+  }
+};
+
+export const ProtocolV1 = {
+  encodeEnvelope: encodeEnvelopeMessage,
+  encodeMessageChunks,
+  encodeTransportPackets,
+  decodeFirstChunk,
+
+  decodeMessage: decodeV1Message,
+};
+
+export const ProtocolV2 = {
+  isAckFrame,
+
+  inspectFrame(schemas: ProtocolV2Schemas, frame: Uint8Array) {
+    const { messageTypeId, pbPayload, seq } = decodeV2Frame(frame);
+    const { messageName } = createProtocolV2MessageFromType(messageTypeId, schemas);
+    return {
+      messageName,
+      messageTypeId,
+      pbPayload,
+      seq,
+      type: messageName,
+    };
+  },
+
+  encodeFrame(
+    schemas: ProtocolV2Schemas,
+    name: string,
+    data: Record<string, unknown>,
+    options: ProtocolV2FrameOptions = {}
+  ) {
+    const encodeMessages = resolveProtocolV2EncodeSchema(name, schemas);
+    const { Message, messageTypeId } = createMessageFromName(encodeMessages, name);
+    const pbBuffer = encodeProtobuf(Message, data);
+    pbBuffer.reset();
+    const rawPbBuffer = pbBuffer.toBuffer() as unknown as ArrayBuffer;
+    const pbBytes = new Uint8Array(rawPbBuffer);
+
+    return encodeProtobufFrame(
+      messageTypeId,
+      pbBytes,
+      options.packetSrc,
+      options.router,
+      options.seq
+    );
+  },
+
+  decodeFrame(schemas: ProtocolV2Schemas, frame: Uint8Array) {
+    const { messageTypeId, pbPayload, seq, messageName } = this.inspectFrame(schemas, frame);
+    const { Message } = createProtocolV2MessageFromType(messageTypeId, schemas);
+    const rxByteBuffer = ByteBuffer.wrap(Buffer.from(pbPayload) as unknown as ArrayBuffer);
+    const message = decodeProtobuf(Message, rxByteBuffer);
+
+    return {
+      message,
+      messageName,
+      messageTypeId,
+      pbPayload,
+      seq,
+      type: messageName,
+    };
+  },
+};

package/src/{serialization/protocol → protocols/v1}/decode.ts

@@ -1,6 +1,6 @@
 import ByteBuffer from 'bytebuffer';
 
-import { MESSAGE_HEADER_BYTE } from '../../constants';
+import { PROTOCOL_V1_HEADER_BYTE } from '../../constants';
 
 /**
  * Reads meta information from buffer
@@ -24,7 +24,7 @@ const readHeaderChunked = (buffer: ByteBuffer) => {
   return { sharp1, sharp2, typeId, length };
 };
 
-export const decode = (byteBuffer: ByteBuffer) => {
+export const decodeEnvelope = (byteBuffer: ByteBuffer) => {
   const { typeId } = readHeader(byteBuffer);
 
   return {
@@ -35,13 +35,13 @@ export const decode = (byteBuffer: ByteBuffer) => {
 
 // Parses first raw input that comes from Trezor and returns some information about the whole message.
 // [compatibility]: accept Buffer just like decode does. But this would require changes in lower levels
-export const decodeChunked = (bytes: ArrayBuffer) => {
+export const decodeFirstChunk = (bytes: ArrayBuffer) => {
   // convert to ByteBuffer so it's easier to read
   const byteBuffer = ByteBuffer.wrap(bytes, undefined, undefined, true);
 
   const { sharp1, sharp2, typeId, length } = readHeaderChunked(byteBuffer);
 
-  if (sharp1 !== MESSAGE_HEADER_BYTE || sharp2 !== MESSAGE_HEADER_BYTE) {
+  if (sharp1 !== PROTOCOL_V1_HEADER_BYTE || sharp2 !== PROTOCOL_V1_HEADER_BYTE) {
     throw new Error("Didn't receive expected header signature.");
   }