@qubic.ts/core 0.1.0

package/src/protocol/tick-data.ts

@@ -0,0 +1,127 @@
+import { readI64LE } from "../primitives/number64.js";
+import { NetworkMessageType } from "./message-types.js";
+import { encodeRequestPacket } from "./request-packet.js";
+
+export const NUMBER_OF_TRANSACTIONS_PER_TICK = 1024;
+export const MAX_NUMBER_OF_CONTRACTS = 1024;
+export const SIGNATURE_LENGTH = 64;
+
+export const TICK_DATA_PAYLOAD_SIZE =
+  16 + // fixed header fields
+  32 + // timelock
+  NUMBER_OF_TRANSACTIONS_PER_TICK * 32 +
+  MAX_NUMBER_OF_CONTRACTS * 8 +
+  SIGNATURE_LENGTH;
+
+export type TickDataView = Readonly<{
+  computorIndex: number; // uint16
+  epoch: number; // uint16
+  tick: number; // uint32
+
+  millisecond: number; // uint16
+  second: number; // uint8
+  minute: number; // uint8
+  hour: number; // uint8
+  day: number; // uint8
+  month: number; // uint8
+  year: number; // uint8
+
+  timelock32: Uint8Array;
+  signature64: Uint8Array;
+
+  getTransactionDigest(index: number): Uint8Array;
+  getContractFee(index: number): bigint;
+}>;
+
+function assertU32(value: number, name: string) {
+  if (!Number.isSafeInteger(value) || value < 0 || value > 0xffffffff) {
+    throw new RangeError(`${name} must be a uint32`);
+  }
+}
+
+export function encodeRequestTickData(tick: number): Uint8Array {
+  assertU32(tick, "tick");
+  const payload = new Uint8Array(4);
+  new DataView(payload.buffer).setUint32(0, tick, true);
+  return encodeRequestPacket(NetworkMessageType.REQUEST_TICK_DATA, payload);
+}
+
+export function decodeBroadcastFutureTickData(payload: Uint8Array): TickDataView {
+  if (!(payload instanceof Uint8Array)) {
+    throw new TypeError("payload must be a Uint8Array");
+  }
+  if (payload.byteLength !== TICK_DATA_PAYLOAD_SIZE) {
+    throw new RangeError(`payload must be ${TICK_DATA_PAYLOAD_SIZE} bytes`);
+  }
+
+  const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+
+  const computorIndex = view.getUint16(0, true);
+  const epoch = view.getUint16(2, true);
+  const tick = view.getUint32(4, true);
+
+  const millisecond = view.getUint16(8, true);
+  const second = view.getUint8(10);
+  const minute = view.getUint8(11);
+  const hour = view.getUint8(12);
+  const day = view.getUint8(13);
+  const month = view.getUint8(14);
+  const year = view.getUint8(15);
+
+  const timelockOffset = 16;
+  const transactionDigestsOffset = timelockOffset + 32;
+  const contractFeesOffset = transactionDigestsOffset + NUMBER_OF_TRANSACTIONS_PER_TICK * 32;
+  const signatureOffset = contractFeesOffset + MAX_NUMBER_OF_CONTRACTS * 8;
+
+  const timelock32 = payload.slice(timelockOffset, timelockOffset + 32);
+  const signature64 = payload.slice(signatureOffset, signatureOffset + SIGNATURE_LENGTH);
+
+  const getTransactionDigest = (index: number): Uint8Array => {
+    if (!Number.isSafeInteger(index) || index < 0 || index >= NUMBER_OF_TRANSACTIONS_PER_TICK) {
+      throw new RangeError("index out of range");
+    }
+    const start = transactionDigestsOffset + index * 32;
+    return payload.subarray(start, start + 32);
+  };
+
+  const getContractFee = (index: number): bigint => {
+    if (!Number.isSafeInteger(index) || index < 0 || index >= MAX_NUMBER_OF_CONTRACTS) {
+      throw new RangeError("index out of range");
+    }
+    const start = contractFeesOffset + index * 8;
+    return readI64LE(payload, start);
+  };
+
+  return {
+    computorIndex,
+    epoch,
+    tick,
+    millisecond,
+    second,
+    minute,
+    hour,
+    day,
+    month,
+    year,
+    timelock32,
+    signature64,
+    getTransactionDigest,
+    getContractFee,
+  };
+}
+
+export function countNonZeroTransactionDigests(tickData: TickDataView): number {
+  let count = 0;
+  for (let i = 0; i < NUMBER_OF_TRANSACTIONS_PER_TICK; i++) {
+    const d = tickData.getTransactionDigest(i);
+    let nonZero = false;
+    for (let j = 0; j < d.byteLength; j++) {
+      if ((d[j] ?? 0) !== 0) {
+        nonZero = true;
+        break;
+      }
+    }
+    if (nonZero) count++;
+  }
+  return count;
+}

