@0block.io/sdk 0.1.0 → 0.2.0

package/README.md

@@ -3,10 +3,17 @@
 [![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.
+**The SDK for 0Block's two products — independent, composable:**
+
+| Product | What it does | Needs the other? |
+|---|---|---|
+| **DEX Smart Router** | Build swap transactions on-chain-routed across 60+ venues — through your tenant wrapper (your fee applies) or directly (0Block fee only) | No — submit through any RPC |
+| **Landing Service** | Land **any** fully-signed Solana transaction: tip-gated submission forwarded to staked infrastructure and current/next leader TPUs | No — accepts any transaction |
+
+Used together they form a complete trade pipeline: build with the router SDK,
+sign externally, land through the service.
+
+**Router highlights:**
 
 - **Zero network calls at trade time.** Market context, lookup tables, and a
   blockhash are resolved once server-side and streamed; the client assembles
@@ -14,6 +21,8 @@ accounting.
 - **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.
+- **SOL-native UX, program-managed.** In tenant mode the wrapper wraps/unwraps
+  and cleans up token accounts on-chain — clients never touch wSOL.
 - **External-signer native.** Returns the exact message bytes to sign, for
   wallets, signing services, or HSMs — no `Keypair` ever touches the SDK.
 
@@ -117,6 +126,36 @@ const events = decodeSwapResultEvents(tx.meta.logMessages);
 //    items: [{ kind: "platform" | "tenant", bps, amount, tenantProgram }] } }]
 ```
 
+## Landing Service (standalone)
+
+Land any transaction — router-built or otherwise. Three rules: include the
+tip (a plain transfer to an allowlisted account, kept as a **static** message
+key, never behind a lookup table), use a **finalized** blockhash, and confirm
+by **polling** (no websocket).
+
+```ts
+import { createLandingClient, withLandingTip } from "@0block.io/sdk";
+
+// Any instructions at all — no router required:
+const ixs = withLandingTip(myInstructions, payer, {
+  account: tipAccount,          // allowlisted tip account
+  lamports: 1_000_000n,         // ≥ the service minimum
+});
+// ...compile with a FINALIZED blockhash, sign...
+
+const landing = createLandingClient({
+  url: "https://<landing-endpoint>",
+  apiKey: process.env.ZEROBLOCK_API_KEY,
+});
+const { signature, slot } = await landing.submitAndConfirm(wireBytes, readConnection, {
+  lastValidBlockHeight,
+});
+```
+
+Router-built transactions already carry the tip when you pass `tip` to
+`buildPumpfunSwapTransaction` — hand their signed wire bytes straight to
+`landing.sendTransaction`.
+
 ## API overview
 
 | Runs | Function | Purpose |
@@ -135,6 +174,13 @@ exported as well.
 
 ## Operational notes
 
+- **Order ids are server-authoritative in tenant mode.** The wrapper enforces
+  an exactly-once replay gate keyed by `(payer, order_id)`: a duplicate order
+  id fails at account creation and the whole swap reverts. Mint `orderId` on
+  your backend (non-zero u128, one per business order — reuse it across
+  retries) and pass it to `buildPumpfunSwapTransaction`; the SDK refuses to
+  build tenant swaps without one. Direct mode has no marker; a random id is
+  generated when omitted.
 - **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

package/dist/constants.d.ts

@@ -20,6 +20,7 @@ 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_ORDER_MARKER: 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>;

package/dist/constants.js

@@ -29,6 +29,7 @@ export const PUMPFUN_PROGRAM_ID = new web3.PublicKey("6EF8rrecthR5Dkzon8Nwu78hRv
 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_ORDER_MARKER = te.encode("order");
 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");

package/dist/idl/tenantWrapper.d.ts

@@ -74,6 +74,7 @@ export declare const TENANT_WRAPPER_IDL: {
         }];
     }, {
         readonly name: "swap";
+        readonly docs: readonly ["Tenant swap with a hard, exactly-once-SUCCESS replay gate (R-6 / H1).", "", "The `order_marker` account is created with Anchor `init` (NOT", "`init_if_needed`) ATOMICALLY in this same instruction, BEFORE the router", "CPI runs. A second instruction with the same `(payer, order_id)` fails at", "`create_account` (\"account already in use\") and reverts the WHOLE", "instruction — including the router CPI — so a duplicate business order can", "never execute (and never pays fees) twice.", "", "INVARIANTS (off-chain encoder MUST uphold):", "- `order_id` is SERVER-AUTHORITATIVE. It is minted by the backend per", "business order and is NEVER a client-supplied value. A client that could", "choose `order_id` could grief a victim only inside its own `payer`", "namespace (see namespacing note below), but a server-authoritative id", "also guarantees that all per-gate provider-variants (0block / Jito /", "Helius / ...) of ONE business order reuse the SAME `(payer, order_id)`,", "so at most one variant can ever succeed.", "- On land-but-revert (the tx is included on-chain but the instruction", "reverts for any reason), the `init` is rolled back: the marker does NOT", "persist, the `order_id` is reclaimable, and the order may be retried with", "a FRESH durable nonce. (Durable-nonce dedup is at-most-one-LAND; this", "marker is exactly-once-SUCCESS — complementary, not redundant.)"];
         readonly discriminator: readonly [248, 198, 158, 145, 225, 117, 135, 200];
         readonly accounts: readonly [{
             readonly name: "payer";
@@ -88,17 +89,33 @@ export declare const TENANT_WRAPPER_IDL: {
                     readonly value: readonly [116, 101, 110, 97, 110, 116, 95, 119, 114, 97, 112, 112, 101, 114, 95, 99, 111, 110, 102, 105, 103];
                 }];
             };
+        }, {
+            readonly name: "order_marker";
+            readonly docs: readonly ["Per-order replay marker (R-6 / H1). `init` (NOT `init_if_needed`) makes a", "duplicate `(payer, order_id)` fail at `create_account` → the whole", "instruction (router CPI included) reverts.", "", "Namespaced by `payer` for griefing isolation: a third party can only ever", "init markers inside its OWN payer namespace, so it cannot pre-burn another", "user's `order_id`.", "", "ALTERNATIVE NAMESPACING: keying by `tenant_authority` instead of `payer`", "would dedup per business tenant (so the same logical order is unique across", "all of a tenant's relayer payers). We choose `payer` here because the RAX", "flow has one user-payer per order and `payer`-namespacing gives the", "strongest third-party griefing isolation; revisit if a single business", "order can legitimately arrive under multiple distinct payers."];
+            readonly writable: true;
+            readonly pda: {
+                readonly seeds: readonly [{
+                    readonly kind: "const";
+                    readonly value: readonly [111, 114, 100, 101, 114];
+                }, {
+                    readonly kind: "account";
+                    readonly path: "payer";
+                }, {
+                    readonly kind: "arg";
+                    readonly path: "order_id";
+                }];
+            };
         }, {
             readonly name: "router_program";
             readonly docs: readonly ["Router program (hard-checked by address)"];
             readonly address: "zeroRxfemoQCz6JT7RyShjuuRCN7VZof1WSekfXhmEn";
         }, {
             readonly name: "source_token_account";
-            readonly docs: readonly ["SOURCE token account (authority = payer)"];
+            readonly docs: readonly ["SOURCE token account (authority = payer).", "buys (Anchor deserializes typed accounts before the handler runs, which", "would reject a not-yet-existing ATA). The router CPI re-validates", "`token::mint = source_mint, token::authority = payer` on this account."];
             readonly writable: true;
         }, {
             readonly name: "destination_token_account";
-            readonly docs: readonly ["DESTINATION token account (receives the swap output)"];
+            readonly docs: readonly ["DESTINATION token account (receives the swap output).", "M2: authority must be `payer` so output cannot be routed to an arbitrary", "same-mint account — enforced by the ROUTER's account constraints."];
             readonly writable: true;
         }, {
             readonly name: "source_mint";
@@ -106,10 +123,10 @@ export declare const TENANT_WRAPPER_IDL: {
             readonly name: "destination_mint";
         }, {
             readonly name: "global_cfg";
-            readonly docs: readonly ["Global config (router PDA)"];
+            readonly docs: readonly ["Global config (router PDA; owner/discriminator checked here, PDA seeds", "re-validated by the router). Typed so the wrapper can read the 0Block", "fee bps for exact wSOL fee-headroom sizing."];
         }, {
             readonly name: "tenant_cfg";
-            readonly docs: readonly ["Tenant config (router PDA)"];
+            readonly docs: readonly ["Tenant config (router PDA; owner/discriminator checked here, PDA seeds", "re-validated by the router)."];
         }, {
             readonly name: "zeroblock_sol_vault";
             readonly docs: readonly ["0BLOCK fee authority (owns 0BLOCK fee token accounts)"];
@@ -138,7 +155,7 @@ export declare const TENANT_WRAPPER_IDL: {
             readonly address: "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
         }, {
             readonly name: "system_program";
-            readonly optional: true;
+            readonly docs: readonly ["REQUIRED (was optional): the `order_marker` `init` needs the System", "program, and it is also forwarded to the router for fee-ATA creation."];
             readonly address: "11111111111111111111111111111111";
         }, {
             readonly name: "ix_sysvar";
@@ -158,6 +175,15 @@ export declare const TENANT_WRAPPER_IDL: {
         }];
     }];
     readonly accounts: readonly [{
+        readonly name: "GlobalConfig";
+        readonly discriminator: readonly [149, 8, 156, 202, 160, 252, 176, 217];
+    }, {
+        readonly name: "OrderMarker";
+        readonly discriminator: readonly [221, 221, 169, 152, 245, 69, 110, 108];
+    }, {
+        readonly name: "TenantConfig";
+        readonly discriminator: readonly [195, 252, 97, 104, 160, 30, 231, 112];
+    }, {
         readonly name: "TenantWrapperConfig";
         readonly discriminator: readonly [221, 67, 69, 41, 128, 45, 34, 31];
     }];
@@ -169,6 +195,26 @@ export declare const TENANT_WRAPPER_IDL: {
         readonly code: 6001;
         readonly name: "InvalidAdmin";
         readonly msg: "Admin cannot be the default pubkey";
+    }, {
+        readonly code: 6002;
+        readonly name: "ZeroOrderId";
+        readonly msg: "order_id must be non-zero";
+    }, {
+        readonly code: 6003;
+        readonly name: "MissingTokenProgram";
+        readonly msg: "token program account is required for native-SOL handling";
+    }, {
+        readonly code: 6004;
+        readonly name: "MissingAssociatedTokenProgram";
+        readonly msg: "associated token program account is required for native-SOL handling";
+    }, {
+        readonly code: 6005;
+        readonly name: "AmountOverflow";
+        readonly msg: "amount_in plus fees overflows u64";
+    }, {
+        readonly code: 6006;
+        readonly name: "InvalidTokenAccount";
+        readonly msg: "account is not a valid SPL token account";
     }];
     readonly types: readonly [{
         readonly name: "Dex";
@@ -307,6 +353,81 @@ export declare const TENANT_WRAPPER_IDL: {
                 readonly name: "SolRfq";
             }];
         };
+    }, {
+        readonly name: "GlobalConfig";
+        readonly serialization: "bytemuckunsafe";
+        readonly repr: {
+            readonly kind: "c";
+        };
+        readonly type: {
+            readonly kind: "struct";
+            readonly fields: readonly [{
+                readonly name: "bump";
+                readonly docs: readonly ["PDA bump"];
+                readonly type: "u8";
+            }, {
+                readonly name: "admin";
+                readonly docs: readonly ["Program admin (controls global/tenant settings)"];
+                readonly type: "pubkey";
+            }, {
+                readonly name: "zeroblock_fee_bps";
+                readonly docs: readonly ["0BLOCK platform fee default (bps out of 10_000)"];
+                readonly type: "u16";
+            }, {
+                readonly name: "zeroblock_fee_vault";
+                readonly docs: readonly ["Fee authority that owns 0BLOCK fee token accounts"];
+                readonly type: "pubkey";
+            }, {
+                readonly name: "paused";
+                readonly docs: readonly ["A2 (remediation-2026-07-02): global instant-halt switch. `0` = not", "paused (default; matches the zeroed tail of every already-deployed", "account), `1` = paused. Plain `u8` rather than `bool` — zero_copy/Pod", "requires every byte pattern to be valid, which `bool` does not", "guarantee. Use `is_paused()`/`set_paused()`, never the raw field."];
+                readonly type: "u8";
+            }, {
+                readonly name: "spl_token_swap_allowlist";
+                readonly docs: readonly ["A1 (remediation-2026-07-02): admin-provisioned CPI-target allowlist", "for the `SplTokenSwap` (Dex=0) adapter — the router invokes", "`swap_accounts.dex_program_id` with the `0block_sa` PDA as signer on", "hop ≥ 1, so an unconstrained target is a confused-deputy sweep of any", "PDA-held funds. Unlike the other ~60 adapters this venue has no", "single hardcoded upstream program id (multiple live forks share the", "same instruction interface), so the allowed set is admin-configured", "instead of a compile-time const. Unset slots are `Pubkey::default()`", "and never match; an all-default allowlist rejects every CPI (fail", "closed) until an admin provisions it via `set_spl_token_swap_allowlist`", "(see `// TODO(remediation-2026-07-02):` in `adapters/spl_token_swap.rs`", "— provisioning real venue ids is a deploy-config/operator action, out", "of scope for this remediation pass, same as the plan's other", "\"provisioning\" items)."];
+                readonly type: {
+                    readonly array: readonly ["pubkey", 2];
+                };
+            }, {
+                readonly name: "stable_swap_allowlist";
+                readonly docs: readonly ["A1 (remediation-2026-07-02): same contract as", "`spl_token_swap_allowlist`, for the `StableSwap` (Dex=1) adapter."];
+                readonly type: {
+                    readonly array: readonly ["pubkey", 2];
+                };
+            }, {
+                readonly name: "padding";
+                readonly docs: readonly ["Reserved to keep struct size stable for future upgrades. Shrunk from", "the original 160 bytes by exactly the width of the fields above (see", "`REMAINING_PADDING_BYTES`) so total account size is unchanged."];
+                readonly type: {
+                    readonly array: readonly ["u8", 31];
+                };
+            }];
+        };
+    }, {
+        readonly name: "OrderMarker";
+        readonly docs: readonly ["Per-order replay marker (R-6 / H1). Audit-only fields — the account's", "EXISTENCE under seeds `[b\"order\", payer, order_id_le]` IS the dedup signal."];
+        readonly type: {
+            readonly kind: "struct";
+            readonly fields: readonly [{
+                readonly name: "order_id";
+                readonly docs: readonly ["The server-authoritative business order id this marker pins."];
+                readonly type: "u128";
+            }, {
+                readonly name: "authority";
+                readonly docs: readonly ["The payer namespace this marker was created under (== `payer`)."];
+                readonly type: "pubkey";
+            }, {
+                readonly name: "slot";
+                readonly docs: readonly ["Slot at creation (forensics only)."];
+                readonly type: "u64";
+            }, {
+                readonly name: "unix_timestamp";
+                readonly docs: readonly ["Unix timestamp at creation (forensics only)."];
+                readonly type: "i64";
+            }, {
+                readonly name: "bump";
+                readonly docs: readonly ["PDA bump."];
+                readonly type: "u8";
+            }];
+        };
     }, {
         readonly name: "Route";
         readonly type: {
@@ -395,6 +516,46 @@ export declare const TENANT_WRAPPER_IDL: {
                 };
             }];
         };
