@keelcodes/sdk 2.4.0 → 2.5.1

package/dist/http.d.ts

@@ -1,6 +1,6 @@
 import type { KeelConfig } from './types';
 /** SDK 版本（契约 §5，随包版本同步）。 */
-export declare const SDK_VERSION = "2.4.0";
+export declare const SDK_VERSION = "2.5.1";
 export declare class HttpClient {
     private baseUrl;
     private headers;

package/dist/http.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpClient = exports.SDK_VERSION = void 0;
 const errors_1 = require("./errors");
 /** SDK 版本（契约 §5，随包版本同步）。 */
-exports.SDK_VERSION = '2.4.0';
+exports.SDK_VERSION = '2.5.1';
 /**
  * 钱包签名的复用时长（ms）：首次签名后在该窗口内复用，避免每个请求都触发钱包弹窗。
  * 服务端会话 TTL 为 24h，此处取 1h 留足余量。

package/dist/wallet/index.d.ts

@@ -2,6 +2,7 @@ export * from './types';
 export * from './solana-account-types';
 export * from './solana-execution-types';
 export * from './solana-dex-types';
+export * from './solana-dex-provider';
 export * from './mpc-types';
 export * from './wallet-api';
 export * from '../aa';

package/dist/wallet/index.js

@@ -21,6 +21,7 @@ __exportStar(require("./types"), exports);
 __exportStar(require("./solana-account-types"), exports);
 __exportStar(require("./solana-execution-types"), exports);
 __exportStar(require("./solana-dex-types"), exports);
+__exportStar(require("./solana-dex-provider"), exports);
 __exportStar(require("./mpc-types"), exports);
 __exportStar(require("./wallet-api"), exports);
 __exportStar(require("../aa"), exports);

package/dist/wallet/solana-dex-provider.d.ts

@@ -0,0 +1,56 @@
+import type { SolanaDexQuoteParams } from './solana-dex-types';
+export interface DexInstructionAccount {
+    pubkey: string;
+    isSigner?: boolean;
+    isWritable?: boolean;
+}
+/** 归一化后的单条内层指令（data 为 base64） */
+export interface DexInstruction {
+    programId: string;
+    accounts: DexInstructionAccount[];
+    data: string;
+}
+/** 统一报价（字段口径与 relay `/dex/swap` 的响应一致） */
+export interface DexProviderQuote {
+    inAmount: string;
+    outAmount: string;
+    otherAmountThreshold: string;
+    priceImpactPct: string;
+    slippageBps: number;
+    /** provider 原始响应，供 `swapInstructions` 复用（不会发给 relay） */
+    raw?: unknown;
+}
+export interface DexProviderSwapRequest {
+    inputMint: string;
+    outputMint: string;
+    amount: string | number;
+    slippageBps?: number;
+    /** swap 的 user（= Squads vault PDA） */
+    userPublicKey: string;
+    /** `quote()` 返回的 `raw` */
+    quote?: unknown;
+}
+export interface DexProviderSwap {
+    instructions: DexInstruction[];
+    addressLookupTableAddresses?: string[];
+}
+export interface DexProvider {
+    readonly name: string;
+    quote(req: SolanaDexQuoteParams): Promise<DexProviderQuote>;
+    swapInstructions(req: DexProviderSwapRequest): Promise<DexProviderSwap>;
+}
+export interface JupiterProviderOptions {
+    /** 默认 https://lite-api.jup.ag */
+    baseUrl?: string;
+    /** Jupiter Pro（或自建网关）的 key，非空时作为 `x-api-key` 头 */
+    apiKey?: string;
+    /** 便于测试注入；默认全局 fetch */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Jupiter（含任意 Jupiter 兼容端点）provider。
+ * 只需要 base URL 与可选 key，B 端即可用自己的额度/网关取价取指令。
+ */
+export declare function jupiterProvider(opts?: JupiterProviderOptions): DexProvider;
+/** B 端自定义 provider 的便捷校验：确保 relay 需要的字段齐全。 */
+export declare function assertDexProvider(provider: DexProvider): void;

package/dist/wallet/solana-dex-provider.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jupiterProvider = jupiterProvider;
+exports.assertDexProvider = assertDexProvider;
+/** Jupiter `/swap/v1/swap-instructions` → 有顺序的指令列表（与 relay 内部口径一致）。 */
+function collectJupiterInstructions(body) {
+    const out = [];
+    const push = (ix) => {
+        if (ix && ix.programId)
+            out.push({ programId: ix.programId, accounts: ix.accounts ?? [], data: ix.data });
+    };
+    push(body?.tokenLedgerInstruction);
+    for (const ix of body?.computeBudgetInstructions ?? [])
+        push(ix);
+    for (const ix of body?.setupInstructions ?? [])
+        push(ix);
+    push(body?.swapInstruction);
+    push(body?.cleanupInstruction);
+    for (const ix of body?.otherInstructions ?? [])
+        push(ix);
+    return out;
+}
+/**
+ * Jupiter（含任意 Jupiter 兼容端点）provider。
+ * 只需要 base URL 与可选 key，B 端即可用自己的额度/网关取价取指令。
+ */
+function jupiterProvider(opts = {}) {
+    const baseUrl = (opts.baseUrl ?? 'https://lite-api.jup.ag').replace(/\/+$/, '');
+    const doFetch = opts.fetchImpl ?? fetch;
+    const headers = () => ({
+        'content-type': 'application/json',
+        ...(opts.apiKey ? { 'x-api-key': opts.apiKey } : {}),
+    });
+    async function readJson(res, path) {
+        const text = await res.text();
+        if (!res.ok)
+            throw new Error(`jupiter ${path} failed: HTTP ${res.status} ${text.slice(0, 200)}`);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`jupiter ${path} returned invalid JSON`);
+        }
+    }
+    return {
+        name: 'jupiter',
+        async quote(req) {
+            const qs = new URLSearchParams({
+                inputMint: req.inputMint,
+                outputMint: req.outputMint,
+                amount: String(req.amount),
+                ...(req.slippageBps === undefined ? {} : { slippageBps: String(req.slippageBps) }),
+            });
+            const path = `/swap/v1/quote?${qs.toString()}`;
+            const raw = await readJson(await doFetch(`${baseUrl}${path}`, { headers: headers() }), path);
+            return {
+                inAmount: String(raw.inAmount),
+                outAmount: String(raw.outAmount),
+                otherAmountThreshold: String(raw.otherAmountThreshold ?? ''),
+                priceImpactPct: String(raw.priceImpactPct ?? '0'),
+                slippageBps: Number(raw.slippageBps ?? req.slippageBps ?? 50),
+                raw,
+            };
+        },
+        async swapInstructions(req) {
+            const path = '/swap/v1/swap-instructions';
+            const body = {
+                quoteResponse: req.quote,
+                userPublicKey: req.userPublicKey,
+                wrapAndUnwrapSol: true,
+                dynamicComputeUnitLimit: true,
+            };
+            const raw = await readJson(await doFetch(`${baseUrl}${path}`, {
+                method: 'POST',
+                headers: headers(),
+                body: JSON.stringify(body),
+            }), path);
+            if (raw?.error)
+                throw new Error(`jupiter swap-instructions error: ${String(raw.error)}`);
+            return {
+                instructions: collectJupiterInstructions(raw),
+                addressLookupTableAddresses: Array.isArray(raw?.addressLookupTableAddresses)
+                    ? raw.addressLookupTableAddresses
+                    : [],
+            };
+        },
+    };
+}
+/** B 端自定义 provider 的便捷校验：确保 relay 需要的字段齐全。 */
+function assertDexProvider(provider) {
+    if (!provider || typeof provider.quote !== 'function' || typeof provider.swapInstructions !== 'function') {
+        throw new Error('dexProvider must implement quote() and swapInstructions()');
+    }
+}

