near-contract-tools

Helpful functions and macros for developing smart contracts on NEAR Protocol.

This package is a collection of common tools and patterns in NEAR smart contract development:

• Storage fee management
• Owner pattern (derive macro available)
• Role-based access control
• Pause (derive macro available)
• Derive macro for NEP-297 events
• Derive macro for NEP-141 (and NEP-148) fungible tokens

Not to be confused with near-contract-standards, which contains official implementations of standardized NEPs. This crate is intended to be a complement to near-contract-standards.

WARNING: This is still early software, and there may be breaking changes between versions. I'll try my best to keep the docs & changelogs up-to-date. Don't hesitate to create an issue if find anything wrong.

Examples

See also: the full integration tests.

Owner

```rust use nearsdk::{nearbindgen, AccountId}; use nearcontracttools::{owner::Owner, Owner};

[derive(Owner)]

[near_bindgen]

struct Contract { // ... }

[near_bindgen]

impl Contract { #[init] pub fn new(owner_id: AccountId) -> Self { let contract = Self { // ... };

    Owner::init(&contract, &owner_id);

    contract
}

pub fn owner_only(&self) {
    Self::require_owner();

    // ...
}

} ```

The Owner derive macro exposes the following methods to the blockchain:

rust fn own_get_owner(&self) -> Option<AccountId>; fn own_get_proposed_owner(&self) -> Option<AccountId>; fn own_renounce_owner(&mut self); fn own_propose_owner(&mut self, account_id: Option<AccountId>); fn own_accept_owner(&mut self);

Events

```rust use nearcontracttools::event::*; use nearcontracttools::Event; use serde::Serialize;

[derive(Serialize)]

pub struct Nep171NftMintData { pub ownerid: String, pub tokenids: Vec, }

[derive(Event, Serialize)]

[event(standard = "nep171", version = "1.0.0")]

[serde(untagged)]

pub enum Nep171 { #[event(name = "nft_mint")] NftMint(Vec), }

let myevent = Nep171::NftMint(vec![Nep171NftMintData { ownerid: "owner".tostring(), tokenids: vec!["token1".tostring(), "token2".tostring()], }]);

my_event.emit(); // Emits event to the blockchain ```

Fungible Token

To create a contract that is compatible with the NEP-141 and NEP-148 standards, that emits standard-compliant (NEP-141, NEP-297) events.

```rust use nearcontracttools::FungibleToken; use nearsdk::nearbindgen;

[derive(FungibleToken)]

[fungible_token(

name = "My Fungible Token",
symbol = "MYFT",
decimals = 18,
no_hooks

)]

[near_bindgen]

struct FungibleToken { // ... } ```

Standalone macros for each individual standard also exist.

Macro Combinations

One may wish to combine the features of multiple macros in one contract. All of the macros are written such that they will work in a standalone manner, so this should largely work without issue. However, sometimes it may be desirable for the macros to work in combination with each other. For example, to make a fungible token pausable, use the fungible token hooks to require that a contract be unpaused before making a token transfer:

```rust use nearcontracttools::{ pause::Pause, standard::nep141::{Nep141Hook, Nep141Transfer}, FungibleToken, Pause, }; use nearsdk::nearbindgen;

[derive(FungibleToken, Pause)]

[fungible_token(name = "Pausable Fungible Token", symbol = "PFT", decimals = 18)]

[near_bindgen]

struct Contract {}

impl Nep141Hook for Contract { fn beforetransfer(&mut self, _transfer: &Nep141Transfer) { Contract::requireunpaused(); } } ```

Note: Hooks can be disabled using #[nep141(no_hooks)] or #[fungible_token(no_hooks)].

Authors

• Jacob Lindahl @sudo_build