@0block.io/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export * from "./constants.js";
+export * from "./types.js";
+export { createContext, type CreateContextParams, type TenantInit, type ZeroBlockContext, } from "./context.js";
+export { toPk, deriveAta, deriveWrapperConfig, deriveRouterGlobalConfig, deriveRouterTenantConfig, derivePumpfunGlobal, derivePumpfunBondingCurve, derivePumpfunBondingCurveV2, derivePumpfunEventAuthority, derivePumpfunCreatorVault, derivePumpfunGlobalVolumeAccumulator, derivePumpfunUserVolumeAccumulator, derivePumpfunFeeConfig, } from "./pda.js";
+export { type AccountFetcher, connectionFetcher, resolveTokenProgram, resolvePumpfunMarketContext, fetchPumpfunGlobalFeeRecipient, fetchPumpfunBondingCurveCreator, fetchPumpfunBuybackFeeRecipients, } from "./fetch.js";
+export { buildPumpfunRemainingAccounts, type PumpfunRemainingAccountsParams, } from "./venues/pumpfun.js";
+export { buildPumpfunSwapInstruction, decodeSwapData, randomOrderId, resolveFeeMint, type SwapInstructionResult, } from "./swap.js";
+export { buildTipInstruction, maskTipAccountInTables } from "./tip.js";
+export { buildComputeBudgetInstructions } from "./computeBudget.js";
+export { createAtaIdempotentInstruction, syncNativeInstruction, closeAccountInstruction, wrapSolInstructions, unwrapWsolInstruction, } from "./wsol.js";
+export { buildPumpfunSwapTransaction, serializeWithSignatures, toLookupTableAccount, } from "./transaction.js";
+export { buildLookupTableAddresses, buildInitLookupTableInstructions, type InitLookupTableResult, } from "./alt.js";
+export { applyPreset, slippagePctToBps, solToLamports, type PresetSwapInputs, type PresetSwapOutputs, } from "./presets.js";
+export { decodeSwapResultEvents } from "./events.js";
+export { TENANT_WRAPPER_IDL } from "./idl/tenantWrapper.js";
+export { ROUTER_IDL } from "./idl/router.js";

package/dist/index.js

@@ -0,0 +1,27 @@
+// @0block/sdk — browser-first transaction builder for the 0Block DEX router.
+//
+// Initialize with createContext(): pass a tenant (wrapper program + fee vault)
+// to route through that tenant's wrapper, or nothing to invoke the 0Block
+// router directly with 0Block fee accounts.
+//
+// Split of responsibilities:
+//   server-side (near an RPC):  resolvePumpfunMarketContext, buildLookupTableAddresses,
+//                               buildInitLookupTableInstructions
+//   client-side (fully offline): createContext, applyPreset, buildPumpfunSwapTransaction
+//   indexer-side:                decodeSwapResultEvents
+export * from "./constants.js";
+export * from "./types.js";
+export { createContext, } from "./context.js";
+export { toPk, deriveAta, deriveWrapperConfig, deriveRouterGlobalConfig, deriveRouterTenantConfig, derivePumpfunGlobal, derivePumpfunBondingCurve, derivePumpfunBondingCurveV2, derivePumpfunEventAuthority, derivePumpfunCreatorVault, derivePumpfunGlobalVolumeAccumulator, derivePumpfunUserVolumeAccumulator, derivePumpfunFeeConfig, } from "./pda.js";
+export { connectionFetcher, resolveTokenProgram, resolvePumpfunMarketContext, fetchPumpfunGlobalFeeRecipient, fetchPumpfunBondingCurveCreator, fetchPumpfunBuybackFeeRecipients, } from "./fetch.js";
+export { buildPumpfunRemainingAccounts, } from "./venues/pumpfun.js";
+export { buildPumpfunSwapInstruction, decodeSwapData, randomOrderId, resolveFeeMint, } from "./swap.js";
+export { buildTipInstruction, maskTipAccountInTables } from "./tip.js";
+export { buildComputeBudgetInstructions } from "./computeBudget.js";
+export { createAtaIdempotentInstruction, syncNativeInstruction, closeAccountInstruction, wrapSolInstructions, unwrapWsolInstruction, } from "./wsol.js";
+export { buildPumpfunSwapTransaction, serializeWithSignatures, toLookupTableAccount, } from "./transaction.js";
+export { buildLookupTableAddresses, buildInitLookupTableInstructions, } from "./alt.js";
+export { applyPreset, slippagePctToBps, solToLamports, } from "./presets.js";
+export { decodeSwapResultEvents } from "./events.js";
+export { TENANT_WRAPPER_IDL } from "./idl/tenantWrapper.js";
+export { ROUTER_IDL } from "./idl/router.js";

