gavindiaz/sol-trade-sdk

Fork 0

Files

T

0xfnzero 9af86c8397 Update SWQOS submit behavior

2026-06-23 04:32:50 +08:00

15 KiB

Raw Permalink Blame History

📋 交易参数参考手册

本文档提供 Sol Trade SDK 中所有交易参数的完整参考说明。

📋 目录

SimpleBuyParams / SimpleSellParams
TradeBuyParams
TradeSellParams
参数分类
重要说明

SimpleBuyParams / SimpleSellParams

新接入优先使用 SimpleBuyParams 和 SimpleSellParams。这两个结构体描述交易意图，SDK 内部会转换成低层 TradeBuyParams / TradeSellParams。

SimpleBuyParams

参数	类型	必需	说明
`dex_type`	`DexType`	✅	使用哪个协议交易，例如 `DexType::PumpFun`。
`pay_with`	`TradeTokenType`	✅	买入时用什么 quote 支付。钱包实际花原生 SOL 就传 `SOL`。PumpFun V2 的 SOL/WSOL quote 池，如果你想用原生 SOL 结算，也仍然传 `SOL`。
`mint`	`Pubkey`	✅	要买入的 token mint。
`amount`	`BuyAmount`	✅	买入数量语义。选择一个枚举，不再组合多个低层数量字段。
`extension_params`	`DexParamEnum`	✅	协议状态参数，来自 parser/RPC 缓存，例如 `DexParamEnum::PumpFun(PumpFunParams::from_trade(...))`。
`recent_blockhash`	`Hash`	✅，使用 `new` 时	非 nonce 交易使用的 recent blockhash。SDK 不会在热路径临时获取。
`gas_fee_strategy`	`GasFeeStrategy`	✅	CU price/limit 和 relay tip 配置。
`slippage_basis_points`	`Option<u64>`	❌	可选滑点覆盖。`100` 表示 1%。
`account_policy`	`AccountPolicy`	❌	ATA 创建/关闭策略。默认 `Auto`。
`address_lookup_table_accounts`	`Vec<AddressLookupTableAccount>`	❌	可选 ALT 列表。传 1 个元素表示单 ALT，传多个元素表示多 ALT，用于减少交易体积。
`wait_tx_confirmed`	`bool`	❌	是否等链上确认后再返回。默认 `false`。
`wait_for_all_submits`	`bool`	❌	是否等待所有 SWQoS 通道返回并拿到已提交签名；适合 poll-any 确认或外部监控。recent blockhash 多路交易不互斥；durable nonce 多路交易互斥。
`durable_nonce`	`Option<DurableNonceInfo>`	❌	durable nonce 信息。使用 `.durable_nonce(nonce_info)` 或 `SimpleBuyParams::with_durable_nonce(...)` 设置，不要和 `recent_blockhash` 混用。
`simulate`	`bool`	❌	只构建并模拟交易，不提交。默认 `false`。
`grpc_recv_us`	`Option<i64>`	❌	上游收到事件的微秒时间戳，用于延迟追踪。

SimpleSellParams

参数	类型	必需	说明
`dex_type`	`DexType`	✅	使用哪个协议交易，例如 `DexType::PumpFun`。
`receive_as`	`TradeTokenType`	✅	卖出后接收什么 quote。想收原生 SOL 就传 `SOL`。
`mint`	`Pubkey`	✅	要卖出的 token mint。
`amount`	`SellAmount`	✅	卖出数量语义。
`extension_params`	`DexParamEnum`	✅	协议状态参数，来自 parser/RPC 缓存。
`recent_blockhash`	`Hash`	✅，使用 `new` 时	非 nonce 交易使用的 recent blockhash。
`gas_fee_strategy`	`GasFeeStrategy`	✅	CU price/limit 和 relay tip 配置。
`slippage_basis_points`	`Option<u64>`	❌	可选滑点覆盖。`100` 表示 1%。
`account_policy`	`AccountPolicy`	❌	ATA 创建/关闭策略。默认 `Auto`。
`address_lookup_table_accounts`	`Vec<AddressLookupTableAccount>`	❌	可选 ALT 列表。传 1 个元素表示单 ALT，传多个元素表示多 ALT，用于减少交易体积。
`wait_tx_confirmed`	`bool`	❌	是否等链上确认后再返回。默认 `false`。
`wait_for_all_submits`	`bool`	❌	是否等待所有 SWQoS 通道返回并拿到已提交签名；适合 poll-any 确认或外部监控。recent blockhash 多路交易不互斥；durable nonce 多路交易互斥。
`durable_nonce`	`Option<DurableNonceInfo>`	❌	durable nonce 信息。使用 `.durable_nonce(nonce_info)` 或 `SimpleSellParams::with_durable_nonce(...)` 设置，不要和 `recent_blockhash` 混用。
`simulate`	`bool`	❌	只构建并模拟交易，不提交。默认 `false`。
`with_tip`	`bool`	❌	卖出交易是否带 relay tip。默认 `true`，可通过 `.with_tip(false)` 关闭。
`grpc_recv_us`	`Option<i64>`	❌	上游收到事件的微秒时间戳，用于延迟追踪。