package/src/protocol/tick-info.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "bun:test";
+import { NetworkMessageType } from "./message-types.js";
+import { decodeRequestResponseHeader } from "./request-response-header.js";
+import { decodeRespondCurrentTickInfo, encodeRequestCurrentTickInfo } from "./tick-info.js";
+
+describe("tick-info", () => {
+  it("encodes request current tick info packet", () => {
+    const packet = encodeRequestCurrentTickInfo();
+    expect(packet.byteLength).toBe(8);
+    const header = decodeRequestResponseHeader(packet);
+    expect(header.size).toBe(8);
+    expect(header.type).toBe(NetworkMessageType.REQUEST_CURRENT_TICK_INFO);
+    expect(header.dejavu).not.toBe(0);
+  });
+
+  it("decodes respond current tick info payload", () => {
+    const payload = new Uint8Array(16);
+    const view = new DataView(payload.buffer);
+    view.setUint16(0, 3000, true);
+    view.setUint16(2, 42, true);
+    view.setUint32(4, 123_456, true);
+    view.setUint16(8, 10, true);
+    view.setUint16(10, 2, true);
+    view.setUint32(12, 1_000, true);
+
+    expect(decodeRespondCurrentTickInfo(payload)).toEqual({
+      tickDuration: 3000,
+      epoch: 42,
+      tick: 123_456,
+      numberOfAlignedVotes: 10,
+      numberOfMisalignedVotes: 2,
+      initialTick: 1_000,
+    });
+  });
+});

package/src/protocol/tick-info.ts

@@ -0,0 +1,34 @@
+import { NetworkMessageType } from "./message-types.js";
+import { encodeRequestPacket } from "./request-packet.js";
+
+export type CurrentTickInfo = Readonly<{
+  tickDuration: number; // uint16
+  epoch: number; // uint16
+  tick: number; // uint32
+  numberOfAlignedVotes: number; // uint16
+  numberOfMisalignedVotes: number; // uint16
+  initialTick: number; // uint32
+}>;
+
+export function encodeRequestCurrentTickInfo(): Uint8Array {
+  return encodeRequestPacket(NetworkMessageType.REQUEST_CURRENT_TICK_INFO);
+}
+
+export function decodeRespondCurrentTickInfo(payload: Uint8Array): CurrentTickInfo {
+  if (!(payload instanceof Uint8Array)) {
+    throw new TypeError("payload must be a Uint8Array");
+  }
+  if (payload.byteLength !== 16) {
+    throw new RangeError("payload must be 16 bytes");
+  }
+
+  const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+  return {
+    tickDuration: view.getUint16(0, true),
+    epoch: view.getUint16(2, true),
+    tick: view.getUint32(4, true),
+    numberOfAlignedVotes: view.getUint16(8, true),
+    numberOfMisalignedVotes: view.getUint16(10, true),
+    initialTick: view.getUint32(12, true),
+  };
+}

