northstar-eva-sdk 0.1.0 → 0.2.0

package/README.md

@@ -9,10 +9,55 @@ npm install northstar-eva-sdk @solana/web3.js @coral-xyz/anchor @solana/spl-toke
 ```
 ```ts
 import { NorthstarEva } from "northstar-eva-sdk";
+// localnet with a Keypair:
 const sdk = NorthstarEva.create({ network: "localnet", wallet });
+// OR keep your existing AnchorProvider + read-only wallet + custom RPC (see 0.2.0):
+const sdk = NorthstarEva.create({ provider, erRpc: ER_RPC_URL, evaProgramId });
 ```
 > 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's new in 0.2.0
+
+Integration-friendly construction — **no Keypair required, keep your provider, any RPC URL.**
+
+- **Read-only / remote wallets are supported.** `wallet` now accepts any **wallet adapter** (`publicKey` + `signTransaction`) — e.g. a Turnkey `ReadOnlyWallet` — not just a `Keypair`. The SDK signs through `signTransaction` and never needs the secret key. (Fixes the `Type 'Wallet' is missing … 'secretKey'` error.)
+- **Pass your `AnchorProvider` directly.** `NorthstarEva.create({ provider })` reuses the provider's `.wallet` (signer) and `.connection` (the **L1** endpoint) — keep the exact provider/program setup you already have.
+- **Any RPC URL (not just localhost).** Pass `l1Rpc` + `erRpc` (or `provider`/`connection` + `erRpc`). `network` is now just an optional label (any string) and no longer rejects a URL. **The ER is a separate endpoint — always pass `erRpc`** (the SDK throws a clear error if a custom L1 is given without it).
+- **Program ids are configurable + exposed.** `evaProgramId` / `portalProgramId` are options *and* readable as `sdk.evaProgramId` / `sdk.portalProgramId`.
+- **Dynamic recipients.** Deposit credits any `recipient` (a `PublicKey`); withdraw's `recipient` accepts a `Keypair` **or** a wallet adapter (and defaults to the SDK signer).
+
+**Migration — your old `new EvaArenaSDK(program, provider)` shape, unchanged inputs:**
+```ts
+const userPubkey = new PublicKey(turnkeyAddress);
+const wallet     = new ReadOnlyWallet(userPubkey);                       // no Keypair
+const provider   = new anchor.AnchorProvider(connection, wallet, { commitment: "confirmed" });
+const sdk = NorthstarEva.create({
+  provider,                    // keeps provider + read-only wallet
+  erRpc: ER_RPC_URL,           // the NorthStar ER endpoint (any URL)
+  evaProgramId: getProgramId(),// per-environment program id
+});
+```
+> Backwards compatible: `NorthstarEva.create({ network, wallet: keypair })` still works (the Keypair is wrapped automatically). No method signatures changed.
+
+## What's new in 0.1.1
+
+The deposit ("fund fee to ER payer") API now **contains the open-session step**, plus two helper additions:
+
+- **`fundFeeToErPayer` / `fundErFeePayer` now open the session for you.** Portal `DepositFee` requires an open session (the DepositReceipt PDA is derived from it). Before, you had to call `openSession()` yourself first; now the deposit call ensures it. Opt out with `{ ensureSession: false }` if you already opened it.
+  ```ts
+  // 0.1.0 — two calls, deposit fails if you forgot openSession
+  await sdk.openSession();
+  await sdk.fundFeeToErPayer(200_000_000n);
+  // 0.1.1 — one call; the session is opened automatically (idempotent)
+  await sdk.fundFeeToErPayer(200_000_000n);
+  ```
+- **New `ensureSession()`** — the named, idempotent "open the session if it isn't already" method (opens only when the session PDA is absent). This is the step `fundFeeToErPayer` performs internally; call it directly if you want the session open up front.
+- **New `withdrawFeeFromEr(...)`** — alias of `requestWithdraw(...)` that matches the "withdraw fee from ER" API name.
+
+> **Backwards compatible:** existing code that calls `openSession()` before depositing still works (the extra `ensureSession` is a no-op when the session already exists). No signatures or return types changed.
+
+The three user-fund APIs: **query balance** → `querySolBalance(account?)` · **deposit** → `fundFeeToErPayer(lamports, recipient?)` · **withdraw** → `withdrawFeeFromEr({ lamports, recipient, toL1? })`.
+
 ## What it is + the fee point
 
 NorthStar is **one validator process with two lanes**:
@@ -24,7 +69,7 @@ The fee-reduction play: do the cheap, one-time **setup/control/custody** on L1 (
 
 | Operation | Lane |
 | --- | --- |
-| `openSession`, `fundErFeePayer`/`ensureErFunds`, `delegateKeypairAccount`, `createPortalOwnedAccount`, `closeSession` | **L1** |
+| `openSession`/`ensureSession`, `fundFeeToErPayer`/`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 |
 
