[Report] Tutorial Repository for developing Near Contracts in Rust (april 01-> april 30 2022)

Education Fellowships
1

Project Title: New Full Tutorial for Near in Rust.

One-liner: Tutorial Repository for developing Near Contracts in Rust

Project Summary: : There are many great tutorials about creating NEAR contracts in Rust. This project isn’t intended to be a replacement to any of those. Instead, it will be detailed examples about the features of Rust using NEAR contracts. Several times when the compiler gives an error, a new developer may feel compelled to just try making changes until the error go away.

This tutorial will show all possible implementations for all kinds of features in rust. Including ownership, modules, traits, generics, enums and so on. That way it can work as reference for aspiring rustaceans.

Project Members: Lucas Lemos, Matias Wald

Period: April 01 → April 30

Extra : Project is written in Brazilian Portuguese. Translations to English and Spanish are also being made by Matias Wald.

The following list are the results obtained by me:

Week 09

  • Lesson 6-2 is being replaced by a more practical example. It’s a contract for storing data from thermal sensors, or thermometers. Still unfinished. Link: https://github.com/On0n0k1/Tutorial_NEAR_Rust/commit/288c87a51e54b274a7024ed0a22a02d817ee5cc1
  • The purpose of the contract is to show how we can use enums to control how data input/output/storage works. Some examples of use are described below:
    • We can use it to make some arguments of a function optional.
    • We can make a function receive more than one type as argument.
    • We can make an enum be treated as a primitive type. E.g. something like This::Value(String) could be displayed/returned as just String. Therefore we can make the return type of a function be several different types simultaneously.
  • Someone could use the contract to store the data from several different sensors simultaneously. Only to later collect them into a local storage. It’s a cheap way to synchronize several different devices without paying for expensive cloud services.
  • A real application project could be more interesting to readers. So, as long as it is well structured and explained, this example will be worthwhile.

Week 10

  • Finished writing the code for lesson 6-2 thermometer. Need to write unit tests and the lesson Readme next. But this lesson is looking really good. Here are the topics it show:
    • Using enum to manage input/output for functions;
    • Using serde to manage how data is stored/displayed;
    • Storing data in trie using LookupMap, Vector and UnorderedSet;
    • Managing user access and permissions in the contract. “Who can access what”;
    • Adding functionality to custom types by implementing standard library traits. E.g. From , std::fmt::Display , Default , PartialEq , Eq .
  • After finished with this lesson’s unit tests, documentation and lesson Readme, I’m considering sending it as an example for NEAR University Learn NEAR repository group;
  • I created this contract with the intent of it being practical and usable in production environment. Just compile my project and use it for your embedded devices as you please. Making whatever changes you need (It’s MIT License).

Here’s a summary of how the contract works:

  • Deploy your contract to one of your accounts;
  • Create one NEAR account for each of your embedded devices;
  • Only the owner is allowed to make function calls on the contract. But you can allow other accounts by calling the function allow_user '{"account_id": "your-contract-name.testnet"}' .
  • Each allowed user has it’s own Vector of entries. The owner can read all the entries. But each user can only add and list their own entries. Only the owner can delete entries.
  • Owner can call the function set_format '{"temp_format": "Celsius"}' to change the default temperature format to “Celsius”, “Fahrenheit” or “Kelvin”. Default format is “Kelvin”.
  • Each entry is added to the Vector associated with the predecessor’s account ID . It must have a value of Temperature . Temperature Format is optional. Time is optional. Date is optional. If Temperature Format is omitted, use current system format. If Date or Time are omitted, use current date or time.
  • Add entries with function calls like:
    • new_entry '{"value": 10}' ;
    • new_entry '{"value": 10, "format": "f"}' ;
    • new_entry '{"value": 10, "format": "Kelvin", "date": (2022, "feb", 20), "time": (18, 30, 44, 0.543412314) }' ;
  • If the system has a different temperature format to the message. Convert it before storing. If the system’s temperature format changes. It will only convert stored values when retrieving.
  • See all entries for an account with list_entries '{"account_id": "my-account.testnet"}' . If account_id is omitted check own entries. Only owner is allowed to check entries for other contracts;
  • Clear entries for an account with clear_entries '{"account_id": "account_name.testnet"}' . Only owner may call this function.
  • Remove a user with remove_user '{"account_id": "account_name.testnet" }' . Only owner may call this function. I just realized that I didn’t forbid the contract from deleting the owner’s account. Will have to change that.
  • Time stored is treated as UTC. Maybe I should add functionality for changing time formats the same way we change temperature.

Week 11

  • Cleaned unused code for lesson 6-2 thermometer example. Link: https://github.com/On0n0k1/Tutorial_NEAR_Rust/commit/335c64761962a0922ed5972e4d9cdeecc582efcb
  • Wrote documentation for all structs, enums, functions and methods for lesson 6-2 thermometer example. 533 lines. Link: https://github.com/On0n0k1/Tutorial_NEAR_Rust/commit/f7de057539db01d56fcc237fd8c6216177836c70
  • Users can generate the documentation website by calling the following cargo command : cargo doc -p lesson_6_2_thermometer --open . But I will also keep an example hosted on my website. There will be a link displayed in the Readme.md file.
  • Now that everything is documented. Only need to write the actual lesson.
  • near-sdk-rs stable version version 4.0 is announced to release on mainnet soon. So I will prepare the tutorials for the newer version when it comes out.
  • workspaces-rs newer version is also coming soon. So, I want to write a brazilian portuguese tutorial for it.
  • My setup for recording video classes is also ready now. So will start making a few video lessons for near-in-minutes soon. I’m considering hiring a video editor and make a youtube/odysee channel just for reference. Videos will be in english but with subtitles in portuguese and spanish. These videos would have to be as fast and efficient as possible so we don’t waste the viewers’ time. Just considering the possibility. Will discuss with the team about it more.
  • near-sdk-rs 4.0 contracts are going to look a lot more polished. Looking forward for making the next tutorials.

Week 12

  • Finally finished lesson 6-2-thermometer. It’s the largest and most detailed example in the project. There’s documentation for all elements in the project. There are tests. Code has been cleaned up of any unused code. The largest Readme yet, explaining every detail about Rust and NEAR that can be taken from the project. Link: https://github.com/On0n0k1/Tutorial_NEAR_Rust/tree/main/PT-BR/lesson_6_enums/lesson_6_2_thermometer#li%C3%A7%C3%A3o-6---2-term%C3%B4metro
  • The following lessons will be a lot smaller. Else I will be writing this tutorial forever.
  • Participated in april 29 Near University’s NCD group session. Offered support on some topics related to Smart Contract development.
  • Will join more NCD events to offer support if needed.
  • I’m still going to make Youtube and loom videos about NEAR Smart Contracts in Rust. It’s a lot easier to just share a video to a student than go through all the trouble of scheduling a meetup. Plus that will relieve me more time to study new techniques for dapps.
  • Studied how to deploy websites into IPFS. I want to find a way to coordinate websites that connect to IPFS and use NEAR contracts. Now I feel I should start studying more other blockchain technologies to understand the advantages and downsides of each one. People will look for tutorials about these subjects.
1 Like