Satsuma

Satsuma 协议自动交互脚本

Satsuma 是 Citrea Testnet 上的 DeFi 协议，支持代币交换、质押和流动性管理。本脚本支持全自动化交互，帮助用户完成各种 DeFi 操作。

核心功能：
1. 代币交换（Swap） - cBTC、USDC、SUMA 之间互换
2. 转换（Convert） - 将 SUMA 转换为 veSUMA
3. 质押（Stake） - 质押 veSUMA 获得收益
4. 解除质押（Unstake） - 解除 veSUMA 质押
5. 添加流动性（Add Liquidity） - 添加 USDC 到流动性池
6. 退出（Exit） - 将 veSUMA 即时退出为 SUMA
7. 全部操作（All） - 自动执行所有操作

功能特性：
- 支持 3 种代币：cBTC（原生）、USDC、SUMA
- 自动授权（Approve）代币
- 随机数量范围，模拟真实用户
- 可配置操作类型和参数
- 支持多次交易循环
- 详细的执行日志
- 兼容 web3.py 6.11.3

使用说明：

【平台介绍】
Satsuma：Citrea Testnet DeFi 协议
- RPC: https://rpc.testnet.citrea.xyz
- Chain ID: 5115
- 区块浏览器: https://explorer.testnet.citrea.xyz
- 类型：DeFi 协议（Swap、Staking、Liquidity）

合约地址：
- Swap Router: 0x3012e9049d05b4b5369d690114d5a5861ebb85cb
- USDC Token: 0x36c16eac6b0ba6c50f494914ff015fca95b7835f
- SUMA Token: 0xdE4251dd68e1aD5865b14Dd527E54018767Af58a
- veSUMA Token: 0x97a4f684620D578312Dc9fFBc4b0EbD8E804ab4a
- Staking Contract: 0x22625aDDDcD0e6D981312f6c6E2DBb0003863A90
- WcBTC: 0x8d0c9d1c17ae5e40fff9be350f57840e9e66cd93
- Liquidity Manager: 0xcA3534C15Cc22535BF880Ba204c69340f813730b
- USDC-SUMA Vault: 0xf04462C7ce97fF4d38540e3F1ae729113EE88cBc

【配置说明】
在 config.ini 中设置：

【Network Settings（网络设置）】
- rpc_url：RPC 节点地址（默认 https://rpc.testnet.citrea.xyz）
- 如果默认 RPC 失效，需要修改为其他可用的 RPC

【Operation Settings（操作设置）】
- operation_type：操作类型（默认 all）
- swap：代币交换
- convert：转换 SUMA 为 veSUMA
- stake：质押 veSUMA
- unstake：解除质押 veSUMA
- liquidity：添加流动性
- exit：退出 veSUMA
- all：执行全部操作（推荐）

• transactions_per_wallet：每个钱包的交易次数（默认 1）
• 仅对 operation_type = all 有效
• 建议值：1 - 10 次
• 每轮执行所有操作（6次swap + convert + stake + liquidity + unstake + exit）

【Swap Settings（交换设置）】
仅当 operation_type = swap 时有效

• from_token：源代币（默认 cBTC）
• 可选：cBTC, USDC, SUMA

• 从哪个代币交换

• to_token：目标代币（默认 USDC）

• 可选：cBTC, USDC, SUMA
• 交换到哪个代币

• 不能与 from_token 相同

• swap_amount_min/max：交换数量范围（默认 0.00001 - 0.000015）

• 单位：代币原生单位
• 每次交换会在此范围内随机选择数量

【Convert Settings（转换设置）】
仅当 operation_type = convert 时有效

• convert_amount_min/max：转换数量范围（默认 0.001 - 0.0015）
• 单位：SUMA
• 将 SUMA 转换为 veSUMA

【Stake Settings（质押设置）】
仅当 operation_type = stake 时有效

• stake_amount_min/max：质押数量范围（默认 0.001 - 0.0015）
• 单位：veSUMA
• 质押 veSUMA 到质押合约

【Unstake Settings（解除质押设置）】
仅当 operation_type = unstake 时有效

• unstake_amount_min/max：解除质押数量范围（默认 0.001 - 0.0015）
• 单位：veSUMA
• 从质押合约解除 veSUMA

【Liquidity Settings（流动性设置）】
仅当 operation_type = liquidity 时有效

• liquidity_amount_min/max：添加流动性数量范围（默认 1 - 10）
• 单位：USDC
• 添加 USDC 到 USDC-SUMA 流动性池

【Exit Settings（退出设置）】
仅当 operation_type = exit 时有效

• exit_amount_min/max：退出数量范围（默认 0.001 - 0.0015）
• 单位：veSUMA
• 将 veSUMA 即时退出为 SUMA

