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

package/dist/bookMatch.js

@@ -0,0 +1,131 @@
+import { formatStructureTicker } from './format.js';
+/**
+ * The single order-matching predicate shared by `book check`, `book preview`
+ * and `book fill`.
+ *
+ * Before this module the two paths matched differently: `check` compared only
+ * `strikes[0]` while `preview`/`fill` compared the whole vector element-wise.
+ * `check` therefore reported "No orderbook liquidity" for strikes that sat on
+ * a live structure's second/third/fourth leg — routing traders off the book
+ * (and off orderbook credit) onto RFQ — while simultaneously reporting 4-leg
+ * rangers as fillable vanillas whose recommended `preview` command then failed.
+ *
+ * One predicate here means `check` cannot disagree with `fill` about what the
+ * book holds.
+ */
+/** Strikes are stored 1e8-scaled. */
+export const STRIKE_DECIMALS = 8;
+const STRIKE_SCALE = 10 ** STRIKE_DECIMALS;
+export function orderStrikesRaw(order) {
+    const strikes = order.rawApiData?.strikes ?? [];
+    return strikes.map((s) => BigInt(s));
+}
+export function orderStrikesUsd(order) {
+    return orderStrikesRaw(order).map((s) => Number(s) / STRIKE_SCALE);
+}
+export function usdToStrikeRaw(strikeUsd) {
+    return BigInt(Math.round(strikeUsd * STRIKE_SCALE));
+}
+/**
+ * Compare two strike vectors as multisets rather than sequences.
+ *
+ * Makers do not store strikes in a canonical order: 19 of 310 live orders keep
+ * them descending (`PUT_SPREAD [68000, 67000]`, `PUT_FLY [69000, 66000,
+ * 63000]`). Element-wise comparison meant `--strikes 67000,68000` — the
+ * natural ascending form a human types — missed a live order that
+ * `--strikes 68000,67000` filled. Matching on the multiset is safe because the
+ * fill encodes the *signed order's own* strike vector; the caller's argument
+ * order never reaches the contract.
+ */
+export function sameStrikeMultiset(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const sortAsc = (xs) => [...xs].sort((x, y) => (x < y ? -1 : x > y ? 1 : 0));
+    const sa = sortAsc(a);
+    const sb = sortAsc(b);
+    return sa.every((v, i) => v === sb[i]);
+}
+/** True when `order` is exactly the instrument `sel` describes. */
+export function orderMatchesSelector(order, sel) {
+    const raw = order.rawApiData;
+    if (!raw)
+        return false;
+    const orderType = raw.isCall ? 'CALL' : 'PUT';
+    if (orderType !== sel.type)
+        return false;
+    if (raw.priceFeed?.toLowerCase() !== sel.priceFeed)
+        return false;
+    if (Number(order.order.expiry) !== sel.expiry)
+        return false;
+    return sameStrikeMultiset(orderStrikesRaw(order), sel.strikesRaw);
+}
+export function findMatchingOrders(orders, sel) {
+    return orders.filter((o) => orderMatchesSelector(o, sel));
+}
+/**
+ * Live multi-leg orders that carry `strikeRaw` on any leg.
+ *
+ * This is the liquidity `book check` used to be blind to. A caller asking
+ * about a single strike that only exists inside a spread/fly/ranger can still
+ * trade on the book — they just have to fill the whole structure, so the
+ * caller must be told which structure it is before acting.
+ */
+export function ordersWithStrikeAsLeg(orders, priceFeed, type, expiry, strikeRaw) {
+    const matches = [];
+    for (const order of orders) {
+        const raw = order.rawApiData;
+        if (!raw)
+            continue;
+        const orderType = raw.isCall ? 'CALL' : 'PUT';
+        if (orderType !== type)
+            continue;
+        if (raw.priceFeed?.toLowerCase() !== priceFeed)
+            continue;
+        if (Number(order.order.expiry) !== expiry)
+            continue;
+        const strikes = orderStrikesRaw(order);
+        if (strikes.length < 2)
+            continue;
+        const legIndex = strikes.findIndex((s) => s === strikeRaw);
+        if (legIndex >= 0)
+            matches.push({ order, legIndex });
+    }
+    return matches;
+}
+/**
+ * Describe an order's structure for display.
+ *
+ * `numStrikes` from chain config is deliberately ignored: it disagrees across
+ * deployments (RANGER is 2 on one implementation address and 4 on another).
+ * The order's own strike vector is the only reliable leg count.
+ */
+export function structureInfo(order, underlying, implementations) {
+    const implAddress = order.rawApiData?.implementation?.toLowerCase();
+    const meta = implAddress ? implementations[implAddress] : undefined;
+    const strikesUsd = orderStrikesUsd(order);
+    const type = order.rawApiData?.isCall ? 'CALL' : 'PUT';
+    const expiry = Number(order.order.expiry);
+    return {
+        name: meta?.name ?? implAddress ?? 'UNKNOWN',
+        kind: meta?.type ?? 'UNKNOWN',
+        strikesUsd,
+        ticker: formatStructureTicker(underlying, expiry, strikesUsd, type, meta?.name),
+        isMultiLeg: strikesUsd.length > 1,
+    };
+}
+/**
+ * Resolve an underlying symbol to a price-feed address.
+ *
+ * Chain config carries legacy alias keys (`ETH/USD` alongside `ETH`) that
+ * resolve to the same feed. They stay accepted as input but are filtered out
+ * of the "Known:" hint so the error message reads cleanly.
+ */
+export function resolvePriceFeed(underlying, priceFeeds) {
+    const feed = priceFeeds[underlying.toUpperCase()];
+    if (feed)
+        return { feed: feed.toLowerCase() };
+    const known = Object.keys(priceFeeds)
+        .filter((k) => !k.includes('/'))
+        .join(', ');
+    return { error: `Unknown underlying "${underlying}". Known: ${known}.` };
+}

