@btx-tools/challenges-sdk 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,406 @@
+/**
+ * Type definitions mirroring the BTX service-challenges RPC schema.
+ *
+ * Source: btx.dev/docs/rpc/service-challenges (verified 2026-05-20).
+ * Schema captured against live btxd v0.29.7 at btx-iowa (block 106270).
+ *
+ * IMPORTANT: We do NOT camelCase rename — the RPC schema is the wire contract.
+ * Field names mirror btxd output verbatim.
+ */
+/** Difficulty calibration policy for issued challenges. */
+type DifficultyPolicy = 'fixed' | 'adaptive_window';
+/**
+ * Standard purpose labels recognized by the chain. Free-form strings allowed too.
+ *
+ * The `(string & {})` trick keeps autocomplete on the known labels while still
+ * accepting arbitrary purpose strings. Don't "simplify" to plain `string` — it
+ * loses the autocompletion benefit. See: https://github.com/microsoft/TypeScript/issues/29729
+ */
+type ChallengePurpose = 'rate_limit' | 'api_gate' | 'ai_inference_gate' | (string & {});
+/** Parameters for issuing a challenge via getmatmulservicechallenge. */
+interface IssueParams {
+    purpose: ChallengePurpose;
+    resource: string;
+    subject: string;
+    /** Calibrates client compute work to roughly this many seconds. btxd default: 1.0. */
+    target_solve_time_s?: number;
+    /** Challenge lifetime in seconds. btxd default: 300. Range 1–86400. */
+    expires_in_s?: number;
+    validation_overhead_s?: number;
+    propagation_overhead_s?: number;
+    /** btxd default: "fixed". */
+    difficulty_policy?: DifficultyPolicy;
+    difficulty_window_blocks?: number;
+    min_solve_time_s?: number;
+    max_solve_time_s?: number;
+    solver_parallelism?: number;
+    solver_duty_cycle_pct?: number;
+}
+/**
+ * Binding identifies the (purpose, resource, subject) trio the challenge is
+ * scoped to. btxd also embeds hashes + anchor info for replay protection.
+ */
+interface ChallengeBinding {
+    chain: string;
+    purpose: string;
+    resource: string;
+    subject: string;
+    resource_hash: string;
+    subject_hash: string;
+    salt: string;
+    anchor_height: number;
+    anchor_hash: string;
+    /** Hashing rule used to compute challenge_id. Treat as opaque docstring from btxd. */
+    challenge_id_rule?: string;
+    seed_derivation_rule?: string;
+    /** Open extension — btxd may add fields without breaking us. */
+    [k: string]: unknown;
+}
+/**
+ * Proof policy describes what btxd will check when redeeming. Treat fields
+ * as authoritative — do NOT re-derive verification rules client-side.
+ */
+interface ChallengeProofPolicy {
+    verification_rule: string;
+    sigma_gate_applied: boolean;
+    expiration_enforced: boolean;
+    challenge_id_required: boolean;
+    replay_protection: string;
+    redeem_rpc: string;
+    solve_rpc: string;
+    locally_issued_required: boolean;
+    issued_challenge_store?: string;
+    issued_challenge_scope?: string;
+    [k: string]: unknown;
+}
+/** MatMul parameters needed to solve. Day 2 solver consumes these. */
+interface ChallengeMatmul {
+    /** Matrix dimension. btxd ships n=512 in production. */
+    n: number;
+    /** Block dimension for compression. */
+    b: number;
+    /** Noise rank. */
+    r: number;
+    /** Field modulus (Mersenne prime 2^31-1). */
+    q: number;
+    min_dimension: number;
+    max_dimension: number;
+    /** Hex-encoded seed for matrix A. */
+    seed_a: string;
+    /** Hex-encoded seed for matrix B. */
+    seed_b: string;
+}
+/** Block header context the challenge is anchored to. */
+interface ChallengeHeaderContext {
+    version: number;
+    previousblockhash: string;
+    merkleroot: string;
+    time: number;
+    bits: string;
+    nonce64_start: number;
+    matmul_dim: number;
+    seed_a: string;
+    seed_b: string;
+}
+/**
+ * Inner challenge payload — what the solver actually needs.
+ * The Day 2 MatMul solver reads `matmul`, `target`, `noncerange`, and `header_context`.
+ */
+interface ChallengePayload {
+    chain: string;
+    algorithm: string;
+    height: number;
+    previousblockhash: string;
+    mintime: number;
+    bits: string;
+    difficulty: number;
+    /** Hex-encoded target. Digest must compare ≤ target for valid proof. */
+    target: string;
+    noncerange: string;
+    header_context: ChallengeHeaderContext;
+    matmul: ChallengeMatmul;
+    /** btxd ships additional fields (work_profile, runtime_observability, etc.) we treat as opaque. */
+    [k: string]: unknown;
+}
+/**
+ * The challenge envelope returned by getmatmulservicechallenge.
+ * Opaque to the SDK at the wire boundary — pass through to solver / redeem.
+ */
+interface Challenge {
+    /** btxd schema kind discriminator (e.g. "matmul_service_challenge_v1"). */
+    kind?: string;
+    challenge_id: string;
+    issued_at: number;
+    expires_at: number;
+    expires_in_s: number;
+    binding: ChallengeBinding;
+    proof_policy: ChallengeProofPolicy;
+    challenge: ChallengePayload;
+    /** Open extension. */
+    [k: string]: unknown;
+}
+/** Reasons returned by verify/redeem. Open string — btxd may add more. */
+type VerifyReason = 'ok' | 'invalid_proof' | 'challenge_mismatch' | 'expired' | 'unknown_challenge' | 'already_redeemed' | 'missing_proof' | (string & {});
+/** Outcome of verifymatmulserviceproof / redeemmatmulserviceproof. */
+interface VerifyResult {
+    valid: boolean;
+    expired?: boolean;
+    reason: VerifyReason;
+    issued_by_local_node?: boolean;
+    redeemed?: boolean;
+    redeemable?: boolean;
+    mismatch_field?: string;
+}
+/** Single entry in a batch redeem/verify call. */
+interface BatchEntry {
+    challenge: Challenge;
+    nonce64_hex: string;
+    digest_hex: string;
+}
+/** Batch response — sequential per-proof results. */
+interface BatchResult {
+    count: number;
+    valid: number;
+    invalid: number;
+    by_reason: Record<string, number>;
+    results: VerifyResult[];
+}
+/** Solver output (also returned by solvematmulservicechallenge RPC). */
+interface SolverOutput {
+    nonce64_hex: string;
+    digest_hex: string;
+    proof: Record<string, unknown>;
+}
+/** RPC client configuration. */
+interface BtxClientOpts {
+    /**
+     * Full JSON-RPC endpoint, e.g. `http://127.0.0.1:19332`.
+     *
+     * **Security**: use HTTPS (or a localhost-only deployment) when the RPC
+     * endpoint is not on `127.0.0.1`. Basic auth over plaintext exposes credentials.
+     * Terminate TLS at stunnel/nginx/Caddy in front of btxd; do NOT expose
+     * btxd's RPC port directly to the public internet.
+     */
+    rpcUrl: string;
+    /** Basic-auth credentials matching btxd's rpcauth / rpcuser+rpcpassword. */
+    rpcAuth: {
+        user: string;
+        pass: string;
+    };
+    /** Request timeout in ms (default 30000). */
+    timeoutMs?: number;
+}
+/** Base class — all SDK errors extend this for `instanceof BtxError` checks. */
+declare class BtxError extends Error {
+    readonly method?: string | undefined;
+    constructor(message: string, method?: string | undefined);
+}
+/** btxd returned a JSON-RPC error envelope with code + message. */
+declare class BtxRpcError extends BtxError {
+    readonly code: number;
+    constructor(code: number, message: string, method?: string);
+}
+/** btxd returned a non-2xx HTTP status. */
+declare class BtxHttpError extends BtxError {
+    readonly status: number;
+    /** Response body, with `Authorization: Basic ...` patterns redacted. */
+    readonly body: string;
+    constructor(status: number, 
+    /** Response body, with `Authorization: Basic ...` patterns redacted. */
+    body: string, method?: string);
+}
+/** The HTTP response was 2xx but the body wasn't valid JSON. */
+declare class BtxParseError extends BtxError {
+    /** Underlying SyntaxError or similar. Overrides the ES2022 `Error.cause` slot. */
+    readonly cause: unknown;
+    /** Raw response body (redacted). */
+    readonly body: string;
+    constructor(
+    /** Underlying SyntaxError or similar. Overrides the ES2022 `Error.cause` slot. */
+    cause: unknown, 
+    /** Raw response body (redacted). */
+    body: string, method?: string);
+}
+/** Request exceeded `timeoutMs`. */
+declare class BtxTimeoutError extends BtxError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, method?: string);
+}
+/** Transport-level failure (DNS, TCP reset, TLS, etc.). Wraps the underlying cause. */
+declare class BtxNetworkError extends BtxError {
+    /** Underlying error from fetch / dns / tls. Overrides the ES2022 `Error.cause` slot. */
+    readonly cause: unknown;
+    constructor(
+    /** Underlying error from fetch / dns / tls. Overrides the ES2022 `Error.cause` slot. */
+    cause: unknown, method?: string);
+}
+
+/**
+ * JSON-RPC client for BTX service-challenges.
+ *
+ * Wraps the 5 core RPCs:
+ *   - getmatmulservicechallenge   (issue)
+ *   - verifymatmulserviceproof    (verify, stateless)
+ *   - redeemmatmulserviceproof    (verify + consume, anti-replay)
+ *   - verifymatmulserviceproofs   (batch verify)
+ *   - redeemmatmulserviceproofs   (batch redeem)
+ *
+ * Plus helper RPCs:
+ *   - solvematmulservicechallenge (server-side solver — for fixtures + tests)
+ *
+ * RPC reference: https://btx.dev/docs/rpc/service-challenges
+ *
+ * Error model:
+ *   - {@link BtxRpcError}     — btxd returned a JSON-RPC error envelope
+ *   - {@link BtxHttpError}    — non-2xx HTTP status
+ *   - {@link BtxParseError}   — 2xx but body wasn't valid JSON
+ *   - {@link BtxTimeoutError} — request exceeded `timeoutMs`
+ *   - {@link BtxNetworkError} — DNS / TCP / TLS-level failure
+ *   - All extend {@link BtxError}.
+ */
+declare class BtxChallengeClient {
+    private readonly opts;
+    constructor(opts: BtxClientOpts);
+    /** Low-level: raw JSON-RPC call. Exposed for forward compatibility. */
+    call<T = unknown>(method: string, params?: unknown[]): Promise<T>;
+    /** Issue a fresh challenge bound to (purpose, resource, subject). */
+    issue(params: IssueParams): Promise<Challenge>;
+    /**
+     * Verify a proof statelessly. Does NOT consume the challenge.
+     * Use this for diagnostic / monitoring paths.
+     * For admission control, use {@link redeem} instead — verification alone
+     * does not prevent replay.
+     */
+    verify(challenge: Challenge, nonce64_hex: string, digest_hex: string, lookup_local_status?: boolean): Promise<VerifyResult>;
+    /**
+     * Verify-and-consume atomically. THIS is the admission control entry point.
+     * On success, the challenge is marked redeemed and cannot be replayed.
+     */
+    redeem(challenge: Challenge, nonce64_hex: string, digest_hex: string): Promise<VerifyResult>;
+    /** Batch verify. Spec range 1–256 (audit M2). No consumption. */
+    verifyBatch(entries: BatchEntry[]): Promise<BatchResult>;
+    /** Batch verify + consume. Sequential per-entry. Spec range 1–256 (audit M2). */
+    redeemBatch(entries: BatchEntry[]): Promise<BatchResult>;
+    /**
+     * Server-side local solver. Useful when generating fixtures or pre-computing
+     * for tests. For production browser-side solving, ship the WASM solver —
+     * RPC-based solving puts compute load on YOUR node, defeating the point.
+     */
+    solve(challenge: Challenge): Promise<SolverOutput>;
+    private assertBatchSize;
+}
+
+/**
+ * Top-level pure-JS solver for the BTX MatMul service-challenge PoW.
+ *
+ * Ported from `btxd v0.29.7 src/matmul/matmul_pow.cpp` lines 293-358 (`Solve`).
+ *
+ *   A = FromSeed(seed_a, n)
+ *   B = FromSeed(seed_b, n)
+ *   for nonce in [start, start + maxTries):
+ *     sigma   = DeriveSigma(state(nonce))
+ *     noise   = noise::Generate(sigma, n, r)
+ *     E       = noise.E_L · noise.E_R
+ *     F       = noise.F_L · noise.F_R
+ *     A'      = A + E
+ *     B'      = B + F
+ *     result  = transcript::CanonicalMatMul(A', B', b, sigma)
+ *     if uintLE(result.transcript_hash) <= uintBE(target): return success
+ *
+ * Comparison semantics: `transcript_hash` is the raw SHA-256d output, treated
+ * as a 256-bit integer in **little-endian byte order** (btxd's `uint256` ↔
+ * `arith_uint256` convention). `target` arrives as a BE hex string. Both are
+ * converted to `bigint` for the `<=` test.
+ */
+
+/** Options for {@link solveJs}. */
+interface SolveJsOptions {
+    /** Max nonces to try before giving up. Default 1_000_000. */
+    maxTries?: number;
+    /** Override the starting nonce (default: challenge.header_context.nonce64_start). */
+    nonceStart?: bigint;
+    /** Optional callback fired every N attempts for progress reporting. */
+    onAttempt?: (attemptIndex: number, nonce: bigint) => void;
+    /** Frequency of `onAttempt` calls (default every 1 attempt). */
+    attemptInterval?: number;
+}
+
+/**
+ * How a challenge should be solved.
+ *
+ * - `'rpc'` — delegate to btxd's `solvematmulservicechallenge`. Requires
+ *   `opts.rpcClient`. Server-side / Node-only.
+ *
+ * - `'pure-js'` — solve locally with a pure-TypeScript MatMul implementation.
+ *   Browser-compatible. Ports the canonical CPU path of btxd's matmul solver.
+ *   At default difficulty + n=512, pure-JS solving is slow (perf is currently
+ *   bounded by `BigInt`-based M31 multiplication; WASM/SIMD acceleration is
+ *   planned for a future iteration).
+ *
+ * - `'auto'` — pick automatically: `'rpc'` if `opts.rpcClient` is provided,
+ *   else `'pure-js'`.
+ */
+type SolverMode = 'rpc' | 'pure-js' | 'auto';
+/** Options for {@link Solver.solve}. */
+interface SolverOptions {
+    /** Solve strategy. Default: `'auto'` (rpc if client provided, else pure-js). */
+    mode?: SolverMode;
+    /** Required for `mode === 'rpc'`. Ignored for `'pure-js'`. */
+    rpcClient?: BtxChallengeClient;
+    /** Forwarded to the pure-JS solver. Ignored for `'rpc'`. */
+    pureJs?: SolveJsOptions;
+}
+/**
+ * Solve a BTX service challenge to produce a (nonce, digest, proof) tuple
+ * that btxd will accept on redemption.
+ *
+ * **Modes**:
+ *  - `'rpc'`: delegate to btxd's `solvematmulservicechallenge` RPC. Pass an
+ *    authenticated `BtxChallengeClient` in `opts.rpcClient`. **Production
+ *    note**: the solve RPC shares the matmul backend with block-template
+ *    mining; consumers MUST point at a dedicated non-mining btxd, otherwise
+ *    individual solves can queue behind mining work for 10+ minutes.
+ *  - `'pure-js'`: solve locally with the ported TypeScript MatMul. Browser-
+ *    compatible. Slower than `'rpc'` but no node required.
+ *  - `'auto'`: prefers `'rpc'` if a client is provided, else `'pure-js'`.
+ *
+ * @example Server-side (Node, RPC mode)
+ * ```typescript
+ * import { BtxChallengeClient, Solver } from '@btx/challenges-sdk';
+ *
+ * const client = new BtxChallengeClient({
+ *   rpcUrl: 'http://127.0.0.1:19332',
+ *   rpcAuth: { user: 'rpcuser', pass: 'rpcpass' },
+ * });
+ *
+ * const challenge = await client.issue({
+ *   purpose: 'ai_inference_gate',
+ *   resource: 'model:gpt-x|route:/v1/generate',
+ *   subject: 'tenant:abc123',
+ * });
+ *
+ * const proof = await Solver.solve(challenge, { mode: 'rpc', rpcClient: client });
+ * const result = await client.redeem(challenge, proof.nonce64_hex, proof.digest_hex);
+ *
+ * if (result.valid && result.reason === 'ok') {
+ *   // Admit the caller.
+ * }
+ * ```
+ *
+ * @example Browser-side (pure-JS mode)
+ * ```typescript
+ * import { Solver } from '@btx/challenges-sdk';
+ *
+ * // Solve a challenge with no server-side help. Slow at default difficulty;
+ * // for production browser use cases, calibrate via `target_solve_time_s`.
+ * const proof = await Solver.solve(challenge, {
+ *   mode: 'pure-js',
+ *   pureJs: { maxTries: 100_000 },
+ * });
+ * ```
+ */
+declare class Solver {
+    static solve(challenge: Challenge, opts?: SolverOptions): Promise<SolverOutput>;
+}
+
+export { type BatchEntry, type BatchResult, BtxChallengeClient, type BtxClientOpts, BtxError, BtxHttpError, BtxNetworkError, BtxParseError, BtxRpcError, BtxTimeoutError, type Challenge, type ChallengeBinding, type ChallengeHeaderContext, type ChallengeMatmul, type ChallengePayload, type ChallengeProofPolicy, type ChallengePurpose, type DifficultyPolicy, type IssueParams, Solver, type SolverOutput, type VerifyReason, type VerifyResult };