@degen-insurance/sdk 0.2.0

package/dist/limits.js

@@ -0,0 +1,180 @@
+/**
+ * What a user is actually allowed to buy.
+ *
+ * Three separate limits decide it and they are denominated in three different things: the
+ * registry's minimum and maximum are notional wei, remaining capacity is a payout, and the
+ * share cap counts tokens. A user typing one number into one box cannot reconcile those, so a
+ * partner that does not do this arithmetic can only relay refusals after the fact -- which is
+ * what "This transaction would fail on chain (0xeddee5b2)" looked like before the front end
+ * grew the same helpers.
+ */
+export const BPS = 10000n;
+/**
+ * Robinhood Chain's rate card, and nobody else's.
+ *
+ * Named for the chain it was measured on, because that is the whole of its validity. The
+ * premiums come from a calibration run over 4,679 pools and 301,612 buys on Robinhood Chain;
+ * `Chains.card()` reverts `NoRateCard` for every other chain rather than reuse them, and this
+ * SDK holds the same line. A premium is a claim about how often a token collapses, and that
+ * is a property of a chain's flow, not of the product.
+ *
+ * Use it to render a quote before you have a connection. Once you have one, read the card off
+ * the registry with `readRateCard` -- a deployment may have been reconfigured, and on any
+ * chain but Robinhood these numbers were never true to begin with.
+ */
+export const ROBINHOOD_RATE_CARD = [
+    { id: 0, name: "Basic", premiumBps: 300n, payoutBps: 1500n, minEntryBps: 12500n },
+    { id: 1, name: "Standard", premiumBps: 500n, payoutBps: 2500n, minEntryBps: 15000n },
+    { id: 2, name: "Degen Max", premiumBps: 1000n, payoutBps: 5000n, minEntryBps: 25000n },
+];
+/** Tier names are presentation, which the contracts do not own. Everything else is read. */
+const TIER_NAMES = { 0: "Basic", 1: "Standard", 2: "Degen Max" };
+export function tierById(card, id) {
+    const t = card.find((x) => x.id === id);
+    if (!t)
+        throw new Error(`unknown tier ${id}`);
+    return t;
+}
+/**
+ * Read the live rate card off a deployment's registry.
+ *
+ * The premium, the payout and the minimum entry are all product terms the contract enforces,
+ * so all three are read. Only the display name is local.
+ */
+export async function readRateCard(reader, registry, abi, ids = [0, 1, 2]) {
+    const rows = await Promise.all(ids.map((id) => reader.readContract({ address: registry, abi, functionName: "tiers", args: [BigInt(id)] })));
+    return rows.map((row, i) => {
+        const [premiumBps, payoutBps, minEntryBps, enabled] = row;
+        if (!enabled)
+            throw new Error(`tier ${ids[i]} is disabled on this deployment`);
+        return {
+            id: ids[i],
+            name: TIER_NAMES[ids[i]] ?? `Tier ${ids[i]}`,
+            premiumBps: BigInt(premiumBps),
+            payoutBps: BigInt(payoutBps),
+            minEntryBps: BigInt(minEntryBps),
+        };
+    });
+}
+/**
+ * Throw if a local card disagrees with the chain's.
+ *
+ * For callers who quote from `ROBINHOOD_RATE_CARD` before connecting: this is what turns a
+ * silent mispricing into a loud failure the first time it happens. Quoting one chain's
+ * premiums against another chain's risk is the failure mode worth being noisy about, because
+ * nothing downstream of it looks wrong -- the trade succeeds, at the wrong price.
+ */
+export function assertRateCard(local, onChain) {
+    for (const chain of onChain) {
+        const mine = local.find((t) => t.id === chain.id);
+        if (!mine)
+            throw new Error(`local card is missing tier ${chain.id}`);
+        for (const field of ["premiumBps", "payoutBps", "minEntryBps"]) {
+            if (mine[field] !== chain[field]) {
+                throw new Error(`rate card mismatch on tier ${chain.id}: local ${field}=${mine[field]}, chain says ${chain[field]}`);
+            }
+        }
+    }
+}
+/** Split a total payment into the trade and the premium, exactly as the router does. */
+export function splitValue(total, premiumBps) {
+    const notional = (total * BPS) / (BPS + premiumBps);
+    return { notional, premium: (notional * premiumBps) / BPS };
+}
+/** A notional, grossed up to the total a user pays -- trade plus premium. */
+export function totalForNotional(notional, tier) {
+    return (notional * (BPS + tier.premiumBps)) / BPS;
+}
+/**
+ * Largest total spendable before the payout exceeds what is left on a token.
+ *
+ * Remaining capacity is a *payout* figure, and a user types a *trade size*. They differ by the
+ * tier -- 2.2x at Degen Max, 6.9x at Basic -- so relaying the capacity number itself tells a
+ * user to spend far less than they could.
+ */
+export function maxTotalForCapacity(capacity, tier) {
+    if (capacity <= 0n || tier.payoutBps === 0n)
+        return 0n;
+    return totalForNotional((capacity * BPS) / tier.payoutBps, tier);
+}
+/** Tokens a payment buys, from the pool's own constant-product maths. */
+export function quoteOut(q, notional) {
+    if (notional <= 0n || q.tokenReserve === 0n || q.quoteReserve === 0n)
+        return 0n;
+    const inAfterFee = notional - (notional * q.feeBps) / BPS;
+    if (inAfterFee <= 0n)
+        return 0n;
+    return (q.tokenReserve * inAfterFee) / (q.quoteReserve + inAfterFee);
+}
+/**
+ * The inverse of `quoteOut`: the largest payment that buys no more than `tokens`.
+ *
+ * The position-share cap is a share of supply, so it is expressed in tokens while the user
+ * pays in the quote asset. Rounds down, and settles the last wei against `quoteOut` rather
+ * than trusting the algebra -- integer division lands either side of the true answer depending
+ * on the residue, and "the maximum" being one wei too large is the whole bug this prevents.
+ */
+export function notionalForTokens(q, tokens) {
+    if (tokens <= 0n || q.tokenReserve === 0n || q.quoteReserve === 0n)
+        return 0n;
+    if (tokens >= q.tokenReserve)
+        return 0n; // the curve cannot deliver its whole reserve
+    const afterFee = (tokens * q.quoteReserve) / (q.tokenReserve - tokens);
+    const feeDenom = BPS - q.feeBps;
+    if (feeDenom <= 0n)
+        return 0n;
+    let notional = (afterFee * BPS) / feeDenom;
+    while (notional > 0n && quoteOut(q, notional) > tokens)
+        notional -= 1n;
+    while (quoteOut(q, notional + 1n) <= tokens)
+        notional += 1n;
+    return notional;
+}
+/**
+ * The band of totals a buy will actually be accepted at.
+ *
+ * A zero limit means "not known", never "capped at zero" -- treating an unloaded bound as a
+ * hard zero collapses the band and refuses everything.
+ *
+ * The share bound is shaved by 1%. It counts tokens while the user pays in the quote asset,
+ * and the rate between them moves on every trade, so a price fall between quoting a maximum
+ * and signing it means the same payment buys more. Sitting exactly on the limit is how a
+ * stated maximum still gets refused.
+ */
+export function amountRange(capacity, tier, limits) {
+    const min = limits.minTradeWei > 0n ? totalForNotional(limits.minTradeWei, tier) : 1n;
+    let max = maxTotalForCapacity(capacity, tier);
+    const cap = (other) => {
+        if (other < max)
+            max = other;
+    };
+    if (limits.perTradeMaxWei > 0n)
+        cap(totalForNotional(limits.perTradeMaxWei, tier));
+    if (limits.maxShareNotionalWei !== undefined) {
+        cap(totalForNotional((limits.maxShareNotionalWei * 99n) / 100n, tier));
+    }
+    return { min, max, usable: max >= min };
+}
+/**
+ * Tokens a wallet may still insure on a token, before either share cap binds.
+ *
+ * Both caps are cumulative and both are a share of supply: one per wallet, one across all
+ * wallets. Whichever has less room left decides.
+ */
+export function shareHeadroom(supply, walletTokensInsured, tokenTokensInsured, limits) {
+    if (supply <= 0n)
+        return 0n;
+    const walletRoom = (supply * limits.maxPositionShareBps) / BPS - walletTokensInsured;
+    const tokenRoom = (supply * limits.maxTokenInsuredShareBps) / BPS - tokenTokensInsured;
+    const room = walletRoom < tokenRoom ? walletRoom : tokenRoom;
+    return room > 0n ? room : 0n;
+}
+/** Decode the `getParams()` tuple into the limits this module works in. */
+export function riskLimitsFromParams(p) {
+    return {
+        maxPositionShareBps: BigInt(p[6]),
+        maxTokenInsuredShareBps: BigInt(p[7]),
+        minTradeWei: BigInt(p[9]),
+        perTradeMaxWei: BigInt(p[10]),
+    };
+}