+    }, {
+        readonly name: "TenantConfig";
+        readonly docs: readonly ["----------------------------------------------------------------------------", "TenantConfig (+ strict wrapper enforcement)", "----------------------------------------------------------------------------"];
+        readonly type: {
+            readonly kind: "struct";
+            readonly fields: readonly [{
+                readonly name: "bump";
+                readonly type: "u8";
+            }, {
+                readonly name: "tenant_authority";
+                readonly docs: readonly ["Signer (EOA or PDA) authorized to act for this tenant"];
+                readonly type: "pubkey";
+            }, {
+                readonly name: "tenant_wrapper_program";
+                readonly docs: readonly ["Wrapper program id used to validate tenant-mode calls."];
+                readonly type: "pubkey";
+            }, {
+                readonly name: "zeroblock_fee_bps";
+                readonly docs: readonly ["0BLOCK fee (bps out of 10_000) for this tenant. Use 0 to fall back to global default."];
+                readonly type: "u16";
+            }, {
+                readonly name: "tenant_fee_vault";
+                readonly docs: readonly ["Fee authority that owns tenant fee token accounts"];
+                readonly type: "pubkey";
+            }, {
+                readonly name: "whitelisted";
+                readonly docs: readonly ["Whether this tenant is active/whitelisted"];
+                readonly type: "bool";
+            }, {
+                readonly name: "max_total_fee_bps";
+                readonly docs: readonly ["Optional per-tenant cap: (tenant_fee_bps + zeroblock_fee_bps) must be <= this if > 0.", "tenant_fee_bps is supplied per swap."];
+                readonly type: "u16";
+            }, {
+                readonly name: "_reserved";
+                readonly docs: readonly ["Reserved for upgrades (fixed size)"];
+                readonly type: {
+                    readonly array: readonly ["u8", 64];
+                };
+            }];
+        };
     }, {
         readonly name: "TenantWrapperConfig";
         readonly type: {

package/dist/idl/tenantWrapper.js

@@ -1,7 +1,9 @@
 // Vendored from the tenant-wrapper build of nyx-solana-dex-router (target/idl/zeroblock_tenant_wrapper.json).
 // The instruction layout is identical for every tenant wrapper deployment; the program
 // address is per-tenant and intentionally stripped — pass wrapperProgramId at init.
-// tenant_authority is not an account: the wrapper_config PDA signs the router CPI.
+// swap: order_marker replay gate (server-authoritative non-zero order_id); the
+// wrapper_config PDA signs the router CPI; native-SOL wrap/fee-headroom/unwrap/
+// ATA-cleanup are PROGRAM-MANAGED — clients add no wSOL instructions.
 export const TENANT_WRAPPER_IDL = {
     "address": "11111111111111111111111111111111",
     "metadata": {
@@ -201,6 +203,30 @@ export const TENANT_WRAPPER_IDL = {
         },
         {
             "name": "swap",
+            "docs": [
+                "Tenant swap with a hard, exactly-once-SUCCESS replay gate (R-6 / H1).",
+                "",
+                "The `order_marker` account is created with Anchor `init` (NOT",
+                "`init_if_needed`) ATOMICALLY in this same instruction, BEFORE the router",
+                "CPI runs. A second instruction with the same `(payer, order_id)` fails at",
+                "`create_account` (\"account already in use\") and reverts the WHOLE",
+                "instruction — including the router CPI — so a duplicate business order can",
+                "never execute (and never pays fees) twice.",
+                "",
+                "INVARIANTS (off-chain encoder MUST uphold):",
+                "- `order_id` is SERVER-AUTHORITATIVE. It is minted by the backend per",
+                "business order and is NEVER a client-supplied value. A client that could",
+                "choose `order_id` could grief a victim only inside its own `payer`",
+                "namespace (see namespacing note below), but a server-authoritative id",
+                "also guarantees that all per-gate provider-variants (0block / Jito /",
+                "Helius / ...) of ONE business order reuse the SAME `(payer, order_id)`,",
+                "so at most one variant can ever succeed.",
+                "- On land-but-revert (the tx is included on-chain but the instruction",
+                "reverts for any reason), the `init` is rolled back: the marker does NOT",
+                "persist, the `order_id` is reclaimable, and the order may be retried with",
+                "a FRESH durable nonce. (Durable-nonce dedup is at-most-one-LAND; this",
+                "marker is exactly-once-SUCCESS — complementary, not redundant.)"
+            ],
             "discriminator": [
                 248,
                 198,
@@ -253,6 +279,48 @@ export const TENANT_WRAPPER_IDL = {
                         ]
                     }
                 },
+                {
+                    "name": "order_marker",
+                    "docs": [
+                        "Per-order replay marker (R-6 / H1). `init` (NOT `init_if_needed`) makes a",
+                        "duplicate `(payer, order_id)` fail at `create_account` → the whole",
+                        "instruction (router CPI included) reverts.",
+                        "",
+                        "Namespaced by `payer` for griefing isolation: a third party can only ever",
+                        "init markers inside its OWN payer namespace, so it cannot pre-burn another",
+                        "user's `order_id`.",
+                        "",
+                        "ALTERNATIVE NAMESPACING: keying by `tenant_authority` instead of `payer`",
+                        "would dedup per business tenant (so the same logical order is unique across",
+                        "all of a tenant's relayer payers). We choose `payer` here because the RAX",
+                        "flow has one user-payer per order and `payer`-namespacing gives the",
+                        "strongest third-party griefing isolation; revisit if a single business",
+                        "order can legitimately arrive under multiple distinct payers."
+                    ],
+                    "writable": true,
+                    "pda": {
+                        "seeds": [
+                            {
+                                "kind": "const",
+                                "value": [
+                                    111,
+                                    114,
+                                    100,
+                                    101,
+                                    114
+                                ]
+                            },
+                            {
+                                "kind": "account",
+                                "path": "payer"
+                            },
+                            {
+                                "kind": "arg",
+                                "path": "order_id"
+                            }
+                        ]
+                    }
+                },
                 {
                     "name": "router_program",
                     "docs": [
@@ -263,14 +331,19 @@ export const TENANT_WRAPPER_IDL = {
                 {
                     "name": "source_token_account",
                     "docs": [
-                        "SOURCE token account (authority = payer)"
+                        "SOURCE token account (authority = payer).",
+                        "buys (Anchor deserializes typed accounts before the handler runs, which",
+                        "would reject a not-yet-existing ATA). The router CPI re-validates",
+                        "`token::mint = source_mint, token::authority = payer` on this account."
                     ],
                     "writable": true
                 },
                 {
                     "name": "destination_token_account",
                     "docs": [
-                        "DESTINATION token account (receives the swap output)"
+                        "DESTINATION token account (receives the swap output).",
+                        "M2: authority must be `payer` so output cannot be routed to an arbitrary",
+                        "same-mint account — enforced by the ROUTER's account constraints."
                     ],
                     "writable": true
                 },
@@ -283,13 +356,16 @@ export const TENANT_WRAPPER_IDL = {
                 {
                     "name": "global_cfg",
                     "docs": [
-                        "Global config (router PDA)"
+                        "Global config (router PDA; owner/discriminator checked here, PDA seeds",
+                        "re-validated by the router). Typed so the wrapper can read the 0Block",
+                        "fee bps for exact wSOL fee-headroom sizing."
                     ]
                 },
                 {
                     "name": "tenant_cfg",
                     "docs": [
-                        "Tenant config (router PDA)"
+                        "Tenant config (router PDA; owner/discriminator checked here, PDA seeds",
+                        "re-validated by the router)."
                     ]
                 },
                 {
@@ -335,7 +411,10 @@ export const TENANT_WRAPPER_IDL = {
                 },
                 {
                     "name": "system_program",
-                    "optional": true,
+                    "docs": [
+                        "REQUIRED (was optional): the `order_marker` `init` needs the System",
+                        "program, and it is also forwarded to the router for fee-ATA creation."
+                    ],
                     "address": "11111111111111111111111111111111"
                 },
                 {
@@ -363,6 +442,45 @@ export const TENANT_WRAPPER_IDL = {
         }
     ],
     "accounts": [
+        {
+            "name": "GlobalConfig",
+            "discriminator": [
+                149,
+                8,
+                156,
+                202,
+                160,
+                252,
+                176,
+                217
+            ]
+        },
+        {
+            "name": "OrderMarker",
+            "discriminator": [
+                221,
+                221,
+                169,
+                152,
+                245,
+                69,
+                110,
+                108
+            ]
+        },
+        {
+            "name": "TenantConfig",
+            "discriminator": [
+                195,
+                252,
+                97,
+                104,
+                160,
+                30,
+                231,
+                112
+            ]
+        },
         {
             "name": "TenantWrapperConfig",
             "discriminator": [
@@ -387,6 +505,31 @@ export const TENANT_WRAPPER_IDL = {
             "code": 6001,
             "name": "InvalidAdmin",
             "msg": "Admin cannot be the default pubkey"
+        },
+        {
+            "code": 6002,
+            "name": "ZeroOrderId",
+            "msg": "order_id must be non-zero"
+        },
+        {
+            "code": 6003,
+            "name": "MissingTokenProgram",
+            "msg": "token program account is required for native-SOL handling"
+        },
+        {
+            "code": 6004,
+            "name": "MissingAssociatedTokenProgram",
+            "msg": "associated token program account is required for native-SOL handling"
+        },
+        {
+            "code": 6005,
+            "name": "AmountOverflow",
+            "msg": "amount_in plus fees overflows u64"
+        },
+        {
+            "code": 6006,
+            "name": "InvalidTokenAccount",
+            "msg": "account is not a valid SPL token account"
         }
     ],
     "types": [
@@ -596,6 +739,156 @@ export const TENANT_WRAPPER_IDL = {
                 ]
             }
         },
+        {
+            "name": "GlobalConfig",
+            "serialization": "bytemuckunsafe",
+            "repr": {
+                "kind": "c"
+            },
+            "type": {
+                "kind": "struct",
+                "fields": [
+                    {
+                        "name": "bump",
+                        "docs": [
+                            "PDA bump"
+                        ],
+                        "type": "u8"
+                    },
+                    {
+                        "name": "admin",
+                        "docs": [
+                            "Program admin (controls global/tenant settings)"
+                        ],
+                        "type": "pubkey"
+                    },
+                    {
+                        "name": "zeroblock_fee_bps",
+                        "docs": [
+                            "0BLOCK platform fee default (bps out of 10_000)"
+                        ],
+                        "type": "u16"
+                    },
+                    {
+                        "name": "zeroblock_fee_vault",
+                        "docs": [
+                            "Fee authority that owns 0BLOCK fee token accounts"
+                        ],
+                        "type": "pubkey"
+                    },
+                    {
+                        "name": "paused",
+                        "docs": [
+                            "A2 (remediation-2026-07-02): global instant-halt switch. `0` = not",
+                            "paused (default; matches the zeroed tail of every already-deployed",
+                            "account), `1` = paused. Plain `u8` rather than `bool` — zero_copy/Pod",
+                            "requires every byte pattern to be valid, which `bool` does not",
+                            "guarantee. Use `is_paused()`/`set_paused()`, never the raw field."
+                        ],
+                        "type": "u8"
+                    },
+                    {
+                        "name": "spl_token_swap_allowlist",
+                        "docs": [
+                            "A1 (remediation-2026-07-02): admin-provisioned CPI-target allowlist",
+                            "for the `SplTokenSwap` (Dex=0) adapter — the router invokes",
+                            "`swap_accounts.dex_program_id` with the `0block_sa` PDA as signer on",
+                            "hop ≥ 1, so an unconstrained target is a confused-deputy sweep of any",
+                            "PDA-held funds. Unlike the other ~60 adapters this venue has no",
+                            "single hardcoded upstream program id (multiple live forks share the",
+                            "same instruction interface), so the allowed set is admin-configured",
+                            "instead of a compile-time const. Unset slots are `Pubkey::default()`",
+                            "and never match; an all-default allowlist rejects every CPI (fail",
+                            "closed) until an admin provisions it via `set_spl_token_swap_allowlist`",
+                            "(see `// TODO(remediation-2026-07-02):` in `adapters/spl_token_swap.rs`",
+                            "— provisioning real venue ids is a deploy-config/operator action, out",
+                            "of scope for this remediation pass, same as the plan's other",
+                            "\"provisioning\" items)."
+                        ],
+                        "type": {
+                            "array": [
+                                "pubkey",
+                                2
+                            ]
+                        }
+                    },
+                    {
+                        "name": "stable_swap_allowlist",
+                        "docs": [
+                            "A1 (remediation-2026-07-02): same contract as",
+                            "`spl_token_swap_allowlist`, for the `StableSwap` (Dex=1) adapter."
+                        ],
+                        "type": {
+                            "array": [
+                                "pubkey",
+                                2
+                            ]
+                        }
+                    },
+                    {
+                        "name": "padding",
+                        "docs": [
+                            "Reserved to keep struct size stable for future upgrades. Shrunk from",
+                            "the original 160 bytes by exactly the width of the fields above (see",
+                            "`REMAINING_PADDING_BYTES`) so total account size is unchanged."
+                        ],
+                        "type": {
+                            "array": [
+                                "u8",
+                                31
+                            ]
+                        }
+                    }
+                ]
+            }
+        },
+        {
+            "name": "OrderMarker",
+            "docs": [
+                "Per-order replay marker (R-6 / H1). Audit-only fields — the account's",
+                "EXISTENCE under seeds `[b\"order\", payer, order_id_le]` IS the dedup signal."
+            ],
+            "type": {
+                "kind": "struct",
+                "fields": [
+                    {
+                        "name": "order_id",
+                        "docs": [
+                            "The server-authoritative business order id this marker pins."
+                        ],
+                        "type": "u128"
+                    },
+                    {
+                        "name": "authority",
+                        "docs": [
+                            "The payer namespace this marker was created under (== `payer`)."
+                        ],
+                        "type": "pubkey"
+                    },
+                    {
+                        "name": "slot",
+                        "docs": [
+                            "Slot at creation (forensics only)."
+                        ],
+                        "type": "u64"
+                    },
+                    {
+                        "name": "unix_timestamp",
+                        "docs": [
+                            "Unix timestamp at creation (forensics only)."
+                        ],
+                        "type": "i64"
+                    },
+                    {
+                        "name": "bump",
+                        "docs": [
+                            "PDA bump."
+                        ],
+                        "type": "u8"
+                    }
+                ]
+            }
+        },
         {
             "name": "Route",
             "type": {
@@ -707,6 +1000,78 @@ export const TENANT_WRAPPER_IDL = {
                 ]
             }
         },
+        {
+            "name": "TenantConfig",
+            "docs": [
+                "----------------------------------------------------------------------------",
+                "TenantConfig (+ strict wrapper enforcement)",
+                "----------------------------------------------------------------------------"
+            ],
+            "type": {
+                "kind": "struct",
+                "fields": [
+                    {
+                        "name": "bump",
+                        "type": "u8"
+                    },
+                    {
+                        "name": "tenant_authority",
+                        "docs": [
+                            "Signer (EOA or PDA) authorized to act for this tenant"
+                        ],
+                        "type": "pubkey"
+                    },
+                    {
+                        "name": "tenant_wrapper_program",
+                        "docs": [
+                            "Wrapper program id used to validate tenant-mode calls."
+                        ],
+                        "type": "pubkey"
+                    },
+                    {
+                        "name": "zeroblock_fee_bps",
+                        "docs": [
+                            "0BLOCK fee (bps out of 10_000) for this tenant. Use 0 to fall back to global default."
+                        ],
+                        "type": "u16"
+                    },
+                    {
+                        "name": "tenant_fee_vault",
+                        "docs": [
+                            "Fee authority that owns tenant fee token accounts"
+                        ],
+                        "type": "pubkey"
+                    },
+                    {
+                        "name": "whitelisted",
+                        "docs": [
+                            "Whether this tenant is active/whitelisted"
+                        ],
+                        "type": "bool"
+                    },
+                    {
+                        "name": "max_total_fee_bps",
+                        "docs": [
+                            "Optional per-tenant cap: (tenant_fee_bps + zeroblock_fee_bps) must be <= this if > 0.",
+                            "tenant_fee_bps is supplied per swap."
+                        ],
+                        "type": "u16"
+                    },
+                    {
+                        "name": "_reserved",
+                        "docs": [
+                            "Reserved for upgrades (fixed size)"
+                        ],
+                        "type": {
+                            "array": [
+                                "u8",
+                                64
+                            ]
+                        }
+                    }
+                ]
+            }
+        },
         {
             "name": "TenantWrapperConfig",
             "type": {

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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 { buildSendTransactionRequest, createLandingClient, withLandingTip, type LandingClient, type LandingServiceConfig, type SendTransactionOptions, } from "./landing.js";
+export { toPk, deriveAta, deriveOrderMarker, 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";

package/dist/index.js

@@ -1,18 +1,21 @@
-// @0block/sdk — browser-first transaction builder for the 0Block DEX router.
+// @0block.io/sdk — SDK for 0Block's two independent products:
 //
-// 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.
+//   1. DEX SMART ROUTER — build swap transactions (tenant-wrapped or direct).
+//      createContext, applyPreset, buildPumpfunSwapTransaction,
+//      resolvePumpfunMarketContext, ALT helpers, decodeSwapResultEvents.
 //
-// Split of responsibilities:
-//   server-side (near an RPC):  resolvePumpfunMarketContext, buildLookupTableAddresses,
-//                               buildInitLookupTableInstructions
-//   client-side (fully offline): createContext, applyPreset, buildPumpfunSwapTransaction
-//   indexer-side:                decodeSwapResultEvents
+//   2. LANDING SERVICE — land ANY fully-signed Solana transaction (tip-gated
+//      submission to staked infra + leader TPUs). createLandingClient,
+//      withLandingTip, buildTipInstruction, maskTipAccountInTables.
+//
+// Neither depends on the other: router transactions can be submitted through
+// any RPC, and the landing service accepts any transaction. They compose
+// naturally when used together.
 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 { buildSendTransactionRequest, createLandingClient, withLandingTip, } from "./landing.js";
+export { toPk, deriveAta, deriveOrderMarker, 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";

package/dist/landing.d.ts

@@ -0,0 +1,66 @@
+import * as web3 from "@solana/web3.js";
+import type { Address, TipParams } from "./types.js";
+/**
+ * 0Block Landing service — a standalone product, independent of the DEX
+ * router. It lands ANY fully-signed Solana transaction: JSON-RPC
+ * `sendTransaction` gated by a tip transfer, forwarded to staked
+ * infrastructure and current/next leader TPUs.
+ *
+ * Contract (independent of what the transaction does):
+ *  - include a SystemProgram transfer ≥ the minimum tip to an allowlisted tip
+ *    account, kept as a STATIC message key (never behind an address lookup
+ *    table — the service verifies raw bytes; see maskTipAccountInTables),
+ *  - use a FINALIZED blockhash (the service submits via different nodes than
+ *    the one you read from),
+ *  - confirm by polling: the service does not serve websockets.
+ */
+export interface LandingServiceConfig {
+    /** Landing service endpoint, e.g. "https://gateway.0block.io". */
+    url: string;
+    /** API key, sent as X-API-Key. */
+    apiKey?: string;
+    /** Injectable fetch (testing / non-standard runtimes). Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export interface SendTransactionOptions {
+    /**
+     * Skip the upstream's preflight simulation (default true — the low-latency
+     * path; a still-propagating blockhash can fail simulation spuriously).
+     */
+    skipPreflight?: boolean;
+}
+/** The exact HTTP request the Landing service expects (pure; useful for tests and custom transports). */
+export declare function buildSendTransactionRequest(config: Pick<LandingServiceConfig, "url" | "apiKey">, wireTransaction: Uint8Array, options?: SendTransactionOptions): {
+    url: string;
+    method: "POST";
+    headers: Record<string, string>;
+    body: string;
+};
+/**
+ * Prepend the landing tip to an instruction list for ANY transaction (router
+ * swap or otherwise). The swap builder does this internally when given `tip`;
+ * use this for arbitrary transactions you land through the service.
+ */
+export declare function withLandingTip(instructions: web3.TransactionInstruction[], payer: Address, tip: TipParams | {
+    account: Address;
+    lamports?: bigint;
+}): web3.TransactionInstruction[];
+export interface LandingClient {
+    /** Submit wire bytes (fully signed). Resolves to the transaction signature (submission ack, NOT confirmation). */
+    sendTransaction(wireTransaction: Uint8Array, options?: SendTransactionOptions): Promise<string>;
+    /**
+     * Submit, then poll the given read connection until the signature confirms,
+     * errors, or the blockhash lapses. The read RPC is separate from the
+     * landing endpoint by design.
+     */
+    submitAndConfirm(wireTransaction: Uint8Array, readConnection: web3.Connection, params: {
+        lastValidBlockHeight: number;
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }, options?: SendTransactionOptions): Promise<{
+        signature: string;
+        slot: number;
+    }>;
+}
+/** Client for the Landing service. Usable with or without the DEX router. */
+export declare function createLandingClient(config: LandingServiceConfig): LandingClient;

package/dist/landing.js

@@ -0,0 +1,78 @@
+import { DEFAULT_TIP_LAMPORTS } from "./constants.js";
+import { buildTipInstruction } from "./tip.js";
+import { toPk } from "./pda.js";
+/** The exact HTTP request the Landing service expects (pure; useful for tests and custom transports). */
+export function buildSendTransactionRequest(config, wireTransaction, options) {
+    const headers = { "Content-Type": "application/json" };
+    if (config.apiKey)
+        headers["X-API-Key"] = config.apiKey;
+    return {
+        url: config.url,
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "sendTransaction",
+            params: [
+                Buffer.from(wireTransaction).toString("base64"),
+                { encoding: "base64", skipPreflight: options?.skipPreflight ?? true },
+            ],
+        }),
+    };
+}
+/**
+ * Prepend the landing tip to an instruction list for ANY transaction (router
+ * swap or otherwise). The swap builder does this internally when given `tip`;
+ * use this for arbitrary transactions you land through the service.
+ */
+export function withLandingTip(instructions, payer, tip) {
+    const lamports = tip.lamports ?? DEFAULT_TIP_LAMPORTS;
+    return [
+        buildTipInstruction(toPk(payer), { account: tip.account, lamports }),
+        ...instructions,
+    ];
+}
+/** Client for the Landing service. Usable with or without the DEX router. */
+export function createLandingClient(config) {
+    const fetchImpl = config.fetchImpl ?? fetch;
+    async function sendTransaction(wireTransaction, options) {
+        const req = buildSendTransactionRequest(config, wireTransaction, options);
+        const res = await fetchImpl(req.url, {
+            method: req.method,
+            headers: req.headers,
+            body: req.body,
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (body.error) {
+            throw new Error(`landing service rejected the transaction (HTTP ${res.status}): ${JSON.stringify(body.error)}`);
+        }
+        if (!body.result) {
+            throw new Error(`unexpected landing service response (HTTP ${res.status}): ${JSON.stringify(body)}`);
+        }
+        return body.result;
+    }
+    async function submitAndConfirm(wireTransaction, readConnection, params, options) {
+        const signature = await sendTransaction(wireTransaction, options);
+        const timeoutMs = params.timeoutMs ?? 90_000;
+        const pollIntervalMs = params.pollIntervalMs ?? 1_000;
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const { value } = await readConnection.getSignatureStatuses([signature]);
+            const status = value?.[0];
+            if (status &&
+                (status.confirmationStatus === "confirmed" || status.confirmationStatus === "finalized")) {
+                if (status.err) {
+                    throw new Error(`transaction landed but FAILED on-chain: ${JSON.stringify(status.err)} (${signature})`);
+                }
+                return { signature, slot: status.slot };
+            }
+            const height = await readConnection.getBlockHeight("confirmed");
+            if (height > params.lastValidBlockHeight || Date.now() > deadline) {
+                throw new Error(`transaction expired without confirming (${signature})`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        }
+    }
+    return { sendTransaction, submitAndConfirm };
+}

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.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) {

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.2.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"
   }
-}
+}