数量如何选择

枚举	含义	底层映射
`BuyAmount::ExactInput(amount)`	精确花费指定 quote 数量，滑点保护最小买到 token 数量。	`input_token_amount = amount`，`use_exact_sol_amount = Some(true)`
`BuyAmount::WithMaxInput { quote_amount }`	常规 PumpFun/PumpSwap buy。SDK 估算输出，并把滑点作用在最大 quote 成本上。	`input_token_amount = quote_amount`，`use_exact_sol_amount = Some(false)`
`BuyAmount::ExactOutput { output_amount, max_input_amount }`	精确买到指定 token 数量，并限制最多花多少 quote。	`fixed_output_token_amount = Some(output_amount)`，`input_token_amount = max_input_amount`
`SellAmount::ExactInput(amount)`	精确卖出指定 token 数量，滑点保护最少收到 quote 数量。	`input_token_amount = amount`
`SellAmount::ExactOutput { output_amount, max_input_amount }`	精确收到指定 quote 数量，并限制最多卖出多少 token；取决于 DEX 是否支持。	`fixed_output_token_amount = Some(output_amount)`，`input_token_amount = max_input_amount`

AccountPolicy

枚举	行为	适用场景
`Auto`	SDK 按实际路径创建必要 ATA。买入会创建目标 token ATA；卖出接收非 SOL 时会创建输出 ATA。	普通应用、手动交易工具。
`HotPathMinimal`	交易内不创建/关闭 ATA。	Bot、狙击、套利、对交易体积敏感的路径。
`CreateMissing`	尽量在交易内创建缺失 ATA。	更重视方便，不追求最小交易体积。
`AssumePrepared`	不创建也不关闭 token account，调用方保证都已准备好。	高级确定性流程。

Simple 参数使用 Durable Nonce

fetch_nonce_info 和 DurableNonceInfo 已从 crate root 重新导出：

use sol_trade_sdk::{fetch_nonce_info, SimpleBuyParams};

let nonce_info = fetch_nonce_info(&client.infrastructure.rpc, nonce_account)
    .await
    .expect("nonce account must be initialized");

let buy_params = SimpleBuyParams::new(
    dex_type,
    pay_with,
    mint,
    amount,
    extension_params,
    recent_blockhash,
    gas_fee_strategy,
)
.durable_nonce(nonce_info);

调用 .durable_nonce(...) 会清空 recent_blockhash；nonce 交易会使用 nonce value 作为 transaction blockhash。

TradeBuyParams

TradeBuyParams 是高级低层买入 API。新接入建议优先使用 SimpleBuyParams，只有需要直接控制单个 ATA flag 时再使用它。

基础交易参数

参数	类型	必需	描述
`dex_type`	`DexType`	✅	要使用的交易协议 (PumpFun, PumpSwap, Bonk, RaydiumCpmm, RaydiumAmmV4, MeteoraDammV2)
`input_token_type`	`TradeTokenType`	✅	要使用的输入代币类型 (SOL, WSOL, USD1)
`mint`	`Pubkey`	✅	要购买的代币 mint 公钥
`input_token_amount`	`u64`	✅	要花费的输入代币数量（最小代币单位）
`slippage_basis_points`	`Option<u64>`	❌	滑点容忍度（基点单位，例如 100 = 1%, 500 = 5%）
`recent_blockhash`	`Option<Hash>`	❌	用于交易有效性的最新区块哈希
`extension_params`	`Box<dyn ProtocolParams>`	✅	协议特定参数 (PumpFunParams, PumpSwapParams 等)

