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

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,87 @@
-# Temporary Holding Version
+# Odette SDK
 
-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 own code: trading bots, apps, scripts and AI agents.
+
+Just want to trade from a terminal? Use the CLI,
+[`@thetanuts-finance/odette-cli`](https://www.npmjs.com/package/@thetanuts-finance/odette-cli).
+
+The SDK reads the public order list, then calls the OptionBook contract on Base
+(`fillOrder`) with your own signer. You don't need to know the contract: the SDK
+handles the order format, sizing and units, safety checks and approvals.
+**Every fill carries Odette's referrer**, `0x94D784e81A5c8cA6E19629C73217b61a256Ea1c7`.
+It is fixed; no option changes it.
+
+Products: PUT, CALL (LINEAR_CALL) and RANGER, paid in USDC. The SDK only **buys**.
+Odette options are cash-settled in USDC at expiry.
+
+## Install
+
+```sh
+npm install @thetanuts-finance/odette-sdk ethers
+```
+
+Node.js 20 or newer, ethers v6. ESM and CommonJS both work.
+
+## Quick start
+
+```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, {
+  onSent: (hash) => console.log('sent', hash), // the tx hash, before it is mined
+});
+console.log(client.optionBook.decodeOrderFilled(receipt));
+```
+
+## Main methods
+
+| Method | What it does |
+|---|---|
+| `new OdetteClient({ provider, signer? })` | Base (8453) only. Refuses a `referrer` option. |
+| `client.api.fetchOrders()` | The orders the Odette app lists now (PUT, LINEAR_CALL, RANGER). |
+| `client.optionBook.previewFillOrder(order, usdc?)` | Contracts, premium (`totalCollateral`), `maxPayout`, step, min, max. No network. |
+| `client.optionBook.checkFill(order, usdc?)` | The pre-send checks against Base: chain, order, size, maker funds, your balance and allowance, simulation. Never sends. |
+| `client.optionBook.encodeFillOrder(order, usdc?)` | `{ to, data }` for any wallet library (for example a smart wallet). |
+| `client.optionBook.fillOrder(order, usdc?, { onSent? })` | Runs the checks, then sends `fillOrder`. Refuses to send if a check fails. |
+| `client.optionBook.decodeOrderFilled(receipt)` | The `OrderFilled` event: option address, premium, fee, referrer. |
+| `client.erc20.ensureAllowance(token, spender, amount)` | Approves USDC if needed. |
+
+Without `usdc`, preview, encode and fill use the order's **maximum** size.
+
+## Units
+
+- USDC amounts and contract sizes have 6 decimals (`5_000000n` = 5 USDC).
+- Prices and strikes are USD with 8 decimals.
+- The amount you pass is the USDC premium you want to spend, not a number of
+  contracts. Sizes round down to the contract's step; the minimum premium is 0.50 USDC.
+
+## Errors
+
+Errors are `OdetteError` with a `code`, for example `CHECK_FAILED`, `SIGNER_REQUIRED`,
+`INVALID_ORDER` or `TRANSACTION_CANCELLED`. A fill that was sent never reports as failed
+because of a callback or a logger.
+
+## Good to know
+
+- **Base only** (chain 8453).
+- The contracts and the order feed are Thetanuts Finance's. Odette is the app on top.
+- The referrer tag is a default in this SDK, not enforced by the contract.
+- **Found a security problem?** Don't open a public issue. See [SECURITY.md](https://github.com/Shawnchee/odette-sdk/blob/main/SECURITY.md).
+
+## License
+
+MIT, Copyright (c) 2026 Thetanuts Finance. Parts are adapted from
+[thetanuts-sdk](https://github.com/Thetanuts-Finance/thetanuts-sdk); see [NOTICE.md](https://github.com/Shawnchee/odette-sdk/blob/main/NOTICE.md).