@circuit-llm/onchain 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Circuit LLM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# @circuit-llm/onchain
+
+> Read Circuit's on-chain state over **pure JSON-RPC** — StakePoint stake verification, CIRC balances, and the mesh registry — with no `@solana/web3.js` dependency.
+
+Part of the **[Circuit SDK](https://github.com/Circuit-LLM/circuit-sdk)**. [Contribute a node →](https://github.com/Circuit-LLM/circuit-sdk/blob/main/docs/contributing-a-node.md)
+
+## Install
+
+```bash
+npm install @circuit-llm/onchain
+```
+
+## Usage
+
+```ts
+import { verifyStake, circBalance } from '@circuit-llm/onchain';
+
+const staked = await verifyStake(wallet, pool, 100_000, { rpcUrl });   // ≥ 100k CIRC staked?
+const circ = await circBalance(address, { rpcUrl });
+```
+
+Also reads the on-chain mesh registry (`getMeshConfig`, `getNode`, `getNodes`) and stake positions (`getStakePositions`). Thin, dependency-light, and browser-friendly.

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+interface RpcOptions {
+    rpcUrl: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+declare class RpcError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+declare function rpcCall<T = unknown>(opts: RpcOptions, method: string, params: unknown[]): Promise<T>;
+
+declare const STAKEPOINT_PROGRAM_ID = "gLHaGJsZ6G7AXZxoDL9EsSWkRbKAWhFHi73gVfNXuzK";
+interface StakePosition {
+    positionAddress: string;
+    stakedRaw: bigint;
+    lockUntil: number;
+    lockActive: boolean;
+}
+/** Fetch all ACTIVE (non-zero) staker positions for a wallet in a pool. A wallet can
+ *  hold multiple positions; they're summed by verifyStake. */
+declare function getStakePositions(wallet: string, pool: string, opts: RpcOptions & {
+    now?: () => number;
+}): Promise<StakePosition[]>;
+interface StakeResult {
+    eligible: boolean;
+    stakedAmount: number;
+    stakedRaw: string;
+    positionCount: number;
+    lockUntil: number | null;
+    lockActive: boolean;
+    positions: Array<{
+        address: string;
+        stakedAmount: number;
+        stakedRaw: string;
+        lockUntil: number;
+        lockActive: boolean;
+    }>;
+}
+/** Verify a wallet has >= minAmount (human units) staked, summed across all positions.
+ *  Eligibility is exact (BigInt); the float amounts are for display. */
+declare function verifyStake(wallet: string, pool: string, minAmount: number, opts: RpcOptions & {
+    decimals?: number;
+    now?: () => number;
+}): Promise<StakeResult>;
+
+/** Total CIRC (human units) held by a wallet, summed across its token accounts. */
+declare function circBalance(wallet: string, opts: RpcOptions & {
+    mint?: string;
+}): Promise<number>;
+
+declare const MESH_REGISTRY_PROGRAM_ID = "BC2sxffu498cB8gUp3P5V5HuBLDsx9XCtJdEmnnGUvfe";
+type NodeRole = 'orchestrator' | 'holder';
+type TrustLevel = 'probation' | 'trusted';
+interface MeshNode {
+    address: string;
+    node: string;
+    role: NodeRole;
+    trust: TrustLevel;
+    banned: boolean;
+    payoutWallet: string;
+    stakePool: string;
+    joinedAt: number;
+    updatedAt: number;
+}
+interface SlotRange {
+    start: number;
+    end: number;
+}
+interface MeshConfig {
+    address: string;
+    authority: string;
+    auditor: string;
+    modelFp: string;
+    numLayers: number;
+    replication: number;
+    slots: SlotRange[];
+    version: number;
+    bump: number;
+}
+/** Decode a 124-byte Node account (pure). Throws if the discriminator/size is wrong. */
+declare function decodeNode(address: string, data: Buffer): MeshNode;
+/** Decode the singleton MeshConfig account (pure). Variable length (String + Vec), so read sequentially. */
+declare function decodeMeshConfig(address: string, data: Buffer): MeshConfig;
+/** All registered node membership records (each node's role/trust/ban/payout/stake-pool). */
+declare function getNodes(opts: RpcOptions): Promise<MeshNode[]>;
+/** A single node's membership record by its ed25519 identity. Looks up by the stored identity field
+ *  (offset 8) so no PDA derivation (and thus no @solana/web3.js) is needed. Null if not registered. */
+declare function getNode(nodePubkey: string, opts: RpcOptions): Promise<MeshNode | null>;
+/** The singleton topology contract (authority, auditor, model, layer slots, version). Null if the mesh
+ *  config has not been initialized on this cluster. */
+declare function getMeshConfig(opts: RpcOptions): Promise<MeshConfig | null>;
+
+declare function base58(buf: Uint8Array | Buffer): string;
+
+export { MESH_REGISTRY_PROGRAM_ID, type MeshConfig, type MeshNode, type NodeRole, RpcError, type RpcOptions, STAKEPOINT_PROGRAM_ID, type SlotRange, type StakePosition, type StakeResult, type TrustLevel, base58, circBalance, decodeMeshConfig, decodeNode, getMeshConfig, getNode, getNodes, getStakePositions, rpcCall, verifyStake };

package/dist/index.js

@@ -0,0 +1,235 @@
+// src/rpc.ts
+var RpcError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(`RPC ${code}: ${message}`);
+    this.name = "RpcError";
+    this.code = code;
+  }
+};
+var _id = 0;
+async function rpcCall(opts, method, params) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const res = await fetchImpl(opts.rpcUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: ++_id, method, params }),
+    signal: AbortSignal.timeout(opts.timeoutMs ?? 15e3)
+  });
+  if (!res.ok) throw new RpcError(res.status, `HTTP ${res.status}`);
+  const j = await res.json();
+  if (j.error) throw new RpcError(j.error.code, j.error.message);
+  return j.result;
+}
+
+// src/stakepoint.ts
+var STAKEPOINT_PROGRAM_ID = "gLHaGJsZ6G7AXZxoDL9EsSWkRbKAWhFHi73gVfNXuzK";
+var STAKER_ACCOUNT_SIZE = 185;
+var DISCRIMINATOR = "96c5b01d37847095";
+var OFFSET_WALLET = 8;
+var OFFSET_POOL = 40;
+var OFFSET_STAKED = 72;
+var OFFSET_LOCK_UNTIL = 80;
+async function getStakePositions(wallet, pool, opts) {
+  const accounts = await rpcCall(opts, "getProgramAccounts", [
+    STAKEPOINT_PROGRAM_ID,
+    {
+      encoding: "base64",
+      filters: [
+        { dataSize: STAKER_ACCOUNT_SIZE },
+        { memcmp: { offset: OFFSET_WALLET, bytes: wallet } },
+        { memcmp: { offset: OFFSET_POOL, bytes: pool } }
+      ]
+    }
+  ]);
+  const nowSec = Math.floor((opts.now ?? Date.now)() / 1e3);
+  const positions = [];
+  for (const acc of accounts ?? []) {
+    const buf = Buffer.from(acc.account.data[0], "base64");
+    if (buf.length < STAKER_ACCOUNT_SIZE) continue;
+    if (buf.subarray(0, 8).toString("hex") !== DISCRIMINATOR) continue;
+    const stakedRaw = buf.readBigUInt64LE(OFFSET_STAKED);
+    if (stakedRaw === 0n) continue;
+    const lockUntil = Number(buf.readBigUInt64LE(OFFSET_LOCK_UNTIL));
+    positions.push({
+      positionAddress: acc.pubkey,
+      stakedRaw,
+      lockUntil,
+      lockActive: lockUntil > 0 && lockUntil > nowSec
+    });
+  }
+  return positions;
+}
+async function verifyStake(wallet, pool, minAmount, opts) {
+  const positions = await getStakePositions(wallet, pool, opts);
+  const dec = opts.decimals ?? 6;
+  const div = 10 ** dec;
+  if (!positions.length) {
+    return { eligible: false, stakedAmount: 0, stakedRaw: "0", positionCount: 0, lockUntil: null, lockActive: false, positions: [] };
+  }
+  const totalRaw = positions.reduce((s, p) => s + p.stakedRaw, 0n);
+  const minRaw = BigInt(Math.round((minAmount ?? 0) * div));
+  const activeLocks = positions.filter((p) => p.lockActive);
+  return {
+    eligible: totalRaw >= minRaw,
+    stakedAmount: Number(totalRaw) / div,
+    stakedRaw: totalRaw.toString(),
+    positionCount: positions.length,
+    lockUntil: activeLocks.length ? Math.max(...activeLocks.map((p) => p.lockUntil)) : null,
+    lockActive: activeLocks.length > 0,
+    positions: positions.map((p) => ({
+      address: p.positionAddress,
+      stakedAmount: Number(p.stakedRaw) / div,
+      stakedRaw: p.stakedRaw.toString(),
+      lockUntil: p.lockUntil,
+      lockActive: p.lockActive
+    }))
+  };
+}
+
+// src/balance.ts
+import { CIRC_MINT } from "@circuit-llm/core";
+async function circBalance(wallet, opts) {
+  const mint = opts.mint ?? CIRC_MINT;
+  const r = await rpcCall(opts, "getTokenAccountsByOwner", [
+    wallet,
+    { mint },
+    { encoding: "jsonParsed" }
+  ]);
+  return (r.value ?? []).reduce(
+    (sum, a) => sum + (a.account.data.parsed.info.tokenAmount.uiAmount ?? 0),
+    0
+  );
+}
+
+// src/bs58.ts
+var B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function base58(buf) {
+  const bytes = Uint8Array.from(buf);
+  let zeros = 0;
+  while (zeros < bytes.length && bytes[zeros] === 0) zeros++;
+  const digits = [];
+  for (let i = zeros; i < bytes.length; i++) {
+    let carry = bytes[i];
+    for (let j = 0; j < digits.length; j++) {
+      carry += digits[j] << 8;
+      digits[j] = carry % 58;
+      carry = carry / 58 | 0;
+    }
+    while (carry) {
+      digits.push(carry % 58);
+      carry = carry / 58 | 0;
+    }
+  }
+  let out = "1".repeat(zeros);
+  for (let k = digits.length - 1; k >= 0; k--) out += B58[digits[k]];
+  return out;
+}
+
+// src/mesh-registry.ts
+var MESH_REGISTRY_PROGRAM_ID = "BC2sxffu498cB8gUp3P5V5HuBLDsx9XCtJdEmnnGUvfe";
+var NODE_DISCRIMINATOR = "d0350103317ab431";
+var NODE_DISCRIMINATOR_B58 = "bpsQsGpQe1N";
+var MESH_CONFIG_DISCRIMINATOR = "eff3dba40bea7cf5";
+var MESH_CONFIG_DISCRIMINATOR_B58 = "h8qkU9oSVXr";
+var NODE_ACCOUNT_SIZE = 124;
+var ROLES = ["orchestrator", "holder"];
+var TRUST = ["probation", "trusted"];
+function decodeNode(address, data) {
+  if (data.length < NODE_ACCOUNT_SIZE) throw new Error(`Node account too small: ${data.length} < ${NODE_ACCOUNT_SIZE}`);
+  if (data.subarray(0, 8).toString("hex") !== NODE_DISCRIMINATOR) throw new Error("not a Node account (bad discriminator)");
+  const roleByte = data.readUInt8(40);
+  const trustByte = data.readUInt8(41);
+  const role = ROLES[roleByte];
+  const trust = TRUST[trustByte];
+  if (!role) throw new Error(`unknown node role ${roleByte}`);
+  if (!trust) throw new Error(`unknown trust level ${trustByte}`);
+  return {
+    address,
+    node: base58(data.subarray(8, 40)),
+    role,
+    trust,
+    banned: data.readUInt8(42) !== 0,
+    // canonical Borsh bool: any non-zero byte is true
+    payoutWallet: base58(data.subarray(43, 75)),
+    stakePool: base58(data.subarray(75, 107)),
+    joinedAt: Number(data.readBigInt64LE(107)),
+    updatedAt: Number(data.readBigInt64LE(115))
+  };
+}
+function decodeMeshConfig(address, data) {
+  if (data.subarray(0, 8).toString("hex") !== MESH_CONFIG_DISCRIMINATOR) {
+    throw new Error("not a MeshConfig account (bad discriminator)");
+  }
+  let o = 8;
+  const authority = base58(data.subarray(o, o + 32));
+  o += 32;
+  const auditor = base58(data.subarray(o, o + 32));
+  o += 32;
+  const fpLen = data.readUInt32LE(o);
+  o += 4;
+  const modelFp = data.subarray(o, o + fpLen).toString("utf8");
+  o += fpLen;
+  const numLayers = data.readUInt16LE(o);
+  o += 2;
+  const replication = data.readUInt8(o);
+  o += 1;
+  const slotCount = data.readUInt32LE(o);
+  o += 4;
+  const slots = [];
+  for (let i = 0; i < slotCount; i++) {
+    slots.push({ start: data.readUInt16LE(o), end: data.readUInt16LE(o + 2) });
+    o += 4;
+  }
+  const version = data.readUInt32LE(o);
+  o += 4;
+  const bump = data.readUInt8(o);
+  return { address, authority, auditor, modelFp, numLayers, replication, slots, version, bump };
+}
+async function getNodes(opts) {
+  const accounts = await rpcCall(opts, "getProgramAccounts", [
+    MESH_REGISTRY_PROGRAM_ID,
+    { encoding: "base64", filters: [{ dataSize: NODE_ACCOUNT_SIZE }, { memcmp: { offset: 0, bytes: NODE_DISCRIMINATOR_B58 } }] }
+  ]);
+  const out = [];
+  for (const acc of accounts ?? []) {
+    try {
+      out.push(decodeNode(acc.pubkey, Buffer.from(acc.account.data[0], "base64")));
+    } catch {
+    }
+  }
+  return out;
+}
+async function getNode(nodePubkey, opts) {
+  const accounts = await rpcCall(opts, "getProgramAccounts", [
+    MESH_REGISTRY_PROGRAM_ID,
+    { encoding: "base64", filters: [{ dataSize: NODE_ACCOUNT_SIZE }, { memcmp: { offset: 8, bytes: nodePubkey } }] }
+  ]);
+  const acc = (accounts ?? [])[0];
+  if (!acc) return null;
+  return decodeNode(acc.pubkey, Buffer.from(acc.account.data[0], "base64"));
+}
+async function getMeshConfig(opts) {
+  const accounts = await rpcCall(opts, "getProgramAccounts", [
+    MESH_REGISTRY_PROGRAM_ID,
+    { encoding: "base64", filters: [{ memcmp: { offset: 0, bytes: MESH_CONFIG_DISCRIMINATOR_B58 } }] }
+  ]);
+  const acc = (accounts ?? [])[0];
+  if (!acc) return null;
+  return decodeMeshConfig(acc.pubkey, Buffer.from(acc.account.data[0], "base64"));
+}
+export {
+  MESH_REGISTRY_PROGRAM_ID,
+  RpcError,
+  STAKEPOINT_PROGRAM_ID,
+  base58,
+  circBalance,
+  decodeMeshConfig,
+  decodeNode,
+  getMeshConfig,
+  getNode,
+  getNodes,
+  getStakePositions,
+  rpcCall,
+  verifyStake
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@circuit-llm/onchain",
+  "version": "0.2.1",
+  "description": "Circuit SDK on-chain reads — StakePoint stake verification + CIRC balances via pure JSON-RPC (no @solana/web3.js).",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --conditions=development --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "build": "tsup src/index.ts --format esm --dts --clean --out-dir dist",
+    "prepack": "tsup src/index.ts --format esm --dts --clean --out-dir dist"
+  },
+  "dependencies": {
+    "@circuit-llm/core": "0.2.1"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Circuit-LLM/circuit-sdk.git",
+    "directory": "packages/onchain"
+  },
+  "homepage": "https://github.com/Circuit-LLM/circuit-sdk/tree/main/packages/onchain#readme",
+  "bugs": {
+    "url": "https://github.com/Circuit-LLM/circuit-sdk/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}