简介
Stellar Trade Contracts 是 Stellar Trade 的 Soroban 合约工作区。Stellar Trade 是构建于 Stellar 之上的开源预测市场原型。这些合约规定 XLM 如何进入市场池、参与者如何减少持仓，以及已结算或已取消的市场如何分配支付和退款。
该仓库面向需要构建、测试、审查或部署应用程序后端合约的开发者。仓库包含市场合约，以及代币、推荐、排行榜和跨合约集成测试等支持性 crate。
了解工作区
仓库由五个主要 crate 组成，每个 crate 负责明确的功能：
prediction_market：创建市场、接受持仓、减少持仓、处理结算者操作、计算按比例分配的申领金额、处理取消退款、记录费用，并支持争议和治理。stellar_trade_token：提供奖励代币，支持管理员控制、授权铸币者、暂停控制和可选的供应上限。全新部署使用名称Stellar Trade和符号STRD。referral_registry：登记推荐关系、限制推荐链深度，并分配推荐费用。leaderboard：记录参与者积分和胜负记录，应用分数衰减，并支持授权奖励铸币。cross_contract_invariants：测试市场、推荐、排行榜和代币合约之间的记账和行为。
设置 Rust 工作区
项目通过 rust-toolchain.toml 固定使用 Rust 1.91.0 和 wasm32v1-none 目标。在从仓库根目录运行检查之前，请安装仓库指定的工具链和目标。
环境准备就绪后，运行完整的工作区测试套件：
cargo test --workspace --all-features格式检查用于验证源代码是否遵循项目的格式规则：
cargo fmt --all -- --check运行 Clippy，并将警告视为错误，以发现代码质量和正确性问题：
cargo clippy --workspace --all-features -- -D warnings使用发布配置文件，将预测市场合约构建为 WebAssembly：
cargo build --release --target wasm32v1-none -p prediction_market这些命令对应于仓库 GitHub Actions 工作流使用的检查。对于默认分支和拉取请求中的变更，该工作流还会构建 WASM 构件并运行跨合约不变量测试。
了解市场生命周期
1. 创建市场
获得授权的创建者发布市场问题、类别和关闭时间。市场创建受到权限控制，因此调用者必须满足合约配置的授权规则。
2. 建立持仓
参与者调用 place_bet，在 YES 或 NO 一方投注 XLM。合约会应用配置的费用，并将扣除费用后的持仓记入参与者所选的一方。
减少持仓机制不是点对点销售、订单簿或做空仓位，而是对参与者现有记录持仓执行的操作。
3. 在关闭前减少持仓
在市场关闭前，参与者可以调用 reduce_position 来减少现有持仓。合约使用参与者记录的一方，并根据减少的持仓和保留费用规则计算返还金额。
由于合约会从参与者的现有持仓中选择一方，调用者不应将此操作视为切换阵营或与其他参与者交易。
4. 结算市场
市场关闭后，获得授权的结算者提交结果。随后，市场合约会为获胜持仓计算按比例分配的支付金额。
结算受到权限控制。此工作区不提供自动预言机。除非获得授权的结算者使用外部价格或网络数据并提交结果，否则这些数据无法结算市场。
5. 申领奖励或接收取消退款
市场结算后，参与者通过合约申领按比例分配的支付金额。已取消的市场采用独立的退款流程，而不是正常的获胜持仓支付流程。
结算者的选择、结算标准、证据和争议处理都是重要的信任假设。在依赖已部署的市场之前，请审查这些流程。
审查记账和安全属性
在修改合约行为之前，请阅读不变量矩阵。它将重要的记账规则与保护这些规则的测试关联起来。
该矩阵涵盖以下领域：
- 费用守恒和市场级费用隔离。
- 按比例支付金额的边界。
- 取消行为。
- 推荐记账。
- 奖励供应量跟踪。
- 存储生存时间处理。
- 紧急暂停流程。
如果修改费用、奖励、支付公式或存储生命周期，请同时更新相关的回归测试和不变量测试。当变更影响多个合约时，cross_contract_invariants crate 尤其有用。
正确使用历史问题报告
issues/ 目录包含历史安全和正确性报告。请阅读 issues/README.md 以了解其背景。
这些报告记录了此前的设计风险。不应将其视为合约已完成审计的证明，也不应视为其中列出的每个问题目前仍然存在的确认。请将其作为审查材料，并结合当前源代码、测试和不变量矩阵一起使用。
为部署做好准备
测试网部署会保留其历史合约 ID 和代币元数据。全新部署会创建新的地址并初始化 STRD；它不会迁移现有持有者或余额。
部署前，请确认以下所有事项：
- 目标网络。
- 合约 ID。
- 管理员身份。
- 费用设置。
- 解析器配置。
切勿将私钥、钱包恢复短语、.deploy.env、部署输出或本地身份文件提交到代码仓库。
有关本地前端开发和应用级部署说明，请参阅应用 README。
高级开发技巧
测试跨合约行为
看似只影响一个 crate 的更改，可能会影响推荐、奖励、排行榜记录或代币供应量。请运行完整的工作区测试套件和跨合约不变量测试，不要只依赖单个 crate 的单元测试。
明确权限边界
市场创建、结果解析、代币管理、铸造和其他敏感操作都使用授权控制。审查或扩展合约时，请确认哪些身份可以执行每项操作，以及暂停控制如何影响紧急行为。
审查存储生命周期变更
存储 TTL 处理是项目安全模型的一部分。任何对存储访问模式或生命周期的更改，都应根据不变量矩阵进行检查，并通过回归测试覆盖。
验证发布产物
在发布或部署更改前，请运行格式化检查、Clippy、测试和发布版 WASM 构建。将本地构建通过视为开发前提，而不是替代配置和部署身份审查的依据。
结论
Stellar Trade Contracts 提供用于创建预测市场、记录 YES 和 NO 仓位、减少投注额、解析结果、分配按比例计算的收益以及退还已取消市场资金的 Soroban 逻辑。其配套 crate 增加了奖励代币、推荐、排行榜和集成功能。
要安全地使用该代码仓库，请从固定的 Rust 环境开始，运行所有工作区检查，了解市场生命周期，并在更改记账或存储行为前审查不变量矩阵。部署期间，请核实每项权限和网络设置，并将所有机密信息置于版本控制之外。