【Advanced Settings（高级设置）】
- request_timeout：交易确认超时时间，秒（默认 120）
- operation_delay_min/max：操作间延迟，秒（默认 5-10）

【功能详细说明】

1. 代币交换（Swap）

功能：在 cBTC、USDC、SUMA 之间进行交换

执行流程：
1. 检查是否是原生代币（cBTC）
2. 如果不是原生代币，先授权（Approve）Router 合约
3. 构建 Swap 交易数据（使用 exactInputSingle 方法）
4. 发送交易到 Swap Router
5. 等待交易确认

配置参数：
- from_token：源代币
- to_token：目标代币
- swap_amount_min/max：交换数量范围

注意事项：
- 源代币和目标代币不能相同
- 如果源代币不是 cBTC，需要先有该代币余额
- 交换会收取一定的手续费
- 确保钱包有足够的 cBTC 作为 Gas 费

2. 转换（Convert）

功能：将 SUMA 代币转换为 veSUMA 代币

执行流程：
1. 授权 SUMA 给 veSUMA 合约
2. 调用 veSUMA 合约的转换方法
3. 发送交易
4. 等待交易确认

配置参数：
- convert_amount_min/max：转换数量范围

注意事项：
- 需要先有 SUMA 余额（通过 Swap 获得）
- 转换是单向的（需要通过 Exit 退出）
- veSUMA 是治理代币，可以质押获得收益

3. 质押（Stake）

功能：质押 veSUMA 到质押合约获得收益

执行流程：
1. 授权 veSUMA 给 Staking 合约
2. 调用 Staking 合约的 deposit 方法
3. 发送交易
4. 等待交易确认

配置参数：
- stake_amount_min/max：质押数量范围

注意事项：
- 需要先有 veSUMA 余额（通过 Convert 获得）
- 质押后可以获得奖励
- 可以通过 Unstake 解除质押

4. 解除质押（Unstake）

功能：从质押合约解除 veSUMA

执行流程：
1. 调用 Staking 合约的 withdraw 方法
2. 发送交易
3. 等待交易确认

配置参数：
- unstake_amount_min/max：解除质押数量范围

注意事项：
- 需要先有质押的 veSUMA
- 解除质押后会失去奖励
- 解除后的 veSUMA 可以继续使用

5. 添加流动性（Add Liquidity）

功能：添加 USDC 到 USDC-SUMA 流动性池

执行流程：
1. 授权 USDC 给 Liquidity Manager 合约
2. 构建添加流动性交易数据
3. 发送交易
4. 等待交易确认

配置参数：
- liquidity_amount_min/max：添加流动性数量范围

注意事项：
- 需要先有 USDC 余额（通过 Swap 获得）
- 添加流动性可以获得 LP 代币和手续费分成
- 本脚本仅支持添加，不支持移除

6. 退出（Exit）

功能：将 veSUMA 即时退出为 SUMA

执行流程：
1. 调用 veSUMA 合约的 exit 方法
2. 发送交易
3. 等待交易确认

配置参数：
- exit_amount_min/max：退出数量范围

注意事项：
- 需要有未质押的 veSUMA
- 退出是将 veSUMA 转换回 SUMA
- 如果 veSUMA 已质押，需要先 Unstake

7. 全部操作（All）

功能：自动执行所有上述操作

执行流程（每轮）：
1. 执行 6 次 Swap（cBTC→USDC, cBTC→SUMA, SUMA→cBTC, SUMA→USDC, USDC→cBTC, USDC→SUMA）
2. 执行 Convert（SUMA→veSUMA）
3. 执行 Stake（质押 veSUMA）
4. 执行 Add Liquidity（添加 USDC 流动性）
5. 执行 Unstake（解除质押 veSUMA）
6. 执行 Exit（veSUMA→SUMA）

配置参数：
- transactions_per_wallet：每个钱包执行的轮数

注意事项：
- 这是最全面的交互方式
- 每轮会消耗一定的 Gas 费
- 确保钱包有足够的 cBTC 余额
- 所有数量都是随机的，模拟真实用户行为

【使用步骤】

第一步：获取测试币
1. 准备 EVM 钱包私钥
2. 访问 Citrea Testnet 水龙头获取 cBTC（原生代币）
3. 确保每个钱包有足够的 cBTC（建议至少 0.01 cBTC）

第二步：配置参数
1. 在 config.ini 中选择操作类型
2. 根据操作类型设置相应的参数
3. 设置每个钱包的交易次数（仅 all 模式）
4. 检查 RPC URL 是否可用

