@qubic.ts/core 0.1.0

package/src/protocol/assets.ts

@@ -0,0 +1,276 @@
+import { readI64LE, readU64LE, writeU64LE } from "../primitives/number64.js";
+import { NetworkMessageType } from "./message-types.js";
+import { encodeRequestPacket } from "./request-packet.js";
+
+export const ASSETS_DEPTH = 24;
+export const ASSET_RECORD_SIZE = 48;
+export const RESPOND_ASSETS_PAYLOAD_SIZE = 56;
+export const RESPOND_ASSETS_WITH_SIBLINGS_PAYLOAD_SIZE = 824;
+
+export const AssetRecordType = {
+  EMPTY: 0,
+  ISSUANCE: 1,
+  OWNERSHIP: 2,
+  POSSESSION: 3,
+} as const;
+
+export type IssuanceAssetRecord = Readonly<{
+  type: typeof AssetRecordType.ISSUANCE;
+  publicKey32: Uint8Array;
+  name7: Uint8Array;
+  numberOfDecimalPlaces: number; // int8-ish
+  unitOfMeasurement7: Uint8Array;
+}>;
+
+export type OwnershipAssetRecord = Readonly<{
+  type: typeof AssetRecordType.OWNERSHIP;
+  publicKey32: Uint8Array;
+  managingContractIndex: number; // uint16
+  issuanceIndex: number; // uint32
+  numberOfShares: bigint; // int64
+}>;
+
+export type PossessionAssetRecord = Readonly<{
+  type: typeof AssetRecordType.POSSESSION;
+  publicKey32: Uint8Array;
+  managingContractIndex: number; // uint16
+  ownershipIndex: number; // uint32
+  numberOfShares: bigint; // int64
+}>;
+
+export type AssetRecord =
+  | IssuanceAssetRecord
+  | OwnershipAssetRecord
+  | PossessionAssetRecord
+  | Readonly<{ type: typeof AssetRecordType.EMPTY; publicKey32: Uint8Array }>;
+
+export type RespondAssets = Readonly<{
+  asset: AssetRecord;
+  tick: number; // uint32
+  universeIndex: number; // uint32
+}>;
+
+export type RespondAssetsWithSiblings = Readonly<
+  RespondAssets & { siblings: ReadonlyArray<Uint8Array> }
+>;
+
+function assertUint8ArrayLength(bytes: Uint8Array, length: number, name: string) {
+  if (!(bytes instanceof Uint8Array)) {
+    throw new TypeError(`${name} must be a Uint8Array`);
+  }
+  if (bytes.byteLength !== length) {
+    throw new RangeError(`${name} must be ${length} bytes`);
+  }
+}
+
+function assertU32(value: number, name: string) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > 0xffffffff) {
+    throw new RangeError(`${name} must be a uint32`);
+  }
+}
+
+function assertU16(value: number, name: string) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > 0xffff) {
+    throw new RangeError(`${name} must be a uint16`);
+  }
+}
+
+export const RequestAssetsType = {
+  ISSUANCE: 0,
+  OWNERSHIP: 1,
+  POSSESSION: 2,
+  BY_UNIVERSE_INDEX: 3,
+} as const;
+
+export const RequestAssetsFlag = {
+  GET_SIBLINGS: 0b1,
+  ANY_ISSUER: 0b10,
+  ANY_ASSET_NAME: 0b100,
+  ANY_OWNER: 0b1000,
+  ANY_OWNERSHIP_MANAGING_CONTRACT: 0b10000,
+  ANY_POSSESSOR: 0b100000,
+  ANY_POSSESSION_MANAGING_CONTRACT: 0b1000000,
+} as const;
+
+export type RequestAssetsByFilterParams = Readonly<{
+  requestType:
+    | typeof RequestAssetsType.ISSUANCE
+    | typeof RequestAssetsType.OWNERSHIP
+    | typeof RequestAssetsType.POSSESSION;
+  getSiblings?: boolean;
+
+  issuerPublicKey32?: Uint8Array;
+  assetNameU64LE?: bigint;
+  ownerPublicKey32?: Uint8Array;
+  possessorPublicKey32?: Uint8Array;
+  ownershipManagingContractIndex?: number;
+  possessionManagingContractIndex?: number;
+}>;
+
+export type RequestAssetsByUniverseIndexParams = Readonly<{
+  universeIndex: number; // uint32
+  getSiblings?: boolean;
+}>;
+
+export function assetNameToU64LE(name: string): bigint {
+  if (typeof name !== "string") {
+    throw new TypeError("name must be a string");
+  }
+  if (name.length > 8) {
+    throw new RangeError("name must be <= 8 characters");
+  }
+  const bytes = new Uint8Array(8);
+  for (let i = 0; i < name.length; i++) {
+    const c = name.charCodeAt(i);
+    if (c < 32 || c > 126) throw new Error("name must be ASCII");
+    bytes[i] = c;
+  }
+  return readU64LE(bytes, 0);
+}
+
+export function encodeRequestAssetsByUniverseIndex(
+  params: RequestAssetsByUniverseIndexParams,
+): Uint8Array {
+  assertU32(params.universeIndex, "universeIndex");
+
+  const flags = params.getSiblings ? RequestAssetsFlag.GET_SIBLINGS : 0;
+  const payload = new Uint8Array(112);
+  const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+  view.setUint16(0, RequestAssetsType.BY_UNIVERSE_INDEX, true);
+  view.setUint16(2, flags, true);
+  view.setUint32(4, params.universeIndex, true);
+  return encodeRequestPacket(NetworkMessageType.REQUEST_ASSETS, payload);
+}
+
+export function encodeRequestAssetsByFilter(params: RequestAssetsByFilterParams): Uint8Array {
+  const requestType = params.requestType;
+  if (
+    requestType !== RequestAssetsType.ISSUANCE &&
+    requestType !== RequestAssetsType.OWNERSHIP &&
+    requestType !== RequestAssetsType.POSSESSION
+  ) {
+    throw new RangeError("requestType is invalid");
+  }
+
+  let flags = params.getSiblings ? RequestAssetsFlag.GET_SIBLINGS : 0;
+
+  const ownershipManagingContractIndex = params.ownershipManagingContractIndex ?? 0;
+  const possessionManagingContractIndex = params.possessionManagingContractIndex ?? 0;
+  assertU16(ownershipManagingContractIndex, "ownershipManagingContractIndex");
+  assertU16(possessionManagingContractIndex, "possessionManagingContractIndex");
+
+  const issuerPublicKey32 = params.issuerPublicKey32 ?? new Uint8Array(32);
+  const ownerPublicKey32 = params.ownerPublicKey32 ?? new Uint8Array(32);
+  const possessorPublicKey32 = params.possessorPublicKey32 ?? new Uint8Array(32);
+
+  if (params.issuerPublicKey32 === undefined) flags |= RequestAssetsFlag.ANY_ISSUER;
+  if (params.assetNameU64LE === undefined) flags |= RequestAssetsFlag.ANY_ASSET_NAME;
+  if (requestType === RequestAssetsType.OWNERSHIP && params.ownerPublicKey32 === undefined)
+    flags |= RequestAssetsFlag.ANY_OWNER;
+  if (
+    requestType === RequestAssetsType.OWNERSHIP &&
+    params.ownershipManagingContractIndex === undefined
+  )
+    flags |= RequestAssetsFlag.ANY_OWNERSHIP_MANAGING_CONTRACT;
+  if (requestType === RequestAssetsType.POSSESSION && params.possessorPublicKey32 === undefined)
+    flags |= RequestAssetsFlag.ANY_POSSESSOR;
+  if (
+    requestType === RequestAssetsType.POSSESSION &&
+    params.possessionManagingContractIndex === undefined
+  )
+    flags |= RequestAssetsFlag.ANY_POSSESSION_MANAGING_CONTRACT;
+
+  assertUint8ArrayLength(issuerPublicKey32, 32, "issuerPublicKey32");
+  assertUint8ArrayLength(ownerPublicKey32, 32, "ownerPublicKey32");
+  assertUint8ArrayLength(possessorPublicKey32, 32, "possessorPublicKey32");
+
+  const assetNameU64LE = params.assetNameU64LE ?? 0n;
+  if (assetNameU64LE < 0n || assetNameU64LE > 0xffff_ffff_ffff_ffffn) {
+    throw new RangeError("assetNameU64LE must fit in uint64");
+  }
+
+  const payload = new Uint8Array(112);
+  const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+  view.setUint16(0, requestType, true);
+  view.setUint16(2, flags, true);
+  view.setUint16(4, ownershipManagingContractIndex, true);
+  view.setUint16(6, possessionManagingContractIndex, true);
+  payload.set(issuerPublicKey32, 8);
+  writeU64LE(assetNameU64LE, payload, 40);
+  payload.set(ownerPublicKey32, 48);
+  payload.set(possessorPublicKey32, 80);
+
+  return encodeRequestPacket(NetworkMessageType.REQUEST_ASSETS, payload);
+}
+
+export function decodeAssetRecord(recordBytes48: Uint8Array): AssetRecord {
+  assertUint8ArrayLength(recordBytes48, ASSET_RECORD_SIZE, "recordBytes48");
+  const type = recordBytes48[32] ?? 0;
+  const view = new DataView(
+    recordBytes48.buffer,
+    recordBytes48.byteOffset,
+    recordBytes48.byteLength,
+  );
+
+  if (type === AssetRecordType.ISSUANCE) {
+    return {
+      type: AssetRecordType.ISSUANCE,
+      publicKey32: recordBytes48.slice(0, 32),
+      name7: recordBytes48.slice(33, 40),
+      numberOfDecimalPlaces: ((recordBytes48[40] ?? 0) << 24) >> 24,
+      unitOfMeasurement7: recordBytes48.slice(41, 48),
+    };
+  }
+
+  if (type === AssetRecordType.OWNERSHIP) {
+    return {
+      type: AssetRecordType.OWNERSHIP,
+      publicKey32: recordBytes48.slice(0, 32),
+      managingContractIndex: view.getUint16(34, true),
+      issuanceIndex: view.getUint32(36, true),
+      numberOfShares: readI64LE(recordBytes48, 40),
+    };
+  }
+
+  if (type === AssetRecordType.POSSESSION) {
+    return {
+      type: AssetRecordType.POSSESSION,
+      publicKey32: recordBytes48.slice(0, 32),
+      managingContractIndex: view.getUint16(34, true),
+      ownershipIndex: view.getUint32(36, true),
+      numberOfShares: readI64LE(recordBytes48, 40),
+    };
+  }
+
+  return { type: AssetRecordType.EMPTY, publicKey32: recordBytes48.slice(0, 32) };
+}
+
+export function decodeRespondAssets(payload: Uint8Array): RespondAssets {
+  if (!(payload instanceof Uint8Array)) throw new TypeError("payload must be a Uint8Array");
+  if (payload.byteLength !== RESPOND_ASSETS_PAYLOAD_SIZE) {
+    throw new RangeError(`payload must be ${RESPOND_ASSETS_PAYLOAD_SIZE} bytes`);
+  }
+
+  const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+  const asset = decodeAssetRecord(payload.subarray(0, ASSET_RECORD_SIZE));
+  const tick = view.getUint32(48, true);
+  const universeIndex = view.getUint32(52, true);
+
+  return { asset, tick, universeIndex };
+}
+
+export function decodeRespondAssetsWithSiblings(payload: Uint8Array): RespondAssetsWithSiblings {
+  if (!(payload instanceof Uint8Array)) throw new TypeError("payload must be a Uint8Array");
+  if (payload.byteLength !== RESPOND_ASSETS_WITH_SIBLINGS_PAYLOAD_SIZE) {
+    throw new RangeError(`payload must be ${RESPOND_ASSETS_WITH_SIBLINGS_PAYLOAD_SIZE} bytes`);
+  }
+
+  const base = decodeRespondAssets(payload.subarray(0, RESPOND_ASSETS_PAYLOAD_SIZE));
+  const siblings: Uint8Array[] = [];
+  const siblingsOffset = RESPOND_ASSETS_PAYLOAD_SIZE;
+  for (let i = 0; i < ASSETS_DEPTH; i++) {
+    const start = siblingsOffset + i * 32;
+    siblings.push(payload.slice(start, start + 32));
+  }
+  return { ...base, siblings };
+}

