@freedomofpress/cometbft 0.1.0

package/.github/workflows/auto-bump.yml

@@ -0,0 +1,81 @@
+name: Auto Bump Dependencies
+
+on:
+  schedule:
+    - cron: "0 4 * * *"
+  workflow_dispatch:
+
+jobs:
+  auto-bump:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install npm-check-updates
+        run: npm install -g npm-check-updates
+
+      - name: Bump dependencies
+        run: |
+          ncu -u --peer
+          # ncu -u --reject '/^typescript$/'
+
+      - name: Setup Buf
+        uses: bufbuild/buf-setup-action@v1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # buf_token: ${{ secrets.BUF_TOKEN }} # uncomment if you need auth to buf.build
+
+      - name: Cache Buf modules
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/buf
+          key: ${{ runner.os }}-buf-${{ hashFiles('buf.yaml', 'buf.gen.yaml', 'buf.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-buf-
+
+      - name: Generate protobufs
+        run: npm run proto:gen
+
+      - name: Install updated deps
+        run: npm install
+
+      - name: Run npm audit fix
+        run: npm audit fix || true
+
+      - name: Commit changes (bump + audit fix)
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add package.json package-lock.json
+          git diff --cached --quiet || git commit -m "chore: bump dependencies and apply audit fix"
+        continue-on-error: true
+
+      - name: Run tests on updated deps
+        id: test
+        run: npm test
+        continue-on-error: true
+
+      - name: If tests pass, push to main
+        if: steps.test.outcome == 'success'
+        run: git push origin HEAD:main
+
+      - name: If tests fail, create PR
+        if: steps.test.outcome == 'failure'
+        uses: peter-evans/create-pull-request@v5
+        with:
+          branch: bump-deps-failed
+          title: "chore: bump dependencies and audit fix (tests failed)"
+          body: |
+            Dependencies were updated and `npm audit fix` was run, but tests failed.
+            Please investigate and merge manually.
+          commit-message: "chore: bump dependencies and audit fix (tests failed)"

package/.github/workflows/publish.yml

@@ -0,0 +1,60 @@
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  run-tests:
+    uses: ./.github/workflows/test.yml
+
+  publish:
+    needs: run-tests
+    runs-on: ubuntu-latest
+
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - name: Install deps
+        run: npm ci
+
+      - name: Setup Buf
+        uses: bufbuild/buf-setup-action@v1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Cache Buf modules
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/buf
+          key: ${{ runner.os }}-buf-${{ hashFiles('buf.yaml', 'buf.gen.yaml', 'buf.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-buf-
+
+      - name: Generate protobufs
+        run: npm run proto:gen
+
+      - name: Build
+        run: npm run build
+
+      - name: Dry-run publish
+        run: npm publish --dry-run
+
+      - name: Publish to npm
+        run: npm publish --access public

package/.github/workflows/test.yml

@@ -0,0 +1,56 @@
+name: Lint, Test, Proto Gen and Coverage
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+  workflow_call:
+
+jobs:
+  lint-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run ESLint
+        run: npm run lint
+
+      - name: Setup Buf
+        uses: bufbuild/buf-setup-action@v1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Cache Buf modules
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/buf
+          key: ${{ runner.os }}-buf-${{ hashFiles('buf.yaml', 'buf.gen.yaml', 'buf.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-buf-
+
+      - name: Generate protobufs
+        run: npm run proto:gen
+
+      - name: Ensure generated code is up to date
+        run: |
+          if ! git diff --quiet; then
+            echo "Generated protobufs are not up-to-date. Run 'npm run proto:gen' and commit the changes."
+            git --no-pager diff
+            exit 1
+          fi
+
+      - name: Run tests
+        run: npm run test

package/Readme.md

@@ -0,0 +1,54 @@
+# cometbft-ts
+
+_Note: this library has not been audited, thus its security has not been independently verified._
+
+`cometbft-ts` is a small TypeScript library for verifying CometBFT commits in the browser. It takes the JSON you get from CometBFT ABCI/RPC for a `commit` and its `validators`, constructs canonical sign-bytes via protobuf, and verifies Ed25519 signatures and >2/3 quorum. It is verification-only and throws on any cryptographic or format error. It uses the native [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). The library is developed as part of [WEBCAT](https://github.com/freedomofpress/webcat) and is **not audited**.
+
+## Usage
+
+```ts
+import { importCommit } from "./src/commit";
+import { importValidators } from "./src/validators";
+import { verifyCommit } from "./src/lightclient";
+
+// JSON from CometBFT RPC: /commit and /validators
+const sh = importCommit(commitJson);
+const { proto: vset, cryptoIndex } = await importValidators(validatorsJson);
+
+const result = await verifyCommit(sh, vset, cryptoIndex);
+```
+
+## Tests
+
+```bash
+$ npm run coverage
+
+> cometbft@0.1.0 coverage
+> vitest run --coverage
+
+
+ RUN  v3.2.4 /Users/g/cometbft-ts
+      Coverage enabled with v8
+
+ ✓ src/tests/encoding.test.ts (6 tests) 2ms
+ ✓ src/tests/commit.test.ts (27 tests) 7ms
+ ✓ src/tests/validators.test.ts (18 tests) 13ms
+ ✓ src/tests/lightclient.test.ts (19 tests) 11ms
+
+ Test Files  4 passed (4)
+      Tests  70 passed (70)
+   Start at  20:45:26
+   Duration  377ms (transform 133ms, setup 0ms, collect 222ms, tests 33ms, environment 0ms, prepare 241ms)
+
+ % Coverage report from v8
+----------------|---------|----------|---------|---------|-------------------
+File            | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
+----------------|---------|----------|---------|---------|-------------------
+All files       |     100 |      100 |     100 |     100 |
+ commit.ts      |     100 |      100 |     100 |     100 |
+ encoding.ts    |     100 |      100 |     100 |     100 |
+ lightclient.ts |     100 |      100 |     100 |     100 |
+ types.ts       |       0 |        0 |       0 |       0 |
+ validators.ts  |     100 |      100 |     100 |     100 |
+----------------|---------|----------|---------|---------|-------------------
+```

package/buf.gen.yaml

@@ -0,0 +1,12 @@
+version: v1
+plugins:
+  - plugin: buf.build/community/stephenh-ts-proto:v2.6.1
+    out: src/proto
+    opt:
+      - env=browser
+      - esModuleInterop=true
+      - useOptionals=messages
+      - forceLong=bigint
+      - snakeToCamel=true
+      - outputServices=none
+      - useDate=false

package/buf.yaml

@@ -0,0 +1,4 @@
+version: v1
+deps:
+  - buf.build/cometbft/cometbft
+  - buf.build/googleapis/googleapis

package/eslint.config.js

@@ -0,0 +1,31 @@
+import simpleImportSort from "eslint-plugin-simple-import-sort";
+import * as tseslint from "typescript-eslint";
+
+export default [
+  ...tseslint.configs.recommended,
+
+  {
+    files: ["**/*.{js,ts}"],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: "module",
+    },
+    plugins: {
+      "simple-import-sort": simpleImportSort,
+    },
+    rules: {
+      "simple-import-sort/imports": "error",
+      "simple-import-sort/exports": "error",
+      "@typescript-eslint/no-non-null-assertion": "warn",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+        },
+      ],
+
+      "no-delete-var": "off",
+    },
+  },
+];

package/localnet.sh

@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ===================== config =====================
+COMETBFT_BIN="${COMETBFT_BIN:-cometbft}"   # path to cometbft binary
+HOME_ROOT="${HOME_ROOT:-./mytestnet}"
+NODES=4
+
+# base ports (node0 uses these; others add STEP)
+RPC_BASE=26657
+P2P_BASE=26656
+PPROF_BASE=6060
+STEP=3
+
+node_home() { echo "${HOME_ROOT}/node$1"; }
+rpc_port()  { echo $((RPC_BASE  + ($1 * STEP))); }
+p2p_port()  { echo $((P2P_BASE  + ($1 * STEP))); }
+pprof_port(){ echo $((PPROF_BASE+ ($1 * STEP))); }
+
+die() { echo "error: $*" >&2; exit 1; }
+has() { command -v "$1" >/dev/null 2>&1; }
+
+# ===================== portable sed =====================
+# GNU vs BSD sed inline edit
+sedi() {
+  if sed --version >/dev/null 2>&1; then
+    sed -i -e "$@"
+  else
+    sed -i '' -e "$@"
+  fi
+}
+
+# set TOML key within a section [section]; quoted value
+toml_set_q() {
+  local file="$1" section="$2" key="$3" value="$4"
+  sedi "/^\[${section}\]\$/,/^\[/{ s|^${key}[[:space:]]*=.*$|${key} = \"${value}\"|; }" "$file"
+}
+
+# set TOML key within a section [section]; raw (booleans/numbers)
+toml_set_raw() {
+  local file="$1" section="$2" key="$3" value="$4"
+  sedi "/^\[${section}\]\$/,/^\[/{ s|^${key}[[:space:]]*=.*$|${key} = ${value}|; }" "$file"
+}
+
+# ===================== generation & patching =====================
+ensure_tools() {
+  has "$COMETBFT_BIN" || die "cometbft not found; set COMETBFT_BIN or add to PATH"
+  has curl || die "curl required"
+  has jq   || die "jq required (brew install jq)"
+}
+
+gen_testnet() {
+  # nuke old, generate, THEN make logs/run dirs so they survive
+  rm -rf "$HOME_ROOT"
+  "$COMETBFT_BIN" testnet --v "$NODES" --o "$HOME_ROOT" >/dev/null
+  mkdir -p "${HOME_ROOT}/_logs" "${HOME_ROOT}/_run"
+  echo "Generated ${NODES}-node testnet in $HOME_ROOT"
+}
+
+patch_node_config() {
+  local i="$1"
+  local cfg="$(node_home "$i")/config/config.toml"
+
+  toml_set_q   "$cfg" rpc laddr            "tcp://127.0.0.1:$(rpc_port "$i")"
+  toml_set_q   "$cfg" p2p laddr            "tcp://127.0.0.1:$(p2p_port "$i")"
+  toml_set_q   "$cfg" instrumentation pprof_laddr "localhost:$(pprof_port "$i")"
+
+  # localhost-friendly P2P
+  toml_set_raw "$cfg" p2p addr_book_strict false
+  toml_set_raw "$cfg" p2p allow_duplicate_ip true
+}
+
+wire_peers() {
+  # gather ids
+  local -a ids
+  for i in $(seq 0 $((NODES-1))); do
+    ids[$i]=$("$COMETBFT_BIN" show-node-id --home "$(node_home "$i")")
+  done
+  # set persistent_peers (everyone else)
+  for i in $(seq 0 $((NODES-1))); do
+    local peers=""
+    for j in $(seq 0 $((NODES-1))); do
+      [ "$i" -eq "$j" ] && continue
+      local addr="${ids[$j]}@127.0.0.1:$(p2p_port "$j")"
+      peers="${peers:+$peers,}$addr"
+    done
+    toml_set_q "$(node_home "$i")/config/config.toml" p2p persistent_peers "$peers"
+  done
+}
+
+# ===================== lifecycle =====================
+start_nodes() {
+  for i in $(seq 0 $((NODES-1))); do
+    local home log pidfile
+    home="$(node_home "$i")"
+    log="${HOME_ROOT}/_logs/node${i}.log"
+    pidfile="${HOME_ROOT}/_run/node${i}.pid"
+
+    if [ -f "$pidfile" ] && kill -0 "$(cat "$pidfile")" 2>/dev/null; then
+      echo "node${i} already running (pid $(cat "$pidfile"))"
+      continue
+    fi
+
+    echo "Starting node${i} (RPC :$(rpc_port "$i"), P2P :$(p2p_port "$i")) ..."
+    nohup "$COMETBFT_BIN" node \
+      --home "$home" \
+      --proxy_app=persistent_kvstore \
+      >"$log" 2>&1 &
+    echo $! >"$pidfile"
+  done
+
+  # wait for RPC to be responsive
+  for i in $(seq 0 $((NODES-1))); do
+    local port; port=$(rpc_port "$i")
+    printf "Waiting for node%s RPC :%s " "$i" "$port"
+    for _ in $(seq 1 60); do
+      if curl -sf "http://127.0.0.1:${port}/status" >/dev/null; then
+        echo "✓"
+        break
+      fi
+      sleep 0.2; printf "."
+    done
+    echo
+    if ! curl -sf "http://127.0.0.1:${port}/status" >/dev/null; then
+      echo "node${i} failed to start; last 50 log lines:"
+      tail -n 50 "${HOME_ROOT}/_logs/node${i}.log" || true
+      exit 1
+    fi
+  done
+  echo "All nodes up."
+}
+
+stop_nodes() {
+  local any=0
+  for i in $(seq 0 $((NODES-1))); do
+    local pidfile="${HOME_ROOT}/_run/node${i}.pid"
+    if [ -f "$pidfile" ]; then
+      local pid; pid="$(cat "$pidfile")"
+      if kill -0 "$pid" 2>/dev/null; then
+        echo "Stopping node${i} (pid $pid)"
+        kill "$pid" || true
+        any=1
+      fi
+      rm -f "$pidfile"
+    fi
+  done
+  [ "$any" -eq 0 ] && echo "No nodes appeared to be running."
+}
+
+status_nodes() {
+  for i in $(seq 0 $((NODES-1))); do
+    local pidfile="${HOME_ROOT}/_run/node${i}.pid"
+    local state="stopped"
+    if [ -f "$pidfile" ] && kill -0 "$(cat "$pidfile")" 2>/dev/null; then
+      state="RUNNING (pid $(cat "$pidfile"))"
+    fi
+    local port; port=$(rpc_port "$i")
+    local h="n/a"
+    if curl -sf "http://127.0.0.1:${port}/status" >/dev/null 2>&1; then
+      h=$(curl -s "http://127.0.0.1:${port}/status" | jq -r .result.sync_info.latest_block_height)
+    fi
+    echo "node${i}: ${state}, RPC :$port, height=${h}"
+  done
+}
+
+logs_node() {
+  local i="${1:-0}"
+  tail -f "${HOME_ROOT}/_logs/node${i}.log"
+}
+
+clean_all() {
+  stop_nodes || true
+  rm -rf "$HOME_ROOT"
+  echo "Cleaned $HOME_ROOT"
+}
+
+send_tx() {
+  local port="${1:-26657}"
+  local data="${2:-a=1}"
+  curl -s "http://127.0.0.1:${port}/broadcast_tx_commit?tx=\"${data}\"" | jq .
+}
+
+snapshot() {
+  local port="${1:-26657}"
+  local H="${2:-$(curl -s 127.0.0.1:${port}/status | jq -r .result.sync_info.latest_block_height)}"
+  curl -s "http://127.0.0.1:${port}/commit?height=${H}"     > "commit-${H}.json"
+  curl -s "http://127.0.0.1:${port}/validators?height=${H}" > "validators-${H}.json"
+  echo "Wrote commit-${H}.json and validators-${H}.json"
+}
+
+# ===================== CLI =====================
+case "${1:-}" in
+  start)
+    ensure_tools
+    gen_testnet
+    for i in $(seq 0 $((NODES-1))); do patch_node_config "$i"; done
+    wire_peers
+    start_nodes
+    ;;
+  stop)     stop_nodes ;;
+  status)   status_nodes ;;
+  logs)     logs_node "${2:-0}" ;;
+  clean)    clean_all ;;
+  tx)       send_tx "${2:-26657}" "${3:-a=1}" ;;
+  snapshot) snapshot "${2:-26657}" "${3:-}" ;;
+  *)
+    cat <<EOF
+Usage: $0 {start|stop|status|logs [i]|clean|tx [rpc_port [kv]]|snapshot [rpc_port [height]]}
+
+start     Generate & start 4-node localhost net (in-process kvstore)
+stop      Stop all nodes
+status    Show PID / RPC / height
+logs [i]  Tail logs for node i (default 0)
+clean     Stop & remove the testnet directory
+tx [p d]  Broadcast kv tx to RPC port p (default 26657) with data d (default "a=1")
+snapshot [p H] Export commit-H.json and validators-H.json from RPC port p (defaults to latest)
+EOF
+    ;;
+esac

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@freedomofpress/cometbft",
+  "version": "0.1.0",
+  "description": "A CometBFT light client for the browser.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/freedomofpress/cometbft-ts"
+  },
+  "main": "dist/client.js",
+  "types": "dist/client.d.ts",
+  "scripts": {
+    "proto:gen": "buf generate buf.build/cometbft/cometbft --path cometbft/types/v1/types.proto --path cometbft/types/v1/canonical.proto --path cometbft/types/v1/validator.proto --path cometbft/version/v1/types.proto",
+    "build": "tsc",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "lint": "npx eslint --ignore-pattern '**/*.test.ts' . --fix && npx prettier --write ."
+  },
+  "keywords": [
+    "cometbft",
+    "ed25519",
+    "p2p",
+    "browser",
+    "typescript"
+  ],
+  "author": "Giulio B",
+  "license": "MIT",
+  "homepage": "https://github.com/freedomofpress/cometbft-ts#readme",
+  "bugs": "https://github.com/freedomofpress/cometbft-ts/issues",
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.13",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.0",
+    "vitest": "^4.0.13"
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.10.1"
+  }
+}