playbooks

home / skills / near / agent-skills / near-smart-contracts

near-smart-contracts skill

/skills/near-smart-contracts

This skill helps you write, review, and deploy NEAR smart contracts in Rust, covering security, state management, and cross-contract patterns.

npx playbooks add skill near/agent-skills --skill near-smart-contracts

Review the files below or copy the command above to add this skill to your agents.

Files (6)
SKILL.md
4.6 KB
---
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

| 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 | Gas Optimization | MEDIUM | `gas-` |
| 6 | Testing | MEDIUM | `testing-` |
| 7 | Best Practices | MEDIUM | `best-` |

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

Overview

This skill provides practical guidance for developing, reviewing, and deploying NEAR Protocol smart contracts in Rust using the NEAR SDK. It focuses on secure contract structure, robust state management, safe cross-contract calls, testing strategies, and gas optimization. The content is organized as prioritized rules and actionable patterns you can apply directly to code and reviews.

How this skill works

The skill inspects contract design and implementation patterns against a prioritized rule set covering security, structure, state, cross-contract calls, gas, testing, and general best practices. For each rule it explains why it matters, shows incorrect and corrected examples, and lists NEAR-specific considerations. Use it while authoring code, performing security reviews, writing tests, or preparing deployments to catch common pitfalls and improve performance.

When to use it

  • Writing new NEAR smart contracts in Rust
  • Reviewing or auditing existing NEAR contracts for security and correctness
  • Implementing and testing cross-contract calls and callbacks
  • Designing state layout, migrations, and gas-efficient collections
  • Optimizing gas usage and profiling contract performance
  • Preparing unit, integration, and simulation tests for deployment

Best practices

  • Prioritize security rules: storage validation, access control, reentrancy protection, and checked arithmetic
  • Use #[near_bindgen], clear initialization patterns, and semantic versioning for upgrades
  • Prefer NEAR SDK collections (LookupMap, UnorderedMap, Vector) and Borsh serialization for compact state
  • Handle all promise results; validate callbacks and mark internal callbacks private
  • Minimize reads/writes, batch operations, and avoid unnecessary cloning to save gas
  • Write unit, integration, and simulation tests and include gas profiling and edge-case scenarios

Example use cases

  • Implement a token or marketplace contract with clear access control, events, and versioning
  • Review a legacy contract to add storage checks, state migration, and improved collections
  • Design cross-contract payment flows with properly chained promises and validated callbacks
  • Refactor a contract to reduce gas by batching updates and switching to more efficient collections
  • Create comprehensive tests using workspaces-rs or near-sdk-sim including gas profiling and edge cases

FAQ

How do I prevent reentrancy in NEAR contracts?

Structure mutable state changes before issuing cross-contract calls, use private callbacks, and validate callback outcomes to avoid unsafe reentrancy paths.

Which collections should I use for large datasets?

Choose UnorderedMap or Vector for bulk storage and LookupMap for keyed access; implement pagination and lazy loading to minimize gas for reads.

How should I handle promise results?

Never unwrap promise results unconditionally. Implement robust callback handling that checks success/failure and reacts accordingly, refunding or reverting as needed.