near-smart-contracts

NEAR 智能合约开发

使用 Rust 和 NEAR SDK（v5.x）在 NEAR Protocol 上开发安全、高效智能合约的综合指南。

适用场景

在以下情况下，请参考这些指南：

• 使用 Rust 编写新的 NEAR 智能合约
• 从安全性和优化角度审查现有合约代码
• 实现跨合约调用和回调
• 管理合约状态和存储
• 测试和部署 NEAR 合约
• 优化 Gas 用量和性能

开始使用

前置条件

开始开发前，请安装所需工具：

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add wasm32 target for compiling contracts
rustup target add wasm32-unknown-unknown

# Install cargo-near (build, deploy, and manage contracts)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/cargo-near/releases/latest/download/cargo-near-installer.sh | sh

# Install near-cli-rs (interact with NEAR network)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/near-cli-rs/releases/latest/download/near-cli-rs-installer.sh | sh

创建新项目

重要：创建新项目时，务必运行 cargo near new。切勿手动创建 Cargo.toml、lib.rs 或任何项目文件。该命令会生成所有必需文件，并使用正确的配置。

# REQUIRED: Create a new contract project using the official template
cargo near new my-contract

# Navigate to project directory
cd my-contract

# Build the contract
cargo near build

# Run tests
cargo test

必须使用 cargo near new 的原因：

• 生成包含正确依赖项和构建设置的 Cargo.toml
• 创建合适的项目结构，并提供 src/lib.rs 模板
• 在 tests/ 目录中包含集成测试配置
• 配置带有 overflow-checks = true 的发布配置
• 为 WASM 编译设置正确的 crate-type
• 避免导致构建失败的常见配置错误

请勿：

• 手动创建 Cargo.toml
• 手动创建 src/lib.rs
• 从示例中复制粘贴项目结构
• 跳过此步骤，直接创建文件

项目结构

my-contract/
├── Cargo.toml          # Dependencies and project config
├── src/
│   └── lib.rs          # Main contract code
├── tests/              # Integration tests
│   └── test_basics.rs
└── README.md

部署到 Testnet

# Create a testnet account (if needed)
near account create-account sponsor-by-faucet-service my-contract.testnet autogenerate-new-keypair save-to-keychain network-config testnet create

# Build in release mode
cargo near build --release

# Deploy to testnet
cargo near deploy my-contract.testnet without-init-call network-config testnet sign-with-keychain send

按优先级划分的规则类别

优先级	类别	影响	前缀
1	安全与防护	严重	security-
2	合约结构	高	structure-
3	状态管理	高	state-
4	跨合约调用	中高	xcc-
5	合约升级	中高	upgrade-
6	链签名	中高	chain-
7	Gas 优化	中	gas-
8	延迟与恢复	中	yield-
9	测试	中	testing-
10	最佳实践	中	best-

1. 安全与防护（严重）

• security-storage-checks - 始终验证存储操作并检查存款
• security-access-control - 使用 predecessor_account_id 实现适当的访问控制
• security-reentrancy - 防范重入攻击（在外部调用前更新状态）
• security-overflow - 在 Cargo.toml 中使用 overflow-checks = true 以防止溢出
• security-callback-validation - 验证回调结果并处理失败情况
• security-private-callbacks - 将回调标记为 #[private]，以防止外部调用
• security-yoctonear-validation - 在 #[payable] 函数中验证附加存款
• security-sybil-resistance - 实施最低存款检查以防止垃圾请求

2. 合约结构（高）

• structure-near-bindgen - 对合约结构体使用 #[near(contract_state)] 宏（替代旧的 #[near_bindgen]）
• structure-initialization - 使用 #[init] 模式正确实现初始化
• structure-versioning - 通过版本控制机制为合约升级做好规划
• structure-events - 使用 env::log_str() 和结构化事件日志（NEP-297）
• structure-standards - 遵循 NEAR 增强提案（NEP）中的标准
• structure-serializers - 对数据结构体使用 #[near(serializers = [json, borsh])]
• structure-panic-default - 使用 #[derive(PanicOnDefault)] 要求先进行初始化

3. 状态管理（高）

• state-collections - 使用 near_sdk::store 中的 SDK 集合：IterableMap、IterableSet、Vector、LookupMap、LookupSet、UnorderedMap、UnorderedSet、TreeMap
• state-serialization - 状态使用 Borsh，外部接口使用 JSON
• state-lazy-loading - 使用 SDK 集合实现延迟加载以节省 Gas（按需加载，而非一次性全部加载）
• state-pagination - 对大型数据集使用 .skip() 和 .take() 实现分页
• state-migration - 使用版本控制规划状态迁移策略
• state-storage-cost - 请记住：1 NEAR ≈ 100kb 存储空间，合约需为其使用的存储空间付费
• state-unique-prefixes - 为所有集合使用唯一的字节前缀（避免冲突）
• state-native-vs-sdk - 原生集合（Vec、HashMap）会加载所有数据；仅在条目少于 100 个时使用