package/src/protocol/broadcast-transaction.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "bun:test";
+import { privateKeyFromSeed } from "../crypto/seed.js";
+import { publicKeyFromIdentity } from "../primitives/identity.js";
+import { buildSignedTransaction } from "../transactions/transaction.js";
+import { encodeBroadcastTransactionPacket } from "./broadcast-transaction.js";
+import { NetworkMessageType } from "./message-types.js";
+import { decodeRequestResponseHeader } from "./request-response-header.js";
+
+describe("broadcast-transaction", () => {
+  it("encodes a BROADCAST_TRANSACTION packet with dejavu=0", async () => {
+    const seed = "jvhbyzjinlyutyuhsweuxiwootqoevjqwqmdhjeohrytxjxidpbcfyg";
+    const secretKey32 = await privateKeyFromSeed(seed);
+
+    const sourcePublicKey32 = publicKeyFromIdentity(
+      "HZEBBDSKZRTAWGYMTTSDZQDXYWPBUKBEAIYZNFLVWARZJBEBIJRRFKUDVETA",
+    );
+    const destinationPublicKey32 = publicKeyFromIdentity(
+      "AFZPUAIYVPNUYGJRQVLUKOPPVLHAZQTGLYAAUUNBXFTVTAMSBKQBLEIEPCVJ",
+    );
+
+    const txBytes = await buildSignedTransaction(
+      { sourcePublicKey32, destinationPublicKey32, amount: 1n, tick: 12345 },
+      secretKey32,
+    );
+
+    const packet = encodeBroadcastTransactionPacket(txBytes);
+    const header = decodeRequestResponseHeader(packet.subarray(0, 8));
+
+    expect(header.size).toBe(8 + txBytes.byteLength);
+    expect(header.type).toBe(NetworkMessageType.BROADCAST_TRANSACTION);
+    expect(header.dejavu).toBe(0);
+    expect(packet.subarray(8)).toEqual(txBytes);
+  });
+});

