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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hd-transport",
-  "version": "1.2.0-alpha.2",
+  "version": "1.2.0-alpha.20",
   "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": "6c183b7f7027f4b4d3db4f427f6360351a6c6680"
+  "gitHead": "5fbc1ada90fd3cfda7e5ef08be368cb452018733"
 }

package/scripts/protobuf-build.sh

@@ -2,35 +2,29 @@
 
 set -euxo pipefail
 
-echo $#
-
-PARENT_PATH=$( cd "$(dirname "${BASH_SOURCE[0]}")" ; pwd -P )
+PARENT_PATH=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)
 PACKAGE_ROOT="$PARENT_PATH/.."
+REPO_ROOT="$PARENT_PATH/../../.."
+CORE_MESSAGES_DIR="$REPO_ROOT/packages/core/src/data/messages"
 
 SRC="../../submodules/firmware/common/protob"
 DIST="."
 LANG="typescript"
-# Absolute paths — resolved relative to this script's directory
-REPO_ROOT="$PARENT_PATH/../../.."
-CORE_MESSAGES_DIR="$REPO_ROOT/packages/core/src/data/messages"
 
-if [[ $# -ne 0 && $# -ne 3 ]]
-    then
-        echo "must provide either 3 or 0 arguments. $# provided"
-        exit 1
+if [[ $# -ne 0 && $# -ne 3 ]]; then
+    echo "must provide either 3 or 0 arguments. $# provided"
+    exit 1
 fi
 
-if [[ $# -eq 3 ]]
-    then
-        SRC=$1
-        DIST=$2
-        LANG=$3
+if [[ $# -eq 3 ]]; then
+    SRC=$1
+    DIST=$2
+    LANG=$3
 fi
 
-if [[ "$LANG" != "typescript" && "$LANG" != "flow" ]];
-    then
-        echo "either typescript or flow must be specified as the third argument"
-        exit 1
+if [[ "$LANG" != "typescript" && "$LANG" != "flow" ]]; then
+    echo "either typescript or flow must be specified as the third argument"
+    exit 1
 fi
 
 if [[ "$SRC" = /* ]]; then
@@ -45,308 +39,100 @@ else
     DIST_PATH="$PACKAGE_ROOT/$DIST"
 fi
 
-# Remove temp proto files on any exit, including failure paths
-trap 'rm -f "$DIST_PATH/messages-tmp.proto" "$PARENT_PATH/messages-protocol-v2-tmp.proto"' EXIT
-
-
-# ============================================================
-# BUILD Pro1 messages.json  (requires firmware submodule)
-# ============================================================
-# Combines all messages*.proto files from firmware submodule into
-# messages.json, then copies to core package.
-if [ -d "$SRC_PATH" ] && ls "$SRC_PATH"/messages*.proto 1>/dev/null 2>&1; then
-    echo "=== Building Pro1 (legacy) protobuf messages ==="
-    TMP_PROTO="$DIST_PATH/messages-tmp.proto"
-    echo 'syntax = "proto2";' > "$TMP_PROTO"
-    echo 'import "google/protobuf/descriptor.proto";' >> "$TMP_PROTO"
-    echo "Build proto file from $SRC_PATH"
-    grep -hv -e '^import ' -e '^syntax' -e '^package' -e 'option java_' "$SRC_PATH"/messages*.proto \
-    | sed 's/ hw\.trezor\.messages\.common\./ /' \
-    | sed 's/ common\./ /' \
-    | sed 's/ ethereum_definitions\./ /' \
-    | sed 's/ management\./ /' \
-    | sed 's/^option /\/\/ option /' \
-    | grep -v '    reserved '>> "$TMP_PROTO"
-
-    npx pbjs -t json -p "$DIST_PATH" -o "$DIST_PATH/messages.json" --keep-case "$TMP_PROTO"
-    rm "$TMP_PROTO"
-
-    # Copy to core package
-    cp "$DIST_PATH/messages.json" "$CORE_MESSAGES_DIR/messages.json"
-    echo "Pro1 messages.json copied to core"
-
-    yarn --cwd "$PACKAGE_ROOT" prettier --write "$DIST_PATH/messages.json"
-    yarn --cwd "$PACKAGE_ROOT" prettier --write "$CORE_MESSAGES_DIR/messages.json"
-    # Type generation (protobuf-types.js) runs once at the end of the Protocol V2
-    # section below, after both schemas are available.
-else
-    # Intentional asymmetry with the Protocol V2 section below: the legacy firmware
-    # submodule is optional (the committed messages.json stays in use when it is
-    # absent), while firmware-pro2 is the only source of the Protocol V2 schema,
-    # so its absence is a hard error (exit 1).
-    echo "⚠️  firmware submodule not found at $SRC_PATH"
-    echo "    Skipping Pro1 protobuf build. To enable:"
-    echo "    git submodule update --init submodules/firmware"
-fi
-
-
-# ============================================================
-# BUILD Protocol V2 messages-protocol-v2.json
-# ============================================================
-# Source of truth: submodules/firmware-pro2/sys/protobuf/onekey_protocol/.
-# Protocol V2 keeps chain/app protocols under legacy/ and system protocols under latest/.
-# The SDK flattens them into one protobuf schema for transport runtime, but it must keep
-# firmware message names and enum values intact. SDK-facing aliases belong in core/API code,
-# not in the protobuf schema.
-# ============================================================
-cd "$PARENT_PATH"
-
+V1_TMP_PROTO="$DIST_PATH/messages-tmp.proto"
+V2_TMP_PROTO="$PARENT_PATH/messages-protocol-v2-tmp.proto"
+trap 'rm -f "$V1_TMP_PROTO" "$V2_TMP_PROTO"' EXIT
+
+echo "=== Building Protocol V1 messages ==="
+echo 'syntax = "proto2";' > "$V1_TMP_PROTO"
+echo 'import "google/protobuf/descriptor.proto";' >> "$V1_TMP_PROTO"
+grep -hv -e '^import ' -e '^syntax' -e '^package' -e 'option java_' "$SRC_PATH"/messages*.proto \
+| sed 's/ hw\.trezor\.messages\.common\./ /' \
+| sed 's/ common\./ /' \
+| sed 's/ ethereum_definitions\./ /' \
+| sed 's/ management\./ /' \
+| sed 's/^option /\/\/ option /' \
+| grep -v '    reserved ' >> "$V1_TMP_PROTO"
+
+npx pbjs -t json -p "$DIST_PATH" -o "$DIST_PATH/messages.json" --keep-case "$V1_TMP_PROTO"
+cp "$DIST_PATH/messages.json" "$CORE_MESSAGES_DIR/messages.json"
+
+echo "=== Building Protocol V2 messages ==="
 SRC_PRO2_LEGACY="$REPO_ROOT/submodules/firmware-pro2/sys/protobuf/onekey_protocol/legacy"
 SRC_PRO2_LATEST="$REPO_ROOT/submodules/firmware-pro2/sys/protobuf/onekey_protocol/latest"
 
-if [ -d "$SRC_PRO2_LATEST" ] && ls "$SRC_PRO2_LATEST"/messages*.proto 1>/dev/null 2>&1; then
-    echo "=== Building Protocol V2 messages from firmware-pro2 legacy + latest protobuf schema ==="
-    TMP_PROTO="$PARENT_PATH/messages-protocol-v2-tmp.proto"
-
-    {
-        echo 'syntax = "proto2";'
-        echo 'import "google/protobuf/descriptor.proto";'
-        echo ''
-
-        # Pro2 firmware keeps chain/app protocols under legacy/, and Protocol V2
-        # device/filesystem/firmware protocols under latest/. Build one flat
-        # schema so Protocol V2 framing can also encode legacy public-chain calls.
-        grep -hv \
-            -e '^import ' -e '^syntax' -e '^package' -e 'option java_' \
-            "$SRC_PRO2_LEGACY"/messages*.proto \
-            | sed 's/ hw\.onekey\.messages\.[a-zA-Z_]*\./ /g' \
-            | sed 's/ crypto\./ /g' \
-            | sed 's/ ethereum_definitions\./ /g' \
-            | sed 's/ management\./ /g' \
-            | sed 's/^option /\/\/ option /' \
-            | grep -v '    reserved '
-
-        if ! grep -q '^message TonSignData ' "$SRC_PRO2_LEGACY"/messages*.proto; then
-            echo ''
-            echo '// --- TON signData (kept until firmware-pro2 legacy proto exports it) ---'
-            echo 'message TonSignData {'
-            echo '    repeated uint32 address_n = 1;'
-            echo '    required TonSignDataType type = 2;'
-            echo '    required bytes payload = 3;'
-            echo '    optional string schema = 4;'
-            echo '    required string appdomain = 5;'
-            echo '    required uint64 timestamp = 6;'
-            echo '    optional string from_address = 7;'
-            echo '    optional TonWalletVersion wallet_version = 8 [default=V4R2];'
-            echo '    optional uint32 wallet_id = 9 [default=698983191];'
-            echo '    optional TonWorkChain workchain = 10 [default=BASECHAIN];'
-            echo '    optional bool is_bounceable = 11 [default=false];'
-            echo '    optional bool is_testnet_only = 12 [default=false];'
-            echo ''
-            echo '    enum TonSignDataType {'
-            echo '        TEXT = 0;'
-            echo '        BINARY = 1;'
-            echo '        CELL = 2;'
-            echo '    }'
-            echo '}'
-            echo ''
-            echo 'message TonSignedData {'
-            echo '    optional bytes signature = 1;'
-            echo '    optional bytes digest = 2;'
-            echo '}'
-        fi
-
-        echo ''
-        echo '// --- Protocol V2 system messages ---'
-        grep -hv \
-            -e '^import ' -e '^syntax' -e '^package' -e 'option java_' \
-            -e '^option ' \
-            "$SRC_PRO2_LATEST"/messages*.proto \
-            | grep -v '    reserved '
-
-        if ! grep -q '^message GetOnboardingStatus ' "$SRC_PRO2_LATEST"/messages*.proto; then
-            echo ''
-            echo '// --- Onboarding status (kept until firmware-pro2 latest proto exports it) ---'
-            echo 'enum OnboardingStep {'
-            echo '    ONBOARDING_STEP_UNKNOWN = 0;'
-            echo '    ONBOARDING_STEP_DEVICE_VERIFICATION = 1;'
-            echo '    ONBOARDING_STEP_PERSONALIZATION = 2;'
-            echo '    ONBOARDING_STEP_SETUP = 3;'
-            echo '    ONBOARDING_STEP_FIRMWARE = 4;'
-            echo '}'
-            echo ''
-            echo 'message GetOnboardingStatus {'
-            echo '}'
-            echo ''
-            echo 'message OnboardingStatus {'
-            echo '    message Setup {'
-            echo '        message NewDevice {'
-            echo '            optional bool seedcard_backup = 1;'
-            echo '        }'
-            echo '        message Restore {'
-            echo '            optional bool mnemonic = 1;'
-            echo '            optional bool seedcard = 2;'
-            echo '        }'
-            echo '        optional NewDevice new_device = 1;'
-            echo '        optional Restore restore = 2;'
-            echo '    }'
-            echo '    required OnboardingStep step = 1;'
-            echo '    optional Setup setup = 2;'
-            echo '    optional uint32 detail_code = 3;'
-            echo '    optional string detail_str = 4;'
-            echo '}'
-        fi
-    } > "$TMP_PROTO"
-
-    if ! grep -q 'MessageType_TonSignData' "$TMP_PROTO"; then
-        node - "$TMP_PROTO" <<'NODE'
-const fs = require('fs');
-
-const protoPath = process.argv[2];
-const proto = fs.readFileSync(protoPath, 'utf8');
-const updated = proto.replace(
-  /(    MessageType_TonTxAck\s*=\s*11907[^\n]*;\n)/,
-  `$1    MessageType_TonSignData = 11908 [(wire_in) = true];\n    MessageType_TonSignedData = 11909 [(wire_out) = true];\n`
-);
-
-if (updated === proto) {
-  throw new Error('Unable to insert TON signData MessageType entries into Pro2 schema');
-}
-
-fs.writeFileSync(protoPath, updated);
-NODE
-    fi
-
-    if ! grep -q 'MessageType_GetOnboardingStatus' "$TMP_PROTO"; then
-        node - "$TMP_PROTO" <<'NODE'
-const fs = require('fs');
-
-const protoPath = process.argv[2];
-const proto = fs.readFileSync(protoPath, 'utf8');
-const updated = proto.replace(
-  /(    MessageType_DeviceInfo\s*=\s*60601[^\n]*;\n)/,
-  `$1    MessageType_GetOnboardingStatus = 60602;\n    MessageType_OnboardingStatus = 60603;\n`
-);
-
-if (updated === proto) {
-  throw new Error('Unable to insert onboarding MessageType entries into Pro2 schema');
-}
-
-fs.writeFileSync(protoPath, updated);
-NODE
-    fi
+if [[ ! -d "$SRC_PRO2_LEGACY" || ! -d "$SRC_PRO2_LATEST" ]]; then
+    echo "firmware-pro2 protobuf schema is missing"
+    exit 1
+fi
 
-    node - "$TMP_PROTO" <<'NODE'
+{
+    echo 'syntax = "proto2";'
+    echo 'import "google/protobuf/descriptor.proto";'
+    echo ''
+    grep -hv \
+        -e '^import ' -e '^syntax' -e '^package' -e 'option java_' \
+        "$SRC_PRO2_LEGACY"/messages*.proto \
+        | sed 's/ hw\.onekey\.messages\.[a-zA-Z_]*\./ /g' \
+        | sed 's/ crypto\./ /g' \
+        | sed 's/ ethereum_definitions\./ /g' \
+        | sed 's/ management\./ /g' \
+        | sed 's/^option /\/\/ option /' \
+        | grep -v '    reserved '
+    echo ''
+    echo '// --- Protocol V2 system messages ---'
+    grep -hv \
+        -e '^import ' -e '^syntax' -e '^package' -e 'option java_' -e '^option ' \
+        "$SRC_PRO2_LATEST"/messages*.proto \
+        | grep -v '    reserved '
+} > "$V2_TMP_PROTO"
+
+# Protocol V2 latest schema defines common request names that also exist in
+# legacy chain messages. Keep the legacy definitions and remove the duplicate
+# top-level latest declarations before protobufjs parses the flattened schema.
+node - "$V2_TMP_PROTO" <<'NODE'
 const fs = require('fs');
 
 const protoPath = process.argv[2];
-const proto = fs.readFileSync(protoPath, 'utf8');
-const messageNames = new Set(
-  Array.from(proto.matchAll(/^\s*message\s+([A-Za-z_][A-Za-z0-9_]*)\s*\{/gm)).map(
-    match => match[1]
-  )
-);
-const messageTypeNames = new Set(
-  Array.from(proto.matchAll(/^\s*MessageType_([A-Za-z_][A-Za-z0-9_]*)\s*=/gm)).map(
-    match => match[1]
-  )
-);
-const requiredMessages = [
-  'Ping',
-  'Success',
-  'Failure',
-  'DevReboot',
-  'DevGetDeviceInfo',
-  'DeviceInfo',
-  'DevFirmwareUpdate',
-  'DevFirmwareInstallProgress',
-  'DevGetFirmwareUpdateStatus',
-  'DevFirmwareUpdateStatus',
-  'FilesystemFixPermission',
-  'FilesystemPathInfo',
-  'FilesystemPathInfoQuery',
-  'FilesystemFile',
-  'FilesystemFileRead',
-  'FilesystemFileWrite',
-  'FilesystemFileDelete',
-  'FilesystemDir',
-  'FilesystemDirList',
-  'FilesystemDirMake',
-  'FilesystemDirRemove',
-  'FilesystemFormat',
-  'TonSignData',
-  'TonSignedData',
-  'GetOnboardingStatus',
-  'OnboardingStatus',
-];
-const missingMessages = requiredMessages.filter(name => !messageNames.has(name));
-const missingMessageTypes = requiredMessages.filter(name => !messageTypeNames.has(name));
-
-if (missingMessages.length > 0 || missingMessageTypes.length > 0) {
-  throw new Error(
-    `Protocol V2 schema missing required entries: messages=[${missingMessages.join(
-      ', '
-    )}], messageTypes=[${missingMessageTypes.join(
-      ', '
-    )}]. Make sure submodules/firmware-pro2 is checked out on branch dev_romloader_split ` +
-      '(origin/dev_romloader_split), which contains the Filesystem*/DevFirmwareUpdate/DevReboot messages.'
-  );
+let proto = fs.readFileSync(protoPath, 'utf8');
+
+function removeLastTopLevelMessage(source, name) {
+  const pattern = new RegExp(`(^|\\n)message\\s+${name}\\s*\\{`, 'gm');
+  const matches = Array.from(source.matchAll(pattern));
+  if (matches.length < 2) return source;
+  const match = matches[matches.length - 1];
+  const start = match.index + (match[1] ? match[1].length : 0);
+  let depth = 0;
+  for (let index = start; index < source.length; index += 1) {
+    if (source[index] === '{') depth += 1;
+    if (source[index] === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        let end = index + 1;
+        while (end < source.length && /\\s/.test(source[end])) end += 1;
+        return `${source.slice(0, start)}${source.slice(end)}`;
+      }
+    }
+  }
+  throw new Error(`Unterminated message block: ${name}`);
 }
 
-// Provisional wire IDs injected by this script for messages the firmware proto does
-// not export yet (pending firmware confirmation, see
-// docs/protocol-v2-deviceinfo-field-gaps.md). If the firmware submodule starts
-// exporting these MessageType entries itself, the injection above is skipped and the
-// firmware-assigned IDs flow into TMP_PROTO — assert they still match the IDs the SDK
-// was built against, and fail loudly on any drift.
-const expectedInjectedIds = {
-  TonSignData: 11908,
-  TonSignedData: 11909,
-  GetOnboardingStatus: 60602,
-  OnboardingStatus: 60603,
-};
-const actualIds = {};
-for (const match of proto.matchAll(/^\s*MessageType_([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(\d+)/gm)) {
-  actualIds[match[1]] = Number(match[2]);
-}
-const idMismatches = Object.entries(expectedInjectedIds)
-  .filter(([name, id]) => name in actualIds && actualIds[name] !== id)
-  .map(([name, id]) => `${name}: expected ${id}, firmware proto has ${actualIds[name]}`);
+['Initialize', 'GetFeatures', 'OnekeyGetFeatures', 'Features'].forEach(name => {
+  proto = removeLastTopLevelMessage(proto, name);
+});
 
-if (idMismatches.length > 0) {
-  throw new Error(
-    `Protocol V2 injected MessageType wire IDs conflict with the firmware proto: ${idMismatches.join(
-      '; '
-    )}. Update the injected IDs in protobuf-build.sh and the registry section in ` +
-      'docs/protocol-v2-deviceinfo-field-gaps.md.'
-  );
-}
+fs.writeFileSync(protoPath, proto);
 NODE
 
-    npx pbjs -t json \
-        -p "$PARENT_PATH" \
-        -o "$PARENT_PATH/../messages-protocol-v2.json" \
-        --keep-case \
-        "$(basename "$TMP_PROTO")"
+npx pbjs -t json -p "$PARENT_PATH" -o "$PACKAGE_ROOT/messages-protocol-v2.json" --keep-case "$V2_TMP_PROTO"
+cp "$PACKAGE_ROOT/messages-protocol-v2.json" "$CORE_MESSAGES_DIR/messages-protocol-v2.json"
 
-    rm -f "$TMP_PROTO"
-
-    cp "$PARENT_PATH/../messages-protocol-v2.json" "$CORE_MESSAGES_DIR/messages-protocol-v2.json"
-    echo "Protocol V2 messages-protocol-v2.json generated from firmware-pro2 legacy + latest schema and copied to core"
-
-    yarn --cwd "$PACKAGE_ROOT" prettier --write "$PARENT_PATH/../messages-protocol-v2.json"
-    yarn --cwd "$PACKAGE_ROOT" prettier --write "$CORE_MESSAGES_DIR/messages-protocol-v2.json"
+echo "generating type definitions for: $LANG"
+cd "$PARENT_PATH"
+node ./protobuf-types.js "$LANG"
 
-    echo "generating type definitions for: $LANG"
-    node ./protobuf-types.js $LANG
-    yarn --cwd "$PACKAGE_ROOT" prettier --write "$PACKAGE_ROOT/src/types/messages.ts"
-    echo "=== Protocol V2 messages build complete ==="
-else
-    # Unlike the optional Pro1 (legacy) section above, the firmware-pro2 submodule is
-    # the only source of the Protocol V2 schema, so a missing checkout is a hard error.
-    echo "firmware-pro2 latest protobuf schema not found at $SRC_PRO2_LATEST"
-    echo "The Protocol V2 schema requires firmware-pro2 on branch dev_romloader_split."
-    echo "Run: git submodule update --init submodules/firmware-pro2"
-    echo "Then: git -C submodules/firmware-pro2 fetch origin dev_romloader_split && git -C submodules/firmware-pro2 checkout origin/dev_romloader_split"
-    exit 1
-fi
+yarn --cwd "$PACKAGE_ROOT" prettier --write "$DIST_PATH/messages.json"
+yarn --cwd "$PACKAGE_ROOT" prettier --write "$CORE_MESSAGES_DIR/messages.json"
+yarn --cwd "$PACKAGE_ROOT" prettier --write "$PACKAGE_ROOT/messages-protocol-v2.json"
+yarn --cwd "$PACKAGE_ROOT" prettier --write "$CORE_MESSAGES_DIR/messages-protocol-v2.json"
+yarn --cwd "$PACKAGE_ROOT" prettier --write "$PACKAGE_ROOT/src/types/messages.ts"

package/scripts/protobuf-patches/index.js

@@ -210,6 +210,7 @@ const TYPE_PATCH = {
   'TonSignMessage.ext_ton_amount': UINT_TYPE,
   'TonSignData.timestamp': UINT_TYPE,
   'TonSignProof.expire_at': UINT_TYPE,
+  'TonSignData.timestamp': UINT_TYPE,
 };
 
 const DEFINITION_PATCH = {

package/scripts/protobuf-types.js

@@ -19,6 +19,10 @@ 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));
 
@@ -53,12 +57,16 @@ const ENUM_KEYS = [
   'InputScriptType',
   'OutputScriptType',
   'RequestType',
+  'KaspaInputScriptType',
+  'KaspaOutputScriptType',
+  'KaspaRequestType',
   'BackupType',
   'Capability',
   'SafetyCheckLevel',
   'ButtonRequestType',
   'PinMatrixRequestType',
   'WordRequestType',
+  'ProtocolV2Capability',
 ];
 
 const parseEnumTypescript = (itemName, item) => {
@@ -317,6 +325,10 @@ 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

package/src/constants.ts

@@ -1,44 +1,50 @@
 // ---- Protocol V1 (Pro1 / Touch / Mini / Classic) ----
 
-/** Protocol V1 USB report 标记，ASCII '?'。 */
+/** Protocol V1 USB report marker, ASCII `?`. */
 export const PROTOCOL_V1_REPORT_ID = 0x3f;
 
-/** Protocol V1 envelope 头部标记，ASCII '#'。 */
+/** Protocol V1 envelope marker, ASCII `#`. */
 export const PROTOCOL_V1_HEADER_BYTE = 0x23;
 
-/** Protocol V1 单个 chunk 去掉 report 标记后的可用 payload 长度。 */
+/** Protocol V1 payload bytes per chunk after the report marker. */
 export const PROTOCOL_V1_CHUNK_PAYLOAD_SIZE = 63;
 
-/** Protocol V1 USB packet 长度：report 标记 + chunk payload。 */
+/** 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：message type 2 字节 + payload length 4 字节。 */
+/** 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 + payload length。 */
+/** 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) ----
 
-/** Protocol V2 单帧最大长度，包含 header、payload 和 CRC；需容纳 4096 数据块及 protobuf 开销。 */
-export const PROTOCOL_V2_FRAME_MAX_BYTES = 4608;
+/** Firmware Proto Link runtime limit for a complete V2 frame, including header and CRC. */
+export const PROTOCOL_V2_FRAME_MAX_BYTES = 4200;
 
-/** WebUSB 下 FilesystemFileWrite 的文件数据分块大小。 */
-export const PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE = 4096;
+/** FilesystemFileWrite chunk size over WebUSB. */
+export const PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE = 4000;
 
-/** BLE 下 FilesystemFileWrite 的文件数据分块大小。 */
+/** FilesystemFileWrite chunk size over BLE. */
 export const PROTOCOL_V2_BLE_FILE_CHUNK_SIZE = 1800;
 
-/** @deprecated 使用按传输区分的 PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE / PROTOCOL_V2_BLE_FILE_CHUNK_SIZE。 */
+/** 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;
 
 /**
- * Protocol V2 路由 channel。
- * USB 端点直接到主 MCU，不需要 proto-link 路由；BLE 需要经过 BLE 协处理器 UART bridge。
+ * Protocol V2 routing channel. USB reaches the main MCU directly, while BLE routes
+ * through the BLE coprocessor UART bridge.
  */
 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。 */
+/** packet_src for protobuf commands; firmware routes zero to the protobuf dispatcher. */
 export const PROTOCOL_V2_PACKET_SRC_COMMAND = 0;

package/src/index.ts

@@ -10,8 +10,11 @@ import {
 } 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,
@@ -49,6 +52,8 @@ 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,
@@ -58,7 +63,10 @@ export default {
   ProtocolV2,
   PROTOCOL_V2_SYS_MESSAGE_THRESHOLD,
   ProtocolV2FrameAssembler,
+  ProtocolV2LinkManager,
+  ProtocolV2SequenceCursor,
   ProtocolV2Session,
+  ProtocolV2UsbTransportBase,
   bytesToHex,
   concatUint8Arrays,
   createMessageFromName,