@0block.io/sdk 0.1.0

package/README.md

@@ -0,0 +1,172 @@
+# @0block.io/sdk
+
+[![npm version](https://img.shields.io/npm/v/%400block.io%2Fsdk.svg)](https://www.npmjs.com/package/@0block.io/sdk)
+[![types](https://img.shields.io/npm/types/%400block.io%2Fsdk.svg)](https://www.npmjs.com/package/@0block.io/sdk)
+
+**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.
+
+- **Zero network calls at trade time.** Market context, lookup tables, and a
+  blockhash are resolved once server-side and streamed; the client assembles
+  the transaction synchronously.
+- **One signature.** The end user is the only required signer, in both modes.
+- **Fees are on-chain, not inputs.** Tenant and platform commissions are read
+  and enforced by the programs; the SDK never accepts a fee parameter.
+- **External-signer native.** Returns the exact message bytes to sign, for
+  wallets, signing services, or HSMs — no `Keypair` ever touches the SDK.
+
+## Installation
+
+```sh
+npm install @0block.io/sdk
+```
+
+Requires Node ≥ 20 server-side; browser builds work with any modern bundler.
+
+## Modes
+
+The mode is fixed at initialization:
+
+```ts
+import { createContext } from "@0block.io/sdk";
+
+// Tenant mode — swaps route through your tenant wrapper program.
+// Your tenant fee (set on-chain) and the 0Block fee apply.
+const ctx = createContext({
+  tenant: {
+    wrapperProgramId: "<your tenant wrapper program id>",
+    tenantFeeVault: "<your tenant fee vault>",
+  },
+});
+
+// Direct mode — swaps invoke the 0Block router directly.
+// Only the 0Block platform fee applies.
+const ctx = createContext();
+```
+
+## Quick start
+
+### 1. Backend — resolve market context once, stream it
+
+```ts
+import { connectionFetcher, resolvePumpfunMarketContext } from "@0block.io/sdk";
+
+const fetcher = connectionFetcher(connection);
+const market = await resolvePumpfunMarketContext(fetcher, { mint });
+// `market` is plain strings — push it to clients over your existing
+// stream together with quotes and a FINALIZED blockhash.
+```
+
+### 2. Backend ops — shared lookup table, once per venue set
+
+```ts
+import {
+  buildLookupTableAddresses,
+  buildInitLookupTableInstructions,
+} from "@0block.io/sdk";
+
+const addresses = buildLookupTableAddresses({ context: ctx, market });
+const { tableAddress, transactions } = buildInitLookupTableInstructions({
+  authority: opsKey,
+  recentSlot,
+  addresses,
+});
+// Send each batch as one transaction, in order. Wait ~1 slot before first use.
+```
+
+### 3. Client — preset → unsigned transaction → your signer
+
+```ts
+import { applyPreset, buildPumpfunSwapTransaction } from "@0block.io/sdk";
+
+const { minReturn, tip, computeBudget } = applyPreset(
+  { slippagePct: 20, prioritySol: 0.001, bribeSol: 0.001 },
+  { expectedOut: quote.expectedOut, tipAccount: streamed.tipAccount }
+);
+
+const built = buildPumpfunSwapTransaction({
+  context: ctx,
+  market,
+  user: wallet.address,
+  side: "buy",
+  amountIn: 10_000_000n, // 0.01 SOL
+  minReturn,
+  recentBlockhash: streamed.finalizedBlockhash,
+  lookupTables: streamed.lookupTables,
+  tip,
+  computeBudget,
+});
+
+// built.messageBytes  → sign with the user's key (exactly one signature)
+// built.orderId       → correlate the fill via SwapResultEvent
+// built.estimatedSize → wire size, pre-checked against the 1232-byte limit
+```
+
+Attach the signature and get wire bytes with `serializeWithSignatures(built, [sig])`,
+then submit through the 0Block gateway.
+
+### 4. Indexer — fee accounting from confirmed transactions
+
+```ts
+import { decodeSwapResultEvents } from "@0block.io/sdk";
+
+const events = decodeSwapResultEvents(tx.meta.logMessages);
+// [{ orderId, status, commissions: { feeMint, totalFeeAmount,
+//    items: [{ kind: "platform" | "tenant", bps, amount, tenantProgram }] } }]
+```
+
+## API overview
+
+| Runs | Function | Purpose |
+|---|---|---|
+| anywhere | `createContext` | Resolve tenant vs direct mode from init params |
+| backend | `resolvePumpfunMarketContext` | Chain-derived accounts for a mint, as streamable strings |
+| backend | `buildLookupTableAddresses` / `buildInitLookupTableInstructions` | Create the shared static-accounts table |
+| client | `applyPreset` | Slippage % / priority SOL / bribe SOL → build params |
+| client | `buildPumpfunSwapTransaction` | Complete unsigned v0 transaction (offline) |
+| client | `serializeWithSignatures` | Attach external signatures → wire bytes |
+| indexer | `decodeSwapResultEvents` | `SwapResultEvent` → normalized commission breakdown |
+
+Lower-level building blocks (`buildPumpfunSwapInstruction`, PDA derivations,
+wSOL wrap/unwrap helpers, tip and compute-budget builders, vendored IDLs) are
+exported as well.
+
+## Operational notes
+
+- **Tenant mode prerequisites.** Your wrapper must be the build in which the
+  `wrapper_config` PDA signs the router CPI, and the router's
+  `TenantConfig.tenant_authority` must equal that PDA
+  (`deriveWrapperConfig(wrapperProgramId)`). Otherwise swaps fail
+  `UnauthorizedTenant`.
+- **Direct mode prerequisite.** The router requires *a* `TenantConfig` account
+  in the `tenant_cfg` slot even on direct calls (ignored for fees). The router
+  operator provisions a standing "direct" config; override its key with
+  `directTenantConfigKey` if needed.
+- **Tips must stay static message keys.** The gateway verifies the tip transfer
+  on raw bytes without resolving lookup tables. The builder masks tip accounts
+  out of table copies defensively — never add tip accounts to an ALT.
+- **Use a FINALIZED blockhash.** The gateway forwards to a different staked
+  node; a `confirmed` hash may be unknown there.
+- **Native SOL handling.** Buys wrap SOL → wSOL in-transaction (idempotent ATA
+  + transfer + SyncNative); sells close the wSOL ATA back to SOL. Opt out with
+  `wrapSol` / `unwrapWsol` if your users manage wSOL themselves.
+- **Venue coverage.** v1 ships the pump.fun bonding-curve venue (buy/sell,
+  single hop). Additional venues follow the same shape — one
+  remaining-accounts builder per venue.
+
+## Development
+
+```sh
+npm install
+npm test   # compiles, then runs the offline smoke test (no network, no keys)
+```
+
+The vendored IDLs under `src/idl/` are generated from the on-chain programs'
+Anchor builds. Regenerate them after any program change — account ordering and
+discriminators must match on-chain reality.
+
+## License
+
+UNLICENSED — all rights reserved. Contact 0block.io for usage terms.

package/dist/alt.d.ts

@@ -0,0 +1,34 @@
+import * as web3 from "@solana/web3.js";
+import type { ZeroBlockContext } from "./context.js";
+import type { PumpfunMarketContext } from "./types.js";
+/**
+ * The static account set for pump.fun swaps under a context — everything that
+ * is identical across users and trades. Load these into a shared address
+ * lookup table once (ops), and every user's v0 transaction references it.
+ *
+ * Never add gateway tip accounts: the gateway requires the tip destination as
+ * a static message key (the build path masks it defensively either way).
+ */
+export declare function buildLookupTableAddresses(params: {
+    context: ZeroBlockContext;
+    /** Any market context for the venue — only its static venue fields are used. */
+    market: Pick<PumpfunMarketContext, "pumpfunProgram" | "pumpfunFeeProgram" | "global" | "eventAuthority" | "globalVolumeAccumulator" | "feeConfig" | "buybackFeeRecipients">;
+    extra?: (string | web3.PublicKey)[];
+}): web3.PublicKey[];
+export interface InitLookupTableResult {
+    tableAddress: web3.PublicKey;
+    /**
+     * Instruction batches: send each inner array as one transaction, in order
+     * (create+first extend, then further extends of ≤20 addresses). Wait ~1
+     * slot after the last extend before first use.
+     */
+    transactions: web3.TransactionInstruction[][];
+}
+/** Build the create/extend instruction batches for a shared lookup table (ops path). */
+export declare function buildInitLookupTableInstructions(params: {
+    authority: web3.PublicKey;
+    payer?: web3.PublicKey;
+    /** A recent (finalized) slot, required by createLookupTable. */
+    recentSlot: number;
+    addresses: web3.PublicKey[];
+}): InitLookupTableResult;

package/dist/alt.js

@@ -0,0 +1,83 @@
+import * as web3 from "@solana/web3.js";
+import { ASSOCIATED_TOKEN_PROGRAM_ID, INSTRUCTIONS_SYSVAR_ID, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID, WSOL_MINT, } from "./constants.js";
+import { deriveAta, deriveRouterGlobalConfig, deriveRouterTenantConfig, deriveWrapperConfig, toPk, } from "./pda.js";
+/**
+ * The static account set for pump.fun swaps under a context — everything that
+ * is identical across users and trades. Load these into a shared address
+ * lookup table once (ops), and every user's v0 transaction references it.
+ *
+ * Never add gateway tip accounts: the gateway requires the tip destination as
+ * a static message key (the build path masks it defensively either way).
+ */
+export function buildLookupTableAddresses(params) {
+    const { context } = params;
+    const routerProgramId = context.routerProgramId;
+    const zeroblockFeeVault = context.zeroblockFeeVault;
+    const tenantAddresses = context.mode === "tenant"
+        ? [
+            context.wrapperProgramId,
+            deriveWrapperConfig(context.wrapperProgramId),
+            deriveRouterTenantConfig(routerProgramId, context.wrapperProgramId),
+            context.tenantFeeVault,
+            deriveAta(context.tenantFeeVault, WSOL_MINT, TOKEN_PROGRAM_ID),
+        ]
+        : [deriveRouterTenantConfig(routerProgramId, context.directTenantConfigKey)];
+    const addresses = [
+        routerProgramId,
+        deriveRouterGlobalConfig(routerProgramId),
+        ...tenantAddresses,
+        zeroblockFeeVault,
+        deriveAta(zeroblockFeeVault, WSOL_MINT, TOKEN_PROGRAM_ID),
+        TOKEN_PROGRAM_ID,
+        TOKEN_2022_PROGRAM_ID,
+        ASSOCIATED_TOKEN_PROGRAM_ID,
+        web3.SystemProgram.programId,
+        INSTRUCTIONS_SYSVAR_ID,
+        WSOL_MINT,
+        toPk(params.market.pumpfunProgram),
+        toPk(params.market.global),
+        toPk(params.market.eventAuthority),
+        toPk(params.market.globalVolumeAccumulator),
+        toPk(params.market.feeConfig),
+        toPk(params.market.pumpfunFeeProgram),
+        ...params.market.buybackFeeRecipients.map((r) => toPk(r)),
+        ...(params.extra ?? []).map((a) => toPk(a)),
+    ];
+    const seen = new Set();
+    return addresses.filter((a) => {
+        const k = a.toBase58();
+        if (seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    });
+}
+/** Build the create/extend instruction batches for a shared lookup table (ops path). */
+export function buildInitLookupTableInstructions(params) {
+    const payer = params.payer ?? params.authority;
+    const CHUNK = 20;
+    const [createIx, tableAddress] = web3.AddressLookupTableProgram.createLookupTable({
+        authority: params.authority,
+        payer,
+        recentSlot: params.recentSlot,
+    });
+    const transactions = [];
+    const first = web3.AddressLookupTableProgram.extendLookupTable({
+        payer,
+        authority: params.authority,
+        lookupTable: tableAddress,
+        addresses: params.addresses.slice(0, CHUNK),
+    });
+    transactions.push([createIx, first]);
+    for (let i = CHUNK; i < params.addresses.length; i += CHUNK) {
+        transactions.push([
+            web3.AddressLookupTableProgram.extendLookupTable({
+                payer,
+                authority: params.authority,
+                lookupTable: tableAddress,
+                addresses: params.addresses.slice(i, i + CHUNK),
+            }),
+        ]);
+    }
+    return { tableAddress, transactions };
+}

package/dist/computeBudget.d.ts

@@ -0,0 +1,8 @@
+import * as web3 from "@solana/web3.js";
+import type { ComputeBudgetParams } from "./types.js";
+/**
+ * Convert a UI-level "priority fee in SOL" (the preset's Priority field) into
+ * compute-budget instructions: a CU limit plus a per-CU price such that the
+ * total priority fee equals approximately `prioritySol`.
+ */
+export declare function buildComputeBudgetInstructions(params: ComputeBudgetParams): web3.TransactionInstruction[];

package/dist/computeBudget.js

@@ -0,0 +1,25 @@
+import * as web3 from "@solana/web3.js";
+import { DEFAULT_COMPUTE_UNIT_LIMIT } from "./constants.js";
+/**
+ * Convert a UI-level "priority fee in SOL" (the preset's Priority field) into
+ * compute-budget instructions: a CU limit plus a per-CU price such that the
+ * total priority fee equals approximately `prioritySol`.
+ */
+export function buildComputeBudgetInstructions(params) {
+    const units = params.computeUnitLimit ?? DEFAULT_COMPUTE_UNIT_LIMIT;
+    if (!Number.isInteger(units) || units <= 0 || units > 1_400_000) {
+        throw new Error("computeUnitLimit must be an integer in (0, 1_400_000]");
+    }
+    if (!(params.prioritySol >= 0)) {
+        throw new Error("prioritySol must be >= 0");
+    }
+    const ixs = [
+        web3.ComputeBudgetProgram.setComputeUnitLimit({ units }),
+    ];
+    // total lamports = units * microLamports / 1e6  =>  micro-lamports per CU:
+    const microLamports = BigInt(Math.round((params.prioritySol * 1e9 * 1e6) / units));
+    if (microLamports > 0n) {
+        ixs.push(web3.ComputeBudgetProgram.setComputeUnitPrice({ microLamports }));
+    }
+    return ixs;
+}

package/dist/constants.d.ts

@@ -0,0 +1,45 @@
+import * as web3 from "@solana/web3.js";
+/** Solana wire-format ceiling for a serialized transaction (packet MTU). */
+export declare const MAX_TX_SIZE = 1232;
+/** 0Block DEX router program (the default when no tenant is configured). */
+export declare const ROUTER_PROGRAM_ID: web3.PublicKey;
+/** 0Block platform fee authority (owner of 0Block fee token accounts). */
+export declare const ZEROBLOCK_FEE_VAULT: web3.PublicKey;
+export declare const TOKEN_PROGRAM_ID: web3.PublicKey;
+export declare const TOKEN_2022_PROGRAM_ID: web3.PublicKey;
+export declare const ASSOCIATED_TOKEN_PROGRAM_ID: web3.PublicKey;
+export declare const WSOL_MINT: web3.PublicKey;
+export declare const USDC_MINT: web3.PublicKey;
+export declare const USD1_MINT: web3.PublicKey;
+export declare const INSTRUCTIONS_SYSVAR_ID: web3.PublicKey;
+/**
+ * Mints the router accepts as the fee mint. Fee base = amount_in when the
+ * SOURCE mint is allowlisted, else amount_out (see router config.rs fee math).
+ */
+export declare const FEE_MINT_ALLOWLIST: readonly string[];
+export declare const PUMPFUN_PROGRAM_ID: web3.PublicKey;
+export declare const PUMPFUN_FEE_PROGRAM_ID: web3.PublicKey;
+export declare const SEED_WRAPPER_CONFIG: Uint8Array<ArrayBuffer>;
+export declare const SEED_ROUTER_GLOBAL_CONFIG: Uint8Array<ArrayBuffer>;
+export declare const SEED_ROUTER_TENANT: Uint8Array<ArrayBuffer>;
+export declare const SEED_PUMPFUN_GLOBAL: Uint8Array<ArrayBuffer>;
+export declare const SEED_PUMPFUN_BONDING_CURVE: Uint8Array<ArrayBuffer>;
+export declare const SEED_PUMPFUN_BONDING_CURVE_V2: Uint8Array<ArrayBuffer>;
+export declare const SEED_PUMPFUN_EVENT_AUTHORITY: Uint8Array<ArrayBuffer>;
+export declare const SEED_PUMPFUN_CREATOR_VAULT: Uint8Array<ArrayBuffer>;
+export declare const SEED_PUMPFUN_GLOBAL_VOLUME: Uint8Array<ArrayBuffer>;
+export declare const SEED_PUMPFUN_USER_VOLUME: Uint8Array<ArrayBuffer>;
+export declare const SEED_PUMPFUN_FEE_CONFIG: Uint8Array<ArrayBuffer>;
+/**
+ * Byte offset of Global.buyback_fee_recipients ([Pubkey; 8]) inside the
+ * pump.fun Global account data (8-byte discriminator + preceding fields).
+ */
+export declare const PUMPFUN_GLOBAL_BUYBACK_RECIPIENTS_OFFSET = 741;
+/** Default gateway tip when the caller does not specify one (0.001 SOL). */
+export declare const DEFAULT_TIP_LAMPORTS = 1000000n;
+/**
+ * Default compute-unit limit for a single-hop wrapper swap. Router swaps CPI
+ * through the wrapper into the venue program, so they are heavier than a
+ * direct venue call.
+ */
+export declare const DEFAULT_COMPUTE_UNIT_LIMIT = 400000;

package/dist/constants.js

@@ -0,0 +1,54 @@
+import * as web3 from "@solana/web3.js";
+/** Solana wire-format ceiling for a serialized transaction (packet MTU). */
+export const MAX_TX_SIZE = 1232;
+/** 0Block DEX router program (the default when no tenant is configured). */
+export const ROUTER_PROGRAM_ID = new web3.PublicKey("zeroRxfemoQCz6JT7RyShjuuRCN7VZof1WSekfXhmEn");
+/** 0Block platform fee authority (owner of 0Block fee token accounts). */
+export const ZEROBLOCK_FEE_VAULT = new web3.PublicKey("zerobvXpiuDCSrpmw1dJNbfAXPLp8hFYeQ62u4XRQZf");
+export const TOKEN_PROGRAM_ID = new web3.PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
+export const TOKEN_2022_PROGRAM_ID = new web3.PublicKey("TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb");
+export const ASSOCIATED_TOKEN_PROGRAM_ID = new web3.PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
+export const WSOL_MINT = new web3.PublicKey("So11111111111111111111111111111111111111112");
+export const USDC_MINT = new web3.PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
+export const USD1_MINT = new web3.PublicKey("USD1ttGY1N17NEEHLmELoaybftRBUSErhqYiQzvEmuB");
+export const INSTRUCTIONS_SYSVAR_ID = new web3.PublicKey("Sysvar1nstructions1111111111111111111111111");
+/**
+ * Mints the router accepts as the fee mint. Fee base = amount_in when the
+ * SOURCE mint is allowlisted, else amount_out (see router config.rs fee math).
+ */
+export const FEE_MINT_ALLOWLIST = [
+    web3.SystemProgram.programId.toBase58(),
+    WSOL_MINT.toBase58(),
+    USDC_MINT.toBase58(),
+    USD1_MINT.toBase58(),
+];
+// ---------------------------------------------------------------------------
+// pump.fun (the v1 venue)
+// ---------------------------------------------------------------------------
+export const PUMPFUN_PROGRAM_ID = new web3.PublicKey("6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P");
+export const PUMPFUN_FEE_PROGRAM_ID = new web3.PublicKey("pfeeUxB6jkeY1Hxd7CsFCAjcbHA9rWtchMGdZ6VojVZ");
+const te = new TextEncoder();
+export const SEED_WRAPPER_CONFIG = te.encode("tenant_wrapper_config");
+export const SEED_ROUTER_GLOBAL_CONFIG = te.encode("config");
+export const SEED_ROUTER_TENANT = te.encode("tenant");
+export const SEED_PUMPFUN_GLOBAL = te.encode("global");
+export const SEED_PUMPFUN_BONDING_CURVE = te.encode("bonding-curve");
+export const SEED_PUMPFUN_BONDING_CURVE_V2 = te.encode("bonding-curve-v2");
+export const SEED_PUMPFUN_EVENT_AUTHORITY = te.encode("__event_authority");
+export const SEED_PUMPFUN_CREATOR_VAULT = te.encode("creator-vault");
+export const SEED_PUMPFUN_GLOBAL_VOLUME = te.encode("global_volume_accumulator");
+export const SEED_PUMPFUN_USER_VOLUME = te.encode("user_volume_accumulator");
+export const SEED_PUMPFUN_FEE_CONFIG = te.encode("fee_config");
+/**
+ * Byte offset of Global.buyback_fee_recipients ([Pubkey; 8]) inside the
+ * pump.fun Global account data (8-byte discriminator + preceding fields).
+ */
+export const PUMPFUN_GLOBAL_BUYBACK_RECIPIENTS_OFFSET = 741;
+/** Default gateway tip when the caller does not specify one (0.001 SOL). */
+export const DEFAULT_TIP_LAMPORTS = 1000000n;
+/**
+ * Default compute-unit limit for a single-hop wrapper swap. Router swaps CPI
+ * through the wrapper into the venue program, so they are heavier than a
+ * direct venue call.
+ */
+export const DEFAULT_COMPUTE_UNIT_LIMIT = 400_000;

package/dist/context.d.ts

@@ -0,0 +1,47 @@
+import * as web3 from "@solana/web3.js";
+import type { Address } from "./types.js";
+/** Tenant initialization: the tenant's wrapper program + fee vault. */
+export interface TenantInit {
+    /** The tenant's deployed wrapper program. */
+    wrapperProgramId: Address;
+    /** Tenant fee authority (owns the tenant fee token accounts). */
+    tenantFeeVault: Address;
+}
+export interface CreateContextParams {
+    /**
+     * Provide to route swaps through the tenant's wrapper program (tenant fees
+     * apply). Omit to invoke the 0Block router directly with 0Block fee
+     * accounts only.
+     */
+    tenant?: TenantInit;
+    /** Router program id. Defaults to the mainnet router. */
+    routerProgramId?: Address;
+    /** 0Block platform fee authority. Defaults to the mainnet vault. */
+    zeroblockFeeVault?: Address;
+    /**
+     * Direct mode only: the wrapper key whose router TenantConfig PDA is passed
+     * as `tenant_cfg` (the account must exist; the router ignores it for fee
+     * purposes on direct calls). Defaults to the default pubkey — the router
+     * operator initializes this "direct" TenantConfig once.
+     */
+    directTenantConfigKey?: Address;
+}
+/** Resolved build context: tenant-wrapped or direct-to-router. */
+export type ZeroBlockContext = {
+    mode: "tenant";
+    routerProgramId: web3.PublicKey;
+    zeroblockFeeVault: web3.PublicKey;
+    wrapperProgramId: web3.PublicKey;
+    tenantFeeVault: web3.PublicKey;
+} | {
+    mode: "direct";
+    routerProgramId: web3.PublicKey;
+    zeroblockFeeVault: web3.PublicKey;
+    directTenantConfigKey: web3.PublicKey;
+};
+/**
+ * Resolve how transactions are built. With a `tenant`, swaps go through the
+ * tenant's wrapper program (tenant + 0Block fees); without one, they invoke
+ * the 0Block router directly (0Block fee only).
+ */
+export declare function createContext(params?: CreateContextParams): ZeroBlockContext;

package/dist/context.js

@@ -0,0 +1,27 @@
+import * as web3 from "@solana/web3.js";
+import { ROUTER_PROGRAM_ID, ZEROBLOCK_FEE_VAULT } from "./constants.js";
+import { toPk } from "./pda.js";
+/**
+ * Resolve how transactions are built. With a `tenant`, swaps go through the
+ * tenant's wrapper program (tenant + 0Block fees); without one, they invoke
+ * the 0Block router directly (0Block fee only).
+ */
+export function createContext(params = {}) {
+    const routerProgramId = toPk(params.routerProgramId ?? ROUTER_PROGRAM_ID);
+    const zeroblockFeeVault = toPk(params.zeroblockFeeVault ?? ZEROBLOCK_FEE_VAULT);
+    if (params.tenant) {
+        return {
+            mode: "tenant",
+            routerProgramId,
+            zeroblockFeeVault,
+            wrapperProgramId: toPk(params.tenant.wrapperProgramId),
+            tenantFeeVault: toPk(params.tenant.tenantFeeVault),
+        };
+    }
+    return {
+        mode: "direct",
+        routerProgramId,
+        zeroblockFeeVault,
+        directTenantConfigKey: toPk(params.directTenantConfigKey ?? web3.PublicKey.default),
+    };
+}

package/dist/events.d.ts

@@ -0,0 +1,9 @@
+import type { DecodedSwapResult } from "./types.js";
+/**
+ * Decode every router SwapResultEvent found in a transaction's log messages
+ * (tx.meta.logMessages). This is the accounting hook: on success the event
+ * carries the full CommissionBreakdown — fee mint, base, total, and one item
+ * per recipient (platform vs tenant, with the tenant wrapper program id) —
+ * plus the order_id that correlates back to the submitted order.
+ */
+export declare function decodeSwapResultEvents(logMessages: readonly string[]): DecodedSwapResult[];

package/dist/events.js

@@ -0,0 +1,106 @@
+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, BorshEventCoder } = anchor;
+import { ROUTER_IDL } from "./idl/router.js";
+// Event layouts derive from the vendored (trimmed) router IDL.
+const eventCoder = new BorshEventCoder(ROUTER_IDL);
+const PROGRAM_DATA_PREFIX = "Program data: ";
+function toBigint(v) {
+    if (typeof v === "bigint")
+        return v;
+    if (BN.isBN(v))
+        return BigInt(v.toString());
+    return BigInt(String(v));
+}
+function toBase58(v) {
+    return v instanceof web3.PublicKey ? v.toBase58() : new web3.PublicKey(String(v)).toBase58();
+}
+/** Case-insensitive enum-variant lookup ({Success:{…}} vs {success:{…}}). */
+function variant(obj, name) {
+    for (const key of Object.keys(obj)) {
+        if (key.toLowerCase() === name.toLowerCase())
+            return obj[key];
+    }
+    return undefined;
+}
+/**
+ * Anchor decodes tuple enum variants as { "0": value } (numeric string keys);
+ * named-field variants decode as plain objects. Normalize to the inner value.
+ */
+function unwrapTuple(value) {
+    if (Array.isArray(value))
+        return value[0];
+    const obj = value;
+    if (obj && typeof obj === "object" && "0" in obj && Object.keys(obj).length === 1) {
+        return obj["0"];
+    }
+    return obj;
+}
+/**
+ * Decode every router SwapResultEvent found in a transaction's log messages
+ * (tx.meta.logMessages). This is the accounting hook: on success the event
+ * carries the full CommissionBreakdown — fee mint, base, total, and one item
+ * per recipient (platform vs tenant, with the tenant wrapper program id) —
+ * plus the order_id that correlates back to the submitted order.
+ */
+export function decodeSwapResultEvents(logMessages) {
+    const results = [];
+    for (const line of logMessages) {
+        const idx = line.indexOf(PROGRAM_DATA_PREFIX);
+        if (idx === -1)
+            continue;
+        const base64 = line.slice(idx + PROGRAM_DATA_PREFIX.length).trim();
+        let decoded = null;
+        try {
+            decoded = eventCoder.decode(base64);
+        }
+        catch {
+            continue; // some other program's data log
+        }
+        if (!decoded || decoded.name !== "SwapResultEvent")
+            continue;
+        const data = decoded.data;
+        const orderId = toBigint(data.order_id ?? data.orderId);
+        const resultData = (data.data ?? {});
+        const successRaw = variant(resultData, "Success");
+        if (successRaw) {
+            const success = unwrapTuple(successRaw);
+            const commissions = success.commissions;
+            const feeSource = variant((commissions.fee_source ?? commissions.feeSource ?? {}), "Input")
+                ? "input"
+                : "output";
+            const items = (commissions.items ?? []).map((item) => ({
+                kind: (variant((item.kind ?? {}), "Platform")
+                    ? "platform"
+                    : "tenant"),
+                bps: Number(item.bps),
+                amount: toBigint(item.amount),
+                tenantProgram: toBase58(item.tenant_program ?? item.tenantProgram),
+            }));
+            results.push({
+                orderId,
+                status: "success",
+                commissions: {
+                    feeMint: toBase58(commissions.fee_mint ?? commissions.feeMint),
+                    feeSource,
+                    feeBaseAmount: toBigint(commissions.fee_base_amount ?? commissions.feeBaseAmount),
+                    totalFeeAmount: toBigint(commissions.total_fee_amount ?? commissions.totalFeeAmount),
+                    items,
+                },
+            });
+            continue;
+        }
+        const failureRaw = variant(resultData, "Failure");
+        if (failureRaw) {
+            const f = unwrapTuple(failureRaw);
+            results.push({
+                orderId,
+                status: "failure",
+                failure: { code: toBigint(f.code), message: String(f.message) },
+            });
+        }
+    }
+    return results;
+}

package/dist/fetch.d.ts

@@ -0,0 +1,34 @@
+import * as web3 from "@solana/web3.js";
+import type { Address, PumpfunMarketContext } from "./types.js";
+/**
+ * The one seam the resolver needs to read chain state. Implement it with a
+ * web3.js Connection (see connectionFetcher) or any RPC client. The builder
+ * itself never fetches — resolve once server-side, stream the context out.
+ */
+export interface AccountFetcher {
+    getAccountInfo(address: web3.PublicKey): Promise<{
+        data: Uint8Array;
+        owner: web3.PublicKey;
+    } | null>;
+}
+/** AccountFetcher backed by a @solana/web3.js Connection. */
+export declare function connectionFetcher(connection: web3.Connection): AccountFetcher;
+/** Which token program owns a mint (classic SPL vs Token-2022). */
+export declare function resolveTokenProgram(fetcher: AccountFetcher, mint: Address): Promise<web3.PublicKey>;
+/** Global.fee_recipient (offset: discriminator + initialized flag + authority). */
+export declare function fetchPumpfunGlobalFeeRecipient(fetcher: AccountFetcher, globalAccount: web3.PublicKey): Promise<web3.PublicKey>;
+/** Non-zero entries of Global.buyback_fee_recipients ([Pubkey; 8]). */
+export declare function fetchPumpfunBuybackFeeRecipients(fetcher: AccountFetcher, globalAccount: web3.PublicKey): Promise<web3.PublicKey[]>;
+/** BondingCurve.creator (offset: discriminator + 5×u64 + bool). */
+export declare function fetchPumpfunBondingCurveCreator(fetcher: AccountFetcher, bondingCurve: web3.PublicKey): Promise<web3.PublicKey>;
+/**
+ * Resolve everything a pump.fun swap needs for one mint. Run this server-side
+ * next to an RPC (the tenant's backend) and stream the result to clients — every field
+ * is a plain base58 string. Only the per-user volume accumulator is left for
+ * build time (it depends on the user key).
+ */
+export declare function resolvePumpfunMarketContext(fetcher: AccountFetcher, params: {
+    mint: Address;
+    pumpfunProgram?: Address;
+    pumpfunFeeProgram?: Address;
+}): Promise<PumpfunMarketContext>;