@jinn-network/sdk 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @jinn-network/sdk
+
+Stable SDK surface for Jinn SolverNets, Harnesses, plugins, and typed
+payloads.
+
+Runtime internals live in `@jinn-network/client`. The SDK builds, validates,
+describes, and prepares; the client runs, stores, posts, claims, signs,
+submits, and watches.
+
+## Install
+
+```bash
+npm install @jinn-network/sdk
+```
+
+## Harness authoring
+
+```ts
+import type {
+  Harness,
+  ExternalHarnessEnv,
+  HarnessContext,
+  Solution,
+} from '@jinn-network/sdk/harness';
+import { buildSolutionOutput } from '@jinn-network/sdk/solvernets/prediction-v1';
+
+export default function createHarness(env: ExternalHarnessEnv): Harness {
+  return {
+    name: env.implName,
+    version: env.implVersion,
+    supports: ({ solverType, role }) =>
+      solverType === 'prediction.v1' && role !== 'evaluation',
+    async run(ctx: HarnessContext): Promise<Solution> {
+      return buildSolutionOutput({
+        solverType: 'prediction.v1',
+        venueName: 'polymarket',
+        payload: {
+          probabilityYes: '0.50',
+          submittedAt: new Date().toISOString(),
+          format: 'decimal',
+          modelId: 'example-harness',
+        },
+      });
+    },
+  };
+}
+```
+
+## Public subpaths
+
+- `@jinn-network/sdk/harness` — Harness interfaces, context, capability
+  handles, and signed Harness manifest types.
+- `@jinn-network/sdk/solvernets` — SolverNet contract registry, validation, and
+  generic typed output builders.
+- `@jinn-network/sdk/solvernets/prediction-v1` — first-party Prediction v1
+  schemas, payload types, validation, and output helpers.
+- `@jinn-network/sdk/plugins` — SolverPlugin manifest types and validation
+  helpers for normal AI tooling plugins.
+
+The daemon still performs final runtime validation, envelope assembly, signing,
+storage, and submission.

package/dist/capabilities.d.ts

@@ -0,0 +1,52 @@
+import type { Address, Hex } from './types.js';
+export interface SignTypedDataArgs {
+    domain: {
+        name?: string;
+        version?: string;
+        chainId?: number;
+        verifyingContract?: Address;
+    };
+    types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>;
+    primaryType: string;
+    message: Record<string, unknown>;
+}
+/**
+ * The runtime gate on `ScopedSigner.signTypedData` is enforced
+ * daemon-side: the daemon constructs the signer with an allow-list
+ * derived from the manifest's `capabilities.signer.typedDataDomains`
+ * (see {@link TypedDataAllowEntry} on `manifest.ts`) and refuses any
+ * domain not on the list. An impl that ships no `typedDataDomains`
+ * entry cannot call `signTypedData` at all (default-deny). The
+ * `ScopedSigner` interface itself is unchanged — the gate lives in
+ * the construction args, not the contract surface.
+ */
+export interface SendAllowedCallArgs {
+    to: Address;
+    data: Hex;
+    value?: bigint;
+}
+export interface ScopedSigner {
+    readonly address: Address;
+    signTypedData(args: SignTypedDataArgs): Promise<Hex>;
+    sendAllowedCall(call: SendAllowedCallArgs): Promise<Hex>;
+}
+export interface ScopedRpc {
+    readContract(args: {
+        address: Address;
+        abi: readonly unknown[];
+        functionName: string;
+        args?: readonly unknown[];
+    }): Promise<unknown>;
+    getBlockNumber(): Promise<bigint>;
+    getBalance(args: {
+        address: Address;
+    }): Promise<bigint>;
+    getCode(args: {
+        address: Address;
+    }): Promise<Hex | undefined>;
+    getChainId(): Promise<number>;
+}
+export type ScopedSecrets = Readonly<Record<string, string>>;

package/dist/capabilities.js

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

package/dist/contracts.d.ts