高级配置参数

参数	类型	必需	描述
`wait_tx_confirmed`	`bool`	✅	是否等待交易确认
`create_input_token_ata`	`bool`	✅	是否创建输入代币关联代币账户
`close_input_token_ata`	`bool`	✅	交易后是否关闭输入代币 ATA
`create_mint_ata`	`bool`	✅	是否创建代币 mint ATA
`durable_nonce`	`Option<DurableNonceInfo>`	❌	持久 nonce 信息，包含 nonce 账户和当前 nonce 值
`fixed_output_token_amount`	`Option<u64>`	❌	可选的固定输出代币数量。对于支持 exact-out 的 DEX，会使用 exact-out 指令，并将 input_token_amount 作为最大输入预算（Meteora DAMM V2 必需）
`gas_fee_strategy`	`GasFeeStrategy`	✅	Gas fee 策略实例，用于控制交易费用和优先级
`simulate`	`bool`	✅	是否模拟交易而不实际执行。当为 true 时，将通过 RPC 模拟交易以验证并显示详细日志、计算单元消耗和潜在错误，而不会实际提交到区块链

TradeSellParams

TradeSellParams 结构体包含在不同 DEX 协议上执行卖出订单所需的所有参数。

基础交易参数

参数	类型	必需	描述
`dex_type`	`DexType`	✅	要使用的交易协议 (PumpFun, PumpSwap, Bonk, RaydiumCpmm, RaydiumAmmV4, MeteoraDammV2)
`output_token_type`	`TradeTokenType`	✅	要接收的输出代币类型 (SOL, WSOL, USD1)
`mint`	`Pubkey`	✅	要出售的代币 mint 公钥
`input_token_amount`	`u64`	✅	要出售的代币数量（最小代币单位）
`slippage_basis_points`	`Option<u64>`	❌	滑点容忍度（基点单位，例如 100 = 1%, 500 = 5%）
`recent_blockhash`	`Option<Hash>`	❌	用于交易有效性的最新区块哈希
`with_tip`	`bool`	✅	交易中是否包含小费
`extension_params`	`Box<dyn ProtocolParams>`	✅	协议特定参数 (PumpFunParams, PumpSwapParams 等)

高级配置参数

参数	类型	必需	描述
`wait_tx_confirmed`	`bool`	✅	是否等待交易确认
`create_output_token_ata`	`bool`	✅	是否创建输出代币关联代币账户
`close_output_token_ata`	`bool`	✅	交易后是否关闭输出代币 ATA
`durable_nonce`	`Option<DurableNonceInfo>`	❌	持久 nonce 信息，包含 nonce 账户和当前 nonce 值
`gas_fee_strategy`	`GasFeeStrategy`	✅	Gas fee 策略实例，用于控制交易费用和优先级
`fixed_output_token_amount`	`Option<u64>`	❌	可选的固定输出代币数量。对于支持 exact-out 的 DEX，会使用 exact-out 指令，并将 input_token_amount 作为最大输入预算（Meteora DAMM V2 必需）
`simulate`	`bool`	✅	是否模拟交易而不实际执行。当为 true 时，将通过 RPC 模拟交易以验证并显示详细日志、计算单元消耗和潜在错误，而不会实际提交到区块链

参数分类

🎯 核心交易参数

这些参数对于定义基本交易操作至关重要：

dex_type: 确定用于交易的协议
input_token_type (买入) / output_token_type (卖出): 指定基础代币类型 (SOL, WSOL, USD1)
mint: 指定要交易的代币
input_token_amount: 定义交易规模（买入和卖出操作都使用此参数）
recent_blockhash: 确保交易有效性

⚙️ 交易控制参数

这些参数控制交易的处理方式：

slippage_basis_points: 控制可接受的价格滑点
wait_tx_confirmed: 控制是否等待确认

🔧 账户管理参数

