@swarm-tips/client 0.0.0 → 0.1.0

package/dist/vow/schema.js

@@ -0,0 +1,132 @@
+import { PublicKey } from "@solana/web3.js";
+/**
+ * Step 1 — schema check. Implements the well-formed-per-type table
+ * from `docs/specs/vow-v1.md` §4. Returns the first failure reason
+ * encountered, or null if the schema check passes.
+ *
+ * Pure — no RPC, no I/O.
+ */
+export function checkSchema(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return "schema_invalid:<root>";
+    }
+    const a = input;
+    if (a.version !== "vow/v1")
+        return "schema_invalid:version";
+    if (!isPubkey(a.program_id))
+        return "schema_invalid:program_id";
+    if (!isPubkey(a.account))
+        return "schema_invalid:account";
+    if (!isPubkey(a.client))
+        return "schema_invalid:client";
+    if (!isPubkey(a.agent))
+        return "schema_invalid:agent";
+    if (a.oracle_feed !== null && !isPubkey(a.oracle_feed)) {
+        return "schema_invalid:oracle_feed";
+    }
+    if (a.network !== "mainnet" && a.network !== "devnet") {
+        return "schema_invalid:network";
+    }
+    if (!isU8Number(a.platform))
+        return "schema_invalid:platform";
+    if (!isDecimalU64(a.task_id))
+        return "schema_invalid:task_id";
+    if (!isDecimalU64(a.composite_score))
+        return "schema_invalid:composite_score";
+    if (!isDecimalU64(a.score_max))
+        return "schema_invalid:score_max";
+    if (!isHex32(a.verification_hash))
+        return "schema_invalid:verification_hash";
+    if (!isHex32(a.content_hash))
+        return "schema_invalid:content_hash";
+    if (!isHex32(a.content_id_hash))
+        return "schema_invalid:content_id_hash";
+    if (!isEnumString(a.state))
+        return "schema_invalid:state";
+    if (!isEnumString(a.account_kind))
+        return "schema_invalid:account_kind";
+    if (!isRfc3339NoFraction(a.verified_at)) {
+        return "schema_invalid:verified_at";
+    }
+    if (a.extensions !== undefined && !isPlainObject(a.extensions)) {
+        return "schema_invalid:extensions";
+    }
+    if (a.verifier_instructions !== undefined &&
+        typeof a.verifier_instructions !== "string") {
+        return "schema_invalid:verifier_instructions";
+    }
+    return null;
+}
+/** Base58, decodes to exactly 32 bytes. */
+function isPubkey(v) {
+    if (typeof v !== "string" || v.length === 0)
+        return false;
+    try {
+        const bytes = new PublicKey(v).toBytes();
+        return bytes.length === 32;
+    }
+    catch {
+        return false;
+    }
+}
+/** JSON number in [0, 255]. */
+function isU8Number(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 0 && v <= 255;
+}
+/**
+ * Decimal string matching ^[0-9]+$, no leading zeros except the literal
+ * "0", fits in u64 (max 18446744073709551615 = 2^64 - 1).
+ */
+function isDecimalU64(v) {
+    if (typeof v !== "string")
+        return false;
+    if (!/^[0-9]+$/.test(v))
+        return false;
+    if (v.length > 1 && v.startsWith("0"))
+        return false;
+    // Compare as BigInt to avoid Number precision loss.
+    try {
+        const n = BigInt(v);
+        return n >= 0n && n <= U64_MAX;
+    }
+    catch {
+        return false;
+    }
+}
+const U64_MAX = (1n << 64n) - 1n;
+/** Lowercase hex of length 64 (= 32 bytes). */
+function isHex32(v) {
+    return typeof v === "string" && /^[0-9a-f]{64}$/.test(v);
+}
+/** Non-empty, no whitespace. Lowercase optional (verifiers tolerate). */
+function isEnumString(v) {
+    return typeof v === "string" && v.length > 0 && !/\s/.test(v);
+}
+/**
+ * RFC 3339 timestamp with NO fractional seconds. Either `Z` or `+00:00`
+ * UTC offset (per spec §3 row for `verified_at`). Verifiers MUST accept
+ * both forms.
+ */
+function isRfc3339NoFraction(v) {
+    if (typeof v !== "string")
+        return false;
+    // Anchor pattern: YYYY-MM-DDTHH:MM:SS{Z|+00:00}
+    // No fractional seconds (".123" is rejected).
+    const pattern = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(Z|\+00:00)$/;
+    if (!pattern.test(v))
+        return false;
+    // Round-trip via Date to confirm the components describe a real
+    // moment (rejects e.g. "2026-13-32T25:61:99Z").
+    const ms = Date.parse(v);
+    return !Number.isNaN(ms);
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Once `checkSchema` passes, narrow the input to `AasV1Attestation`.
+ * Pure runtime cast — no defensive checks (those already ran).
+ */
+export function asV1(a) {
+    return a;
+}

package/dist/vow/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * VOW v1 wire format. Mirrors the type table in
+ * `docs/specs/vow-v1.md` §3. All u64-typed on-chain values are
+ * decimal strings on the wire (per v1 §3 to avoid JS
+ * Number.MAX_SAFE_INTEGER truncation).
+ */
+export interface VowV1Attestation {
+    version: "vow/v1";
+    network: "mainnet" | "devnet";
+    program_id: string;
+    account: string;
+    account_kind: string;
+    task_id: string;
+    client: string;
+    agent: string;
+    state: string;
+    platform: number;
+    composite_score: string;
+    score_max: string;
+    verified_at: string;
+    verification_hash: string;
+    content_hash: string;
+    content_id_hash: string;
+    oracle_feed: string | null;
+    verifier_instructions?: string;
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Closed taxonomy of failure reasons, matching `docs/specs/vow-v1.md`
+ * §4 step-to-reason table. The string is the entire taxonomy — a
+ * verifier MUST return one of these strings (with the named field
+ * substituted into `field_mismatch:<field>` and `schema_invalid:<field>`).
+ */
+export type FailureReason = `schema_invalid:${string}` | "account_closed" | "owner_mismatch" | "discriminator_mismatch" | `field_mismatch:${string}` | "score_above_max" | "state_invalid";
+/**
+ * @deprecated Renamed to {@link VowV1Attestation} when the standard became VOW
+ * (Verifiable On-chain Work) on 2026-07-10. The wire format is `vow/v1`; this
+ * alias only keeps existing importers compiling and will be removed.
+ */
+export type AasV1Attestation = VowV1Attestation;
+export type Verdict = {
+    valid: true;
+    attestation: AasV1Attestation;
+    checked_at: string;
+    rpc_endpoint: string;
+} | {
+    valid: false;
+    attestation: AasV1Attestation;
+    checked_at: string;
+    rpc_endpoint: string;
+    failure_reason: FailureReason;
+};
+/**
+ * Decoded representation of the on-chain account body (sans the 8-byte
+ * Anchor discriminator). The reference shillbot decoder lives in
+ * `decoders/shillbot.ts`; protocols emit their own decoder for VOW v1
+ * conformance. The verifier compares each field below to the
+ * attestation's wire-format claim.
+ */
+export interface DecodedAccount {
+    task_id: bigint;
+    client: string;
+    agent: string;
+    state: number;
+    composite_score: bigint;
+    verified_at: bigint;
+    verification_hash: string;
+    content_hash: string;
+    content_id_hash: string;
+}
+/**
+ * Per-protocol pluggable decoder. The verifier calls this with the
+ * raw account bytes (after stripping the 8-byte Anchor discriminator)
+ * and the attestation's `account_kind` for routing.
+ */
+export type AccountDecoder = (data: Uint8Array, accountKind: string) => DecodedAccount;
+/**
+ * Per-protocol state-name resolver. The verifier calls this to map the
+ * decoded `state` u8 (e.g. 3) to the published lower-case enum name
+ * (e.g. "verified"). Protocols that publish their state enum under a
+ * different naming convention can pass a custom resolver.
+ *
+ * Returns `null` for unknown discriminants — the verifier treats that
+ * as `state_invalid`.
+ */
+export type StateResolver = (state: number, accountKind: string) => string | null;
+/**
+ * Per-protocol "states valid for attestation" lookup. Per spec §4 step
+ * 7, protocols publish which on-chain states are attestable. The
+ * verifier rejects an attestation whose `state` isn't in this list.
+ *
+ * Shillbot exports `["verified"]` (only Verified is attestable; finalize
+ * closes the on-chain account, see spec §6 capture window). Other
+ * protocols MAY allow multiple states.
+ */
+export type ValidStates = (accountKind: string) => readonly string[];
+/**
+ * The three pluggable hooks a non-Shillbot protocol passes when calling
+ * the verifier. For Shillbot, `sdk/client/src/vow/decoders/shillbot.ts`
+ * exports all three with the canonical Task layout, TaskState enum,
+ * and the `["verified"]`-only attestation policy.
+ */
+export interface ProtocolHandler {
+    decode: AccountDecoder;
+    resolveState: StateResolver;
+    validStates: ValidStates;
+}

package/dist/vow/types.js

@@ -0,0 +1 @@
+export {};

package/dist/vow/verify.d.ts

@@ -0,0 +1,23 @@
+import { Connection } from "@solana/web3.js";
+import type { AasV1Attestation, FailureReason, ProtocolHandler, Verdict } from "./types.js";
+/**
+ * Step-by-step verifier per `docs/specs/vow-v1.md` §4.
+ *
+ * Steps split:
+ *   - `verifyV1Schema` — pure (steps 1, 6).
+ *   - `verifyV1OnChain` — touches RPC (steps 2-5, 7).
+ *   - `verifyV1` (this) — full 7-step pipeline.
+ *
+ * Splitting lets unit tests cover the pure parts without an RPC.
+ */
+export declare function verifyV1(attestation: unknown, protocol: ProtocolHandler, rpc: Connection): Promise<Verdict>;
+/**
+ * Pure step 1 + step 6 of the protocol. Returns null on success or
+ * the first failure reason.
+ */
+export declare function verifyV1Schema(attestation: unknown): FailureReason | null;
+/**
+ * Steps 2-5 + 7 — touches RPC. Returns null on success or the first
+ * failure reason.
+ */
+export declare function verifyV1OnChain(a: AasV1Attestation, protocol: ProtocolHandler, rpc: Connection): Promise<FailureReason | null>;

package/dist/vow/verify.js

@@ -0,0 +1,145 @@
+import { PublicKey } from "@solana/web3.js";
+import { anchorDiscriminator, bytesEqual } from "./discriminator.js";
+import { asV1, checkSchema } from "./schema.js";
+/**
+ * Step-by-step verifier per `docs/specs/vow-v1.md` §4.
+ *
+ * Steps split:
+ *   - `verifyV1Schema` — pure (steps 1, 6).
+ *   - `verifyV1OnChain` — touches RPC (steps 2-5, 7).
+ *   - `verifyV1` (this) — full 7-step pipeline.
+ *
+ * Splitting lets unit tests cover the pure parts without an RPC.
+ */
+export async function verifyV1(attestation, protocol, rpc) {
+    const checkedAt = nowRfc3339();
+    const rpcEndpoint = rpc.rpcEndpoint;
+    const schemaFail = verifyV1Schema(attestation);
+    if (schemaFail) {
+        return {
+            valid: false,
+            attestation: attestation,
+            checked_at: checkedAt,
+            rpc_endpoint: rpcEndpoint,
+            failure_reason: schemaFail,
+        };
+    }
+    const a = asV1(attestation);
+    const onChainFail = await verifyV1OnChain(a, protocol, rpc);
+    if (onChainFail) {
+        return {
+            valid: false,
+            attestation: a,
+            checked_at: checkedAt,
+            rpc_endpoint: rpcEndpoint,
+            failure_reason: onChainFail,
+        };
+    }
+    return {
+        valid: true,
+        attestation: a,
+        checked_at: checkedAt,
+        rpc_endpoint: rpcEndpoint,
+    };
+}
+/**
+ * Pure step 1 + step 6 of the protocol. Returns null on success or
+ * the first failure reason.
+ */
+export function verifyV1Schema(attestation) {
+    const schemaFail = checkSchema(attestation);
+    if (schemaFail)
+        return schemaFail;
+    const a = asV1(attestation);
+    // Step 6 — domain bound. Both are decimal-string u64 (passed step 1).
+    if (BigInt(a.composite_score) > BigInt(a.score_max)) {
+        return "score_above_max";
+    }
+    return null;
+}
+/**
+ * Steps 2-5 + 7 — touches RPC. Returns null on success or the first
+ * failure reason.
+ */
+export async function verifyV1OnChain(a, protocol, rpc) {
+    // Step 2 — fetch the on-chain account.
+    const accountInfo = await rpc.getAccountInfo(new PublicKey(a.account));
+    if (accountInfo === null) {
+        return "account_closed";
+    }
+    const data = new Uint8Array(accountInfo.data);
+    // Step 3 — owner check.
+    if (accountInfo.owner.toBase58() !== a.program_id) {
+        return "owner_mismatch";
+    }
+    // Step 4 — Anchor discriminator check.
+    if (data.length < 8) {
+        return "discriminator_mismatch";
+    }
+    const expectedDisc = anchorDiscriminator(a.account_kind);
+    if (!bytesEqual(expectedDisc, data.slice(0, 8))) {
+        return "discriminator_mismatch";
+    }
+    // Step 5 — field equality. Decoder strips the 8-byte discriminator.
+    // The decoders THROW on a short/malformed body (shillbot rejects < 286 bytes,
+    // extension likewise). Letting that escape turned "this account does not
+    // verify" into an exception the caller had to catch, so a truncated or
+    // wrong-kind account crashed the verifier instead of returning a verdict.
+    // A body we cannot decode IS a schema failure — report it as one.
+    let decoded;
+    try {
+        decoded = protocol.decode(data.slice(8), a.account_kind);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return `schema_invalid:${msg}`;
+    }
+    if (decoded.task_id.toString() !== a.task_id) {
+        return "field_mismatch:task_id";
+    }
+    if (decoded.client !== a.client) {
+        return "field_mismatch:client";
+    }
+    if (decoded.agent !== a.agent) {
+        return "field_mismatch:agent";
+    }
+    if (decoded.composite_score.toString() !== a.composite_score) {
+        return "field_mismatch:composite_score";
+    }
+    if (decoded.verification_hash !== a.verification_hash) {
+        return "field_mismatch:verification_hash";
+    }
+    if (decoded.content_hash !== a.content_hash) {
+        return "field_mismatch:content_hash";
+    }
+    if (decoded.content_id_hash !== a.content_id_hash) {
+        return "field_mismatch:content_id_hash";
+    }
+    // verified_at: chain stores i64 unix seconds; wire is RFC 3339 with
+    // no fractional seconds. Convert and compare with ±1 second
+    // tolerance (per spec §4 step 5).
+    const wireSeconds = Math.floor(Date.parse(a.verified_at) / 1000);
+    const chainSeconds = Number(decoded.verified_at);
+    if (Math.abs(wireSeconds - chainSeconds) > 1) {
+        return "field_mismatch:verified_at";
+    }
+    // Step 5 (state) — map decoded u8 to the protocol's published name.
+    const resolved = protocol.resolveState(decoded.state, a.account_kind);
+    if (resolved === null || resolved !== a.state) {
+        return "field_mismatch:state";
+    }
+    // Step 7 — state validity. Spec §4 step 7 says protocols publish
+    // which on-chain states are "valid for attestation"; the verifier
+    // delegates to the protocol handler's `validStates` to avoid
+    // hardcoding any one protocol's policy. Shillbot returns
+    // `["verified"]`; other protocols can return larger sets without
+    // forking this verifier.
+    const valid = protocol.validStates(a.account_kind);
+    if (!valid.includes(a.state)) {
+        return "state_invalid";
+    }
+    return null;
+}
+function nowRfc3339() {
+    return new Date().toISOString().replace(/\.\d+Z$/, "Z");
+}

package/package.json

@@ -1,17 +1,103 @@
 {
   "name": "@swarm-tips/client",
-  "version": "0.0.0",
-  "description": "Bootstrap release for the unified Swarm Tips JavaScript client",
+  "version": "0.1.0",
+  "description": "Typed browser and Node.js clients for Swarm Tips, Shillbot, and Coordination Game",
   "type": "module",
-  "main": "index.js",
-  "files": ["index.js", "README.md"],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./shillbot": {
+      "types": "./dist/shillbot/index.d.ts",
+      "import": "./dist/shillbot/index.js"
+    },
+    "./coordination-game": {
+      "types": "./dist/coordination-game/index.d.ts",
+      "import": "./dist/coordination-game/index.js"
+    },
+    "./evm": {
+      "types": "./dist/evm/index.d.ts",
+      "import": "./dist/evm/index.js"
+    },
+    "./evm/testing": {
+      "types": "./dist/evm/testing.d.ts",
+      "import": "./dist/evm/testing.js"
+    },
+    "./inbox": {
+      "types": "./dist/inbox/index.d.ts",
+      "import": "./dist/inbox/index.js"
+    },
+    "./vow": {
+      "types": "./dist/vow/index.d.ts",
+      "import": "./dist/vow/index.js"
+    },
+    "./idl/shillbot": "./dist/contracts/idl/shillbot.json",
+    "./idl/coordination-game": "./dist/contracts/idl/coordination_game.json",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "swarm-tx": "dist/cli/swarm-tx.js",
+    "vow-verify": "dist/cli/vow-verify.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SBOM.spdx.json"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/corsur/swarm-tips.git",
     "directory": "sdk/client"
   },
+  "homepage": "https://github.com/corsur/swarm-tips/tree/main/sdk/client#readme",
+  "bugs": "https://github.com/corsur/swarm-tips/issues",
   "license": "MIT",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@coral-xyz/anchor": "^0.32.1",
+    "@solana/web3.js": "^1.98.4",
+    "@switchboard-xyz/common": "^5.7.0",
+    "bs58": "^6.0.0",
+    "buffer": "^6.0.3",
+    "js-sha256": "^0.11.0"
+  },
+  "peerDependencies": {
+    "viem": "^2.52.2",
+    "wagmi": "^2.19.5"
+  },
+  "peerDependenciesMeta": {
+    "viem": {
+      "optional": true
+    },
+    "wagmi": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "esbuild": "^0.25.9",
+    "typescript": "^5.7.3",
+    "viem": "^2.52.2",
+    "vitest": "^2.1.9",
+    "wagmi": "^2.19.5"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint": "tsc --noEmit -p tsconfig.json",
+    "check:generated": "node scripts/sync-generated.mjs --check",
+    "sync:generated": "node scripts/sync-generated.mjs",
+    "sbom": "node scripts/generate-sbom.mjs",
+    "verify:packed": "node scripts/verify-packed.mjs"
   }
-}
+}

package/index.js

@@ -1 +0,0 @@
-export const CLIENT_VERSION = "0.0.0";