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

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