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:

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