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

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 };

package/src/protocols/v1/index.ts

@@ -0,0 +1,4 @@
+export * from './decode';
+export * from './encode';
+export * from './packets';
+export * from './receive';

package/src/protocols/v1/packets.ts

@@ -0,0 +1,53 @@
+import ByteBuffer from 'bytebuffer';
+
+import { encode as encodeProtobuf } from '../../serialization/protobuf';
+import { encodeEnvelope } from './encode';
+import { createMessageFromName } from '../../serialization/protobuf/messages';
+import { PROTOCOL_V1_CHUNK_PAYLOAD_SIZE, PROTOCOL_V1_REPORT_ID } from '../../constants';
+
+import type { Root } from 'protobufjs/light';
+
+export function encodeEnvelopeMessage(messages: Root, name: string, data: Record<string, unknown>) {
+  const { Message, messageTypeId } = createMessageFromName(messages, name);
+
+  const buffer = encodeProtobuf(Message, data);
+  return encodeEnvelope(buffer, {
+    addTrezorHeaders: false,
+    chunked: false,
+    messageTypeId,
+  });
+}
+
+export const encodeMessageChunks = (
+  messages: Root,
+  name: string,
+  data: Record<string, unknown>
+) => {
+  const { Message, messageTypeId } = createMessageFromName(messages, name);
+  const buffer = encodeProtobuf(Message, data);
+  return encodeEnvelope(buffer, {
+    addTrezorHeaders: true,
+    chunked: true,
+    messageTypeId,
+  });
+};
+
+export const encodeTransportPackets = (
+  messages: Root,
+  name: string,
+  data: Record<string, unknown>
+) => {
+  const encodeBuffers = encodeMessageChunks(messages, name, data);
+
+  const outBuffers: ByteBuffer[] = [];
+
+  for (const buf of encodeBuffers) {
+    const chunkBuffer = new ByteBuffer(PROTOCOL_V1_CHUNK_PAYLOAD_SIZE + 1);
+    chunkBuffer.writeByte(PROTOCOL_V1_REPORT_ID);
+    chunkBuffer.append(buf);
+    chunkBuffer.reset();
+    outBuffers.push(chunkBuffer);
+  }
+
+  return outBuffers;
+};

package/src/{serialization → protocols/v1}/receive.ts

@@ -1,15 +1,15 @@
 import ByteBuffer from 'bytebuffer';
 
-import * as decodeProtobuf from './protobuf/decode';
-import * as decodeProtocol from './protocol/decode';
-import { createMessageFromType } from './protobuf/messages';
+import * as decodeProtobuf from '../../serialization/protobuf/decode';
+import { decodeEnvelope } from './decode';
+import { createMessageFromType } from '../../serialization/protobuf/messages';
 
 import type { Root } from 'protobufjs/light';
 
