sdk: add multi-language read-only SDKs for serviceability, telemetry, and revdist programs

.github/workflows/release.sdk-revdist.yml

@@ -0,0 +1,86 @@
+name: Release SDK revdist
+
+on:
+  push:
+    tags:
+      - "sdk-revdist/v*.*.*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish-pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#sdk-revdist/v}" >> "$GITHUB_OUTPUT"
+
+      - name: Verify version matches pyproject.toml
+        working-directory: sdk/revdist/python
+        run: |
+          pkg_version=$(python3 -c "
+          import tomllib
+          with open('pyproject.toml', 'rb') as f:
+              print(tomllib.load(f)['project']['version'])
+          ")
+          if [ "$pkg_version" != "${{ steps.version.outputs.version }}" ]; then
+            echo "Tag version (${{ steps.version.outputs.version }}) does not match pyproject.toml version ($pkg_version)"
+            exit 1
+          fi
+
+      - uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        working-directory: sdk/revdist/python
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: sdk/revdist/python/dist/
+
+  publish-npm:
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#sdk-revdist/v}" >> "$GITHUB_OUTPUT"
+
+      - name: Verify version matches package.json
+        working-directory: sdk/revdist/typescript
+        run: |
+          pkg_version=$(node -p "require('./package.json').version")
+          if [ "$pkg_version" != "${{ steps.version.outputs.version }}" ]; then
+            echo "Tag version (${{ steps.version.outputs.version }}) does not match package.json version ($pkg_version)"
+            exit 1
+          fi
+
+      - uses: oven-sh/setup-bun@v2
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Upgrade npm for OIDC trusted publishing
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        working-directory: sdk/revdist/typescript
+        run: bun install
+
+      - name: Build
+        working-directory: sdk/revdist/typescript
+        run: bun run build
+
+      - name: Publish to npm
+        working-directory: sdk/revdist/typescript
+        run: npm publish --access public

.github/workflows/release.sdk-serviceability.yml

@@ -0,0 +1,86 @@
+name: Release SDK serviceability
+
+on:
+  push:
+    tags:
+      - "sdk-serviceability/v*.*.*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish-pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#sdk-serviceability/v}" >> "$GITHUB_OUTPUT"
+
+      - name: Verify version matches pyproject.toml
+        working-directory: sdk/serviceability/python
+        run: |
+          pkg_version=$(python3 -c "
+          import tomllib
+          with open('pyproject.toml', 'rb') as f:
+              print(tomllib.load(f)['project']['version'])
+          ")
+          if [ "$pkg_version" != "${{ steps.version.outputs.version }}" ]; then
+            echo "Tag version (${{ steps.version.outputs.version }}) does not match pyproject.toml version ($pkg_version)"
+            exit 1
+          fi
+
+      - uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        working-directory: sdk/serviceability/python
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: sdk/serviceability/python/dist/
+
+  publish-npm:
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#sdk-serviceability/v}" >> "$GITHUB_OUTPUT"
+
+      - name: Verify version matches package.json
+        working-directory: sdk/serviceability/typescript
+        run: |
+          pkg_version=$(node -p "require('./package.json').version")
+          if [ "$pkg_version" != "${{ steps.version.outputs.version }}" ]; then
+            echo "Tag version (${{ steps.version.outputs.version }}) does not match package.json version ($pkg_version)"
+            exit 1
+          fi
+
+      - uses: oven-sh/setup-bun@v2
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Upgrade npm for OIDC trusted publishing
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        working-directory: sdk/serviceability/typescript
+        run: bun install
+
+      - name: Build
+        working-directory: sdk/serviceability/typescript
+        run: bun run build
+
+      - name: Publish to npm
+        working-directory: sdk/serviceability/typescript
+        run: npm publish --access public

.github/workflows/release.sdk-telemetry.yml

@@ -0,0 +1,86 @@
+name: Release SDK telemetry
+
+on:
+  push:
+    tags:
+      - "sdk-telemetry/v*.*.*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish-pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#sdk-telemetry/v}" >> "$GITHUB_OUTPUT"
+
+      - name: Verify version matches pyproject.toml
+        working-directory: sdk/telemetry/python
+        run: |
+          pkg_version=$(python3 -c "
+          import tomllib
+          with open('pyproject.toml', 'rb') as f:
+              print(tomllib.load(f)['project']['version'])
+          ")
+          if [ "$pkg_version" != "${{ steps.version.outputs.version }}" ]; then
+            echo "Tag version (${{ steps.version.outputs.version }}) does not match pyproject.toml version ($pkg_version)"
+            exit 1
+          fi
+
+      - uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        working-directory: sdk/telemetry/python
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: sdk/telemetry/python/dist/
+
+  publish-npm:
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#sdk-telemetry/v}" >> "$GITHUB_OUTPUT"
+
+      - name: Verify version matches package.json
+        working-directory: sdk/telemetry/typescript
+        run: |
+          pkg_version=$(node -p "require('./package.json').version")
+          if [ "$pkg_version" != "${{ steps.version.outputs.version }}" ]; then
+            echo "Tag version (${{ steps.version.outputs.version }}) does not match package.json version ($pkg_version)"
+            exit 1
+          fi
+
+      - uses: oven-sh/setup-bun@v2
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Upgrade npm for OIDC trusted publishing
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        working-directory: sdk/telemetry/typescript
+        run: bun install
+
+      - name: Build
+        working-directory: sdk/telemetry/typescript
+        run: bun run build
+
+      - name: Publish to npm
+        working-directory: sdk/telemetry/typescript
+        run: npm publish --access public

.github/workflows/sdk.yml

@@ -0,0 +1,33 @@
+name: sdk
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  sdk-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+      - uses: astral-sh/setup-uv@v6
+      - uses: oven-sh/setup-bun@v2
+      - run: make sdk-test
+
+  sdk-compat-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+      - uses: astral-sh/setup-uv@v6
+      - uses: oven-sh/setup-bun@v2
+      - run: make sdk-compat-test
+        env:
+          REVDIST_COMPAT_TEST: "1"

.gitignore

@@ -11,6 +11,7 @@ test-ledger/
 **/bin/*
 smartcontract/cli/config/*
 controlplane/funder/cmd/funder/funder
+revdist-cli
 
 .idea
 .private
@@ -22,6 +23,10 @@ controlplane/funder/cmd/funder/funder
 .env
 
 dist/
+node_modules/
+__pycache__/
+.pytest_cache/
+.venv/
 
 # Local devnet deployment artifacts.
 dev/.deploy/

CHANGELOG.md

@@ -16,6 +16,13 @@ All notable changes to this project will be documented in this file.
   - Fix goroutine leak in TWAMP sender — `cleanUpReceived` goroutines now exit on `Close()` instead of living until process shutdown
 - CLI
   - Enhance delete multicast group command to cascade into deleting AP entry (#2754)
+  - Added activation check for existing users before subscribing to new groups (#2782)
+- SDK
+  - Add read-only Go SDK (`revdist`) for the revenue distribution Solana program, with typed deserialization of all onchain accounts and Rust-generated fixture tests for cross-language compatibility
+  - Add `revdist-cli` tool for inspecting onchain revenue distribution state
+  - Add Python and TypeScript SDKs for serviceability, telemetry, and revdist programs with typed deserialization, RPC clients, PDA derivation, enum string types, and cross-language fixture tests
+  - Add shared `borsh-incremental` library (Go, Python, TypeScript) for cursor-based Borsh deserialization with backward-compatible trailing field defaults
+  - Add npm and PyPI publish workflows for serviceability and telemetry SDKs
 - Client
   - Cache network interface index/name lookups in liveness UDP service to fix high CPU usage caused by per-packet RTM_GETLINK netlink dumps
   - Add observability to BGP handleUpdate: log withdrawal/NLRI counts per batch and track processing duration via `doublezero_bgp_handle_update_duration_seconds` histogram

CLAUDE.md

@@ -14,6 +14,11 @@
 - Summary bullets should be concise, ordered by importance/significance
 - Focus on "what" and "why", not implementation details
 - Include a "Testing Verification" section
+- Don't mention table-stakes items like "compiles cleanly" in testing verification
+
+## Terminology
+
+- Use "onchain" (one word, no hyphen), never "on-chain"
 
 ## Rust Development
 
@@ -24,6 +29,13 @@
 
 Always run `make rust-fmt` before committing Rust changes.
 
+## TypeScript SDK Development
+
+- Use `bun` as the package manager and runtime for TypeScript SDKs
+- Build with `bun tsc` (not `npx tsc`)
+- Type-check with `bun tsc --noEmit`
+- Install dependencies with `bun install`
+
 ## Local Devnet / E2E Environment
 
 The local devnet runs in Docker containers with the naming convention `dz-local-*`.

Cargo.toml

@@ -12,7 +12,11 @@ members = [
     "smartcontract/programs/common",
 ]
 default-members = []
-exclude = []
+exclude = [
+    "sdk/revdist/testdata/fixtures/generate-fixtures",
+    "sdk/serviceability/testdata/fixtures/generate-fixtures",
+    "sdk/telemetry/testdata/fixtures/generate-fixtures",
+]
 resolver = "2"
 
 [workspace.package]