kerb-sdk 0.1.0

package/README.md

@@ -0,0 +1,12 @@
+# kerb-sdk
+
+Read Kerb Terms from anywhere: the market-time risk layer for tokenized stocks on X Layer.
+
+```ts
+import { Kerb } from "kerb-sdk";
+const kerb = new Kerb();                 // X Layer mainnet, https://api.usekerb.xyz
+const t = await kerb.terms("BRK.Bx");
+if (!t.usable) throw new Error("no new exposure: terms stale or regime unsound");
+```
+
+Docs: https://www.usekerb.xyz/docs · API: https://github.com/Franlinozz/Kerb/blob/main/docs/API.md · MIT

package/index.d.ts

@@ -0,0 +1,175 @@
+/**
+ * @kerb/sdk: read Kerb Terms from the REST API or straight from the chain.
+ *
+ *   const kerb = new Kerb();
+ *   const terms = await kerb.terms("KOx");
+ *   if (!terms.usable) return;                       // no new risk may be taken
+ *   const maxDebt = Number(terms.carryLTV) * collateralValue;
+ *
+ * Every number is a decimal string and carries the provenance label it was published with.
+ */
+export type ProvenanceLabel = "Verified" | "Observed" | "Attested" | "Computed";
+export declare const KERB_API = "https://api.usekerb.xyz";
+export declare const X_LAYER = 196;
+export declare const X_LAYER_TESTNET = 1952;
+export declare const REGIMES: readonly ["DEEP", "NORMAL", "THIN", "PRE_TRANSITION", "REFERENCE_CLOSED", "ACTION", "HALTED", "STALE", "RECOVERY"];
+export type Regime = (typeof REGIMES)[number];
+export interface RawValue {
+    raw: string;
+    decimals: number;
+    label: ProvenanceLabel;
+}
+export interface Terms {
+    chainId: number;
+    assetId: string;
+    symbol: string | null;
+    observedAt: string;
+    ageSec: number;
+    /** false means "no new risk may be taken". It never means "liquidate everything". */
+    usable: boolean;
+    regime: {
+        value: Regime;
+        index: number;
+        label: ProvenanceLabel;
+    };
+    creditMark: RawValue;
+    carryLTV: RawValue;
+    sessionMaxLTV: RawValue;
+    debtCeiling: RawValue;
+    executableDepth1: RawValue;
+    inputsHash: string;
+    tx: string;
+    contracts: {
+        clock?: string;
+        terms?: string;
+    };
+    history: {
+        observedAt: string;
+        regime: Regime;
+        carryLTV: string;
+        sessionMaxLTV: string;
+        creditMark: string;
+        tx: string;
+    }[];
+}
+export interface BoardRow {
+    symbol: string;
+    underlying: {
+        symbol: string;
+        market: string;
+        currency: string;
+    };
+    status: "live" | "no report" | "stale";
+    regime: {
+        value: Regime | null;
+        label: ProvenanceLabel;
+        observedAt: string | null;
+    };
+    creditMark: {
+        value: string | null;
+        label: ProvenanceLabel;
+    };
+    executableDepth1: {
+        value: string | null;
+        label: ProvenanceLabel;
+    };
+    carryLTV: {
+        value: string | null;
+        label: ProvenanceLabel;
+    };
+    sessionMaxLTV: {
+        value: string | null;
+        label: ProvenanceLabel;
+    };
+    debtCeiling: {
+        value: string | null;
+        label: ProvenanceLabel;
+    };
+    coverageRatio: {
+        value: string | null;
+        label: ProvenanceLabel;
+    };
+    reportAgeSec: number | null;
+}
+export interface Board {
+    chainId: number;
+    loanAsset: string;
+    generatedAt: string;
+    contracts: {
+        KerbClock: string | null;
+        KerbTerms: string | null;
+    };
+    rows: BoardRow[];
+    sources: {
+        name: string;
+        lastObservedAt: string | null;
+        ageSec: number | null;
+        healthy: boolean;
+    }[];
+}
+/** Scale a raw integer string by its decimals, exactly, without floating point. */
+export declare function toDecimalString(v: RawValue | {
+    raw: string;
+    decimals: number;
+}): string;
+export declare class KerbError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export interface KerbOptions {
+    baseUrl?: string;
+    chainId?: number;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+export declare class Kerb {
+    private readonly baseUrl;
+    private readonly chainId;
+    private readonly doFetch;
+    private readonly timeoutMs;
+    constructor(opts?: KerbOptions);
+    private get;
+    /** Latest posted Terms for an asset, by symbol, token address or assetId. */
+    terms(asset: string, chainId?: number): Promise<Terms>;
+    /** Every tracked asset with its regime, mark, depth and capacities. */
+    board(chainId?: number): Promise<Board>;
+    /** The pinned input bundle behind a report, so any number can be recomputed. */
+    bundle(inputsHashOrReportId: string): Promise<unknown>;
+    report(reportId: string): Promise<unknown>;
+    health(): Promise<{
+        status: string;
+        observations: {
+            ageSec: number | null;
+        };
+    }>;
+}
+/**
+ * Read `effectiveTerms` straight from KerbTerms with any viem-compatible client, for
+ * consumers that will not trust an HTTP API.
+ */
+export declare const KERB_TERMS_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "effectiveTerms";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "assetId";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "carryLTV";
+        readonly type: "uint64";
+    }, {
+        readonly name: "sessionMaxLTV";
+        readonly type: "uint64";
+    }, {
+        readonly name: "creditMark";
+        readonly type: "uint128";
+    }, {
+        readonly name: "regime";
+        readonly type: "uint16";
+    }, {
+        readonly name: "usable";
+        readonly type: "bool";
+    }];
+}];
+export declare function regimeName(index: number): Regime;

