Building on NEAR Protocol
A comprehensive developer's guide to the sharded, scalable blockchain.
Learn how to leverage NEAR's Nightshade sharding, developer-friendly account model, and support for Rust & AssemblyScript to build next-generation dApps.
In This Guide
What is NEAR Protocol?
A sharded, proof-of-stake, layer-one blockchain designed for usability and scalability.
Scalable via Sharding
NEAR uses Nightshade sharding, allowing the network to scale linearly with the number of shards. Each shard processes transactions in parallel, significantly increasing throughput and keeping fees low as usage grows.
Why Build on NEAR?
Developers choose NEAR for its scalability, developer-friendly tools (Rust & AssemblyScript SDKs, robust CLI), unique account model (human-readable names, flexible keys), predictable gas costs, and focus on user experience (e.g., contract-paid gas).
Architecture Highlights
Key components include Nightshade sharding, Doomslug consensus for fast block production, a Wasm-based runtime, a unique account model with multiple access keys, and built-in interoperability features like the Rainbow Bridge.
Development Ecosystem
NEAR offers SDKs for Rust and AssemblyScript (compiles to Wasm), a powerful command-line interface (NEAR CLI), extensive documentation, testing tools (Workspaces), and integrations like Gitpod for easy onboarding.
Understanding NEAR's Architecture
The technical components powering the NEAR Protocol.
Core Components & Concepts
Key building blocks and unique aspects of NEAR
Nightshade Sharding
Parallel processing across multiple shards ('chunks') enabling high throughput and scalability.
Flexible Account Model
Human-readable account names (`.near`), subaccounts, and multiple access keys (FullAccess, FunctionCall) per account enhance usability and security.
Rust & AssemblyScript SDKs
Robust Software Development Kits for writing Wasm smart contracts in popular, memory-safe languages.
Predictable Gas Fees
Gas units (TGas) and stable pricing make transaction cost estimation reliable. Option for contracts to cover user gas fees.
Asynchronous Cross-Contract Calls
Enables complex interactions between contracts, even across shards, using a callback-based model.
Rainbow Bridge
A trustless, permissionless bridge connecting NEAR with Ethereum, allowing asset transfers (ERC20s, ETH, NFTs) and cross-chain contract calls.
Aurora (EVM Compatibility)
An EVM implementation built as a smart contract on NEAR, allowing Ethereum dApps to run seamlessly on NEAR with lower fees and higher speeds.
Proof-of-Stake (PoS)
Validators stake NEAR tokens to participate in consensus (Doomslug/Nightshade), securing the network and earning rewards. Delegators can stake with validators.
Building on NEAR
Key steps and considerations for dApp development
Prerequisites
Familiarity with Rust or TypeScript/AssemblyScript. Node.js and npm/yarn installed. Basic understanding of blockchain concepts and Wasm.
Setup Environment
Install NEAR CLI (`npm install -g near-cli`). Set up Rust toolchain (`rustup`) or AssemblyScript environment. Log in using `near login` to create/manage accounts.
Account Management
Create NEAR accounts (TestNet/MainNet) using NEAR Wallet or NEAR CLI. Understand FullAccess vs. FunctionCall keys for deploying contracts and interacting with dApps.
Write Smart Contracts
Develop your contract logic using the `near-sdk-rs` (Rust) or `near-sdk-js` (AssemblyScript). Define state, public methods, initialization, callbacks, and events.
Compile to Wasm
Compile your Rust or AssemblyScript code into a WebAssembly (`.wasm`) binary file using standard build commands (`cargo build --target wasm32-unknown-unknown --release` or `npm run build`).
Testing
Write unit tests within your Rust/AS project. Use NEAR Workspaces (Rust or JS) for simulation testing, allowing interaction testing between multiple contracts and accounts in a controlled environment.
Deployment
Deploy the compiled `.wasm` file to a NEAR account (TestNet first) using `near deploy`. Initialize the contract state if required by calling its initialization method.
Frontend Integration
Use `near-api-js` library in your web frontend (React, Vue, etc.) to connect to user wallets (NEAR Wallet, Sender, etc.), query contract state (view calls), and send transactions (change calls).
Gas & Storage Management
Attach gas for function calls and deposit NEAR for storage usage (storage staking). Optimize contracts to minimize gas and storage costs. Understand the implications of attached deposits.
Security Audits
For contracts handling significant value, obtain security audits from firms familiar with NEAR's architecture, Rust/AS, and potential pitfalls like storage management or async call complexities.
Smart Contract Development
Building with Rust & AssemblyScript on NEAR
Development Tools
Essential tools for building on NEAR Protocol
NEAR CLI
The primary command-line interface for interacting with the NEAR network: creating accounts, deploying contracts, calling methods, managing keys, querying state.
SDKs (Rust & AssemblyScript)
`near-sdk-rs` and `near-sdk-js` provide the necessary libraries, macros, and types for writing NEAR smart contracts in Rust and AssemblyScript.
near-api-js
JavaScript/TypeScript library for frontend and backend development, enabling interaction with NEAR accounts, contracts, and the network via RPC.
NEAR Workspaces (Rust & JS)
Testing frameworks for running simulation tests. Allows scripting interactions between multiple contracts and accounts in a local, deterministic environment.
NEAR Wallet
The official web-based wallet for managing NEAR accounts, keys, staking, and authorizing dApp transactions.
NEAR Explorer
Block explorer for viewing transactions, blocks, accounts, contract interactions, and network status on NEAR MainNet, TestNet, and BetaNet.
Gitpod / Codespaces
Cloud-based development environments pre-configured for NEAR development, allowing developers to start coding quickly without local setup.
NEAR Examples
A repository of official example contracts and applications demonstrating various features and patterns on NEAR.
Testing & Deployment
Best practices for validating and launching NEAR applications
Cross-Chain Functionality
Connecting NEAR to other ecosystems
Rainbow Bridge
NEAR's flagship bridge providing trustless and permissionless connectivity with Ethereum. Supports transfer of ETH, ERC20s, NFTs, and arbitrary data, enabling cross-chain contract calls. Secured by light clients on both chains.
Aurora (EVM on NEAR)
An Ethereum Virtual Machine implemented as a smart contract on NEAR. Allows developers to deploy Solidity contracts and users to interact with Ethereum dApps using familiar tools (MetaMask) while benefiting from NEAR's performance and low fees.
Octopus Network
A multichain network built on NEAR, providing shared security and interoperability for application-specific blockchains (appchains). Appchains lease security from Octopus validators staking OCT tokens.
Allbridge / Wormhole / LayerZero
Integration with third-party generic messaging and bridging protocols enables connectivity with a wider range of blockchains beyond Ethereum, facilitating asset transfers and potential cross-chain interactions.
Cross-Chain Asset Wrapping
Assets from other chains (e.g., BTC, stablecoins) are often brought onto NEAR (and Aurora) as wrapped tokens via bridges, enabling their use within NEAR's DeFi ecosystem.
Future Developments
Ongoing research and development focus on improving existing bridges, potentially developing new native bridges, and enhancing cross-shard and cross-chain communication protocols for better efficiency and security.
Governance & Economics
Decision-making and tokenomics in the NEAR ecosystem
Security Best Practices
Protecting your applications on NEAR Protocol
Access Key Management
Understand the difference between FullAccess keys (can do anything) and FunctionCall keys (limited scope). Use FunctionCall keys for dApp interactions whenever possible to minimize risk if a key is compromised.
Contract Audits
Essential for NEAR contracts handling value. Engage auditors experienced with Rust/AS, Wasm, and NEAR's specific features like async calls, gas model, and storage staking.
Secure Coding (Rust/AS)
Follow language best practices (e.g., avoid `unsafe` in Rust unless necessary). Validate inputs, check permissions (`predecessor_account_id`, `signer_account_id`), handle errors properly, and prevent integer overflows/underflows.
Storage Staking Awareness
Ensure users or contracts attach sufficient deposit to cover storage costs associated with state changes. Malicious actors might try to fill contract storage to cause issues; implement checks and limits.
Asynchronous Call Safety
Be mindful of state changes between initiating a cross-contract call and receiving its callback. Implement checks in callbacks to ensure consistency. Avoid patterns susceptible to reentrancy-like issues in the async model.
Gas Management
Explicitly specify gas limits for cross-contract calls. Be aware that insufficient gas can cause calls or callbacks to fail. Protect against gas-related Denial-of-Service attacks.
Testing
Thorough unit and simulation testing (Workspaces) is critical to catch logic errors, security flaws, and issues related to async calls or storage management before deployment.
Dependency Management
Keep SDKs and libraries updated, but carefully vet dependencies for potential vulnerabilities.
Real-World Examples
Prominent projects and use cases on NEAR Protocol
Aurora: EVM Compatibility Layer
An EVM built as a NEAR smart contract, enabling seamless deployment and interaction with Ethereum dApps while leveraging NEAR's performance. Hosts its own ecosystem of DeFi and NFT projects.
Ref Finance: DeFi Hub
A major Automated Market Maker (AMM) and DeFi platform native to NEAR. Offers token swaps, liquidity provision, yield farming, and a launchpad, showcasing NEAR's capabilities for DeFi.
Paras: NFT Marketplace
A popular NFT marketplace focused on digital art cards and collectibles, built natively on NEAR. Demonstrates NEAR's suitability for handling NFT minting, trading, and ownership efficiently.
Sweat Economy: Move-to-Earn
A large-scale Web3 application rewarding users for physical activity. Initially built on NEAR, showcasing the protocol's ability to handle high transaction volumes from mainstream applications.
Octopus Network: Appchain Infrastructure
Provides infrastructure for launching application-specific blockchains (appchains) secured by NEAR. Offers flexibility and customization for projects needing their own chain environment.
NEAR Social (BOS): Decentralized Frontend
A platform for building and discovering decentralized frontends stored directly on NEAR. Enables composable Web3 applications and community-owned social experiences.
Future of NEAR Protocol
Upcoming developments and the roadmap for the ecosystem
Frequently Asked Questions
Common questions about developing on NEAR Protocol
Additional Resources
Essential links and tools for NEAR developers
NEAR Documentation
Official comprehensive documentation covering concepts, tutorials, SDKs, and APIs.
NEAR Examples
Official repository of example contracts and applications.
NEAR University
Educational resources, courses, and certifications for learning NEAR development.
NEAR Explorer
Block explorer for NEAR MainNet, TestNet, and BetaNet.
NEAR Wallet
Official web wallet for managing accounts and interacting with dApps.
NEAR CLI Documentation
Reference guide for the NEAR Command Line Interface.
near-api-js Documentation
Documentation for the JavaScript library for frontend/backend integration.
Rust SDK Book
Detailed documentation for the NEAR Rust SDK (`near-sdk-rs`).
AssemblyScript SDK Docs
Documentation for the NEAR AssemblyScript SDK (`near-sdk-js`).
NEAR Discord
Community hub for discussions, support, and announcements.
Ready to Build on NEAR?
Take the next steps in your NEAR Protocol development journey.