package/src/protocol/broadcast-transaction.ts

@@ -0,0 +1,17 @@
+import { MAX_TRANSACTION_SIZE, TRANSACTION_HEADER_SIZE } from "../transactions/transaction.js";
+import { NetworkMessageType } from "./message-types.js";
+import { encodeRequestPacket } from "./request-packet.js";
+
+export function encodeBroadcastTransactionPacket(txBytes: Uint8Array): Uint8Array {
+  if (!(txBytes instanceof Uint8Array)) {
+    throw new TypeError("txBytes must be a Uint8Array");
+  }
+  if (txBytes.byteLength < TRANSACTION_HEADER_SIZE) {
+    throw new RangeError("txBytes is too short");
+  }
+  if (txBytes.byteLength > MAX_TRANSACTION_SIZE) {
+    throw new RangeError(`txBytes must be <= ${MAX_TRANSACTION_SIZE} bytes`);
+  }
+
+  return encodeRequestPacket(NetworkMessageType.BROADCAST_TRANSACTION, txBytes, { dejavu: 0 });
+}

package/src/protocol/contract-function.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "bun:test";
+import {
+  decodeRespondContractFunction,
+  encodeRequestContractFunction,
+  REQUEST_CONTRACT_FUNCTION_PREFIX_SIZE,
+} from "./contract-function.js";
+import { NetworkMessageType } from "./message-types.js";
+import { decodeRequestResponseHeader } from "./request-response-header.js";
+
+describe("contract-function", () => {
+  it("encodes request contract function packet", () => {
+    const packet = encodeRequestContractFunction({
+      contractIndex: 123,
+      inputType: 42,
+      inputBytes: Uint8Array.from([1, 2, 3]),
+    });
+
+    const header = decodeRequestResponseHeader(packet.subarray(0, 8));
+    expect(header.type).toBe(NetworkMessageType.REQUEST_CONTRACT_FUNCTION);
+    expect(header.size).toBe(8 + REQUEST_CONTRACT_FUNCTION_PREFIX_SIZE + 3);
+    expect(header.dejavu).not.toBe(0);
+
+    const payload = packet.subarray(8);
+    const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+    expect(view.getUint32(0, true)).toBe(123);
+    expect(view.getUint16(4, true)).toBe(42);
+    expect(view.getUint16(6, true)).toBe(3);
+    expect(payload.subarray(REQUEST_CONTRACT_FUNCTION_PREFIX_SIZE)).toEqual(
+      Uint8Array.from([1, 2, 3]),
+    );
+  });
+
+  it("decodes contract function response payload as raw bytes", () => {
+    const payload = Uint8Array.from([9, 8, 7]);
+    expect(decodeRespondContractFunction(payload)).toEqual(payload);
+  });
+});

