@0block.io/sdk 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,124 @@
+import * as web3 from "@solana/web3.js";
+import type { ZeroBlockContext } from "./context.js";
+/** Anywhere a key is accepted, both base58 strings and PublicKeys work. */
+export type Address = string | web3.PublicKey;
+export type SwapSide = "buy" | "sell";
+/**
+ * Everything chain-derived that a pump.fun swap needs, resolved once
+ * (server-side, close to an RPC) and streamed to clients as plain strings.
+ * The frontend then builds transactions fully offline.
+ */
+export interface PumpfunMarketContext {
+    /** The pump.fun token mint being traded. */
+    mint: string;
+    /** SPL token program owning the mint (classic or Token-2022). */
+    mintTokenProgram: string;
+    pumpfunProgram: string;
+    pumpfunFeeProgram: string;
+    global: string;
+    bondingCurve: string;
+    associatedBondingCurve: string;
+    bondingCurveV2: string;
+    creatorVault: string;
+    /** Current Global.fee_recipient. */
+    feeRecipient: string;
+    /** Non-zero Global.buyback_fee_recipients entries (builder picks one). */
+    buybackFeeRecipients: string[];
+    eventAuthority: string;
+    globalVolumeAccumulator: string;
+    feeConfig: string;
+}
+/** Serializable address-lookup-table contents, streamable over a WS. */
+export interface LookupTableData {
+    key: string;
+    addresses: string[];
+}
+/**
+ * A trading preset as a tenant UI typically models it: slippage %, priority
+ * fee in SOL, bribe (gateway tip) in SOL. `mevMode` is carried through
+ * untouched — it is gateway-side behavior, not transaction content.
+ */
+export interface TradingPreset {
+    /** Max acceptable slippage, percent (e.g. 20 for 20%). */
+    slippagePct: number;
+    /** Total priority fee in SOL (e.g. 0.001). */
+    prioritySol: number;
+    /** Gateway tip ("bribe") in SOL (e.g. 0.001). */
+    bribeSol: number;
+    mevMode?: "off" | "reduced" | "secure";
+}
+export interface TipParams {
+    /** Allowlisted gateway tip account. MUST stay a static message key. */
+    account: Address;
+    lamports: bigint;
+}
+export interface ComputeBudgetParams {
+    /** Total priority fee in SOL, converted to a per-CU price. */
+    prioritySol: number;
+    /** Compute-unit limit the price is spread over. */
+    computeUnitLimit?: number;
+}
+export interface BuildPumpfunSwapParams {
+    /** From createContext(): tenant-wrapped or direct-to-router. */
+    context: ZeroBlockContext;
+    market: PumpfunMarketContext;
+    /** The end user: fee payer, token-account owner, swap authority. */
+    user: Address;
+    side: SwapSide;
+    /** buy: lamports of wSOL in. sell: raw token amount in. */
+    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. */
+    orderId?: bigint;
+    /** A FINALIZED blockhash (gateway forwards to a different staked node). */
+    recentBlockhash: string;
+    /** Shared static-accounts tables (see buildLookupTableAddresses). */
+    lookupTables?: LookupTableData[];
+    /** Gateway tip. Omit only for plain-RPC submission paths. */
+    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.
+     */
+    wrapSol?: boolean;
+    /** sell only: append close-wSOL-ATA so proceeds land as native SOL. Default true on sell. */
+    unwrapWsol?: boolean;
+}
+export interface BuildSwapResult {
+    /** The unsigned v0 transaction. */
+    transaction: web3.VersionedTransaction;
+    /** Exactly what each required signer signs (serialized v0 message). */
+    messageBytes: Uint8Array;
+    /** Signers the message requires, in fee-payer-first order. */
+    requiredSigners: web3.PublicKey[];
+    /** order_id embedded in the swap args (u128). */
+    orderId: bigint;
+    /** Wire size once all signatures are attached; already checked ≤ 1232. */
+    estimatedSize: number;
+}
+/** Decoded router SwapResultEvent, normalized for accounting consumers. */
+export interface DecodedSwapResult {
+    orderId: bigint;
+    status: "success" | "failure";
+    /** Present on success. */
+    commissions?: {
+        feeMint: string;
+        feeSource: "input" | "output";
+        feeBaseAmount: bigint;
+        totalFeeAmount: bigint;
+        items: Array<{
+            kind: "platform" | "tenant";
+            bps: number;
+            amount: bigint;
+            /** Tenant wrapper program id for tenant items; default pubkey for platform. */
+            tenantProgram: string;
+        }>;
+    };
+    /** Present on failure. */
+    failure?: {
+        code: bigint;
+        message: string;
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/venues/pumpfun.d.ts

@@ -0,0 +1,32 @@
+import * as web3 from "@solana/web3.js";
+import type { SwapSide } from "../types.js";
+export interface PumpfunRemainingAccountsParams {
+    dexProgramId: web3.PublicKey;
+    /** The swap authority — the user (signs the transaction). */
+    swapAuthority: web3.PublicKey;
+    swapSourceToken: web3.PublicKey;
+    swapDestinationToken: web3.PublicKey;
+    pumpfunGlobal: web3.PublicKey;
+    pumpfunFeeRecipient: web3.PublicKey;
+    pumpfunMint: web3.PublicKey;
+    pumpfunBondingCurve: web3.PublicKey;
+    pumpfunAssociatedBondingCurve: web3.PublicKey;
+    systemProgramId: web3.PublicKey;
+    tokenProgramId: web3.PublicKey;
+    pumpfunCreatorVault: web3.PublicKey;
+    pumpfunEventAuthority: web3.PublicKey;
+    pumpfunGlobalVolumeAccumulator: web3.PublicKey;
+    pumpfunUserVolumeAccumulator: web3.PublicKey;
+    pumpfunFeeConfig: web3.PublicKey;
+    pumpfunFeeProgram: web3.PublicKey;
+    pumpfunBondingCurveV2: web3.PublicKey;
+    pumpfunBuybackFeeRecipient: web3.PublicKey;
+    /** Classic token program, appended when the mint lives on Token-2022. */
+    extraTokenProgramId?: web3.PublicKey | null;
+}
+/**
+ * Remaining accounts for one pump.fun leg, in the exact order the router's
+ * adapter parses them (PumpfunBuyAccounts / PumpfunSellAccounts). The dex
+ * program id is always index 0 and is hard-checked on-chain.
+ */
+export declare function buildPumpfunRemainingAccounts(side: SwapSide, p: PumpfunRemainingAccountsParams): web3.AccountMeta[];

package/dist/venues/pumpfun.js

@@ -0,0 +1,56 @@
+/**
+ * Remaining accounts for one pump.fun leg, in the exact order the router's
+ * adapter parses them (PumpfunBuyAccounts / PumpfunSellAccounts). The dex
+ * program id is always index 0 and is hard-checked on-chain.
+ */
+export function buildPumpfunRemainingAccounts(side, p) {
+    const metas = [];
+    const push = (pubkey, isWritable, isSigner = false) => metas.push({ pubkey, isWritable, isSigner });
+    if (side === "buy") {
+        push(p.dexProgramId, false);
+        push(p.swapAuthority, false, true);
+        push(p.swapSourceToken, true);
+        push(p.swapDestinationToken, true);
+        push(p.pumpfunGlobal, false);
+        push(p.pumpfunFeeRecipient, true);
+        push(p.pumpfunMint, false);
+        push(p.pumpfunBondingCurve, true);
+        push(p.pumpfunAssociatedBondingCurve, true);
+        push(p.systemProgramId, false);
+        push(p.tokenProgramId, false);
+        push(p.pumpfunCreatorVault, true);
+        push(p.pumpfunEventAuthority, false);
+        push(p.pumpfunGlobalVolumeAccumulator, false);
+        push(p.pumpfunUserVolumeAccumulator, true);
+        push(p.pumpfunFeeConfig, false);
+        push(p.pumpfunFeeProgram, false);
+        push(p.pumpfunBondingCurveV2, false);
+        push(p.pumpfunBuybackFeeRecipient, true);
+        if (p.extraTokenProgramId)
+            push(p.extraTokenProgramId, false);
+        return metas;
+    }
+    if (side === "sell") {
+        push(p.dexProgramId, false);
+        push(p.swapAuthority, false, true);
+        push(p.swapSourceToken, true);
+        push(p.swapDestinationToken, true);
+        push(p.pumpfunGlobal, false);
+        push(p.pumpfunFeeRecipient, true);
+        push(p.pumpfunMint, false);
+        push(p.pumpfunBondingCurve, true);
+        push(p.pumpfunAssociatedBondingCurve, true);
+        push(p.systemProgramId, false);
+        push(p.pumpfunCreatorVault, true);
+        push(p.tokenProgramId, false);
+        push(p.pumpfunEventAuthority, false);
+        push(p.pumpfunFeeConfig, false);
+        push(p.pumpfunFeeProgram, false);
+        push(p.pumpfunBondingCurveV2, false);
+        push(p.pumpfunBuybackFeeRecipient, true);
+        if (p.extraTokenProgramId)
+            push(p.extraTokenProgramId, false);
+        return metas;
+    }
+    throw new Error(`Unsupported pump.fun side: ${side}`);
+}

package/dist/wsol.d.ts

@@ -0,0 +1,30 @@
+import * as web3 from "@solana/web3.js";
+/**
+ * Create an associated token account if it does not exist (ATA program
+ * instruction 1, "CreateIdempotent"). Safe to include on every transaction.
+ */
+export declare function createAtaIdempotentInstruction(params: {
+    payer: web3.PublicKey;
+    owner: web3.PublicKey;
+    mint: web3.PublicKey;
+    tokenProgram?: web3.PublicKey;
+}): web3.TransactionInstruction;
+/** SPL Token "SyncNative" (instruction 17) — refresh a wSOL account balance. */
+export declare function syncNativeInstruction(account: web3.PublicKey): web3.TransactionInstruction;
+/** SPL Token "CloseAccount" (instruction 9) — reclaim lamports (unwrap wSOL). */
+export declare function closeAccountInstruction(params: {
+    account: web3.PublicKey;
+    destination: web3.PublicKey;
+    owner: web3.PublicKey;
+}): web3.TransactionInstruction;
+/**
+ * Fund a user's wSOL ATA from native SOL: create the ATA if missing, transfer
+ * lamports in, then SyncNative so the token balance reflects them. Lets users
+ * buy from plain SOL without ever holding wSOL between trades.
+ */
+export declare function wrapSolInstructions(params: {
+    user: web3.PublicKey;
+    lamports: bigint;
+}): web3.TransactionInstruction[];
+/** Close the user's wSOL ATA back into native SOL (after a sell). */
+export declare function unwrapWsolInstruction(user: web3.PublicKey): web3.TransactionInstruction;

package/dist/wsol.js

@@ -0,0 +1,69 @@
+import * as web3 from "@solana/web3.js";
+import { ASSOCIATED_TOKEN_PROGRAM_ID, TOKEN_PROGRAM_ID, WSOL_MINT, } from "./constants.js";
+import { deriveAta } from "./pda.js";
+/**
+ * Create an associated token account if it does not exist (ATA program
+ * instruction 1, "CreateIdempotent"). Safe to include on every transaction.
+ */
+export function createAtaIdempotentInstruction(params) {
+    const tokenProgram = params.tokenProgram ?? TOKEN_PROGRAM_ID;
+    const ata = deriveAta(params.owner, params.mint, tokenProgram);
+    return new web3.TransactionInstruction({
+        programId: ASSOCIATED_TOKEN_PROGRAM_ID,
+        keys: [
+            { pubkey: params.payer, isSigner: true, isWritable: true },
+            { pubkey: ata, isSigner: false, isWritable: true },
+            { pubkey: params.owner, isSigner: false, isWritable: false },
+            { pubkey: params.mint, isSigner: false, isWritable: false },
+            { pubkey: web3.SystemProgram.programId, isSigner: false, isWritable: false },
+            { pubkey: tokenProgram, isSigner: false, isWritable: false },
+        ],
+        data: Buffer.from([1]),
+    });
+}
+/** SPL Token "SyncNative" (instruction 17) — refresh a wSOL account balance. */
+export function syncNativeInstruction(account) {
+    return new web3.TransactionInstruction({
+        programId: TOKEN_PROGRAM_ID,
+        keys: [{ pubkey: account, isSigner: false, isWritable: true }],
+        data: Buffer.from([17]),
+    });
+}
+/** SPL Token "CloseAccount" (instruction 9) — reclaim lamports (unwrap wSOL). */
+export function closeAccountInstruction(params) {
+    return new web3.TransactionInstruction({
+        programId: TOKEN_PROGRAM_ID,
+        keys: [
+            { pubkey: params.account, isSigner: false, isWritable: true },
+            { pubkey: params.destination, isSigner: false, isWritable: true },
+            { pubkey: params.owner, isSigner: true, isWritable: false },
+        ],
+        data: Buffer.from([9]),
+    });
+}
+/**
+ * Fund a user's wSOL ATA from native SOL: create the ATA if missing, transfer
+ * lamports in, then SyncNative so the token balance reflects them. Lets users
+ * buy from plain SOL without ever holding wSOL between trades.
+ */
+export function wrapSolInstructions(params) {
+    const ata = deriveAta(params.user, WSOL_MINT, TOKEN_PROGRAM_ID);
+    return [
+        createAtaIdempotentInstruction({
+            payer: params.user,
+            owner: params.user,
+            mint: WSOL_MINT,
+        }),
+        web3.SystemProgram.transfer({
+            fromPubkey: params.user,
+            toPubkey: ata,
+            lamports: params.lamports,
+        }),
+        syncNativeInstruction(ata),
+    ];
+}
+/** Close the user's wSOL ATA back into native SOL (after a sell). */
+export function unwrapWsolInstruction(user) {
+    const ata = deriveAta(user, WSOL_MINT, TOKEN_PROGRAM_ID);
+    return closeAccountInstruction({ account: ata, destination: user, owner: user });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "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.",
+  "keywords": [
+    "solana",
+    "dex",
+    "router",
+    "swap",
+    "0block",
+    "transaction-builder",
+    "versioned-transactions",
+    "address-lookup-tables"
+  ],
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node test/smoke.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "@coral-xyz/anchor": "^0.31.1",
+    "@solana/web3.js": "^1.98.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4"
+  }
+}