Release notes
Release notes and unreleased changes can be found in the CHANGELOG
Example
Wrap a struct in #[unc]
and it generates a smart contract compatible with the Utility blockchain:
use ;
Features
Unit-testable
Writing unit tests is easy with unc-sdk
:
Run unit test the usual way:
Asynchronous cross-contract calls
Asynchronous cross-contract calls allow parallel execution of multiple contracts in parallel with subsequent aggregation on another contract. env
exposes the following methods:
promise_create
-- schedules an execution of a function on some contract;promise_then
-- attaches the callback back to the current contract once the function is executed;promise_and
-- combinator, allows waiting on several promises simultaneously, before executing the callback;promise_return
-- treats the result of execution of the promise as the result of the current function.
Follow examples/cross-contract-high-level to see various usages of cross contract calls, including system-level actions done from inside the contract like balance transfer (examples of other system-level actions are: account creation, access key creation/deletion, contract deployment, etc).
Initialization methods
We can define an initialization method that can be used to initialize the state of the contract. #[init]
verifies that the contract has not been initialized yet (the contract state doesn't exist) and will panic otherwise.
Even if you have initialization method your smart contract is still expected to derive Default
trait. If you don't
want to disable default initialization, then you can prohibit it like this:
You can also prohibit Default
trait initialization by using unc_sdk::PanicOnDefault
helper macro. E.g.:
Payable methods
We can allow methods to accept token transfer together with the function call. This is done so that contracts can define a fee in tokens that needs to be payed when they are used. By the default the methods are not payable and they will panic if someone will attempt to transfer tokens to them during the invocation. This is done for safety reason, in case someone accidentally transfers tokens during the function call.
To declare a payable method simply use #[payable]
decorator:
Private methods
Usually, when a contract has to have a callback for a remote cross-contract call, this callback method should
only be called by the contract itself. It's to avoid someone else calling it and messing the state. Pretty common pattern
is to have an assert that validates that the direct caller (predecessor account ID) matches to the contract's account (current account ID).
Macro #[private]
simplifies it, by making it a single line macro instead and improves readability.
To declare a private method use #[private]
decorator:
/// Which is equivalent to
Now, only the account of the contract itself can call this method, either directly or through a promise.
Pre-requisites
To develop Rust contracts you would need to:
- Install Rustup:
|
- Add wasm target to your toolchain:
Writing Rust Contract
You can follow the examples/status-message crate that shows a simple Rust contract.
The general workflow is the following:
-
Create a crate and configure the
Cargo.toml
similarly to how it is configured in examples/status-message/Cargo.toml; -
Crate needs to have one
pub
struct that will represent the smart contract itself:- The struct needs to implement
Default
trait which UNC will use to create the initial state of the contract upon its first usage; - The struct also needs to implement
BorshSerialize
andBorshDeserialize
traits which UNC will use to save/load contract's internal state;
Here is an example of a smart contract struct:
use ;
- The struct needs to implement
-
Define methods that UNC will expose as smart contract methods:
- You are free to define any methods for the struct but only public methods will be exposed as smart contract methods;
- Methods need to use either
&self
,&mut self
, orself
; - Decorate the
impl
section with#[unc]
macro. That is where all the M.A.G.I.C. (Macros-Auto-Generated Injected Code) happens; - If you need to use blockchain interface, e.g. to get the current account id then you can access it with
env::*
;
Here is an example of smart contract methods:
Building Rust Contract
cargo-unc
This can be used as an alternative, to allow building while also generating an abi
# Install the unc extension if you haven't already
# Builds the wasm contract and ABI into `target/unc`
Using cargo build
RUSTFLAGS='-C link-arg=-s'
Building with reproducible builds
Since WebAssembly compiler includes a bunch of debug information into the binary, the resulting binary might be different on different machines. To be able to compile the binary in a reproducible way, we added a Dockerfile that allows to compile the binary.
Use contract-builder
Utility contract standards
unc-contract-standards
crate provides a set of interfaces and implementations for UNC's contract standards:
- Upgradability
- Fungible Token (UIP-141). See example usage
- Non-Fungible Token (UIP-171). See example usage
Versioning
Semantic Versioning
This crate follows Cargo's semver guidelines.
State breaking changes (low-level serialization format of any data type) will be avoided at all costs. If a change like this were to happen, it would come with a major version and come with a compiler error. If you encounter one that does not, open an issue!
MSRV
The minimum supported Rust version is currently 1.78
. There are no guarantees that this will be upheld if a security patch release needs to come in that requires a Rust toolchain increase.
Contributing
If you are interested in contributing, please look at the contributing guidelines.