package/src/protocol/contract-function.ts

@@ -0,0 +1,53 @@
+import { NetworkMessageType } from "./message-types.js";
+import { encodeRequestPacket } from "./request-packet.js";
+
+export const REQUEST_CONTRACT_FUNCTION_PREFIX_SIZE = 8; // u32 + u16 + u16
+
+export type RequestContractFunctionParams = Readonly<{
+  contractIndex: number; // uint32
+  inputType: number; // uint16
+  inputBytes: Uint8Array;
+}>;
+
+function assertU32(value: number, name: string) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > 0xffffffff) {
+    throw new RangeError(`${name} must be a uint32`);
+  }
+}
+
+function assertU16(value: number, name: string) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > 0xffff) {
+    throw new RangeError(`${name} must be a uint16`);
+  }
+}
+
+export function encodeRequestContractFunction(params: RequestContractFunctionParams): Uint8Array {
+  assertU32(params.contractIndex, "contractIndex");
+  assertU16(params.inputType, "inputType");
+
+  if (!(params.inputBytes instanceof Uint8Array)) {
+    throw new TypeError("inputBytes must be a Uint8Array");
+  }
+  if (params.inputBytes.byteLength > 0xffff) {
+    throw new RangeError("inputBytes must be <= 65535 bytes");
+  }
+
+  const payload = new Uint8Array(
+    REQUEST_CONTRACT_FUNCTION_PREFIX_SIZE + params.inputBytes.byteLength,
+  );
+  const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+  view.setUint32(0, params.contractIndex, true);
+  view.setUint16(4, params.inputType, true);
+  view.setUint16(6, params.inputBytes.byteLength, true);
+  payload.set(params.inputBytes, REQUEST_CONTRACT_FUNCTION_PREFIX_SIZE);
+
+  return encodeRequestPacket(NetworkMessageType.REQUEST_CONTRACT_FUNCTION, payload);
+}
+
+export function decodeRespondContractFunction(payload: Uint8Array): Uint8Array {
+  if (!(payload instanceof Uint8Array)) {
+    throw new TypeError("payload must be a Uint8Array");
+  }
+  // Contract response is variable length; empty payload indicates failure.
+  return payload.slice();
+}

