@mysten/deepbook-v3 2.0.1 → 2.1.4

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # @mysten/deepbook-v3
 
+## 2.1.4
+
+## 2.1.3
+
+## 2.1.2
+
+## 2.1.1
+
+## 2.1.0
+
+### Minor Changes
+
+- 31f4bf1: Add the `@mysten/deepbook-v3/account` subpath, which now hosts the shared on-chain
+  account primitive (`AccountContract`, the generated `account` bindings, and the `Account` /
+  `AccountWrapper` BCS structs). The primitive is shared infrastructure — DeepBook's core account
+  wrapper and DeepBook Predict both build on the same Move package — so it lives alongside spot and
+  margin rather than in either consumer.
+
+  The package root's export surface is unchanged: `@mysten/deepbook-v3` exports exactly what it did
+  before, and subpaths are separate module graphs, so importing `/account` does not load spot or
+  margin code. Note that `Account` exported from the root remains
+  `@deepbook/core::account::Account`; the account primitive's `Account` is a different type and is
+  reachable only from `/account`.
+
+  Documenting a second entry point changes the generated API-reference layout: TypeDoc now emits an
+  `index` module alongside `account`, so existing deepbook-v3 doc pages gain an `index.` segment in
+  their names. External links into the published reference will need updating; nothing in this repo
+  links to them.
+
+  `/account` also exports `getAccountConfig(network)`, the deployed ids for the shared account
+  package, so consumers do not transcribe them. It reads a record generated from the deploy
+  tooling's own manifest, which every subpath shares — `getDeployment(network)` reports which
+  deployment and source commit those ids came from. Testnet only for now; other networks throw
+  rather than returning placeholder ids.
+
+  This release also marks the package `sideEffects: false`. No module in `src` has an import side
+  effect, so the only emitted-output change is that pure re-export modules are now tree-shaken out
+  of the bundle rather than imported for effect.
+
+  `@mysten/deepbook-account` is superseded. Its final release, `0.1.0`, is self-contained and keeps
+  working, but it will not be updated — import from `@mysten/deepbook-v3/account` instead.
+
+- 31f4bf1: Add the `@mysten/deepbook-v3/predict` subpath, completing the consolidation of the
+  DeepBook SDKs behind one package. DeepBook Predict — market discovery, quotes, mint/redeem/claim,
+  PLP, typed receipts, and the client-side board pricer — now ships from here rather than from a
+  separate package.
+
+  The package root is unchanged, and subpaths remain separate module graphs: importing `/predict`
+  loads no spot or margin code.
+
+  `@mysten/deepbook-predict` is superseded. Its last published release keeps working for anyone
+  already on it, but it will not be updated — import from `@mysten/deepbook-v3/predict` instead.
+
+  Predict's testnet ids now come from the shared generated deployment record instead of a
+  hand-written literal, so `/account`, `/sessions` and `/predict` cannot drift apart across a
+  redeploy. `getConfig(network)` and `TESTNET_CONFIG` keep their values, but `PredictConfig` gains
+  two required fields — `coinTypes` (`plp`, `deep`) and `units` (`positionLotSize`,
+  `fixedPointScale`, `quoteCoinDecimals`, `positionQuantityDecimals`). Consumers using the shipped
+  config are unaffected; anyone hand-building a config for their own deployment must add both;
+  `getDeployment(network)` reports which deployment and source commit they came from.
+
+- 31f4bf1: Add the `@mysten/deepbook-v3/sessions` subpath: time-limited trading sessions over a
+  canonical Account. An owner authorizes an ephemeral address to act for the Account until a fixed
+  expiry, and the session key never holds a reusable `Auth` — each wrapper mints app authorization
+  internally and consumes it in the same call.
+
+  `SessionsContract` covers the session lifecycle (`authorizeSession`, `revokeSession`,
+  `sessionExpirationMs`) and the DeepBook Predict wrappers (`mintExactQuantity`, `mintExactAmount`,
+  `redeemLive`, `redeemSettled`), plus `deriveAccountId` / `deriveSessionsFieldId` /
+  `decodeSessions` / `activeSessions` for enumerating an Account's grants — there is no bulk
+  on-chain read, and expired grants keep occupying slots against a 20-address cap.
+
+  The DeepBook spot session wrappers are generated and reachable from `sessionsMoveCalls`, but are
+  not wrapped on `SessionsContract` yet — the surrounding spot-over-Account workflow is not
+  modelled.
+
+  The package root is unchanged, and subpaths are separate module graphs — importing `/sessions`
+  loads no spot or margin code.
+
+  `getSessionsConfig(network)` returns the deployed sessions ids — package, `SessionsConfig` object,
+  and the account ids sessions shares — plus `deepbookRegistry` and the `deepbook_core_account`
+  package id for the generated spot wrappers. It reads the same generated deployment record
+  `/account` and `/predict` use, so a redeploy moves every subpath together. Testnet only for now;
+  other networks throw.
+
 ## 2.0.1
 
 ### Patch Changes

