--- 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. Based on near-sdk v5.x with modern macro syntax. 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 (v5.x). ## 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 ## Getting Started ### Prerequisites Install the required tools before starting development: ```bash # 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 ``` ### Create a New Project > **CRITICAL**: ALWAYS run `cargo near new` to create new projects. NEVER manually create Cargo.toml, lib.rs, or any project files. The command generates all required files with correct configurations. ```bash # 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 ``` **Why `cargo near new` is mandatory:** - Generates correct `Cargo.toml` with proper dependencies and build settings - Creates proper project structure with `src/lib.rs` template - Includes integration test setup in `tests/` directory - Configures release profile with `overflow-checks = true` - Sets up correct crate-type for WASM compilation - Avoids common configuration mistakes that cause build failures **DO NOT:** - Manually create `Cargo.toml` - Manually create `src/lib.rs` - Copy-paste project structure from examples - Skip this step and create files directly ### Project Structure ``` my-contract/ ├── Cargo.toml # Dependencies and project config ├── src/ │ └── lib.rs # Main contract code ├── tests/ # Integration tests │ └── test_basics.rs └── README.md ``` ### Deploy to Testnet ```bash # 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 ``` ## 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 | Contract Upgrades | MEDIUM-HIGH | `upgrade-` | | 6 | Chain Signatures | MEDIUM-HIGH | `chain-` | | 7 | Gas Optimization | MEDIUM | `gas-` | | 8 | Yield & Resume | MEDIUM | `yield-` | | 9 | Testing | MEDIUM | `testing-` | | 10 | Best Practices | MEDIUM | `best-` | ### 1. Security & Safety (CRITICAL) - `security-storage-checks` - Always validate storage operations and check deposits - `security-access-control` - Implement proper access control using `predecessor_account_id` - `security-reentrancy` - Protect against reentrancy attacks (update state before external calls) - `security-overflow` - Use `overflow-checks = true` in Cargo.toml to prevent overflow - `security-callback-validation` - Validate callback results and handle failures - `security-private-callbacks` - Mark callbacks as `#[private]` to prevent external calls - `security-yoctonear-validation` - Validate attached deposits with `#[payable]` functions - `security-sybil-resistance` - Implement minimum deposit checks to prevent spam ### 2. Contract Structure (HIGH) - `structure-near-bindgen` - Use `#[near(contract_state)]` macro for contract struct (replaces old `#[near_bindgen]`) - `structure-initialization` - Implement proper initialization with `#[init]` patterns - `structure-versioning` - Plan for contract upgrades with versioning mechanisms - `structure-events` - Use `env::log_str()` and structured event logging (NEP-297) - `structure-standards` - Follow NEAR Enhancement Proposals (NEPs) for standards - `structure-serializers` - Use `#[near(serializers = [json, borsh])]` for data structs - `structure-panic-default` - Use `#[derive(PanicOnDefault)]` to require initialization ### 3. State Management (HIGH) - `state-collections` - Use SDK collections from `near_sdk::store`: `IterableMap`, `IterableSet`, `Vector`, `LookupMap`, `LookupSet`, `UnorderedMap`, `UnorderedSet`, `TreeMap` - `state-serialization` - Use Borsh for state, JSON for external interfaces - `state-lazy-loading` - Use SDK collections for lazy loading to save gas (loaded on-demand, not all at once) - `state-pagination` - Implement pagination with `.skip()` and `.take()` for large datasets - `state-migration` - Plan state migration strategies using versioning - `state-storage-cost` - Remember: 1 NEAR ≈ 100kb storage, contracts pay for their storage - `state-unique-prefixes` - Use unique byte prefixes for all collections (avoid collisions) - `state-native-vs-sdk` - Native collections (Vec, HashMap) load all data; use only for <100 entries ### 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. Contract Upgrades & Migration (MEDIUM-HIGH) - `upgrade-migration` - Use enums for state versioning and implement `migrate` method with `#[init(ignore_state)]` - `upgrade-self-update` - Pattern for contracts that can update themselves programmatically - `upgrade-cleanup-old-state` - Always remove old state structures to free storage - `upgrade-dao-controlled` - Use multisig or DAO for production upgrade governance ### 6. Chain Signatures (MEDIUM-HIGH) - `chain-signatures` - Derive foreign blockchain addresses, request MPC signatures, and build multichain transactions - `chain-callback-handling` - Handle MPC signature callbacks properly - `chain-gas-allocation` - Allocate sufficient gas for MPC calls (yield/resume pattern) ### 7. Gas Optimization (MEDIUM) - `gas-batch-operations` - Batch operations to reduce transaction costs - `gas-minimal-state-reads` - Minimize state reads and writes (cache in memory) - `gas-efficient-collections` - Choose appropriate collection types (LookupMap vs IterableMap) - `gas-view-functions` - Mark read-only functions as view (`&self` in Rust) - `gas-avoid-cloning` - Avoid unnecessary cloning of large data structures - `gas-early-validation` - Use `require!` early to save gas on invalid inputs - `gas-prepaid-gas` - Attach appropriate gas for cross-contract calls (recommended: 30 TGas) ### 8. Yield & Resume (MEDIUM) - `yield-resume` - Create yielded promises, signal resume, handle timeouts, and manage state between yield/resume - `yield-gatekeeping` - Protect resume methods from unauthorized callers ### 9. Testing (MEDIUM) - `testing-integration-tests` - Use `near-sandbox` + `near-api` for integration tests - `testing-unit-tests` - Write comprehensive unit tests with mock contexts - `testing-sandbox` - Test with local sandbox environment before testnet/mainnet - `testing-edge-cases` - Test boundary conditions, overflow, and empty states - `testing-gas-profiling` - Profile gas usage in integration tests - `testing-cross-contract` - Test cross-contract calls and callbacks thoroughly - `testing-failure-scenarios` - Test promise failures and timeout scenarios - `testing-time-travel` - Use `sandbox.fast_forward()` for time-sensitive tests ### 10. Best Practices (MEDIUM) - `best-contract-tools` - Use `near-sdk-contract-tools` for NEP standards (FT, NFT, etc.) and NEP-297 structured events - `best-panic-messages` - Provide clear, actionable panic messages - `best-logging` - Use `env::log_str()` for debugging and event emission - `best-documentation` - Document public methods, parameters, and complex logic - `best-error-types` - Define custom error types or use descriptive strings - `best-constants` - Use constants for magic numbers and configuration - `best-require-macro` - Use `require!` instead of `assert!` for better error messages - `best-promise-return` - Return promises from cross-contract calls for proper tracking - `best-sdk-crates` - Reuse SDK-exported crates (borsh, serde, base64, etc.) - `best-account-id-encoding` - Encode AccountIds in base32 for 40% storage savings ## How to Use Read individual rule files for detailed explanations and code examples: ``` 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 ``` 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 ## Latest Tools & Versions ### Development Tools - **cargo-near**: Latest - Build, deploy, and manage contracts (`cargo near build`, `cargo near deploy`) - **near-cli-rs**: Latest - Command-line interface for NEAR (`near contract call`, `near contract view`) - **rustc**: Latest stable - Rust compiler - **near-sandbox**: Latest - Local sandbox environment for integration testing - **near-api-rs**: Latest - Rust API client for interacting with NEAR (replaces near-workspaces-rs for tests) - **omni-transaction-rs**: Latest - Build transactions for multiple blockchains (Bitcoin, Ethereum, etc.) ### SDK Versions - **near-sdk-rs**: v5.x (v6.x coming with structured errors support) - **near-sdk-contract-tools**: Latest - Derive macros for NEP standards (FT, NFT, Storage Management) ### Key Features - **Unified macro syntax**: `#[near(contract_state)]` replaces `#[near_bindgen]` + derives - **Flexible serialization**: `#[near(serializers = [json, borsh])]` for data structs - **Store collections**: `near_sdk::store::IterableMap`, `IterableSet`, `LookupMap`, `LookupSet`, `Vector`, `UnorderedMap`, `UnorderedSet`, `TreeMap` - **Simplified cross-contract calls**: High-level promise API with `Promise::new()` and `.then()` - **Built-in NEP support**: FT (NEP-141), NFT (NEP-171), and other standards - **Result handling**: `#[handle_result]` for methods returning `Result` without panicking - **Yield/Resume**: Contracts can yield execution and wait for external services to resume - **Chain Signatures**: Sign transactions for other blockchains (Bitcoin, Ethereum, Solana, etc.) - **Contract Tools**: Derive macros for Owner, Pause, Role-based access control patterns ## Resources - NEAR Documentation: - Smart Contract Quickstart: - Contract Anatomy: - NEAR SDK Rust: - SDK Rust Reference: - Storage & Collections: - Best Practices: - Cross-Contract Calls: - Yield & Resume: - Contract Upgrades: - Chain Signatures: - Chain Signatures Implementation: - Security Best Practices: - Integration Testing: - NEP-297 Events: - NEAR Standards (NEPs): - NEAR Examples: - Sandbox Testing: - NEAR API Rust: - Omni Transaction RS: - Contract Tools: ## Storage Costs Reference | Storage | Cost | Notes | |---------|------|-------| | 1 byte | 0.00001 NEAR | ~10kb per 0.1 NEAR | | 100 KB | ~1 NEAR | Approximate reference | | AccountId | 64+ bytes | Can save 40% with base32 encoding | | Contract code | Variable | Paid by contract account | ## SDK Collections Reference | Collection | Iterable | Clear | Ordered | Range | Use Case | |------------|----------|-------|---------|-------|----------| | `Vector` | Yes | Yes | Yes | Yes | Ordered list with index access | | `LookupMap` | No | No | No | No | Fast key-value, no iteration needed | | `LookupSet` | No | No | No | No | Fast membership checks | | `IterableMap` | Yes | Yes | Yes | No | Key-value with iteration | | `IterableSet` | Yes | Yes | Yes | No | Set with iteration | | `UnorderedMap` | Yes | Yes | No | No | Key-value, unordered iteration | | `UnorderedSet` | Yes | Yes | No | No | Set, unordered iteration | | `TreeMap` | Yes | Yes | Yes | Yes | Sorted key-value with range queries |