northstar-eva-sdk 0.6.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
 

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,6 +382,13 @@ 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 `sender` (default: the signer) → its WithdrawalSink. (Portal SOL bridge; distinct from the eva `withdraw` instruction.) */

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,6 +2466,18 @@ 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 });

package/package.json

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