@0block.io/sdk 0.1.0 → 0.3.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: {