northstar-eva-sdk 0.1.1 → 0.3.0

package/README.md

@@ -9,10 +9,57 @@ npm install northstar-eva-sdk @solana/web3.js @coral-xyz/anchor @solana/spl-toke
 ```
 ```ts
 import { NorthstarEva } from "northstar-eva-sdk";
+// localnet with a Keypair:
 const sdk = NorthstarEva.create({ network: "localnet", wallet });
+// OR keep your existing AnchorProvider + read-only wallet + custom RPC (see 0.2.0):
+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.**
+
+- **Read-only / remote wallets are supported.** `wallet` now accepts any **wallet adapter** (`publicKey` + `signTransaction`) — e.g. a Turnkey `ReadOnlyWallet` — not just a `Keypair`. The SDK signs through `signTransaction` and never needs the secret key. (Fixes the `Type 'Wallet' is missing … 'secretKey'` error.)
+- **Pass your `AnchorProvider` directly.** `NorthstarEva.create({ provider })` reuses the provider's `.wallet` (signer) and `.connection` (the **L1** endpoint) — keep the exact provider/program setup you already have.
+- **Any RPC URL (not just localhost).** Pass `l1Rpc` + `erRpc` (or `provider`/`connection` + `erRpc`). `network` is now just an optional label (any string) and no longer rejects a URL. **The ER is a separate endpoint — always pass `erRpc`** (the SDK throws a clear error if a custom L1 is given without it).
+- **Program ids are configurable + exposed.** `evaProgramId` / `portalProgramId` are options *and* readable as `sdk.evaProgramId` / `sdk.portalProgramId`.
+- **Dynamic recipients.** Deposit credits any `recipient` (a `PublicKey`); withdraw's `recipient` accepts a `Keypair` **or** a wallet adapter (and defaults to the SDK signer).
+
+**Migration — your old `new EvaArenaSDK(program, provider)` shape, unchanged inputs:**
+```ts
+const userPubkey = new PublicKey(turnkeyAddress);
+const wallet     = new ReadOnlyWallet(userPubkey);                       // no Keypair
+const provider   = new anchor.AnchorProvider(connection, wallet, { commitment: "confirmed" });
+const sdk = NorthstarEva.create({
+  provider,                    // keeps provider + read-only wallet
+  erRpc: ER_RPC_URL,           // the NorthStar ER endpoint (any URL)
+  evaProgramId: getProgramId(),// per-environment program id
+});
+```
+> Backwards compatible: `NorthstarEva.create({ network, wallet: keypair })` still works (the Keypair is wrapped automatically). No method signatures changed.
+
 ## 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:

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

