@freedomofpress/cometbft 0.1.0

package/src/commit.ts

@@ -0,0 +1,210 @@
+// src/commit.ts
+import { base64ToUint8Array, hexToUint8Array } from "./encoding";
+import {
+  BlockID,
+  Commit,
+  CommitSig,
+  Header,
+  SignedHeader,
+} from "./proto/cometbft/types/v1/types";
+import { BlockIDFlag } from "./proto/cometbft/types/v1/validator";
+import { Consensus } from "./proto/cometbft/version/v1/types";
+import { Timestamp as PbTimestamp } from "./proto/google/protobuf/timestamp";
+import type { CommitJson } from "./types";
+
+// ---- helpers ----
+function assertLen(name: string, u8: Uint8Array, expect: number) {
+  if (u8.length !== expect) {
+    throw new Error(`${name} must be ${expect} bytes, got ${u8.length}`);
+  }
+}
+
+function parseRFC3339ToTimestamp(s: string): PbTimestamp {
+  const d = new Date(s);
+  if (Number.isNaN(d.getTime())) throw new Error(`Invalid RFC3339 time: ${s}`);
+
+  // extract fractional seconds (up to 9 digits for nanos)
+  const fracMatch = s.match(/\.(\d+)Z$/i);
+  const frac = fracMatch ? fracMatch[1] : "";
+  const n = Math.min(frac.length, 9);
+  const nanos = n === 0 ? 0 : Number((frac + "0".repeat(9 - n)).slice(0, 9));
+  const seconds = BigInt(Math.floor(d.getTime() / 1000));
+
+  return { seconds, nanos };
+}
+
+/**
+ * Parse and validate a /commit JSON and return a ts-proto SignedHeader
+ * (cometbft.types.v1.SignedHeader).
+ */
+export function importCommit(resp: CommitJson): SignedHeader {
+  const sh = resp.signed_header;
+
+  if (!sh) throw new Error("Missing signed_header");
+
+  const h = sh.header;
+  const c = sh.commit;
+
+  if (!h) throw new Error("Missing header");
+  if (!c) throw new Error("Missing commit");
+
+  // Heights
+  if (!h.height) throw new Error("Missing header.height");
+  if (c.height == null || c.height === "")
+    throw new Error("Missing commit.height");
+  const headerHeight = BigInt(h.height);
+  const commitHeight = BigInt(c.height);
+  if (headerHeight !== commitHeight) {
+    throw new Error(`height mismatch header=${h.height} commit=${c.height}`);
+  }
+
+  // Round
+  if (
+    typeof c.round !== "number" ||
+    c.round < 0 ||
+    !Number.isInteger(c.round)
+  ) {
+    throw new Error("Invalid commit.round");
+  }
+
+  // version (optional)
+  const version: Consensus = {
+    block: h.version?.block ? BigInt(h.version.block) : 0n,
+    app: h.version?.app ? BigInt(h.version.app) : 0n,
+  };
+
+  // last_block_id
+  if (!h.last_block_id || !h.last_block_id.hash || !h.last_block_id.parts) {
+    throw new Error("Invalid last_block_id");
+  }
+  const lastBlockIdHash = hexToUint8Array(h.last_block_id.hash);
+  assertLen("last_block_id.hash", lastBlockIdHash, 32);
+  const lastBlockPartsHash = hexToUint8Array(h.last_block_id.parts.hash);
+  assertLen("last_block_id.parts.hash", lastBlockPartsHash, 32);
+  const lastBlockId: BlockID = {
+    hash: lastBlockIdHash,
+    partSetHeader: {
+      total: Number(h.last_block_id.parts.total),
+      hash: lastBlockPartsHash,
+    },
+  };
+  if (
+    !lastBlockId.partSetHeader ||
+    !lastBlockId.partSetHeader.total ||
+    !Number.isInteger(lastBlockId.partSetHeader.total) ||
+    lastBlockId.partSetHeader.total < 0
+  ) {
+    throw new Error("Invalid last_block_id.parts.total");
+  }
+
+  // Hash fields (32 bytes unless app hash, which is app-defined length)
+  const lastCommitHash = hexToUint8Array(h.last_commit_hash);
+  assertLen("last_commit_hash", lastCommitHash, 32);
+  const dataHash = hexToUint8Array(h.data_hash);
+  assertLen("data_hash", dataHash, 32);
+  const validatorsHash = hexToUint8Array(h.validators_hash);
+  assertLen("validators_hash", validatorsHash, 32);
+  const nextValidatorsHash = hexToUint8Array(h.next_validators_hash);
+  assertLen("next_validators_hash", nextValidatorsHash, 32);
+  const consensusHash = hexToUint8Array(h.consensus_hash);
+  assertLen("consensus_hash", consensusHash, 32);
+  const appHash = hexToUint8Array(h.app_hash); // variable length accepted
+  const lastResultsHash = hexToUint8Array(h.last_results_hash);
+  assertLen("last_results_hash", lastResultsHash, 32);
+  const evidenceHash = hexToUint8Array(h.evidence_hash);
+  assertLen("evidence_hash", evidenceHash, 32);
+
+  // proposer_address (20 bytes)
+  if (!h.proposer_address) throw new Error("Missing proposer_address");
+  const proposerAddress = hexToUint8Array(h.proposer_address);
+  assertLen("proposer_address", proposerAddress, 20);
+
+  // time
+  if (!h.time) throw new Error("Missing header.time");
+  const time = parseRFC3339ToTimestamp(h.time);
+
+  // Commit BlockID
+  if (!c.block_id || !c.block_id.hash || !c.block_id.parts) {
+    throw new Error("Invalid commit.block_id");
+  }
+  const commitBlockHash = hexToUint8Array(c.block_id.hash);
+  assertLen("commit.block_id.hash", commitBlockHash, 32);
+  const commitPartsHash = hexToUint8Array(c.block_id.parts.hash);
+  assertLen("commit.block_id.parts.hash", commitPartsHash, 32);
+  const commitBlockId: BlockID = {
+    hash: commitBlockHash,
+    partSetHeader: {
+      total: Number(c.block_id.parts.total),
+      hash: commitPartsHash,
+    },
+  };
+  if (
+    !commitBlockId ||
+    !commitBlockId.partSetHeader ||
+    !Number.isInteger(commitBlockId.partSetHeader.total) ||
+    commitBlockId.partSetHeader.total < 0
+  ) {
+    throw new Error("Invalid commit.block_id.parts.total");
+  }
+
+  // Signatures
+  if (!Array.isArray(c.signatures) || c.signatures.length === 0) {
+    throw new Error("Commit has no signatures");
+  }
+  const signatures: CommitSig[] = c.signatures.map((s, i) => {
+    if (typeof s.block_id_flag !== "number") {
+      throw new Error(`signatures[${i}].block_id_flag must be a number`);
+    }
+    if (!s.validator_address) {
+      throw new Error(`signatures[${i}].validator_address missing`);
+    }
+    const validatorAddress = hexToUint8Array(s.validator_address);
+    assertLen(`signatures[${i}].validator_address`, validatorAddress, 20);
+
+    // bytes fields in proto3 are NOT optional -> use empty Uint8Array when absent
+    const sigBytes = s.signature
+      ? base64ToUint8Array(s.signature)
+      : new Uint8Array(0);
+    if (sigBytes.length !== 0) {
+      assertLen(`signatures[${i}].signature`, sigBytes, 64); // Ed25519
+    }
+
+    const ts = s.timestamp ? parseRFC3339ToTimestamp(s.timestamp) : undefined;
+
+    return {
+      blockIdFlag: s.block_id_flag as BlockIDFlag,
+      validatorAddress,
+      timestamp: ts, // PbTimestamp | undefined (useDate=false)
+      signature: sigBytes, // always Uint8Array (maybe length 0)
+    };
+  });
+
+  const header: Header = {
+    version,
+    chainId: h.chain_id,
+    height: headerHeight,
+    time,
+
+    lastBlockId,
+
+    lastCommitHash,
+    dataHash,
+    validatorsHash,
+    nextValidatorsHash,
+    consensusHash,
+    appHash,
+    lastResultsHash,
+    evidenceHash,
+
+    proposerAddress,
+  };
+
+  const commit: Commit = {
+    height: headerHeight,
+    round: c.round,
+    blockId: commitBlockId,
+    signatures,
+  };
+
+  return { header, commit };
+}

