northstar-eva-sdk 0.4.0 → 0.5.0

package/README.md

@@ -16,6 +16,27 @@ 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).
 
+## Construction — one SDK, three ways (NorthStar or not)
+
+The SDK splits two method families: **eva-contract methods** (`initialize`/`createTrench`/`deposit`/`withdraw`/`finalize`/`buy`/`sell`/…) always run on your **`program` + `provider`**; the **NorthStar bridge methods** (`openSession`/`fundFeeToErPayer`/`withdrawFeeFromEr`) need the **L1 + ER** lanes. Pick the construction that fits your service — `sdk.isNorthStar` tells you which mode you're in.
+
+```ts
+// (1) provider IS the ER, L1 passed separately — RECOMMENDED for NorthStar apps
+const sdk = NorthstarEva.create({ program, provider, l1Endpoint: "https://api.devnet.solana.com" });
+//   → provider.connection = ER, l1Endpoint = L1.  sdk.isNorthStar === true
+
+// (2) NO NorthStar — the SAME SDK as a plain eva client (one chain, no ER/Portal)
+const sdk = NorthstarEva.create({ program, provider });
+//   → eva methods run on the provider; deposit/withdraw/session throw "requires NorthStar".  sdk.isNorthStar === false
+
+// (3) legacy: provider = L1, ER passed as erRpc (still supported)
+const sdk = NorthstarEva.create({ provider, erRpc: "https://ephemeral.devnet.sonic.game" });
+```
+
+- **`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.
+
 ## What's new in 0.4.0
 
 **Complete eva coverage — the SDK now mirrors all 11 eva instructions.** Added the 5 that were missing: `updateConfig`, `withdraw`, `closePool`, `claimTokens`, `distributePrize` (each with a `build…Ix` twin):

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

@@ -145,6 +145,12 @@ export interface NorthstarEvaInput {
     l1Rpc?: string;
     erRpc?: string;
     erWs?: string;
+    /**
+     * The L1 endpoint, for the "provider is the ER" convention: when set, the SDK treats the
+     * `provider`/`connection` RPC as the **ER** and uses `l1Endpoint` as the **L1** (Portal) lane.
+     * (Alternative to passing `erRpc` with a provider that points at L1.)
+     */
+    l1Endpoint?: string;
     portalProgramId?: string | PublicKey;
     evaProgramId?: string | PublicKey;
     gridId?: number | bigint;
@@ -283,11 +289,17 @@ export declare class NorthstarEva {
     readonly payer: PublicKey;
     readonly validatorIdentity: PublicKey;
     readonly program: anchor.Program<Idl>;
+    /** Whether the NorthStar ER + Portal bridge is configured (false = plain Solana, eva only). */
+    readonly northstar: boolean;
     private readonly pollMs;
     /** The eva program id in use (configurable per environment). */
     get evaProgramId(): PublicKey;
     /** The Portal program id in use. */
     get portalProgramId(): PublicKey;
+    /** True when deposit/withdraw/session (the NorthStar Portal/ER bridge) are available. */
+    get isNorthStar(): boolean;
+    /** Throws if the NorthStar bridge isn't configured (used to guard Portal-only methods). */
+    private requireNorthStar;
     constructor(opts: NorthstarEvaOptions);
     static create(opts: NorthstarEvaOptions): NorthstarEva;
     erRpc<T = any>(method: string, params?: unknown[]): Promise<T>;
@@ -475,13 +487,16 @@ export declare class NorthstarEva {
     /** 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` 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.
+     * "Withdraw fee from ER" (path 2): an ER `system_transfer` from the **sender** → its
+     * 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).
      *
