stellar-dev

Stellar 开发技能（以 Soroban 为先）

此技能的用途

用户提出以下需求时，请使用此技能：

• Soroban 智能合约开发（Rust）
• Stellar dApp 前端开发（React / Next.js / Node.js）
• 钱包连接和签名流程（Freighter 等）
• 交易构建、发送和确认
• Stellar 资产发行和管理
• 客户端 SDK 使用（JavaScript、Python、Go、Rust）
• 零知识证明验证（目标网络／协议支持的情况下）
• 隐私保护型应用（隐私池、机密代币）
• 本地测试和部署
• 安全加固和审计式审查
• Agent 付款：付费 API（x402）和 AI Agent 付款客户端（x402、MPP charge、MPP channel）

此技能不适用的场景

• Bitcoin、Ethereum、Solana 或其他非 Stellar 区块链开发
• Stellar 节点／验证者运维（参见验证者文档）
• 与 Soroban 无关的通用 Rust 编程
• Stellar 协议治理或 CAP 编写

默认技术栈决策（带有倾向性）

1. 智能合约：Soroban（Rust）

• 所有智能合约开发均使用 Soroban SDK（soroban-sdk crate）
• 合约编译为 WebAssembly（WASM）
• 使用 #![no_std]——无法使用标准库
• 合约大小上限为 64KB；请使用发布优化选项
• 尽可能优先使用 Stellar 资产，而非自定义代币合约

2. 客户端 SDK：优先使用 stellar-sdk（JavaScript）

• 浏览器和 Node.js 应用使用 @stellar/stellar-sdk
• 同时支持 Stellar RPC 和旧版 Horizon API
• 支持完整的交易构建、签名和提交
• 支持 Soroban 合约部署和调用

3. API 访问：优先使用 Stellar RPC（Horizon 侧重旧版兼容）

• 新项目优先使用 Stellar RPC（JSON-RPC、实时状态）
• Horizon API 仍可用于旧版兼容和历史查询工作流
• RPC：大多数方法可查询最近 7 天的历史记录；getLedgers 可从创世区块开始查询（无限滚动）
• 若需获取超出 RPC 范围的完整历史数据，请使用 Hubble/Galexie

4. 代币策略：优先使用 Stellar 资产

• 同质化代币优先使用 Stellar 资产（经典发行方式 + 信任线）
• 钱包、交易所和锚点等均提供内置生态支持
• Stellar Asset Contracts（SAC）提供 Soroban 互操作性
• 仅在需要复杂逻辑时使用自定义 Soroban 代币

5. 测试

• 本地：使用 Stellar Quickstart Docker 搭建本地网络
• 测试网：使用 Testnet 和 Friendbot 获取资金
• 单元测试：编译为原生代码，以加快迭代
• 集成测试：部署到本地网络／测试网

6. 钱包集成

• Freighter 是主要的浏览器钱包
• 使用 Stellar Wallets Kit 支持多个钱包
• 使用 Wallet Standard 实现一致的连接模式

7. 时效性策略

• 对容易变化的信息（协议支持、RPC 端点、CAP/SEP 状态、SDK API 变更），在将其作为当前信息陈述前，请对照官方文档核实。

操作流程（如何执行任务）

1. 对任务所属层进行分类

• 智能合约层（Soroban/Rust）
• 客户端 SDK／脚本层（JS/Python/Go）
• 前端／钱包层
• 资产管理层（发行、信任线）
• 测试／CI 层
• 基础设施层（RPC/Horizon/索引）

快速路由

• 需要自定义链上逻辑？→ contracts-soroban.md
• 正在构建前端/dApp？→ frontend-stellar-sdk.md
• 正在发行或管理代币？→ stellar-assets.md
• 零知识证明或隐私？→ zk-proofs.md
• 正在配置测试/CI？→ testing.md
• 查询链上数据或建立索引？→ api-rpc-horizon.md（另请参阅 Data Docs）
• 需要安全审查？→ security.md
• 遇到错误？→ common-pitfalls.md
• 需要升级/工厂/治理/DeFi 架构模式？→ advanced-patterns.md
• 需要 SEP/CAP 指南和标准链接？→ standards-reference.md
• 正在构建付费 API 或 AI Agent 支付客户端？→ x402.md 或 mpp.md（参阅下方对比）