package/index.js

@@ -0,0 +1,92 @@
+/**
+ * @kerb/sdk: read Kerb Terms from the REST API or straight from the chain.
+ *
+ *   const kerb = new Kerb();
+ *   const terms = await kerb.terms("KOx");
+ *   if (!terms.usable) return;                       // no new risk may be taken
+ *   const maxDebt = Number(terms.carryLTV) * collateralValue;
+ *
+ * Every number is a decimal string and carries the provenance label it was published with.
+ */
+export const KERB_API = "https://api.usekerb.xyz";
+export const X_LAYER = 196;
+export const X_LAYER_TESTNET = 1952;
+export const REGIMES = [
+    "DEEP", "NORMAL", "THIN", "PRE_TRANSITION", "REFERENCE_CLOSED", "ACTION", "HALTED", "STALE", "RECOVERY",
+];
+/** Scale a raw integer string by its decimals, exactly, without floating point. */
+export function toDecimalString(v) {
+    const neg = v.raw.startsWith("-");
+    const digits = (neg ? v.raw.slice(1) : v.raw).padStart(v.decimals + 1, "0");
+    const cut = digits.length - v.decimals;
+    const out = `${digits.slice(0, cut)}.${digits.slice(cut)}`.replace(/\.?0+$/, "");
+    return `${neg ? "-" : ""}${out === "" ? "0" : out}`;
+}
+export class KerbError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export class Kerb {
+    baseUrl;
+    chainId;
+    doFetch;
+    timeoutMs;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl ?? KERB_API).replace(/\/$/, "");
+        this.chainId = opts.chainId ?? X_LAYER;
+        this.doFetch = opts.fetch ?? globalThis.fetch;
+        this.timeoutMs = opts.timeoutMs ?? 10_000;
+    }
+    async get(path) {
+        const res = await this.doFetch(`${this.baseUrl}${path}`, { signal: AbortSignal.timeout(this.timeoutMs) });
+        if (!res.ok)
+            throw new KerbError(res.status, `kerb: ${path} returned ${res.status}`);
+        return (await res.json());
+    }
+    /** Latest posted Terms for an asset, by symbol, token address or assetId. */
+    async terms(asset, chainId = this.chainId) {
+        return this.get(`/v1/terms/${chainId}/${encodeURIComponent(asset)}`);
+    }
+    /** Every tracked asset with its regime, mark, depth and capacities. */
+    async board(chainId = this.chainId) {
+        return this.get(`/v1/board?chain=${chainId}`);
+    }
+    /** The pinned input bundle behind a report, so any number can be recomputed. */
+    async bundle(inputsHashOrReportId) {
+        return this.get(`/v1/bundle/${encodeURIComponent(inputsHashOrReportId)}`);
+    }
+    async report(reportId) {
+        return this.get(`/v1/reports/${encodeURIComponent(reportId)}`);
+    }
+    async health() {
+        return this.get("/health");
+    }
+}
+/**
+ * Read `effectiveTerms` straight from KerbTerms with any viem-compatible client, for
+ * consumers that will not trust an HTTP API.
+ */
+export const KERB_TERMS_ABI = [
+    {
+        type: "function",
+        name: "effectiveTerms",
+        stateMutability: "view",
+        inputs: [{ name: "assetId", type: "bytes32" }],
+        outputs: [
+            { name: "carryLTV", type: "uint64" },
+            { name: "sessionMaxLTV", type: "uint64" },
+            { name: "creditMark", type: "uint128" },
+            { name: "regime", type: "uint16" },
+            { name: "usable", type: "bool" },
+        ],
+    },
+];
+export function regimeName(index) {
+    const r = REGIMES[index];
+    if (!r)
+        throw new KerbError(0, `unknown regime index ${index}`);
+    return r;
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "kerb-sdk",
+  "version": "0.1.0",
+  "description": "Read Kerb Terms: the market-time risk layer for tokenized stocks on X Layer. Credit on the market's clock.",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": { ".": { "types": "./index.d.ts", "import": "./index.js" } },
+  "files": ["index.js", "index.d.ts", "README.md"],
+  "license": "MIT",
+  "homepage": "https://www.usekerb.xyz/developers",
+  "repository": { "type": "git", "url": "https://github.com/Franlinozz/Kerb", "directory": "packages/sdk" },
+  "keywords": ["kerb", "x layer", "tokenized stocks", "xstocks", "credit", "risk", "okx"],
+  "peerDependencies": { "viem": "^2.45.0" },
+  "peerDependenciesMeta": { "viem": { "optional": true } }
+}