@degen-insurance/sdk 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+This package is versioned independently of the protocol. Breaking changes are called out
+because partners pin a version and need to know what moved.
+
+## 0.2.0
+
+The SDK had not been updated since before the protocol escrowed insured positions, so parts of
+it described a system that no longer existed.
+
+### Breaking
+
+- **Builders take a `Deployment` instead of loose addresses.** `buildBuyWithCover` now takes
+  `{ deployment, ... }` rather than `{ router, ... }`; `buildClaim`, `buildSellAndVoid`,
+  `buildVoidAndRelease` and `buildPartnerClaim` take a deployment as their first argument. This
+  is what makes multi-chain safe: addresses that have to agree now travel together, so one
+  chain's core with another's router cannot be expressed. There is deliberately no `setChain()`
+  — a global current-chain races when a bot serves several chains at once.
+- **`TIERS` is now `ROBINHOOD_RATE_CARD`,** named for the chain it was measured on, and
+  `tierById(card, id)` takes the card. Premiums are the deliverable of a calibration run and
+  belong to one chain; the contracts revert `NoRateCard` elsewhere rather than reuse them, and
+  this package now holds the same line.
+- **`PolicyView.stillHeld` is gone.** It was read from the holder's token balance, which under
+  escrow is zero for every live policy — so it answered "sold" every time. Anyone branching on
+  it was disabling claims on every policy in existence.
+- **`position_sold` alert is now `cover_ended`,** and `PolicyStatus` gains `voided`.
+
+### Added
+
+- `buildSellAndVoid` and `buildVoidAndRelease` — the two ways out of an escrowed position.
+  Without them a partner can only offer "wait for expiry".
+- `amountRange`, `shareHeadroom`, `notionalForTokens`, `maxTotalForCapacity` — what a user may
+  actually buy. Three limits decide it, denominated in three different things: the registry's
+  bounds are notional, capacity is a payout, the share cap counts tokens.
+- `explainRevert` and `REVERT_REASONS` — 31 contract errors in plain language, so a bot can say
+  "that amount is below the minimum trade size" rather than relaying `0xeddee5b2`. Returns
+  `null` when it cannot attribute a failure, so a transport error is never reported as a
+  rejected trade.
+- `readRateCard` and `assertRateCard` — read the live card, and fail loudly if a local one
+  disagrees.
+- `assertChain`, `defineDeployment`, `ROBINHOOD_TESTNET`.
+
+### Packaging
+
+- Ships compiled JavaScript and type declarations. Sources, tests and every document except
+  this changelog and the README stay out of the tarball, enforced by `verify-package`.
+- `viem` moved to `peerDependencies`. A second copy in a consumer's tree means two sets of
+  structurally identical, mutually incompatible types.
+- MIT licence added.
+
+## 0.1.0
+
+First release: transaction builders, partner revenue share, alert state machine, Telegram
+rendering.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vetted-Pro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# @degen-insurance/sdk
+
+```sh
+npm install @degen-insurance/sdk viem
+```
+
+`viem` is a peer dependency: you almost certainly have it already, and a second copy in the
+tree means two sets of structurally identical, mutually incompatible types.
+
+Ships compiled JavaScript with type declarations. Requires Node 18+ or any bundler; ESM only.
+
+Integration surface for Telegram bots and front ends. Maestro is already live on Robinhood
+Chain and NockBot is native to it, so distribution exists without building a custodial bot.
+
+Publishing is documented in [RELEASING.md](RELEASING.md).
+
+## The SDK never holds keys
+
+It builds transaction requests. Partners keep custody and their own UX and sign with the user's
+key. That is the difference between integrating with a bot and becoming one, and it keeps the
+security and regulatory surface of a custodial exchange out of scope entirely.
+
+```ts
+import { buildBuyWithCover, minOutWithSlippage, ROBINHOOD_TESTNET } from "@degen-insurance/sdk";
+
+const tx = buildBuyWithCover({
+  deployment: ROBINHOOD_TESTNET,
+  token,
+  totalValue: parseEther("1.1"),      // trade plus premium, one payment
+  minOut: minOutWithSlippage(quoted, 100),
+  tier: 2,                             // 0 Basic, 1 Standard, 2 Degen Max
+  referrer: MY_BOT_ADDRESS,            // earns the revenue share
+});
+await walletClient.sendTransaction(tx);
+```
+
+## Chains
+
+There is no `setChain()`, deliberately. A setter implies one current chain, which is fine for a
+browser tab and wrong for a bot serving many users at once: two requests for different chains
+arriving together would race on the global, and the loser would build calldata for one chain and
+send it to another. A `Deployment` is a value, and values cannot race.
+
+```ts
+const tx = buildBuyWithCover({ deployment: ROBINHOOD_TESTNET, token, ... });
+// somewhere else, at the same time, safely:
+const other = buildBuyWithCover({ deployment: MY_OTHER_CHAIN, token, ... });
+```
+
+It also keeps addresses that have to agree travelling together. There is no signature that
+takes `core` and `router` separately any more, so one chain's core with another's router cannot
+be expressed.
+
+`ROBINHOOD_TESTNET` is the only deployment shipped, because it is the only one whose addresses
+have been checked against the chain from here. Robinhood mainnet has a deployment in
+`broadcast/`; define it yourself once you have confirmed it:
+
+```ts
+const ROBINHOOD = defineDeployment({
+  chainId: 4663, name: "Robinhood Chain",
+  core: "0x...", router: "0x...", registry: "0x...", partnerRegistry: "0x...",
+  calibrated: true,
+});
+await assertChain(publicClient, ROBINHOOD);   // before signing anything
+```
+
+`assertChain` is worth the round trip. A client on the wrong RPC produces calldata that is
+perfectly well formed and addressed to contracts that are not there, and the failure arrives as
+an unrelated-looking revert.
+
+## Premiums belong to the chain they were measured on
+
+`ROBINHOOD_RATE_CARD` is named for its chain 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()` in the contracts 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 tokens collapse in
+one chain's flow, not a property of the product.
+
+Use the local card to render a quote before you have a connection. Once you have one, read the
+real card and check:
+
+```ts
+const card = await readRateCard(publicClient, deployment.registry, riskRegistryAbi);
+assertRateCard(ROBINHOOD_RATE_CARD, card);   // throws if this deployment prices differently
+
+const range = amountRange(capacity, tierById(card, 2), limits);
+```
+
+Quoting one chain's premiums against another chain's risk is the failure worth being noisy
+about: the trade succeeds, at the wrong price, and nothing downstream looks wrong.
+
+## Revenue share
+
+Pass `referrer` and the partner accrues a share of the premium, claimable at any time. The
+trader pays the same tier rate either way: the share comes out of protocol revenue, not out of
+the buyer's premium and not out of reserves. Partner revenue is junior to policyholders and can
+only be paid from free reserves.
+
+```ts
+await walletClient.sendTransaction(buildPartnerClaim(deployment, myTreasury));
+```
+
+## Alerts
+
+For insurance the alerts are worth more than in-chat buying, and they need no custody at all.
+
+```ts
+const { alerts, sent } = sweep(policies, now, alreadySent);
+for (const a of alerts) {
+  await bot.sendMessage(chatId, renderAlert(a, byId[a.policyId], now), {
+    parse_mode: "MarkdownV2",
+    reply_markup: a.kind === "triggered_claimable" ? claimKeyboard(a.policyId, DEEP_LINK) : undefined,
+  });
+}
+```
+
+Delivery is once per kind per policy. Repeating an alert on every poll trains people to mute
+the bot, and then they miss the one message that mattered. Persist `sent` between runs.
+
+## Claiming
+
+Always `buildClaim`, which sends `latchAndClaim`. Claiming without latching fails whenever
+nobody else happened to record the trigger first.
+
+## Leaving early
+
+The core holds the insured position in escrow for the life of the policy, so a holder cannot
+sell it the ordinary way. That is what makes a claim honest -- the payout is for a loss taken
+by holding, and custody proves the position was held the whole time rather than borrowed for
+one transaction. It also means a partner has to offer the exit, or users are stuck until
+expiry.
+
+```ts
+// Sell and end the cover, in one transaction. Costs no more than selling would have.
+await walletClient.sendTransaction(buildSellAndVoid(deployment, policyId, minOutWei));
+
+// Or take the tokens back and keep them. Ends the cover too.
+await walletClient.sendTransaction(buildVoidAndRelease(deployment, policyId));
+```
+
+Either leaves the policy `voided`, which is a normal outcome and not a failure. Do not read a
+holder's token balance to decide whether cover is live: under escrow it is zero for every
+active policy, and treating that as "sold" disables claiming on everything.
+
+## Amount limits
+
+Three limits decide what a user may buy, 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*. Quoting any one of them at a user is misleading -- capacity in
+particular is 2.2x smaller than the trade it supports at Degen Max.
+
+```ts
+const limits = riskLimitsFromParams(await core.read.getParams());
+const room = shareHeadroom(supply, walletTokensInsured, tokenTokensInsured, limits);
+const range = amountRange(remainingCapacity, tierById(card, 2), {
+  ...limits,
+  maxShareNotionalWei: notionalForTokens(pool, room),
+});
+// -> "Enter between 0.00011 and 0.001214 ETH"
+```
+
+Both share caps are cumulative, so headroom depends on the wallet and on every policy already
+open against the token. A band computed for a fresh wallet will be refused for a busy one.
+`amountRange` keeps a 1% margin under the share cap because that cap counts tokens while the
+user pays in the quote asset, and the rate between them moves on every trade.
+
+## Explaining a refusal
+
+A wallet that cannot estimate gas has no fee to show and no way to say why, so a reverting buy
+reaches the user as "Network fee: Unavailable" or a bare selector. Simulate first and say what
+happened.
+
+```ts
+try {
+  await publicClient.call({ ...tx, account: user });
+} catch (err) {
+  const why = explainRevert(err);
+  if (why) return bot.sendMessage(chatId, why);
+  throw err;                      // not a refusal -- do not report it as one
+}
+```
+
+`explainRevert` returns `null` when it cannot attribute the failure, so a transport error is
+never reported to a user as a rejected trade. 31 selectors are mapped, each pinned by a test
+that derives the expected set from the Solidity source.

package/dist/abi.d.ts

@@ -0,0 +1,418 @@
+export declare const universalRouterAbi: readonly [{
+    readonly name: "buyWithCover";
+    readonly type: "function";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "token";
+    }, {
+        readonly type: "uint256";
+        readonly name: "minOut";
+    }, {
+        readonly type: "uint8";
+        readonly name: "tier";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "received";
+    }, {
+        readonly type: "uint256";
+        readonly name: "policyId";
+    }];
+}, {
+    readonly name: "buyWithCoverVia";
+    readonly type: "function";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "token";
+    }, {
+        readonly type: "uint256";
+        readonly name: "minOut";
+    }, {
+        readonly type: "uint8";
+        readonly name: "tier";
+    }, {
+        readonly type: "address";
+        readonly name: "referrer";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "received";
+    }, {
+        readonly type: "uint256";
+        readonly name: "policyId";
+    }];
+}, {
+    readonly name: "buy";
+    readonly type: "function";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "token";
+    }, {
+        readonly type: "uint256";
+        readonly name: "minOut";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "received";
+    }];
+}, {
+    readonly name: "previewCover";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint8";
+        readonly name: "tier";
+    }, {
+        readonly type: "uint256";
+        readonly name: "totalValue";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "notional";
+    }, {
+        readonly type: "uint256";
+        readonly name: "premium";
+    }];
+}];
+export declare const insuranceCoreAbi: readonly [{
+    readonly name: "latchTrigger";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "token";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "claim";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "id";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "latchAndClaim";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "id";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "remainingCapacity";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "token";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "sellAndVoid";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "id";
+    }, {
+        readonly type: "uint256";
+        readonly name: "minOut";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "voidAndRelease";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "id";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "policyCount";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "policies";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "id";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly type: "address";
+        }, {
+            readonly type: "uint96";
+        }, {
+            readonly type: "address";
+        }, {
+            readonly type: "uint48";
+        }, {
+            readonly type: "uint48";
+        }, {
+            readonly type: "uint128";
+        }, {
+            readonly type: "uint128";
+        }, {
+            readonly type: "uint128";
+        }, {
+            readonly type: "uint128";
+        }, {
+            readonly type: "uint8";
+        }, {
+            readonly type: "uint8";
+        }, {
+            readonly type: "uint16";
+        }];
+    }];
+}, {
+    readonly name: "quote";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "token";
+    }, {
+        readonly type: "uint256";
+        readonly name: "notional";
+    }, {
+        readonly type: "uint256";
+        readonly name: "tokensOut";
+    }, {
+        readonly type: "uint8";
+        readonly name: "tier";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "premium";
+    }, {
+        readonly type: "uint256";
+        readonly name: "payout";
+    }, {
+        readonly type: "uint256";
+        readonly name: "entryPrice";
+    }, {
+        readonly type: "uint256";
+        readonly name: "floorPrice";
+    }];
+}, {
+    readonly name: "walletTokensInsured";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "token";
+    }, {
+        readonly type: "address";
+        readonly name: "holder";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "tokenTokensInsured";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "token";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}];
+export declare const riskRegistryAbi: readonly [{
+    readonly name: "checkToken";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "token";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+        readonly name: "ok";
+    }, {
+        readonly type: "uint8";
+        readonly name: "reason";
+    }];
+}, {
+    readonly name: "tiers";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "id";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly type: "uint16";
+        }, {
+            readonly type: "uint16";
+        }, {
+            readonly type: "uint16";
+        }, {
+            readonly type: "bool";
+        }];
+    }];
+}, {
+    readonly name: "getParams";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly type: "uint32";
+        }, {
+            readonly type: "uint32";
+        }, {
+            readonly type: "uint32";
+        }, {
+            readonly type: "uint16";
+        }, {
+            readonly type: "uint16";
+        }, {
+            readonly type: "uint16";
+        }, {
+            readonly type: "uint16";
+        }, {
+            readonly type: "uint16";
+        }, {
+            readonly type: "uint16";
+        }, {
+            readonly type: "uint128";
+        }, {
+            readonly type: "uint128";
+        }, {
+            readonly type: "uint128";
+        }, {
+            readonly type: "uint128";
+        }];
+    }];
+}];
+export declare const launchPoolAbi: readonly [{
+    readonly name: "quoteReserve";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "tokenReserve";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "feeBps";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint16";
+    }];
+}, {
+    readonly name: "launchPrice";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "spotPrice";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}];
+export declare const erc20Abi: readonly [{
+    readonly name: "balanceOf";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "totalSupply";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "symbol";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly name: "decimals";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint8";
+    }];
+}];
+export declare const partnerRegistryAbi: readonly [{
+    readonly name: "outstanding";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "partner";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "claim";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "to";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}];