@@ -69,10 +114,11 @@ const sdk = NorthstarEva.create({ network: "localnet", wallet });
 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();
+// 2. (Optional since 0.1.1) Open the Portal session on L1 — the deposit below ensures it for you.
+await sdk.ensureSession(); // idempotent; no-op if already open
 
-// 3. Fund the ER fee payer via Portal DepositFee on L1 (ER balance = these credits)
+// 3. Fund the ER fee payer via Portal DepositFee on L1 (ER balance = these credits).
+//    ensureErFunds/fundFeeToErPayer open the session automatically if step 2 was skipped.
 await sdk.ensureErFunds(250_000_000n); // tops up + waits for the credit to land
 
 // 4. Initialize the eva global state on the ER (idempotent)
@@ -198,10 +244,12 @@ The "works devnet later" claim is true only against a **self-hosted NorthStar de
 | 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 }>` |
+| `ensureSession()` | L1 | **The "open session" step** that DepositFee depends on. Idempotent: opens the session only if its PDA is absent. Called for you by `fundFeeToErPayer`/`fundErFeePayer`. | `Promise<{ sessionPda: PublicKey; opened: boolean; signature: string \| null }>` |
 | `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) |
+| `fundFeeToErPayer(lamports, recipient?, { ensureSession? })` | L1 | **"Fund fee to ER payer"** deposit. **Contains the open-session step** — calls `ensureSession()` first (DepositFee requires a session), then Portal `DepositFee`. Pass `{ ensureSession: false }` to skip. | `Promise<string>` (DepositFee sig) |
+| `fundErFeePayer(lamports, recipient?, { ensureSession? })` | L1 | Same as above (the underlying impl). Portal `DepositFee` — credits an ER fee payer (its **ER balance = these credits**, not the L1 balance); ensures the session first. | `Promise<string>` |
+| `ensureErFunds(lamports, recipient?)` | L1 + ER | Ensure the ER fee payer has `>= lamports`; tops up via `DepositFee` (which ensures the session) 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>` |
 

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

@@ -136,7 +136,12 @@ export interface ResolvedConfig {
     settlementIntervalSlots: bigint;
 }
 export interface NorthstarEvaInput {
-    network?: NetworkName;
+    /**
+     * A preset name (`"localnet"` | `"devnet"`) OR any custom label — presets only set
+     * default endpoints. To use ANY RPC (not localhost), pass `l1Rpc` + `erRpc` (or a
+     * `provider`/`connection`); `network` is then just a label and may be any string.
+     */
+    network?: NetworkName | (string & {});
     l1Rpc?: string;
     erRpc?: string;
     erWs?: string;
@@ -217,13 +222,37 @@ export interface ErTxResult {
     err: unknown | null;
     confirmed: boolean;
 }
+/**
+ * A wallet adapter the SDK can sign through — exactly what Anchor's `Wallet`,
+ * a wallet-adapter, or a Turnkey/remote `ReadOnlyWallet` already implement.
+ * The SDK never needs the secret key, so a `Keypair` is NOT required.
+ */
+export interface WalletLike {
+    publicKey: PublicKey;
+    signTransaction<T extends Transaction>(tx: T): Promise<T>;
+    signAllTransactions?<T extends Transaction>(txs: T[]): Promise<T[]>;
+}
+/** Anything the SDK can sign a tx with: a raw Keypair (it partial-signs) or a wallet adapter. */
+export type TxSigner = Keypair | WalletLike;
 export interface NorthstarEvaOptions extends NorthstarEvaInput {
-    /** Signer / fee payer. (v1: a Keypair.) */
-    wallet: Keypair;
+    /**
+     * Signer / fee payer. A `Keypair` (wrapped automatically) **or** any wallet adapter
+     * (`publicKey` + `signTransaction`) — e.g. a Turnkey `ReadOnlyWallet`. Optional when
+     * `provider` is given (its `.wallet` is used).
+     */
+    wallet?: TxSigner;
+    /**
+     * An Anchor `AnchorProvider` (as you already build for eva). Its `.wallet` becomes the
+     * signer and its `.connection` becomes the **L1** connection — so you keep your provider.
+     * NOTE: the ER is a SEPARATE endpoint, so still pass `erRpc`.
+     */
+    provider?: anchor.AnchorProvider;
+    /** Explicit L1 connection (alternative to `provider`/`l1Rpc`). */
+    connection?: Connection;
     /** 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. */
+    /** Validator identity recorded in the session (settlement signer). Defaults to the signer. */
     validatorIdentity?: string | PublicKey;
     /** ms between status/read polls. */
     pollIntervalMs?: number;
@@ -232,10 +261,17 @@ export declare class NorthstarEva {
     readonly cfg: ResolvedConfig;
     readonly l1: Connection;
     readonly er: Connection;
-    readonly wallet: Keypair;
+    /** The signer as a wallet adapter (a passed Keypair is wrapped). Use `.payer` for its pubkey. */
+    readonly wallet: WalletLike;
+    /** The fee-payer / signer public key. */
+    readonly payer: PublicKey;
     readonly validatorIdentity: PublicKey;
     readonly program: anchor.Program<Idl>;
     private readonly pollMs;
+    /** The eva program id in use (configurable per environment). */
+    get evaProgramId(): PublicKey;
+    /** The Portal program id in use. */
+    get portalProgramId(): PublicKey;
     constructor(opts: NorthstarEvaOptions);
     static create(opts: NorthstarEvaOptions): NorthstarEva;
     erRpc<T = any>(method: string, params?: unknown[]): Promise<T>;
@@ -255,9 +291,11 @@ export declare class NorthstarEva {
     getSessionPdaFromEr(): Promise<any>;
     getDelegatedAccounts(): Promise<string[]>;
     sessionPda(): anchor.web3.PublicKey;
+    /** Sign `tx` with a mixed set of signers: raw Keypairs are partial-signed, wallet adapters sign via signTransaction. */
+    private signTx;
     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>;
+    sendOnEr(instructions: Transaction["instructions"], signers: TxSigner[]): Promise<ErTxResult>;
     private sendEva;
     /** Fetch eva GlobalState from the ER or throw a clear "not initialized" error. */
     private requireGlobal;
@@ -269,9 +307,30 @@ export declare class NorthstarEva {
         alreadyOpen: boolean;
     }>;
     closeSession(): Promise<string>;
+    /**
+     * Ensure the Portal session is open (idempotent). Opens it via {@link openSession} only if
+     * the session PDA doesn't exist yet; otherwise does nothing (no tx, no fee).
+     *
+     * THIS is the "open session" step that DepositFee depends on: the DepositReceipt PDA is
+     * derived from the session, so `fundFeeToErPayer` / `fundErFeePayer` call this for you
+     * before depositing. Call it directly if you want the session open up front.
+     */
+    ensureSession(): Promise<{
+        sessionPda: PublicKey;
+        opened: boolean;
+        signature: string | null;
+    }>;
     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>;
+    /**
+     * DepositFee on L1 — funds an ER fee payer (its ER balance = these credits).
+     * DepositFee REQUIRES an open Portal session (the DepositReceipt PDA is derived from it), so
+     * this ENSURES the session is open first via {@link ensureSession} (idempotent). Pass
+     * `{ ensureSession: false }` to skip that if you already opened the session yourself.
+     * Returns the DepositFee transaction signature.
+     */
+    fundErFeePayer(lamports: bigint, recipient?: PublicKey, opts?: {
+        ensureSession?: boolean;
+    }): 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). */
@@ -294,22 +353,38 @@ export declare class NorthstarEva {
         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>;
+    /**
+     * "Fund fee to ER payer" (the green-box deposit API) — deposit SOL from L1 so `recipient`
+     * is credited & spendable on the ER.
+     *
+     * This NOW CONTAINS the open-session step: it calls {@link ensureSession} first (idempotent)
+     * because Portal DepositFee requires an open session. Pass `{ ensureSession: false }` to skip
+     * it if you already opened the session. Returns the DepositFee transaction signature.
+     */
+    fundFeeToErPayer(lamports: bigint, recipient?: PublicKey, opts?: {
+        ensureSession?: boolean;
+    }): 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).
+     * (use {@link waitForL1Settlement} to await it). `recipient` signs the ER transfer and may
+     * be a **Keypair OR a wallet adapter** (e.g. a Turnkey `ReadOnlyWallet`); the L1 receiver never signs.
+     * Defaults to the SDK's own signer if omitted.
      *
      * 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;
+        recipient?: TxSigner;
+        toL1?: PublicKey;
+    }): Promise<ErTxResult>;
+    /** "Withdraw fee from ER" (the green-box withdraw API) — alias of {@link requestWithdraw}. */
+    withdrawFeeFromEr(p: {
+        lamports: bigint;
+        recipient?: TxSigner;
         toL1?: PublicKey;
     }): Promise<ErTxResult>;
     /** Poll an account's L1 balance until it rises by >= `expectedDelta` (settlement is async). Returns the final L1 balance. */

package/dist/northstar-eva-sdk.js

@@ -7,7 +7,7 @@
 // ============================================================================
 import * as anchor from "@coral-xyz/anchor";
 import { readFileSync } from "node:fs";
-import { Connection, Keypair, PublicKey, SystemProgram, Transaction, TransactionInstruction, sendAndConfirmTransaction } from "@solana/web3.js";
+import { Connection, Keypair, PublicKey, SystemProgram, Transaction, TransactionInstruction } from "@solana/web3.js";
 import { TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID, getAssociatedTokenAddressSync, createAssociatedTokenAccountIdempotentInstruction } from "@solana/spl-token";
 // --- embedded eva IDL (CQru6…) ---
 const __EVA_IDL__ = {
@@ -1978,12 +1978,15 @@ export const NETWORKS = {
 const pk = (v) => (typeof v === "string" ? new PublicKey(v) : v);
 const bn = (v, d) => (v === undefined ? d : BigInt(v));
 export function resolveConfig(input) {
-    const preset = NETWORKS[input.network ?? "localnet"];
+    // Only "localnet"/"devnet" are presets; any other `network` value is just a label and
+    // falls back to the localnet preset for defaults — pass l1Rpc/erRpc to override them.
+    const presetKey = input.network === "devnet" ? "devnet" : "localnet";
+    const preset = NETWORKS[presetKey];
     const l1Rpc = input.l1Rpc ?? preset.l1Rpc;
     const erRpc = input.erRpc ?? preset.erRpc;
     if (!l1Rpc || !erRpc) {
-        throw new Error(`Missing RPC endpoints for network "${input.network}". For devnet, pass l1Rpc + erRpc ` +
-            `pointing at your NorthStar node (public Solana devnet has no ER/Portal).`);
+        throw new Error(`Missing RPC endpoints for network "${input.network}". Pass l1Rpc + erRpc (or a provider + erRpc) ` +
+            `pointing at your NorthStar node — public Solana devnet has no ER/Portal, and the ER is a SEPARATE URL from L1.`);
     }
     return {
         l1Rpc,
@@ -2136,6 +2139,7 @@ const evaPdas = { globalStatePda, trenchPda, agentPda, tokenMintPda, trenchToken
  */
 // @coral-xyz/anchor is CommonJS — runtime values live on the default export.
 const A = anchor.default ?? anchor;
+const isWalletLike = (s) => !!s && typeof s.signTransaction === "function";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function loadBundledIdl() {
     return __EVA_IDL__;
@@ -2144,23 +2148,52 @@ export class NorthstarEva {
     cfg;
     l1;
     er;
+    /** The signer as a wallet adapter (a passed Keypair is wrapped). Use `.payer` for its pubkey. */
     wallet;
+    /** The fee-payer / signer public key. */
+    payer;
     validatorIdentity;
     program; // eva, bound to the ER connection
     pollMs;
+    /** The eva program id in use (configurable per environment). */
+    get evaProgramId() { return this.cfg.evaProgramId; }
+    /** The Portal program id in use. */
+    get portalProgramId() { return this.cfg.portalProgramId; }
     constructor(opts) {
-        this.cfg = resolveConfig(opts);
-        this.wallet = opts.wallet;
+        // ── endpoints: a provider/connection can supply the L1 endpoint; ER is always separate ──
+        const providerConn = opts.provider?.connection ?? opts.connection;
+        this.cfg = resolveConfig({ ...opts, l1Rpc: opts.l1Rpc ?? providerConn?.rpcEndpoint });
+        // ── signer: accept a Keypair (wrap it), a wallet adapter, or provider.wallet ──
+        const w = opts.wallet;
+        let signer;
+        if (isWalletLike(w))
+            signer = w; // already an adapter / ReadOnlyWallet
+        else if (w && w.secretKey)
+            signer = new A.Wallet(w); // a Keypair → wrap (NodeWallet)
+        else if (opts.provider?.wallet)
+            signer = opts.provider.wallet;
+        if (!signer)
+            throw new Error("Pass `wallet` (a Keypair or a wallet adapter with signTransaction) or a `provider` (AnchorProvider).");
+        this.wallet = signer;
+        this.payer = signer.publicKey;
         this.validatorIdentity = opts.validatorIdentity
             ? (typeof opts.validatorIdentity === "string" ? new PublicKey(opts.validatorIdentity) : opts.validatorIdentity)
-            : opts.wallet.publicKey;
+            : this.payer;
         this.pollMs = opts.pollIntervalMs ?? 500;
-        this.l1 = new Connection(this.cfg.l1Rpc, "confirmed");
+        this.l1 = providerConn ?? new Connection(this.cfg.l1Rpc, "confirmed");
         // ER provider reads at "processed" so account resolution / reads are fresh.
         this.er = new Connection(this.cfg.erRpc, "processed");
+        // Guard: a custom (non-localhost) L1 with the default localhost ER is almost certainly a
+        // forgotten erRpc — NorthStar's ER is a different URL than L1, fail loudly instead of hitting localhost.
+        const customL1 = !!(opts.l1Rpc || providerConn);
+        const erDefaulted = !opts.erRpc && opts.network !== "devnet";
+        if (customL1 && erDefaulted && !/127\.0\.0\.1|localhost/.test(this.cfg.l1Rpc)) {
+            throw new Error(`Custom L1 endpoint (${this.cfg.l1Rpc}) but no ER endpoint — NorthStar's ER is a SEPARATE URL. Pass erRpc (e.g. the :8910 endpoint).`);
+        }
         const idl = opts.evaIdl ?? (opts.evaIdlPath ? JSON.parse(readFileSync(opts.evaIdlPath, "utf8")) : loadBundledIdl());
         idl.address = this.cfg.evaProgramId.toBase58(); // honor config / devnet override
