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

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:

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