@keelcodes/sdk 2.3.2 → 2.5.0

package/dist/aa/index.d.ts

@@ -7,5 +7,6 @@ export * from './userop';
 export * from './kernel-account';
 export * from './keel-session';
 export * from './x402';
+export * from './x402-solana';
 export * from './x402-session';
 export * from './bundler';

package/dist/aa/index.js

@@ -26,5 +26,6 @@ __exportStar(require("./userop"), exports);
 __exportStar(require("./kernel-account"), exports);
 __exportStar(require("./keel-session"), exports);
 __exportStar(require("./x402"), exports);
+__exportStar(require("./x402-solana"), exports);
 __exportStar(require("./x402-session"), exports);
 __exportStar(require("./bundler"), exports);

package/dist/aa/x402-solana.d.ts

@@ -0,0 +1,99 @@
+import type { X402Accept, X402PaymentRequired, X402ResourceInfo } from './x402';
+/** CAIP-2 Solana network 前缀（如 `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`）。 */
+export declare const SOLANA_NETWORK_PREFIX = "solana:";
+/** Solana x402 签名域分隔标签。 */
+export declare const SOLANA_X402_DOMAIN = "x402-solana-v2";
+/** Solana 原生资产标签（与账本 `asset` 列一致，金额单位为 lamports）。 */
+export declare const SOLANA_X402_ASSET = "sol";
+export interface X402SolanaPaymentPayload {
+    x402Version: 2;
+    resource?: X402ResourceInfo;
+    accepted: X402Accept;
+    payload: {
+        method: string;
+        url: string;
+        /** 重放保护随机串（字符串即可；缺省由 txHash + 时间派生） */
+        salt: string;
+        /** 链上付款交易签名（base58） */
+        txHash: string;
+        /** 付款人公钥（base58） */
+        payer: string;
+    };
+    extensions?: Record<string, unknown>;
+    /** base58(ed25519 signature, 64B) */
+    signature: string;
+}
+/** 链上付款参数：向 `to` 转 `lamports`，原生 SOL。 */
+export interface X402SolanaPayment {
+    to: string;
+    lamports: bigint;
+    asset: typeof SOLANA_X402_ASSET;
+}
+/**
+ * Solana 会话签名器：只需公钥 + 对原始消息签名。
+ * 私钥始终留在客户端（session key / 智能账户），SDK 不接触。
+ */
+export interface X402SolanaSigner {
+    /** base58 公钥（= payload.payer） */
+    publicKey: string;
+    /** 返回 64B 签名：Uint8Array 或 base58 字符串 */
+    signMessage(message: Uint8Array): Promise<Uint8Array | string>;
+}
+export interface PayX402WithSolanaParams {
+    challenge: X402PaymentRequired;
+    /** 不传则自动选第一个 Solana accept */
+    accept?: X402Accept;
+    /** 发起链上转账并返回交易签名（base58） */
+    sendPayment: (payment: X402SolanaPayment) => Promise<{
+        signature: string;
+        payer?: string;
+    }>;
+    signer: X402SolanaSigner;
+    /** 等交易确认（建议传入，避免服务端校验时还查不到） */
+    waitForConfirmation?: (signature: string) => Promise<unknown>;
+    method?: string;
+    url?: string;
+    salt?: string;
+}
+export interface PayX402WithSolanaResult {
+    /** 可直接写入 `PAYMENT-SIGNATURE` 头 */
+    header: string;
+    payload: X402SolanaPaymentPayload;
+    /** 链上付款交易签名（= payload.payload.txHash） */
+    txHash: string;
+    payment: X402SolanaPayment;
+    accept: X402Accept;
+}
+/** base58 编码（仅用于把 64B ed25519 签名转成 wire 形态）。 */
+export declare function encodeBase58(bytes: Uint8Array): string;
+export declare function isSolanaAccept(accept: X402Accept): boolean;
+/** 选 Solana accept：优先 exact；可按 network 精确过滤。 */
+export declare function selectSolanaAccept(challenge: X402PaymentRequired, opts?: {
+    network?: string;
+}): X402Accept;
+/** 按 accept 组装转账参数（原生 SOL）。 */
+export declare function buildSolanaX402Payment(accept: X402Accept): X402SolanaPayment;
+/** 构造待签消息（必须与 payments `buildSolanaPaymentMessage` 逐字节一致）。 */
+export declare function buildSolanaX402Message(payload: X402SolanaPaymentPayload): Uint8Array;
+/** 由链上付款结果构造未签名的 payload。 */
+export declare function buildSolanaX402Payload(args: {
+    challenge: X402PaymentRequired;
+    accepted: X402Accept;
+    txHash: string;
+    payer: string;
+    method?: string;
+    url?: string;
+    salt?: string;
+}): X402SolanaPaymentPayload;
+/**
+ * 用 Solana 会话密钥签 x402 payload，返回 base58 签名。
+ * 写入 `payload.signature` 后即可 base64 成 `PAYMENT-SIGNATURE`。
+ */
+export declare function signX402WithSolanaSession(payload: X402SolanaPaymentPayload, signer: X402SolanaSigner): Promise<string>;
+/** 把已签名的 payload 编码成 `PAYMENT-SIGNATURE` 头。 */
+export declare function encodeSolanaPaymentSignature(payload: X402SolanaPaymentPayload): string;
+/**
+ * 一次完成「链上转账 → 等确认 → x402 凭证签名」。
+ * 转账由调用方注入（可用 aa-relay `/solana/submit` 广播，gas 可垫付）。
+ */
+export declare function payX402WithSolana(params: PayX402WithSolanaParams): Promise<PayX402WithSolanaResult>;