@@ -0,0 +1,107 @@
+import type { z } from 'zod';
+import type { OutputArtifact, RationaleEntry, Solution } from './types.js';
+import { type PredictionV1Task } from './prediction-v1.js';
+import { type PredictionV1RestorationPayload, type PredictionV1VerdictPayload } from './payloads/prediction-v1.js';
+export type SolverNetContractRole = 'creator' | 'solver' | 'evaluator';
+export type PayloadKind = 'task' | 'solution' | 'verdict';
+export type SupportedSolverType = 'prediction.v1';
+export interface CredentialRequirement {
+    id: string;
+    kind: 'public-api' | 'client-owned' | 'operator-credential';
+    required: boolean;
+    description: string;
+}
+export interface SolverNetEvaluationFunction {
+    id: string;
+    deterministic: boolean;
+    inputs: readonly string[];
+    output: string;
+    implementation: string;
+}
+export interface SolverNetAggregationFunction {
+    id: string;
+    deterministic: boolean;
+    inputs: readonly string[];
+    output: string;
+    windowDays?: number;
+}
+export interface SolverNetClaimPolicyDefaults {
+    kind: string;
+    maxClaims: number;
+    maxClaimsPerSolver: number;
+    claimWindow: string;
+    selection: string;
+    economics: string;
+}
+export interface SolverNetContract {
+    name: string;
+    solverType: SupportedSolverType;
+    schemas: {
+        task: z.ZodTypeAny;
+        solution: z.ZodTypeAny;
+        verdict: z.ZodTypeAny;
+    };
+    claimPolicyDefaults: SolverNetClaimPolicyDefaults;
+    credentialRequirements: Record<SolverNetContractRole, CredentialRequirement[]>;
+    evaluationFunction: SolverNetEvaluationFunction;
+    aggregationFunction: SolverNetAggregationFunction;
+    referencePlugins: string[];
+}
+export type SolverNetContractMap = Record<SupportedSolverType, SolverNetContract>;
+export declare const PREDICTION_V1_SOLVER_NET_CONTRACT: SolverNetContract;
+export declare const SOLVER_NET_CONTRACTS: SolverNetContractMap;
+export declare function getSolverNetContract(solverType: string): SolverNetContract | undefined;
+export interface PayloadValidationIssue {
+    path: string;
+    message: string;
+}
+export interface PayloadValidationFailure {
+    ok: false;
+    error: {
+        code: 'unsupported_solver_type' | 'invalid_payload';
+        message: string;
+        issues: PayloadValidationIssue[];
+    };
+}
+export interface PayloadValidationSuccess<T> {
+    ok: true;
+    value: T;
+}
+export type PayloadValidationResult<T> = PayloadValidationSuccess<T> | PayloadValidationFailure;
+export declare class PayloadValidationException extends Error {
+    readonly code: 'unsupported_solver_type' | 'invalid_payload';
+    readonly issues: PayloadValidationIssue[];
+    constructor(code: 'unsupported_solver_type' | 'invalid_payload', message: string, issues?: PayloadValidationIssue[]);
+}
+export declare function validateTask(solverType: 'prediction.v1', task: unknown): PayloadValidationResult<PredictionV1Task>;
+export declare function validateTask(solverType: string, task: unknown): PayloadValidationResult<unknown>;
+export declare function assertTask(solverType: 'prediction.v1', task: unknown): PredictionV1Task;
+export declare function assertTask(solverType: string, task: unknown): unknown;
+export declare function validateSolutionPayload(solverType: 'prediction.v1', payload: unknown): PayloadValidationResult<PredictionV1RestorationPayload>;
+export declare function validateSolutionPayload(solverType: string, payload: unknown): PayloadValidationResult<Record<string, unknown>>;
+export declare function assertSolutionPayload(solverType: 'prediction.v1', payload: unknown): PredictionV1RestorationPayload;
+export declare function assertSolutionPayload(solverType: string, payload: unknown): Record<string, unknown>;
+export declare function validateVerdictPayload(solverType: 'prediction.v1', payload: unknown): PayloadValidationResult<PredictionV1VerdictPayload>;
+export declare function validateVerdictPayload(solverType: string, payload: unknown): PayloadValidationResult<Record<string, unknown>>;
+export declare function assertVerdictPayload(solverType: 'prediction.v1', payload: unknown): PredictionV1VerdictPayload;
+export declare function assertVerdictPayload(solverType: string, payload: unknown): Record<string, unknown>;
+export interface BuildSolutionOutputArgs {
+    solverType: string;
+    venueName: string;
+    payload: Record<string, unknown>;
+    gating?: Record<string, unknown>;
+    informational?: Record<string, unknown>;
+    artifacts?: OutputArtifact[];
+    rationale?: RationaleEntry[];
+}
+export declare function buildSolutionOutput(args: BuildSolutionOutputArgs): Solution;
+export interface BuildVerdictOutputArgs {
+    solverType: string;
+    venueName?: string;
+    payload: Record<string, unknown>;
+    gating?: Record<string, unknown>;
+    informational?: Record<string, unknown>;
+    artifacts?: OutputArtifact[];
+    rationale?: RationaleEntry[];
+}
+export declare function buildVerdictOutput(args: BuildVerdictOutputArgs): Solution;

