northstar-eva-sdk 0.1.0

package/README.md

@@ -0,0 +1,294 @@
+# northstar-eva-sdk
+
+A high-level TypeScript SDK to run the **eva** program on a **NorthStar Ephemeral Rollup (ER)** and cut fees. It speaks the NorthStar Portal/ER protocol directly with **corrected encoders** and is self-contained on the three standard Solana libraries — no `@sonicsvm/northstar-sdk` dependency.
+
+## Install
+
+```bash
+npm install northstar-eva-sdk @solana/web3.js @coral-xyz/anchor @solana/spl-token
+```
+```ts
+import { NorthstarEva } from "northstar-eva-sdk";
+const sdk = NorthstarEva.create({ network: "localnet", wallet });
+```
+> Ships compiled JS + TypeScript types — works in any Node ≥18 project (JS or TS). The three Solana libs are **peer dependencies** (install them alongside). Prefer a single drop-in file instead? See `share/` (no npm). Publishing it yourself? See [PUBLISHING.md](PUBLISHING.md).
+
+## What it is + the fee point
+
+NorthStar is **one validator process with two lanes**:
+
+- **L1 lane** (`:8899`) — the base Solana chain. Trust, custody, money, finality. Normal per-signature + priority fees.
+- **ER lane** (`:8910` RPC / `:8911` WS / `:8912` TPU) — an Ephemeral Rollup that lives *inside the same process* and reanchors to the L1 bank every block. **Execution is zero-fee**, but state is in-memory and only a narrow slice ever settles back to L1.
+
+The fee-reduction play: do the cheap, one-time **setup/control/custody** on L1 (open session, fund the ER fee payer, create the game), then run the **hot path — repeated `buy`/`sell` — on the ER for ~0 fee.** This SDK handles the **lane routing** for you (it is otherwise manual: NorthStar has no auto-router):
+
+| Operation | Lane |
+| --- | --- |
+| `openSession`, `fundErFeePayer`/`ensureErFunds`, `delegateKeypairAccount`, `createPortalOwnedAccount`, `closeSession` | **L1** |
+| eva `initialize` / `createTrench` / `deposit` / `finalize` / `ensureUserAta` / `buy` / `sell` | **ER (zero fee)** |
+| Reads (`erGetAccount`, `getGlobal`, `getTrench`, …) | **Either** — ER reads pinned to commitment `processed` so read-after-write is fresh |
+
+Verified live on a local validator: Portal `5TeWSsjg2gbxCyWVniXeCmwM7UtHTCK7svzJr5xYJzHf`, eva `CQru6EauVg2UwepFCvY5qWuqCPEWYC4ta43wBbkFYtmo`.
+
+> **Why the corrected encoders?** The published `@sonicsvm/northstar-sdk` has stale `OpenSession` and `Delegate` encoders. The deployed runtime expects `OpenSession` to carry `validator` + `settlement_interval_slots` (65-byte payload) and `Delegate` to place the session account at **index 2** (the deployed IDL annotation wrongly lists it at index 6 — this SDK deliberately follows the *runtime*, not that stale IDL). Anyone regenerating a client from the Portal IDL would build a broken `Delegate`. This SDK gets it right.
+
+## Install
+
+The SDK is self-contained on three standard Solana peer dependencies:
+
+```bash
+npm install @solana/web3.js@^1.95 @coral-xyz/anchor@^0.31 @solana/spl-token@^0.4
+```
+
+(The package's `peerDependencies` accept `@coral-xyz/anchor` `^0.31 || ^0.32`, `@solana/spl-token` `^0.4`, `@solana/web3.js` `^1.95`.)
+
+**Running TypeScript:**
+- **Node >= 22.6** to run `.ts` directly via `--experimental-strip-types` (this is what the test scripts use), **or**
+- compile with `tsc` (`npm run typecheck` runs `tsc --noEmit`).
+
+The package ships TypeScript sources — `package.json` `exports` maps `.` → `./src/index.ts`, and `files` includes `src`, `idl`, and `README.md`. The eva IDL (`idl/eva_arena.json`) is bundled and loaded automatically unless you override it.
+
+## 60-second quickstart (localnet buy/sell)
+
+Copy-paste runnable against a running NorthStar validator (L1 `:8899` + ER `:8910`). Save as `quickstart.ts` and run with `node --experimental-strip-types quickstart.ts`.
+
+```ts
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { Keypair } from "@solana/web3.js";
+import { NorthstarEva } from "northstar-eva-sdk"; // or: from "../src/index.ts"
+
+// Load a funded local keypair (e.g. ~/.config/solana/id.json)
+const path = resolve(homedir(), ".config/solana/id.json");
+const wallet = Keypair.fromSecretKey(Uint8Array.from(JSON.parse(readFileSync(path, "utf8"))));
+
+const sdk = NorthstarEva.create({ network: "localnet", wallet });
+
+// 1. Health + sync (both lanes should be up)
+const h = await sdk.health();
+if (!h.l1 || !h.er) throw new Error(`validator not healthy: ${JSON.stringify(h)}`);
+
+// 2. Open the Portal session on L1 (idempotent — no-op if already open)
+await sdk.openSession();
+
+// 3. Fund the ER fee payer via Portal DepositFee on L1 (ER balance = these credits)
+await sdk.ensureErFunds(250_000_000n); // tops up + waits for the credit to land
+
+// 4. Initialize the eva global state on the ER (idempotent)
+//    NOTE: keep biddingDuration SMALL so finalize doesn't wait for many slots
+await sdk.initialize({ biddingDuration: 120n, tradingDuration: 100_000n });
+
+// 5. Create a trench (id auto-derived as totalTrenches + 1)
+const { trenchId } = await sdk.createTrench();
+
+// 6. Deposit into the bidding phase (ER)
+await sdk.deposit({ trenchId, lamports: 50_000_000n }); // 0.05 SOL
+
+// 7. Finalize — waits for ER slot >= biddingEndBlock, then seeds the AMM -> Trading
+await sdk.finalize({ trenchId });
+
+// 8. Pre-create the user's token ATA on the ER (buy/sell require it to exist)
+await sdk.ensureUserAta({ trenchId });
+
+// 9. BUY 0.01 SOL on the ER (ZERO fee). Offline quote matches on-chain mint exactly.
+const trench = await sdk.getTrench(trenchId, "er", 5);
+const quote = sdk.previewBuy(trench!.reserves, 10_000_000n);
+const buy = await sdk.buy({ trenchId, solPayWithFee: 10_000_000n });
+console.log("bought tokens:", buy.userTokens, "(offline quote:", quote?.tokensOut, ")");
+
+// 10. SELL half of them back (ER, zero fee)
+const sell = await sdk.sell({ trenchId, tokenAmount: buy.userTokens / 2n });
+console.log("remaining tokens:", sell.userTokens);
+```
+
+All lamport/token amounts are `bigint`. The wallet must be a funded L1 keypair (it pays L1 setup fees and is recorded as the validator identity in the session unless you pass `validatorIdentity`).
+
+## Two usage modes
+
+**(a) Package import (recommended for a project):**
+
+```ts
+import { NorthstarEva } from "northstar-eva-sdk";
+// also available: NETWORKS, resolveConfig, previewBuy/previewSell,
+// decodeTrench/decodeGlobalState, portal.*, evaPdas.*, and the AMM helpers.
+```
+
+**(b) Single-file drop-in:** `dist-single/northstar-eva-sdk.single.ts` is a self-contained file whose only dependencies are the three standard Solana libs. Copy it into any project and import from it directly — no package install of the SDK needed. Regenerate it with `npm run bundle`.
+
+> The committed `dist-single/northstar-eva-sdk.single.ts` is a build artifact and may be out of date — **re-run `npm run bundle` before shipping the drop-in file.**
+
+## Configuration
+
+`NorthstarEva.create(opts)` takes:
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `wallet` | `Keypair` | **required** | Signer / fee payer (L1). |
+| `network` | `"localnet" \| "devnet"` | `"localnet"` | Selects the preset endpoints/program-ids. |
+| `l1Rpc` / `erRpc` / `erWs` | `string` | from preset | Override individual endpoints. |
+| `portalProgramId` / `evaProgramId` | `string \| PublicKey` | Portal `5TeW…`, eva `CQru…` | Override for a different deployment. |
+| `evaIdl` / `evaIdlPath` | `Idl` / path | bundled `idl/eva_arena.json` | Supply a custom IDL or path. |
+| `validatorIdentity` | `string \| PublicKey` | `wallet.publicKey` | Settlement signer recorded in the session. |
+| `gridId` | `number \| bigint` | `1n` | OpenSession param. |
+| `ttlSlots` | `number \| bigint` | `1_000_000n` | Session TTL (slots). |
+| `feeCap` | `number \| bigint` | `1_000_000_000n` | Session fee cap. |
+| `settlementIntervalSlots` | `number \| bigint` | `50n` | Settlement cadence (slots). |
+| `pollIntervalMs` | `number` | `500` | ms between status/read polls. |
+
+### Localnet
+
+Zero config — the `localnet` preset points at the in-process validator:
+
+```ts
+const sdk = NorthstarEva.create({ network: "localnet", wallet });
+// l1Rpc http://127.0.0.1:8899 · erRpc http://127.0.0.1:8910 · erWs ws://127.0.0.1:8911
+```
+
+### Devnet
+
+**Public Solana devnet has NO NorthStar ER/Portal.** "devnet" here means a NorthStar validator running in a devnet-style deployment. The `devnet` preset has **empty `l1Rpc`/`erRpc` sentinels** — `resolveConfig` throws fast unless you pass your node's endpoints:
+
+```ts
+const sdk = NorthstarEva.create({
+  network: "devnet",
+  l1Rpc: "https://your-northstar-node:8899",   // REQUIRED — your NorthStar node
+  erRpc: "https://your-northstar-node:8910",    // REQUIRED — its ER lane
+  erWs:  "wss://your-northstar-node:8911",       // optional
+  // portalProgramId / evaProgramId default to the same ids; override if redeployed
+  wallet,
+});
+```
+
+The "works devnet later" claim is true only against a **self-hosted NorthStar devnet deployment** — there is no hosted default.
+
+## API reference
+
+`NorthstarEva` — `src/client.ts`, re-exported from `src/index.ts`. Lamports/tokens are `bigint`.
+
+### Construction
+
+| Method | Lane | Description | Returns |
+| --- | --- | --- | --- |
+| `static create(opts: NorthstarEvaOptions)` | — | Build an instance (resolves config, binds an L1 connection at `confirmed` and an ER connection at `processed`, loads the eva IDL). | `NorthstarEva` |
+
+### Health / session reads
+
+| Method | Lane | Description | Returns |
+| --- | --- | --- | --- |
+| `health()` | L1 + ER | Pings both lanes (`getSlot` on L1, `getHealth` on ER). | `Promise<{ l1: boolean; er: boolean }>` |
+| `syncStatus()` | ER | ER sync status (`northstarSysGetSyncStatus`). | `Promise<{ isSyncing; latestSyncedSlot; latestL1Slot }>` |
+| `getSessionPdaFromEr()` | ER | Session PDA as reported by the ER (`getSessionPda`). | `Promise<any>` |
+| `getDelegatedAccounts()` | ER | Accounts currently delegated in the session. | `Promise<string[]>` |
+| `sessionPda()` | — (pure) | Derives the Portal session PDA locally. | `PublicKey` |
+
+### Raw account reads
+
+| Method | Lane | Description | Returns |
+| --- | --- | --- | --- |
+| `erRpc(method, params?)` | ER | Raw JSON-RPC to the ER (3 retries on transient network errors). | `Promise<T>` |
+| `erGetAccount(pk)` | ER | Read an account from the ER at `processed`. | `Promise<AccountData \| null>` |
+| `l1GetAccount(pk)` | L1 | Read an account from L1 at `confirmed`. | `Promise<AccountData \| null>` |
+| `erBalance(pk)` | ER | Lamport balance on the ER (`getBalance`, `processed`). | `Promise<bigint>` |
+
+`AccountData = { data: Uint8Array; lamports: bigint; owner: string }`.
+
+### Portal control / custody (L1)
+
+| Method | Lane | Description | Returns |
+| --- | --- | --- | --- |
+| `openSession()` | L1 | Open the global Portal session (idempotent — checks if the session PDA exists first). | `Promise<{ signature: string \| null; sessionPda: PublicKey; alreadyOpen: boolean }>` |
+| `closeSession()` | L1 | Close the session. | `Promise<string>` (signature) |
+| `depositReceiptPda(recipient?)` | — (pure) | Derive the DepositReceipt PDA for a recipient (defaults to wallet). | `PublicKey` |
+| `fundErFeePayer(lamports, recipient?)` | L1 | Portal `DepositFee` — credits an ER fee payer (its **ER balance = these credits**, not the L1 balance). | `Promise<string>` |
+| `ensureErFunds(lamports, recipient?)` | L1 + ER | Ensure the ER fee payer has `>= lamports`; tops up via `DepositFee` and polls up to 25×800ms (~20s) for the credit. | `Promise<bigint>` (resulting balance) |
+| `delegateKeypairAccount(target: Keypair)` | L1 | Delegate a plain System-owned keypair account into the ER (the "proper" delegation path). | `Promise<string>` |
+| `createPortalOwnedAccount(space?)` | L1 | Create a fresh Portal-owned account (delegation-target helper). | `Promise<Keypair>` |
+
+> `delegateKeypairAccount` / `createPortalOwnedAccount` are **not exercised by the integration test** (dev mode uses zero delegated accounts). Their encoders/account order are unit-tested and verified against the runtime, but the end-to-end delegation+settlement flow is unproven on the live validator.
+
+### eva PDA derivations (pure, no network)
+
+| Method | Lane | Description | Returns |
+| --- | --- | --- | --- |
+| `globalStatePda()` | — | eva global state PDA (`["global"]`). | `PublicKey` |
+| `trenchPda(id)` | — | Trench PDA (`["trench", id_le]`). | `PublicKey` |
+| `tokenMintPda(id)` | — | Trench token mint PDA (`["mint", trench]`). | `PublicKey` |
+| `trenchVault(id)` | — | Trench vault ATA (mint, trench). | `PublicKey` |
+| `userAta(id, user?)` | — | User token ATA (mint, user; defaults to wallet). | `PublicKey` |
+
+### eva state reads
+
+| Method | Lane | Description | Returns |
+| --- | --- | --- | --- |
+| `getGlobal(source?="er")` | ER or L1 | Decode the global state. | `Promise<GlobalState \| null>` |
+| `getTrench(id, source?="er", retries?=1)` | ER or L1 | Decode a trench (re-reads up to `retries` attempts, sleeping `pollIntervalMs` between). Param is really "attempts": `retries=1` = a single read, no sleep. | `Promise<Trench \| null>` |
+| `getUserTokenBalance(id, user?, source?="er")` | ER or L1 | User's token balance (SPL amount @ offset 64). | `Promise<bigint>` |
+
+`GlobalState = { admin; feeRecipient; totalTrenches; biddingDuration; tradingDuration }`. `Trench = { id; status: "Bidding"|"Trading"|"Ended"|"Unknown"; totalDepositedSol; reserves: AmmReserves; biddingStartBlock; biddingEndBlock; tradingEndBlock; tokenMint; startTime; prizePoolReserves; bump }`.
+
+### Off-chain quotes / decode (pure)
+
+| Method | Lane | Description | Returns |
+| --- | --- | --- | --- |
+| `previewBuy(reserves, solPayWithFee)` | — | Offline buy quote (1% fee, then constant-product curve). Matches the on-chain mint exactly. | `BuyQuote \| null` |
+| `previewSell(reserves, tokensIn)` | — | Offline sell quote (curve output, then 1% fee). | `SellQuote \| null` |
+| `decodeReserves(data)` | — | Decode AMM reserves from raw trench bytes. | `AmmReserves` |
+
+`BuyQuote = { solPayWithFee; fee; solIntoCurve; tokensOut; reservesAfter }`. `SellQuote = { tokensIn; solOutGross; fee; netSolToUser; reservesAfter }`.
+
+### eva game (executed on the ER, zero fee)
+
+| Method | Lane | Description | Returns |
+| --- | --- | --- | --- |
+| `initialize({ biddingDuration, tradingDuration })` | ER | Create the global state. Idempotent — returns `null` if already initialized. | `Promise<string \| null>` |
+| `createTrench({ initialVirtualTokenReserves? })` | ER | Create the next trench; `trenchId = totalTrenches + 1` (auto). Default `initialVirtualTokenReserves = INITIAL_TOKEN_SUPPLY / 2`. | `Promise<{ trenchId: bigint; signature: string }>` |
+| `deposit({ trenchId, lamports, thinkId? })` | ER | Deposit SOL during the bidding phase. | `Promise<string>` |
+| `finalize({ trenchId })` | ER | Waits for ER slot `>= biddingEndBlock` (polls up to 80×`pollIntervalMs`), then seeds the AMM → Trading. | `Promise<string>` |
+| `ensureUserAta({ trenchId, user? })` | ER | Idempotently create the user's token ATA on the ER (buy/sell require it). | `Promise<string>` |
+| `buy({ trenchId, solPayWithFee, thinkId? })` | ER | Buy tokens off the curve (1% fee). | `Promise<{ signature; trench: Trench; userTokens: bigint }>` |
+| `sell({ trenchId, tokenAmount, minSolOutput?, thinkId? })` | ER | Sell tokens back to the curve (1% fee). | `Promise<{ signature; trench: Trench; userTokens: bigint }>` |
+
+> `finalize` sets `biddingEndBlock = current_slot + biddingDuration`. With a large `biddingDuration` (the test uses `120`), the slot wait can hit its ~40s budget (80×500ms) and then attempt finalize anyway, failing on-chain with `NotBiddingPhase`. **Use a small `biddingDuration` for fast demos.**
+
+### Also exported from `src/index.ts`
+
+- `NETWORKS`, `resolveConfig`, `DEFAULT_PORTAL_PROGRAM_ID`, `DEFAULT_EVA_PROGRAM_ID`, `INITIAL_TOKEN_SUPPLY`, `TOKEN_DECIMALS`
+- AMM helpers (`src/amm.ts`): `getBuyPrice`, `applyBuy`, `getSellPrice`, `applySell`, type `AmmReserves`, `TradeResult`
+- Quote helpers: `previewBuy`, `previewSell`, `FEE_RATE_BPS` (100 = 1%), `BASIS_POINTS` (10000), types `BuyQuote`/`SellQuote`
+- Decoders: `decodeTrench`, `decodeTrenchReserves`, `decodeGlobalState`, `decodeTokenAmount`, `TRENCH_OFFSETS`, `TRENCH_LEN` (242), types `Trench`/`TrenchStatus`/`GlobalState`
+- `portal.*` (corrected Portal encoders + PDA derivations + instruction builders)
+- `evaPdas.*` (eva PDA/ATA derivations)
+- Types: `NorthstarEvaOptions`, `Lane`, `AccountData`, `ErTxResult`, `NetworkName`, `NetworkPreset`, `ResolvedConfig`, `NorthstarEvaInput`
+
+## Running the tests
+
+```bash
+# Unit tests (pure: AMM, codec, decode) — no validator needed (~200ms)
+npm test                  # node --experimental-strip-types --test test/{amm,codec,decode}.test.ts
+
+# Live integration test — requires a running validator
+#   (L1 :8899 + ER :8910 up, eva deployed, ~/.config/solana/id.json funded)
+npm run test:integration  # override the keypair with ADMIN_KEYPAIR=/path/to/id.json
+
+# Typecheck
+npm run typecheck         # tsc --noEmit
+
+# Regenerate the single-file drop-in
+npm run bundle            # writes dist-single/northstar-eva-sdk.single.ts
+```
+
+The integration test (`test/integration.test.ts`) drives the full lifecycle: health → sync → session → fund ER → initialize → createTrench → deposit → finalize → ATA → BUY → SELL, asserting that `realSolReserves == totalDepositedSol * 20 / 100` after finalize and that the offline `previewBuy` quote **exactly equals** the on-chain tokens minted.
+
+**Validation status:** unit 16/16 pass; integration all 11 steps pass against a live validator; `tsc --noEmit` clean (both the package and the single-file project). No correctness bugs found in a source review against the deployed runtime + IDL.
+
+## Limitations (read before using for anything real)
+
+- **DEV-MODE ONLY / not trustless.** eva runs on the ER with a session that has **zero delegated accounts** (the write-filter is bypassed) because eva's PDAs cannot sign `Portal::Delegate` (the "PDA-signer wall"). This is the only way it runs today. Single global session, single validator, ER state in-memory (non-durable, lost on restart). **Not for real user funds — demo/devnet only.**
+- **ER fee-payer balance = Portal DepositFee credits**, not the L1 balance. `ensureErFunds` polls ~20s for the credit; if it lags beyond that, the method returns the (insufficient) balance **without throwing** — assert the returned balance yourself.
+- **Settlement is deliberately narrow:** only same-size DATA diffs of pre-existing delegated accounts + Portal SOL rails settle back. eva's new ER accounts, lamport moves, and owner/size changes **do not** settle — its ER results are demo-grade, not committed custody.
+- **The deployed Portal IDL annotation for `Delegate` is stale** (session listed at index 6); this SDK follows the runtime (session at index 2). Do not regenerate a Portal client from that IDL.
+- **devnet has no hosted endpoints** — you must self-host a NorthStar node and pass `l1Rpc`/`erRpc`.
+- **The single-file bundle is a build artifact** — re-run `npm run bundle` before shipping it.
+
+For the full system picture (the two lanes, dev mode, settlement), see `local_docs/architecture/eva-on-northstar-how-it-works.md`.

package/dist/northstar-eva-sdk.d.ts

@@ -0,0 +1,361 @@
+import * as anchor from "@coral-xyz/anchor";
+import type { Idl } from "@coral-xyz/anchor";
+import { Connection, Keypair, PublicKey, Transaction, TransactionInstruction } from "@solana/web3.js";
+/**
+ * Faithful TypeScript port of eva-contract's constant-product bonding-curve AMM.
+ * Source: eva-contract/programs/program/src/amm.rs (u128 math → JS bigint).
+ * Pure / dependency-free / unit-tested. READ-ONLY simulation for quotes/previews.
+ */
+export interface AmmReserves {
+    virtualSolReserves: bigint;
+    virtualTokenReserves: bigint;
+    realSolReserves: bigint;
+    realTokenReserves: bigint;
+    initialVirtualTokenReserves: bigint;
+}
+export interface TradeResult {
+    tokenAmount: bigint;
+    solAmount: bigint;
+}
+/** tokens out for `solAmount` lamports in (ceil division — favors the pool). */
+export declare function getBuyPrice(amm: AmmReserves, solAmount: bigint): bigint | null;
+export declare function applyBuy(amm: AmmReserves, solAmount: bigint): {
+    result: TradeResult;
+    reserves: AmmReserves;
+} | null;
+/** SOL out for `tokens` in (floor division, capped by real SOL). */
+export declare function getSellPrice(amm: AmmReserves, tokens: bigint): bigint | null;
+export declare function applySell(amm: AmmReserves, tokenAmount: bigint): {
+    result: TradeResult;
+    reserves: AmmReserves;
+} | null;
+/**
+ * Quote / preview engine (pure). Mirrors on-chain fee handling:
+ *  buy  (buy.rs):  fee = solPayWithFee * 1%; AMM applied to (solPayWithFee - fee).
+ *  sell (sell.rs): solOut = curve output; fee = solOut * 1%; user gets (solOut - fee).
+ */
+export declare const FEE_RATE_BPS = 100n;
+export declare const BASIS_POINTS = 10000n;
+export interface BuyQuote {
+    solPayWithFee: bigint;
+    fee: bigint;
+    solIntoCurve: bigint;
+    tokensOut: bigint;
+    reservesAfter: AmmReserves;
+}
+export interface SellQuote {
+    tokensIn: bigint;
+    solOutGross: bigint;
+    fee: bigint;
+    netSolToUser: bigint;
+    reservesAfter: AmmReserves;
+}
+export declare function previewBuy(reserves: AmmReserves, solPayWithFee: bigint): BuyQuote | null;
+export declare function previewSell(reserves: AmmReserves, tokensIn: bigint): SellQuote | null;
+/**
+ * Dependency-free decoders for eva account bytes (works for L1 OR ER reads).
+ * Layouts from eva-contract/programs/program/src/state.rs (Anchor = 8-byte
+ * discriminator + Borsh fields). SPL token amount @ offset 64.
+ */
+export declare const TRENCH_OFFSETS: {
+    readonly id: 8;
+    readonly creator: 16;
+    readonly authority: 48;
+    readonly status: 80;
+    readonly totalDepositedSol: 81;
+    readonly virtualSolReserves: 89;
+    readonly virtualTokenReserves: 105;
+    readonly realSolReserves: 121;
+    readonly realTokenReserves: 137;
+    readonly initialVirtualTokenReserves: 153;
+    readonly biddingStartBlock: 169;
+    readonly biddingEndBlock: 177;
+    readonly tradingEndBlock: 185;
+    readonly tokenMint: 193;
+    readonly startTime: 225;
+    readonly prizePoolReserves: 233;
+    readonly bump: 241;
+};
+export declare const TRENCH_LEN = 242;
+export type TrenchStatus = "Bidding" | "Trading" | "Ended" | "Unknown";
+export interface Trench {
+    id: bigint;
+    status: TrenchStatus;
+    totalDepositedSol: bigint;
+    reserves: AmmReserves;
+    biddingStartBlock: bigint;
+    biddingEndBlock: bigint;
+    tradingEndBlock: bigint;
+    tokenMint: Uint8Array;
+    startTime: bigint;
+    prizePoolReserves: bigint;
+    bump: number;
+}
+export declare function decodeTrenchReserves(data: Uint8Array): AmmReserves;
+export declare function decodeTrench(data: Uint8Array): Trench;
+export interface GlobalState {
+    admin: Uint8Array;
+    feeRecipient: Uint8Array;
+    totalTrenches: bigint;
+    biddingDuration: bigint;
+    tradingDuration: bigint;
+}
+export declare function decodeGlobalState(data: Uint8Array): GlobalState;
+export declare function decodeTokenAmount(data: Uint8Array): bigint;
+/**
+ * Network presets + resolved config. Works for localnet now and devnet later —
+ * the only difference is the endpoints + (possibly) program ids you pass in.
+ *
+ * IMPORTANT (devnet): public Solana devnet has NO NorthStar ER/Portal. "devnet"
+ * here means a NorthStar validator running in a devnet-style deployment — you MUST
+ * point l1Rpc/erRpc at THAT node's endpoints. There is no hosted default yet.
+ */
+export declare const DEFAULT_PORTAL_PROGRAM_ID = "5TeWSsjg2gbxCyWVniXeCmwM7UtHTCK7svzJr5xYJzHf";
+export declare const DEFAULT_EVA_PROGRAM_ID = "CQru6EauVg2UwepFCvY5qWuqCPEWYC4ta43wBbkFYtmo";
+export declare const INITIAL_TOKEN_SUPPLY: bigint;
+export declare const TOKEN_DECIMALS = 6;
+export type NetworkName = "localnet" | "devnet";
+export interface NetworkPreset {
+    l1Rpc: string;
+    erRpc: string;
+    erWs: string;
+    portalProgramId: string;
+    evaProgramId: string;
+}
+export declare const NETWORKS: Record<NetworkName, NetworkPreset>;
+export interface ResolvedConfig {
+    l1Rpc: string;
+    erRpc: string;
+    erWs: string;
+    portalProgramId: PublicKey;
+    evaProgramId: PublicKey;
+    /** Session params for OpenSession. */
+    gridId: bigint;
+    ttlSlots: bigint;
+    feeCap: bigint;
+    settlementIntervalSlots: bigint;
+}
+export interface NorthstarEvaInput {
+    network?: NetworkName;
+    l1Rpc?: string;
+    erRpc?: string;
+    erWs?: string;
+    portalProgramId?: string | PublicKey;
+    evaProgramId?: string | PublicKey;
+    gridId?: number | bigint;
+    ttlSlots?: number | bigint;
+    feeCap?: number | bigint;
+    settlementIntervalSlots?: number | bigint;
+}
+export declare function resolveConfig(input: NorthstarEvaInput): ResolvedConfig;
+export interface OpenSessionArgs {
+    gridId: bigint;
+    ttlSlots: bigint;
+    feeCap: bigint;
+    validator: Uint8Array;
+    settlementIntervalSlots: bigint;
+}
+export declare const encodeOpenSession: (a: OpenSessionArgs) => Uint8Array<ArrayBuffer>;
+export declare const encodeCloseSession: () => Uint8Array<ArrayBuffer>;
+export declare const encodeDepositFee: (lamports: bigint) => Uint8Array<ArrayBuffer>;
+export declare const encodeDelegate: (gridId: bigint) => Uint8Array<ArrayBuffer>;
+export declare const encodeUndelegate: () => Uint8Array<ArrayBuffer>;
+export declare const sessionPda: (programId: PublicKey) => anchor.web3.PublicKey;
+export declare const feeVaultPda: (programId: PublicKey) => anchor.web3.PublicKey;
+export declare const delegationRecordPda: (programId: PublicKey, delegated: PublicKey) => anchor.web3.PublicKey;
+export declare const depositReceiptPda: (programId: PublicKey, session: PublicKey, recipient: PublicKey) => anchor.web3.PublicKey;
+export declare const withdrawalSinkPda: (programId: PublicKey, session: PublicKey, recipient: PublicKey) => anchor.web3.PublicKey;
+export declare function openSessionIx(p: {
+    programId: PublicKey;
+    payer: PublicKey;
+    gridId: bigint;
+    ttlSlots: bigint;
+    feeCap: bigint;
+    validator: PublicKey;
+    settlementIntervalSlots: bigint;
+}): TransactionInstruction;
+export declare function closeSessionIx(p: {
+    programId: PublicKey;
+    closer: PublicKey;
+}): TransactionInstruction;
+export declare function depositFeeIx(p: {
+    programId: PublicKey;
+    depositor: PublicKey;
+    recipient: PublicKey;
+    lamports: bigint;
+}): TransactionInstruction;
+/** Multi-delegation layout: prefix [payer, system_program, session] + one group. */
+export declare function delegateIx(p: {
+    programId: PublicKey;
+    payer: PublicKey;
+    delegatedAccount: PublicKey;
+    ownerProgram: PublicKey;
+    buffer: PublicKey;
+    gridId: bigint;
+}): TransactionInstruction;
+/** Legacy order (undelegate was not refactored). */
+export declare function undelegateIx(p: {
+    programId: PublicKey;
+    authority: PublicKey;
+    delegatedAccount: PublicKey;
+    ownerProgram: PublicKey;
+}): TransactionInstruction;
+export declare const globalStatePda: (programId: PublicKey) => anchor.web3.PublicKey;
+export declare const trenchPda: (programId: PublicKey, id: bigint) => anchor.web3.PublicKey;
+export declare const agentPda: (programId: PublicKey, trench: PublicKey, user: PublicKey) => anchor.web3.PublicKey;
+export declare const tokenMintPda: (programId: PublicKey, trench: PublicKey) => anchor.web3.PublicKey;
+export declare const trenchTokenVault: (mint: PublicKey, trench: PublicKey) => anchor.web3.PublicKey;
+export declare const userTokenAccount: (mint: PublicKey, user: PublicKey) => anchor.web3.PublicKey;
+export type Lane = "l1" | "er";
+export interface AccountData {
+    data: Uint8Array;
+    lamports: bigint;
+    owner: string;
+}
+export interface ErTxResult {
+    signature: string;
+    err: unknown | null;
+    confirmed: boolean;
+}
+export interface NorthstarEvaOptions extends NorthstarEvaInput {
+    /** Signer / fee payer. (v1: a Keypair.) */
+    wallet: Keypair;
+    /** eva IDL object. If omitted, loaded from `evaIdlPath` or the bundled IDL. */
+    evaIdl?: Idl;
+    evaIdlPath?: string;
+    /** Validator identity recorded in the session (settlement signer). Defaults to wallet. */
+    validatorIdentity?: string | PublicKey;
+    /** ms between status/read polls. */
+    pollIntervalMs?: number;
+}
+export declare class NorthstarEva {
+    readonly cfg: ResolvedConfig;
+    readonly l1: Connection;
+    readonly er: Connection;
+    readonly wallet: Keypair;
+    readonly validatorIdentity: PublicKey;
+    readonly program: anchor.Program<Idl>;
+    private readonly pollMs;
+    constructor(opts: NorthstarEvaOptions);
+    static create(opts: NorthstarEvaOptions): NorthstarEva;
+    erRpc<T = any>(method: string, params?: unknown[]): Promise<T>;
+    /** Read an account from the ER at `processed` (fresh) — null on not-found. */
+    erGetAccount(address: PublicKey): Promise<AccountData | null>;
+    l1GetAccount(address: PublicKey): Promise<AccountData | null>;
+    erBalance(address: PublicKey): Promise<bigint>;
+    health(): Promise<{
+        l1: boolean;
+        er: boolean;
+    }>;
+    syncStatus(): Promise<{
+        isSyncing: boolean;
+        latestSyncedSlot: number;
+        latestL1Slot: number;
+    }>;
+    getSessionPdaFromEr(): Promise<any>;
+    getDelegatedAccounts(): Promise<string[]>;
+    sessionPda(): anchor.web3.PublicKey;
+    private sendOnL1;
+    /** Send a tx to the ER and confirm by polling (the ER returns Ok on acceptance). */
+    sendOnEr(instructions: Transaction["instructions"], signers: Keypair[]): Promise<ErTxResult>;
+    private sendEva;
+    /** Fetch eva GlobalState from the ER or throw a clear "not initialized" error. */
+    private requireGlobal;
+    private get methods();
+    private bn;
+    openSession(): Promise<{
+        signature: string | null;
+        sessionPda: PublicKey;
+        alreadyOpen: boolean;
+    }>;
+    closeSession(): Promise<string>;
+    depositReceiptPda(recipient?: PublicKey): anchor.web3.PublicKey;
+    /** DepositFee on L1 — funds an ER fee payer (its ER balance = these credits). */
+    fundErFeePayer(lamports: bigint, recipient?: PublicKey): Promise<string>;
+    /** Ensure the ER fee payer has >= `lamports`; tops up via DepositFee + waits for the credit. */
+    ensureErFunds(lamports: bigint, recipient?: PublicKey): Promise<bigint>;
+    /** Delegate a plain keypair account (System-owned) into the ER (the "proper" path). */
+    delegateKeypairAccount(target: Keypair): Promise<string>;
+    /** Create a fresh Portal-owned account on L1 (delegation target helper). */
+    createPortalOwnedAccount(space?: number): Promise<Keypair>;
+    globalStatePda(): anchor.web3.PublicKey;
+    trenchPda(id: bigint): anchor.web3.PublicKey;
+    tokenMintPda(id: bigint): anchor.web3.PublicKey;
+    trenchVault(id: bigint): anchor.web3.PublicKey;
+    userAta(id: bigint, user?: PublicKey): anchor.web3.PublicKey;
+    getGlobal(source?: Lane): Promise<GlobalState | null>;
+    getTrench(id: bigint, source?: Lane, retries?: number): Promise<Trench | null>;
+    getUserTokenBalance(id: bigint, user?: PublicKey, source?: Lane): Promise<bigint>;
+    previewBuy(reserves: AmmReserves, solPayWithFee: bigint): BuyQuote | null;
+    previewSell(reserves: AmmReserves, tokensIn: bigint): SellQuote | null;
+    decodeReserves(data: Uint8Array): AmmReserves;
+    /** Query an account's SOL balance on BOTH lanes (lamports). No program call, no fee. */
+    querySolBalance(account?: PublicKey): Promise<{
+        er: bigint;
+        l1: bigint;
+    }>;
+    /** "Fund fee to ER payer" — deposit SOL from L1 so `recipient` is credited & spendable on the ER. Alias of fundErFeePayer. */
+    fundFeeToErPayer(lamports: bigint, recipient?: PublicKey): Promise<string>;
+    /** The ER WithdrawalSink PDA for a recipient (where ER withdrawal requests are sent). */
+    getWithdrawalSink(recipient?: PublicKey): PublicKey;
+    /**
+     * "Withdraw fee from ER" (path 2): an ER `system_transfer` from `recipient` → its
+     * WithdrawalSink. The validator pays the L1 SOL ASYNCHRONOUSLY at the next settlement
+     * (use {@link waitForL1Settlement} to await it). `recipient` is a Keypair (it signs the
+     * ER transfer; the L1 receiver never signs).
+     *
+     * NOTE: the L1 payout currently goes to the SAME account that deposited — an arbitrary
+     * `toL1` destination is not supported by the Portal program yet (pending protocol change).
+     */
+    requestWithdraw(p: {
+        lamports: bigint;
+        recipient: Keypair;
+        toL1?: PublicKey;
+    }): Promise<ErTxResult>;
+    /** Poll an account's L1 balance until it rises by >= `expectedDelta` (settlement is async). Returns the final L1 balance. */
+    waitForL1Settlement(account: PublicKey, expectedDelta: bigint, timeoutMs?: number): Promise<bigint>;
+    initialize(p: {
+        biddingDuration: bigint;
+        tradingDuration: bigint;
+    }): Promise<string | null>;
+    /** createTrench with the next sequential id (id == total_trenches + 1). */
+    createTrench(p?: {
+        initialVirtualTokenReserves?: bigint;
+    }): Promise<{
+        trenchId: bigint;
+        signature: string;
+    }>;
+    deposit(p: {
+        trenchId: bigint;
+        lamports: bigint;
+        thinkId?: bigint;
+    }): Promise<string>;
+    /** finalize — waits for the ER slot to pass biddingEndBlock, then seeds the AMM. */
+    finalize(p: {
+        trenchId: bigint;
+    }): Promise<string>;
+    /** Create the user's token ATA on the ER (buy/sell require it to pre-exist). */
+    ensureUserAta(p: {
+        trenchId: bigint;
+        user?: PublicKey;
+    }): Promise<string>;
+    buy(p: {
+        trenchId: bigint;
+        solPayWithFee: bigint;
+        thinkId?: bigint;
+    }): Promise<{
+        signature: string;
+        trench: Trench;
+        userTokens: bigint;
+    }>;
+    sell(p: {
+        trenchId: bigint;
+        tokenAmount: bigint;
+        minSolOutput?: bigint;
+        thinkId?: bigint;
+    }): Promise<{
+        signature: string;
+        trench: Trench;
+        userTokens: bigint;
+    }>;
+}