package/src/encoding.ts

@@ -0,0 +1,37 @@
+export function Uint8ArrayToBase64(data: Uint8Array | ArrayBuffer): string {
+  const uint8 = data instanceof Uint8Array ? data : new Uint8Array(data);
+  const binary = String.fromCharCode(...uint8);
+  return btoa(binary);
+}
+
+export function hexToUint8Array(hex: string): Uint8Array {
+  if (!/^[0-9a-fA-F]*$/.test(hex)) {
+    throw new Error("Hex string contains invalid characters");
+  }
+
+  if (hex.length % 2 !== 0) {
+    throw new Error("Hex string must have an even length");
+  }
+
+  const uint8Array = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < uint8Array.length; i++) {
+    uint8Array[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return uint8Array;
+}
+
+export function Uint8ArrayToHex(uint8Array: Uint8Array): string {
+  return [...uint8Array].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export function base64ToUint8Array(base64: string): Uint8Array {
+  const binaryString = atob(base64);
+  const length = binaryString.length;
+  const bytes = new Uint8Array(length);
+
+  for (let i = 0; i < length; i++) {
+    bytes[i] = binaryString.charCodeAt(i); // Convert binary string to byte array
+  }
+
+  return new Uint8Array(bytes);
+}

package/src/lightclient.ts

@@ -0,0 +1,214 @@
+// src/lightclient.ts
+import { Uint8ArrayToHex } from "./encoding";
+import {
+  CanonicalBlockID,
+  CanonicalPartSetHeader,
+  CanonicalVote,
+} from "./proto/cometbft/types/v1/canonical";
+import { SignedHeader, SignedMsgType } from "./proto/cometbft/types/v1/types";
+import {
+  Validator as ProtoValidator,
+  ValidatorSet as ProtoValidatorSet,
+} from "./proto/cometbft/types/v1/validator";
+import { Timestamp as PbTimestamp } from "./proto/google/protobuf/timestamp";
+
+export type CryptoIndex = Map<string, CryptoKey>;
+
+export interface VerifyOutcome {
+  ok: boolean;
+  quorum: boolean;
+  signedPower: bigint;
+  totalPower: bigint;
+  headerTime?: PbTimestamp;
+  appHash: Uint8Array;
+  blockIdHash: Uint8Array;
+  unknownValidators: string[];
+  invalidSignatures: string[];
+  countedSignatures: number;
+}
+
+function encodeUvarint(value: number): Uint8Array {
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw new Error("encodeUvarint expects a non-negative safe integer");
+
+  const bytes: number[] = [];
+  let v = value;
+  while (v >= 0x80) {
+    bytes.push((v & 0x7f) | 0x80);
+    v >>>= 7;
+  }
+  bytes.push(v);
+  return new Uint8Array(bytes);
+}
+
+function makePrecommitSignBytesProto(
+  chainId: string,
+  height: bigint,
+  round: bigint,
+  blockIdHash: Uint8Array,
+  partsTotal: number,
+  partsHash: Uint8Array,
+  timestamp?: PbTimestamp,
+): Uint8Array {
+  const psh: CanonicalPartSetHeader = { total: partsTotal, hash: partsHash };
+  const bid: CanonicalBlockID = { hash: blockIdHash, partSetHeader: psh };
+
+  const vote: CanonicalVote = {
+    type: SignedMsgType.SIGNED_MSG_TYPE_PRECOMMIT,
+    height, // fixed64
+    round, // fixed64 (encoder omits 0)
+    blockId: bid,
+    timestamp, // omitted if undefined
+    chainId,
+  };
+
+  const body = CanonicalVote.encode(vote).finish();
+  // Go's protoio.MarshalDelimited length-prefixes the canonical vote. Using
+  // the same varint prefix keeps signatures compatible with both v0.34.x and
+  // v1.0.x chains.
+  const prefix = encodeUvarint(body.length);
+  const out = new Uint8Array(prefix.length + body.length);
+  out.set(prefix, 0);
+  out.set(body, prefix.length);
+  return out;
+}
+
+function hasTwoThirds(signed: bigint, total: bigint): boolean {
+  return signed * 3n > total * 2n;
+}
+
+export async function verifyCommit(
+  sh: SignedHeader,
+  vset: ProtoValidatorSet,
+  cryptoIndex: CryptoIndex,
+): Promise<VerifyOutcome> {
+  if (!sh?.header || !sh?.commit) {
+    throw new Error("SignedHeader missing header/commit");
+  }
+  const header = sh.header;
+  const commit = sh.commit;
+
+  if (header.height !== commit.height) {
+    throw new Error(
+      `Header/commit height mismatch: ${header.height} vs ${commit.height}`,
+    );
+  }
+
+  const totalPower = vset?.totalVotingPower ?? 0n;
+  if (!Array.isArray(vset?.validators) || vset.validators.length === 0) {
+    throw new Error("ValidatorSet has no validators");
+  }
+  if (totalPower <= 0n) {
+    throw new Error("ValidatorSet total power must be positive");
+  }
+
+  // Build address -> validator map
+  const setByAddrHex = new Map<string, ProtoValidator>();
+  for (const v of vset.validators) {
+    const hex = Uint8ArrayToHex(v.address).toUpperCase();
+    if (setByAddrHex.has(hex))
+      throw new Error(`Duplicate validator address in set: ${hex}`);
+    setByAddrHex.set(hex, v);
+  }
+
+  if (!commit.blockId) throw new Error("Commit missing BlockID");
+  const bid = commit.blockId;
+  if (!bid.hash || bid.hash.length === 0)
+    throw new Error("Commit BlockID hash is missing");
+  if (!bid.partSetHeader) throw new Error("Commit PartSetHeader is missing");
+  if (!bid.partSetHeader.hash || bid.partSetHeader.hash.length === 0) {
+    throw new Error("Commit PartSetHeader hash is missing");
+  }
+  if (
+    !Number.isInteger(bid.partSetHeader.total) ||
+    bid.partSetHeader.total < 0
+  ) {
+    throw new Error("Commit PartSetHeader total is invalid");
+  }
+
+  const chainId: string = header.chainId;
+  const heightBig: bigint = header.height;
+  const roundBig: bigint = BigInt(commit.round);
+  const blockIdHash: Uint8Array = bid.hash;
+  const partsHash: Uint8Array = bid.partSetHeader.hash;
+  const partsTotal: number = bid.partSetHeader.total;
+
+  let signedPower = 0n;
+  const unknown: string[] = [];
+  const invalid: string[] = [];
+  let counted = 0;
+
+  for (let idx = 0; idx < commit.signatures.length; idx++) {
+    const s = commit.signatures[idx];
+
+    // Only COMMIT votes (BLOCK_ID_FLAG_COMMIT == 2)
+    if (s.blockIdFlag !== 2) continue;
+
+    const addrHex = Uint8ArrayToHex(s.validatorAddress).toUpperCase();
+    const v = setByAddrHex.get(addrHex);
+    if (!v) {
+      unknown.push(addrHex);
+      continue;
+    }
+
+    if (!s.signature || s.signature.length === 0) {
+      invalid.push(addrHex);
+      continue;
+    }
+
+    // Count this COMMIT vote (known validator + non-empty signature)
+    counted++;
+
+    // Canonical sign-bytes
+    const signBytes = makePrecommitSignBytesProto(
+      chainId,
+      heightBig,
+      roundBig,
+      blockIdHash,
+      partsTotal,
+      partsHash,
+      s.timestamp,
+    );
+
+    const key = cryptoIndex.get(addrHex);
+    if (!key) {
+      invalid.push(addrHex);
+      continue;
+    }
+
+    // Verify signature
+    let ok = false;
+    try {
+      ok = await crypto.subtle.verify(
+        { name: "Ed25519" },
+        key,
+        new Uint8Array(s.signature),
+        new Uint8Array(signBytes),
+      );
+    } catch {
+      ok = false;
+    }
+
+    if (!ok) {
+      invalid.push(addrHex);
+      continue;
+    }
+
+    signedPower += v.votingPower ?? 0n;
+  }
+
+  const quorum = hasTwoThirds(signedPower, totalPower);
+
+  return {
+    ok: quorum,
+    quorum,
+    signedPower,
+    totalPower,
+    headerTime: header.time,
+    appHash: header.appHash,
+    blockIdHash,
+    unknownValidators: unknown,
+    invalidSignatures: invalid,
+    countedSignatures: counted,
+  };
+}