northstar-eva-sdk 0.2.0 → 0.3.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).
 
+## What's new in 0.3.0
+
+**Construct from your existing `program` + `provider`, and an exported `EVA_IDL` — minimal code change.**
+
+- **Pass a pre-built Anchor `program`.** `NorthstarEva.create({ program, provider, erRpc })` mirrors the old `new EvaArenaSDK(program, provider)` shape. The SDK **adopts `program.programId` as the single source of truth** (all PDA derivations follow it) and reuses the program's `provider.wallet` + `provider.connection` — so the program id can never disagree between L1 and the ER, or across environments. (If you *also* pass a conflicting `evaProgramId`, the SDK throws instead of silently mismatching.)
+- **`EVA_IDL` is now exported** — build your program exactly like before:
+  ```ts
+  import { NorthstarEva, EVA_IDL } from "northstar-eva-sdk";
+
+  const wallet   = new ReadOnlyWallet(userPubkey);                         // no Keypair (Turnkey)
+  const provider = new anchor.AnchorProvider(connection, wallet, { commitment: "confirmed" });
+  const programId = getProgramId();                                       // per-environment id
+  const program  = new anchor.Program({ ...EVA_IDL, address: programId.toBase58() }, provider);
+
+  const sdk = NorthstarEva.create({ program, provider, erRpc: ER_RPC_URL });
+  // sdk.evaProgramId === programId  (adopted from your program)
+  ```
+- The eva program is **one address, identical on L1 and ER** (the ER reanchors and executes the L1 program — there is no separate ER deployment), and both `evaProgramId`/`portalProgramId` remain configurable + readable via `sdk.evaProgramId` / `sdk.portalProgramId`.
+
+> Backwards compatible: `{ network, wallet: keypair }` and `{ provider, erRpc, evaProgramId }` both still work.
+
 ## What's new in 0.2.0
 
 Integration-friendly construction — **no Keypair required, keep your provider, any RPC URL.**

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

@@ -249,6 +249,16 @@ export interface NorthstarEvaOptions extends NorthstarEvaInput {
     provider?: anchor.AnchorProvider;
     /** Explicit L1 connection (alternative to `provider`/`l1Rpc`). */
     connection?: Connection;
+    /**
+     * A pre-built Anchor `Program` for eva (as you already build with your IDL + program id).
+     * If given, it becomes the SINGLE SOURCE OF TRUTH for the program id — the SDK adopts
+     * `program.programId` (so all PDA derivations follow it), and reuses the program's
+     * `provider.wallet`/`provider.connection` for the signer + L1 endpoint. Use the exported
+     * `EVA_IDL` to build it: `new anchor.Program({ ...EVA_IDL, address }, provider)`.
+     */
+    program?: anchor.Program<Idl>;
+    /** Alias of `program`. */
+    evaProgram?: anchor.Program<Idl>;
     /** eva IDL object. If omitted, loaded from `evaIdlPath` or the bundled IDL. */
     evaIdl?: Idl;
     evaIdlPath?: string;
@@ -257,6 +267,12 @@ export interface NorthstarEvaOptions extends NorthstarEvaInput {
     /** ms between status/read polls. */
     pollIntervalMs?: number;
 }
+/**
+ * The eva Anchor IDL, exported as a constant so you can build your own `Program`:
+ * `new anchor.Program({ ...EVA_IDL, address: programId.toBase58() }, provider)` and pass it
+ * to `NorthstarEva.create({ program, provider, erRpc })`.
+ */
+export declare const EVA_IDL: Idl;
 export declare class NorthstarEva {
     readonly cfg: ResolvedConfig;
     readonly l1: Connection;

package/dist/northstar-eva-sdk.js

@@ -2144,6 +2144,12 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function loadBundledIdl() {
     return __EVA_IDL__;
 }
+/**
+ * The eva Anchor IDL, exported as a constant so you can build your own `Program`:
+ * `new anchor.Program({ ...EVA_IDL, address: programId.toBase58() }, provider)` and pass it
+ * to `NorthstarEva.create({ program, provider, erRpc })`.
+ */
+export const EVA_IDL = loadBundledIdl();
 export class NorthstarEva {
     cfg;
     l1;
@@ -2160,10 +2166,18 @@ export class NorthstarEva {
     /** The Portal program id in use. */
     get portalProgramId() { return this.cfg.portalProgramId; }
     constructor(opts) {
-        // ── 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 ──
+        // 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.
+        const passedProgram = opts.program ?? opts.evaProgram;
+        const programProvider = passedProgram?.provider;
+        const programId = passedProgram?.programId?.toBase58();
+        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 ──
+        const providerConn = opts.provider?.connection ?? opts.connection ?? programProvider?.connection;
+        this.cfg = resolveConfig({ ...opts, l1Rpc: opts.l1Rpc ?? providerConn?.rpcEndpoint, 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;
         if (isWalletLike(w))
@@ -2172,8 +2186,10 @@ export class NorthstarEva {
             signer = new A.Wallet(w); // a Keypair → wrap (NodeWallet)
         else if (opts.provider?.wallet)
             signer = opts.provider.wallet;
+        else if (programProvider?.wallet)
+            signer = programProvider.wallet;
         if (!signer)
-            throw new Error("Pass `wallet` (a Keypair or a wallet adapter with signTransaction) or a `provider` (AnchorProvider).");
+            throw new Error("Pass `wallet` (a Keypair or a wallet adapter with signTransaction), a `provider` (AnchorProvider), or a `program` whose provider has a wallet.");
         this.wallet = signer;
         this.payer = signer.publicKey;
         this.validatorIdentity = opts.validatorIdentity
@@ -2190,11 +2206,17 @@ export class NorthstarEva {
         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
-        // 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);
+        if (passedProgram) {
+            // Use the caller's program as-is (only used to BUILD instructions; the SDK sends manually).
+            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.
+            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); }
     // ───────────────────────── ER transport (raw RPC, retries, processed) ─────────────────────────

package/package.json

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