Crate near_sdk

Expand description

§`near-sdk`

near-sdk is a Rust toolkit for developing smart contracts on the NEAR blockchain.
It provides abstractions, macros, and utilities to make building robust and secure contracts easy. More information on how to develop smart contracts can be found in the NEAR documentation. With near-sdk you can create DeFi applications, NFTs and marketplaces, DAOs, gaming and metaverse apps, and much more.

§Features

State Management: Simplified handling of contract state with serialization via Borsh or JSON.
Initialization methods We can define an initialization method that can be used to initialize the state of the contract. #[init] macro verifies that the contract has not been initialized yet (the contract state doesn’t exist) and will panic otherwise.
Payable methods We can allow methods to accept token transfer together with the function call with #[payable] macro.
Private methods #[private] macro makes it possible to define private methods that can’t be called from the outside of the contract.
Cross-Contract Calls: Support for asynchronous interactions between contracts.
Unit Testing: Built-in support for testing contracts in a Rust environment.
WASM Compilation: Compile Rust code to WebAssembly (WASM) for execution on the NEAR runtime.

§Quick Start

Add near-sdk to your Cargo.toml:

[dependencies]
near-sdk = "5.6.0"

§Example: Counter Smart Contract

Below is an example of a simple counter contract that increments and retrieves a value:

use near_sdk::{env, near};

#[near(contract_state)]
#[derive(Default)]
pub struct Counter {
    value: i32,
}

#[near]
impl Counter {
    /// Increment the counter by one.
    pub fn increment(&mut self) {
        self.value += 1;
        env::log_str(&format!("Counter incremented to: {}", self.value));
    }

    /// Get the current value of the counter.
    pub fn get(&self) -> i32 {
        self.value
    }
}

§Compiling to WASM

Install cargo near in case if you don’t have it:

cargo install --locked cargo-near

Build your contract for the NEAR blockchain:

cargo near build

§Running Unit Tests

Use the following testing setup:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn increment_works() {
        let mut counter = Counter::default();
        counter.increment();
        assert_eq!(counter.get(), 1);
    }
}

Run tests using:

cargo test

Re-exports§

pub use near_sys as sys;
pub use base64;
pub use borsh;
pub use bs58;
pub use schemars;
pub use serde;
pub use serde_json;
pub use crate::utils::*;

Modules§

collections: Collections that offer an alternative to standard containers from std::collections::* by utilizing the underlying blockchain trie storage more efficiently.
env: Blockchain-specific methods available to the smart contract that allow to interact with NEAR runtime. This is a wrapper around a low-level near_sys. Unless you know what you are doing prefer using env::* whenever possible. In case of cross-contract calls prefer using even higher-level API available through callback_args, callback_args_vec, ext_contract, Promise, and PromiseOrValue.
json_types: Helper types for JSON serialization.
mock: Mock blockchain utilities. These can only be used inside tests and are not available for a wasm32 target.
near: #[near] and #[near_bindgen] documentation module
store: Collections and types used when interacting with storage.
test_utils: Testing blockchain utilities. These can only be used inside tests and are not available for a wasm32 target.
utils: Helper methods that often used in smart contracts.

Macros§

log: Helper macro to log a message through env::log_str. This macro can be used similar to the std::format macro.
require: Helper macro to create assertions that will panic through the runtime host functions.
setup_allocDeprecated: Deprecated helper function which used to generate code to initialize the GlobalAllocator. This is now initialized by default. Disable wee_alloc feature to configure manually.
testing_env: Initializes a testing environment to mock interactions which would otherwise go through a validator node. This macro will initialize or overwrite the MockedBlockchain instance for interactions from a smart contract.

Structs§

Abort: A simple type used in conjunction with FunctionError representing that the function should abort without a custom message.
AccountId: NEAR Account Identifier.
AccountIdRef: Account identifier. This is the human readable UTF-8 string which is used internally to index accounts on the network and their respective state.
Gas: A wrapper struct for u64 that represents gas. And provides helpful methods to convert to and from tera-gas and giga-gas.
GasWeight: Weight of unused gas to use with promise_batch_action_function_call_weight.
MockedBlockchain: Mocked blockchain that can be used in the tests for the smart contracts. It implements BlockchainInterface by redirecting calls to VMLogic. It unwraps errors of VMLogic to cause panic during the unit tests similarly to how errors of VMLogic would cause the termination of guest program execution. Unit tests can even assert the expected error message.
NearToken: A wrapper struct for u128 that represents tokens. And provides helpful methods to convert with a proper precision.
Promise: A structure representing a result of the scheduled execution on another contract.
PromiseIndex: Promise index that is computed only once. It is an internal index that identifies a specific promise (or a sequence of promises) created during the execution of a smart contract. Returned by promise_create and can be used to refer this promise in promise_then, promise_batch_create, and other functions. Example:
PublicKey: Public key in a binary format with base58 string serialization with human-readable curve. The key types currently supported are secp256k1 and ed25519.
RuntimeFeesConfig
VMContext: Context for the contract execution.