package/dist/aa/x402-solana.js

@@ -0,0 +1,171 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// x402 v2 · Solana（verifyOnly）客户端
+//
+// 结算模型与 EVM 一致：客户端自己广播 SOL 转账，服务端只做「验签 + 链上校验 +
+// 入账」，没有 facilitator `/settle`。
+//
+// 与 payments 服务端（`protocol/x402-v2.ts`）逐字节对齐：
+//   message = ["x402-solana-v2", scheme, network, amount, asset, payTo,
+//              method, url, salt, txHash].join("\n")
+//   header  = base64(JSON({ x402Version, resource, accepted,
+//                 payload:{method,url,salt,txHash,payer}, signature }))
+//
+// EVM 用 EIP-712 把「accepted + payload」绑定到付款人；SVM 没有等价的结构化
+// 签名，改用 ed25519 对上面这条确定性消息签名，payer 由 `payload.payer` 显式给出
+// （ed25519 无法从签名恢复公钥），服务端再用该公钥验签 + 校验链上同址。
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOLANA_X402_ASSET = exports.SOLANA_X402_DOMAIN = exports.SOLANA_NETWORK_PREFIX = void 0;
+exports.encodeBase58 = encodeBase58;
+exports.isSolanaAccept = isSolanaAccept;
+exports.selectSolanaAccept = selectSolanaAccept;
+exports.buildSolanaX402Payment = buildSolanaX402Payment;
+exports.buildSolanaX402Message = buildSolanaX402Message;
+exports.buildSolanaX402Payload = buildSolanaX402Payload;
+exports.signX402WithSolanaSession = signX402WithSolanaSession;
+exports.encodeSolanaPaymentSignature = encodeSolanaPaymentSignature;
+exports.payX402WithSolana = payX402WithSolana;
+const x402_1 = require("./x402");
+/** CAIP-2 Solana network 前缀（如 `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`）。 */
+exports.SOLANA_NETWORK_PREFIX = 'solana:';
+/** Solana x402 签名域分隔标签。 */
+exports.SOLANA_X402_DOMAIN = 'x402-solana-v2';
+/** Solana 原生资产标签（与账本 `asset` 列一致，金额单位为 lamports）。 */
+exports.SOLANA_X402_ASSET = 'sol';
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+/** base58 编码（仅用于把 64B ed25519 签名转成 wire 形态）。 */
+function encodeBase58(bytes) {
+    let zeros = 0;
+    while (zeros < bytes.length && bytes[zeros] === 0)
+        zeros++;
+    const digits = [];
+    for (let i = zeros; i < bytes.length; i++) {
+        let carry = bytes[i];
+        for (let j = 0; j < digits.length; j++) {
+            carry += digits[j] << 8;
+            digits[j] = carry % 58;
+            carry = (carry / 58) | 0;
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = (carry / 58) | 0;
+        }
+    }
+    let out = '1'.repeat(zeros);
+    for (let i = digits.length - 1; i >= 0; i--)
+        out += BASE58_ALPHABET[digits[i]];
+    return out;
+}
+function isSolanaAccept(accept) {
+    return (String(accept.network ?? '').startsWith(exports.SOLANA_NETWORK_PREFIX) &&
+        String(accept.asset ?? '').toLowerCase() === exports.SOLANA_X402_ASSET);
+}
+/** 选 Solana accept：优先 exact；可按 network 精确过滤。 */
+function selectSolanaAccept(challenge, opts = {}) {
+    const matches = challenge.accepts.filter((a) => isSolanaAccept(a) && (opts.network === undefined || a.network === opts.network));
+    const pick = matches.find((a) => a.scheme === 'exact') ?? matches[0];
+    if (!pick)
+        throw new Error('[keel-sdk] no Solana accept in this x402 challenge');
+    return pick;
+}
+/** 按 accept 组装转账参数（原生 SOL）。 */
+function buildSolanaX402Payment(accept) {
+    if (!isSolanaAccept(accept)) {
+        throw new Error(`[keel-sdk] accept is not Solana native: ${accept.network}/${accept.asset}`);
+    }
+    const lamports = BigInt(accept.amount);
+    if (lamports <= 0n)
+        throw new Error('[keel-sdk] x402 amount must be > 0');
+    if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(accept.payTo)) {
+        throw new Error(`[keel-sdk] invalid Solana payTo: ${accept.payTo}`);
+    }
+    return { to: accept.payTo, lamports, asset: exports.SOLANA_X402_ASSET };
+}
+/** 构造待签消息（必须与 payments `buildSolanaPaymentMessage` 逐字节一致）。 */
+function buildSolanaX402Message(payload) {
+    const { accepted } = payload;
+    return new TextEncoder().encode([
+        exports.SOLANA_X402_DOMAIN,
+        accepted.scheme,
+        accepted.network,
+        accepted.amount,
+        accepted.asset,
+        accepted.payTo,
+        payload.payload.method,
+        payload.payload.url,
+        payload.payload.salt,
+        payload.payload.txHash,
+    ].join('\n'));
+}
+/** 由链上付款结果构造未签名的 payload。 */
+function buildSolanaX402Payload(args) {
+    return {
+        x402Version: 2,
+        resource: args.challenge.resource,
+        accepted: args.accepted,
+        payload: {
+            method: args.method ?? 'GET',
+            url: args.url ?? args.challenge.resource?.url ?? '',
+            salt: args.salt ?? `${args.txHash}:${Date.now()}:${Math.random().toString(36).slice(2)}`,
+            txHash: args.txHash,
+            payer: args.payer,
+        },
+        signature: '',
+    };
+}
+/**
+ * 用 Solana 会话密钥签 x402 payload，返回 base58 签名。
+ * 写入 `payload.signature` 后即可 base64 成 `PAYMENT-SIGNATURE`。
+ */
+async function signX402WithSolanaSession(payload, signer) {
+    if (payload.payload.payer !== signer.publicKey) {
+        throw new Error('[keel-sdk] payload.payer does not match the signing publicKey');
+    }
+    const raw = await signer.signMessage(buildSolanaX402Message(payload));
+    const sig = typeof raw === 'string' ? raw : encodeBase58(raw);
+    if (!/^[1-9A-HJ-NP-Za-km-z]{64,88}$/.test(sig)) {
+        throw new Error('[keel-sdk] signMessage must return a 64-byte ed25519 signature');
+    }
+    return sig;
+}
+/** 把已签名的 payload 编码成 `PAYMENT-SIGNATURE` 头。 */
+function encodeSolanaPaymentSignature(payload) {
+    return (0, x402_1.toBase64)(JSON.stringify(payload));
+}
+/**
+ * 一次完成「链上转账 → 等确认 → x402 凭证签名」。
+ * 转账由调用方注入（可用 aa-relay `/solana/submit` 广播，gas 可垫付）。
+ */
+async function payX402WithSolana(params) {
+    const accept = params.accept ?? selectSolanaAccept(params.challenge);
+    const payment = buildSolanaX402Payment(accept);
+    const sent = await params.sendPayment(payment);
+    const txHash = String(sent?.signature ?? '').trim();
+    if (!/^[1-9A-HJ-NP-Za-km-z]{64,88}$/.test(txHash)) {
+        throw new Error(`[keel-sdk] sendPayment must return a base58 tx signature, got ${txHash}`);
+    }
+    const payer = String(sent.payer ?? params.signer.publicKey);
+    if (payer !== params.signer.publicKey) {
+        throw new Error('[keel-sdk] sendPayment payer differs from the x402 signing key');
+    }
+    if (params.waitForConfirmation)
+        await params.waitForConfirmation(txHash);
+    const unsigned = buildSolanaX402Payload({
+        challenge: params.challenge,
+        accepted: accept,
+        txHash,
+        payer,
+        method: params.method,
+        url: params.url,
+        salt: params.salt,
+    });
+    unsigned.signature = await signX402WithSolanaSession(unsigned, params.signer);
+    return {
+        header: encodeSolanaPaymentSignature(unsigned),
+        payload: unsigned,
+        txHash,
+        payment,
+        accept,
+    };
+}