4. 跨合约调用（中高）

• xcc-promise-chaining - 正确串联 Promise
• xcc-callback-handling - 处理所有回调场景（成功、失败）
• xcc-gas-management - 为跨合约调用分配适当的 Gas
• xcc-error-handling - 实现稳健的错误处理
• xcc-result-unwrap - 未经检查，切勿解包 Promise 结果

5. 合约升级与迁移（中高）

• upgrade-migration - 使用枚举进行状态版本控制，并通过 #[init(ignore_state)] 实现 migrate 方法
• upgrade-self-update - 为可通过编程方式自行更新的合约采用相应模式
• upgrade-cleanup-old-state - 始终移除旧状态结构以释放存储空间
• upgrade-dao-controlled - 在生产环境中使用多签或 DAO 管理升级

6. 链签名（中高）

• chain-signatures - 派生其他区块链的地址、请求 MPC 签名并构建多链交易
• chain-callback-handling - 正确处理 MPC 签名回调
• chain-gas-allocation - 为 MPC 调用分配足够的 Gas（yield/resume 模式）

7. Gas 优化（中）

• gas-batch-operations - 批量执行操作以降低交易成本
• gas-minimal-state-reads - 尽量减少状态读写（在内存中缓存）
• gas-efficient-collections - 选择适当的集合类型（LookupMap 或 IterableMap）
• gas-view-functions - 将只读函数标记为 view（Rust 中使用 &self）
• gas-avoid-cloning - 避免不必要地克隆大型数据结构
• gas-early-validation - 尽早使用 require!，为无效输入节省 Gas
• gas-prepaid-gas - 为跨合约调用附加适当的 Gas（建议：30 TGas）

8. Yield 与 Resume（中）

• yield-resume - 创建 yield Promise、发出 resume 信号、处理超时，并管理 yield/resume 之间的状态
• yield-gatekeeping - 保护 resume 方法，防止未经授权的调用者访问

9. 测试（中）

• testing-integration-tests - 使用 near-sandbox + near-api 编写集成测试
• testing-unit-tests - 使用模拟上下文编写全面的单元测试
• testing-sandbox - 在 testnet/mainnet 之前，使用本地 sandbox 环境进行测试
• testing-edge-cases - 测试边界条件、溢出和空状态
• testing-gas-profiling - 在集成测试中分析 Gas 用量
• testing-cross-contract - 全面测试跨合约调用和回调
• testing-failure-scenarios - 测试 Promise 失败和超时场景
• testing-time-travel - 使用 sandbox.fast_forward() 执行时间相关测试

10. 最佳实践（中）

• best-contract-tools - 对于 NEP 标准（FT、NFT 等）和 NEP-297 结构化事件，使用 near-sdk-contract-tools
• best-panic-messages - 提供清晰、可执行的 panic 消息
• best-logging - 使用 env::log_str() 进行调试和事件发送
• best-documentation - 为公共方法、参数和复杂逻辑编写文档
• best-error-types - 定义自定义错误类型，或使用描述性字符串
• best-constants - 使用常量表示魔术数字和配置
• best-require-macro - 使用 require! 代替 assert!，以提供更好的错误消息
• best-promise-return - 从跨合约调用中返回 promise，以便正确跟踪
• best-sdk-crates - 复用 SDK 导出的 crate（borsh、serde、base64 等）
• best-account-id-encoding - 使用 base32 编码 AccountId，可节省 40% 的存储空间

使用方法

阅读各规则文件，了解详细说明和代码示例：

rules/security-storage-checks.md
rules/structure-near-bindgen.md
rules/state-collections.md
rules/xcc-promise-chaining.md
rules/upgrade-migration.md
rules/chain-signatures.md
rules/yield-resume.md
rules/best-contract-tools.md
rules/testing-integration-tests.md

每个规则文件包含：

• 简要说明规则的重要性
• 错误代码示例及其说明
• 正确代码示例及其说明
• 其他背景信息和 NEAR 特定注意事项

其他规则（上游文档）

没有本地文件的规则，请查阅官方文档（添加 .md 即可获取纯 Markdown）：

主题	上游文档
安全检查清单（整体）	https://docs.near.org/smart-contracts/security/checklist
存储成本攻击	https://docs.near.org/smart-contracts/security/storage
私有回调	https://docs.near.org/smart-contracts/security/cross-contract-calls/callbacks
XCC 失败时退还附加的 NEAR	https://docs.near.org/smart-contracts/security/cross-contract-calls/refunds
不要在回调中触发 panic	https://docs.near.org/smart-contracts/security/cross-contract-calls/callback-panics
安全的 ft_on_transfer / 重入	https://docs.near.org/smart-contracts/security/cross-contract-calls/ft-transfer-call
转账前扣除余额	https://docs.near.org/smart-contracts/security/cross-contract-calls/reentrancy
要求支付一个 yoctoNEAR	https://docs.near.org/smart-contracts/security/one_yocto
Sybil 攻击	https://docs.near.org/smart-contracts/security/sybil
抢先交易	https://docs.near.org/smart-contracts/security/frontrunning
重复的代币 ID	https://docs.near.org/smart-contracts/security/duplicate-inputs
随机数	https://docs.near.org/smart-contracts/security/random
单元测试	https://docs.near.org/smart-contracts/testing/unit-test
全局合约	https://docs.near.org/smart-contracts/global-contracts
序列化	https://docs.near.org/smart-contracts/anatomy/serialization
生产构建	https://docs.near.org/smart-contracts/anatomy/reduce-size