package/src/protocol/entity.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "bun:test";
+import {
+  decodeRespondEntity,
+  encodeRequestEntity,
+  RESPOND_ENTITY_PAYLOAD_SIZE,
+  SPECTRUM_DEPTH,
+} from "./entity.js";
+import { NetworkMessageType } from "./message-types.js";
+import { decodeRequestResponseHeader } from "./request-response-header.js";
+
+describe("entity", () => {
+  it("encodes request entity packet", () => {
+    const pub = new Uint8Array(32).fill(7);
+    const packet = encodeRequestEntity(pub);
+    expect(packet.byteLength).toBe(8 + 32);
+    const header = decodeRequestResponseHeader(packet.subarray(0, 8));
+    expect(header.size).toBe(40);
+    expect(header.type).toBe(NetworkMessageType.REQUEST_ENTITY);
+    expect(packet.subarray(8)).toEqual(pub);
+  });
+
+  it("decodes respond entity payload", () => {
+    const payload = new Uint8Array(RESPOND_ENTITY_PAYLOAD_SIZE);
+    payload.set(
+      new Uint8Array(32).map((_, i) => i),
+      0,
+    );
+
+    const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+    view.setBigInt64(32, 100n, true);
+    view.setBigInt64(40, 25n, true);
+    view.setUint32(48, 3, true);
+    view.setUint32(52, 4, true);
+    view.setUint32(56, 111, true);
+    view.setUint32(60, 222, true);
+    view.setUint32(64, 333, true);
+    view.setInt32(68, -1, true);
+
+    const siblingsOffset = 72;
+    for (let i = 0; i < SPECTRUM_DEPTH; i++) {
+      const sib = new Uint8Array(32).fill(i);
+      payload.set(sib, siblingsOffset + i * 32);
+    }
+
+    const decoded = decodeRespondEntity(payload);
+    expect(decoded.tick).toBe(333);
+    expect(decoded.spectrumIndex).toBe(-1);
+    expect(decoded.entity.incomingAmount).toBe(100n);
+    expect(decoded.entity.outgoingAmount).toBe(25n);
+    expect(decoded.entity.numberOfIncomingTransfers).toBe(3);
+    expect(decoded.entity.numberOfOutgoingTransfers).toBe(4);
+    expect(decoded.entity.latestIncomingTransferTick).toBe(111);
+    expect(decoded.entity.latestOutgoingTransferTick).toBe(222);
+    expect(decoded.siblings).toHaveLength(SPECTRUM_DEPTH);
+    expect(decoded.siblings[0]).toEqual(new Uint8Array(32).fill(0));
+    expect(decoded.siblings[23]).toEqual(new Uint8Array(32).fill(23));
+  });
+});