@@ -136,7 +136,12 @@ export interface ResolvedConfig {
     settlementIntervalSlots: bigint;
 }
 export interface NorthstarEvaInput {
-    network?: NetworkName;
+    /**
+     * A preset name (`"localnet"` | `"devnet"`) OR any custom label — presets only set
+     * default endpoints. To use ANY RPC (not localhost), pass `l1Rpc` + `erRpc` (or a
+     * `provider`/`connection`); `network` is then just a label and may be any string.
+     */
+    network?: NetworkName | (string & {});
     l1Rpc?: string;
     erRpc?: string;
     erWs?: string;
@@ -217,25 +222,72 @@ export interface ErTxResult {
     err: unknown | null;
     confirmed: boolean;
 }
+/**
+ * A wallet adapter the SDK can sign through — exactly what Anchor's `Wallet`,
+ * a wallet-adapter, or a Turnkey/remote `ReadOnlyWallet` already implement.
+ * The SDK never needs the secret key, so a `Keypair` is NOT required.
+ */
+export interface WalletLike {
+    publicKey: PublicKey;
+    signTransaction<T extends Transaction>(tx: T): Promise<T>;
+    signAllTransactions?<T extends Transaction>(txs: T[]): Promise<T[]>;
+}
+/** Anything the SDK can sign a tx with: a raw Keypair (it partial-signs) or a wallet adapter. */
+export type TxSigner = Keypair | WalletLike;
 export interface NorthstarEvaOptions extends NorthstarEvaInput {
-    /** Signer / fee payer. (v1: a Keypair.) */
-    wallet: Keypair;
+    /**
+     * Signer / fee payer. A `Keypair` (wrapped automatically) **or** any wallet adapter
+     * (`publicKey` + `signTransaction`) — e.g. a Turnkey `ReadOnlyWallet`. Optional when
+     * `provider` is given (its `.wallet` is used).
+     */
+    wallet?: TxSigner;
+    /**
+     * An Anchor `AnchorProvider` (as you already build for eva). Its `.wallet` becomes the
+     * signer and its `.connection` becomes the **L1** connection — so you keep your provider.
+     * NOTE: the ER is a SEPARATE endpoint, so still pass `erRpc`.
+     */
+    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;
-    /** Validator identity recorded in the session (settlement signer). Defaults to wallet. */
+    /** Validator identity recorded in the session (settlement signer). Defaults to the signer. */
     validatorIdentity?: string | PublicKey;
     /** 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;
     readonly er: Connection;
-    readonly wallet: Keypair;
+    /** The signer as a wallet adapter (a passed Keypair is wrapped). Use `.payer` for its pubkey. */
+    readonly wallet: WalletLike;
+    /** The fee-payer / signer public key. */
+    readonly payer: PublicKey;
     readonly validatorIdentity: PublicKey;
     readonly program: anchor.Program<Idl>;
     private readonly pollMs;
+    /** The eva program id in use (configurable per environment). */
+    get evaProgramId(): PublicKey;
+    /** The Portal program id in use. */
+    get portalProgramId(): PublicKey;
     constructor(opts: NorthstarEvaOptions);
     static create(opts: NorthstarEvaOptions): NorthstarEva;
     erRpc<T = any>(method: string, params?: unknown[]): Promise<T>;
@@ -255,9 +307,11 @@ export declare class NorthstarEva {
     getSessionPdaFromEr(): Promise<any>;
     getDelegatedAccounts(): Promise<string[]>;
     sessionPda(): anchor.web3.PublicKey;
+    /** Sign `tx` with a mixed set of signers: raw Keypairs are partial-signed, wallet adapters sign via signTransaction. */
+    private signTx;
     private sendOnL1;
     /** Send a tx to the ER and confirm by polling (the ER returns Ok on acceptance). */
-    sendOnEr(instructions: Transaction["instructions"], signers: Keypair[]): Promise<ErTxResult>;
+    sendOnEr(instructions: Transaction["instructions"], signers: TxSigner[]): Promise<ErTxResult>;
     private sendEva;
     /** Fetch eva GlobalState from the ER or throw a clear "not initialized" error. */
     private requireGlobal;
@@ -331,21 +385,22 @@ export declare class NorthstarEva {
     /**
      * "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` is a Keypair (it signs the
-     * ER transfer; the L1 receiver never signs).
+     * (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.
      *
      * NOTE: the L1 payout currently goes to the SAME account that deposited — an arbitrary
      * `toL1` destination is not supported by the Portal program yet (pending protocol change).
      */
     requestWithdraw(p: {
         lamports: bigint;
-        recipient: Keypair;
+        recipient?: TxSigner;
         toL1?: PublicKey;
     }): Promise<ErTxResult>;
     /** "Withdraw fee from ER" (the green-box withdraw API) — alias of {@link requestWithdraw}. */
     withdrawFeeFromEr(p: {
         lamports: bigint;
-        recipient: Keypair;
+        recipient?: TxSigner;
         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

@@ -7,7 +7,7 @@
 // ============================================================================
 import * as anchor from "@coral-xyz/anchor";
 import { readFileSync } from "node:fs";
-import { Connection, Keypair, PublicKey, SystemProgram, Transaction, TransactionInstruction, sendAndConfirmTransaction } from "@solana/web3.js";
+import { Connection, Keypair, PublicKey, SystemProgram, Transaction, TransactionInstruction } from "@solana/web3.js";
 import { TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID, getAssociatedTokenAddressSync, createAssociatedTokenAccountIdempotentInstruction } from "@solana/spl-token";
 // --- embedded eva IDL (CQru6…) ---
 const __EVA_IDL__ = {
@@ -1978,12 +1978,15 @@ export const NETWORKS = {
 const pk = (v) => (typeof v === "string" ? new PublicKey(v) : v);
 const bn = (v, d) => (v === undefined ? d : BigInt(v));
 export function resolveConfig(input) {
-    const preset = NETWORKS[input.network ?? "localnet"];
+    // Only "localnet"/"devnet" are presets; any other `network` value is just a label and
+    // falls back to the localnet preset for defaults — pass l1Rpc/erRpc to override them.
+    const presetKey = input.network === "devnet" ? "devnet" : "localnet";
+    const preset = NETWORKS[presetKey];
     const l1Rpc = input.l1Rpc ?? preset.l1Rpc;
     const erRpc = input.erRpc ?? preset.erRpc;
     if (!l1Rpc || !erRpc) {
-        throw new Error(`Missing RPC endpoints for network "${input.network}". For devnet, pass l1Rpc + erRpc ` +
-            `pointing at your NorthStar node (public Solana devnet has no ER/Portal).`);
+        throw new Error(`Missing RPC endpoints for network "${input.network}". Pass l1Rpc + erRpc (or a provider + erRpc) ` +
+            `pointing at your NorthStar node — public Solana devnet has no ER/Portal, and the ER is a SEPARATE URL from L1.`);
     }
     return {
         l1Rpc,
@@ -2136,32 +2139,84 @@ const evaPdas = { globalStatePda, trenchPda, agentPda, tokenMintPda, trenchToken
  */
 // @coral-xyz/anchor is CommonJS — runtime values live on the default export.
 const A = anchor.default ?? anchor;
+const isWalletLike = (s) => !!s && typeof s.signTransaction === "function";
 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;
     er;
+    /** The signer as a wallet adapter (a passed Keypair is wrapped). Use `.payer` for its pubkey. */
     wallet;
+    /** The fee-payer / signer public key. */
+    payer;
     validatorIdentity;
     program; // eva, bound to the ER connection
     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; }
     constructor(opts) {
-        this.cfg = resolveConfig(opts);
-        this.wallet = opts.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))
+            signer = w; // already an adapter / ReadOnlyWallet
+        else if (w && w.secretKey)
+            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), a `provider` (AnchorProvider), or a `program` whose provider has a wallet.");
+        this.wallet = signer;
+        this.payer = signer.publicKey;
         this.validatorIdentity = opts.validatorIdentity
             ? (typeof opts.validatorIdentity === "string" ? new PublicKey(opts.validatorIdentity) : opts.validatorIdentity)
-            : opts.wallet.publicKey;
+            : this.payer;
         this.pollMs = opts.pollIntervalMs ?? 500;
-        this.l1 = new Connection(this.cfg.l1Rpc, "confirmed");
+        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");
-        const idl = opts.evaIdl ?? (opts.evaIdlPath ? JSON.parse(readFileSync(opts.evaIdlPath, "utf8")) : loadBundledIdl());
-        idl.address = this.cfg.evaProgramId.toBase58(); // honor config / devnet override
-        const provider = new A.AnchorProvider(this.er, new A.Wallet(this.wallet), { commitment: "processed" });
-        this.program = new A.Program(idl, provider);
+        // 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).`);
+        }
+        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) ─────────────────────────
@@ -2220,10 +2275,27 @@ export class NorthstarEva {
     getSessionPdaFromEr() { return this.erRpc("getSessionPda"); }
     getDelegatedAccounts() { return this.erRpc("getDelegatedAccounts"); }
     sessionPda() { return portal.sessionPda(this.cfg.portalProgramId); }
+    // ───────────────────────── 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) {
+        const keypairs = signers.filter((s) => !isWalletLike(s));
+        const wallets = signers.filter(isWalletLike);
+        if (keypairs.length)
+            tx.partialSign(...keypairs);
+        let signed = tx;
+        for (const wlt of wallets)
+            signed = await wlt.signTransaction(signed); // adds payer sig, preserves partials
+        return signed;
+    }
     // ───────────────────────── L1 send + ER send ─────────────────────────
     async sendOnL1(instructions, signers) {
-        const tx = new Transaction().add(...instructions);
-        return sendAndConfirmTransaction(this.l1, tx, signers, { commitment: "confirmed", skipPreflight: false });
+        const { blockhash, lastValidBlockHeight } = await this.l1.getLatestBlockhash("confirmed");
+        const tx = new Transaction({ feePayer: signers[0].publicKey, blockhash, lastValidBlockHeight });
+        tx.add(...instructions);
+        const signed = await this.signTx(tx, signers);
+        const sig = await this.l1.sendRawTransaction(signed.serialize(), { skipPreflight: false, preflightCommitment: "confirmed" });
+        await this.l1.confirmTransaction({ signature: sig, blockhash, lastValidBlockHeight }, "confirmed");
+        return sig;
     }
     /** Send a tx to the ER and confirm by polling (the ER returns Ok on acceptance). */
     async sendOnEr(instructions, signers) {
@@ -2233,8 +2305,8 @@ export class NorthstarEva {
                 const { blockhash } = await this.er.getLatestBlockhash("processed");
                 const tx = new Transaction({ feePayer: signers[0].publicKey, blockhash, lastValidBlockHeight: 0 });
                 tx.add(...instructions);
-                tx.sign(...signers);
-                signature = await this.er.sendRawTransaction(tx.serialize(), { skipPreflight: false, preflightCommitment: "processed" });
+                const signed = await this.signTx(tx, signers);
+                signature = await this.er.sendRawTransaction(signed.serialize(), { skipPreflight: false, preflightCommitment: "processed" });
                 break;
             }
             catch (e) {
@@ -2410,19 +2482,21 @@ export class NorthstarEva {
     /**
      * "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` is a Keypair (it signs the
-     * ER transfer; the L1 receiver never signs).
+     * (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.
      *
      * NOTE: the L1 payout currently goes to the SAME account that deposited — an arbitrary
      * `toL1` destination is not supported by the Portal program yet (pending protocol change).
      */
     async requestWithdraw(p) {
-        if (p.toL1 && !p.toL1.equals(p.recipient.publicKey)) {
+        const recipient = p.recipient ?? this.wallet;
+        if (p.toL1 && !p.toL1.equals(recipient.publicKey)) {
             throw new Error("Arbitrary L1 withdrawal destination is not supported yet (Portal pays the deposit recipient). Omit `toL1` or set it equal to recipient.");
         }
-        const sink = this.getWithdrawalSink(p.recipient.publicKey);
-        const ix = SystemProgram.transfer({ fromPubkey: p.recipient.publicKey, toPubkey: sink, lamports: Number(p.lamports) });
-        return this.sendOnEr([ix], [p.recipient]);
+        const sink = this.getWithdrawalSink(recipient.publicKey);
+        const ix = SystemProgram.transfer({ fromPubkey: recipient.publicKey, toPubkey: sink, lamports: Number(p.lamports) });
+        return this.sendOnEr([ix], [recipient]);
     }
     /** "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.1.1",
+  "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",