Basic Counter Example

At its core, the NEAR blockchain is a big database. A contract is a program with its own storage space, commonly called "contract storage" or "on-chain storage." You have access to read and write to this storage like you would any key/value data structure.

The simplest example of this is a counter. A contract that can read, increment, and decrement a value.

To follow along, use VS Code to open the contracts/counter folder inside the raen-examples project that you cloned in Getting Set Up. Then open src/lib.rs. We'll walk through this code in order.

Docs & Imports

The \\! lines at the top are container documentation comments you can use to document a whole contract/module/crate.

The use lines import dependencies, like import or require in JavaScript. Look in Cargo.toml to see that kebab-case crate names like near-sdk are turned into snake-case names like near_sdk in the code. Let's learn more about these specific imports by seeing how they're used.

State Shape

Rust's type system gives us a way to tell NEAR's Runtime how our contract's state is shaped. If you're following along, look for the struct definition on line 10:

pub struct Counter {
    val: i8,
}

About this:

Ok, straightforward enough.

But if you're actually looking at the code in your own editor, you're probably wondering about the stuff right above pub struct Counter:

#[near_bindgen]
#[derive(Default, BorshDeserialize, BorshSerialize)]
pub struct Counter {
    val: i8,
}

These are called macros. Macros are Rust's way of generating extra code. This kind of "hash bracket" macro (#[...]) will expand the definition of the thing that follows, adding extra logic to save you from needing to copy-paste boilerplate.

(The other kind of Rust macro looks like a function, but has an exclamation mark, like log!(...). You'll see this soon.)

Here's what these macros are doing:

impl ::core::default::Default for Counter {
    #[inline]
    fn default() -> Counter {
        Counter {
            val: ::core::default::Default::default(),
        }
    }
}
impl borsh::de::BorshDeserialize for Counter
where
    i8: borsh::BorshDeserialize,
{
    fn deserialize(buf: &mut &[u8]) -> ::core::result::Result<Self, borsh::maybestd::io::Error> {
        Ok(Self {
            val: borsh::BorshDeserialize::deserialize(buf)?,
        })
    }
}
impl borsh::ser::BorshSerialize for Counter
where
    i8: borsh::ser::BorshSerialize,
{
    fn serialize<W: borsh::maybestd::io::Write>(
        &self,
        writer: &mut W,
    ) -> ::core::result::Result<(), borsh::maybestd::io::Error> {
        borsh::BorshSerialize::serialize(&self.val, writer)?;
        Ok(())
    }
}

Borsh?

The data in your contract and, indeed, your contract itself, need to be stored on-disk in between calls to your contract.

Then when a NEAR user makes a call to your contract, validators' computers need to fetch your contract from storage, load it into memory, check how your contract's storage is shaped, then finally deserialize your contract storage and execute the call.

Borsh is a serialization specification (a way of representing data as bytes) developed and maintained by the nearcore team, because nothing else was good enough when NEAR started. The biggest problem with other serialization standards was a lack of consistency—the same in-memory object could be represented in multiple valid ways as bytes.

You'll see Borsh used in a couple different ways in NEAR contracts. The most common is here—as the serialization format for your contract data.

Methods

To attach methods to a struct in Rust, use an impl.

A View Method

Let's start by looking at the view method starting on line 17:

impl Counter {
    /// Public method: Returns the counter value.
    pub fn get_num(&self) -> i8 {
        self.val
    }
    ...
}

Go ahead and play with this a bit. Do things that don't make sense, and your well-configured editor will yell at you. Looking at the errors will teach you about how Rust works. You can try each of these things, changing it back to how it was after each:

• Change -> i8 to -> i16
• Change -> i8 to -> (), an empty tuple
• Remove -> i18 – note that you get the same error message as when you changed it to an empty tuple! Empty tuple is one of the closest things Rust has to a void type.
• Change self.val to self.val;
• Change self.val to return self.val; and it will behave the same way as self.val with no semicolon. Note that this is super non-idiomatic! No one writes Rust this way. Get used to paying attention to the presence & lack of semicolons.

A Change Method

Next let's see how to mutate or change val. Look at the increment method starting on line 22:

impl Counter {
    ...

    /// Public method: Increment the counter.
    pub fn increment(&mut self) -> i8 {
        self.val += 1;
        log!("Increased number to {}", self.val);
        self.val
    }
  
    ...
}

Digging Deeper: Result Serialization

Look again at the view function get_num. It returns an i8. However, any call to a NEAR contract happens via Remote Procedure Calls, and this i8 needs to be serialized into something the consumer can read. By default, near_bindgen generates code to serialize it into a JSON number, since this is the most common case, e.g. a web app calling get_num. If you really need to, you can override this setting. For example, this would serialize it to Borsh instead:

#[result_serializer(borsh)]
pub fn get_num(&self) -> i8 {
    self.val
}

Serializing to Borsh can be useful in a couple cases:

• gas-intensive contract methods that need to optimize every detail
• methods only used in cross-contract call logic, where no external consumers are expected or allowed

However, most of the time you will probably want to stick with the default JSON result serialization, to make it easier for apps to interact with your contract.

Summary

In this unit we saw our first NEAR smart contract. We were introduced to some Rust basics, like its type system, numbers, struct, documentation comments, and (im)mutability. We saw how NEAR works with Rust to generate code for you using macros, leaving your code clean and focused on your own logic, rather than various boilerplate.

Next, we'll build the contract with raen and interact with it using RAEN Admin.