northstar-eva-sdk 0.5.0 → 0.7.0

package/README.md

@@ -36,6 +36,7 @@ const sdk = NorthstarEva.create({ provider, erRpc: "https://ephemeral.devnet.son
 - **`l1Endpoint`** means "the provider's RPC is the ER; this is the L1." It's the cleanest fit when your app's provider already points at the ER. (`L1Endpoint` is accepted too.)
 - **Same SDK, both services:** with no `l1Endpoint`/`erRpc`, you get a normal eva client — one codebase covers the NorthStar and non-NorthStar deployments.
 - **Withdraw returns to the sender:** `withdrawFeeFromEr({ lamports })` reclaims the fee to whoever funded the ER (the SDK signer) — no recipient needed.
+- **Session helpers:** `await sdk.isSessionOpen()` (read-only boolean), `await sdk.getSession()` (decoded session struct — validator, `ttlSlots`, `createdAt`, `expiresAtSlot`, … or `null`), and `await sdk.buildEnsureSessionIx()` (returns the OpenSession instruction to compose/sign yourself, or `null` if the session already exists).
 
 ## What's new in 0.4.0
 
@@ -68,7 +69,7 @@ tx.sign(myKeypair);                       // or wallet.signTransaction(tx)
 await connection.sendRawTransaction(tx.serialize());
 ```
 
-Builders (each mirrors the send-method's inputs): `buildOpenSessionIx()`, `buildCloseSessionIx()`, `buildDepositFeeIx(lamports, recipient?)`, `buildWithdrawFeeFromErIx({ lamports, recipient?, toL1? })` (Portal SOL bridge), `buildInitializeIx(p)`, `buildUpdateConfigIx(p)`, `buildCreateTrenchIx({ trenchId?, initialVirtualTokenReserves? })`, `buildDepositIx(p)`, `buildWithdrawIx({ trenchId, amount, thinkId? })` (eva trench withdraw), `buildFinalizeIx(p)`, `buildUserAtaIx(p)`, `buildBuyIx(p)`, `buildSellIx(p)`, `buildClosePoolIx(p)`, `buildClaimTokensIx(p)`, `buildDistributePrizeIx(p)`, plus `buildTransaction(ixs, { lane?, feePayer? })`, `nextTrenchId()`, and the `agentPda(id, user?)` PDA helper.
+Builders (each mirrors the send-method's inputs): `buildOpenSessionIx()`, `buildCloseSessionIx()`, `buildDepositFeeIx(lamports, recipient?)`, `buildWithdrawFeeFromErIx({ lamports, sender?, toL1? })` (Portal SOL bridge), `buildInitializeIx(p)`, `buildUpdateConfigIx(p)`, `buildCreateTrenchIx({ trenchId?, initialVirtualTokenReserves? })`, `buildDepositIx(p)`, `buildWithdrawIx({ trenchId, amount, thinkId? })` (eva trench withdraw), `buildFinalizeIx(p)`, `buildUserAtaIx(p)`, `buildBuyIx(p)`, `buildSellIx(p)`, `buildClosePoolIx(p)`, `buildClaimTokensIx(p)`, `buildDistributePrizeIx(p)`, plus `buildTransaction(ixs, { lane?, feePayer? })`, `nextTrenchId()`, and the `agentPda(id, user?)` PDA helper.
 
 > The existing send-methods (`buy`, `sell`, `fundFeeToErPayer`, …) are unchanged — they now just call these builders internally. Builders perform the same state **reads** to resolve accounts (e.g. `buildBuyIx` reads global for `feeRecipient`) but never **send**.
 
@@ -133,7 +134,7 @@ The deposit ("fund fee to ER payer") API now **contains the open-session step**,
 
 > **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? })`.
+The three user-fund APIs: **query balance** → `querySolBalance(account?)` · **deposit** → `fundFeeToErPayer(lamports, recipient?)` · **withdraw** → `withdrawFeeFromEr({ lamports, sender?, toL1? })`.
 
 ## What it is + the fee point
 

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

@@ -101,6 +101,46 @@ export interface GlobalState {
     tradingDuration: bigint;
 }
 export declare function decodeGlobalState(data: Uint8Array): GlobalState;
+export declare const SESSION_LEN = 219;
+export declare const SESSION_DISCRIMINATOR = 1;
+export declare const SESSION_OFFSETS: {
+    readonly discriminator: 0;
+    readonly gridId: 1;
+    readonly ttlSlots: 9;
+    readonly feeCap: 17;
+    readonly createdAt: 25;
+    readonly nonce: 33;
+    readonly authority: 49;
+    readonly validator: 81;
+    readonly settlementIntervalSlots: 113;
+    readonly lastSettledL1Slot: 121;
+    readonly lastSettledErSlot: 129;
+    readonly settlementStatus: 137;
+    readonly settlementErSlot: 138;
+    readonly settlementStartedL1Slot: 210;
+    readonly bump: 218;
+};
+export type SettlementStatus = "Idle" | "InProgress" | "Unknown";
+export interface SessionAccount {
+    discriminator: number;
+    gridId: bigint;
+    ttlSlots: bigint;
+    feeCap: bigint;
+    createdAt: bigint;
+    /** created_at + ttl_slots — the session is expired once the L1 slot passes this (matches the program's `is_expired`). */
+    expiresAtSlot: bigint;
+    nonce: bigint;
+    authority: Uint8Array;
+    validator: Uint8Array;
+    settlementIntervalSlots: bigint;
+    lastSettledL1Slot: bigint;
+    lastSettledErSlot: bigint;
+    settlementStatus: SettlementStatus;
+    settlementErSlot: bigint;
+    settlementStartedL1Slot: bigint;
+    bump: number;
+}
+export declare function decodeSession(data: Uint8Array): SessionAccount;
 export declare function decodeTokenAmount(data: Uint8Array): bigint;
 /**
  * Network presets + resolved config. Works for localnet now and devnet later —
@@ -319,6 +359,15 @@ export declare class NorthstarEva {
     getSessionPdaFromEr(): Promise<any>;
     getDelegatedAccounts(): Promise<string[]>;
     sessionPda(): anchor.web3.PublicKey;
+    /**
+     * Read + decode the Portal session account from L1 (the single global session for this Portal).
+     * Returns `null` if no valid session exists. Read-only — no transaction, no fee. Use the returned
+     * `ttlSlots`/`createdAt`/`expiresAtSlot`/`validator` for details (compare `expiresAtSlot` to the
+     * current L1 slot — `await this.l1.getSlot()` — to tell if it's expired).
+     */
+    getSession(): Promise<SessionAccount | null>;
+    /** True if a valid Portal session is open on L1 (read-only; no tx). */
+    isSessionOpen(): Promise<boolean>;
     /** Sign `tx` with a mixed set of signers: raw Keypairs are partial-signed, wallet adapters sign via signTransaction. */
     private signTx;
     private sendOnL1;
@@ -333,12 +382,19 @@ export declare class NorthstarEva {
     buildOpenSessionIx(): TransactionInstruction;
     /** Portal CloseSession instruction (L1). */
     buildCloseSessionIx(): TransactionInstruction;
+    /**
+     * Build version of {@link ensureSession}: returns the OpenSession instruction **only if the
+     * session isn't created yet**, or **`null`** if it already exists. Async (it reads the session
+     * on L1). The caller composes the returned ix into a tx, signs, and submits — e.g.:
+     * `const ix = await sdk.buildEnsureSessionIx(); if (ix) tx.add(ix);`
+     */
+    buildEnsureSessionIx(): Promise<TransactionInstruction | null>;
     /** Portal DepositFee instruction (L1) — "fund fee to ER payer". (Caller must ensure a session exists.) */
     buildDepositFeeIx(lamports: bigint, recipient?: PublicKey): TransactionInstruction;
-    /** "Withdraw fee from ER" instruction (ER) — system transfer from `recipient` (default: signer) → its WithdrawalSink. (Portal SOL bridge; distinct from the eva `withdraw` instruction.) */
+    /** "Withdraw fee from ER" instruction (ER) — system transfer from `sender` (default: the signer) → its WithdrawalSink. (Portal SOL bridge; distinct from the eva `withdraw` instruction.) */
     buildWithdrawFeeFromErIx(p: {
         lamports: bigint;
-        recipient?: PublicKey;
+        sender?: PublicKey;
         toL1?: PublicKey;
     }): TransactionInstruction;
     /** Next sequential trench id (= total_trenches + 1) read from the ER global state. */
@@ -491,23 +547,23 @@ export declare class NorthstarEva {
      * WithdrawalSink, returning the fee to whoever sent it. The validator pays the L1 SOL
      * ASYNCHRONOUSLY at the next settlement (use {@link waitForL1Settlement} to await it).
      *
-     * By default the **sender = the SDK's signer** (the account that funded the ER), so
-     * `withdrawFeeFromEr({ lamports })` reclaims to the sender — no recipient needed. You may
-     * still pass `recipient` (a Keypair OR a wallet adapter) to reclaim a different funded
-     * account; it signs the ER transfer (the L1 receiver never signs).
+     * `sender` is a **PublicKey** (default: the SDK signer's pubkey). This send-method signs with
+     * the SDK's wallet adapter — so `sender` must be the SDK's own account (the user's wallet, which
+     * signs remotely; no secret key needed). To withdraw for a different account whose signature you
+     * collect elsewhere, use {@link buildWithdrawFeeFromErIx} and have that account sign the tx.
      *
      * NOTE: the L1 payout goes to the SAME account that deposited (the sender) — an arbitrary
      * `toL1` destination is not supported by the Portal program yet (pending protocol change).
      */
     requestWithdraw(p: {
         lamports: bigint;
-        recipient?: TxSigner;
+        sender?: PublicKey;
         toL1?: PublicKey;
     }): Promise<ErTxResult>;
     /** "Withdraw fee from ER" (the green-box withdraw API) — alias of {@link requestWithdraw}. */
     withdrawFeeFromEr(p: {
         lamports: bigint;
-        recipient?: TxSigner;
+        sender?: PublicKey;
         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

@@ -1938,6 +1938,41 @@ export function decodeGlobalState(data) {
         tradingDuration: data.length >= 96 ? uLE(data, 88, 8) : 0n,
     };
 }
+// ---- Portal Session (portal/src/state.rs struct Session; Borsh, LEN 219, discriminator 1) ----
+export const SESSION_LEN = 219;
+export const SESSION_DISCRIMINATOR = 1;
+export const SESSION_OFFSETS = {
+    discriminator: 0, gridId: 1, ttlSlots: 9, feeCap: 17, createdAt: 25, nonce: 33,
+    authority: 49, validator: 81, settlementIntervalSlots: 113, lastSettledL1Slot: 121,
+    lastSettledErSlot: 129, settlementStatus: 137, settlementErSlot: 138,
+    settlementStartedL1Slot: 210, bump: 218,
+};
+const SETTLEMENT_STATUS = ["Idle", "InProgress"];
+export function decodeSession(data) {
+    if (data.length < SESSION_LEN)
+        throw new Error(`Session data too short: ${data.length} < ${SESSION_LEN}`);
+    const o = SESSION_OFFSETS;
+    const createdAt = uLE(data, o.createdAt, 8);
+    const ttlSlots = uLE(data, o.ttlSlots, 8);
+    return {
+        discriminator: data[o.discriminator],
+        gridId: uLE(data, o.gridId, 8),
+        ttlSlots,
+        feeCap: uLE(data, o.feeCap, 8),
+        createdAt,
+        expiresAtSlot: createdAt + ttlSlots,
+        nonce: uLE(data, o.nonce, 16),
+        authority: data.slice(o.authority, o.authority + 32),
+        validator: data.slice(o.validator, o.validator + 32),
+        settlementIntervalSlots: uLE(data, o.settlementIntervalSlots, 8),
+        lastSettledL1Slot: uLE(data, o.lastSettledL1Slot, 8),
+        lastSettledErSlot: uLE(data, o.lastSettledErSlot, 8),
+        settlementStatus: SETTLEMENT_STATUS[data[o.settlementStatus]] ?? "Unknown",
+        settlementErSlot: uLE(data, o.settlementErSlot, 8),
+        settlementStartedL1Slot: uLE(data, o.settlementStartedL1Slot, 8),
+        bump: data[o.bump],
+    };
+}
 // ---- SPL token account amount (u64 @ 64) ----
 export function decodeTokenAmount(data) {
     if (data.length < 72)
@@ -2321,6 +2356,22 @@ export class NorthstarEva {
     getSessionPdaFromEr() { return this.erRpc("getSessionPda"); }
     getDelegatedAccounts() { return this.erRpc("getDelegatedAccounts"); }
     sessionPda() { return portal.sessionPda(this.cfg.portalProgramId); }
+    /**
+     * Read + decode the Portal session account from L1 (the single global session for this Portal).
+     * Returns `null` if no valid session exists. Read-only — no transaction, no fee. Use the returned
+     * `ttlSlots`/`createdAt`/`expiresAtSlot`/`validator` for details (compare `expiresAtSlot` to the
+     * current L1 slot — `await this.l1.getSlot()` — to tell if it's expired).
+     */
+    async getSession() {
+        const info = await this.l1GetAccount(this.sessionPda());
+        if (!info || info.data.length < SESSION_LEN || info.data[0] !== SESSION_DISCRIMINATOR)
+            return null;
+        return decodeSession(info.data);
+    }
+    /** True if a valid Portal session is open on L1 (read-only; no tx). */
+    async isSessionOpen() {
+        return (await this.getSession()) !== null;
+    }
     // ───────────────────────── 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) {
@@ -2415,16 +2466,28 @@ export class NorthstarEva {
     buildCloseSessionIx() {
         return portal.closeSessionIx({ programId: this.cfg.portalProgramId, closer: this.payer });
     }
+    /**
+     * Build version of {@link ensureSession}: returns the OpenSession instruction **only if the
+     * session isn't created yet**, or **`null`** if it already exists. Async (it reads the session
+     * on L1). The caller composes the returned ix into a tx, signs, and submits — e.g.:
+     * `const ix = await sdk.buildEnsureSessionIx(); if (ix) tx.add(ix);`
+     */
+    async buildEnsureSessionIx() {
+        this.requireNorthStar("buildEnsureSessionIx");
+        if (await this.l1GetAccount(this.sessionPda()))
+            return null; // already created
+        return this.buildOpenSessionIx();
+    }
     /** Portal DepositFee instruction (L1) — "fund fee to ER payer". (Caller must ensure a session exists.) */
     buildDepositFeeIx(lamports, recipient = this.payer) {
         return portal.depositFeeIx({ programId: this.cfg.portalProgramId, depositor: this.payer, recipient, lamports });
     }
-    /** "Withdraw fee from ER" instruction (ER) — system transfer from `recipient` (default: signer) → its WithdrawalSink. (Portal SOL bridge; distinct from the eva `withdraw` instruction.) */
+    /** "Withdraw fee from ER" instruction (ER) — system transfer from `sender` (default: the signer) → its WithdrawalSink. (Portal SOL bridge; distinct from the eva `withdraw` instruction.) */
     buildWithdrawFeeFromErIx(p) {
-        const recipient = p.recipient ?? this.payer;
-        if (p.toL1 && !p.toL1.equals(recipient))
-            throw new Error("Arbitrary L1 withdrawal destination is not supported yet (Portal pays the deposit recipient). Omit `toL1` or set it equal to recipient.");
-        return SystemProgram.transfer({ fromPubkey: recipient, toPubkey: this.getWithdrawalSink(recipient), lamports: Number(p.lamports) });
+        const sender = p.sender ?? this.payer;
+        if (p.toL1 && !p.toL1.equals(sender))
+            throw new Error("Arbitrary L1 withdrawal destination is not supported yet (Portal pays the sender). Omit `toL1` or set it equal to sender.");
+        return SystemProgram.transfer({ fromPubkey: sender, toPubkey: this.getWithdrawalSink(sender), lamports: Number(p.lamports) });
     }
     /** Next sequential trench id (= total_trenches + 1) read from the ER global state. */
     async nextTrenchId() { return (await this.requireGlobal()).totalTrenches + 1n; }
@@ -2630,19 +2693,18 @@ export class NorthstarEva {
      * WithdrawalSink, returning the fee to whoever sent it. The validator pays the L1 SOL
      * ASYNCHRONOUSLY at the next settlement (use {@link waitForL1Settlement} to await it).
      *
-     * By default the **sender = the SDK's signer** (the account that funded the ER), so
-     * `withdrawFeeFromEr({ lamports })` reclaims to the sender — no recipient needed. You may
-     * still pass `recipient` (a Keypair OR a wallet adapter) to reclaim a different funded
-     * account; it signs the ER transfer (the L1 receiver never signs).
+     * `sender` is a **PublicKey** (default: the SDK signer's pubkey). This send-method signs with
+     * the SDK's wallet adapter — so `sender` must be the SDK's own account (the user's wallet, which
+     * signs remotely; no secret key needed). To withdraw for a different account whose signature you
+     * collect elsewhere, use {@link buildWithdrawFeeFromErIx} and have that account sign the tx.
      *
      * NOTE: the L1 payout goes to the SAME account that deposited (the sender) — an arbitrary
      * `toL1` destination is not supported by the Portal program yet (pending protocol change).
      */
     async requestWithdraw(p) {
         this.requireNorthStar("withdrawFeeFromEr (withdraw ER→L1)");
-        const sender = p.recipient ?? this.wallet; // default: the sender (SDK signer)
-        const ix = this.buildWithdrawFeeFromErIx({ lamports: p.lamports, recipient: sender.publicKey, toL1: p.toL1 });
-        return this.sendOnEr([ix], [sender]);
+        const ix = this.buildWithdrawFeeFromErIx({ lamports: p.lamports, sender: p.sender ?? this.payer, toL1: p.toL1 });
+        return this.sendOnEr([ix], [this.wallet]); // signed by the SDK's wallet adapter (the user)
     }
     /** "Withdraw fee from ER" (the green-box withdraw API) — alias of {@link requestWithdraw}. */
     async withdrawFeeFromEr(p) {

package/package.json

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