package/dist/bookOrderIdentity.js

@@ -0,0 +1,43 @@
+/**
+ * Find the exact signed order in a refreshed book.
+ *
+ * Odette reuses a nonce across batches of orders, so `(maker, nonce)` is not a
+ * unique identity. The EIP-712 signature commits to the complete order and is
+ * stable when list indices move or available liquidity changes.
+ */
+export function findSignedOrder(orders, reference) {
+    const maker = reference.order.maker.toLowerCase();
+    const signature = reference.signature.toLowerCase();
+    return orders.find((candidate) => candidate.order.maker.toLowerCase() === maker &&
+        candidate.signature.toLowerCase() === signature);
+}
+/**
+ * Find the same instrument in a refreshed book, whatever its current quote.
+ *
+ * Identity follows the Odette web app's getOrderSelectionKey (config.js:297-303)
+ * plus the maker: implementation, strikes, expiry, call/put, price feed and
+ * collateral. The quote (price, signature, quote expiry) may differ; the caller
+ * must compare terms and re-confirm. When several quotes match, the cheapest wins.
+ */
+export function findSameInstrument(orders, reference) {
+    const key = (o) => {
+        const r = o.rawApiData;
+        return [
+            o.order.maker.toLowerCase(),
+            r?.implementation.toLowerCase(),
+            (r?.strikes ?? []).join(','),
+            o.order.expiry.toString(),
+            r?.isCall ? '1' : '0',
+            r?.priceFeed.toLowerCase(),
+            r?.collateral.toLowerCase(),
+            // Part of the signed terms (option parameters and nonce), so a quote
+            // with different extra data is a different instrument.
+            (r?.extraOptionData ?? '0x').toLowerCase(),
+        ].join(':');
+    };
+    const want = key(reference);
+    const matches = orders.filter((o) => key(o) === want);
+    if (matches.length === 0)
+        return undefined;
+    return matches.reduce((best, o) => (o.order.price < best.order.price ? o : best));
+}

package/dist/bookPreview.js

@@ -0,0 +1,35 @@
+// Adapted from thetanuts-sdk cli/src/bookPreview.ts at 9e72aef1ab5c008ccc92352fa5048bd08c452ede.
+// MIT License, Copyright (c) 2026 Thetanuts Finance.
+/**
+ * OptionBook prices use the protocol's fixed 8-decimal scale. Contract counts
+ * for the CLI's supported USDC book fills use 6 decimals.
+ */
+export const BOOK_PRICE_SCALE = 100000000n;
+/**
+ * Correct the legacy SDK preview's `totalCollateral` field locally.
+ *
+ * Older SDK releases echo the requested spend ceiling when one is provided.
+ * That is harmless for contract encoding, but it overstates the premium when
+ * maker liquidity caps the fill. The CLI must approve and display the premium
+ * for the contracts that will actually be filled.
+ */
+export function withActualBookPremium(preview) {
+    return {
+        ...preview,
+        totalCollateral: (preview.numContracts * preview.pricePerContract) / BOOK_PRICE_SCALE,
+    };
+}
+/**
+ * Ceiling of the same premium — for allowance sizing only.
+ *
+ * `withActualBookPremium` floors, matching the SDK's own formula. If the
+ * OptionBook contract instead rounds the taker's premium up, an exactly-floored
+ * approval is one unit short and the fill reverts at broadcast. Approving the
+ * ceiling costs at most one unit of the collateral token (1e-6 USDC) and makes
+ * the fill robust to either rounding convention. Display still shows the real
+ * (floored) premium.
+ */
+export function bookPremiumCeiling(preview) {
+    const product = preview.numContracts * preview.pricePerContract;
+    return (product + BOOK_PRICE_SCALE - 1n) / BOOK_PRICE_SCALE;
+}

package/dist/client.js

