near-smart-contracts

在 Rust 中进行 NEAR Protocol 智能合约开发。当您需要编写、审查或部署 NEAR 智能合约时，可调用此技能。涵盖合约结构、状态管理、跨合约调用、测试、安全性以及优化模式。

SKILL.md

--- frontmatter

name: near-smart-contracts
description: NEAR Protocol smart contract development in Rust. Use when writing, reviewing, or deploying NEAR smart contracts. Covers contract structure, state management, cross-contract calls, testing, security, and optimization patterns.
license: MIT
metadata:
  author: near
  version: "1.0.0"

NEAR Smart Contracts Development

Comprehensive guide for developing secure and efficient smart contracts on NEAR Protocol using Rust and the NEAR SDK.

When to Apply

Reference these guidelines when:

•Writing new NEAR smart contracts in Rust
•Reviewing existing contract code for security and optimization
•Implementing cross-contract calls and callbacks
•Managing contract state and storage
•Testing and deploying NEAR contracts
•Optimizing gas usage and performance

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Security & Safety	CRITICAL	`security-`
2	Contract Structure	HIGH	`structure-`
3	State Management	HIGH	`state-`
4	Cross-Contract Calls	MEDIUM-HIGH	`xcc-`
5	Gas Optimization	MEDIUM	`gas-`
6	Testing	MEDIUM	`testing-`
7	Best Practices	MEDIUM	`best-`

Quick Reference

1. Security & Safety (CRITICAL)

•security-storage-checks - Always validate storage operations
•security-access-control - Implement proper access control for sensitive functions
•security-reentrancy - Protect against reentrancy attacks
•security-overflow - Use checked arithmetic to prevent overflow
•security-callback-validation - Validate callback results and handle failures
•security-private-callbacks - Mark callbacks as private
•security-yoctonear-validation - Validate attached deposits

2. Contract Structure (HIGH)

•structure-near-bindgen - Use #[near_bindgen] macro for contract struct
•structure-initialization - Implement proper initialization patterns
•structure-versioning - Plan for contract upgrades with versioning
•structure-events - Emit events for important state changes
•structure-standards - Follow NEAR Enhancement Proposals (NEPs)

3. State Management (HIGH)

•state-collections - Use NEAR SDK collections (Vector, LookupMap, UnorderedMap, etc.)
•state-serialization - Use efficient serialization (Borsh)
•state-lazy-loading - Load state lazily to save gas
•state-pagination - Implement pagination for large datasets
•state-migration - Plan state migration strategies

4. Cross-Contract Calls (MEDIUM-HIGH)

•xcc-promise-chaining - Chain promises correctly
•xcc-callback-handling - Handle all callback scenarios (success, failure)
•xcc-gas-management - Allocate appropriate gas for cross-contract calls
•xcc-error-handling - Implement robust error handling
•xcc-result-unwrap - Never unwrap promise results without checks

5. Gas Optimization (MEDIUM)

•gas-batch-operations - Batch operations to reduce transaction costs
•gas-minimal-state-reads - Minimize state reads and writes
•gas-efficient-collections - Choose appropriate collection types
•gas-view-functions - Mark read-only functions as view
•gas-avoid-cloning - Avoid unnecessary cloning of large data

6. Testing (MEDIUM)

•testing-unit-tests - Write comprehensive unit tests
•testing-integration-tests - Use workspaces-rs for integration tests
•testing-simulation-tests - Test with near-sdk-sim or workspaces
•testing-edge-cases - Test boundary conditions and edge cases
•testing-gas-profiling - Profile gas usage in tests

7. Best Practices (MEDIUM)

•best-panic-messages - Provide clear panic messages
•best-logging - Use env::log_str for debugging
•best-documentation - Document public methods and complex logic
•best-error-types - Define custom error types
•best-constants - Use constants for magic numbers

How to Use

Read individual rule files for detailed explanations and code examples:

code

rules/security-storage-checks.md
rules/structure-near-bindgen.md

Each rule file contains:

•Brief explanation of why it matters
•Incorrect code example with explanation
•Correct code example with explanation
•Additional context and NEAR-specific considerations

Resources

•NEAR Documentation: https://docs.near.org
•NEAR SDK Rust: https://docs.near.org/sdk/rust/introduction
•NEAR Examples: https://github.com/near-examples
•NEAR Standards (NEPs): https://github.com/near/NEPs
•Security Best Practices: https://docs.near.org/develop/contracts/security/welcome

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md