@thetanuts-finance/odette-sdk 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`.