第三步：准备私钥
1. 在 UI 中加载 EVM 私钥
2. 确保私钥格式正确（不带 0x 前缀）
3. 钱包需要有 Citrea Testnet 的 cBTC

第四步：执行脚本
1. 点击「开始执行」
2. 查看日志输出
3. 等待所有钱包完成操作
4. 在区块浏览器查看交易结果

【操作建议】

操作类型选择：
- All：最全面，执行所有操作（推荐）
- Swap：单独测试交换功能
- Convert/Stake：体验质押流程
- Liquidity：体验 LP 功能

交易次数建议：
- 测试：1 次（了解流程）
- 正常：3-5 次（增加交互次数）
- 积极：10 次（最大化交互）

批量处理建议：
- 钱包数量：5-20 个
- 钱包间延迟：5-10 秒
- 使用「按顺序」执行
- 确保每个钱包都有足够 cBTC

【重要提示】

1. 网络要求
   - Citrea Testnet 是测试网，可能不稳定
   - 需要稳定的网络连接
   - RPC 可能会失效，需要更换
   - 交易确认时间约 10-30 秒

2. 余额管理
   - 每个操作都需要 Gas 费（cBTC）
   - 建议每个钱包留 0.005 cBTC 作为 Gas 储备
   - All 模式会执行多次操作，消耗较多 Gas
   - 确保有足够的代币余额进行各种操作

3. Gas 费说明
   - Approve：约 50,000 - 100,000 Gas
   - Swap：约 400,000 - 600,000 Gas
   - Convert：约 150,000 - 200,000 Gas
   - Stake/Unstake：约 150,000 - 300,000 Gas
   - Add Liquidity：约 400,000 - 600,000 Gas
   - Exit：约 150,000 - 200,000 Gas
   - Gas Price 会自动从网络获取

4. 测试网特性
   - 测试网可能随时重置
   - 测试币没有实际价值
   - 用于测试和学习 DeFi 操作
   - 不要发送真实资产到测试网

5. 错误处理
   - 余额不足：会自动跳过该钱包
   - 授权失败：会停止后续操作
   - 交易失败：会记录错误继续下一个
   - 网络超时：会等待最多 120 秒
   - RPC 失效：需要手动更换

6. 代币流转
   - cBTC 是原生代币，用于 Gas 和交换
   - USDC 通过 Swap 从 cBTC 获得
   - SUMA 通过 Swap 从 cBTC 或 USDC 获得
   - veSUMA 通过 Convert 从 SUMA 获得
   - 质押的 veSUMA 需要先 Unstake 才能 Exit

【常见问题】

Q: 什么是 Satsuma？
A: Satsuma 是 Citrea Testnet 上的 DeFi 协议，支持代币交换、质押和流动性管理。

Q: cBTC 是什么？
A: cBTC 是 Citrea Testnet 的原生代币（类似以太坊的 ETH），用于支付 Gas 费和进行交易。

Q: veSUMA 和 SUMA 有什么区别？
A: veSUMA 是 SUMA 的治理代币版本，可以质押获得收益。SUMA 可以通过 Convert 转换为 veSUMA，veSUMA 可以通过 Exit 退出为 SUMA。

Q: 为什么需要授权（Approve）？
A: 授权允许智能合约代表你使用你的代币。这是 ERC20 标准的安全机制，需要用户明确授权。

Q: All 模式会执行哪些操作？
A: All 模式会执行 6 次 Swap（覆盖所有代币对）+ Convert + Stake + Add Liquidity + Unstake + Exit，共约 10 个操作。

Q: 为什么交换会失败？
A: 可能原因：余额不足、滑点过大、流动性不足、Gas 不足、RPC 失效。检查日志了解具体错误。

Q: 可以只执行单个操作吗？
A: 可以。将 operation_type 设置为 swap、convert、stake、unstake、liquidity 或 exit 之一。

Q: 质押有什么好处？
A: 质押 veSUMA 可以获得协议收益分成和治理权。实际收益取决于协议设置。

Q: 添加流动性有什么风险？
A: 添加流动性可能面临无常损失（Impermanent Loss），但可以获得交易手续费分成。

Q: 如何查看交易详情？
A: 访问区块浏览器 https://explorer.testnet.citrea.xyz 输入交易哈希查看详情。

依赖库：
- web3：以太坊交互库（版本 6.11.3）

官方信息：
- 项目：Satsuma
- 类型：Citrea Testnet DeFi 协议
- RPC: https://rpc.testnet.citrea.xyz
- Chain ID: 5115
- 浏览器: https://explorer.testnet.citrea.xyz

适用场景：
- Citrea Testnet DeFi 交互
- 代币交换测试
- 质押和治理参与
- 流动性提供测试
- 批量钱包管理