package/dist/wallet/solana-dex-types.d.ts

@@ -1,4 +1,5 @@
 import type { SolanaSubmitResult } from './solana-execution-types';
+import type { DexInstruction, DexProvider } from './solana-dex-provider';
 /** DEX 报价（只读，不构建交易） */
 export interface SolanaDexQuoteParams {
     chain: string;
@@ -96,8 +97,26 @@ export interface SolanaDexSwapParams {
     /**
      * policy 创建时 `instructionsConstraints` 的顺序（programId 数组）。
      * 缺省取 relay 配置白名单顺序；链上要求逐条指令都能映射到一条约束。
+     * 使用 `dexProvider`（external 模式）时**必须**给出，relay 以它作为 program 白名单。
      */
     policyPrograms?: string[];
+    /**
+     * 自定义 DEX/聚合器 provider（2026-10-24）。给出时 SDK 先本地取价取指令，
+     * 再以 `provider: 'external'` 交给 relay 组装交易；URL/key 不经过 relay。
+     */
+    dexProvider?: DexProvider;
+    /** external 模式的报价回显（不参与风控/计费）；`dexProvider` 会自动填充 */
+    quote?: {
+        inAmount?: string;
+        outAmount?: string;
+        otherAmountThreshold?: string;
+        priceImpactPct?: string;
+        slippageBps?: number;
+    };
+    /** external 模式的归一化内层指令（`dexProvider` 会自动填充） */
+    swapInstructions?: DexInstruction[];
+    /** external 模式的地址查找表（`dexProvider` 会自动填充） */
+    addressLookupTableAddresses?: string[];
 }
 export interface SolanaDexSwapResult {
     chain: string;
@@ -119,6 +138,15 @@ export interface SolanaDexSwapResult {
         feePayer: string;
         feeLamports: string;
     };
+    /** 同交易扣费信息（费用已在内层指令里；无需账本预付） */
+    fee?: {
+        mint: string;
+        symbol: string;
+        amountAtomic: string;
+        position: 'first' | 'last';
+    };
+    /** 费用凭证（HMAC 绑定本笔交易）；`dexSwapAndSubmit` 会自动转交 `/submit` */
+    feeProof?: string;
 }
 /**
  * 本地签名回调：入参为未签名交易（base64 v0）与需要签名的公钥，
@@ -129,6 +157,11 @@ export type SolanaTransactionSigner = (transaction: string, signers: string[]) =
 /** `dexSwapAndSubmit`：一次完成「取未签名交易 → 本地签名 → 经 relay 计费广播」。 */
 export interface SolanaDexSwapAndSubmitParams extends SolanaDexSwapParams {
     sign: SolanaTransactionSigner;
+    /**
+     * 垫付模式下的扣费主体（客户地址）。fee payer 是平台热钱包时必须给，
+     * relay 会把「固定服务费 + 实际垫付 lamports」扣在该地址账本上。
+     */
+    payer?: string;
 }
 export interface SolanaDexSwapAndSubmitResult extends SolanaDexSwapResult {
     /** relay `/submit` 的广播回执（计费发生在这里） */

package/dist/wallet/solana-execution-types.d.ts

@@ -75,6 +75,16 @@ export interface SolanaRemoveSignerParams {
 export interface SolanaSubmitParams {
     chain: string;
     transaction: string;
+    /**
+     * 垫付模式的扣费主体（客户 base58 地址）。仅当交易 fee payer 是平台热钱包时需要；
+     * relay 会把固定服务费 + 实际垫付 lamports 扣在该地址。
+     */
+    payer?: string;
+    /**
+     * 同交易扣费凭证（`/dex/swap` 响应里的 `feeProof`）。给出且校验通过时，
+     * relay 不再从账本扣服务费（费用已在交易内由智能账户直接支付）。
+     */
+    feeProof?: string;
 }
 /** 构建端点返回的未签名交易（base64）。 */
 export interface SolanaUnsignedTransaction {
@@ -87,4 +97,8 @@ export interface SolanaSubmitResult {
     chain: string;
     signature: string;
     feePayer?: string;
+    /** 同交易扣费：服务费已由智能账户在交易内支付（无账本扣费） */
+    fee?: {
+        mode: 'onchain';
+    };
 }

package/dist/wallet/wallet-api.js

@@ -158,17 +158,23 @@ class WalletAPI {
             /** DEX：一站式 policy 安装——返回四笔未签名交易，按 `steps` 顺序本地签名广播。 */
             dexInstallPolicy: (p) => this.http.post('/v1/wallet/session/solana/dex/install', p),
             /** DEX：组装 ProgramInteraction swap 交易（未签名；签名后经 `submit` 广播并计费）。 */
-            dexSwap: (p) => this.http.post('/v1/wallet/session/solana/dex/swap', p),
+            dexSwap: (p) => buildDexSwapRequest(this.http, p),
             /**
              * DEX：一步完成 swap —— 取未签名交易 → `sign` 回调本地签名 → 经 `/submit` 广播。
              * `sign` 由调用方提供（SDK 不内置 Solana 依赖），例如：
              * `(b64) => { const tx = VersionedTransaction.deserialize(Buffer.from(b64, 'base64')); tx.sign([kp]); return Buffer.from(tx.serialize()).toString('base64') }`
              */
             dexSwapAndSubmit: async (p) => {
-                const { sign, ...swap } = p;
-                const built = await this.http.post('/v1/wallet/session/solana/dex/swap', swap);
+                const { sign, payer, ...swap } = p;
+                const built = await buildDexSwapRequest(this.http, swap);
                 const signed = await sign(built.transaction, [...new Set([swap.feePayer, swap.sessionKey])]);
-                const submit = await this.http.post('/v1/wallet/session/solana/submit', { chain: swap.chain, transaction: signed });
+                const submit = await this.http.post('/v1/wallet/session/solana/submit', {
+                    chain: swap.chain,
+                    transaction: signed,
+                    ...(payer ? { payer } : {}),
+                    // 同交易扣费：把构建时签发的凭证一并交给 /submit，避免账本重复扣费
+                    ...(built.feeProof ? { feeProof: built.feeProof } : {}),
+                });
                 return { ...built, submit };
             },
         },
@@ -202,3 +208,45 @@ class WalletAPI {
     };
 }
 exports.WalletAPI = WalletAPI;
+/**
+ * `/dex/swap` 的请求构造（2026-10-24）：
+ *   - 给了 `dexProvider`：本地取价取指令 → 以 `provider: 'external'` 交给 relay；
+ *   - 只给了 `swapInstructions`（B 端自己取）：直接透传为 external；
+ *   - 都没给：原样发给 relay，由 relay 调内置 Jupiter（默认行为）。
+ */
+async function buildDexSwapRequest(http, p) {
+    const { dexProvider, quote, swapInstructions, addressLookupTableAddresses, ...plain } = p;
+    if (!dexProvider) {
+        const payload = {
+            ...plain,
+            ...(swapInstructions ? { provider: 'external', swapInstructions } : {}),
+            ...(quote ? { quote } : {}),
+            ...(addressLookupTableAddresses?.length ? { addressLookupTableAddresses } : {}),
+        };
+        return http.post('/v1/wallet/session/solana/dex/swap', payload);
+    }
+    const q = await dexProvider.quote(plain);
+    const swap = await dexProvider.swapInstructions({
+        inputMint: String(plain.inputMint),
+        outputMint: String(plain.outputMint),
+        amount: plain.amount,
+        slippageBps: plain.slippageBps,
+        userPublicKey: plain.vaultPda,
+        quote: q.raw,
+    });
+    return http.post('/v1/wallet/session/solana/dex/swap', {
+        ...plain,
+        provider: 'external',
+        quote: {
+            inAmount: q.inAmount,
+            outAmount: q.outAmount,
+            otherAmountThreshold: q.otherAmountThreshold,
+            priceImpactPct: q.priceImpactPct,
+            slippageBps: q.slippageBps,
+        },
+        swapInstructions: swap.instructions,
+        ...(swap.addressLookupTableAddresses?.length
+            ? { addressLookupTableAddresses: swap.addressLookupTableAddresses }
+            : {}),
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keelcodes/sdk",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "description": "Keel SDK — unified access to payment / wallet / data / account modules over https://keel.codes",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",