northstar-eva-sdk 0.1.0 → 0.1.1

package/README.md

@@ -13,6 +13,25 @@ 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'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 +43,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 +88,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 +218,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

@@ -269,9 +269,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,8 +315,17 @@ 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;
     /**
@@ -312,6 +342,12 @@ export declare class NorthstarEva {
         recipient: Keypair;
         toL1?: PublicKey;
     }): Promise<ErTxResult>;
+    /** "Withdraw fee from ER" (the green-box withdraw API) — alias of {@link requestWithdraw}. */
+    withdrawFeeFromEr(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: {

package/dist/northstar-eva-sdk.js

@@ -2296,11 +2296,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 +2392,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) {
@@ -2397,6 +2424,10 @@ export class NorthstarEva {
         const ix = SystemProgram.transfer({ fromPubkey: p.recipient.publicKey, toPubkey: sink, lamports: Number(p.lamports) });
         return this.sendOnEr([ix], [p.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) {
         const start = (await this.l1GetAccount(account))?.lamports ?? 0n;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "northstar-eva-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",