-     * NOTE: the L1 payout currently goes to the SAME account that deposited — an arbitrary
+     * 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: {

package/dist/northstar-eva-sdk.js

@@ -2159,12 +2159,21 @@ export class NorthstarEva {
     /** The fee-payer / signer public key. */
     payer;
     validatorIdentity;
-    program; // eva, bound to the ER connection
+    program; // eva, runs on the ER (= provider) connection
+    /** Whether the NorthStar ER + Portal bridge is configured (false = plain Solana, eva only). */
+    northstar;
     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; }
+    /** True when deposit/withdraw/session (the NorthStar Portal/ER bridge) are available. */
+    get isNorthStar() { return this.northstar; }
+    /** Throws if the NorthStar bridge isn't configured (used to guard Portal-only methods). */
+    requireNorthStar(op) {
+        if (!this.northstar)
+            throw new Error(`${op} requires NorthStar (the ER + Portal bridge), which is not configured. Pass \`l1Endpoint\` (with a provider whose RPC is the ER) or \`erRpc\` to enable deposit/withdraw/session. Without it, only the eva program methods work (plain Solana).`);
+    }
     constructor(opts) {
         // A pre-built Anchor program (Bai's `(program, provider)` shape) is the source of truth
         // for the program id, and can also supply the provider's wallet + L1 connection.
@@ -2174,9 +2183,39 @@ export class NorthstarEva {
         if (passedProgram && opts.evaProgramId && new PublicKey(opts.evaProgramId).toBase58() !== programId) {
             throw new Error(`evaProgramId (${new PublicKey(opts.evaProgramId).toBase58()}) does not match the passed program.programId (${programId}). Pass one source of truth.`);
         }
-        // ── endpoints: a provider/connection/program can supply the L1 endpoint; ER is always separate ──
+        // ── endpoints: resolve the L1 + ER lanes and whether NorthStar (ER+Portal) is active ──
         const providerConn = opts.provider?.connection ?? opts.connection ?? programProvider?.connection;
-        this.cfg = resolveConfig({ ...opts, l1Rpc: opts.l1Rpc ?? providerConn?.rpcEndpoint, evaProgramId: opts.evaProgramId ?? programId });
+        const providerEndpoint = providerConn?.rpcEndpoint;
+        const l1Endpoint = opts.l1Endpoint ?? opts.L1Endpoint; // accept Bai's casing too
+        let l1RpcStr, erRpcStr, northstar;
+        if (l1Endpoint) {
+            // NEW convention: the provider's RPC IS the ER; l1Endpoint is the L1 (Portal) lane.
+            northstar = true;
+            l1RpcStr = l1Endpoint;
+            erRpcStr = opts.erRpc ?? providerEndpoint;
+            if (!erRpcStr)
+                throw new Error("`l1Endpoint` was given but no ER RPC — pass a `provider`/`connection` (its RPC is the ER) or an explicit `erRpc`.");
+        }
+        else if (opts.erRpc) {
+            // LEGACY convention: provider's RPC is L1, erRpc is the ER.
+            northstar = true;
+            l1RpcStr = opts.l1Rpc ?? providerEndpoint;
+            erRpcStr = opts.erRpc;
+        }
+        else if (providerEndpoint || opts.l1Rpc) {
+            // NO-NORTHSTAR: a single chain (provider / l1Rpc). eva runs there; no Portal/ER bridge.
+            northstar = false;
+            l1RpcStr = erRpcStr = opts.l1Rpc ?? providerEndpoint;
+        }
+        else {
+            // Network preset (e.g. localnet has both lanes; devnet needs explicit endpoints).
+            const presetEr = NETWORKS[opts.network === "devnet" ? "devnet" : "localnet"].erRpc;
+            northstar = presetEr !== "";
+            l1RpcStr = opts.l1Rpc;
+            erRpcStr = opts.erRpc; // resolved from preset by resolveConfig below
+        }
+        this.northstar = northstar;
+        this.cfg = resolveConfig({ ...opts, l1Rpc: l1RpcStr ?? opts.l1Rpc, erRpc: erRpcStr ?? opts.erRpc, evaProgramId: opts.evaProgramId ?? programId });
         // ── signer: accept a Keypair (wrap it), a wallet adapter, provider.wallet, or program.provider.wallet ──
         const w = opts.wallet;
         let signer;
@@ -2196,24 +2235,31 @@ export class NorthstarEva {
             ? (typeof opts.validatorIdentity === "string" ? new PublicKey(opts.validatorIdentity) : opts.validatorIdentity)
             : this.payer;
         this.pollMs = opts.pollIntervalMs ?? 500;
-        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).`);
+        // Assign lanes per the resolved convention. `this.er` is where the eva program executes
+        // (the provider's connection in the new/no-NorthStar modes); reads use "processed" so
+        // read-after-write is fresh. `this.l1` is the Portal control lane.
+        if (l1Endpoint) {
+            // provider IS the ER; l1Endpoint is the L1.
+            this.er = providerConn ?? new Connection(this.cfg.erRpc, "processed");
+            this.l1 = new Connection(this.cfg.l1Rpc, "confirmed");
+        }
+        else if (!northstar) {
+            // single chain: eva runs on the provider; no separate Portal/ER lane.
+            this.l1 = this.er = providerConn ?? new Connection(this.cfg.l1Rpc, "confirmed");
+        }
+        else {
+            // legacy / preset: provider (if any) is L1, ER is its own endpoint.
+            this.l1 = providerConn ?? new Connection(this.cfg.l1Rpc, "confirmed");
+            this.er = new Connection(this.cfg.erRpc, "processed");
         }
         if (passedProgram) {
-            // Use the caller's program as-is (only used to BUILD instructions; the SDK sends manually).
+            // Use the caller's program (program + provider) as-is — eva methods build from it.
             this.program = passedProgram;
         }
         else {
             const idl = opts.evaIdl ?? (opts.evaIdlPath ? JSON.parse(readFileSync(opts.evaIdlPath, "utf8")) : loadBundledIdl());
             idl.address = this.cfg.evaProgramId.toBase58(); // honor config / devnet override
-            // eva program is bound to the ER connection (it executes there) + signs through the same wallet.
+            // eva program runs on `this.er` (= provider) + signs through the same wallet.
             const provider = new A.AnchorProvider(this.er, this.wallet, { commitment: "processed" });
             this.program = new A.Program(idl, provider);
         }
@@ -2455,6 +2501,7 @@ export class NorthstarEva {
     }
     // ───────────────────────── Portal control (L1) ─────────────────────────
     async openSession() {
+        this.requireNorthStar("openSession");
         const pda = this.sessionPda();
         if (await this.l1GetAccount(pda))
             return { signature: null, sessionPda: pda, alreadyOpen: true };
@@ -2462,6 +2509,7 @@ export class NorthstarEva {
         return { signature, sessionPda: pda, alreadyOpen: false };
     }
     async closeSession() {
+        this.requireNorthStar("closeSession");
         return this.sendOnL1([this.buildCloseSessionIx()], [this.wallet]);
     }
     /**
@@ -2487,6 +2535,7 @@ export class NorthstarEva {
      * Returns the DepositFee transaction signature.
      */
     async fundErFeePayer(lamports, recipient = this.wallet.publicKey, opts = {}) {
+        this.requireNorthStar("fundFeeToErPayer (deposit L1→ER)");
         if (opts.ensureSession !== false)
             await this.ensureSession();
         return this.sendOnL1([this.buildDepositFeeIx(lamports, recipient)], [this.wallet]);
@@ -2577,19 +2626,23 @@ export class NorthstarEva {
         return portal.withdrawalSinkPda(this.cfg.portalProgramId, this.sessionPda(), recipient);
     }
     /**
-     * "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` 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.
+     * "Withdraw fee from ER" (path 2): an ER `system_transfer` from the **sender** → its
+     * 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).
      *
-     * NOTE: the L1 payout currently goes to the SAME account that deposited — an arbitrary
+     * 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) {
-        const recipient = p.recipient ?? this.wallet;
-        const ix = this.buildWithdrawFeeFromErIx({ lamports: p.lamports, recipient: recipient.publicKey, toL1: p.toL1 });
-        return this.sendOnEr([ix], [recipient]);
+        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]);
     }
     /** "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.4.0",
+  "version": "0.5.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",