package/dist/http.d.ts

@@ -1,6 +1,6 @@
 import type { KeelConfig } from './types';
 /** SDK 版本（契约 §5，随包版本同步）。 */
-export declare const SDK_VERSION = "2.3.2";
+export declare const SDK_VERSION = "2.5.0";
 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.3.2';
+exports.SDK_VERSION = '2.5.0';
 /**
  * 钱包签名的复用时长（ms）：首次签名后在该窗口内复用，避免每个请求都触发钱包弹窗。
  * 服务端会话 TTL 为 24h，此处取 1h 留足余量。
@@ -88,7 +88,7 @@ class HttpClient {
             return { ...this.headers, ...this.walletToken.headers };
         }
         const timestamp = String(now);
-        const signature = await this.wallet.sign(`InfraX auth: ${timestamp}`);
+        const signature = await this.wallet.sign(`Keel auth: ${timestamp}`);
         const headers = {
             'x-wallet-address': this.wallet.address.toLowerCase(),
             'x-wallet-timestamp': timestamp,

package/dist/wallet/index.d.ts

@@ -1,6 +1,8 @@
 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

@@ -20,6 +20,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __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

@@ -0,0 +1,160 @@
+import type { SolanaSubmitResult } from './solana-execution-types';
+import type { DexInstruction, DexProvider } from './solana-dex-provider';
+/** DEX 报价（只读，不构建交易） */
+export interface SolanaDexQuoteParams {
+    chain: string;
+    inputMint: string;
+    outputMint: string;
+    /** base units（十进制整数） */
+    amount: string | number;
+    slippageBps?: number;
+}
+export interface SolanaDexQuoteResult {
+    chain: string;
+    /** Jupiter 原始报价（字段随聚合器版本变化，按需读取） */
+    quote: Record<string, unknown>;
+    inputMint: string;
+    inAmount: string;
+    outputMint: string;
+    outAmount: string;
+    otherAmountThreshold: string;
+    priceImpactPct: string;
+    slippageBps: number;
+}
+/** `ProgramInteraction` policy 安装入参（`/dex/policy` 与 `/dex/install` 通用） */
+export interface SolanaDexPolicyParams {
+    chain: string;
+    blockhash: string;
+    feePayer: string;
+    creator: string;
+    settingsPda: string;
+    transactionIndex: string | number;
+    /** policy PDA 的 u64 seed（= 调用前链上 `settings.policySeed + 1`） */
+    seed: string | number;
+    /** 作为 policy 唯一签名者的 session key 公钥 */
+    sessionKey: string;
+    rentPayer?: string;
+    accountIndex?: number;
+    /** 缺省 `[1,2,4]`（Initiate | Vote | Execute） */
+    permissions?: number[];
+    spendingLimits?: Array<{
+        mint: string;
+        /** base units（十进制整数） */
+        maxPerPeriod: string | number;
+        period?: number;
+        start?: string | number;
+        expiration?: string | number;
+    }>;
+    /** 缺省 = relay 配置里的 program 白名单（Jupiter + 直连 DEX + 辅助 program） */
+    constraints?: Array<{
+        programId: string;
+        accountConstraints?: Array<{
+            accountIndex: number;
+            pubkeys: string[];
+            owner?: string;
+        }>;
+        dataConstraints?: Array<{
+            offset: string | number;
+            value?: string;
+            operator?: number;
+        }>;
+    }>;
+    memo?: string;
+}
+/** 安装计划中的一步（未签名交易，按 `steps` 顺序签名广播） */
+export interface SolanaDexInstallStep {
+    step: 'createSettingsTransaction' | 'createProposal' | 'approveProposal' | 'executeSettingsTransaction';
+    /** 需要本地签名的公钥（base58） */
+    signers: string[];
+    instructionCount: number;
+    /** base64（v0） */
+    transaction: string;
+}
+export interface SolanaDexInstallResult {
+    chain: string;
+    policyPda: string;
+    /** 四步共用同一个 blockhash；过期未走完需重新调用 */
+    blockhash: string;
+    steps: SolanaDexInstallStep[];
+}
+export interface SolanaDexSwapParams {
+    chain: string;
+    blockhash: string;
+    feePayer: string;
+    /** policy PDA */
+    policy: string;
+    /** smart account（vault）PDA */
+    vaultPda: string;
+    sessionKey: string;
+    inputMint: string;
+    outputMint: string;
+    amount: string | number;
+    accountIndex?: number;
+    numSigners?: number;
+    slippageBps?: number;
+    wrapAndUnwrapSol?: boolean;
+    dynamicComputeUnitLimit?: boolean;
+    /**
+     * 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;
+    inAmount: string;
+    outAmount: string;
+    otherAmountThreshold: string;
+    priceImpactPct: string;
+    slippageBps: number;
+    innerInstructionCount: number;
+    instructionConstraintIndices: number[];
+    addressLookupTables: number;
+    transactionBytes: number;
+    /** 未签名交易（base64 v0）；签名后经 `submit` 广播才会计费 */
+    transaction: string;
+    instructionCount?: number;
+    /** 计费提示：签名后发到该端点，relay 按 fee payer 收固定服务费 */
+    billing?: {
+        endpoint: string;
+        feePayer: string;
+        feeLamports: string;
+    };
+}
+/**
+ * 本地签名回调：入参为未签名交易（base64 v0）与需要签名的公钥，
+ * 返回已签名的 base64 交易。SDK 不内置 Solana 依赖，由调用方用
+ * `@solana/web3.js`（`VersionedTransaction.deserialize` → `sign`）实现。
+ */
+export type SolanaTransactionSigner = (transaction: string, signers: string[]) => Promise<string> | string;
+/** `dexSwapAndSubmit`：一次完成「取未签名交易 → 本地签名 → 经 relay 计费广播」。 */
+export interface SolanaDexSwapAndSubmitParams extends SolanaDexSwapParams {
+    sign: SolanaTransactionSigner;
+    /**
+     * 垫付模式下的扣费主体（客户地址）。fee payer 是平台热钱包时必须给，
+     * relay 会把「固定服务费 + 实际垫付 lamports」扣在该地址账本上。
+     */
+    payer?: string;
+}
+export interface SolanaDexSwapAndSubmitResult extends SolanaDexSwapResult {
+    /** relay `/submit` 的广播回执（计费发生在这里） */
+    submit: SolanaSubmitResult;
+}

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -75,6 +75,11 @@ export interface SolanaRemoveSignerParams {
 export interface SolanaSubmitParams {
     chain: string;
     transaction: string;
+    /**
+     * 垫付模式的扣费主体（客户 base58 地址）。仅当交易 fee payer 是平台热钱包时需要；
+     * relay 会把固定服务费 + 实际垫付 lamports 扣在该地址。
+     */
+    payer?: string;
 }
 /** 构建端点返回的未签名交易（base64）。 */
 export interface SolanaUnsignedTransaction {

package/dist/wallet/wallet-api.d.ts

@@ -3,6 +3,7 @@ import type { KeelEnvelope } from '../types';
 import type { CreateWalletParams, WalletCreated, ImportWalletParams, SignParams, SignResult, SendParams, SendResult, ChainParams, ChainResult, WalletBalanceParams, WalletBalanceResult, SessionCreateParams, SessionCreated, PaymasterInfo, PaymasterVoucherParams, PaymasterVoucher } from './types';
 import type { SolanaDeriveAccountParams, SolanaDerivedAccount, SolanaCreateAccountParams, SolanaInstallPolicyParams, SolanaCreatePolicyTransactionParams, SolanaCreateProposalParams, SolanaApproveProposalParams, SolanaExecutePolicyTransactionParams, SolanaRemovePolicyParams } from './solana-account-types';
 import type { SolanaExecutePolicyPayloadParams, SolanaCloseSettingsParams, SolanaCloseTransactionParams, SolanaExecutePolicyParams, SolanaExecuteParams, SolanaRemoveSignerParams, SolanaSubmitParams, SolanaUnsignedTransaction, SolanaSubmitResult } from './solana-execution-types';
+import type { SolanaDexQuoteParams, SolanaDexQuoteResult, SolanaDexPolicyParams, SolanaDexInstallResult, SolanaDexSwapParams, SolanaDexSwapResult, SolanaDexSwapAndSubmitParams, SolanaDexSwapAndSubmitResult } from './solana-dex-types';
 import type { MpcSendCodeParams, MpcVerifyParams, MpcBalanceParams, MpcSignMessageParams, MpcSignTypedDataParams, MpcSendTransactionParams, MpcContractCallParams, MpcContractWriteParams, MpcGasEstimateParams, MpcRegisterParams, MpcRegisterResult, MpcSolanaSignParams, MpcSolanaSignResult, MpcSolanaSendParams, MpcSolanaSendResult } from './mpc-types';
 export declare class WalletAPI {
     private http;
@@ -171,6 +172,18 @@ export declare class WalletAPI {
             execute: (p: SolanaExecuteParams) => Promise<SolanaUnsignedTransaction>;
             removeSigner: (p: SolanaRemoveSignerParams) => Promise<SolanaUnsignedTransaction>;
             submit: (p: SolanaSubmitParams) => Promise<SolanaSubmitResult>;
+            /** DEX：Jupiter 报价（只读，不构建交易）。 */
+            dexQuote: (p: SolanaDexQuoteParams) => Promise<SolanaDexQuoteResult>;
+            /** DEX：一站式 policy 安装——返回四笔未签名交易，按 `steps` 顺序本地签名广播。 */
+            dexInstallPolicy: (p: SolanaDexPolicyParams) => Promise<SolanaDexInstallResult>;
+            /** DEX：组装 ProgramInteraction swap 交易（未签名；签名后经 `submit` 广播并计费）。 */
+            dexSwap: (p: SolanaDexSwapParams) => Promise<SolanaDexSwapResult>;
+            /**
+             * 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: (p: SolanaDexSwapAndSubmitParams) => Promise<SolanaDexSwapAndSubmitResult>;
         };
     };
     /** MPC（email 分片钱包）子域：canonical `/v1/wallet/mpc/*`。 */

package/dist/wallet/wallet-api.js

@@ -153,6 +153,24 @@ class WalletAPI {
             execute: (p) => this.http.post('/v1/wallet/session/solana/session/execute', p),
             removeSigner: (p) => this.http.post('/v1/wallet/session/solana/session/remove-signer', p),
             submit: (p) => this.http.post('/v1/wallet/session/solana/submit', p),
+            /** DEX：Jupiter 报价（只读，不构建交易）。 */
+            dexQuote: (p) => this.http.post('/v1/wallet/session/solana/dex/quote', p),
+            /** DEX：一站式 policy 安装——返回四笔未签名交易，按 `steps` 顺序本地签名广播。 */
+            dexInstallPolicy: (p) => this.http.post('/v1/wallet/session/solana/dex/install', p),
+            /** DEX：组装 ProgramInteraction swap 交易（未签名；签名后经 `submit` 广播并计费）。 */
+            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, 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, ...(payer ? { payer } : {}) });
+                return { ...built, submit };
+            },
         },
     };
     /** MPC（email 分片钱包）子域：canonical `/v1/wallet/mpc/*`。 */
@@ -184,3 +202,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.3.2",
+  "version": "2.5.0",
   "description": "Keel SDK — unified access to payment / wallet / data / account modules over https://keel.codes",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",