near-smart-contracts

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:

# 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.

# 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

# 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<T, E> 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: https://docs.near.org
• Smart Contract Quickstart: https://docs.near.org/smart-contracts/quickstart
• Contract Anatomy: https://docs.near.org/smart-contracts/anatomy/
• NEAR SDK Rust: https://docs.near.org/tools/sdk
• SDK Rust Reference: https://docs.rs/near-sdk
• Storage & Collections: https://docs.near.org/smart-contracts/anatomy/collections
• Best Practices: https://docs.near.org/smart-contracts/anatomy/best-practices
• Cross-Contract Calls: https://docs.near.org/smart-contracts/anatomy/crosscontract
• Yield & Resume: https://docs.near.org/smart-contracts/anatomy/yield-resume
• Contract Upgrades: https://docs.near.org/smart-contracts/release/upgrade
• Chain Signatures: https://docs.near.org/chain-abstraction/chain-signatures
• Chain Signatures Implementation: https://docs.near.org/chain-abstraction/chain-signatures/implementation
• Security Best Practices: https://docs.near.org/smart-contracts/security/welcome
• Integration Testing: https://docs.near.org/smart-contracts/testing/integration-test
• NEP-297 Events: https://github.com/near/NEPs/blob/master/neps/nep-0297.md
• NEAR Standards (NEPs): https://github.com/near/NEPs
• NEAR Examples: https://github.com/near-examples
• Sandbox Testing: 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
• Contract Tools: https://github.com/near/near-sdk-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 |