package/dist/contracts.js

@@ -0,0 +1,149 @@
+import { PredictionV1TaskSchema } from './prediction-v1.js';
+import { PredictionV1RestorationPayloadSchema, PredictionV1VerdictPayloadSchema, } from './payloads/prediction-v1.js';
+export const PREDICTION_V1_SOLVER_NET_CONTRACT = {
+    name: 'Prediction',
+    solverType: 'prediction.v1',
+    schemas: {
+        task: PredictionV1TaskSchema,
+        solution: PredictionV1RestorationPayloadSchema,
+        verdict: PredictionV1VerdictPayloadSchema,
+    },
+    claimPolicyDefaults: {
+        kind: 'parallel',
+        maxClaims: 25,
+        maxClaimsPerSolver: 1,
+        claimWindow: 'task-window',
+        selection: 'all-valid-solutions-scored',
+        economics: 'testnet-flat',
+    },
+    credentialRequirements: {
+        creator: [
+            {
+                id: 'polymarket.public.market-data.read',
+                kind: 'public-api',
+                required: true,
+                description: 'Read public Polymarket market metadata and orderbook snapshots for Task creation.',
+            },
+        ],
+        solver: [],
+        evaluator: [
+            {
+                id: 'polymarket.public.resolution.read',
+                kind: 'public-api',
+                required: true,
+                description: 'Read public Polymarket/UMA final market state for resolution mapping.',
+            },
+        ],
+    },
+    evaluationFunction: {
+        id: 'prediction.brier-loss.v1',
+        deterministic: true,
+        inputs: ['prediction.v1 Task', 'prediction.v1 Solution', 'Polymarket/UMA resolution'],
+        output: 'prediction.v1 Verdict',
+        implementation: 'client/src/harnesses/impls/prediction-v1-evaluator',
+    },
+    aggregationFunction: {
+        id: 'prediction.trailing-mean-brier-spread.v1',
+        deterministic: true,
+        inputs: ['SCORED prediction.v1 Verdicts'],
+        output: 'trailing mean brierSpread',
+        windowDays: 84,
+    },
+    referencePlugins: ['bundled:jinn-prediction-plugin'],
+};
+export const SOLVER_NET_CONTRACTS = {
+    'prediction.v1': PREDICTION_V1_SOLVER_NET_CONTRACT,
+};
+export function getSolverNetContract(solverType) {
+    return SOLVER_NET_CONTRACTS[solverType];
+}
+export class PayloadValidationException extends Error {
+    code;
+    issues;
+    constructor(code, message, issues = []) {
+        super(message);
+        this.name = 'PayloadValidationException';
+        this.code = code;
+        this.issues = issues;
+    }
+}
+function issuesFrom(error) {
+    return error.issues.map((issue) => ({
+        path: issue.path.length > 0 ? issue.path.join('.') : '<root>',
+        message: issue.message,
+    }));
+}
+function getSchema(solverType, kind) {
+    return getSolverNetContract(solverType)?.schemas[kind];
+}
+function validateWithSchema(solverType, kind, value) {
+    const schema = getSchema(solverType, kind);
+    if (!schema) {
+        return {
+            ok: false,
+            error: {
+                code: 'unsupported_solver_type',
+                message: `Unsupported SolverType for ${kind} validation: ${solverType}`,
+                issues: [],
+            },
+        };
+    }
+    const parsed = schema.safeParse(value);
+    if (!parsed.success) {
+        const issues = issuesFrom(parsed.error);
+        return {
+            ok: false,
+            error: {
+                code: 'invalid_payload',
+                message: `${solverType} ${kind} failed validation: ${issues.map((issue) => `${issue.path}: ${issue.message}`).join('; ')}`,
+                issues,
+            },
+        };
+    }
+    return { ok: true, value: parsed.data };
+}
+function assertValid(result) {
+    if (result.ok)
+        return result.value;
+    throw new PayloadValidationException(result.error.code, result.error.message, result.error.issues);
+}
+export function validateTask(solverType, task) {
+    return validateWithSchema(solverType, 'task', task);
+}
+export function assertTask(solverType, task) {
+    return assertValid(validateTask(solverType, task));
+}
+export function validateSolutionPayload(solverType, payload) {
+    return validateWithSchema(solverType, 'solution', payload);
+}
+export function assertSolutionPayload(solverType, payload) {
+    return assertValid(validateSolutionPayload(solverType, payload));
+}
+export function validateVerdictPayload(solverType, payload) {
+    return validateWithSchema(solverType, 'verdict', payload);
+}
+export function assertVerdictPayload(solverType, payload) {
+    return assertValid(validateVerdictPayload(solverType, payload));
+}
+export function buildSolutionOutput(args) {
+    const payload = assertSolutionPayload(args.solverType, args.payload);
+    return {
+        venueRef: { name: args.venueName },
+        gating: args.gating ?? {},
+        ...(args.informational ? { informational: args.informational } : {}),
+        solutionPayload: payload,
+        ...(args.artifacts ? { artifacts: args.artifacts } : {}),
+        ...(args.rationale ? { rationale: args.rationale } : {}),
+    };
+}
+export function buildVerdictOutput(args) {
+    const payload = assertVerdictPayload(args.solverType, args.payload);
+    return {
+        venueRef: { name: args.venueName ?? 'jinn-evaluator' },
+        gating: args.gating ?? {},
+        ...(args.informational ? { informational: args.informational } : {}),
+        verdictPayload: payload,
+        ...(args.artifacts ? { artifacts: args.artifacts } : {}),
+        ...(args.rationale ? { rationale: args.rationale } : {}),
+    };
+}