package/dist/telegram/render.d.ts

@@ -0,0 +1,14 @@
+import type { Alert, PolicyView } from "../alerts/state.js";
+/** Wei to a short decimal string. Kept local so the SDK has no formatting dependency. */
+export declare function formatEth(wei: bigint, dp?: number): string;
+export declare function formatCountdown(seconds: number): string;
+/** Telegram MarkdownV2 reserves a lot of punctuation; unescaped text silently fails to send. */
+export declare function escapeMarkdown(text: string): string;
+export declare function renderAlert(alert: Alert, policy: PolicyView, nowSeconds: number): string;
+/** Inline keyboard for a claimable policy. Partners render this against their own signer. */
+export declare function claimKeyboard(policyId: string, deepLink: string): {
+    inline_keyboard: {
+        text: string;
+        url: string;
+    }[][];
+};

package/dist/telegram/render.js

@@ -0,0 +1,44 @@
+/** Wei to a short decimal string. Kept local so the SDK has no formatting dependency. */
+export function formatEth(wei, dp = 4) {
+    const neg = wei < 0n;
+    const v = neg ? -wei : wei;
+    const whole = v / 10n ** 18n;
+    const frac = (v % 10n ** 18n).toString().padStart(18, "0").slice(0, dp).replace(/0+$/, "");
+    return `${neg ? "-" : ""}${frac ? `${whole}.${frac}` : whole}`;
+}
+export function formatCountdown(seconds) {
+    if (seconds <= 0)
+        return "expired";
+    const m = Math.floor(seconds / 60);
+    const s = seconds % 60;
+    return `${m}m ${String(s).padStart(2, "0")}s`;
+}
+/** Telegram MarkdownV2 reserves a lot of punctuation; unescaped text silently fails to send. */
+export function escapeMarkdown(text) {
+    return text.replace(/[_*[\]()~`>#+\-=|{}.!\\]/g, (c) => `\\${c}`);
+}
+export function renderAlert(alert, policy, nowSeconds) {
+    const sym = escapeMarkdown(policy.symbol);
+    const cover = escapeMarkdown(formatEth(policy.maxPayoutWei));
+    const left = escapeMarkdown(formatCountdown(policy.expiresAt - nowSeconds));
+    switch (alert.kind) {
+        case "cover_active":
+            return `🛡 *Cover active* on ${sym}\nPays up to ${cover} ETH if it falls back to launch price\\. ${left} left\\.`;
+        case "triggered_claimable":
+            return `🔔 *${sym} hit the floor* \\- your cover is claimable now\nPayout: ${cover} ETH`;
+        case "window_closing":
+            return `⏳ *${sym} cover expires in ${left}*\nNo payout unless it falls back to launch price before then\\.`;
+        case "claim_paid":
+            return `✅ *Claim paid* on ${sym}\n${cover} ETH sent to your wallet\\.`;
+        case "expired_unused":
+            return `${sym} cover expired without a collapse\\. Nothing to claim \\- that is the good outcome\\.`;
+        case "cover_ended":
+            return `Cover on ${sym} ended \\- you took the position out early\\. Nothing left to claim on it\\.`;
+    }
+}
+/** Inline keyboard for a claimable policy. Partners render this against their own signer. */
+export function claimKeyboard(policyId, deepLink) {
+    return {
+        inline_keyboard: [[{ text: "Claim now", url: `${deepLink}?claim=${encodeURIComponent(policyId)}` }]],
+    };
+}

package/dist/tx/build.d.ts

@@ -0,0 +1,51 @@
+import { type Address, type Hex } from "viem";
+import type { Deployment } from "../deployment.js";
+/** A transaction request a partner signs with the user's own key. Never a private key here. */
+export interface TxRequest {
+    to: Address;
+    data: Hex;
+    value: bigint;
+}
+export interface BuyWithCoverParams {
+    /** Which deployment, on which chain. Carries the addresses that have to agree. */
+    deployment: Deployment;
+    token: Address;
+    /** Total the user commits: trade plus premium. */
+    totalValue: bigint;
+    /** Slippage bound in token base units. */
+    minOut: bigint;
+    tier: number;
+    /** Partner address earning the revenue share. Omit for an unattributed trade. */
+    referrer?: Address;
+}
+/**
+ * Build the buy-with-cover call.
+ *
+ * The SDK never holds keys and never submits. Partners keep custody and their own UX; this
+ * returns a request for them to sign. That is the difference between integrating with a bot
+ * and becoming one, and it keeps the security surface of a custodial exchange out of scope.
+ */
+export declare function buildBuyWithCover(params: BuyWithCoverParams): TxRequest;
+export declare function buildBuyWithoutCover(deployment: Deployment, token: Address, totalValue: bigint, minOut: bigint): TxRequest;
+/** Latch the trigger and claim in one call, which is what a UI should always send. */
+export declare function buildClaim(deployment: Deployment, policyId: bigint): TxRequest;
+/**
+ * Sell the insured position and end the cover, in one transaction.
+ *
+ * The core escrows the position for the life of the policy, so a holder cannot sell it the
+ * ordinary way. Without this a partner can only offer "wait for expiry", which is not a
+ * product -- the whole point of the escrow design was that leaving stays a single click.
+ *
+ * `minOut` is a slippage bound on the sale proceeds in wei, not in tokens.
+ */
+export declare function buildSellAndVoid(deployment: Deployment, policyId: bigint, minOut: bigint): TxRequest;
+/**
+ * Take the position back out of escrow and end the cover, without selling.
+ *
+ * For a holder who wants to keep the tokens. Also the only exit when no venue is registered
+ * for the token, since `sellAndVoid` needs somewhere to route the sale.
+ */
+export declare function buildVoidAndRelease(deployment: Deployment, policyId: bigint): TxRequest;
+export declare function buildPartnerClaim(deployment: Deployment, to: Address): TxRequest;
+/** Slippage bound from an expected output. `bps` is tolerance, so 100 is 1%. */
+export declare function minOutWithSlippage(expectedOut: bigint, bps: number): bigint;

package/dist/tx/build.js

@@ -0,0 +1,92 @@
+import { encodeFunctionData } from "viem";
+import { universalRouterAbi, insuranceCoreAbi, partnerRegistryAbi } from "../abi.js";
+/**
+ * Build the buy-with-cover call.
+ *
+ * The SDK never holds keys and never submits. Partners keep custody and their own UX; this
+ * returns a request for them to sign. That is the difference between integrating with a bot
+ * and becoming one, and it keeps the security surface of a custodial exchange out of scope.
+ */
+export function buildBuyWithCover(params) {
+    const { deployment, token, totalValue, minOut, tier, referrer } = params;
+    if (totalValue <= 0n)
+        throw new Error("totalValue must be positive");
+    if (!Number.isInteger(tier) || tier < 0)
+        throw new Error("tier must be a non-negative integer");
+    const data = referrer
+        ? encodeFunctionData({
+            abi: universalRouterAbi,
+            functionName: "buyWithCoverVia",
+            args: [token, minOut, tier, referrer],
+        })
+        : encodeFunctionData({
+            abi: universalRouterAbi,
+            functionName: "buyWithCover",
+            args: [token, minOut, tier],
+        });
+    return { to: deployment.router, data, value: totalValue };
+}
+export function buildBuyWithoutCover(deployment, token, totalValue, minOut) {
+    if (totalValue <= 0n)
+        throw new Error("totalValue must be positive");
+    return {
+        to: deployment.router,
+        data: encodeFunctionData({ abi: universalRouterAbi, functionName: "buy", args: [token, minOut] }),
+        value: totalValue,
+    };
+}
+/** Latch the trigger and claim in one call, which is what a UI should always send. */
+export function buildClaim(deployment, policyId) {
+    return {
+        to: deployment.core,
+        data: encodeFunctionData({ abi: insuranceCoreAbi, functionName: "latchAndClaim", args: [policyId] }),
+        value: 0n,
+    };
+}
+/**
+ * Sell the insured position and end the cover, in one transaction.
+ *
+ * The core escrows the position for the life of the policy, so a holder cannot sell it the
+ * ordinary way. Without this a partner can only offer "wait for expiry", which is not a
+ * product -- the whole point of the escrow design was that leaving stays a single click.
+ *
+ * `minOut` is a slippage bound on the sale proceeds in wei, not in tokens.
+ */
+export function buildSellAndVoid(deployment, policyId, minOut) {
+    if (minOut < 0n)
+        throw new Error("minOut must not be negative");
+    return {
+        to: deployment.core,
+        data: encodeFunctionData({ abi: insuranceCoreAbi, functionName: "sellAndVoid", args: [policyId, minOut] }),
+        value: 0n,
+    };
+}
+/**
+ * Take the position back out of escrow and end the cover, without selling.
+ *
+ * For a holder who wants to keep the tokens. Also the only exit when no venue is registered
+ * for the token, since `sellAndVoid` needs somewhere to route the sale.
+ */
+export function buildVoidAndRelease(deployment, policyId) {
+    return {
+        to: deployment.core,
+        data: encodeFunctionData({ abi: insuranceCoreAbi, functionName: "voidAndRelease", args: [policyId] }),
+        value: 0n,
+    };
+}
+export function buildPartnerClaim(deployment, to) {
+    if (!deployment.partnerRegistry) {
+        throw new Error(`${deployment.name} has no partner registry`);
+    }
+    return {
+        to: deployment.partnerRegistry,
+        data: encodeFunctionData({ abi: partnerRegistryAbi, functionName: "claim", args: [to] }),
+        value: 0n,
+    };
+}
+/** Slippage bound from an expected output. `bps` is tolerance, so 100 is 1%. */
+export function minOutWithSlippage(expectedOut, bps) {
+    if (bps < 0 || bps > 10_000)
+        throw new Error("slippage must be between 0 and 10000 bps");
+    return (expectedOut * BigInt(10_000 - bps)) / 10000n;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@degen-insurance/sdk",
+  "version": "0.2.0",
+  "description": "Build Degen Trade Insurance transactions, quotes and alerts. Never holds keys.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "verify-package": "node scripts/verify-package.mjs",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build && npm run verify-package"
+  },
+  "peerDependencies": {
+    "viem": ">=2.21.0 <3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^5.6.3",
+    "viem": "^2.21.0",
+    "vitest": "^2.1.3"
+  }
+}