@onekeyfe/hd-transport 1.1.27 → 1.2.0-alpha.0

package/scripts/protobuf-types.js

@@ -6,9 +6,29 @@
 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 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 +46,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',
@@ -111,8 +133,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}`);
@@ -120,7 +143,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) {
@@ -142,11 +167,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;
@@ -173,8 +202,159 @@ 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);
+  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 = {
@@ -223,10 +403,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 + '>;');
     });
@@ -241,11 +425,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');
@@ -253,7 +444,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('};');
 
@@ -266,11 +461,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,44 @@
-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 标记，ASCII '?'。 */
+export const PROTOCOL_V1_REPORT_ID = 0x3f;
+
+/** Protocol V1 envelope 头部标记，ASCII '#'。 */
+export const PROTOCOL_V1_HEADER_BYTE = 0x23;
+
+/** Protocol V1 单个 chunk 去掉 report 标记后的可用 payload 长度。 */
+export const PROTOCOL_V1_CHUNK_PAYLOAD_SIZE = 63;
+
+/** Protocol V1 USB packet 长度：report 标记 + chunk payload。 */
+export const PROTOCOL_V1_USB_PACKET_SIZE = PROTOCOL_V1_CHUNK_PAYLOAD_SIZE + 1;
+
+/** Protocol V1 message metadata：message type 2 字节 + payload length 4 字节。 */
+export const PROTOCOL_V1_MESSAGE_HEADER_SIZE = 2 + 4;
+
+/** Protocol V1 envelope metadata：## + message type + payload length。 */
+export const PROTOCOL_V1_ENVELOPE_HEADER_SIZE = 1 + 1 + PROTOCOL_V1_MESSAGE_HEADER_SIZE;
+
+// ---- Protocol V2 (Pro2 USB / BLE transports) ----
+
+/** Protocol V2 单帧最大长度，包含 header、payload 和 CRC；需容纳 4096 数据块及 protobuf 开销。 */
+export const PROTOCOL_V2_FRAME_MAX_BYTES = 4608;
+
+/** WebUSB 下 FilesystemFileWrite 的文件数据分块大小。 */
+export const PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE = 4096;
+
+/** BLE 下 FilesystemFileWrite 的文件数据分块大小。 */
+export const PROTOCOL_V2_BLE_FILE_CHUNK_SIZE = 1800;
+
+/** @deprecated 使用按传输区分的 PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE / PROTOCOL_V2_BLE_FILE_CHUNK_SIZE。 */
+export const PROTOCOL_V2_FILE_CHUNK_SIZE = PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE;
+
 /**
- * exclude ?##
+ * Protocol V2 路由 channel。
+ * USB 端点直接到主 MCU，不需要 proto-link 路由；BLE 需要经过 BLE 协处理器 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;
+
+/** protobuf 命令流的 packet_src，固件侧会把 0 路由到 protobuf dispatcher。 */
+export const PROTOCOL_V2_PACKET_SRC_COMMAND = 0;

package/src/index.ts

@@ -1,14 +1,25 @@
 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 {
+  ProtocolV2FrameAssembler,
+  ProtocolV2Session,
+  bytesToHex,
+  concatUint8Arrays,
+  getErrorMessage,
+  hexToBytes,
+  probeProtocolV2,
+  withProtocolTimeout,
+} from './protocols/v2/session';
 import * as check from './utils/highlevel-checks';
 
 protobuf.util.Long = Long;
@@ -21,10 +32,12 @@ export type {
   OneKeyMobileDeviceInfo,
   OneKeyDeviceInfoWithSession,
   MessageFromOneKey,
+  TransportCallOptions,
   LowlevelTransportSharedPlugin,
   LowLevelDevice,
   OneKeyDeviceInfoBase,
   OneKeyDeviceCommType,
+  ProtocolType,
 } from './types';
 
 export { Messages } from './types';
@@ -32,13 +45,28 @@ 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 default {
   check,
-  buildOne,
-  buildBuffers,
-  buildEncodeBuffers,
-  receiveOne,
   parseConfigure,
-  decodeProtocol,
+  protocolV2: protocolV2Codec,
+  ProtocolV1,
+  ProtocolV2,
+  PROTOCOL_V2_SYS_MESSAGE_THRESHOLD,
+  ProtocolV2FrameAssembler,
+  ProtocolV2Session,
+  bytesToHex,
+  concatUint8Arrays,
+  createMessageFromName,
+  createMessageFromType,
+  encodeProtobuf,
+  decodeProtobuf,
+  getErrorMessage,
+  hexToBytes,
+  probeProtocolV2,
+  withProtocolTimeout,
 };

package/src/protocols/index.ts

@@ -0,0 +1,144 @@
+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 } from './v2';
+
+import type { Root } from 'protobufjs/light';
+import type { ProtocolV2DebugLogger } from './v2';
+
+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;
+  logger?: ProtocolV2DebugLogger;
+  logPrefix?: string;
+  context?: string;
+};
+
+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([
+  '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 = {
+  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);
+
+    options.logger?.debug?.(`[${options.logPrefix ?? 'ProtocolV2'}] encode protobuf`, {
+      context: options.context ?? `encode:${name}`,
+      messageName: name,
+      messageTypeId,
+      pbPayloadLength: pbBytes.length,
+      packetSrc: options.packetSrc ?? 0,
+      router: options.router ?? 0,
+    });
+
+    return encodeProtobufFrame(
+      messageTypeId,
+      pbBytes,
+      options.packetSrc,
+      options.router,
+      {
+        logger: options.logger,
+        logPrefix: options.logPrefix,
+        context: options.context ?? `encode:${name}`,
+        messageName: name,
+      },
+      options.seq
+    );
+  },
+
+  decodeFrame(
+    schemas: ProtocolV2Schemas,
+    frame: Uint8Array,
+    options: Pick<ProtocolV2FrameOptions, 'logger' | 'logPrefix' | 'context'> = {}
+  ) {
+    const { messageTypeId, pbPayload, seq } = decodeV2Frame(frame, {
+      logger: options.logger,
+      logPrefix: options.logPrefix,
+      context: options.context ?? 'decode',
+    });
+    const { Message, messageName } = createProtocolV2MessageFromType(messageTypeId, schemas);
+    const rxByteBuffer = ByteBuffer.wrap(Buffer.from(pbPayload) as unknown as ArrayBuffer);
+    const message = decodeProtobuf(Message, rxByteBuffer);
+
+    options.logger?.debug?.(`[${options.logPrefix ?? 'ProtocolV2'}] decode protobuf`, {
+      context: options.context ?? `decode:${messageName}`,
+      messageName,
+      messageTypeId,
+      pbPayloadLength: pbPayload.length,
+      seq,
+    });
+
+    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.");
   }
 

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

@@ -1,30 +1,35 @@
 import ByteBuffer from 'bytebuffer';
 
-import { BUFFER_SIZE, HEADER_SIZE, MESSAGE_HEADER_BYTE } from '../../constants';
+import {
+  PROTOCOL_V1_CHUNK_PAYLOAD_SIZE,
+  PROTOCOL_V1_ENVELOPE_HEADER_SIZE,
+  PROTOCOL_V1_HEADER_BYTE,
+} from '../../constants';
 
 type Options<Chunked> = {
   chunked: Chunked;
   addTrezorHeaders: boolean;
-  messageType: number;
+  messageTypeId: number;
 };
 
-function encode(data: ByteBuffer, options: Options<true>): Buffer[];
-function encode(data: ByteBuffer, options: Options<false>): Buffer;
-function encode(data: any, options: any): any {
-  const { addTrezorHeaders, chunked, messageType } = options;
-  // eslint-disable-next-line @typescript-eslint/restrict-plus-operands
-  const fullSize = (addTrezorHeaders ? HEADER_SIZE : HEADER_SIZE - 2) + data.limit;
+function encodeEnvelope(data: ByteBuffer, options: Options<true>): Buffer[];
+function encodeEnvelope(data: ByteBuffer, options: Options<false>): Buffer;
+function encodeEnvelope(data: any, options: any): any {
+  const { addTrezorHeaders, chunked, messageTypeId } = options;
+  const fullSize =
+    (addTrezorHeaders ? PROTOCOL_V1_ENVELOPE_HEADER_SIZE : PROTOCOL_V1_ENVELOPE_HEADER_SIZE - 2) +
+    Number(data.limit);
 
   const encodedByteBuffer = new ByteBuffer(fullSize);
 
   if (addTrezorHeaders) {
     // 2*1 byte
-    encodedByteBuffer.writeByte(MESSAGE_HEADER_BYTE);
-    encodedByteBuffer.writeByte(MESSAGE_HEADER_BYTE);
+    encodedByteBuffer.writeByte(PROTOCOL_V1_HEADER_BYTE);
+    encodedByteBuffer.writeByte(PROTOCOL_V1_HEADER_BYTE);
   }
 
   // 2 bytes
-  encodedByteBuffer.writeUint16(messageType);
+  encodedByteBuffer.writeUint16(messageTypeId);
 
   // 4 bytes (so 8 in total)
   encodedByteBuffer.writeUint32(data.limit);
@@ -39,7 +44,7 @@ function encode(data: any, options: any): any {
   }
 
   const result: Buffer[] = [];
-  const size = BUFFER_SIZE;
+  const size = PROTOCOL_V1_CHUNK_PAYLOAD_SIZE;
 
   // How many pieces will there actually be
   const count = Math.floor((encodedByteBuffer.limit - 1) / size) + 1 || 1;
@@ -56,4 +61,4 @@ function encode(data: any, options: any): any {
   return result;
 }
 
-export { encode };
+export { encodeEnvelope };