package/dist/pda.d.ts

@@ -0,0 +1,21 @@
+import * as web3 from "@solana/web3.js";
+import type { Address } from "./types.js";
+/** Normalize an Address (base58 string or PublicKey) to a PublicKey. */
+export declare function toPk(address: Address): web3.PublicKey;
+/** SPL associated token account for (owner, mint) under the given token program. */
+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;
+/** Router GlobalConfig PDA (seeds: ["config"]). */
+export declare function deriveRouterGlobalConfig(routerProgramId: Address): web3.PublicKey;
+/** Router TenantConfig PDA (seeds: ["tenant", wrapper_program]). */
+export declare function deriveRouterTenantConfig(routerProgramId: Address, wrapperProgramId: Address): web3.PublicKey;
+export declare function derivePumpfunGlobal(programId: Address): web3.PublicKey;
+export declare function derivePumpfunBondingCurve(programId: Address, mint: Address): web3.PublicKey;
+export declare function derivePumpfunBondingCurveV2(programId: Address, mint: Address): web3.PublicKey;
+export declare function derivePumpfunEventAuthority(programId: Address): web3.PublicKey;
+export declare function derivePumpfunCreatorVault(programId: Address, creator: Address): web3.PublicKey;
+export declare function derivePumpfunGlobalVolumeAccumulator(programId: Address): web3.PublicKey;
+/** Per-user volume accumulator — the one pump.fun PDA derived at build time. */
+export declare function derivePumpfunUserVolumeAccumulator(programId: Address, user: Address): web3.PublicKey;
+export declare function derivePumpfunFeeConfig(feeProgramId: Address, pumpProgramId: Address): web3.PublicKey;

package/dist/pda.js

@@ -0,0 +1,53 @@
+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";
+/** Normalize an Address (base58 string or PublicKey) to a PublicKey. */
+export function toPk(address) {
+    return typeof address === "string" ? new web3.PublicKey(address) : address;
+}
+function pda(seeds, programId) {
+    return web3.PublicKey.findProgramAddressSync(seeds, programId)[0];
+}
+/** SPL associated token account for (owner, mint) under the given token program. */
+export function deriveAta(owner, mint, tokenProgram = TOKEN_PROGRAM_ID) {
+    return pda([toPk(owner).toBytes(), toPk(tokenProgram).toBytes(), toPk(mint).toBytes()], ASSOCIATED_TOKEN_PROGRAM_ID);
+}
+/** Tenant wrapper config PDA (seeds: ["tenant_wrapper_config"]). */
+export function deriveWrapperConfig(wrapperProgramId) {
+    return pda([SEED_WRAPPER_CONFIG], toPk(wrapperProgramId));
+}
+/** Router GlobalConfig PDA (seeds: ["config"]). */
+export function deriveRouterGlobalConfig(routerProgramId) {
+    return pda([SEED_ROUTER_GLOBAL_CONFIG], toPk(routerProgramId));
+}
+/** Router TenantConfig PDA (seeds: ["tenant", wrapper_program]). */
+export function deriveRouterTenantConfig(routerProgramId, wrapperProgramId) {
+    return pda([SEED_ROUTER_TENANT, toPk(wrapperProgramId).toBytes()], toPk(routerProgramId));
+}
+// ---------------------------------------------------------------------------
+// pump.fun PDAs
+// ---------------------------------------------------------------------------
+export function derivePumpfunGlobal(programId) {
+    return pda([SEED_PUMPFUN_GLOBAL], toPk(programId));
+}
+export function derivePumpfunBondingCurve(programId, mint) {
+    return pda([SEED_PUMPFUN_BONDING_CURVE, toPk(mint).toBytes()], toPk(programId));
+}
+export function derivePumpfunBondingCurveV2(programId, mint) {
+    return pda([SEED_PUMPFUN_BONDING_CURVE_V2, toPk(mint).toBytes()], toPk(programId));
+}
+export function derivePumpfunEventAuthority(programId) {
+    return pda([SEED_PUMPFUN_EVENT_AUTHORITY], toPk(programId));
+}
+export function derivePumpfunCreatorVault(programId, creator) {
+    return pda([SEED_PUMPFUN_CREATOR_VAULT, toPk(creator).toBytes()], toPk(programId));
+}
+export function derivePumpfunGlobalVolumeAccumulator(programId) {
+    return pda([SEED_PUMPFUN_GLOBAL_VOLUME], toPk(programId));
+}
+/** Per-user volume accumulator — the one pump.fun PDA derived at build time. */
+export function derivePumpfunUserVolumeAccumulator(programId, user) {
+    return pda([SEED_PUMPFUN_USER_VOLUME, toPk(user).toBytes()], toPk(programId));
+}
+export function derivePumpfunFeeConfig(feeProgramId, pumpProgramId) {
+    return pda([SEED_PUMPFUN_FEE_CONFIG, toPk(pumpProgramId).toBytes()], toPk(feeProgramId));
+}

