@thetanuts-finance/odette-cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thetanuts Finance
+
+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/NOTICE.md

@@ -0,0 +1,65 @@
+# NOTICE
+
+This repository adapts code from **thetanuts-sdk**
+(<https://github.com/Thetanuts-Finance/thetanuts-sdk>), MIT License,
+Copyright (c) 2026 Thetanuts Finance. Source commit:
+`9e72aef1ab5c008ccc92352fa5048bd08c452ede`.
+
+Each file below keeps the Thetanuts Finance MIT notice in its header, and the
+header lists what changed.
+
+## SDK (`packages/sdk/src`)
+
+| File | Source in thetanuts-sdk | How |
+|---|---|---|
+| `abi/optionBook.ts` | `src/abis/optionBook.ts` | Copied as-is |
+| `abi/erc20.ts` | `src/abis/erc20.ts` | Copied as-is |
+| `chain.ts` | `src/chains/index.ts` (Base block) | Addresses only |
+| `client.ts` | `src/client/ThetanutsClient.ts` | Trimmed; fixed referrer; Base only |
+| `errors.ts` | `src/types/errors.ts`, `src/utils/errors.ts` | Trimmed; renamed to `OdetteError` |
+| `logger.ts` | `src/utils/logger.ts`, `src/types/logger.ts` | Renamed to `OdetteLogger` |
+| `types.ts` | `src/types/optionBook.ts`, `src/types/api.ts` | Trimmed to the feed order shape |
+| `feed.ts` | `src/modules/api.ts` (`fetchOrders`) | Rewritten on `fetch`, strict field checks |
+| `normalize.ts` | `src/modules/api.ts` (`normalizeOdetteOrder`) | Typed input; no 0 / "" fallbacks |
+| `modules/optionBook.ts` | `src/modules/optionBook.ts` | Trimmed; fixed referrer; Odette sizing and checks |
+| `modules/erc20.ts` | `src/modules/erc20.ts` | Trimmed (no transfer, no callStatic) |
+| `modules/utils.ts` | `src/modules/utils.ts` | `toBigInt`, `fromBigInt` only |
+| `utils/decimals.ts` | `src/utils/decimals.ts` | `toBigInt`, `fromBigInt` only |
+| `utils/validation.ts` | `src/utils/validation.ts` | `validateAddress` only |
+
+## CLI (`packages/cli/src`)
+
+| File | Source in thetanuts-sdk | How |
+|---|---|---|
+| `index.ts` | `cli/src/index.ts` | Name and description |
+| `options.ts` | `cli/src/options.ts` | No `--chain`, no `--referrer` |
+| `client.ts` | `cli/src/client.ts` | `OdetteClient`; no referrer resolution; no RFQ keystore |
+| `config.ts` | `cli/src/config.ts` | `~/.config/odette`; a `referrer` key is an error |
+| `confirm.ts` | `cli/src/confirm.ts` | Unchanged |
+| `defaults.ts` | `cli/src/defaults.ts` | Comments |
+| `output.ts` | `cli/src/output.ts` | Comments |
+| `format.ts` | `cli/src/format.ts` | Unchanged |
+| `bookEligibility.ts` | `cli/src/bookEligibility.ts` | Import only |
+| `bookMatch.ts` | `cli/src/bookMatch.ts` | Import only |
+| `bookOrderIdentity.ts` | `cli/src/bookOrderIdentity.ts` | Adds `findSameInstrument` (Odette re-signs orders) |
+| `bookPreview.ts` | `cli/src/bookPreview.ts` | Unchanged |
+| `bookCheck.ts` | `cli/src/bookCheck.ts` | No RFQ recommendation |
+| `commands/book.ts` | `cli/src/commands/book.ts` | Top-level commands; no payout block; pre-send checks |
+| `commands/wallet.ts` | `cli/src/commands/wallet.ts` | No `transfer`; approve is USDC to the OptionBook only |
+| `commands/setup.ts` | `cli/src/commands/setup.ts` | No referrer prompt |
+| `commands/config.ts` | `cli/src/commands/config.ts` | `referrer` refused |
+| `commands/registry.ts` | `cli/src/commands/registry.ts` | Odette commands only |
+
+Test patterns (not copied code): `cli/tests/exitCodes.test.ts`.
+
+## Ported from the Odette web app
+
+These files port rules from `thetaverse/odette` (Thetanuts' Odette web app) at
+`origin/dev` `5c3f2b0639ce07a134a0f82b7df8113dea1e744b`, checked against the
+OptionBook and option contracts in `thetanuts_rfq` at
+`2c830620861eefcca895fb8e2a60b8f3fa915e7f`. They carry the same MIT notice.
+
+| File | Source |
+|---|---|
+| `packages/sdk/src/whitelist.ts` | `odette/config.js`: implementation constants, `isSpreadOrder`, `isDirectionalOrder`, `isRangerOrder`, `CANONICAL_ASSETS`, `COLLATERAL_TOKENS`, `filterOrdersForDailyBook`, `EXPIRY_FILTER_LIMITS`, `isAssetAvailableOnDay`; `ui_interactions.js` `isOrderExpiringSoon` |
+| `packages/sdk/src/sizing.ts` | `odette/config.js`: `getContractQuantumStrike`, `getMaxRawContracts`, `validateNumContractsForContract`, `calculateMaxContracts`, `getMinimumPercentage`, `MIN_PREMIUM_USD` |

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# Odette SDK and CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Buy Odette options on Base from your terminal or your own code.
+
+- **`odette`**, the command-line tool: `@thetanuts-finance/odette-cli`
+- **The SDK**, a TypeScript library: `@thetanuts-finance/odette-sdk`
+
+Odette runs on Thetanuts Finance contracts on Base. You sign every trade with your
+own wallet. No trade goes through a server: `odette` only reads the public order
+list and sends your signed transaction straight to Base.
+
+## What you can do
+
+- See the options Odette lists right now: PUT, CALL (LINEAR_CALL) and RANGER.
+- Check a trade before you make it.
+- Buy an option with USDC.
+
+The tools only **buy**. They do not sell or close positions. Odette options are
+cash-settled in USDC at expiry, so there is nothing to close.
+
+## Before you start
+
+- [Node.js](https://nodejs.org) 20 or newer
+- A wallet on **Base** with:
+  - **USDC**, to pay for the option (the minimum trade is 0.50 USDC)
+  - a little **ETH**, for gas (a trade costs a few cents)
+
+## Install
+
+```sh
+npm install -g @thetanuts-finance/odette-cli
+```
+
+## Set up your wallet (once)
+
+Use the wallet you already have:
+
+```sh
+odette wallet import
+```
+
+Paste your private key when asked. You won't see it as you paste, and that's expected.
+
+Don't have one? `odette wallet create` makes a new wallet. Then send it USDC and some ETH on Base.
+
+Your key is saved only on your computer, in `~/.config/odette/config.json`, and only you
+can read that file. **Never share your private key or paste it into a chat.**
+
+Check it worked:
+
+```sh
+odette wallet show       # your address
+odette wallet balance    # your ETH and USDC
+```
+
+## Make a trade
+
+**1. See what's on offer.**
+
+```sh
+odette orders --underlying ETH --type PUT
+```
+
+Each row is one option: its strike price, the expiry date and time, and the price of one contract.
+`--type` can be `PUT`, `CALL` or `RANGER`.
+
+**2. Check the trade.** Pick a strike and expiry from the list. `--collateral` is how
+much USDC you want to spend. (The strike and expiry below are examples: copy real
+ones from `odette orders`, because options expire every day.)
+
+```sh
+odette preview --underlying ETH --type PUT --strike 2200 --expiry 1793174400 --collateral 5
+```
+
+This shows how many contracts you get, and runs safety checks:
+does the seller have the funds, do you have enough USDC, is the quote still live.
+Nothing is sent.
+
+**3. Buy.**
+
+```sh
+odette fill --underlying ETH --type PUT --strike 2200 --expiry 1793174400 --collateral 5
+```
+
+The first time, `odette` asks you to let the Odette contract take your USDC. That
+permission is called an approval. Then it asks you to confirm the trade. Answer `y`
+to both. When it's done, it prints the transaction link.
+
+Prices update about once a minute. If the price moves while you're deciding, `odette`
+shows the new price and asks you again.
+
+Want to see the transaction without sending it? Add `--dry-run`. With `--yes` (no
+questions), `--collateral` is required, so `odette` never buys a maximum size by itself.
+
+**Buying a RANGER.** A RANGER pays out if the price ends inside a range. It has
+four strikes, so use `--type RANGER` with `--strikes`:
+
+```sh
+odette orders --underlying BTC --type RANGER
+odette preview --underlying BTC --type RANGER --strikes 78500,79000,80000,80500 --expiry 1793174400 --collateral 5
+```
+
+`preview` shows what you pay (`premium`) and the most you can be paid at expiry (`maxPayout`). In `-o json`
+output the premium is the `totalCollateral` field (the name upstream uses).
+
+## Useful flags
+
+| Flag | What it does |
+|---|---|
+| `--dry-run` | Show what would happen. Send nothing. |
+| `--yes` | Skip the questions (the safety checks still run). |
+| `-o json` | Print JSON, for scripts. |
+| `--rpc-url <url>` | Use your own Base RPC instead of the public one. |
+
+Exit codes for scripts: `0` ok, `1` the trade or a check failed, `2` a wrong command or flag,
+`3` you said no, `4` a wallet or config problem.
+
+## For developers: the SDK
+
+```sh
+npm install @thetanuts-finance/odette-sdk ethers
+```
+
+```ts
+import { JsonRpcProvider, Wallet } from 'ethers';
+import { OdetteClient } from '@thetanuts-finance/odette-sdk';
+
+const provider = new JsonRpcProvider('https://mainnet.base.org');
+const signer = new Wallet(process.env.ODETTE_PRIVATE_KEY!, provider);
+const client = new OdetteClient({ provider, signer });
+
+const orders = await client.api.fetchOrders();
+const order = orders.find((o) => o.product === 'PUT' && o.underlying === 'ETH')!;
+
+const usdc = 5_000000n; // 5 USDC (USDC has 6 decimals)
+const preview = client.optionBook.previewFillOrder(order, usdc);
+const checks = await client.optionBook.checkFill(order, usdc); // reads only, never sends
+
+await client.erc20.ensureAllowance(preview.collateralToken, preview.optionBook, preview.totalCollateral);
+const receipt = await client.optionBook.fillOrder(order, usdc); // refuses if a check fails
+```
+
+Amounts: USDC and contract sizes have 6 decimals. Prices and strikes are in USD with 8 decimals.
+The amount you pass is the USDC you want to spend, not a number of contracts.
+
+## Good to know
+
+- **Base only** (chain 8453).
+- **Found a security problem?** Don't open a public issue. See `SECURITY.md`.
+- **Every trade is tagged with Odette's referrer**, `0x94D784e81A5c8cA6E19629C73217b61a256Ea1c7`.
+  You can't change it in these tools. The contract itself does not enforce the tag.
+- Orders and contracts come from Thetanuts Finance. Odette is the app on top.
+
+## License
+
+MIT, Copyright (c) 2026 Thetanuts Finance. Parts are adapted from
+[thetanuts-sdk](https://github.com/Thetanuts-Finance/thetanuts-sdk); see `NOTICE.md`.

package/dist/bookCheck.js

@@ -0,0 +1,305 @@
+import { ORDER_PRICE_DECIMALS } from './bookEligibility.js';
+import { findMatchingOrders, orderStrikesUsd, ordersWithStrikeAsLeg, structureInfo, usdToStrikeRaw, } from './bookMatch.js';
+const NEARBY_TOLERANCE = 0.05;
+const DAPP_URL = 'https://odette.fi';
+function isoOf(expiry) {
+    return new Date(expiry * 1000).toISOString();
+}
+function utcDate(expiry) {
+    return isoOf(expiry).slice(0, 10);
+}
+function priceOf(order) {
+    return order.order?.price ? Number(order.order.price) / 10 ** ORDER_PRICE_DECIMALS : 0;
+}
+function strikesCsv(strikesUsd) {
+    return strikesUsd.join(',');
+}
+export function computeCheckResult(orders, params, ctx) {
+    const indexOf = new Map();
+    orders.forEach((o, i) => indexOf.set(o, i));
+    const strikeRaw = usdToStrikeRaw(params.strike);
+    const side = params.direction === 'buy' ? 'ASK' : 'BID';
+    const contracts = (o) => Number(ctx.maxContracts(o)) / ctx.contractScale;
+    const describe = (o) => structureInfo(o, params.underlying, ctx.implementations);
+    // Everything on this feed/type, regardless of expiry — used for the
+    // "your expiry has no book at all" branch.
+    const sameInstrument = orders.filter((o) => {
+        const raw = o.rawApiData;
+        if (!raw)
+            return false;
+        const orderType = raw.isCall ? 'CALL' : 'PUT';
+        return orderType === params.type && raw.priceFeed?.toLowerCase() === ctx.priceFeed;
+    });
+    const atExpiry = sameInstrument.filter((o) => Number(o.order.expiry) === params.expiry);
+    const liveExpiryMap = new Map();
+    for (const o of sameInstrument) {
+        const e = Number(o.order.expiry);
+        let entry = liveExpiryMap.get(e);
+        if (!entry) {
+            entry = { expiry: e, iso: isoOf(e), vanillaCount: 0, structureCount: 0 };
+            liveExpiryMap.set(e, entry);
+        }
+        if (orderStrikesUsd(o).length > 1)
+            entry.structureCount += 1;
+        else
+            entry.vanillaCount += 1;
+    }
+    const liveExpiries = [...liveExpiryMap.values()].sort((a, b) => a.expiry - b.expiry);
+    // Same UTC date as the requested expiry. Never auto-snap: the book carries
+    // both an 03:00Z and an 08:00Z expiry on some dates, so picking one for the
+    // caller would be a guess with money attached.
+    const didYouMean = liveExpiries
+        .filter((e) => e.expiry !== params.expiry && utcDate(e.expiry) === utcDate(params.expiry))
+        .map((e) => e.expiry);
+    // The Odette referrer is fixed, so emitted commands need no referrer flag.
+    const previewBase = `odette preview --underlying ${params.underlying} --type ${params.type}`;
+    // Odette has no RFQ. When the book has nothing here, say so in prose.
+    const noOrderStep = `No Odette order matches. Run \`odette orders --underlying ${params.underlying} --type ${params.type}\` ` +
+        'and pick a listed strike and expiry.';
+    const dappStep = `Fill this ${params.direction === 'buy' ? 'ask' : 'bid'} in the Odette app (${DAPP_URL}) — ` +
+        'the CLI executes buys only.';
+    // --- 1. Exact single-strike instrument -----------------------------------
+    const exact = findMatchingOrders(atExpiry, {
+        priceFeed: ctx.priceFeed,
+        type: params.type,
+        strikesRaw: [strikeRaw],
+        expiry: params.expiry,
+    });
+    // Best price first, matching how `resolveOrderBySelector` picks (strictly
+    // lowest price for a buy, first-encountered on a tie — Array#sort is stable,
+    // so `orderbookOrders[0]` IS the order the emitted command resolves to).
+    const orderbookOrders = exact
+        .map((o) => {
+        const info = describe(o);
+        return {
+            index: indexOf.get(o) ?? -1,
+            ticker: info.ticker,
+            type: params.type,
+            strike: params.strike,
+            expiry: Number(o.order.expiry),
+            expiryDate: isoOf(Number(o.order.expiry)),
+            side,
+            price: priceOf(o),
+            availableContracts: contracts(o),
+            maker: o.makerAddress ?? o.order?.maker ?? '',
+        };
+    })
+        .sort((a, b) => (params.direction === 'buy' ? a.price - b.price : b.price - a.price));
+    const levelMap = new Map();
+    for (const o of orderbookOrders) {
+        let level = levelMap.get(o.price);
+        if (!level) {
+            level = { price: o.price, availableContracts: 0, orders: 0 };
+            levelMap.set(o.price, level);
+        }
+        level.availableContracts += o.availableContracts;
+        level.orders += 1;
+    }
+    const priceLevels = [...levelMap.values()].sort((a, b) => params.direction === 'buy' ? a.price - b.price : b.price - a.price);
+    // --- 2. Structures carrying the strike on any leg ------------------------
+    //
+    // Deliberately NOT ranked. A spread, a fly and a ranger that happen to share
+    // one strike are different products: their whole-structure premiums are not
+    // comparable, and the requested strike can be a long, short or middle leg —
+    // so "cheapest" could hand the caller exposure opposite to the vanilla they
+    // asked about. Sorted by price only for a stable, inspectable listing.
+    const legMatches = ordersWithStrikeAsLeg(atExpiry, ctx.priceFeed, params.type, params.expiry, strikeRaw);
+    const structureMatches = legMatches
+        .map(({ order, legIndex }) => {
+        const info = describe(order);
+        const expiry = Number(order.order.expiry);
+        const availableContracts = contracts(order);
+        return {
+            index: indexOf.get(order) ?? -1,
+            structure: info.name,
+            structureKind: info.kind,
+            ticker: info.ticker,
+            strikes: info.strikesUsd,
+            legIndex,
+            legCount: info.strikesUsd.length,
+            structurePrice: priceOf(order),
+            availableContracts,
+            meetsRequestedSize: params.size === undefined ? null : availableContracts >= params.size,
+            expiry,
+            expiryDate: isoOf(expiry),
+            maker: order.makerAddress ?? order.order?.maker ?? '',
+            // `book preview` filters to asks, so its command form is meaningless
+            // for a sell-side match — emit the manual action instead.
+            nextStep: ctx.cliExecutable
+                ? `${previewBase} --strikes ${strikesCsv(info.strikesUsd)} ` +
+                    `--expiry ${expiry} --collateral <amount>`
+                : dappStep,
+            nextStepIsCommand: ctx.cliExecutable,
+        };
+    })
+        .sort((a, b) => a.structurePrice - b.structurePrice);
+    // --- 3. Nearby vanilla strikes (same expiry, within tolerance) -----------
+    const tolerance = params.strike * NEARBY_TOLERANCE;
+    const nearbyByStrike = new Map();
+    for (const o of atExpiry) {
+        const strikes = orderStrikesUsd(o);
+        if (strikes.length !== 1)
+            continue;
+        const s = strikes[0];
+        if (s === params.strike)
+            continue;
+        if (Math.abs(s - params.strike) > tolerance)
+            continue;
+        if (!nearbyByStrike.has(s))
+            nearbyByStrike.set(s, []);
+        nearbyByStrike.get(s).push(o);
+    }
+    const nearbyStrikes = [...nearbyByStrike.entries()]
+        .map(([strike, group]) => {
+        const best = group.reduce((acc, curr) => params.direction === 'buy'
+            ? priceOf(curr) < priceOf(acc)
+                ? curr
+                : acc
+            : priceOf(curr) > priceOf(acc)
+                ? curr
+                : acc);
+        const diff = (((strike - params.strike) / params.strike) * 100).toFixed(1);
+        return {
+            strike,
+            priceDiff: `${parseFloat(diff) >= 0 ? '+' : ''}${diff}%`,
+            bestPrice: priceOf(best),
+            availableContracts: group.reduce((sum, o) => sum + contracts(o), 0),
+            orderIndex: indexOf.get(best) ?? -1,
+        };
+    })
+        .sort((a, b) => Math.abs(a.strike - params.strike) - Math.abs(b.strike - params.strike))
+        .slice(0, 5);
+    // --- Aggregate vanilla availability --------------------------------------
+    const totalAvailable = orderbookOrders.reduce((sum, o) => sum + o.availableContracts, 0);
+    const bestPrice = orderbookOrders.length > 0 ? orderbookOrders[0].price : null;
+    // What ONE `book fill` against the recommended command can actually take.
+    const topOrderSize = orderbookOrders.length > 0 ? orderbookOrders[0].availableContracts : null;
+    const sideWord = params.direction === 'buy' ? 'ask' : 'bid';
+    const cliCaveat = ctx.cliExecutable
+        ? ''
+        : ` The CLI cannot execute sells — fill via the Odette app (${DAPP_URL}).`;
+    let recommendation;
+    let reason;
+    let nextStep;
+    let nextStepIsCommand;
+    let nextStepMaxSize = null;
+    let partialFillAvailable = false;
+    let partialSize = null;
+    if (orderbookOrders.length > 0) {
+        recommendation = 'orderbook';
+        const previewStep = `${previewBase} --strike ${params.strike} --expiry ${params.expiry} --collateral <amount>`;
+        const spread = priceLevels.length > 1
+            ? ` Liquidity spans ${priceLevels.length} price levels across ` +
+                `${orderbookOrders.length} makers — one fill takes one order, so sweeping ` +
+                `the rest means repeating the command against the next level.`
+            : '';
+        if (params.size !== undefined && topOrderSize !== null && params.size > topOrderSize) {
+            partialFillAvailable = true;
+            partialSize = topOrderSize;
+            reason =
+                params.size > totalAvailable
+                    ? `Found ${totalAvailable.toFixed(4)} contracts total at strike $${params.strike} ` +
+                        `(you requested ${params.size}); the best ${sideWord} at ` +
+                        `$${bestPrice?.toFixed(2)} holds ${topOrderSize.toFixed(4)}. Partial fill ` +
+                        `available.${spread}${cliCaveat}`
+                    : `The book holds ${totalAvailable.toFixed(4)} contracts at strike $${params.strike} ` +
+                        `(you requested ${params.size}), but the best ${sideWord} at ` +
+                        `$${bestPrice?.toFixed(2)} holds only ${topOrderSize.toFixed(4)} — one fill takes ` +
+                        `${topOrderSize.toFixed(4)}, the remainder sits at worse prices. See ` +
+                        `priceLevels for the ladder.${cliCaveat}`;
+        }
+        else {
+            reason =
+                `Found orderbook liquidity at strike $${params.strike}. ` +
+                    `Best ${sideWord} price: $${bestPrice?.toFixed(2)} ` +
+                    `(${topOrderSize?.toFixed(4)} contracts). ` +
+                    `Available across all makers: ${totalAvailable.toFixed(4)} contracts.${spread}${cliCaveat}`;
+        }
+        // When the CLI cannot execute the side, say so as prose.
+        nextStep = ctx.cliExecutable ? previewStep : dappStep;
+        nextStepIsCommand = ctx.cliExecutable;
+        nextStepMaxSize = ctx.cliExecutable ? topOrderSize : null;
+    }
+    else if (structureMatches.length > 0) {
+        // The strike is on the book, but only inside a structure. Staying on the
+        // book preserves orderbook credit; the caller has to choose WHICH
+        // structure, because these payoffs cannot be ranked against each other.
+        recommendation = 'orderbook';
+        const listed = structureMatches
+            .slice(0, 3)
+            .map((m) => `${m.ticker} (strikes ${m.strikes.join('/')}, your strike is leg ${m.legIndex + 1} ` +
+            `of ${m.legCount}) at $${m.structurePrice.toFixed(2)} per contract, ` +
+            `${m.availableContracts.toFixed(4)} available`)
+            .join('; ');
+        const more = structureMatches.length > 3 ? ` (+${structureMatches.length - 3} more)` : '';
+        const sizeNote = params.size === undefined
+            ? ''
+            : ` ${structureMatches.filter((m) => m.meetsRequestedSize).length} of ` +
+                `${structureMatches.length} can cover your ${params.size}-contract size on their own ` +
+                `— see meetsRequestedSize per match.`;
+        reason =
+            `No standalone $${params.strike} ${params.type} on the book, but $${params.strike} sits ` +
+                `on a leg of ${structureMatches.length} live ` +
+                `${structureMatches.length === 1 ? 'structure' : 'structures'} at this expiry: ` +
+                `${listed}${more}. These are alternatives, not substitutes — a spread, fly, condor and ` +
+                `ranger sharing one strike have different payoffs, and your strike may be a short or ` +
+                `middle leg, so the whole-structure premiums are not comparable and none is "cheapest". ` +
+                `Pick the structure whose payoff you want, then fill it in full to stay on the ` +
+                `orderbook.${sizeNote}${cliCaveat}`;
+        nextStep = ctx.cliExecutable
+            ? 'Choose a structure from structureMatches after inspecting its payoff, then run that ' +
+                "match's nextStep. No top-level command is emitted: ranking by premium is only valid " +
+                'among orders for the same complete structure.'
+            : dappStep;
+        nextStepIsCommand = false;
+    }
+    else if (atExpiry.length > 0) {
+        recommendation = 'none';
+        reason =
+            nearbyStrikes.length > 0
+                ? `No Odette order at strike $${params.strike} for this expiry. ` +
+                    `Nearby strikes available: ${nearbyStrikes
+                        .slice(0, 3)
+                        .map((s) => `$${s.strike} (${s.priceDiff})`)
+                        .join(', ')}. Odette has no RFQ: trade a nearby strike.`
+                : `The book has ${atExpiry.length} live ${params.type} order(s) at this expiry but ` +
+                    `nothing at or near $${params.strike}. Odette has no RFQ: pick a listed strike.`;
+        nextStep = noOrderStep;
+        nextStepIsCommand = false;
+    }
+    else {
+        recommendation = 'none';
+        const expiryHint = liveExpiries.length === 0
+            ? `The book has no live ${params.underlying} ${params.type} orders at all right now.`
+            : didYouMean.length > 0
+                ? `No orders at expiry ${params.expiry}. The book has ${didYouMean
+                    .map((e) => `${e} (${isoOf(e).slice(0, 16)}Z)`)
+                    .join(' and ')} on the same UTC date — did you mean one of those?`
+                : `No orders at expiry ${params.expiry}. Live expiries: ${liveExpiries
+                    .map((e) => `${e.expiry} (${e.iso.slice(0, 16)}Z)`)
+                    .join(', ')}.`;
+        reason = `${expiryHint} Re-check against a listed expiry.`;
+        nextStep = noOrderStep;
+        nextStepIsCommand = false;
+    }
+    return {
+        recommendation,
+        reason,
+        params,
+        orderbookOrders: orderbookOrders.slice(0, 10),
+        priceLevels,
+        structureMatches: structureMatches.slice(0, 10),
+        bestPrice,
+        availableSize: totalAvailable > 0 ? totalAvailable : null,
+        partialFillAvailable,
+        partialSize,
+        nearbyStrikes,
+        liveExpiries,
+        didYouMean,
+        cliExecutable: ctx.cliExecutable,
+        nextStep,
+        nextStepIsCommand,
+        nextStepMaxSize,
+        referrer: ctx.referrer ?? null,
+    };
+}

package/dist/bookEligibility.js

@@ -0,0 +1,69 @@
+/**
+ * The CLI currently supports cash-settled, USDC-collateralized OptionBook
+ * purchases only. Keep the accepted implementation names explicit: physical
+ * PUTs may also use USDC, so collateral filtering alone is not sufficient.
+ */
+const CASH_SETTLED_IMPLEMENTATION_KEYS = [
+    'PUT',
+    'LINEAR_CALL',
+    'CALL_SPREAD',
+    'PUT_SPREAD',
+    'CALL_FLY',
+    'PUT_FLY',
+    'CALL_CONDOR',
+    'PUT_CONDOR',
+    'IRON_CONDOR',
+    'RANGER',
+];
+export const ORDER_PRICE_DECIMALS = 8;
+/** Build the current-chain allowlist while dropping undeployed zero addresses. */
+export function cashSettledImplementationSet(implementations) {
+    const values = implementations;
+    const accepted = new Set();
+    for (const key of CASH_SETTLED_IMPLEMENTATION_KEYS) {
+        const address = values[key];
+        if (address &&
+            address.toLowerCase() !== '0x0000000000000000000000000000000000000000') {
+            accepted.add(address.toLowerCase());
+        }
+    }
+    return accepted;
+}
+/**
+ * Return the first reason an order is unsafe for the requested taker side.
+ *
+ * Odette's OptionBook semantics are:
+ *   isLong=false -> maker is the seller -> taker can BUY (an ask)
+ *   isLong=true  -> maker is the buyer  -> taker can SELL (a bid)
+ *
+ * This is deliberately based on rawApiData.isLong rather than the SDK's legacy
+ * `order.isBuyer` compatibility field, whose Odette mapping was historically
+ * reversed in `normalizeOdetteOrder`.
+ */
+export function bookOrderIneligibility(order, policy) {
+    const raw = order.rawApiData;
+    if (!raw)
+        return 'missing-order-data';
+    if (raw.collateral.toLowerCase() !== policy.usdcAddress.toLowerCase()) {
+        return 'wrong-collateral';
+    }
+    if (!policy.cashSettledImplementations.has(raw.implementation.toLowerCase())) {
+        return 'unsupported-implementation';
+    }
+    const makerIsLong = raw.isLong;
+    const requiredMakerIsLong = policy.direction === 'sell';
+    if (makerIsLong !== requiredMakerIsLong)
+        return 'wrong-side';
+    if (Number(order.order.expiry) <= policy.now)
+        return 'expired-option';
+    if (raw.orderExpiryTimestamp <= policy.now)
+        return 'expired-order';
+    if (order.order.price <= 0n)
+        return 'invalid-price';
+    if (order.availableAmount <= 0n)
+        return 'no-liquidity';
+    return null;
+}
+export function isEligibleBookOrder(order, policy) {
+    return bookOrderIneligibility(order, policy) === null;
+}