package/src/transactions/transaction.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "bun:test";
+import { verify } from "../crypto/schnorrq.js";
+import { privateKeyFromSeed } from "../crypto/seed.js";
+import { publicKeyFromIdentity } from "../primitives/identity.js";
+import {
+  buildSignedTransaction,
+  buildUnsignedTransaction,
+  SIGNATURE_LENGTH,
+  TRANSACTION_HEADER_SIZE,
+  transactionId,
+  unsignedTransactionDigest,
+} from "./transaction.js";
+
+describe("transaction", () => {
+  it("encodes the transaction header correctly", () => {
+    const sourcePublicKey32 = new Uint8Array(32).fill(1);
+    const destinationPublicKey32 = new Uint8Array(32).fill(2);
+    const amount = 123n;
+    const tick = 456;
+
+    const unsigned = buildUnsignedTransaction({
+      sourcePublicKey32,
+      destinationPublicKey32,
+      amount,
+      tick,
+      inputType: 0,
+      inputBytes: new Uint8Array(),
+    });
+
+    expect(unsigned.byteLength).toBe(TRANSACTION_HEADER_SIZE);
+    expect(unsigned.subarray(0, 32)).toEqual(sourcePublicKey32);
+    expect(unsigned.subarray(32, 64)).toEqual(destinationPublicKey32);
+
+    const view = new DataView(unsigned.buffer, unsigned.byteOffset, unsigned.byteLength);
+    expect(view.getBigInt64(64, true)).toBe(amount);
+    expect(view.getUint32(72, true)).toBe(tick);
+    expect(view.getUint16(76, true)).toBe(0);
+    expect(view.getUint16(78, true)).toBe(0);
+  });
+
+  it("signs and verifies a simple transfer transaction", async () => {
+    const seed = "jvhbyzjinlyutyuhsweuxiwootqoevjqwqmdhjeohrytxjxidpbcfyg";
+    const destId = "AFZPUAIYVPNUYGJRQVLUKOPPVLHAZQTGLYAAUUNBXFTVTAMSBKQBLEIEPCVJ";
+
+    const secretKey32 = await privateKeyFromSeed(seed);
+    const destinationPublicKey32 = publicKeyFromIdentity(destId);
+    const sourcePublicKey32 = publicKeyFromIdentity(
+      "HZEBBDSKZRTAWGYMTTSDZQDXYWPBUKBEAIYZNFLVWARZJBEBIJRRFKUDVETA",
+    );
+
+    const unsigned = buildUnsignedTransaction({
+      sourcePublicKey32,
+      destinationPublicKey32,
+      amount: 1n,
+      tick: 12345,
+    });
+
+    const digest32 = await unsignedTransactionDigest(unsigned);
+    expect(digest32.byteLength).toBe(32);
+
+    const signed = await buildSignedTransaction(
+      {
+        sourcePublicKey32,
+        destinationPublicKey32,
+        amount: 1n,
+        tick: 12345,
+      },
+      secretKey32,
+    );
+
+    expect(signed.byteLength).toBe(TRANSACTION_HEADER_SIZE + SIGNATURE_LENGTH);
+
+    const signature64 = signed.subarray(signed.byteLength - SIGNATURE_LENGTH);
+    expect(verify(sourcePublicKey32, digest32, signature64)).toBe(1);
+
+    const id = await transactionId(signed);
+    expect(id.length).toBe(60);
+  });
+});
+

package/src/transactions/transaction.ts