package/dist/presets.d.ts

@@ -0,0 +1,23 @@
+import type { Address, ComputeBudgetParams, TipParams, TradingPreset } from "./types.js";
+export interface PresetSwapInputs {
+    /** Quoted expected output for the trade, raw units. */
+    expectedOut: bigint;
+    /** Allowlisted gateway tip account (from tenant/gateway config). */
+    tipAccount: Address;
+    computeUnitLimit?: number;
+}
+export interface PresetSwapOutputs {
+    /** expectedOut reduced by the preset's slippage tolerance. */
+    minReturn: bigint;
+    tip: TipParams | null;
+    computeBudget: ComputeBudgetParams | null;
+}
+/** Percent (UI) → basis points, clamped to [0, 10000]. */
+export declare function slippagePctToBps(slippagePct: number): number;
+export declare function solToLamports(sol: number): bigint;
+/**
+ * Map a UI trading preset (Slippage %, Priority SOL, Bribe SOL) onto concrete
+ * build parameters. `mevMode` is intentionally not consumed here — it selects
+ * gateway-side submission behavior, not transaction content.
+ */
+export declare function applyPreset(preset: TradingPreset, inputs: PresetSwapInputs): PresetSwapOutputs;

package/dist/presets.js

@@ -0,0 +1,36 @@
+import { DEFAULT_COMPUTE_UNIT_LIMIT } from "./constants.js";
+/** Percent (UI) → basis points, clamped to [0, 10000]. */
+export function slippagePctToBps(slippagePct) {
+    if (!(slippagePct >= 0) || slippagePct > 100) {
+        throw new Error("slippagePct must be within [0, 100]");
+    }
+    return Math.min(10_000, Math.round(slippagePct * 100));
+}
+export function solToLamports(sol) {
+    if (!(sol >= 0))
+        throw new Error("SOL amount must be >= 0");
+    return BigInt(Math.round(sol * 1e9));
+}
+/**
+ * Map a UI trading preset (Slippage %, Priority SOL, Bribe SOL) onto concrete
+ * build parameters. `mevMode` is intentionally not consumed here — it selects
+ * gateway-side submission behavior, not transaction content.
+ */
+export function applyPreset(preset, inputs) {
+    const bps = slippagePctToBps(preset.slippagePct);
+    const minReturn = (inputs.expectedOut * BigInt(10_000 - bps)) / 10000n;
+    if (minReturn <= 0n) {
+        throw new Error("minReturn collapsed to 0 — expectedOut too small for this slippage");
+    }
+    const tipLamports = solToLamports(preset.bribeSol);
+    return {
+        minReturn,
+        tip: tipLamports > 0n ? { account: inputs.tipAccount, lamports: tipLamports } : null,
+        computeBudget: preset.prioritySol > 0
+            ? {
+                prioritySol: preset.prioritySol,
+                computeUnitLimit: inputs.computeUnitLimit ?? DEFAULT_COMPUTE_UNIT_LIMIT,
+            }
+            : null,
+    };
+}

package/dist/swap.d.ts