package/src/protocol/entity.ts

@@ -0,0 +1,82 @@
+import { readI64LE } from "../primitives/number64.js";
+import { NetworkMessageType } from "./message-types.js";
+import { encodeRequestPacket } from "./request-packet.js";
+
+export const SPECTRUM_DEPTH = 24;
+export const ENTITY_RECORD_SIZE = 64;
+export const RESPOND_ENTITY_PAYLOAD_SIZE = ENTITY_RECORD_SIZE + 4 + 4 + 32 * SPECTRUM_DEPTH; // 840
+
+export type EntityRecord = Readonly<{
+  publicKey32: Uint8Array;
+  incomingAmount: bigint; // int64
+  outgoingAmount: bigint; // int64
+  numberOfIncomingTransfers: number; // uint32
+  numberOfOutgoingTransfers: number; // uint32
+  latestIncomingTransferTick: number; // uint32
+  latestOutgoingTransferTick: number; // uint32
+}>;
+
+export type RespondEntity = Readonly<{
+  entity: EntityRecord;
+  tick: number; // uint32
+  spectrumIndex: number; // int32
+  siblings: ReadonlyArray<Uint8Array>; // [SPECTRUM_DEPTH][32]
+}>;
+
+function assertUint8ArrayLength(bytes: Uint8Array, length: number, name: string) {
+  if (!(bytes instanceof Uint8Array)) {
+    throw new TypeError(`${name} must be a Uint8Array`);
+  }
+  if (bytes.byteLength !== length) {
+    throw new RangeError(`${name} must be ${length} bytes`);
+  }
+}
+
+export function encodeRequestEntity(publicKey32: Uint8Array): Uint8Array {
+  assertUint8ArrayLength(publicKey32, 32, "publicKey32");
+  return encodeRequestPacket(NetworkMessageType.REQUEST_ENTITY, publicKey32);
+}
+
+export function decodeRespondEntity(payload: Uint8Array): RespondEntity {
+  if (!(payload instanceof Uint8Array)) {
+    throw new TypeError("payload must be a Uint8Array");
+  }
+  if (payload.byteLength !== RESPOND_ENTITY_PAYLOAD_SIZE) {
+    throw new RangeError(`payload must be ${RESPOND_ENTITY_PAYLOAD_SIZE} bytes`);
+  }
+
+  const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+
+  const publicKey32 = payload.subarray(0, 32);
+  const incomingAmount = readI64LE(payload, 32);
+  const outgoingAmount = readI64LE(payload, 40);
+  const numberOfIncomingTransfers = view.getUint32(48, true);
+  const numberOfOutgoingTransfers = view.getUint32(52, true);
+  const latestIncomingTransferTick = view.getUint32(56, true);
+  const latestOutgoingTransferTick = view.getUint32(60, true);
+
+  const tick = view.getUint32(64, true);
+  const spectrumIndex = view.getInt32(68, true);
+
+  const siblingsOffset = 72;
+  const siblings: Uint8Array[] = [];
+  for (let i = 0; i < SPECTRUM_DEPTH; i++) {
+    const start = siblingsOffset + i * 32;
+    siblings.push(payload.slice(start, start + 32));
+  }
+
+  return {
+    entity: {
+      publicKey32: publicKey32.slice(),
+      incomingAmount,
+      outgoingAmount,
+      numberOfIncomingTransfers,
+      numberOfOutgoingTransfers,
+      latestIncomingTransferTick,
+      latestOutgoingTransferTick,
+    },
+    tick,
+    spectrumIndex,
+    siblings,
+  };
+}

package/src/protocol/message-types.ts

@@ -0,0 +1,16 @@
+export const NetworkMessageType = {
+  BROADCAST_FUTURE_TICK_DATA: 8,
+  REQUEST_TICK_DATA: 16,
+  REQUEST_CONTRACT_FUNCTION: 42,
+  RESPOND_CONTRACT_FUNCTION: 43,
+  REQUEST_CURRENT_TICK_INFO: 27,
+  RESPOND_CURRENT_TICK_INFO: 28,
+  REQUEST_ENTITY: 31,
+  RESPOND_ENTITY: 32,
+  END_RESPONSE: 35,
+  BROADCAST_TRANSACTION: 24,
+  REQUEST_SYSTEM_INFO: 46,
+  RESPOND_SYSTEM_INFO: 47,
+  REQUEST_ASSETS: 52,
+  RESPOND_ASSETS: 53,
+} as const;