@@ -0,0 +1,150 @@
+import { k12 } from "../crypto/k12.js";
+import { sign } from "../crypto/schnorrq.js";
+import { identityFromPublicKey } from "../primitives/identity.js";
+import { MAX_I64, MIN_I64, writeI64LE } from "../primitives/number64.js";
+
+export const TRANSACTION_HEADER_SIZE = 80;
+export const SIGNATURE_LENGTH = 64;
+export const MAX_TRANSACTION_SIZE = 1024;
+export const MAX_INPUT_SIZE = MAX_TRANSACTION_SIZE - (TRANSACTION_HEADER_SIZE + SIGNATURE_LENGTH);
+
+export type BuildUnsignedTransactionParams = Readonly<{
+  sourcePublicKey32: Uint8Array;
+  destinationPublicKey32: Uint8Array;
+  amount: bigint | number;
+  tick: number;
+  inputType?: number;
+  inputBytes?: 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`);
+  }
+}
+
+function toI64(value: bigint | number, name: string): bigint {
+  const bigintValue = typeof value === "number" ? BigInt(value) : value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || !Number.isSafeInteger(value)) {
+      throw new RangeError(`${name} must be a safe integer`);
+    }
+  }
+  if (bigintValue < MIN_I64 || bigintValue > MAX_I64) {
+    throw new RangeError(`${name} must fit in int64`);
+  }
+  return bigintValue;
+}
+
+export function buildUnsignedTransaction(params: BuildUnsignedTransactionParams): Uint8Array {
+  const inputType = params.inputType ?? 0;
+  const inputBytes = params.inputBytes ?? new Uint8Array();
+
+  assertUint8ArrayLength(params.sourcePublicKey32, 32, "sourcePublicKey32");
+  assertUint8ArrayLength(params.destinationPublicKey32, 32, "destinationPublicKey32");
+  assertU16(inputType, "inputType");
+  assertU32(params.tick, "tick");
+
+  if (!(inputBytes instanceof Uint8Array)) {
+    throw new TypeError("inputBytes must be a Uint8Array");
+  }
+  if (inputBytes.byteLength > MAX_INPUT_SIZE) {
+    throw new RangeError(`inputBytes must be <= ${MAX_INPUT_SIZE} bytes`);
+  }
+
+  const inputSize = inputBytes.byteLength;
+  const out = new Uint8Array(TRANSACTION_HEADER_SIZE + inputSize);
+  out.set(params.sourcePublicKey32, 0);
+  out.set(params.destinationPublicKey32, 32);
+  writeI64LE(toI64(params.amount, "amount"), out, 64);
+
+  const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
+  view.setUint32(72, params.tick, true);
+  view.setUint16(76, inputType, true);
+  view.setUint16(78, inputSize, true);
+  out.set(inputBytes, TRANSACTION_HEADER_SIZE);
+
+  return out;
+}
+
+export async function unsignedTransactionDigest(unsignedTxBytes: Uint8Array): Promise<Uint8Array> {
+  if (!(unsignedTxBytes instanceof Uint8Array)) {
+    throw new TypeError("unsignedTxBytes must be a Uint8Array");
+  }
+  return k12(unsignedTxBytes, 32);
+}
+
+export async function signTransaction(
+  unsignedTxBytes: Uint8Array,
+  secretKey32: Uint8Array,
+): Promise<Uint8Array> {
+  if (!(unsignedTxBytes instanceof Uint8Array)) {
+    throw new TypeError("unsignedTxBytes must be a Uint8Array");
+  }
+  assertUint8ArrayLength(secretKey32, 32, "secretKey32");
+  if (unsignedTxBytes.byteLength < TRANSACTION_HEADER_SIZE) {
+    throw new RangeError("unsignedTxBytes is too short");
+  }
+
+  const view = new DataView(
+    unsignedTxBytes.buffer,
+    unsignedTxBytes.byteOffset,
+    unsignedTxBytes.byteLength,
+  );
+  const inputSize = view.getUint16(78, true);
+  if (unsignedTxBytes.byteLength !== TRANSACTION_HEADER_SIZE + inputSize) {
+    throw new RangeError("unsignedTxBytes length does not match inputSize");
+  }
+
+  const digest32 = await unsignedTransactionDigest(unsignedTxBytes);
+  const publicKey32 = unsignedTxBytes.subarray(0, 32);
+  return sign(secretKey32, publicKey32, digest32);
+}
+
+export async function buildSignedTransaction(
+  params: BuildUnsignedTransactionParams,
+  secretKey32: Uint8Array,
+): Promise<Uint8Array> {
+  const unsignedTxBytes = buildUnsignedTransaction(params);
+  const signature64 = await signTransaction(unsignedTxBytes, secretKey32);
+  assertUint8ArrayLength(signature64, SIGNATURE_LENGTH, "signature64");
+
+  const out = new Uint8Array(unsignedTxBytes.byteLength + SIGNATURE_LENGTH);
+  out.set(unsignedTxBytes, 0);
+  out.set(signature64, unsignedTxBytes.byteLength);
+  return out;
+}
+
+export async function transactionDigest(txBytes: Uint8Array): Promise<Uint8Array> {
+  if (!(txBytes instanceof Uint8Array)) {
+    throw new TypeError("txBytes must be a Uint8Array");
+  }
+  if (txBytes.byteLength < TRANSACTION_HEADER_SIZE + SIGNATURE_LENGTH) {
+    throw new RangeError("txBytes is too short");
+  }
+  if (txBytes.byteLength > MAX_TRANSACTION_SIZE) {
+    throw new RangeError(`txBytes must be <= ${MAX_TRANSACTION_SIZE} bytes`);
+  }
+  return k12(txBytes, 32);
+}
+
+export async function transactionId(txBytes: Uint8Array): Promise<string> {
+  const digest32 = await transactionDigest(txBytes);
+  return identityFromPublicKey(digest32, { lowerCase: true });
+}
+

package/src/transport/async-queue.ts

@@ -0,0 +1,60 @@
+export class AsyncQueue<T> implements AsyncIterable<T> {
+  private readonly values: T[] = [];
+  private readonly waiters: Array<(result: IteratorResult<T>) => void> = [];
+  private closed = false;
+  private failure: unknown = undefined;
+
+  push(value: T) {
+    if (this.closed) return;
+
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter({ value, done: false });
+      return;
+    }
+
+    this.values.push(value);
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    while (this.waiters.length) {
+      const waiter = this.waiters.shift();
+      waiter?.({ value: undefined as never, done: true });
+    }
+  }
+
+  error(err: unknown) {
+    if (this.closed) return;
+    this.failure = err;
+    this.closed = true;
+    while (this.waiters.length) {
+      const waiter = this.waiters.shift();
+      waiter?.({ value: undefined as never, done: true });
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return {
+      next: () => {
+        if (this.failure !== undefined) {
+          return Promise.reject(this.failure);
+        }
+
+        const value = this.values.shift();
+        if (value !== undefined) {
+          return Promise.resolve({ value, done: false });
+        }
+
+        if (this.closed) {
+          return Promise.resolve({ value: undefined as never, done: true });
+        }
+
+        return new Promise<IteratorResult<T>>((resolve) => {
+          this.waiters.push(resolve);
+        });
+      },
+    };
+  }
+}

package/src/transport/bridge.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "bun:test";
+import type { BridgeWebSocketConstructor } from "./bridge.js";
+import { createBridgeTransport } from "./bridge.js";
+
+type Listener = (event: unknown) => void;
+
+class FakeWebSocket {
+  static readonly CONNECTING = 0;
+  static readonly OPEN = 1;
+  static readonly CLOSING = 2;
+  static readonly CLOSED = 3;
+
+  readonly CONNECTING = FakeWebSocket.CONNECTING;
+  readonly OPEN = FakeWebSocket.OPEN;
+  readonly CLOSING = FakeWebSocket.CLOSING;
+  readonly CLOSED = FakeWebSocket.CLOSED;
+
+  readyState = FakeWebSocket.CONNECTING;
+  binaryType = "arraybuffer";
+  readonly sent: Uint8Array[] = [];
+  readonly listeners = new Map<string, Listener[]>();
+
+  constructor(public readonly url: string) {
+    queueMicrotask(() => this.open());
+  }
+
+  addEventListener(type: string, listener: Listener, options?: { once?: boolean }) {
+    const wrapper: Listener = options?.once
+      ? (e) => {
+          this.removeEventListener(type, wrapper);
+          listener(e);
+        }
+      : listener;
+    const list = this.listeners.get(type) ?? [];
+    list.push(wrapper);
+    this.listeners.set(type, list);
+  }
+
+  removeEventListener(type: string, listener: Listener) {
+    const list = this.listeners.get(type) ?? [];
+    this.listeners.set(
+      type,
+      list.filter((l) => l !== listener),
+    );
+  }
+
+  private emit(type: string, event: unknown) {
+    const list = this.listeners.get(type) ?? [];
+    for (const l of list) l(event);
+  }
+
+  open() {
+    this.readyState = FakeWebSocket.OPEN;
+    this.emit("open", {});
+  }
+
+  message(data: Uint8Array | ArrayBuffer) {
+    this.emit("message", { data });
+  }
+
+  send(data: Uint8Array) {
+    this.sent.push(new Uint8Array(data));
+  }
+
+  close() {
+    this.readyState = FakeWebSocket.CLOSED;
+    this.emit("close", {});
+  }
+}
+
+describe("bridge transport", () => {
+  it("writes websocket binary messages", async () => {
+    let instance: FakeWebSocket | undefined;
+    const WebSocketImpl = class extends FakeWebSocket {
+      constructor(url: string) {
+        super(url);
+        instance = this;
+      }
+    };
+
+    const transport = await createBridgeTransport({
+      url: "ws://example",
+      WebSocketImpl: WebSocketImpl as unknown as BridgeWebSocketConstructor,
+    });
+
+    await transport.write(Uint8Array.from([1, 2, 3]));
+    expect(instance?.sent).toEqual([Uint8Array.from([1, 2, 3])]);
+
+    await transport.close();
+  });
+
+  it("yields inbound messages", async () => {
+    let instance: FakeWebSocket | undefined;
+    const WebSocketImpl = class extends FakeWebSocket {
+      constructor(url: string) {
+        super(url);
+        instance = this;
+      }
+    };
+
+    const transport = await createBridgeTransport({
+      url: "ws://example",
+      WebSocketImpl: WebSocketImpl as unknown as BridgeWebSocketConstructor,
+    });
+    const iter = transport.read()[Symbol.asyncIterator]();
+
+    instance?.message(Uint8Array.from([9, 8, 7]));
+    const msg = await iter.next();
+    expect(msg.done).toBe(false);
+    expect(msg.value).toEqual(Uint8Array.from([9, 8, 7]));
+
+    await transport.close();
+  });
+});