@@ -0,0 +1,46 @@
+import * as web3 from "@solana/web3.js";
+import type { ZeroBlockContext } from "./context.js";
+import type { PumpfunMarketContext, SwapSide } from "./types.js";
+/** Random u128 order id (correlates SwapResultEvent with an off-chain order). */
+export declare function randomOrderId(): bigint;
+/**
+ * The mint the router charges fees in: source if allowlisted, else
+ * destination. Mirrors the on-chain fee-base rule (input vs output).
+ */
+export declare function resolveFeeMint(sourceMint: web3.PublicKey, destinationMint: web3.PublicKey): web3.PublicKey;
+export interface SwapInstructionResult {
+    instruction: web3.TransactionInstruction;
+    orderId: bigint;
+    /** User source/destination token accounts, for wrap/unwrap composition. */
+    sourceTokenAccount: web3.PublicKey;
+    destinationTokenAccount: web3.PublicKey;
+}
+/**
+ * Build the swap instruction for a single-hop pump.fun leg — through the
+ * tenant's wrapper program (tenant context) or directly against the 0Block
+ * router (direct context). Pure and synchronous: all chain-derived inputs
+ * arrive via the market context; the only PDAs derived here depend on the
+ * user key.
+ */
+export declare function buildPumpfunSwapInstruction(params: {
+    context: ZeroBlockContext;
+    market: PumpfunMarketContext;
+    user: web3.PublicKey;
+    side: SwapSide;
+    amountIn: bigint;
+    minReturn: bigint;
+    orderId?: bigint;
+}): SwapInstructionResult;
+/**
+ * Decode a swap instruction's data. Both programs share the `swap`
+ * discriminator (anchor hashes the instruction name), and the wrapper layout
+ * is a strict prefix of the router's (which appends `tenant_fee_bps:
+ * Option<u16>`) — so the router coder is tried FIRST: it fails on wrapper
+ * data (missing trailing option byte), while the wrapper coder would
+ * silently mis-decode router data by ignoring the tail.
+ */
+export declare function decodeSwapData(data: Uint8Array): {
+    program: "tenant-wrapper" | "router";
+    name: string;
+    data: unknown;
+};

package/dist/swap.js