---

最新工具和版本

开发工具

• cargo-near：最新版本 - 构建、部署和管理合约（cargo near build、cargo near deploy）
• near-cli-rs：最新版本 - NEAR 命令行界面（near contract call、near contract view）
• rustc：最新稳定版 - Rust 编译器
• near-sandbox：最新版本 - 用于集成测试的本地沙盒环境
• near-api-rs：最新版本 - 用于与 NEAR 交互的 Rust API 客户端（在测试中取代 near-workspaces-rs）
• omni-transaction-rs：最新版本 - 构建适用于多个区块链（Bitcoin、Ethereum 等）的交易

SDK 版本

• near-sdk-rs：v5.x（最新版本 5.29.x）— 当前稳定版 SDK；#[handle_result] 和 #[near(contract_state)] 是现代惯用写法
• near-sdk-contract-tools：最新版本 - 用于 NEP 标准（FT、NFT、存储管理）的派生宏

主要功能

• 统一的宏语法：#[near(contract_state)] 替代 #[near_bindgen] + 派生宏
• 灵活的序列化：数据结构体可使用 #[near(serializers = [json, borsh])]
• 存储集合：near_sdk::store::IterableMap、IterableSet、LookupMap、LookupSet、Vector、UnorderedMap、UnorderedSet、TreeMap
• 简化的跨合约调用：使用 Promise::new() 和 .then() 的高级 Promise API
• 内置 NEP 支持：FT（NEP-141）、NFT（NEP-171）及其他标准
• 结果处理：使用 #[handle_result] 处理返回 Result<T, E> 且不会触发 panic 的方法
• 让出/恢复：合约可以让出执行权，并等待外部服务恢复执行
• 链签名：为其他区块链（Bitcoin、Ethereum、Solana 等）签署交易
• 合约工具：用于 Owner、Pause、基于角色的访问控制模式的派生宏

资源

• NEAR 文档：https://docs.near.org
• 智能合约快速入门：https://docs.near.org/smart-contracts/quickstart
• 合约结构：https://docs.near.org/smart-contracts/anatomy/
• NEAR SDK Rust：https://docs.near.org/tools/sdk
• SDK Rust 参考：https://docs.rs/near-sdk
• 存储与集合：https://docs.near.org/smart-contracts/anatomy/collections
• 最佳实践：https://docs.near.org/smart-contracts/anatomy/best-practices
• 跨合约调用：https://docs.near.org/smart-contracts/anatomy/crosscontract
• 让出与恢复：https://docs.near.org/smart-contracts/anatomy/yield-resume
• 合约升级：https://docs.near.org/smart-contracts/release/upgrade
• 链签名：https://docs.near.org/chain-abstraction/chain-signatures
• 链签名实现：https://docs.near.org/chain-abstraction/chain-signatures/implementation
• 安全最佳实践：https://docs.near.org/smart-contracts/security/checklist
• 集成测试：https://docs.near.org/smart-contracts/testing/integration-test
• NEP-297 事件：https://github.com/near/NEPs/blob/master/neps/nep-0297.md
• NEAR 标准（NEP）：https://github.com/near/NEPs
• NEAR 示例：https://github.com/near-examples
• Sandbox 测试：https://github.com/near/near-sandbox
• NEAR API Rust：https://github.com/near/near-api-rs
• Omni Transaction RS：https://github.com/near/omni-transaction-rs
• 合约工具：https://github.com/near/near-sdk-contract-tools

存储成本参考

存储	成本	备注
1 字节	0.00001 NEAR	每 0.1 NEAR 约可存储 10kb
100 KB	约 1 NEAR	近似参考值
AccountId	64+ 字节	使用 base32 编码可节省 40%
合约代码	可变	由合约账户支付

SDK 集合参考

集合	可迭代	清除	有序	范围查询	用途
Vector	是	是	是	是	可通过索引访问的有序列表
LookupMap	否	否	否	否	快速键值存储，无需迭代
LookupSet	否	否	否	否	快速成员检查
IterableMap	是	是	是	否	支持迭代的键值存储
IterableSet	是	是	是	否	支持迭代的集合
UnorderedMap	是	是	否	否	键值存储，迭代顺序不定
UnorderedSet	是	是	否	否	集合，迭代顺序不定
TreeMap	是	是	是	是	支持范围查询的有序键值存储