openbrush-contracts: A Rust repository from Brushfam

📢 📢 📢 We are thrilled to announce Patron, which brings smart contract verification functionality to the Polkadot ecosystem. 📢 📢 📢

Smart contract verification ensures the security, reliability, and trustworthiness of dApps and blockchain platforms. With Patron, you can simplify the deployment flow, manage your builds and make the Polkadot ecosystem more secure and transparent.

So, in other words, Patron is an all-in-one contracts platform, which allows you to build and verify ink! smart contracts inside of an isolated environment, explore contract verification details.

OpenBrush is maintained by the Brushfam team, and was created to make ink! development faster, safer and easier. We plan to integrate most of the features OpenBrush into ink!. OpenBrush provides documentation with FAQ section.

If you have any questions regarding OpenBrush, you can join the Brushfam Element channel to find your answers and meet other ink! smart contracts developers, or ask questions regarding ink! development on Element, Discord, or Telegram OpenBrush channels by the links above.

Summary

OpenBrush is a library for smart contract development on ink!.

Why use this library?

To make contracts interoperable to do safe cross-contracts calls (by having the same functions signature among every contracts)
To ensure the usage of Polkadot Standards Proposals
To ensure the usage of the latest & most secure implementation
Useful contracts that provide custom logic to be implemented in contracts
To save time by not writing boilerplate code
Useful features which can simplify development
All contracts are upgradeable by default

Which Standard tokens & useful contracts does it provide?

PSP22 - Fungible Token (ERC20 equivalent) with extensions
PSP34 - Non-Fungible Token (ERC721 equivalent) with extensions
PSP37 - ERC1155 equivalent with extensions
Ownable Restrict access to action for non-owners
Access Control Define set of roles and restrict access to action by roles
Reentrancy guard Prevent reentrant calls to a function
Pausable Pause/Unpause the contract to disable/enable some operations
Timelock Controller Execute transactions with some delay
Payment Splitter Split amount of native tokens between participants

Default implementation in ink! traits

You can provide a default implementation in the traits method and have internal functions. You can use the ink! trait as a native rust trait with several restrictions regarding external functions(functions marked #[ink(message)]).

#[openbrush::trait_definition]
pub trait Governance: AccessControl {
    #[ink(message)]
    fn execute(&mut self, transaction: Transaction) -> Result<(), GovernanceError> {
        self.internal_execute(transaction)
    }

    fn internal_execute(&mut self, transaction: Transaction) -> Result<(), GovernanceError> {
        ...
    }
}

Modifiers

Solidity smart contracts provides modifiers to restrain function call to certain pre-defined parameters. OpenBrush provides attribute macros to use standardised modifiers. You can use our useful contracts to use as modifiers, or define your own modifiers.

// Before execution of `mint` method, `only_owner` should verify that caller is the owner.
#[ink(message)]
#[modifiers(only_owner)]
fn mint(&mut self, ids_amounts: Vec<(Id, Balance)>) -> Result<(), PSP37Error> {
  self._mint_to(Self::env().caller(), ids_amounts)
}

Wrapper around traits

You are enough to have a trait definition (you don't need directly a contract that implements that trait) to call methods of that trait from some contract in the network (do a cross contract call).

// Somewhere defined trait
#[openbrush::trait_definition]
pub trait Trait1 {
    #[ink(message)]
    fn foo(&mut self) -> bool;
}

// You can create wrapper in the place where you defined the trait
// Or if you import **everything** from the file where you define trait
#[openbrush::wrapper]
type Trait1Ref = dyn Trait1;

{
    // It should be `AccountId` of contract in the network that implements `Trait1` trait
    let callee: openbrush::traits::AccountId = [1; 32].into();
    // This code will execute a cross contract call to `callee` contract
    let result_of_foo: bool = Trait1Ref::foo(&callee);
}

Note: The trait should be defined with openbrush::trait_definition. The callee contract should implement that trait.

Additional stuff

You can use test_utils to simplify unit testing of you code.
You can use traits that provides some additional functionality for your code.
Read our documentation in doc.
Go through our examples in examples to check hot to use the library and ink!.
Check the example of project struct and according documentation.

Not sure where to start? Use the interactive generator to bootstrap your contract and learn about the components offered in OpenBrush.

‼️ Important ‼️

Events are not supported currently due to how ink! currently handles them.
The identifiers of events must be based on the name of the trait. At the moment, ink! doesn't support it, but it must be fixed with this issue.

Issues to be resolved before the library becomes production-ready:

Event's identifiers are based on the naming of the storage structure

Installation & Testing

To work with project you need to install ink! toolchain and NodeJS's dependencies.

So, you need an actual installer rustup.
ink! toolchain
NodeJS deps you can install via yarn command

Build

$ yarn build

If you want to build in release mode, you can use this command

$ yarn build:release

Tests

You can run unit tests by RUSTFLAGS="-D warnings" cargo test --workspace --features test-all -- --test-threads=10 command from the root of the directory.

To run integration test you need to start the node with contract-pallet.

Setup and start the node with contract-pallet

After you can run tests by npm run test command. It will build all contracts required for integration tests and run them.

End-to-End (E2E) Tests

To run e2e-tests in the contract we recoment to use this versions of tools:

rustc: 1.71.1
cargo: 1.71.1
rustup toolchain: stable
cargo-contract: 3.2.0
ink!: 4.3.0
ink_e2e: 4.3.0
substrate-contracts-node: 0.27.0

To run e2e-tests you need to write this command in the root of the directory:

$ cargo test --features e2e-tests

Brushfam/openbrush-contracts