@@ -0,0 +1,230 @@
+import * as web3 from "@solana/web3.js";
+// Anchor ships CJS-only; a default import + destructure works everywhere
+// (bundlers and raw Node ESM), named imports do not.
+import anchor from "@coral-xyz/anchor";
+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 { 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()
+// takes snake_case argument keys and PascalCase enum variants — verified
+// against anchor 0.31.
+const wrapperCoder = new BorshInstructionCoder(TENANT_WRAPPER_IDL);
+const routerCoder = new BorshInstructionCoder(ROUTER_IDL);
+/** Random u128 order id (correlates SwapResultEvent with an off-chain order). */
+export function randomOrderId() {
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    let n = 0n;
+    for (const b of bytes)
+        n = (n << 8n) | BigInt(b);
+    return n;
+}
+/**
+ * The mint the router charges fees in: source if allowlisted, else
+ * destination. Mirrors the on-chain fee-base rule (input vs output).
+ */
+export function resolveFeeMint(sourceMint, destinationMint) {
+    if (FEE_MINT_ALLOWLIST.includes(sourceMint.toBase58()))
+        return sourceMint;
+    if (FEE_MINT_ALLOWLIST.includes(destinationMint.toBase58()))
+        return destinationMint;
+    throw new Error("Source or destination mint must be SOL/wSOL/USDC/USD1");
+}
+function bnFromBigint(value, name, bits) {
+    if (value < 0n || value >= 1n << BigInt(bits)) {
+        throw new Error(`${name} must fit u${bits}`);
+    }
+    return new BN(value.toString());
+}
+/**
+ * Build the swap instruction for a single-hop pump.fun leg — through the
+ * tenant's wrapper program (tenant context) or directly against the 0Block
+ * router (direct context). Pure and synchronous: all chain-derived inputs
+ * arrive via the market context; the only PDAs derived here depend on the
+ * user key.
+ */
+export function buildPumpfunSwapInstruction(params) {
+    const { context, market, user, side } = params;
+    if (params.amountIn <= 0n)
+        throw new Error("amountIn must be > 0");
+    if (params.minReturn <= 0n)
+        throw new Error("minReturn must be > 0");
+    const routerProgramId = context.routerProgramId;
+    const zeroblockFeeVault = context.zeroblockFeeVault;
+    const pumpMint = toPk(market.mint);
+    const mintTokenProgram = toPk(market.mintTokenProgram);
+    const pumpProgram = toPk(market.pumpfunProgram);
+    // buy: wSOL -> token; sell: token -> wSOL. wSOL always rides the classic
+    // token program; the pump mint may live on Token-2022.
+    const sourceMint = side === "buy" ? WSOL_MINT : pumpMint;
+    const destinationMint = side === "buy" ? pumpMint : WSOL_MINT;
+    const sourceTokenProgram = side === "buy" ? TOKEN_PROGRAM_ID : mintTokenProgram;
+    const destinationTokenProgram = side === "buy" ? mintTokenProgram : TOKEN_PROGRAM_ID;
+    const sourceTokenAccount = deriveAta(user, sourceMint, sourceTokenProgram);
+    const destinationTokenAccount = deriveAta(user, destinationMint, destinationTokenProgram);
+    // Fee mint is the wSOL side for pump.fun swaps; fee ATAs belong to the fee
+    // authorities and are pre-created (and ALT-listed) by ops.
+    const feeMint = resolveFeeMint(sourceMint, destinationMint);
+    const feeTokenProgram = feeMint.equals(sourceMint)
+        ? sourceTokenProgram
+        : destinationTokenProgram;
+    const zeroblockFeeTokenAccount = deriveAta(zeroblockFeeVault, feeMint, feeTokenProgram);
+    const orderId = params.orderId ?? randomOrderId();
+    const dexVariant = side === "buy" ? { PumpfunBuy: {} } : { PumpfunSell: {} };
+    const amountIn = bnFromBigint(params.amountIn, "amountIn", 64);
+    const swapArgs = {
+        amount_in: amountIn,
+        min_return: bnFromBigint(params.minReturn, "minReturn", 64),
+        amounts: [amountIn],
+        routes: [[{ dexes: [dexVariant], weights: Buffer.from([100]) }]],
+        options: null,
+    };
+    // Random pick among the non-zero buyback recipients — the program validates
+    // membership on-chain, and ops pre-load all eight into the shared ALT.
+    const buyback = market.buybackFeeRecipients;
+    if (!buyback.length)
+        throw new Error("market.buybackFeeRecipients is empty");
+    const pick = new Uint32Array(1);
+    globalThis.crypto.getRandomValues(pick);
+    const buybackFeeRecipient = toPk(buyback[pick[0] % buyback.length]);
+    const remainingAccounts = buildPumpfunRemainingAccounts(side, {
+        dexProgramId: pumpProgram,
+        swapAuthority: user,
+        swapSourceToken: sourceTokenAccount,
+        swapDestinationToken: destinationTokenAccount,
+        pumpfunGlobal: toPk(market.global),
+        pumpfunFeeRecipient: toPk(market.feeRecipient),
+        pumpfunMint: pumpMint,
+        pumpfunBondingCurve: toPk(market.bondingCurve),
+        pumpfunAssociatedBondingCurve: toPk(market.associatedBondingCurve),
+        systemProgramId: web3.SystemProgram.programId,
+        tokenProgramId: mintTokenProgram,
+        pumpfunCreatorVault: toPk(market.creatorVault),
+        pumpfunEventAuthority: toPk(market.eventAuthority),
+        pumpfunGlobalVolumeAccumulator: toPk(market.globalVolumeAccumulator),
+        pumpfunUserVolumeAccumulator: derivePumpfunUserVolumeAccumulator(pumpProgram, user),
+        pumpfunFeeConfig: toPk(market.feeConfig),
+        pumpfunFeeProgram: toPk(market.pumpfunFeeProgram),
+        pumpfunBondingCurveV2: toPk(market.bondingCurveV2),
+        pumpfunBuybackFeeRecipient: buybackFeeRecipient,
+        extraTokenProgramId: mintTokenProgram.equals(TOKEN_2022_PROGRAM_ID)
+            ? TOKEN_PROGRAM_ID
+            : null,
+    });
+    const globalCfg = deriveRouterGlobalConfig(routerProgramId);
+    let programId;
+    let data;
+    let fixedKeys;
+    if (context.mode === "tenant") {
+        // Tenant path: wrapper swap ix. The wrapper reads its stored fee_bps and
+        // PDA-signs the router CPI, so the user is the only tx-level signer.
+        const wrapperProgramId = context.wrapperProgramId;
+        const tenantFeeVault = context.tenantFeeVault;
+        const tenantFeeTokenAccount = deriveAta(tenantFeeVault, feeMint, feeTokenProgram);
+        programId = wrapperProgramId;
+        data = wrapperCoder.encode("swap", {
+            args: swapArgs,
+            order_id: bnFromBigint(orderId, "orderId", 128),
+        });
+        // Fixed accounts in the exact order the wrapper IDL declares them.
+        fixedKeys = [
+            { pubkey: user, isWritable: true, isSigner: true },
+            { pubkey: deriveWrapperConfig(wrapperProgramId), isWritable: false, isSigner: false },
+            { pubkey: routerProgramId, isWritable: false, isSigner: false },
+            { pubkey: sourceTokenAccount, isWritable: true, isSigner: false },
+            { pubkey: destinationTokenAccount, isWritable: true, isSigner: false },
+            { pubkey: sourceMint, isWritable: false, isSigner: false },
+            { pubkey: destinationMint, isWritable: false, isSigner: false },
+            { pubkey: globalCfg, isWritable: false, isSigner: false },
+            {
+                pubkey: deriveRouterTenantConfig(routerProgramId, wrapperProgramId),
+                isWritable: false,
+                isSigner: false,
+            },
+            // No tenant_authority account: the wrapper_config PDA signs the router
+            // CPI via seeds, so the user is the only transaction-level signer.
+            { pubkey: zeroblockFeeVault, isWritable: true, isSigner: false },
+            { pubkey: tenantFeeVault, isWritable: true, isSigner: false },
+            { pubkey: zeroblockFeeTokenAccount, isWritable: true, isSigner: false },
+            { pubkey: tenantFeeTokenAccount, isWritable: true, isSigner: false },
+            { pubkey: sourceTokenProgram, isWritable: false, isSigner: false },
+            { pubkey: destinationTokenProgram, isWritable: false, isSigner: false },
+            { pubkey: ASSOCIATED_TOKEN_PROGRAM_ID, isWritable: false, isSigner: false },
+            { pubkey: web3.SystemProgram.programId, isWritable: false, isSigner: false },
+            { pubkey: INSTRUCTIONS_SYSVAR_ID, isWritable: false, isSigner: false },
+        ];
+    }
+    else {
+        // Direct path: router swap ix, 0Block fee only (tenant_fee_bps = None).
+        // The router validates tenant_cfg/tenant vaults only on wrapped calls, so
+        // the user doubles as tenant_authority (dedupes with payer — still one
+        // signer) and the 0Block fee accounts fill the tenant slots.
+        programId = routerProgramId;
+        data = routerCoder.encode("swap", {
+            args: swapArgs,
+            order_id: bnFromBigint(orderId, "orderId", 128),
+            tenant_fee_bps: null,
+        });
+        // Fixed accounts in the exact order the router IDL declares them.
+        fixedKeys = [
+            { pubkey: user, isWritable: true, isSigner: true },
+            { pubkey: sourceTokenAccount, isWritable: true, isSigner: false },
+            { pubkey: destinationTokenAccount, isWritable: true, isSigner: false },
+            { pubkey: sourceMint, isWritable: false, isSigner: false },
+            { pubkey: destinationMint, isWritable: false, isSigner: false },
+            { pubkey: globalCfg, isWritable: false, isSigner: false },
+            {
+                pubkey: deriveRouterTenantConfig(routerProgramId, context.directTenantConfigKey),
+                isWritable: false,
+                isSigner: false,
+            },
+            { pubkey: user, isWritable: false, isSigner: true },
+            { pubkey: zeroblockFeeVault, isWritable: true, isSigner: false },
+            { pubkey: zeroblockFeeVault, isWritable: true, isSigner: false },
+            { pubkey: zeroblockFeeTokenAccount, isWritable: true, isSigner: false },
+            { pubkey: zeroblockFeeTokenAccount, isWritable: true, isSigner: false },
+            { pubkey: sourceTokenProgram, isWritable: false, isSigner: false },
+            { pubkey: destinationTokenProgram, isWritable: false, isSigner: false },
+            { pubkey: ASSOCIATED_TOKEN_PROGRAM_ID, isWritable: false, isSigner: false },
+            { pubkey: web3.SystemProgram.programId, isWritable: false, isSigner: false },
+            { pubkey: INSTRUCTIONS_SYSVAR_ID, isWritable: false, isSigner: false },
+        ];
+    }
+    return {
+        instruction: new web3.TransactionInstruction({
+            programId,
+            keys: [...fixedKeys, ...remainingAccounts],
+            data,
+        }),
+        orderId,
+        sourceTokenAccount,
+        destinationTokenAccount,
+    };
+}
+/**
+ * Decode a swap instruction's data. Both programs share the `swap`
+ * discriminator (anchor hashes the instruction name), and the wrapper layout
+ * is a strict prefix of the router's (which appends `tenant_fee_bps:
+ * Option<u16>`) — so the router coder is tried FIRST: it fails on wrapper
+ * data (missing trailing option byte), while the wrapper coder would
+ * silently mis-decode router data by ignoring the tail.
+ */
+export function decodeSwapData(data) {
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    try {
+        const direct = routerCoder.decode(buf);
+        if (direct)
+            return { program: "router", ...direct };
+    }
+    catch {
+        // fall through to the wrapper layout
+    }
+    const wrapped = wrapperCoder.decode(buf);
+    if (wrapped)
+        return { program: "tenant-wrapper", ...wrapped };
+    throw new Error("not a tenant-wrapper or router instruction");
+}

package/dist/tip.d.ts

@@ -0,0 +1,15 @@
+import * as web3 from "@solana/web3.js";
+import type { TipParams } from "./types.js";
+/**
+ * Gateway tip: a plain SystemProgram transfer to an allowlisted tip account.
+ * The 0Block gateway verifies it structurally on the RAW transaction bytes
+ * and does not resolve address lookup tables, so the destination must remain
+ * a static message key (see maskTipAccountInTables).
+ */
+export declare function buildTipInstruction(from: web3.PublicKey, tip: TipParams): web3.TransactionInstruction;
+/**
+ * Return copies of the lookup tables with the tip destination replaced by an
+ * unmatchable placeholder, so the v0 compiler cannot move the tip account
+ * into the lookup section. Never mutates the caller's tables.
+ */
+export declare function maskTipAccountInTables(tables: web3.AddressLookupTableAccount[], tipAccount: web3.PublicKey): web3.AddressLookupTableAccount[];

package/dist/tip.js

@@ -0,0 +1,37 @@
+import * as web3 from "@solana/web3.js";
+import { toPk } from "./pda.js";
+/**
+ * Gateway tip: a plain SystemProgram transfer to an allowlisted tip account.
+ * The 0Block gateway verifies it structurally on the RAW transaction bytes
+ * and does not resolve address lookup tables, so the destination must remain
+ * a static message key (see maskTipAccountInTables).
+ */
+export function buildTipInstruction(from, tip) {
+    if (tip.lamports <= 0n)
+        throw new Error("tip lamports must be > 0");
+    return web3.SystemProgram.transfer({
+        fromPubkey: from,
+        toPubkey: toPk(tip.account),
+        lamports: tip.lamports,
+    });
+}
+/**
+ * Return copies of the lookup tables with the tip destination replaced by an
+ * unmatchable placeholder, so the v0 compiler cannot move the tip account
+ * into the lookup section. Never mutates the caller's tables.
+ */
+export function maskTipAccountInTables(tables, tipAccount) {
+    return tables.map((table) => {
+        const masked = table.state.addresses.map((address) => {
+            if (!address.equals(tipAccount))
+                return address;
+            const random = new Uint8Array(32);
+            globalThis.crypto.getRandomValues(random);
+            return new web3.PublicKey(random);
+        });
+        return new web3.AddressLookupTableAccount({
+            key: table.key,
+            state: { ...table.state, addresses: masked },
+        });
+    });
+}

package/dist/transaction.d.ts

@@ -0,0 +1,19 @@
+import * as web3 from "@solana/web3.js";
+import type { BuildPumpfunSwapParams, BuildSwapResult, LookupTableData } from "./types.js";
+/** Rehydrate a streamed lookup table into web3.js form (compile-time only fields defaulted). */
+export declare function toLookupTableAccount(data: LookupTableData): web3.AddressLookupTableAccount;
+/**
+ * Build a complete, UNSIGNED v0 swap transaction for one pump.fun leg through
+ * a tenant wrapper. Fully offline: blockhash, market context, and lookup
+ * tables all arrive as inputs (streamed from the tenant backend).
+ *
+ * Instruction order: [tip] [compute budget] [ATA / wrap pre-steps] swap [unwrap].
+ * The tip leads so the gateway finds it without scanning past CPI-heavy ixs,
+ * and its destination is kept out of the lookup tables (raw-bytes rule).
+ */
+export declare function buildPumpfunSwapTransaction(params: BuildPumpfunSwapParams): BuildSwapResult;
+/**
+ * Attach externally-produced signatures (e.g. from sigcore) in
+ * requiredSigners order and return the wire-ready bytes.
+ */
+export declare function serializeWithSignatures(result: BuildSwapResult, signatures: Uint8Array[]): Uint8Array;

package/dist/transaction.js

@@ -0,0 +1,106 @@
+import * as web3 from "@solana/web3.js";
+import { MAX_TX_SIZE } from "./constants.js";
+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";
+/** Rehydrate a streamed lookup table into web3.js form (compile-time only fields defaulted). */
+export function toLookupTableAccount(data) {
+    return new web3.AddressLookupTableAccount({
+        key: toPk(data.key),
+        state: {
+            deactivationSlot: 2n ** 64n - 1n,
+            lastExtendedSlot: 0,
+            lastExtendedSlotStartIndex: 0,
+            authority: undefined,
+            addresses: data.addresses.map((a) => toPk(a)),
+        },
+    });
+}
+/**
+ * Build a complete, UNSIGNED v0 swap transaction for one pump.fun leg through
+ * a tenant wrapper. Fully offline: blockhash, market context, and lookup
+ * tables all arrive as inputs (streamed from the tenant backend).
+ *
+ * Instruction order: [tip] [compute budget] [ATA / wrap pre-steps] swap [unwrap].
+ * The tip leads so the gateway finds it without scanning past CPI-heavy ixs,
+ * and its destination is kept out of the lookup tables (raw-bytes rule).
+ */
+export function buildPumpfunSwapTransaction(params) {
+    const user = toPk(params.user);
+    const swap = buildPumpfunSwapInstruction({
+        context: params.context,
+        market: params.market,
+        user,
+        side: params.side,
+        amountIn: params.amountIn,
+        minReturn: params.minReturn,
+        orderId: params.orderId,
+    });
+    const instructions = [];
+    if (params.tip) {
+        instructions.push(buildTipInstruction(user, params.tip));
+    }
+    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 }));
+        }
+        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));
+    }
+    let tables = (params.lookupTables ?? []).map(toLookupTableAccount);
+    if (params.tip) {
+        tables = maskTipAccountInTables(tables, toPk(params.tip.account));
+    }
+    const message = new web3.TransactionMessage({
+        payerKey: user,
+        recentBlockhash: params.recentBlockhash,
+        instructions,
+    }).compileToV0Message(tables);
+    const transaction = new web3.VersionedTransaction(message);
+    const estimatedSize = transaction.serialize().length; // placeholder sigs = wire size
+    if (estimatedSize > MAX_TX_SIZE) {
+        throw new Error(`transaction too large (${estimatedSize} > ${MAX_TX_SIZE}); ` +
+            "pass the shared lookup table(s) via lookupTables");
+    }
+    const requiredSigners = message.staticAccountKeys.slice(0, message.header.numRequiredSignatures);
+    return {
+        transaction,
+        messageBytes: message.serialize(),
+        requiredSigners,
+        orderId: swap.orderId,
+        estimatedSize,
+    };
+}
+/**
+ * Attach externally-produced signatures (e.g. from sigcore) in
+ * requiredSigners order and return the wire-ready bytes.
+ */
+export function serializeWithSignatures(result, signatures) {
+    const expected = result.transaction.message.header.numRequiredSignatures;
+    if (signatures.length !== expected) {
+        throw new Error(`expected ${expected} signatures, got ${signatures.length}`);
+    }
+    for (const [i, signer] of result.requiredSigners.entries()) {
+        result.transaction.addSignature(signer, signatures[i]);
+    }
+    return result.transaction.serialize();
+}