package/dist/harness.d.ts

@@ -0,0 +1,69 @@
+export type { Address, Hex, IntentWindow, Task, OutputArtifact, RationaleEntry, Solution, TrajectoryCollector, TrajectorySpanInput, ReadyStatus, EnableArgDef, IntentEnableMetadata, EnableResult, } from './types.js';
+export { REQUIRES_LIVE_DAEMON_READINESS, SkippableError } from './types.js';
+export type { SignTypedDataArgs, SendAllowedCallArgs, ScopedSigner, ScopedRpc, ScopedSecrets, } from './capabilities.js';
+export type { CapabilityAllowEntry, ManifestRpcAllow, ManifestSecretSpec, TypedDataAllowEntry, JinnManifest, } from './manifest.js';
+import type { Task, Solution, TrajectoryCollector, ReadyStatus, IntentEnableMetadata, EnableResult } from './types.js';
+import type { ScopedSigner, ScopedRpc, ScopedSecrets } from './capabilities.js';
+export interface HarnessContext {
+    task: Task;
+    taskCid?: string;
+    implStateDir: string;
+    workingDir: string;
+    log: (event: {
+        level: 'info' | 'warn' | 'error';
+        msg: string;
+        data?: unknown;
+    }) => void;
+    abort: AbortSignal;
+    msUntilEndTs: () => number;
+    trajectory: TrajectoryCollector;
+    signer?: ScopedSigner;
+    rpc?: ScopedRpc;
+    secrets?: ScopedSecrets;
+}
+/**
+ * Construction-time environment passed to the impl factory.
+ * Per-attempt Task inputs are provided through HarnessContext.
+ */
+export interface ExternalHarnessEnv {
+    readonly implName: string;
+    readonly implVersion: string;
+    readonly network: string;
+    readonly implStateDir: string;
+    readonly secrets: ScopedSecrets;
+    readonly log: HarnessContext['log'];
+    /** True for CLI introspection; impls should report stub readiness. */
+    readonly stub: boolean;
+}
+export interface Harness {
+    name: string;
+    version: string;
+    supports(ctx: {
+        solverType: string;
+        role?: 'restoration' | 'evaluation';
+    }): boolean;
+    canAttempt?(task: Task): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    run(ctx: HarnessContext): Promise<Solution>;
+    isReady?(spec?: {
+        solverType: string;
+        role?: 'restoration' | 'evaluation';
+    }): Promise<ReadyStatus>;
+    enableMetadata?(): IntentEnableMetadata;
+    onEnable?(args: Record<string, string | undefined>, spec?: {
+        solverType: string;
+        role?: 'restoration' | 'evaluation';
+    }): Promise<EnableResult>;
+    onDisable?(spec?: {
+        solverType: string;
+        role?: 'restoration' | 'evaluation';
+    }): Promise<void>;
+}
+/**
+ * External-impl factory: default-export shape for external Harness packages.
+ */
+export type ExternalHarnessFactory = (env: ExternalHarnessEnv) => Harness;