-export function receiveOne(messages: Root, data: string) {
+export function decodeMessage(messages: Root, data: string) {
   const bytebuffer = ByteBuffer.wrap(data, 'hex');
 
-  const { typeId, buffer } = decodeProtocol.decode(bytebuffer);
+  const { typeId, buffer } = decodeEnvelope(bytebuffer);
   const { Message, messageName } = createMessageFromType(messages, typeId);
   const message = decodeProtobuf.decode(Message, buffer);
   return {

package/src/protocols/v2/constants.ts

@@ -0,0 +1,7 @@
+export const PROTO_HEAD_SOF = 0x5a;
+export const PROTO_PRE_HEAD_SIZE = 4;
+export const PROTO_HEAD_CRC_SIZE = 8;
+export const CRC8_INIT = 0x30;
+export const PACKET_SIZE = 4096;
+export const PROTO_DATA_TYPE_PACKET = 0;
+export const PROTO_DATA_TYPE_ACK = 1;

package/src/protocols/v2/crc8.ts

@@ -0,0 +1,34 @@
+import { CRC8_INIT } from './constants';
+
+// Protocol V2 帧校验用的 CRC-8 查表，不是设备或业务数据。
+// 表值与固件侧 crc8 实现保持一致；初始值见 CRC8_INIT。
+export const CRC8_TABLE = new Uint8Array([
+  0x00, 0x5e, 0xbc, 0xe2, 0x61, 0x3f, 0xdd, 0x83, 0xc2, 0x9c, 0x7e, 0x20, 0xa3, 0xfd, 0x1f, 0x41,
+  0x9d, 0xc3, 0x21, 0x7f, 0xfc, 0xa2, 0x40, 0x1e, 0x5f, 0x01, 0xe3, 0xbd, 0x3e, 0x60, 0x82, 0xdc,
+  0x23, 0x7d, 0x9f, 0xc1, 0x42, 0x1c, 0xfe, 0xa0, 0xe1, 0xbf, 0x5d, 0x03, 0x80, 0xde, 0x3c, 0x62,
+  0xbe, 0xe0, 0x02, 0x5c, 0xdf, 0x81, 0x63, 0x3d, 0x7c, 0x22, 0xc0, 0x9e, 0x1d, 0x43, 0xa1, 0xff,
+  0x46, 0x18, 0xfa, 0xa4, 0x27, 0x79, 0x9b, 0xc5, 0x84, 0xda, 0x38, 0x66, 0xe5, 0xbb, 0x59, 0x07,
+  0xdb, 0x85, 0x67, 0x39, 0xba, 0xe4, 0x06, 0x58, 0x19, 0x47, 0xa5, 0xfb, 0x78, 0x26, 0xc4, 0x9a,
+  0x65, 0x3b, 0xd9, 0x87, 0x04, 0x5a, 0xb8, 0xe6, 0xa7, 0xf9, 0x1b, 0x45, 0xc6, 0x98, 0x7a, 0x24,
+  0xf8, 0xa6, 0x44, 0x1a, 0x99, 0xc7, 0x25, 0x7b, 0x3a, 0x64, 0x86, 0xd8, 0x5b, 0x05, 0xe7, 0xb9,
+  0x8c, 0xd2, 0x30, 0x6e, 0xed, 0xb3, 0x51, 0x0f, 0x4e, 0x10, 0xf2, 0xac, 0x2f, 0x71, 0x93, 0xcd,
+  0x11, 0x4f, 0xad, 0xf3, 0x70, 0x2e, 0xcc, 0x92, 0xd3, 0x8d, 0x6f, 0x31, 0xb2, 0xec, 0x0e, 0x50,
+  0xaf, 0xf1, 0x13, 0x4d, 0xce, 0x90, 0x72, 0x2c, 0x6d, 0x33, 0xd1, 0x8f, 0x0c, 0x52, 0xb0, 0xee,
+  0x32, 0x6c, 0x8e, 0xd0, 0x53, 0x0d, 0xef, 0xb1, 0xf0, 0xae, 0x4c, 0x12, 0x91, 0xcf, 0x2d, 0x73,
+  0xca, 0x94, 0x76, 0x28, 0xab, 0xf5, 0x17, 0x49, 0x08, 0x56, 0xb4, 0xea, 0x69, 0x37, 0xd5, 0x8b,
+  0x57, 0x09, 0xeb, 0xb5, 0x36, 0x68, 0x8a, 0xd4, 0x95, 0xcb, 0x29, 0x77, 0xf4, 0xaa, 0x48, 0x16,
+  0xe9, 0xb7, 0x55, 0x0b, 0x88, 0xd6, 0x34, 0x6a, 0x2b, 0x75, 0x97, 0xc9, 0x4a, 0x14, 0xf6, 0xa8,
+  0x74, 0x2a, 0xc8, 0x96, 0x15, 0x4b, 0xa9, 0xf7, 0xb6, 0xe8, 0x0a, 0x54, 0xd7, 0x89, 0x6b, 0x35,
+]);
+
+/**
+ * Compute CRC-8 over the first len bytes using the firmware-compatible initial value.
+ */
+export function crc8(data: Uint8Array, len: number): number {
+  let crc = CRC8_INIT;
+  for (let i = 0; i < len; i++) {
+    // eslint-disable-next-line no-bitwise
+    crc = CRC8_TABLE[crc ^ data[i]];
+  }
+  return crc;
+}

package/src/protocols/v2/decode.ts

@@ -0,0 +1,89 @@
+import { PROTO_DATA_TYPE_ACK, PROTO_HEAD_CRC_SIZE, PROTO_HEAD_SOF } from './constants';
+import { crc8 } from './crc8';
+
+export interface ProtoV2Frame {
+  /** Little-endian message type ID */
+  messageTypeId: number;
+  /** Raw protobuf-encoded payload (bytes after the 2-byte messageTypeId) */
+  pbPayload: Uint8Array;
+  /** Sequence number from the frame header */
+  seq: number;
+}
+
+function validateFrame(data: Uint8Array): number {
+  if (data.length < PROTO_HEAD_CRC_SIZE) {
+    throw new Error(`Protocol V2 frame too short: ${data.length} bytes`);
+  }
+
+  if (data[0] !== PROTO_HEAD_SOF) {
+    throw new Error(
+      `Invalid SOF byte: expected 0x5A, got 0x${data[0].toString(16).padStart(2, '0')}`
+    );
+  }
+
+  const frameLen = data[1] + data[2] * 256;
+
+  if (data.length < frameLen) {
+    throw new Error(`Frame truncated: expected ${frameLen} bytes, got ${data.length}`);
+  }
+
+  const expectedHeaderCrc = crc8(data, 3);
+  if (data[3] !== expectedHeaderCrc) {
+    throw new Error(
+      `Header CRC mismatch: expected 0x${expectedHeaderCrc
+        .toString(16)
+        .padStart(2, '0')}, got 0x${data[3].toString(16).padStart(2, '0')}`
+    );
+  }
+
+  const expectedFrameCrc = crc8(data, frameLen - 1);
+  if (data[frameLen - 1] !== expectedFrameCrc) {
+    throw new Error(
+      `Frame CRC mismatch: expected 0x${expectedFrameCrc
+        .toString(16)
+        .padStart(2, '0')}, got 0x${data[frameLen - 1].toString(16).padStart(2, '0')}`
+    );
+  }
+
+  return frameLen;
+}
+
+export function isAckFrame(data: Uint8Array): boolean {
+  // eslint-disable-next-line no-bitwise
+  if (data.length < 6 || (data[5] & 0x03) !== PROTO_DATA_TYPE_ACK) {
+    return false;
+  }
+
+  const frameLen = validateFrame(data);
+  if (frameLen !== PROTO_HEAD_CRC_SIZE) {
+    throw new Error(`Invalid Protocol V2 ACK frame length: ${frameLen}`);
+  }
+  return true;
+}
+
+/**
+ * Parse and validate a Protocol V2 response frame.
+ *
+ * Validates:
+ *   - SOF byte (0x5A)
+ *   - Header CRC (bytes 0-2)
+ *   - Frame CRC (full frame except last byte)
+ *
+ * Returns the decoded messageTypeId, raw protobuf payload, and sequence number.
+ */
+export function decodeFrame(data: Uint8Array): ProtoV2Frame {
+  const frameLen = validateFrame(data);
+
+  const seq = data[6];
+  // Payload spans bytes 7 to frameLen-2 (inclusive), excluding final CRC byte
+  const payloadData = data.slice(7, frameLen - 1);
+
+  if (payloadData.length < 2) {
+    throw new Error(`Protocol V2 payload too short (need >=2 bytes for messageTypeId)`);
+  }
+
+  const messageTypeId = payloadData[0] + payloadData[1] * 256;
+  const pbPayload = payloadData.slice(2);
+
+  return { messageTypeId, pbPayload, seq };
+}

package/src/protocols/v2/encode.ts

@@ -0,0 +1,90 @@
+import { PROTO_DATA_TYPE_PACKET, PROTO_HEAD_CRC_SIZE, PROTO_HEAD_SOF } from './constants';
+import { crc8 } from './crc8';
+import { PROTOCOL_V2_FRAME_MAX_BYTES } from '../../constants';
+
+// Default sequence number when callers do not manage one themselves.
+// Stateful per-session sequencing lives in ProtocolV2Session (session.ts),
+// which advances the counter via nextProtoSeq() and passes it in explicitly.
+const PROTO_SEQ_DEFAULT = 1;
+
+/**
+ * Advance a Protocol V2 sequence counter: 1-255, wraps around skipping 0.
+ */
+export function nextProtoSeq(current: number): number {
+  return current >= 255 ? 1 : current + 1;
+}
+
+/**
+ * Build a raw Protocol V2 frame (0x5A framing).
+ *
+ * Frame layout (PROTO_HEAD_CRC_SIZE = 8 overhead bytes):
+ *   [0]      SOF  = 0x5A
+ *   [1]      frameLen low byte
+ *   [2]      frameLen high byte
+ *   [3]      CRC8 of bytes 0-2 (pre-header CRC)
+ *   [4]      router
+ *   [5]      attr = ((packetSrc & 0x0F) << 2) | dataType
+ *   [6]      seq  (1-255, wraps skipping 0)
+ *   [7..N-2] payload
+ *   [N-1]    CRC8 of bytes 0 to N-2 (frame CRC)
+ */
+export function encodeFrame(
+  payload: Uint8Array | null,
+  packetSrc?: number,
+  router?: number,
+  seq?: number
+): Uint8Array {
+  const resolvedPacketSrc = packetSrc ?? 0;
+  const resolvedRouter = router ?? 0;
+  const resolvedSeq = seq ?? PROTO_SEQ_DEFAULT;
+  if (!Number.isInteger(resolvedSeq) || resolvedSeq < 1 || resolvedSeq > 255) {
+    throw new Error(`Protocol V2 seq out of range (1-255): ${resolvedSeq}`);
+  }
+  const payloadLen = payload ? payload.length : 0;
+  const frameLen = payloadLen + PROTO_HEAD_CRC_SIZE;
+  if (frameLen > PROTOCOL_V2_FRAME_MAX_BYTES) {
+    throw new Error(`Protocol V2 frame too large: ${frameLen}`);
+  }
+  const frame = new Uint8Array(frameLen);
+
+  frame[0] = PROTO_HEAD_SOF;
+  frame[1] = frameLen % 256;
+  frame[2] = Math.floor(frameLen / 256) % 256;
+  frame[3] = 0; // placeholder — filled in below
+  frame[4] = resolvedRouter % 256;
+  frame[5] = (resolvedPacketSrc % 16) * 4 + (PROTO_DATA_TYPE_PACKET % 4);
+  frame[6] = resolvedSeq;
+
+  // CRC8 over first 3 bytes (SOF + length)
+  frame[3] = crc8(frame, 3);
+
+  if (payload && payloadLen > 0) {
+    frame.set(payload, 7);
+  }
+
+  // CRC8 over entire frame except last byte
+  frame[frameLen - 1] = crc8(frame, frameLen - 1);
+
+  return frame;
+}
+
+/**
+ * Build a Protocol V2 frame carrying a protobuf message.
+ *
+ * Payload layout:
+ *   [0-1]  messageTypeId as little-endian uint16
+ *   [2..]  protobuf-encoded message bytes
+ */
+export function encodeProtobufFrame(
+  messageTypeId: number,
+  pbPayload: Uint8Array,
+  packetSrc?: number,
+  router?: number,
+  seq?: number
+): Uint8Array {
+  const payload = new Uint8Array(2 + pbPayload.length);
+  payload[0] = messageTypeId % 256;
+  payload[1] = Math.floor(messageTypeId / 256) % 256;
+  payload.set(pbPayload, 2);
+  return encodeFrame(payload, packetSrc, router, seq);
+}

package/src/protocols/v2/frame-assembler.ts

@@ -0,0 +1,98 @@
+import { PROTOCOL_V2_FRAME_MAX_BYTES } from '../../constants';
+import { PROTO_HEAD_CRC_SIZE, PROTO_HEAD_SOF, PROTO_PRE_HEAD_SIZE } from './constants';
+import { crc8 } from './crc8';
+
+export function concatUint8Arrays(arrays: Uint8Array[]): Uint8Array {
+  const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const arr of arrays) {
+    result.set(arr, offset);
+    offset += arr.length;
+  }
+  return result;
+}
+
+export class ProtocolV2FrameAssembler {
+  private buffer = new Uint8Array(0);
+
+  private readonly maxFrameBytes: number;
+
+  constructor(maxFrameBytes = PROTOCOL_V2_FRAME_MAX_BYTES) {
+    this.maxFrameBytes = maxFrameBytes;
+  }
+
+  reset() {
+    this.buffer = new Uint8Array(0);
+  }
+
+  push(chunk: Uint8Array): Uint8Array | undefined {
+    this.append(chunk);
+    return this.extractFrame();
+  }
+
+  /**
+   * Append a chunk (optional) and extract every complete frame currently
+   * buffered. Same validation/throw semantics as push(); push() stays
+   * backward compatible for callers that drain one frame at a time.
+   */
+  drain(chunk: Uint8Array = new Uint8Array(0)): Uint8Array[] {
+    this.append(chunk);
+    const frames: Uint8Array[] = [];
+    for (;;) {
+      const frame = this.extractFrame();
+      if (!frame) break;
+      frames.push(frame);
+    }
+    return frames;
+  }
+
+  private append(chunk: Uint8Array) {
+    if (chunk.length > 0) {
+      this.buffer = concatUint8Arrays([this.buffer, chunk]);
+    }
+  }
+
+  private extractFrame(): Uint8Array | undefined {
+    if (this.buffer.length < 3) return undefined;
+
+    if (this.buffer[0] !== PROTO_HEAD_SOF) {
+      this.reset();
+      throw new Error('Invalid Protocol V2 SOF');
+    }
+
+    const expectedLen = this.buffer[1] + this.buffer[2] * 256;
+    if (expectedLen < PROTO_HEAD_CRC_SIZE) {
+      // A declared length below the 8-byte frame overhead can never become a
+      // complete frame: without resetting, this poison prefix would stay in
+      // the buffer forever and deadlock the caller's drain loop.
+      this.reset();
+      throw new Error(`Protocol V2 frame length too small: ${expectedLen}`);
+    }
+    if (expectedLen > this.maxFrameBytes) {
+      this.reset();
+      throw new Error(`Protocol V2 frame too large: ${expectedLen}`);
+    }
+
+    if (this.buffer.length < PROTO_PRE_HEAD_SIZE) return undefined;
+
+    // Validate the pre-header CRC (byte 3 covers bytes 0-2) as soon as the
+    // first 4 bytes arrive, so a corrupted length field fails fast instead of
+    // waiting for bytes that will never come.
+    const expectedHeaderCrc = crc8(this.buffer, 3);
+    if (this.buffer[3] !== expectedHeaderCrc) {
+      this.reset();
+      throw new Error(
+        `Protocol V2 header CRC mismatch: expected 0x${expectedHeaderCrc
+          .toString(16)
+          .padStart(2, '0')}`
+      );
+    }
+
+    if (this.buffer.length < expectedLen) return undefined;
+
+    const frame = this.buffer.slice(0, expectedLen);
+    this.buffer = this.buffer.slice(expectedLen);
+    return frame;
+  }
+}

package/src/protocols/v2/index.ts

@@ -0,0 +1,5 @@
+export * from './constants';
+export * from './crc8';
+export * from './encode';
+export * from './decode';
+export * from './frame-assembler';

package/src/protocols/v2/link-manager.ts

@@ -0,0 +1,162 @@
+import { ProtocolV2SequenceCursor } from './sequence-cursor';
+import { ProtocolV2Session, getErrorMessage } from './session';
+
+import type { MessageFromOneKey, TransportCallOptions } from '../../types';
+import type { ProtocolV2CallContext, ProtocolV2Schemas, ProtocolV2SessionOptions } from './session';
+
+export type ProtocolV2LinkErrorClassification = 'link-fatal' | 'recoverable';
+
+export interface ProtocolV2LinkAdapter {
+  router: number;
+  maxFrameBytes?: number;
+  generation: number;
+  prepareCall(context: ProtocolV2CallContext): Promise<void> | void;
+  writeFrame(frame: Uint8Array, context: ProtocolV2CallContext): Promise<void>;
+  readFrame(context: ProtocolV2CallContext): Promise<Uint8Array>;
+  reset(reason: string): Promise<void> | void;
+  logger?: ProtocolV2SessionOptions['logger'];
+  logPrefix?: string;
+  createTimeoutError?: ProtocolV2SessionOptions['createTimeoutError'];
+  writeTimeoutMs?: number;
+}
+
+export type ProtocolV2LinkManagerOptions<Key> = {
+  getSchemas: () => ProtocolV2Schemas;
+  classifyError: (error: unknown) => ProtocolV2LinkErrorClassification;
+  onLinkInvalidated?: (key: Key, reason: string) => Promise<void> | void;
+};
+
+type ProtocolV2Link = {
+  adapter: ProtocolV2LinkAdapter;
+  session: ProtocolV2Session;
+  state: {
+    invalidatedReason?: string;
+  };
+};
+
+export class ProtocolV2LinkManager<Key> {
+  private readonly links = new Map<Key, ProtocolV2Link>();
+
+  private readonly sequences = new Map<Key, ProtocolV2SequenceCursor>();
+
+  private readonly callQueues = new Map<Key, Promise<unknown>>();
+
+  private readonly options: ProtocolV2LinkManagerOptions<Key>;
+
+  constructor(options: ProtocolV2LinkManagerOptions<Key>) {
+    this.options = options;
+  }
+
+  call(
+    key: Key,
+    createAdapter: () => ProtocolV2LinkAdapter,
+    name: string,
+    data: Record<string, unknown>,
+    options?: TransportCallOptions
+  ): Promise<MessageFromOneKey> {
+    const run = () => this.executeCall(key, createAdapter, name, data, options);
+    const previous = this.callQueues.get(key) ?? Promise.resolve();
+    const result = previous.then(run, run);
+    const queue = result.catch(() => undefined);
+    this.callQueues.set(key, queue);
+    result
+      .then(
+        () => this.clearSettledCallQueue(key, queue),
+        () => this.clearSettledCallQueue(key, queue)
+      )
+      .catch(() => undefined);
+    return result;
+  }
+
+  async invalidateLink(key: Key, reason: string): Promise<void> {
+    const link = this.links.get(key);
+    if (!link) return;
+
+    this.links.delete(key);
+    link.state.invalidatedReason = reason;
+    await link.adapter.reset(reason);
+    await this.options.onLinkInvalidated?.(key, reason);
+  }
+
+  async invalidateAllLinks(reason: string): Promise<void> {
+    await Promise.all(Array.from(this.links.keys(), key => this.invalidateLink(key, reason)));
+  }
+
+  async dispose(reason: string): Promise<void> {
+    await this.invalidateAllLinks(reason);
+    this.sequences.clear();
+    this.callQueues.clear();
+  }
+
+  private getOrCreateLink(key: Key, createAdapter: () => ProtocolV2LinkAdapter): ProtocolV2Link {
+    const existing = this.links.get(key);
+    if (existing) return existing;
+
+    const adapter = createAdapter();
+    const state: ProtocolV2Link['state'] = {};
+    const assertLinkActive = () => {
+      if (state.invalidatedReason) {
+        throw new Error(state.invalidatedReason);
+      }
+    };
+    let sequenceCursor = this.sequences.get(key);
+    if (!sequenceCursor) {
+      sequenceCursor = new ProtocolV2SequenceCursor();
+      this.sequences.set(key, sequenceCursor);
+    }
+    const session = new ProtocolV2Session({
+      schemas: this.options.getSchemas(),
+      router: adapter.router,
+      maxFrameBytes: adapter.maxFrameBytes,
+      generation: adapter.generation,
+      sequenceCursor,
+      prepareCall: async context => {
+        assertLinkActive();
+        await adapter.prepareCall(context);
+        assertLinkActive();
+      },
+      writeFrame: async (frame, context) => {
+        assertLinkActive();
+        await adapter.writeFrame(frame, context);
+        assertLinkActive();
+      },
+      readFrame: async context => {
+        assertLinkActive();
+        const frame = await adapter.readFrame(context);
+        assertLinkActive();
+        return frame;
+      },
+      logger: adapter.logger,
+      logPrefix: adapter.logPrefix,
+      createTimeoutError: adapter.createTimeoutError,
+      writeTimeoutMs: adapter.writeTimeoutMs,
+    });
+    const link = { adapter, session, state };
+    this.links.set(key, link);
+    return link;
+  }
+
+  private async executeCall(
+    key: Key,
+    createAdapter: () => ProtocolV2LinkAdapter,
+    name: string,
+    data: Record<string, unknown>,
+    options?: TransportCallOptions
+  ): Promise<MessageFromOneKey> {
+    try {
+      return await this.getOrCreateLink(key, createAdapter).session.call(name, data, options);
+    } catch (error) {
+      if (this.options.classifyError(error) === 'link-fatal') {
+        const errorMessage = getErrorMessage(error) || 'unknown error';
+        await this.invalidateLink(key, `Protocol V2 link-fatal error: ${errorMessage}`);
+      }
+      throw error;
+    }
+  }
+
+  private clearSettledCallQueue(key: Key, queue: Promise<unknown>) {
+    if (this.callQueues.get(key) === queue) {
+      this.callQueues.delete(key);
+    }
+  }
+}

package/src/protocols/v2/sequence-cursor.ts

@@ -0,0 +1,10 @@
+import { nextProtoSeq } from './encode';
+
+export class ProtocolV2SequenceCursor {
+  private current = 0;
+
+  next(): number {
+    this.current = nextProtoSeq(this.current);
+    return this.current;
+  }
+}