package/PREDICT.md

@@ -0,0 +1,256 @@
+# DeepBook Predict (`@mysten/deepbook-v3/predict`)
+
+TypeScript SDK for DeepBook Predict — binary markets on Sui. Builds ready-to-sign transactions and
+reads on-chain state through your Sui client. The SDK never signs and never touches keys: every
+`tx.*` method returns a `Transaction` for your wallet (dapp-kit) or signer to execute.
+
+## Install
+
+```sh
+npm i @mysten/deepbook-v3 @mysten/sui
+```
+
+`@mysten/sui` is a peer dependency.
+
+> Predict is deployed on **testnet** only. `getConfig('mainnet')` throws until a mainnet deployment
+> exists.
+
+## Quickstart
+
+The SDK registers as a client extension — `$extend` it onto your `SuiClient`/`SuiGrpcClient`, then
+reach it at `client.predict.*`:
+
+```ts
+import { SuiGrpcClient } from '@mysten/sui/grpc';
+import { predict } from '@mysten/deepbook-v3/predict';
+
+const client = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+}).$extend(predict({ network: 'testnet' }));
+
+// One-time: create your Predict account (a shared AccountWrapper).
+const createTx = client.predict.tx.createManager();
+
+// Fund it: pulls DUSDC from your address (coin objects and/or address balance).
+const depositTx = client.predict.tx.deposit(myAddress, 250); // $250
+
+// Cash out: lands in your DUSDC address balance by default (no coin-object churn).
+// Pass { toCoinObject: true } if you need a discrete Coin<T> instead.
+const withdrawTx = client.predict.tx.withdraw(myAddress, 100); // $100
+
+// Pick a live market. Expiries are absolute timestamps, so never hardcode one.
+const markets = await client.predict.read.markets();
+const expiryMs = markets[0].expiryMs;
+
+// Describe the position once and reuse it — quoting and minting take the same descriptor.
+const desc = { underlying: 'BTC', expiryMs, strike: 'reference', side: 'up' } as const;
+
+// Quote before you trade: dry-runs your exact mint, real fees, real account.
+const q = await client.predict.read.quoteMint(myAddress, desc, { quantity: 50 });
+q.entryProbability; // your fill (0..1 per $1 payout)
+q.cost; // exact all-in debit
+
+// Trade. `maxCost` is your ceiling on the all-in debit — pass the quote plus a buffer,
+// rounded to 6 decimals, since raw amounts are integers at that scale.
+const mintTx = await client.predict.tx.mint(myAddress, desc, {
+	quantity: 50,
+	maxCost: Math.ceil(q.cost * 1.01 * 1e6) / 1e6,
+});
+// -> sign & execute any of these with your wallet / dapp-kit / signer
+
+// Anonymous board price (no account needed): both sides of any strike.
+const { up, down } = await client.predict.read.price({
+	underlying: 'BTC',
+	expiryMs,
+	strike: 'reference',
+});
+
+// Decode the receipt from the execution result (execute with events included):
+const receipt = client.predict.decode.mint(mintResult);
+receipt.orderId; // PERSIST THIS — needed to redeem/claim later
+receipt.entryProbability; // your fill price (0..1 per $1 payout)
+receipt.premium; // exact cost breakdown
+receipt.fees;
+
+// Read: tradeable markets and pool state.
+const markets = await client.predict.read.markets();
+// -> [{ id, expiryMs, tickSize, admissionTickSize, mintPaused, referencePrice }, ...]
+const market = await client.predict.read.market({
+	underlying: 'BTC',
+	expiryMs: markets[0].expiryMs,
+});
+console.log(market?.nav, market?.tickSize, market?.mintPaused);
+```
+
+## ⚠ Slippage defaults are UNCAPPED
+
+`mint` mirrors the chain's semantics: when you omit `maxCost` and `maxProbability`, the mint is
+**uncapped** — if the price moves between your quote and execution, the position can cost up to your
+full account balance. **Call `read.quoteMint` and pass its `cost` (plus your buffer) as `maxCost`.**
+The same applies to `redeem`: the deployed `redeem_live` DOES take `min_probability` /
+`min_proceeds` floors, but the facade does not surface them yet and always sends `0` (uncapped).
+`read.quoteRedeem` first, close fast — or drive `redeemLive` from the tx layer to set the floors.
+
+## Units
+
+Everything human-facing is decimal; everything on-chain is scaled integers. The facade converts
+**inputs** exactly (string/bigint math — no floats on the money path in). Read outputs typed
+`number` are display values: above 2^53 raw they lose low-digit precision — for accounting-exact
+reads use the primitives layer, which returns raw `bigint`s (`accountBalance`, `poolStats`, …).
+
+| Concept                                     | You pass / receive                                             | On-chain raw                          |
+| ------------------------------------------- | -------------------------------------------------------------- | ------------------------------------- |
+| Amounts (deposit, spend, maxCost, balances) | USD decimal number or string (`12.5`, `"12.5"`)                | ×1e6 (DUSDC)                          |
+| `quantity`                                  | **max payout** in USD; positions pay $1 per contract at expiry | ×1e6, in $0.01 lots                   |
+| `strike`                                    | USD (`105_000`)                                                | ×1e9, must land on the admission grid |
+| `maxProbability`                            | 0..1 (`0.35` = 35¢ per $1 contract)                            | ×1e9                                  |
+| PLP shares (`withdrawPlp`, `plpBalance`)    | raw `bigint` shares                                            | 6-decimal coin                        |
+
+`side: "up"` wins if the settlement price is above the strike; `"down"` below.
+
+## Reference-price markets (Polymarket-style windows)
+
+Each market carries an on-chain **reference price** — derived from the exact previous-window oracle
+observation, so consecutive windows chain naturally (the prior window's settlement observation
+anchors the next window's strike). Build an up/down board straight from discovery, and trade at the
+anchor with `strike: "reference"`:
+
+```ts
+const markets = await client.predict.read.markets();
+// each market: "BTC above $<referencePrice>?  ↑ / ↓"
+
+const tx = await client.predict.tx.mint(
+	myAddress,
+	{ underlying: 'BTC', expiryMs: markets[0].expiryMs, strike: 'reference', side: 'up' },
+	{ quantity: 25, maxCost: 15 },
+);
+```
+
+The reference tick is read fresh at build time (it is unset briefly at the start of a window until
+the keeper seeds it — you get a clean `PredictInputError` rather than a chain abort). Numeric
+strikes away from the reference remain fully supported.
+
+### Numeric strikes must sit on the admission grid
+
+New mint strikes must be a whole multiple of the market's **`admissionTickSize`** — a step
+deliberately coarser than `tickSize`, and it varies by cadence (on the current testnet deployment
+the 1m/5m/1h markets use `$1` and the 1d/1w markets `$100`, against a `$0.01` tick). Always read it
+off the market rather than assuming a value. The market's `referencePrice` is the one finite strike
+the chain admits off-grid. `read.markets()` and `read.market()` both report `admissionTickSize`, so
+a board can be built from it directly:
+
+```ts
+const m = (await client.predict.read.markets())[0];
+const strike = Math.round(target / m.admissionTickSize) * m.admissionTickSize;
+```
+
+An off-grid numeric strike throws `PredictInputError` at build time rather than aborting on chain
+with `EInvalidAdmissionTick`.
+
+## What's in the box
+
+- **`client.predict.tx`** — `createManager`, `deposit`, `withdraw`, `mint`, `mintAmount`, `redeem`,
+  `claimSettled`, `supplyPlp`, `withdrawPlp`, `cancelSupplyPlp`, `cancelWithdrawPlp`,
+  `setBuilderCode`, `unsetBuilderCode`. Market-resolving builders
+  (`mint`/`mintAmount`/`redeem`/`claimSettled`) are async: they resolve the market object from
+  `{ underlying, expiryMs, strike, side }` via the on-chain registry (cached per client).
+- **`client.predict.read`** — `markets()` (tradeable summaries: id, expiry, tick size, mint-paused,
+  reference price), `market(desc)` (state + live NAV), `price(m)` (anonymous both-sides pricing for
+  any strike, one chain call per strike), `pricer(m)` (a **client-side board pricer** — one chain
+  read of the resolved pricer, then price every strike locally; see below),
+  `quoteMint(owner, m, opts)` / `quoteRedeem(owner, m, opts)` (exact dry-run quotes: real fees from
+  the real code path — and they throw the same typed errors the real trade would, so a quote doubles
+  as preflight), `balance(owner)`, `plpBalance(owner)`, `pool()`, `positions(owner)` (chain-only
+  enumeration of open positions), `hasPosition(owner, marketId, orderId)`. All reads run over the
+  client's `simulateTransaction`; no indexer required.
+- **`client.predict.decode`** — pure execution-result decoders (no network): `mint`, `redeem`,
+  `claim`, `createManager`, `deposit`, `withdraw`, `plpRequest`, `plpCancel`, `builderCode`, each
+  with a plural form for batched PTBs. Execute transactions with events included and pass the
+  result; receipts come back in SDK units with raw bigints alongside. Decoding uses the events'
+  canonical BCS bytes, so it is transport-independent.
+- **PTB composition** — integrators who need to compose their own transactions can use the generated
+  Move bindings under `contracts/` directly (transaction thunks + BCS structs), the same layer the
+  facade builds on.
+- **Typed errors** — invalid inputs throw `PredictInputError` before the chain sees them; failed
+  simulations throw `PredictMoveError` with the decoded Move abort (`module`, `code`, `abortName`).
+
+## Client-side pricing (`read.pricer` + `pricing`)
+
+`read.price` runs the deployed SVI math on-chain and is authoritative, but it costs one chain call
+per strike. To paint a whole board — every strike, both sides, implied strikes — instantly, read the
+resolved pricer **once** and compute the rest locally:
+
+```ts
+const pricer = await client.predict.read.pricer({ underlying: 'BTC', expiryMs });
+pricer.up(105_000); // P(settle > $105,000), 0..1
+pricer.down(105_000); // = 1 − up
+pricer.range(104_000, 106_000); // P(strike in (104k, 106k])
+pricer.strikeAtProbability(0.25); // the strike whose UP price is 25¢
+pricer.forward; // the forward it prices against
+```
+
+`read.pricer` does a single simulate of the chain's `load_live_pricer` and decodes the returned
+`Pricer` — so the forward selection (Pyth-vs-Block-Scholes) and the SVI roll-down already happened
+on-chain; the client only evaluates the digital. It throws the same typed stale-oracle/expired
+`PredictMoveError` that `read.price` would when the chain itself cannot quote.
+
+The math is a faithful float port of the deployed `pricing::compute_nd2` (SVI with the skew
+correction, signed params, and the remaining-time roll-down). It agrees with the chain closely —
+within ~1e-4 in probability, up to ~1e-4 near ATM where the chain's fixed-point truncation dominates
+(`tests/testnet/pricing.test.ts` bounds it live). The pure functions are exported under a `pricing`
+namespace for callers who already hold their own oracle inputs (e.g. a live feed) and want zero
+chain calls:
+
+```ts
+import { pricing } from '@mysten/deepbook-v3/predict';
+
+// From a rolled SVI surface + resolved forward you already have:
+const inputs = { forward, svi: { a, b, rho, m, sigma } };
+pricing.upProbability(inputs, strike);
+pricing.strikeAtProbability(inputs, 0.25);
+pricing.boardPricer(inputs); // same shape as read.pricer's return
+
+// Or resolve raw feed data yourself (Strategy-2, matching the on-chain steps):
+const fwd = pricing.forward(pythSpot, bsSpot, bsForward); // Pyth re-anchored by the BS basis
+const rolled = pricing.rollDown(rawSvi, remainingMs, anchorTteMs); // decay a, b toward expiry
+```
+
+## Networks & deployments
+
+**Testnet only today** — `getConfig("mainnet")` throws until a mainnet deployment exists. Object ids
+for the current testnet deployment are baked into the SDK (`TESTNET_CONFIG`); they are updated, with
+a release, whenever a new package version is deployed. Move-call targets flow through one resolution
+seam, which will switch to MVR names (`@deepbook/predict`) once registered — package upgrades then
+stop requiring an SDK release for target resolution.
+
+## Notes
+
+- **Positions are enumerable on-chain**: `read.positions(owner)` lists every open position (market +
+  order id) straight from the account's position table — one round trip warm, no indexer. Persisting
+  `decode.mint(result).orderId` and applying `decode.redeem(result).replacementOrderId` is still the
+  fastest hot path, with `read.positions` as the fresh-start/recovery source and `read.hasPosition`
+  as the cheap validator.
+- PLP supply/withdraw are queued and fill at the next pool flush; cancels take the queue `index` —
+  get it from `decode.plpRequest(result).index`.
+- `claimSettled` closes the order in full — the deployed entrypoint takes no quantity.
+- **`withdraw` lands in your address balance by default** (`0x2::coin::send_funds`), not a coin
+  object — it merges into the versionless accumulator `deposit` already draws from, so the round
+  trip never accretes stray `Coin<DUSDC>` objects. `read.balance(owner)` reflects the account's
+  internal custody balance; use the client's `getBalance(owner)` for the wallet-side DUSDC total
+  (coin objects + address balance). Pass `withdraw(owner, amt, { toCoinObject: true })` for a
+  discrete coin (wallets/explorers that only render coin objects, or same-PTB composition).
+
+## Development
+
+These commands run against the whole `@mysten/deepbook-v3` package, not just Predict — the offline
+lane covers spot, margin, `/account`, `/sessions` and `/predict` together.
+
+```sh
+pnpm install
+pnpm --filter @mysten/deepbook-v3 test      # offline suite, every subpath — what CI runs
+pnpm --filter @mysten/deepbook-v3 test:e2e  # live-testnet smoke: reads + deployed-surface arity guards
+pnpm --filter @mysten/deepbook-v3 build     # ESM + d.ts via tsdown
+```
+
+To run only the Predict tests: `pnpm --filter @mysten/deepbook-v3 vitest run test/predict`.

package/README.md

@@ -1 +1,117 @@
 # Deepbook TypeScript SDK
+
+## Entry points
+
+| Import                         | Contents                                                                                                                                                                                                            |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@mysten/deepbook-v3`          | DeepBook spot and margin — pools, orders, balance managers, flash loans, governance, margin managers/pools, TPSL.                                                                                                   |
+| `@mysten/deepbook-v3/account`  | The shared on-chain **account primitive** (`AccountContract`): the canonical `AccountWrapper`, `Auth`, and custody balances that DeepBook's core account wrapper and DeepBook Predict both build on.                |
+| `@mysten/deepbook-v3/sessions` | **Time-limited trading sessions** over a canonical Account (`SessionsContract`): grant an ephemeral address bounded authority until a fixed expiry. Covers the session lifecycle and the DeepBook Predict wrappers. |
+| `@mysten/deepbook-v3/predict`  | **DeepBook Predict** — binary markets: market discovery, quotes, mint/redeem/claim, PLP, typed receipts and a client-side board pricer. See [PREDICT.md](./PREDICT.md).                                             |
+
+Subpaths are separate module graphs — importing `@mysten/deepbook-v3/account` does not load any spot
+or margin code.
+
+Each subpath also exports the **deployed ids** for its own surface, so a caller never transcribes
+them: `getAccountConfig(network)` on `/account`, `getSessionsConfig(network)` on `/sessions`,
+`getConfig(network)` on `/predict`. All three read one generated record (`src/deployments/`), so a
+redeploy updates every subpath at once and they cannot end up addressing different deployments.
+`getDeployment(network)` names the deployment and the deepbookv3 commit those ids came from.
+Predict, sessions and the account primitive are testnet-only today; an unrecorded network throws
+rather than returning placeholder ids.
+
+### `@mysten/deepbook-v3/account`
+
+An owner has one canonical `AccountWrapper`, a **derived object** of the account registry, so its id
+is computable off-chain with no chain read. `AccountContract` takes only the deployed ids of the
+`account` package, so each consumer drives it against **its own** deployment:
+
+```ts
+import { Transaction } from '@mysten/sui/transactions';
+import { AccountContract, getAccountConfig } from '@mysten/deepbook-v3/account';
+
+// Deployed ids ship with the package — no transcription.
+const account = new AccountContract(getAccountConfig('testnet'));
+
+// …or drive a deployment of your own:
+const custom = new AccountContract({ accountPackageId: '0x…', accountRegistry: '0x…' });
+
+const wrapperId = account.deriveAccountWrapperId(owner);
+
+const tx = new Transaction();
+tx.add(account.depositFunds({ wrapperId, coin, coinType: USDC }));
+```
+
+> `Account` exported from the package root is `@deepbook/core::account::Account` (the per-pool
+> trading account). The account primitive's `Account` is a different type with an unrelated layout
+> and is exported only from the `/account` subpath.
+>
+> The two surfaces also decode integers differently. `/account` parses `u64`/`u128`/`u256` to
+> `bigint`; the root's BCS structs (`Balances`, `Order`, `OrderDeepPrice`) yield decimal
+> **strings**. Both are raw on-chain units — neither is scaled — so a value crossing between them
+> needs a cast, not a conversion.
+
+### `@mysten/deepbook-v3/sessions`
+
+An Account owner authorizes an ephemeral address to submit a bounded set of transactions on the
+Account's behalf until a fixed expiry. The session key never receives a reusable `Auth` — each
+wrapper mints app authorization internally and consumes it in the same call — and there is no
+withdrawal or arbitrary-mutation entrypoint.
+
+```ts
+import { SessionsContract, getSessionsConfig } from '@mysten/deepbook-v3/sessions';
+
+// Deployed ids ship with the package — no transcription.
+const sessions = new SessionsContract(getSessionsConfig('testnet'));
+
+const wrapperId = sessions.deriveAccountWrapperId(owner);
+
+// Owner-signed: grant an ephemeral key one hour of authority.
+tx.add(sessions.authorizeSession({ wrapperId, session: ephemeral, durationMs: 3_600_000 }));
+
+// Signed by the session key: a Predict mint. `pricer` is the result of a preceding
+// `expiry_market::load_live_pricer` command in the same transaction.
+tx.add(sessions.mintExactQuantity({ expiryMarketId, wrapperId, protocolConfig, pricer, ... }));
+```
+
+Notes that bite in practice:
+
+- A grant is dead **at** its expiry — the chain asserts `now < expiresAtMs`.
+- Expired grants are never pruned and keep occupying slots, and an Account holds at most **20**
+  distinct addresses. Use `SessionsContract.decodeSessions` with `activeSessions` /
+  `expiredSessions` to list and prune before granting. There is no bulk on-chain read, and the data
+  hangs off the **derived account address**, not the wrapper address.
+- `revokeSession` on an address that holds no grant is a silent no-op — no abort, no event.
+- Revocation and expiry reads are deliberately **not** version-gated, so they keep working even
+  after the sessions package is retired.
+- The session address is the transaction sender, so it pays its own gas.
+- An admin must have authorized `SessionsApp` on the account registry. Until then — or after a
+  `deauthorize_app` — the **trading** wrappers abort with `EAppNotAuthorized`; `authorizeSession`,
+  `revokeSession` and `sessionExpirationMs` use owner auth or no auth and keep working.
+  `deauthorize_app` does not clear `SessionsData`, so re-authorizing makes every still-unexpired
+  grant live again at once — it pauses sessions, it does not kill them.
+- Listing grants goes through `deriveSessionsFieldId(owner)` → fetch → `decodeSessions`. Pass the
+  whole field object's contents, not the inner value. Fetch it through the core API, and ask for
+  content explicitly — JSON-RPC is gone from public fullnodes, and without `include` the response
+  carries no bytes:
+
+  ```ts
+  const { object } = await client.core.getObject({ objectId, include: { content: true } });
+  const grants = SessionsContract.decodeSessions(object.content);
+  ```
+
+- The field does not exist until the owner's **first** `authorizeSession` — the Move attaches it
+  lazily — so the fetch returns not-found for an owner who has never granted. That is distinct from
+  a field that exists holding an empty map, which means every grant was revoked. Treat not-found as
+  "no grants", but only not-found: a transport failure must not be collapsed into the same answer.
+
+**What a session key can do.** It cannot withdraw to an address, cannot grant or revoke sessions,
+and cannot outlive its expiry. It _can_ trade the Account's full balance: the spot wrappers take a
+caller-chosen `Pool` and pull the account's entire Base, Quote and DEEP balance into the embedded
+manager for the call, with `price_limit` supplied by the caller. Nothing caps notional or restricts
+which pools are reachable, so value can leave through adverse pricing. Fund an ephemeral-session
+Account with only what you would accept losing to that key.
+
+The DeepBook **spot** session wrappers are generated and reachable from `sessionsMoveCalls`, but
+they are not wrapped on `SessionsContract`: the surrounding spot-over-Account workflow — finding the
+embedded balance manager, reading resting orders and locked balances — is not modelled yet.

package/dist/account.d.mts

@@ -0,0 +1,139 @@
+import { AccountConfig as AccountConfig$1 } from "./contracts/account/config-arguments.mjs";
+import { TESTNET_DEPLOYMENT, TESTNET_UNITS } from "./deployments/testnet.mjs";
+import { DeployedNetwork, NetworkArg, getDeployment, getUnits } from "./deployments/index.mjs";
+import { Account, AccountWrapper, account_d_exports } from "./contracts/account/account.mjs";
+import { account_registry_d_exports } from "./contracts/account/account_registry.mjs";
+import { account_events_d_exports } from "./contracts/account/account_events.mjs";
+import { Transaction, TransactionObjectArgument, TransactionResult } from "@mysten/sui/transactions";
+
+//#region src/account.d.ts
+/**
+ * The deployed ids of the shared `account` package this contract builds against.
+ *
+ * Kept deliberately minimal — ids only — so any consumer of the shared account primitive
+ * (DeepBook core's account wrapper, Predict, …) can drive these builders with its OWN
+ * deployment's ids without constructing a full product-SDK config.
+ *
+ * Extends the codegen-generated config interface so there is exactly one config shape and
+ * casing: the generated bindings resolve `options.config` against these same keys, and if
+ * codegen adds, drops, or renames a key this file stops compiling instead of silently
+ * building a PTB against the wrong object. The ids are narrowed to `string` — codegen types
+ * the package id as optional and the registry as the wider `ConfigValue`, but the
+ * wrapper-address derivation needs plain ids.
+ */
+interface AccountConfig extends AccountConfig$1 {
+  /** The `account` Move package id. */
+  accountPackageId: string;
+  /** The shared `AccountRegistry` object id. */
+  accountRegistry: string;
+}
+/**
+ * @description The deployed `account` ids for `network`, so a caller does not transcribe
+ * them. Generated from the deploy manifest — see `src/deployments/`.
+ * @throws if the network has no recorded deployment, rather than returning placeholder ids
+ * that would fail as a confusing on-chain abort.
+ *
+ * ```ts
+ * const account = new AccountContract(getAccountConfig('testnet'));
+ * ```
+ */
+declare function getAccountConfig(network: NetworkArg): AccountConfig;
+/**
+ * AccountContract — the reusable on-chain account primitive (`packages/account`).
+ *
+ * An owner has one canonical `AccountWrapper`, a *derived* object of the account registry,
+ * so its id is computable off-chain (no read). The wrapper holds an `Account` whose custody
+ * balances apps deposit into and withdraw from; app-specific data hangs off it under an
+ * app-keyed slot. Authority is a hot-potato `Auth` minted from the tx sender and consumed
+ * by the very next account-loading call.
+ */
+declare class AccountContract {
+  #private;
+  /**
+   * @param {AccountConfig} config Deployed ids of the shared `account` package
+   */
+  constructor(config: AccountConfig);
+  /**
+   * @description The deterministic id of an owner's canonical account wrapper — no chain
+   * read needed. The wrapper is a derived object of the account registry, so its id is
+   * `derive_address(registry, AccountWrapperKey(owner))`.
+   * @param {string} owner Owner address
+   * @returns The wrapper object id
+   */
+  deriveAccountWrapperId(owner: string): string;
+  /**
+   * @description Mint owner authority for the transaction sender. A hot-potato `Auth`
+   * consumed by the very next account-loading call (`load_account_mut` inside
+   * `deposit_funds` / `withdraw_funds` / an app's own entrypoints).
+   * @returns A function that takes a Transaction object
+   */
+  generateAuth(): (tx: Transaction) => TransactionResult;
+  /**
+   * @description Create the sender's canonical account wrapper and share it. `new` derives
+   * the wrapper at its deterministic address (see `deriveAccountWrapperId`) and aborts if
+   * it already exists; `share` publishes the shared object apps borrow against.
+   * @returns A function that takes a Transaction object
+   */
+  createAccount(): (tx: Transaction) => void;
+  /**
+   * @description First-time funding in ONE PTB: create the sender's wrapper, deposit
+   * `coin` through the fresh handle, then `share` LAST (once shared, by-value use of the
+   * handle is over). This cannot be split into `createAccount` + `depositFunds`: an object
+   * input can only address an object that pre-exists the PTB, so a wrapper created inside
+   * it is reachable only through `new`'s result handle.
+   * @param {object} params Coin to deposit and its coin type
+   * @returns A function that takes a Transaction object
+   */
+  createAccountAndDeposit(params: {
+    coin: TransactionObjectArgument;
+    coinType: string;
+  }): (tx: Transaction) => void;
+  /**
+   * @description Deposit a caller-provided `coin` into the account's stored balance via the
+   * PTB-callable `deposit_funds` (folds settle → authorize → load → deposit; clock and
+   * accumulator root auto-injected). The caller owns coin sourcing.
+   * @param {object} params Wrapper id, coin to deposit, and its coin type
+   * @returns A function that takes a Transaction object
+   */
+  depositFunds(params: {
+    wrapperId: string;
+    coin: TransactionObjectArgument;
+    coinType: string;
+  }): (tx: Transaction) => void;
+  /**
+   * @description Withdraw `amount` (raw u64 units) from the account's stored balance via
+   * the PTB-callable `withdraw_funds` (folds settle → authorize → load → withdraw; clock
+   * and accumulator root auto-injected), returning the minted `Coin<T>` for the caller to
+   * transfer or compose.
+   * @param {object} params Wrapper id, raw amount, and coin type
+   * @returns A function that takes a Transaction object and returns the `Coin<T>`
+   */
+  withdrawFunds(params: {
+    wrapperId: string;
+    amount: bigint;
+    coinType: string;
+  }): (tx: Transaction) => TransactionResult;
+  /**
+   * @description Borrow the `Account` out of its wrapper — the read-side entry point apps
+   * chain their own getters onto (`account::balance<T>`, an app's own data accessors).
+   * @param {object} params Wrapper id
+   * @returns A function that takes a Transaction object and returns the `Account`
+   */
+  loadAccount(params: {
+    wrapperId: string;
+  }): (tx: Transaction) => TransactionResult;
+  /**
+   * @description Read an owner's stored custody balance for a coin type: chains
+   * `load_account(wrapper)` → `balance<T>(account, root, clock)`. Compose in a
+   * dev-inspect/simulate PTB and read the u64 return of the LAST command.
+   * @param {object} params Owner address and coin type
+   * @returns A function that takes a Transaction object
+   */
+  balance(params: {
+    owner: string;
+    coinType: string;
+  }): (tx: Transaction) => TransactionResult;
+}
+//#endregion
+export { Account, AccountConfig, AccountContract, AccountWrapper, type DeployedNetwork, type NetworkArg, TESTNET_DEPLOYMENT, TESTNET_UNITS, account_events_d_exports as accountEvents, account_d_exports as accountMoveCalls, account_registry_d_exports as accountRegistryMoveCalls, getAccountConfig, getDeployment, getUnits };
+//# sourceMappingURL=account.d.mts.map

package/dist/account.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.d.mts","names":[],"sources":["../src/account.ts"],"mappings":";;;;;;;;;;;;AAoCA;;;;;;;;;AAiBA;;UAjBiB,aAAA,SAAsB,eAAA;EAiB6B;EAfnE,gBAAA;EAegC;EAbhC,eAAA;AAAA;;AAqCD;;;;;;;;;iBAxBgB,gBAAA,CAAiB,OAAA,EAAS,UAAA,GAAa,aAAA;;;;;;;;;;cAwB1C,eAAA;EAAA;EAMQ;;;cAAR,MAAA,EAAQ,aAAA;EA0BpB;;;;;;;EAfA,sBAAA,CAAuB,KAAA;EA0CW;;;;;;EA3BlC,YAAA,CAAA,IACS,EAAA,EAAI,WAAA,KAAc,iBAAA;EAgDJ;;;;;;EAtCvB,aAAA,CAAA,IACS,EAAA,EAAI,WAAA;EA0Db;;;;;;;;;EA3CA,uBAAA,CAAwB,MAAA;IAAU,IAAA,EAAM,yBAAA;IAA2B,QAAA;EAAA,KAC1D,EAAA,EAAI,WAAA;EA8Dc;;;;;;;EAzC3B,YAAA,CAAa,MAAA;IAAU,SAAA;IAAmB,IAAA,EAAM,yBAAA;IAA2B,QAAA;EAAA,KAClE,EAAA,EAAI,WAAA;;;;;;;;;EAoBb,aAAA,CAAc,MAAA;IAAU,SAAA;IAAmB,MAAA;IAAgB,QAAA;EAAA,KAClD,EAAA,EAAI,WAAA,KAAc,iBAAA;;;;;;;EAkB3B,WAAA,CAAY,MAAA;IAAU,SAAA;EAAA,KACb,EAAA,EAAI,WAAA,KAAc,iBAAA;;;;;;;;EAW3B,OAAA,CAAQ,MAAA;IAAU,KAAA;IAAe,QAAA;EAAA,KACxB,EAAA,EAAI,WAAA,KAAc,iBAAA;AAAA"}