package/src/protocol/packet-framer.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "bun:test";
+import { createPacketFramer } from "./packet-framer.js";
+import { encodeRequestResponseHeader } from "./request-response-header.js";
+
+function makePacket(type: number, dejavu: number, payload: Uint8Array): Uint8Array {
+  const header = encodeRequestResponseHeader({
+    size: 8 + payload.byteLength,
+    type,
+    dejavu,
+  });
+  const out = new Uint8Array(header.byteLength + payload.byteLength);
+  out.set(header, 0);
+  out.set(payload, 8);
+  return out;
+}
+
+describe("createPacketFramer", () => {
+  it("yields nothing with insufficient header bytes", () => {
+    const framer = createPacketFramer();
+    framer.push(Uint8Array.from([1, 2, 3]));
+    expect(framer.read()).toEqual([]);
+  });
+
+  it("parses a complete packet from a single chunk", () => {
+    const framer = createPacketFramer();
+    const payload = Uint8Array.from([9, 8, 7]);
+    framer.push(makePacket(24, 0, payload));
+
+    const packets = framer.read();
+    expect(packets.length).toBe(1);
+    const packet0 = packets[0];
+    if (!packet0) throw new Error("Expected first packet");
+    expect(packet0.header).toEqual({ size: 11, type: 24, dejavu: 0 });
+    expect([...packet0.payload]).toEqual([9, 8, 7]);
+    expect(framer.bufferedBytes()).toBe(0);
+  });
+
+  it("parses multiple packets from a single chunk", () => {
+    const framer = createPacketFramer();
+    const a = makePacket(27, 1, new Uint8Array(0));
+    const b = makePacket(28, 2, Uint8Array.from([1]));
+    const combined = new Uint8Array(a.length + b.length);
+    combined.set(a, 0);
+    combined.set(b, a.length);
+
+    framer.push(combined);
+
+    const packets = framer.read();
+    expect(packets.length).toBe(2);
+    const packet0 = packets[0];
+    const packet1 = packets[1];
+    if (!packet0 || !packet1) throw new Error("Expected two packets");
+    expect(packet0.header.type).toBe(27);
+    expect(packet0.payload.byteLength).toBe(0);
+    expect(packet1.header.type).toBe(28);
+    expect([...packet1.payload]).toEqual([1]);
+  });
+
+  it("handles header split across chunks", () => {
+    const framer = createPacketFramer();
+    const payload = Uint8Array.from([1, 2, 3, 4]);
+    const packet = makePacket(31, 123, payload);
+
+    framer.push(packet.subarray(0, 2));
+    expect(framer.read()).toEqual([]);
+
+    framer.push(packet.subarray(2, 8));
+    expect(framer.read()).toEqual([]);
+
+    framer.push(packet.subarray(8));
+    const packets = framer.read();
+    expect(packets.length).toBe(1);
+    const packet0 = packets[0];
+    if (!packet0) throw new Error("Expected first packet");
+    expect(packet0.header).toEqual({ size: 12, type: 31, dejavu: 123 });
+    expect([...packet0.payload]).toEqual([1, 2, 3, 4]);
+  });
+
+  it("handles payload split across chunks", () => {
+    const framer = createPacketFramer();
+    const payload = Uint8Array.from([5, 6, 7, 8, 9]);
+    const packet = makePacket(16, 999, payload);
+
+    framer.push(packet.subarray(0, 10));
+    expect(framer.read()).toEqual([]);
+
+    framer.push(packet.subarray(10));
+    const packets = framer.read();
+    expect(packets.length).toBe(1);
+    const packet0 = packets[0];
+    if (!packet0) throw new Error("Expected first packet");
+    expect([...packet0.payload]).toEqual([5, 6, 7, 8, 9]);
+  });
+
+  it("throws on invalid packet size (<8)", () => {
+    const framer = createPacketFramer();
+    const badHeader = encodeRequestResponseHeader({ size: 1, type: 1, dejavu: 0 });
+    framer.push(badHeader);
+    expect(() => framer.read()).toThrow();
+  });
+});