Enums§

Allowance: Allow an access key to spend either an unlimited or limited amount of gas
CurveType: PublicKey curve
PromiseError: All error variants which can occur with promise results.
PromiseOrValue: When the method can return either a promise or a value, it can be called with PromiseOrValue::Promise or PromiseOrValue::Value to specify which one should be returned.
PromiseResult: When there is a callback attached to one or more contract calls the execution results of these calls are available to the contract invoked through the callback.
ReturnData
VmPromiseResult: When there is a callback attached to one or more contract calls the execution results of these calls are available to the contract invoked through the callback.

Traits§

FunctionError: Enables contract runtime to panic with the given type. Any error type used in conjunction with #[handle_result] has to implement this trait.
IntoStorageKey: Converts Self into a Vec<u8> that is used for a storage key through into_storage_key.

Functions§

test_vm_config

Type Aliases§

BlockHeight: Height of the block.
BlockHeightDeltaDeprecated: Block height delta that measures the difference between BlockHeights.
CryptoHash: Raw type for 32 bytes of the hash.
Duration: Raw type for duration in nanoseconds
EpochHeight: Height of the epoch.
GCCountDeprecated
IteratorIndexDeprecated
MerkleHashDeprecated: Hash used by a struct implementing the Merkle tree.
NonceDeprecated: Nonce for transactions.
NumBlocksDeprecated: Number of blocks in current group.
NumSeatsDeprecated: Number of seats of validators (block producer or hidden ones) in current group (settlement).
NumShardsDeprecated: Number of shards in current group.
PromiseIdDeprecated
ProtocolVersionDeprecated
ReceiptIndexDeprecated: An index of Receipt to append an action
ShardIdDeprecated: Shard index, from 0 to NUM_SHARDS - 1.
StorageUsage: StorageUsage is used to count the amount of storage used by a contract.
StorageUsageChangeDeprecated: StorageUsageChange is used to count the storage usage within a single contract call.
Timestamp: Raw type for timestamp in nanoseconds
ValidatorIdDeprecated: Validator identifier in current group.
ValidatorMaskDeprecated: Mask which validators participated in multi sign.

Attribute Macros§

ext_contract: ext_contract takes a Rust Trait and converts it to a module with static methods. Each of these static methods takes positional arguments defined by the Trait, then the receiver_id, the attached deposit and the amount of gas and returns a new Promise.
near: This attribute macro is used on a struct and its implementations to generate the necessary code to expose pub methods from the contract as well as generating the glue code to be a valid NEAR contract.
near_bindgen: This macro is deprecated. Use #[near] instead. The difference between #[near] and #[near_bindgen] is that with #[near_bindgen] you have to manually add boilerplate code for structs and enums so that they become Json- and Borsh-serializable:

Derive Macros§

BorshStorageKey: BorshStorageKey generates implementation for BorshIntoStorageKey trait. It allows the type to be passed as a unique prefix for persistent collections. The type should also implement or derive BorshSerialize trait.
EventMetadata: NOTE: This is an internal implementation for #[near_bindgen(events(standard = ...))] attribute.
FunctionError: FunctionError generates implementation for near_sdk::FunctionError trait. It allows contract runtime to panic with the type using its ToString implementation as the message.
NearSchema: NearSchema is a derive macro that generates BorshSchema and / or JsonSchema implementations. Use #[abi(json)] attribute to generate code for JsonSchema. And #[abi(borsh)] for BorshSchema. You can use both and none as well.
PanicOnDefault: PanicOnDefault generates implementation for Default trait that panics with the following message The contract is not initialized when default() is called. This is a helpful macro in case the contract is required to be initialized with either init or init(ignore_state).

Crate near_sdkCopy item path

§near-sdk