这些参数控制自动账户创建和管理：

create_input_token_ata (买入) / create_output_token_ata (卖出): 自动为输入/输出代币创建代币账户
close_input_token_ata (买入) / close_output_token_ata (卖出): 交易后自动关闭代币账户
create_mint_ata: 自动为交易代币创建代币账户

🚀 优化参数

这些参数启用高级优化：

address_lookup_table_accounts: 使用一个或多个地址查找表减少交易大小

🔄 代币类型参数

TradeTokenType 枚举支持以下基础代币：

SOL: Solana 原生代币（通常与 PumpFun 协议一起使用）
WSOL: 包装 SOL 代币（通常与 PumpSwap、Bonk、Raydium 协议一起使用）
USD1: USD1 稳定币（目前仅在 Bonk 协议上支持）

🔄 非必填参数

当你需要使用 durable nonce 时，需要填入这个参数：

durable_nonce: 持久 nonce 信息，包含 nonce 账户和当前 nonce 值

重要说明

🌱 Seed 优化

Seed 优化现在在创建 SolanaTrade 实例时通过 TradeConfig 全局配置：

// 全局启用 seed 优化（默认: true）
let trade_config = TradeConfig::new(rpc_url, swqos_configs, commitment)
    .with_wsol_ata_config(
        true,  // create_wsol_ata_on_startup: 启动时检查并创建 WSOL ATA（默认: true）
        true   // use_seed_optimize: 为所有 ATA 操作启用 seed 优化（默认: true）
    );

当 seed 优化启用时：

⚠️ 警告: 使用 seed 优化购买的代币必须通过此 SDK 出售
⚠️ 警告: 官方平台的出售方法可能会失败
📝 注意: 使用 get_associated_token_address_with_program_id_fast_use_seed 获取 ATA 地址

💰 代币账户管理

账户管理参数提供精细控制：

独立控制: 创建和关闭操作可以分别控制
批量操作: 创建一次，多次交易，然后关闭
租金优化: 关闭账户时自动回收租金

🔍 地址查找表

使用 address_lookup_table_accounts 之前：

查找表减少交易大小并提高成功率
对于有许多账户引用的复杂交易特别有益

📊 滑点配置

推荐的滑点设置：

保守: 100-300 基点 (1-3%)
中等: 300-500 基点 (3-5%)
激进: 500-1000 基点 (5-10%)

🎯 协议特定参数

每个 DEX 协议需要特定的 extension_params：

PumpFun: PumpFunParams
PumpSwap: PumpSwapParams
Bonk: BonkParams
Raydium CPMM: RaydiumCpmmParams
Raydium AMM V4: RaydiumAmmV4Params
Meteora DAMM V2: MeteoraDammV2Params

请参阅相应的协议文档了解详细的参数规格。

🔍 交易模拟

当 simulate: true 时：

不提交区块链: 交易不会实际提交到区块链
验证功能: 验证交易构建和执行，而不会消耗实际代币
详细输出: 显示全面的信息，包括：
- 带有详细执行步骤的交易日志
- 计算单元消耗（用于优化 CU 预算）
- 潜在错误和失败原因
- 用于调试的内部指令
使用场景:
- 在真实执行前测试交易逻辑
- 调试失败的交易
- 估算计算单元消耗
- 验证交易参数
📝 注意: 模拟使用 RPC 的 simulateTransaction 方法，采用 processed 承诺级别

15 KiB Raw Permalink Blame History Unescape Escape

📋 交易参数参考手册

📋 目录

SimpleBuyParams / SimpleSellParams

SimpleBuyParams

SimpleSellParams

数量如何选择

AccountPolicy

Simple 参数使用 Durable Nonce

TradeBuyParams

基础交易参数

高级配置参数

TradeSellParams

基础交易参数

高级配置参数

参数分类

🎯 核心交易参数

⚙️ 交易控制参数

🔧 账户管理参数

🚀 优化参数

🔄 代币类型参数

🔄 非必填参数

重要说明

🌱 Seed 优化

💰 代币账户管理

🔍 地址查找表

📊 滑点配置

🎯 协议特定参数

🔍 交易模拟

15 KiB

Raw Permalink Blame History