@0block.io/sdk 0.1.0 → 0.3.0

package/dist/pda.d.ts

@@ -6,6 +6,12 @@ export declare function toPk(address: Address): web3.PublicKey;
 export declare function deriveAta(owner: Address, mint: Address, tokenProgram?: Address): web3.PublicKey;
 /** Tenant wrapper config PDA (seeds: ["tenant_wrapper_config"]). */
 export declare function deriveWrapperConfig(wrapperProgramId: Address): web3.PublicKey;
+/**
+ * Per-order replay-marker PDA (seeds: ["order", payer, order_id LE bytes]).
+ * Its existence is the wrapper's exactly-once gate: a second swap with the
+ * same (payer, order_id) fails at account creation and reverts entirely.
+ */
+export declare function deriveOrderMarker(wrapperProgramId: Address, payer: Address, orderId: bigint): web3.PublicKey;
 /** Router GlobalConfig PDA (seeds: ["config"]). */
 export declare function deriveRouterGlobalConfig(routerProgramId: Address): web3.PublicKey;
 /** Router TenantConfig PDA (seeds: ["tenant", wrapper_program]). */

package/dist/pda.js

@@ -1,5 +1,5 @@
 import * as web3 from "@solana/web3.js";
-import { ASSOCIATED_TOKEN_PROGRAM_ID, SEED_PUMPFUN_BONDING_CURVE, SEED_PUMPFUN_BONDING_CURVE_V2, SEED_PUMPFUN_CREATOR_VAULT, SEED_PUMPFUN_EVENT_AUTHORITY, SEED_PUMPFUN_FEE_CONFIG, SEED_PUMPFUN_GLOBAL, SEED_PUMPFUN_GLOBAL_VOLUME, SEED_PUMPFUN_USER_VOLUME, SEED_ROUTER_GLOBAL_CONFIG, SEED_ROUTER_TENANT, SEED_WRAPPER_CONFIG, TOKEN_PROGRAM_ID, } from "./constants.js";
+import { ASSOCIATED_TOKEN_PROGRAM_ID, SEED_ORDER_MARKER, SEED_PUMPFUN_BONDING_CURVE, SEED_PUMPFUN_BONDING_CURVE_V2, SEED_PUMPFUN_CREATOR_VAULT, SEED_PUMPFUN_EVENT_AUTHORITY, SEED_PUMPFUN_FEE_CONFIG, SEED_PUMPFUN_GLOBAL, SEED_PUMPFUN_GLOBAL_VOLUME, SEED_PUMPFUN_USER_VOLUME, SEED_ROUTER_GLOBAL_CONFIG, SEED_ROUTER_TENANT, SEED_WRAPPER_CONFIG, TOKEN_PROGRAM_ID, } from "./constants.js";
 /** Normalize an Address (base58 string or PublicKey) to a PublicKey. */
 export function toPk(address) {
     return typeof address === "string" ? new web3.PublicKey(address) : address;
@@ -15,6 +15,23 @@ export function deriveAta(owner, mint, tokenProgram = TOKEN_PROGRAM_ID) {
 export function deriveWrapperConfig(wrapperProgramId) {
     return pda([SEED_WRAPPER_CONFIG], toPk(wrapperProgramId));
 }
+/**
+ * Per-order replay-marker PDA (seeds: ["order", payer, order_id LE bytes]).
+ * Its existence is the wrapper's exactly-once gate: a second swap with the
+ * same (payer, order_id) fails at account creation and reverts entirely.
+ */
+export function deriveOrderMarker(wrapperProgramId, payer, orderId) {
+    if (orderId <= 0n || orderId >= 1n << 128n) {
+        throw new Error("orderId must be a non-zero u128");
+    }
+    const le = new Uint8Array(16);
+    let n = orderId;
+    for (let i = 0; i < 16; i++) {
+        le[i] = Number(n & 0xffn);
+        n >>= 8n;
+    }
+    return pda([SEED_ORDER_MARKER, toPk(payer).toBytes(), le], toPk(wrapperProgramId));
+}
 /** Router GlobalConfig PDA (seeds: ["config"]). */
 export function deriveRouterGlobalConfig(routerProgramId) {
     return pda([SEED_ROUTER_GLOBAL_CONFIG], toPk(routerProgramId));

package/dist/swap.js

@@ -6,7 +6,7 @@ const { BN, BorshInstructionCoder } = anchor;
 import { ASSOCIATED_TOKEN_PROGRAM_ID, FEE_MINT_ALLOWLIST, INSTRUCTIONS_SYSVAR_ID, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID, WSOL_MINT, } from "./constants.js";
 import { TENANT_WRAPPER_IDL } from "./idl/tenantWrapper.js";
 import { ROUTER_IDL } from "./idl/router.js";
-import { deriveAta, derivePumpfunUserVolumeAccumulator, deriveRouterGlobalConfig, deriveRouterTenantConfig, deriveWrapperConfig, toPk, } from "./pda.js";
+import { deriveAta, deriveOrderMarker, derivePumpfunUserVolumeAccumulator, deriveRouterGlobalConfig, deriveRouterTenantConfig, deriveWrapperConfig, toPk, } from "./pda.js";
 import { buildPumpfunRemainingAccounts } from "./venues/pumpfun.js";
 // One coder per program for the package lifetime; layouts derive from the
 // vendored IDLs. NOTE: the raw (non-camelCased) IDLs are used, so encode()
@@ -53,6 +53,15 @@ export function buildPumpfunSwapInstruction(params) {
         throw new Error("amountIn must be > 0");
     if (params.minReturn <= 0n)
         throw new Error("minReturn must be > 0");
+    if (context.mode === "tenant" && params.orderId === undefined) {
+        // The wrapper's order-marker replay gate makes order_id part of the dedup
+        // key, and its contract requires SERVER-AUTHORITATIVE ids — a random
+        // client-side default would silently break exactly-once semantics.
+        throw new Error("tenant mode requires an explicit orderId (server-authoritative, non-zero u128)");
+    }
+    if (params.orderId !== undefined && params.orderId === 0n) {
+        throw new Error("orderId must be non-zero");
+    }
     const routerProgramId = context.routerProgramId;
     const zeroblockFeeVault = context.zeroblockFeeVault;
     const pumpMint = toPk(market.mint);
@@ -76,12 +85,18 @@ export function buildPumpfunSwapInstruction(params) {
     const orderId = params.orderId ?? randomOrderId();
     const dexVariant = side === "buy" ? { PumpfunBuy: {} } : { PumpfunSell: {} };
     const amountIn = bnFromBigint(params.amountIn, "amountIn", 64);
+    const minReturn = bnFromBigint(params.minReturn, "minReturn", 64);
     const swapArgs = {
         amount_in: amountIn,
-        min_return: bnFromBigint(params.minReturn, "minReturn", 64),
+        min_return: minReturn,
         amounts: [amountIn],
         routes: [[{ dexes: [dexVariant], weights: Buffer.from([100]) }]],
-        options: null,
+        // H2 (fail-closed slippage): the router REQUIRES an explicit downside
+        // bound via options.slippage and rejects a zero effective bound; the bare
+        // min_return field alone is not trusted. MinOut carries our computed bound.
+        // NOTE (M1): for sells the fee is skimmed from the wSOL output, and the
+        // bound is enforced on the user's NET receipt — quote accordingly.
+        options: { slippage: { MinOut: [minReturn] } },
     };
     // Random pick among the non-zero buyback recipients — the program validates
     // membership on-chain, and ops pre-load all eight into the shared ALT.
@@ -134,6 +149,13 @@ export function buildPumpfunSwapInstruction(params) {
         fixedKeys = [
             { pubkey: user, isWritable: true, isSigner: true },
             { pubkey: deriveWrapperConfig(wrapperProgramId), isWritable: false, isSigner: false },
+            // Exactly-once replay gate: init'd by the wrapper; a duplicate
+            // (payer, order_id) fails at create_account and reverts the swap.
+            {
+                pubkey: deriveOrderMarker(wrapperProgramId, user, orderId),
+                isWritable: true,
+                isSigner: false,
+            },
             { pubkey: routerProgramId, isWritable: false, isSigner: false },
             { pubkey: sourceTokenAccount, isWritable: true, isSigner: false },
             { pubkey: destinationTokenAccount, isWritable: true, isSigner: false },

package/dist/transaction.d.ts

@@ -17,3 +17,34 @@ export declare function buildPumpfunSwapTransaction(params: BuildPumpfunSwapPara
  * requiredSigners order and return the wire-ready bytes.
  */
 export declare function serializeWithSignatures(result: BuildSwapResult, signatures: Uint8Array[]): Uint8Array;
+/**
+ * A submit template for a signer-and-submitter that is CHAIN-AGNOSTIC (e.g.
+ * sigcore): it signs `payload` and splices the raw signature into
+ * `wireTemplate` at `signatureOffset`, then broadcasts the result — with no
+ * knowledge of Solana's transaction format.
+ *
+ * The layout works because a Solana v0 transaction is
+ * `[compact-u16 sig count][sig0..sigN-1][message]`, and the bytes that get
+ * signed are exactly the `[message]` tail. `wireTemplate` is that full
+ * structure with the signature region zeroed; splicing the 64-byte signature
+ * over the zeros yields bytes identical to `serializeWithSignatures`.
+ *
+ * Single-signer only (the RAX flow): exactly one signature at a fixed offset.
+ */
+export interface SubmitTemplate {
+    /** The bytes the signer must sign (the transaction message). Hex-encoded. */
+    payloadHex: string;
+    /** Full wire transaction with the signature zeroed. Base64-encoded. */
+    wireTemplateBase64: string;
+    /** Byte offset in the template where the 64-byte signature is spliced in. */
+    signatureOffset: number;
+    /** Signature length in bytes (64 for ed25519). */
+    signatureLength: number;
+    /** The single required signer's base58 address (the user). */
+    signer: string;
+}
+/**
+ * Emit a chain-agnostic {@link SubmitTemplate} from a built single-signer
+ * transaction. The offset is derived from the wire layout, not assumed.
+ */
+export declare function buildSubmitTemplate(result: BuildSwapResult): SubmitTemplate;

package/dist/transaction.js

@@ -4,7 +4,7 @@ import { toPk } from "./pda.js";
 import { buildComputeBudgetInstructions } from "./computeBudget.js";
 import { buildPumpfunSwapInstruction } from "./swap.js";
 import { buildTipInstruction, maskTipAccountInTables } from "./tip.js";
-import { unwrapWsolInstruction, createAtaIdempotentInstruction, wrapSolInstructions } from "./wsol.js";
+import { closeAccountInstruction, createAtaIdempotentInstruction, unwrapWsolInstruction, wrapSolInstructions, } from "./wsol.js";
 /** Rehydrate a streamed lookup table into web3.js form (compile-time only fields defaulted). */
 export function toLookupTableAccount(data) {
     return new web3.AddressLookupTableAccount({
@@ -45,26 +45,59 @@ export function buildPumpfunSwapTransaction(params) {
     if (params.computeBudget) {
         instructions.push(...buildComputeBudgetInstructions(params.computeBudget));
     }
-    if (params.side === "buy") {
-        // Trade from native SOL (default): fund the wSOL ATA in-transaction, and
-        // make sure the destination token ATA exists for first-time buyers.
-        if (params.wrapSol ?? true) {
-            instructions.push(...wrapSolInstructions({ user, lamports: params.amountIn }));
+    // TENANT MODE: the wrapper program manages the entire native-SOL lifecycle
+    // on-chain (ATA creation, wrap sized with exact on-chain fee headroom,
+    // post-swap sweep, proceeds unwrap, emptied-ATA cleanup) — the client adds
+    // NO wSOL/ATA instructions. DIRECT MODE: the router does none of that, so
+    // the client composes it here.
+    const clientManagesWsol = params.context.mode === "direct";
+    if (clientManagesWsol) {
+        if (params.side === "buy") {
+            if (params.wrapSol ?? true) {
+                // The router's input-side fee transfer draws from this same account
+                // AFTER the swap consumes amountIn — wrap fee headroom on top (ceil),
+                // or the fee transfer fails with insufficient funds.
+                const feeBps = BigInt(params.totalFeeBps ?? 0);
+                const feeHeadroom = (params.amountIn * feeBps + 9999n) / 10000n;
+                instructions.push(...wrapSolInstructions({ user, lamports: params.amountIn + feeHeadroom }));
+            }
+            instructions.push(createAtaIdempotentInstruction({
+                payer: user,
+                owner: user,
+                mint: toPk(params.market.mint),
+                tokenProgram: toPk(params.market.mintTokenProgram),
+            }));
+        }
+        else {
+            // Selling into wSOL: the wSOL ATA may not exist between trades.
+            instructions.push(createAtaIdempotentInstruction({ payer: user, owner: user, mint: toPk("So11111111111111111111111111111111111111112") }));
         }
-        instructions.push(createAtaIdempotentInstruction({
-            payer: user,
-            owner: user,
-            mint: toPk(params.market.mint),
-            tokenProgram: toPk(params.market.mintTokenProgram),
-        }));
-    }
-    else {
-        // Selling into wSOL: the wSOL ATA may not exist between trades.
-        instructions.push(createAtaIdempotentInstruction({ payer: user, owner: user, mint: toPk("So11111111111111111111111111111111111111112") }));
     }
     instructions.push(swap.instruction);
-    if (params.side === "sell" && (params.unwrapWsol ?? true)) {
-        instructions.push(unwrapWsolInstruction(user));
+    if (clientManagesWsol) {
+        if (params.side === "buy" && (params.wrapSol ?? true)) {
+            // Sweep the wSOL account after the swap: returns unused fee headroom and
+            // the ATA rent as native SOL (closing a native account pays out ALL its
+            // lamports — that IS the unwrap).
+            instructions.push(closeAccountInstruction({
+                account: swap.sourceTokenAccount,
+                destination: user,
+                owner: user,
+            }));
+        }
+        if (params.side === "sell" && params.closeTokenAccount) {
+            // Full-balance sell: reclaim the empty token ATA's rent for the user.
+            // CloseAccount requires balance == 0, so a partial sell with this flag
+            // reverts the entire transaction (deliberate fail-loud behavior).
+            instructions.push(closeAccountInstruction({
+                account: swap.sourceTokenAccount,
+                destination: user,
+                owner: user,
+            }));
+        }
+        if (params.side === "sell" && (params.unwrapWsol ?? true)) {
+            instructions.push(unwrapWsolInstruction(user));
+        }
     }
     let tables = (params.lookupTables ?? []).map(toLookupTableAccount);
     if (params.tip) {
@@ -104,3 +137,55 @@ export function serializeWithSignatures(result, signatures) {
     }
     return result.transaction.serialize();
 }
+/** compact-u16 (shortvec) encoded length — how Solana prefixes the sig array. */
+function compactU16Length(n) {
+    if (n < 0x80)
+        return 1;
+    if (n < 0x4000)
+        return 2;
+    return 3;
+}
+/**
+ * Emit a chain-agnostic {@link SubmitTemplate} from a built single-signer
+ * transaction. The offset is derived from the wire layout, not assumed.
+ */
+export function buildSubmitTemplate(result) {
+    const header = result.transaction.message.header;
+    if (header.numRequiredSignatures !== 1) {
+        throw new Error(`submit template supports a single signer; got ${header.numRequiredSignatures}`);
+    }
+    const SIG_LEN = 64;
+    // Zeroed-signature serialization IS the template (web3.js fills missing
+    // signatures with 64 zero bytes), so no manual zeroing is needed.
+    const wireTemplate = result.transaction.serialize();
+    const signatureOffset = compactU16Length(1); // count prefix precedes sig 0
+    // Invariant: the payload (message) is the tail after [count][signature].
+    const messageStart = signatureOffset + SIG_LEN;
+    const templateTail = wireTemplate.slice(messageStart);
+    if (templateTail.length !== result.messageBytes.length ||
+        !templateTail.every((b, i) => b === result.messageBytes[i])) {
+        throw new Error("submit template layout mismatch — message tail differs");
+    }
+    return {
+        payloadHex: bytesToHex(result.messageBytes),
+        wireTemplateBase64: toBase64(wireTemplate),
+        signatureOffset,
+        signatureLength: SIG_LEN,
+        signer: result.requiredSigners[0].toBase58(),
+    };
+}
+function bytesToHex(bytes) {
+    let hex = "";
+    for (const b of bytes)
+        hex += b.toString(16).padStart(2, "0");
+    return hex;
+}
+function toBase64(bytes) {
+    // Buffer in Node; btoa fallback in the browser.
+    if (typeof Buffer !== "undefined")
+        return Buffer.from(bytes).toString("base64");
+    let binary = "";
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary);
+}

package/dist/types.d.ts

@@ -69,7 +69,13 @@ export interface BuildPumpfunSwapParams {
     amountIn: bigint;
     /** Minimum acceptable output (quote minus slippage), raw units. */
     minReturn: bigint;
-    /** Correlates the on-chain SwapResultEvent with an off-chain order. Random when omitted. */
+    /**
+     * Business order id (non-zero u128), echoed in SwapResultEvent.
+     * TENANT MODE: REQUIRED and server-authoritative — it keys the wrapper's
+     * per-(payer, order_id) replay marker, so all retries/variants of one
+     * business order MUST reuse the same id (mint it on your backend).
+     * DIRECT MODE: optional; random when omitted (no replay marker).
+     */
     orderId?: bigint;
     /** A FINALIZED blockhash (gateway forwards to a different staked node). */
     recentBlockhash: string;
@@ -79,12 +85,25 @@ export interface BuildPumpfunSwapParams {
     tip?: TipParams | null;
     computeBudget?: ComputeBudgetParams | null;
     /**
-     * buy only: prepend create-wSOL-ATA (idempotent) + transfer + syncNative so
-     * the user trades from native SOL without holding wSOL. Default true on buy.
+     * direct buy only: prepend create-wSOL-ATA (idempotent) + transfer +
+     * syncNative so the user trades from native SOL. Default true.
      */
     wrapSol?: boolean;
-    /** sell only: append close-wSOL-ATA so proceeds land as native SOL. Default true on sell. */
+    /**
+     * direct buy only: total commission bps (0Block fee) used to size the wSOL
+     * wrap — the router collects input-side fees FROM the source wSOL account
+     * AFTER the swap consumes amountIn. Excess is swept back by the post-swap
+     * close. Default 0 (no headroom).
+     */
+    totalFeeBps?: number;
+    /** direct sell only: close the wSOL ATA so proceeds land as native SOL. Default true. */
     unwrapWsol?: boolean;
+    /**
+     * direct sell only: close the (now empty) token ATA after the swap,
+     * refunding its rent to the user. ONLY set when selling the ENTIRE balance
+     * — any remainder reverts the whole transaction. Default false.
+     */
+    closeTokenAccount?: boolean;
 }
 export interface BuildSwapResult {
     /** The unsigned v0 transaction. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@0block.io/sdk",
-  "version": "0.1.0",
-  "description": "Client-side transaction builder for the 0Block DEX router. Builds unsigned v0 swap transactions entirely offline — tenant-wrapped or direct — with shared address lookup tables, gateway tips, and on-chain fee-event decoding for accounting.",
+  "version": "0.3.0",
+  "description": "Client-side transaction builder for the 0Block DEX router. Builds unsigned v0 swap transactions entirely offline \u2014 tenant-wrapped or direct \u2014 with shared address lookup tables, gateway tips, and on-chain fee-event decoding for accounting.",
   "keywords": [
     "solana",
     "dex",
@@ -44,4 +44,4 @@
   "devDependencies": {
     "typescript": "^5.5.4"
   }
-}
+}