northstar-eva-sdk 0.2.0 → 0.4.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).
 
+## 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.**
+
+- **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;
@@ -301,6 +317,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;
@@ -342,6 +449,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>;
@@ -433,4 +541,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

@@ -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) ─────────────────────────
@@ -2330,21 +2352,117 @@ 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() {
         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]);
+        return this.sendOnL1([this.buildCloseSessionIx()], [this.wallet]);
     }
     /**
      * Ensure the Portal session is open (idempotent). Opens it via {@link openSession} only if
@@ -2371,7 +2489,7 @@ export class NorthstarEva {
     async fundErFeePayer(lamports, recipient = this.wallet.publicKey, opts = {}) {
         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) {
@@ -2409,6 +2527,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());
@@ -2469,11 +2588,7 @@ export class NorthstarEva {
      */
     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) });
+        const ix = this.buildWithdrawFeeFromErIx({ lamports: p.lamports, recipient: recipient.publicKey, toL1: p.toL1 });
         return this.sendOnEr([ix], [recipient]);
     }
     /** "Withdraw fee from ER" (the green-box withdraw API) — alias of {@link requestWithdraw}. */
@@ -2497,30 +2612,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++) {
@@ -2529,28 +2634,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.2.0",
+  "version": "0.4.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",