northstar-eva-sdk 0.3.0 → 0.5.0

package/README.md

@@ -16,6 +16,62 @@ 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):
+
+```ts
+// admin / lifecycle
+await sdk.updateConfig({ biddingDuration: 120n, tradingDuration: 100_000n, feeRecipient });
+await sdk.withdraw({ trenchId, amount: 20_000_000n });            // withdraw a bid deposit from a trench
+await sdk.closePool({ trenchId });
+await sdk.claimTokens({ trenchId, user });                        // release a user's tokens from the vault
+await sdk.distributePrize({ trenchId, winners: [w1, w2], amounts: [a1, a2] });
+```
+> Note: eva `withdraw` (withdraw a trench bid deposit) is **different** from the Portal `withdrawFeeFromEr` (bridge SOL ER→L1). They coexist.
+
+**Instruction builders — get the unsigned instruction instead of sending it.** Every send-method now has a `build…Ix` twin with the **same inputs** that returns an unsigned `TransactionInstruction`, so your backend can compose it with its own instructions, sign, and submit however it needs.
+
+```ts
+import { NorthstarEva } from "northstar-eva-sdk";
+
+// 1) build instructions (no signing, no network send — only the reads needed to resolve accounts)
+const ataIx = sdk.buildUserAtaIx({ trenchId });
+const buyIx = await sdk.buildBuyIx({ trenchId, solPayWithFee: 10_000_000n });
+
+// 2) compose them (add your own instructions too), get an unsigned Transaction
+const tx = await sdk.buildTransaction([ataIx, buyIx], { lane: "er" }); // feePayer + blockhash set
+
+// 3) your backend signs + submits — the SDK never sends it
+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.
+
+> 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**.
+
 ## What's new in 0.3.0
 
 **Construct from your existing `program` + `provider`, and an exported `EVA_IDL` — minimal code change.**

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>;
@@ -317,6 +329,97 @@ export declare class NorthstarEva {
     private requireGlobal;
     private get methods();
     private bn;
+    /** Portal OpenSession instruction (L1). */
+    buildOpenSessionIx(): TransactionInstruction;
+    /** Portal CloseSession instruction (L1). */
+    buildCloseSessionIx(): TransactionInstruction;
+    /** 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.) */
+    buildWithdrawFeeFromErIx(p: {
+        lamports: bigint;
+        recipient?: PublicKey;
+        toL1?: PublicKey;
+    }): TransactionInstruction;
+    /** Next sequential trench id (= total_trenches + 1) read from the ER global state. */
+    nextTrenchId(): Promise<bigint>;
+    /** eva initialize instruction (ER). */
+    buildInitializeIx(p: {
+        biddingDuration: bigint;
+        tradingDuration: bigint;
+    }): Promise<TransactionInstruction>;
+    /** eva createTrench instruction (ER). `trenchId` defaults to {@link nextTrenchId}. */
+    buildCreateTrenchIx(p?: {
+        trenchId?: bigint;
+        initialVirtualTokenReserves?: bigint;
+    }): Promise<TransactionInstruction>;
+    /** eva deposit instruction (ER). */
+    buildDepositIx(p: {
+        trenchId: bigint;
+        lamports: bigint;
+        thinkId?: bigint;
+        user?: PublicKey;
+    }): Promise<TransactionInstruction>;
+    /** eva finalize instruction (ER). Reads global for feeRecipient; does NOT wait for the bidding window. */
+    buildFinalizeIx(p: {
+        trenchId: bigint;
+    }): Promise<TransactionInstruction>;
+    /** ATA-create instruction (ER) for a user's trench token account (idempotent). */
+    buildUserAtaIx(p: {
+        trenchId: bigint;
+        user?: PublicKey;
+    }): TransactionInstruction;
+    /** eva buy instruction (ER). Reads global for feeRecipient. */
+    buildBuyIx(p: {
+        trenchId: bigint;
+        solPayWithFee: bigint;
+        thinkId?: bigint;
+        user?: PublicKey;
+    }): Promise<TransactionInstruction>;
+    /** eva sell instruction (ER). Reads global for feeRecipient. */
+    buildSellIx(p: {
+        trenchId: bigint;
+        tokenAmount: bigint;
+        minSolOutput?: bigint;
+        thinkId?: bigint;
+        user?: PublicKey;
+    }): Promise<TransactionInstruction>;
+    /** eva updateConfig instruction (ER, admin) — change bidding/trading durations + fee recipient. */
+    buildUpdateConfigIx(p: {
+        biddingDuration: bigint;
+        tradingDuration: bigint;
+        feeRecipient: PublicKey;
+    }): Promise<TransactionInstruction>;
+    /** eva withdraw instruction (ER) — withdraw a bid deposit from a trench (inverse of {@link buildDepositIx}). NOT the Portal SOL bridge ({@link buildWithdrawFeeFromErIx}). */
+    buildWithdrawIx(p: {
+        trenchId: bigint;
+        amount: bigint;
+        thinkId?: bigint;
+        user?: PublicKey;
+    }): Promise<TransactionInstruction>;
+    /** eva closePool instruction (ER, admin) — close a finished trench's pool. */
+    buildClosePoolIx(p: {
+        trenchId: bigint;
+    }): Promise<TransactionInstruction>;
+    /** eva claimTokens instruction (ER, admin) — release `user`'s tokens from the trench vault to their ATA. */
+    buildClaimTokensIx(p: {
+        trenchId: bigint;
+        user?: PublicKey;
+    }): Promise<TransactionInstruction>;
+    /** eva distributePrize instruction (ER, admin) — pay out the prize pool to `winners` by `amounts` (lamports). */
+    buildDistributePrizeIx(p: {
+        trenchId: bigint;
+        winners: PublicKey[];
+        amounts: bigint[];
+    }): Promise<TransactionInstruction>;
+    /**
+     * Bundle instruction(s) into an UNSIGNED `Transaction` (feePayer + recent blockhash set) for the
+     * given lane (`"er"` default, or `"l1"`). The backend signs + submits it (or adds more instructions first).
+     */
+    buildTransaction(instructions: TransactionInstruction | TransactionInstruction[], opts?: {
+        lane?: Lane;
+        feePayer?: PublicKey;
+    }): Promise<Transaction>;
     openSession(): Promise<{
         signature: string | null;
         sessionPda: PublicKey;
@@ -358,6 +461,7 @@ export declare class NorthstarEva {
     tokenMintPda(id: bigint): anchor.web3.PublicKey;
     trenchVault(id: bigint): anchor.web3.PublicKey;
     userAta(id: bigint, user?: PublicKey): anchor.web3.PublicKey;
+    agentPda(id: bigint, user?: PublicKey): anchor.web3.PublicKey;
     getGlobal(source?: Lane): Promise<GlobalState | null>;
     getTrench(id: bigint, source?: Lane, retries?: number): Promise<Trench | null>;
     getUserTokenBalance(id: bigint, user?: PublicKey, source?: Lane): Promise<bigint>;
@@ -383,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: {
@@ -449,4 +556,31 @@ export declare class NorthstarEva {
         trench: Trench;
         userTokens: bigint;
     }>;
+    /** eva updateConfig (ER, admin) — set bidding/trading durations + fee recipient on the global config. */
+    updateConfig(p: {
+        biddingDuration: bigint;
+        tradingDuration: bigint;
+        feeRecipient: PublicKey;
+    }): Promise<string>;
+    /** eva withdraw (ER) — withdraw a bid deposit from a trench (inverse of {@link deposit}; NOT the Portal SOL bridge {@link withdrawFeeFromEr}). */
+    withdraw(p: {
+        trenchId: bigint;
+        amount: bigint;
+        thinkId?: bigint;
+    }): Promise<string>;
+    /** eva closePool (ER, admin) — close a finished trench's pool. */
+    closePool(p: {
+        trenchId: bigint;
+    }): Promise<string>;
+    /** eva claimTokens (ER, admin) — release `user`'s tokens from the trench vault to their ATA. */
+    claimTokens(p: {
+        trenchId: bigint;
+        user?: PublicKey;
+    }): Promise<string>;
+    /** eva distributePrize (ER, admin) — pay the prize pool to `winners` by `amounts` (lamports). */
+    distributePrize(p: {
+        trenchId: bigint;
+        winners: PublicKey[];
+        amounts: bigint[];
+    }): Promise<string>;
 }

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);
         }
@@ -2352,21 +2398,119 @@ export class NorthstarEva {
     }
     get methods() { return this.program.methods; }
     bn(v) { return new A.BN(v.toString()); }
+    // ───────────────────────── instruction builders (build, DON'T send) ─────────────────────────
+    // Same inputs as the matching send-methods, but each RETURNS the unsigned instruction instead
+    // of signing + submitting — so a backend can compose it with its own instructions, sign, and
+    // send however it wants. State reads needed to resolve accounts still happen; only the network
+    // SEND is omitted. Pair with `buildTransaction()` to get a ready-to-sign Transaction.
+    /** Portal OpenSession instruction (L1). */
+    buildOpenSessionIx() {
+        return portal.openSessionIx({
+            programId: this.cfg.portalProgramId, payer: this.payer,
+            gridId: this.cfg.gridId, ttlSlots: this.cfg.ttlSlots, feeCap: this.cfg.feeCap,
+            validator: this.validatorIdentity, settlementIntervalSlots: this.cfg.settlementIntervalSlots,
+        });
+    }
+    /** Portal CloseSession instruction (L1). */
+    buildCloseSessionIx() {
+        return portal.closeSessionIx({ programId: this.cfg.portalProgramId, closer: this.payer });
+    }
+    /** 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.) */
+    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) });
+    }
+    /** Next sequential trench id (= total_trenches + 1) read from the ER global state. */
+    async nextTrenchId() { return (await this.requireGlobal()).totalTrenches + 1n; }
+    /** eva initialize instruction (ER). */
+    buildInitializeIx(p) {
+        return this.methods.initialize(this.bn(p.biddingDuration), this.bn(p.tradingDuration)).accounts({ admin: this.payer }).instruction();
+    }
+    /** eva createTrench instruction (ER). `trenchId` defaults to {@link nextTrenchId}. */
+    async buildCreateTrenchIx(p = {}) {
+        const trenchId = p.trenchId ?? await this.nextTrenchId();
+        const ivtr = p.initialVirtualTokenReserves ?? INITIAL_TOKEN_SUPPLY / 2n;
+        return this.methods.createTrench(this.bn(trenchId), this.bn(ivtr)).accounts({ globalState: this.globalStatePda(), creator: this.payer }).instruction();
+    }
+    /** eva deposit instruction (ER). */
+    buildDepositIx(p) {
+        return this.methods.deposit(this.bn(p.lamports), this.bn(p.thinkId ?? 0n)).accounts({ trench: this.trenchPda(p.trenchId), user: p.user ?? this.payer }).instruction();
+    }
+    /** eva finalize instruction (ER). Reads global for feeRecipient; does NOT wait for the bidding window. */
+    async buildFinalizeIx(p) {
+        const g = await this.requireGlobal();
+        return this.methods.finalize().accounts({ trench: this.trenchPda(p.trenchId), globalState: this.globalStatePda(), feeRecipient: new PublicKey(g.feeRecipient), admin: this.payer }).instruction();
+    }
+    /** ATA-create instruction (ER) for a user's trench token account (idempotent). */
+    buildUserAtaIx(p) {
+        const user = p.user ?? this.payer;
+        return createAssociatedTokenAccountIdempotentInstruction(this.payer, this.userAta(p.trenchId, user), user, this.tokenMintPda(p.trenchId), TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID);
+    }
+    /** eva buy instruction (ER). Reads global for feeRecipient. */
+    async buildBuyIx(p) {
+        const g = await this.requireGlobal();
+        const user = p.user ?? this.payer;
+        return this.methods.buy(this.bn(p.solPayWithFee), this.bn(p.thinkId ?? 0n)).accounts({ trench: this.trenchPda(p.trenchId), globalState: this.globalStatePda(), feeRecipient: new PublicKey(g.feeRecipient), user, trenchTokenVault: this.trenchVault(p.trenchId), userTokenAccount: this.userAta(p.trenchId, user), systemProgram: SystemProgram.programId, tokenProgram: TOKEN_PROGRAM_ID }).instruction();
+    }
+    /** eva sell instruction (ER). Reads global for feeRecipient. */
+    async buildSellIx(p) {
+        const g = await this.requireGlobal();
+        const user = p.user ?? this.payer;
+        return this.methods.sell(this.bn(p.tokenAmount), this.bn(p.minSolOutput ?? 0n), this.bn(p.thinkId ?? 0n)).accounts({ trench: this.trenchPda(p.trenchId), globalState: this.globalStatePda(), feeRecipient: new PublicKey(g.feeRecipient), user, trenchTokenVault: this.trenchVault(p.trenchId), userTokenAccount: this.userAta(p.trenchId, user), tokenProgram: TOKEN_PROGRAM_ID }).instruction();
+    }
+    /** eva updateConfig instruction (ER, admin) — change bidding/trading durations + fee recipient. */
+    buildUpdateConfigIx(p) {
+        return this.methods.updateConfig(this.bn(p.biddingDuration), this.bn(p.tradingDuration), p.feeRecipient).accounts({ globalState: this.globalStatePda(), admin: this.payer }).instruction();
+    }
+    /** eva withdraw instruction (ER) — withdraw a bid deposit from a trench (inverse of {@link buildDepositIx}). NOT the Portal SOL bridge ({@link buildWithdrawFeeFromErIx}). */
+    buildWithdrawIx(p) {
+        const user = p.user ?? this.payer;
+        return this.methods.withdraw(this.bn(p.amount), this.bn(p.thinkId ?? 0n)).accounts({ trench: this.trenchPda(p.trenchId), agent: this.agentPda(p.trenchId, user), user }).instruction();
+    }
+    /** eva closePool instruction (ER, admin) — close a finished trench's pool. */
+    async buildClosePoolIx(p) {
+        const g = await this.requireGlobal();
+        return this.methods.closePool().accounts({ trench: this.trenchPda(p.trenchId), globalState: this.globalStatePda(), feeRecipient: new PublicKey(g.feeRecipient), admin: this.payer }).instruction();
+    }
+    /** eva claimTokens instruction (ER, admin) — release `user`'s tokens from the trench vault to their ATA. */
+    buildClaimTokensIx(p) {
+        const user = p.user ?? this.payer;
+        return this.methods.claimTokens().accounts({ globalState: this.globalStatePda(), trench: this.trenchPda(p.trenchId), agent: this.agentPda(p.trenchId, user), user, admin: this.payer, trenchTokenVault: this.trenchVault(p.trenchId), userTokenAccount: this.userAta(p.trenchId, user), tokenProgram: TOKEN_PROGRAM_ID }).instruction();
+    }
+    /** eva distributePrize instruction (ER, admin) — pay out the prize pool to `winners` by `amounts` (lamports). */
+    async buildDistributePrizeIx(p) {
+        const g = await this.requireGlobal();
+        return this.methods.distributePrize(p.winners, p.amounts.map((a) => this.bn(a))).accounts({ trench: this.trenchPda(p.trenchId), globalState: this.globalStatePda(), feeRecipient: new PublicKey(g.feeRecipient), admin: this.payer }).instruction();
+    }
+    /**
+     * Bundle instruction(s) into an UNSIGNED `Transaction` (feePayer + recent blockhash set) for the
+     * given lane (`"er"` default, or `"l1"`). The backend signs + submits it (or adds more instructions first).
+     */
+    async buildTransaction(instructions, opts = {}) {
+        const conn = opts.lane === "l1" ? this.l1 : this.er;
+        const { blockhash, lastValidBlockHeight } = await conn.getLatestBlockhash(opts.lane === "l1" ? "confirmed" : "processed");
+        const tx = new Transaction({ feePayer: opts.feePayer ?? this.payer, blockhash, lastValidBlockHeight });
+        tx.add(...(Array.isArray(instructions) ? instructions : [instructions]));
+        return tx;
+    }
     // ───────────────────────── Portal control (L1) ─────────────────────────
     async openSession() {
+        this.requireNorthStar("openSession");
         const pda = this.sessionPda();
         if (await this.l1GetAccount(pda))
             return { signature: null, sessionPda: pda, alreadyOpen: true };
-        const ix = portal.openSessionIx({
-            programId: this.cfg.portalProgramId, payer: this.wallet.publicKey,
-            gridId: this.cfg.gridId, ttlSlots: this.cfg.ttlSlots, feeCap: this.cfg.feeCap,
-            validator: this.validatorIdentity, settlementIntervalSlots: this.cfg.settlementIntervalSlots,
-        });
-        const signature = await this.sendOnL1([ix], [this.wallet]);
+        const signature = await this.sendOnL1([this.buildOpenSessionIx()], [this.wallet]);
         return { signature, sessionPda: pda, alreadyOpen: false };
     }
     async closeSession() {
-        return this.sendOnL1([portal.closeSessionIx({ programId: this.cfg.portalProgramId, closer: this.wallet.publicKey })], [this.wallet]);
+        this.requireNorthStar("closeSession");
+        return this.sendOnL1([this.buildCloseSessionIx()], [this.wallet]);
     }
     /**
      * Ensure the Portal session is open (idempotent). Opens it via {@link openSession} only if
@@ -2391,9 +2535,10 @@ 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([portal.depositFeeIx({ programId: this.cfg.portalProgramId, depositor: this.wallet.publicKey, recipient, lamports })], [this.wallet]);
+        return this.sendOnL1([this.buildDepositFeeIx(lamports, recipient)], [this.wallet]);
     }
     /** Ensure the ER fee payer has >= `lamports`; tops up via DepositFee + waits for the credit. */
     async ensureErFunds(lamports, recipient = this.wallet.publicKey) {
@@ -2431,6 +2576,7 @@ export class NorthstarEva {
     tokenMintPda(id) { return evaPdas.tokenMintPda(this.cfg.evaProgramId, this.trenchPda(id)); }
     trenchVault(id) { return evaPdas.trenchTokenVault(this.tokenMintPda(id), this.trenchPda(id)); }
     userAta(id, user = this.wallet.publicKey) { return evaPdas.userTokenAccount(this.tokenMintPda(id), user); }
+    agentPda(id, user = this.wallet.publicKey) { return evaPdas.agentPda(this.cfg.evaProgramId, this.trenchPda(id), user); }
     // ───────────────────────── eva reads (processed by default) ─────────────────────────
     async getGlobal(source = "er") {
         const info = source === "er" ? await this.erGetAccount(this.globalStatePda()) : await this.l1GetAccount(this.globalStatePda());
@@ -2480,23 +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;
-        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(recipient.publicKey);
-        const ix = SystemProgram.transfer({ fromPubkey: recipient.publicKey, toPubkey: sink, lamports: Number(p.lamports) });
-        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) {
@@ -2519,30 +2665,20 @@ export class NorthstarEva {
     async initialize(p) {
         if (await this.getGlobal("er"))
             return null; // already initialized
-        const ix = await this.methods.initialize(this.bn(p.biddingDuration), this.bn(p.tradingDuration))
-            .accounts({ admin: this.wallet.publicKey }).instruction();
-        return this.sendEva(ix, "initialize");
+        return this.sendEva(await this.buildInitializeIx(p), "initialize");
     }
     /** createTrench with the next sequential id (id == total_trenches + 1). */
     async createTrench(p = {}) {
-        const g = await this.getGlobal("er");
-        if (!g)
-            throw new Error("global state not initialized — call initialize() first");
-        const trenchId = g.totalTrenches + 1n;
-        const ivtr = p.initialVirtualTokenReserves ?? INITIAL_TOKEN_SUPPLY / 2n;
-        const ix = await this.methods.createTrench(this.bn(trenchId), this.bn(ivtr))
-            .accounts({ globalState: this.globalStatePda(), creator: this.wallet.publicKey }).instruction();
+        const trenchId = await this.nextTrenchId();
+        const ix = await this.buildCreateTrenchIx({ trenchId, initialVirtualTokenReserves: p.initialVirtualTokenReserves });
         const signature = await this.sendEva(ix, "createTrench");
         return { trenchId, signature };
     }
     async deposit(p) {
-        const ix = await this.methods.deposit(this.bn(p.lamports), this.bn(p.thinkId ?? 0n))
-            .accounts({ trench: this.trenchPda(p.trenchId), user: this.wallet.publicKey }).instruction();
-        return this.sendEva(ix, "deposit");
+        return this.sendEva(await this.buildDepositIx(p), "deposit");
     }
     /** finalize — waits for the ER slot to pass biddingEndBlock, then seeds the AMM. */
     async finalize(p) {
-        const g = await this.requireGlobal();
         const t = await this.getTrench(p.trenchId, "er", 10);
         if (t)
             for (let i = 0; i < 80; i++) {
@@ -2551,28 +2687,38 @@ export class NorthstarEva {
                     break;
                 await sleep(this.pollMs);
             }
-        const ix = await this.methods.finalize()
-            .accounts({ trench: this.trenchPda(p.trenchId), globalState: this.globalStatePda(), feeRecipient: new PublicKey(g.feeRecipient), admin: this.wallet.publicKey }).instruction();
-        return this.sendEva(ix, "finalize");
+        return this.sendEva(await this.buildFinalizeIx(p), "finalize");
     }
     /** Create the user's token ATA on the ER (buy/sell require it to pre-exist). */
     async ensureUserAta(p) {
-        const user = p.user ?? this.wallet.publicKey;
-        const ix = createAssociatedTokenAccountIdempotentInstruction(this.wallet.publicKey, this.userAta(p.trenchId, user), user, this.tokenMintPda(p.trenchId), TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID);
-        return this.sendEva(ix, "ensureUserAta");
+        return this.sendEva(this.buildUserAtaIx(p), "ensureUserAta");
     }
     async buy(p) {
-        const g = await this.requireGlobal();
-        const ix = await this.methods.buy(this.bn(p.solPayWithFee), this.bn(p.thinkId ?? 0n))
-            .accounts({ trench: this.trenchPda(p.trenchId), globalState: this.globalStatePda(), feeRecipient: new PublicKey(g.feeRecipient), user: this.wallet.publicKey, trenchTokenVault: this.trenchVault(p.trenchId), userTokenAccount: this.userAta(p.trenchId), systemProgram: SystemProgram.programId, tokenProgram: TOKEN_PROGRAM_ID }).instruction();
-        const signature = await this.sendEva(ix, "buy");
+        const signature = await this.sendEva(await this.buildBuyIx(p), "buy");
         return { signature, trench: (await this.getTrench(p.trenchId, "er", 5)), userTokens: await this.getUserTokenBalance(p.trenchId) };
     }
     async sell(p) {
-        const g = await this.requireGlobal();
-        const ix = await this.methods.sell(this.bn(p.tokenAmount), this.bn(p.minSolOutput ?? 0n), this.bn(p.thinkId ?? 0n))
-            .accounts({ trench: this.trenchPda(p.trenchId), globalState: this.globalStatePda(), feeRecipient: new PublicKey(g.feeRecipient), user: this.wallet.publicKey, trenchTokenVault: this.trenchVault(p.trenchId), userTokenAccount: this.userAta(p.trenchId), tokenProgram: TOKEN_PROGRAM_ID }).instruction();
-        const signature = await this.sendEva(ix, "sell");
+        const signature = await this.sendEva(await this.buildSellIx(p), "sell");
         return { signature, trench: (await this.getTrench(p.trenchId, "er", 5)), userTokens: await this.getUserTokenBalance(p.trenchId) };
     }
+    /** eva updateConfig (ER, admin) — set bidding/trading durations + fee recipient on the global config. */
+    async updateConfig(p) {
+        return this.sendEva(await this.buildUpdateConfigIx(p), "updateConfig");
+    }
+    /** eva withdraw (ER) — withdraw a bid deposit from a trench (inverse of {@link deposit}; NOT the Portal SOL bridge {@link withdrawFeeFromEr}). */
+    async withdraw(p) {
+        return this.sendEva(await this.buildWithdrawIx(p), "withdraw");
+    }
+    /** eva closePool (ER, admin) — close a finished trench's pool. */
+    async closePool(p) {
+        return this.sendEva(await this.buildClosePoolIx(p), "closePool");
+    }
+    /** eva claimTokens (ER, admin) — release `user`'s tokens from the trench vault to their ATA. */
+    async claimTokens(p) {
+        return this.sendEva(await this.buildClaimTokensIx(p), "claimTokens");
+    }
+    /** eva distributePrize (ER, admin) — pay the prize pool to `winners` by `amounts` (lamports). */
+    async distributePrize(p) {
+        return this.sendEva(await this.buildDistributePrizeIx(p), "distributePrize");
+    }
 }

package/package.json

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