northstar-eva-sdk 0.5.0 → 0.6.0

package/README.md

@@ -68,7 +68,7 @@ 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.
+Builders (each mirrors the send-method's inputs): `buildOpenSessionIx()`, `buildCloseSessionIx()`, `buildDepositFeeIx(lamports, recipient?)`, `buildWithdrawFeeFromErIx({ lamports, sender?, 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**.
 
@@ -133,7 +133,7 @@ The deposit ("fund fee to ER payer") API now **contains the open-session step**,
 
 > **Backwards compatible:** existing code that calls `openSession()` before depositing still works (the extra `ensureSession` is a no-op when the session already exists). No signatures or return types changed.
 
-The three user-fund APIs: **query balance** → `querySolBalance(account?)` · **deposit** → `fundFeeToErPayer(lamports, recipient?)` · **withdraw** → `withdrawFeeFromEr({ lamports, recipient, toL1? })`.
+The three user-fund APIs: **query balance** → `querySolBalance(account?)` · **deposit** → `fundFeeToErPayer(lamports, recipient?)` · **withdraw** → `withdrawFeeFromEr({ lamports, sender?, toL1? })`.
 
 ## What it is + the fee point
 

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

@@ -335,10 +335,10 @@ export declare class NorthstarEva {
     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.) */
+    /** "Withdraw fee from ER" instruction (ER) — system transfer from `sender` (default: the signer) → its WithdrawalSink. (Portal SOL bridge; distinct from the eva `withdraw` instruction.) */
     buildWithdrawFeeFromErIx(p: {
         lamports: bigint;
-        recipient?: PublicKey;
+        sender?: PublicKey;
         toL1?: PublicKey;
     }): TransactionInstruction;
     /** Next sequential trench id (= total_trenches + 1) read from the ER global state. */
@@ -491,23 +491,23 @@ export declare class NorthstarEva {
      * 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).
+     * `sender` is a **PublicKey** (default: the SDK signer's pubkey). This send-method signs with
+     * the SDK's wallet adapter — so `sender` must be the SDK's own account (the user's wallet, which
+     * signs remotely; no secret key needed). To withdraw for a different account whose signature you
+     * collect elsewhere, use {@link buildWithdrawFeeFromErIx} and have that account sign the tx.
      *
      * 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: {
         lamports: bigint;
-        recipient?: TxSigner;
+        sender?: PublicKey;
         toL1?: PublicKey;
     }): Promise<ErTxResult>;
     /** "Withdraw fee from ER" (the green-box withdraw API) — alias of {@link requestWithdraw}. */
     withdrawFeeFromEr(p: {
         lamports: bigint;
-        recipient?: TxSigner;
+        sender?: PublicKey;
         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

@@ -2419,12 +2419,12 @@ export class NorthstarEva {
     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.) */
+    /** "Withdraw fee from ER" instruction (ER) — system transfer from `sender` (default: the 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) });
+        const sender = p.sender ?? this.payer;
+        if (p.toL1 && !p.toL1.equals(sender))
+            throw new Error("Arbitrary L1 withdrawal destination is not supported yet (Portal pays the sender). Omit `toL1` or set it equal to sender.");
+        return SystemProgram.transfer({ fromPubkey: sender, toPubkey: this.getWithdrawalSink(sender), 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; }
@@ -2630,19 +2630,18 @@ export class NorthstarEva {
      * 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).
+     * `sender` is a **PublicKey** (default: the SDK signer's pubkey). This send-method signs with
+     * the SDK's wallet adapter — so `sender` must be the SDK's own account (the user's wallet, which
+     * signs remotely; no secret key needed). To withdraw for a different account whose signature you
+     * collect elsewhere, use {@link buildWithdrawFeeFromErIx} and have that account sign the tx.
      *
      * 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) {
         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]);
+        const ix = this.buildWithdrawFeeFromErIx({ lamports: p.lamports, sender: p.sender ?? this.payer, toL1: p.toL1 });
+        return this.sendOnEr([ix], [this.wallet]); // signed by the SDK's wallet adapter (the user)
     }
     /** "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.5.0",
+  "version": "0.6.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",