-        const provider = new A.AnchorProvider(this.er, new A.Wallet(this.wallet), { commitment: "processed" });
+        // eva program is bound to the ER connection (it executes there) + signs through the same wallet.
+        const provider = new A.AnchorProvider(this.er, this.wallet, { commitment: "processed" });
         this.program = new A.Program(idl, provider);
     }
     static create(opts) { return new NorthstarEva(opts); }
@@ -2220,10 +2253,27 @@ export class NorthstarEva {
     getSessionPdaFromEr() { return this.erRpc("getSessionPda"); }
     getDelegatedAccounts() { return this.erRpc("getDelegatedAccounts"); }
     sessionPda() { return portal.sessionPda(this.cfg.portalProgramId); }
+    // ───────────────────────── signing (adapter-based, no Keypair required) ─────────────────────────
+    /** Sign `tx` with a mixed set of signers: raw Keypairs are partial-signed, wallet adapters sign via signTransaction. */
+    async signTx(tx, signers) {
+        const keypairs = signers.filter((s) => !isWalletLike(s));
+        const wallets = signers.filter(isWalletLike);
+        if (keypairs.length)
+            tx.partialSign(...keypairs);
+        let signed = tx;
+        for (const wlt of wallets)
+            signed = await wlt.signTransaction(signed); // adds payer sig, preserves partials
+        return signed;
+    }
     // ───────────────────────── L1 send + ER send ─────────────────────────
     async sendOnL1(instructions, signers) {
-        const tx = new Transaction().add(...instructions);
-        return sendAndConfirmTransaction(this.l1, tx, signers, { commitment: "confirmed", skipPreflight: false });
+        const { blockhash, lastValidBlockHeight } = await this.l1.getLatestBlockhash("confirmed");
+        const tx = new Transaction({ feePayer: signers[0].publicKey, blockhash, lastValidBlockHeight });
+        tx.add(...instructions);
+        const signed = await this.signTx(tx, signers);
+        const sig = await this.l1.sendRawTransaction(signed.serialize(), { skipPreflight: false, preflightCommitment: "confirmed" });
+        await this.l1.confirmTransaction({ signature: sig, blockhash, lastValidBlockHeight }, "confirmed");
+        return sig;
     }
     /** Send a tx to the ER and confirm by polling (the ER returns Ok on acceptance). */
     async sendOnEr(instructions, signers) {
@@ -2233,8 +2283,8 @@ export class NorthstarEva {
                 const { blockhash } = await this.er.getLatestBlockhash("processed");
                 const tx = new Transaction({ feePayer: signers[0].publicKey, blockhash, lastValidBlockHeight: 0 });
                 tx.add(...instructions);
-                tx.sign(...signers);
-                signature = await this.er.sendRawTransaction(tx.serialize(), { skipPreflight: false, preflightCommitment: "processed" });
+                const signed = await this.signTx(tx, signers);
+                signature = await this.er.sendRawTransaction(signed.serialize(), { skipPreflight: false, preflightCommitment: "processed" });
                 break;
             }
             catch (e) {
@@ -2296,11 +2346,31 @@ export class NorthstarEva {
     async closeSession() {
         return this.sendOnL1([portal.closeSessionIx({ programId: this.cfg.portalProgramId, closer: this.wallet.publicKey })], [this.wallet]);
     }
+    /**
+     * Ensure the Portal session is open (idempotent). Opens it via {@link openSession} only if
+     * the session PDA doesn't exist yet; otherwise does nothing (no tx, no fee).
+     *
+     * THIS is the "open session" step that DepositFee depends on: the DepositReceipt PDA is
+     * derived from the session, so `fundFeeToErPayer` / `fundErFeePayer` call this for you
+     * before depositing. Call it directly if you want the session open up front.
+     */
+    async ensureSession() {
+        const r = await this.openSession();
+        return { sessionPda: r.sessionPda, opened: !r.alreadyOpen, signature: r.signature };
+    }
     depositReceiptPda(recipient = this.wallet.publicKey) {
         return portal.depositReceiptPda(this.cfg.portalProgramId, this.sessionPda(), recipient);
     }
-    /** DepositFee on L1 — funds an ER fee payer (its ER balance = these credits). */
-    async fundErFeePayer(lamports, recipient = this.wallet.publicKey) {
+    /**
+     * DepositFee on L1 — funds an ER fee payer (its ER balance = these credits).
+     * DepositFee REQUIRES an open Portal session (the DepositReceipt PDA is derived from it), so
+     * this ENSURES the session is open first via {@link ensureSession} (idempotent). Pass
+     * `{ ensureSession: false }` to skip that if you already opened the session yourself.
+     * Returns the DepositFee transaction signature.
+     */
+    async fundErFeePayer(lamports, recipient = this.wallet.publicKey, opts = {}) {
+        if (opts.ensureSession !== false)
+            await this.ensureSession();
         return this.sendOnL1([portal.depositFeeIx({ programId: this.cfg.portalProgramId, depositor: this.wallet.publicKey, recipient, lamports })], [this.wallet]);
     }
     /** Ensure the ER fee payer has >= `lamports`; tops up via DepositFee + waits for the credit. */
@@ -2372,9 +2442,16 @@ export class NorthstarEva {
         const l1 = (await this.l1GetAccount(account))?.lamports ?? 0n;
         return { er, l1 };
     }
-    /** "Fund fee to ER payer" — deposit SOL from L1 so `recipient` is credited & spendable on the ER. Alias of fundErFeePayer. */
-    async fundFeeToErPayer(lamports, recipient = this.wallet.publicKey) {
-        return this.fundErFeePayer(lamports, recipient);
+    /**
+     * "Fund fee to ER payer" (the green-box deposit API) — deposit SOL from L1 so `recipient`
+     * is credited & spendable on the ER.
+     *
+     * This NOW CONTAINS the open-session step: it calls {@link ensureSession} first (idempotent)
+     * because Portal DepositFee requires an open session. Pass `{ ensureSession: false }` to skip
+     * it if you already opened the session. Returns the DepositFee transaction signature.
+     */
+    async fundFeeToErPayer(lamports, recipient = this.wallet.publicKey, opts = {}) {
+        return this.fundErFeePayer(lamports, recipient, opts);
     }
     /** The ER WithdrawalSink PDA for a recipient (where ER withdrawal requests are sent). */
     getWithdrawalSink(recipient = this.wallet.publicKey) {
@@ -2383,19 +2460,25 @@ export class NorthstarEva {
     /**
      * "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).
+     * (use {@link waitForL1Settlement} to await it). `recipient` signs the ER transfer and may
+     * be a **Keypair OR a wallet adapter** (e.g. a Turnkey `ReadOnlyWallet`); the L1 receiver never signs.
+     * Defaults to the SDK's own signer if omitted.
      *
      * 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).
      */
     async requestWithdraw(p) {
-        if (p.toL1 && !p.toL1.equals(p.recipient.publicKey)) {
+        const recipient = p.recipient ?? this.wallet;
+        if (p.toL1 && !p.toL1.equals(recipient.publicKey)) {
             throw new Error("Arbitrary L1 withdrawal destination is not supported yet (Portal pays the deposit recipient). Omit `toL1` or set it equal to recipient.");
         }
-        const sink = this.getWithdrawalSink(p.recipient.publicKey);
-        const ix = SystemProgram.transfer({ fromPubkey: p.recipient.publicKey, toPubkey: sink, lamports: Number(p.lamports) });
-        return this.sendOnEr([ix], [p.recipient]);
+        const sink = this.getWithdrawalSink(recipient.publicKey);
+        const ix = SystemProgram.transfer({ fromPubkey: recipient.publicKey, toPubkey: sink, lamports: Number(p.lamports) });
+        return this.sendOnEr([ix], [recipient]);
+    }
+    /** "Withdraw fee from ER" (the green-box withdraw API) — alias of {@link requestWithdraw}. */
+    async withdrawFeeFromEr(p) {
+        return this.requestWithdraw(p);
     }
     /** Poll an account's L1 balance until it rises by >= `expectedDelta` (settlement is async). Returns the final L1 balance. */
     async waitForL1Settlement(account, expectedDelta, timeoutMs = 60_000) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "northstar-eva-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Run the eva program on a NorthStar ephemeral rollup (zero-fee hot path). A high-level class SDK over the NorthStar Portal/ER protocol + the eva Anchor program. Works localnet & devnet.",
   "type": "module",
   "license": "MIT",