@@ -0,0 +1,119 @@
+// Adapted from thetanuts-sdk cli/src/client.ts at 9e72aef1ab5c008ccc92352fa5048bd08c452ede.
+// MIT License, Copyright (c) 2026 Thetanuts Finance.
+// Changes: OdetteClient; Base only; referrer resolution removed (the referrer is
+// the constant ODETTE_REFERRER); RFQ keystore removed; ODETTE_FEED_URL;
+// no --private-key flag (env or config only); RPC URL errors never print the
+// URL path or query (they can hold an API key).
+import { ethers } from 'ethers';
+import { OdetteClient, ODETTE_REFERRER } from '@thetanuts-finance/odette-sdk';
+import { loadConfig, ConfigError } from './config.js';
+import { DEFAULT_CHAIN_ID, DEFAULT_RPC_URL } from './defaults.js';
+function resolveChainId(cfg) {
+    // The CLI is Base-only. A config for another chain is a config error.
+    if (cfg?.chainId !== undefined && cfg.chainId !== DEFAULT_CHAIN_ID) {
+        throw new ConfigError(`Config chainId is ${cfg.chainId}. Odette trades on Base (${DEFAULT_CHAIN_ID}) only.`);
+    }
+    return DEFAULT_CHAIN_ID;
+}
+function resolveRpcUrl(opts, cfg, _chainId) {
+    const fromFlag = opts.rpcUrl;
+    let rpcUrl;
+    if (fromFlag) {
+        rpcUrl = fromFlag;
+    }
+    else {
+        const fromEnv = process.env.ODETTE_RPC_URL;
+        if (fromEnv) {
+            rpcUrl = fromEnv;
+        }
+        else {
+            rpcUrl = cfg?.rpcUrl ?? DEFAULT_RPC_URL;
+        }
+    }
+    // Reject non-https RPC URLs unless the host is localhost. Signed tx
+    // broadcasts over plain http are vulnerable to MITM tampering of gas /
+    // nonce / data. Localhost is the only sane dev escape hatch.
+    let parsed;
+    try {
+        parsed = new URL(rpcUrl);
+    }
+    catch {
+        // Never echo the URL: hosted RPC URLs carry an API key.
+        throw new Error('odette: RPC URL is not a valid URL. Check --rpc-url, ODETTE_RPC_URL or the config rpcUrl.');
+    }
+    const host = parsed.hostname;
+    const isLocal = host === 'localhost' || host === '127.0.0.1';
+    // https anywhere; plain http only on localhost (upstream let any scheme
+    // through on localhost, e.g. ftp://127.0.0.1).
+    if (!(parsed.protocol === 'https:' || (parsed.protocol === 'http:' && isLocal))) {
+        throw new Error(`odette: RPC URL must use https:// (got ${parsed.protocol}//${parsed.host}); pass an https URL or use a localhost RPC for dev`);
+    }
+    return rpcUrl;
+}
+// Defined inline (not imported) to avoid pulling a command module into client bootstrap
+const PRIVATE_KEY_REGEX = /^0x[0-9a-fA-F]{64}$/;
+/**
+ * Keys come from the environment or the 0600 config file only (CLAUDE.md
+ * rule 2). Upstream's `--private-key` flag is not ported: argv lands in shell
+ * history and process listings.
+ */
+function resolvePrivateKey(cfg) {
+    let key;
+    let source;
+    const fromEnv = process.env.ODETTE_PRIVATE_KEY;
+    if (fromEnv) {
+        key = fromEnv;
+        source = 'ODETTE_PRIVATE_KEY env var';
+    }
+    else if (cfg?.privateKey) {
+        key = cfg.privateKey;
+        source = 'config file';
+    }
+    if (key === undefined)
+        return undefined;
+    // Validate BEFORE handing to ethers — a malformed key would otherwise be echoed verbatim in ethers' "invalid BytesLike value" error message
+    if (!PRIVATE_KEY_REGEX.test(key)) {
+        throw new Error(`Invalid private key from ${source}. Expected 0x-prefixed 64-char hex string.`);
+    }
+    return key;
+}
+/**
+ * Build an `OdetteClient` from the merged CLI options object.
+ *
+ * Pass `opts` from `getGlobalOpts(cmd)`. The function does not touch the
+ * network; it constructs an ethers `JsonRpcProvider` (which is lazy) and
+ * returns immediately.
+ */
+export function getClient(opts) {
+    const configPath = opts.config;
+    const cfg = loadConfig(configPath);
+    const chainId = resolveChainId(cfg);
+    const rpcUrl = resolveRpcUrl(opts, cfg, chainId);
+    const privateKey = resolvePrivateKey(cfg);
+    const feedUrl = process.env.ODETTE_FEED_URL;
+    const provider = new ethers.JsonRpcProvider(rpcUrl);
+    const signer = privateKey ? new ethers.Wallet(privateKey, provider) : undefined;
+    const client = new OdetteClient({
+        chainId: 8453,
+        provider,
+        ...(signer ? { signer } : {}),
+        ...(feedUrl ? { feedUrl } : {}),
+    });
+    return {
+        client,
+        hasSigner: Boolean(signer),
+        chainId,
+        rpcUrl,
+        referrer: ODETTE_REFERRER,
+    };
+}
+/**
+ * Throw a friendly error when a command needs a signer but none was supplied.
+ * Implementer agents call this at the top of any write-op action.
+ */
+export function requireSigner(result) {
+    if (!result.hasSigner) {
+        // Exit 4: a wallet error (PRD 7.2), not a runtime failure.
+        throw Object.assign(new Error('This command requires a signer. Set ODETTE_PRIVATE_KEY, or run `odette wallet import` or `odette setup`.'), { exitCode: 4 });
+    }
+}