package/dist/harness.js

@@ -0,0 +1 @@
+export { REQUIRES_LIVE_DAEMON_READINESS, SkippableError } from './types.js';

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { Address, Hex, IntentWindow, Task, OutputArtifact, RationaleEntry, Solution, TrajectoryCollector, TrajectorySpanInput, ReadyStatus, EnableArgDef, IntentEnableMetadata, EnableResult, } from './types.js';
+export { REQUIRES_LIVE_DAEMON_READINESS, SkippableError } from './types.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+// @jinn-network/sdk
+//
+// Minimal generic SDK root. Use role-oriented subpaths for execution,
+// SolverNet, plugin, and first-party SolverNet helpers.
+export { REQUIRES_LIVE_DAEMON_READINESS, SkippableError } from './types.js';

package/dist/manifest.d.ts

@@ -0,0 +1,69 @@
+export interface CapabilityAllowEntry {
+    chainId: number;
+    to: `0x${string}`;
+    selector: `0x${string}`;
+    description?: string;
+}
+/**
+ * EIP-712 typed-data domain allow-list entry.
+ *
+ * The daemon's scoped signer refuses any `signTypedData` call whose
+ * domain does not match one of these entries:
+ * - `chainId` MUST match exactly.
+ * - `verifyingContract` / `name` / `version` match only when set on
+ *   the entry; an unset field on the entry means "any value".
+ * - An empty / omitted `typedDataDomains` array means default-deny:
+ *   every `signTypedData` call throws.
+ */
+export interface TypedDataAllowEntry {
+    chainId: number;
+    name?: string;
+    version?: string;
+    verifyingContract?: `0x${string}`;
+}
+export interface ManifestRpcAllow {
+    chainId: number;
+    methods: ReadonlyArray<'eth_call' | 'eth_getBlockByNumber' | 'eth_getLogs' | 'eth_getTransactionReceipt' | 'eth_chainId' | 'eth_blockNumber' | 'eth_getBalance' | 'eth_getCode'>;
+    rateLimit?: {
+        perSec: number;
+    };
+}
+export interface ManifestSecretSpec {
+    name: string;
+    description: string;
+    required: boolean;
+}
+export interface JinnManifest {
+    schemaVersion: '1.0.0';
+    name: string;
+    version: string;
+    description?: string;
+    /** Each entry follows `<domain>.v<major>(>=<semver>)` from spec/2026-05-schema-versioning.md. */
+    supportedSolverTypes: readonly string[];
+    /** Path to the entrypoint module, relative to the package root. */
+    entry: string;
+    /** Tarball CID + sha256 (set at publish time). */
+    package: {
+        cid: string;
+        hash: `sha256:${string}`;
+    };
+    capabilities: {
+        signer?: {
+            selectors: ReadonlyArray<CapabilityAllowEntry>;
+            typedDataDomains?: ReadonlyArray<TypedDataAllowEntry>;
+        };
+        rpc?: ReadonlyArray<ManifestRpcAllow>;
+        secrets?: ReadonlyArray<ManifestSecretSpec>;
+    };
+    /** Detached signature object — not part of the canonicalised manifest. */
+    signature: {
+        alg: 'ed25519';
+        publicKey: string;
+        sig: string;
+    };
+    author?: {
+        name: string;
+        url?: string;
+    };
+    license?: string;
+}

package/dist/manifest.js

@@ -0,0 +1,3 @@
+// JinnManifest — the signed package manifest each external Harness ships.
+// See `spec/2026-05-executor-trust-boundary.md` §5.
+export {};