Agent 支付：x402 与 MPP

	x402	MPP Charge	MPP Channel
每次请求都需要链上交易？	是（通过 facilitator）	是（Soroban SAC）	否（链下提交）
需要 facilitator？	是（OZ Channels）	否	否
客户端需要 XLM？	否（费用由他人赞助）	可选（feePayer）	是
配置复杂度	低	低	中（需先部署合约）
最适用于	最快速配置、客户端免手续费	无第三方依赖	高频 Agent

• 销售 API，希望客户端不需要 XLM → x402.md Seller
• 从 Agent 调用 x402 API → x402.md Buyer
• 销售 API，不依赖 facilitator → mpp.md Charge 模式
• Agent 在每个会话中发起许多请求 → mpp.md Channel 模式
• 不确定 → x402（入门门槛最低）

所有协议默认使用 USDC（SEP-41 SAC）；网络 ID 使用 stellar:testnet / stellar:pubnet CAIP-2。

2. 选择合适的构建模块

• 合约：Soroban Rust SDK + Stellar CLI
• 前端：stellar-sdk (JS) + Freighter/Wallets Kit
• 后端：stellar-sdk (JS/Python/Go) + RPC
• 资产：Classic 操作，或用于 Soroban 互操作的 SAC
• 测试：Quickstart（本地）或 Testnet

3. 按照 Stellar 特定要求正确实现

务必明确：

• 网络口令（Mainnet、Testnet 或本地网络）
• 源账户 + 序列号
• 费用 + 资源限制（针对 Soroban）
• 授权要求
• 资产的 Trustline 状态
• 合约存储类型（temporary、persistent 或 instance）

4. 添加测试

• 单元测试：使用 #[test] 进行原生编译
• 集成测试：使用本地 Quickstart 或 Testnet
• 合约测试：使用 soroban-sdk 中的 Env
• 前端测试：模拟钱包/RPC 交互

5. 交付内容要求

实现更改时，请提供：

• 具体修改文件 + 差异
• 安装/构建/测试/部署命令
• 网络配置（口令、RPC 端点）
• 关于签名/费用/存储/授权的风险说明

渐进式阅读（按需查阅）

• 智能合约：contracts-soroban.md
• 前端 + 钱包：frontend-stellar-sdk.md
• 测试策略：testing.md
• Stellar 资产：stellar-assets.md
• 零知识证明：zk-proofs.md
• API 访问（RPC/Horizon）：api-rpc-horizon.md
• 安全检查清单：security.md
• 常见问题：common-pitfalls.md
• 高级架构模式：advanced-patterns.md
• SEP/CAP 标准索引：standards-reference.md
• 生态项目：ecosystem.md
• 参考链接：resources.md
• x402 付费 API + Agent 客户端：x402.md
• MPP Agent 支付（charge + channel）：mpp.md

关键词

stellar, soroban, xlm, 智能合约, rust, wasm, webassembly, rpc, horizon, freighter, stellar-sdk, soroban-sdk, stellar-cli, 信任线, anchor, sep, passkey, 智能钱包, sac, stellar asset contract, defi, 代币, nft, scaffold stellar, constructor, upgrade, factory, 治理, 标准, 零知识, zk, zk-snark, groth16, bn254, poseidon, pairing, 隐私, 保密, noir, risc zero, 隐私池, 默克尔树, x402, mpp, machine payments protocol, Agent 支付, 付费 API, 支付通道, AI Agent 支付, usdc, sep-41, oz channels, openzeppelin relayer, http 402, 按请求付费, soroban auth entries, 费用赞助, 支付中间件