Skip to content

Commit

Permalink
Version 1.0.0
Browse files Browse the repository at this point in the history
  • Loading branch information
zie1ony committed May 23, 2024
1 parent 16160c7 commit 6d7efea
Show file tree
Hide file tree
Showing 55 changed files with 8,008 additions and 5 deletions.
5 changes: 3 additions & 2 deletions docusaurus/docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@ const config = {
'docs/0.6.0/**/*',
'docs/0.7.0/**/*',
'docs/0.8.0/**/*',
'docs/0.9.0/**/*'
'docs/0.9.0/**/*',
'docs/0.9.1/**/*',
]
}]],

Expand All @@ -52,7 +53,7 @@ const config = {
docs: {
sidebarPath: require.resolve('./sidebars.js'),
includeCurrentVersion: true,
lastVersion: '0.9.1',
lastVersion: '1.0.0',
versions: {
current: {
label: 'next',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ pub struct Withdrawal {
}
```

Full code can be found [here](https://github.com/odradev/odra/blob/release/0.9.1/examples/src/contracts/tlw.rs).
Full code can be found [here](https://github.com/odradev/odra/blob/release/1.0.0/examples/src/contracts/tlw.rs).

## Client

Expand Down Expand Up @@ -122,13 +122,13 @@ To interact with the contract, we use the `livenet` backend. It allows to write
```toml title=Cargo.toml
[package]
name = "odra-examples"
version = "0.9.1"
version = "1.0.0"
edition = "2021"

[dependencies]
odra = { path = "../odra", default-features = false }
... # other dependencies
odra-casper-livenet-env = { version = "0.9.1", optional = true }
odra-casper-livenet-env = { version = "1.0.0", optional = true }

... # other sections

Expand Down
120 changes: 120 additions & 0 deletions docusaurus/versioned_docs/version-1.0.0/advanced/01-delegate.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
# Delegate

Managing boilerplate code can often lead to code that is cumbersome and challenging to comprehend. The Odra library introduces a solution to this issue with its Delegate feature. As the name implies, the Delegate feature permits the delegation of function calls to child modules, effectively minimizing the redundancy of boilerplate code and maintaining a lean and orderly parent module.

The main advantage of this feature is that it allows you to inherit the default behavior of child modules seamlessly, making your contracts more readable.

## Overview

To utilize the delegate feature in your contract, use the `delegate!` macro provided by Odra. This macro allows you to list the functions you wish to delegate to the child modules. By using the `delegate!` macro, your parent module remains clean and easy to understand.

You can delegate functions to as many child modules as you like. The functions will be available as if they were implemented in the parent module itself.

## Code Examples

Consider the following basic example for better understanding:

```rust
use crate::{erc20::Erc20, ownable::Ownable};
use odra::{
Address, casper_types::U256,
module::SubModule,
prelude::*
};

#[odra::module]
pub struct OwnedToken {
ownable: SubModule<Ownable>,
erc20: SubModule<Erc20>
}

#[odra::module]
impl OwnedToken {
pub fn init(&mut self, name: String, symbol: String, decimals: u8, initial_supply: U256) {
let deployer = self.env().caller();
self.ownable.init(deployer);
self.erc20.init(name, symbol, decimals, initial_supply);
}

delegate! {
to self.erc20 {
fn transfer(&mut self, recipient: Address, amount: U256);
fn transfer_from(&mut self, owner: Address, recipient: Address, amount: U256);
fn approve(&mut self, spender: Address, amount: U256);
fn name(&self) -> String;
fn symbol(&self) -> String;
fn decimals(&self) -> u8;
fn total_supply(&self) -> U256;
fn balance_of(&self, owner: Address) -> U256;
fn allowance(&self, owner: Address, spender: Address) -> U256;
}

to self.ownable {
fn get_owner(&self) -> Address;
fn change_ownership(&mut self, new_owner: Address);
}
}

pub fn mint(&mut self, address: Address, amount: U256) {
self.ownable.ensure_ownership(self.env().caller());
self.erc20.mint(address, amount);
}
}
```

This `OwnedToken` contract includes two modules: `Erc20` and `Ownable`. We delegate various functions from both modules using the `delegate!` macro. As a result, the contract retains its succinctness without compromising on functionality.

The above example basically merges the functionalities of modules and adds some control over the minting process. But you can use delegation to build more complex contracts, cherry-picking just a few module functionalities.

Let's take a look at another example.

```rust
use crate::{erc20::Erc20, ownable::Ownable, exchange::Exchange};
use odra::{
Address, casper_types::U256,
module::SubModule,
prelude::*
};

#[odra::module]
pub struct DeFiPlatform {
ownable: SubModule<Ownable>,
erc20: SubModule<Erc20>,
exchange: SubModule<Exchange>
}

#[odra::module]
impl DeFiPlatform {
pub fn init(&mut self, name: String, symbol: String, decimals: u8, initial_supply: U256, exchange_rate: u64) {
let deployer = self.env().caller();
self.ownable.init(deployer);
self.erc20.init(name, symbol, decimals, initial_supply);
self.exchange.init(exchange_rate);
}

delegate! {
to self.erc20 {
fn transfer(&mut self, recipient: Address, amount: U256);
fn balance_of(&self, owner: Address) -> U256;
}

to self.ownable {
fn get_owner(&self) -> Address;
}

to self.exchange {
fn swap(&mut self, sender: Address, recipient: Address);
fn set_exchange_rate(&mut self, new_rate: u64);
}
}

pub fn mint(&mut self, address: Address, amount: U256) {
self.ownable.ensure_ownership(self.env().caller());
self.erc20.mint(address, amount);
}
}
```

In this `DeFiPlatform` contract, we include `Erc20`, `Ownable`, and `Exchange` modules. By delegating functions from these modules, the parent contract becomes a powerhouse of functionality while retaining its readability and structure.

Remember, the possibilities are endless with Odra's. By leveraging this feature, you can write cleaner, more efficient, and modular smart contracts.
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# Advanced Storage Concepts

The Odra Framework provides advanced storage interaction capabilities that extend beyond the basic storage interaction. This document will focus on the `Mapping` and `Sequence` modules, which are key components of the advanced storage interaction in Odra.

## Recap and Basic Concepts

Before we delve into the advanced features, let's recap some basic storage concepts in Odra. In the realm of basic storage interaction, Odra provides several types for interacting with contract storage, including `Var`, `Mapping`, and `List`. These types enable contracts to store and retrieve data in a structured manner. The Var type is used to store a single value, while the List and Mapping types store collections of values.

**Var**: A Var in Odra is a fundamental building block used for storing single values. Each Var is uniquely identified by its name in the contract.

**Mapping**: Mapping in Odra serves as a key-value storage system. It stores an association of unique keys to values, and the value can be retrieved using the key.

**List**: Built on top of the Var and Mapping building blocks, List in Odra allows storing an ordered collection of values that can be iterated over.

If you need a refresher on these topics, please refer to our [guide](../basics/05-storage-interaction.md) on basic storage in Odra.

## Advanced Storage Concepts

### Sequence

The `Sequence` in Odra is a basic module that stores a single value in the storage that can be read or incremented. Internally, holds a `Var` which keeps track of the current value.

```rust
pub struct Sequence<T>
where
T: Num + One + ToBytes + FromBytes + CLTyped
{
value: Var<T>
}
```

The Sequence module provides functions `get_current_value` and `next_value` to get the current value and increment the value respectively.

### Advanced Mapping

In Odra, a `Mapping` is a key-value storage system where the key is associated with a value.
In previous examples, the value of the `Mapping` typically comprised a standard serializable type (such as number, string, or bool) or a custom type marked with the `#[odra::odra_type]` attribute.

However, there are more advanced scenarios where the value of the Mapping represents a module itself. This approach is beneficial when managing a collection of modules, each maintaining its unique state.

Let's consider the following example:

```rust title="examples/src/features/storage/mapping.rs"
use odra::{casper_types::U256, Mapping, UnwrapOrRevert};
use odra::prelude::*;
use crate::owned_token::OwnedToken;

#[odra::module]
pub struct Mappings {
strings: Mapping<(String, u32, String), String>,
tokens: Mapping<String, OwnedToken>
}

#[odra::module]
impl Mappings {

...

pub fn total_supply(&mut self, token_name: String) -> U256 {
self.tokens.module(&token_name).total_supply()
}

pub fn get_string_api(
&self,
key1: String,
key2: u32,
key3: String
) -> String {
let opt_string = self.strings.get(&(key1, key2, key3));
opt_string.unwrap_or_revert(&self.env())
}
}
```

As you can see, a `Mapping` key can consist of a tuple of values, not limited to a single value.

:::note
Accessing Odra modules differs from accessing regular values such as strings or numbers.

Firstly, within a `Mapping`, you don't encapsulate the module with `Submodule`.

Secondly, rather than utilizing the `Mapping::get()` function, call `Mapping::module()`, which returns `SubModule<T>` and sets the appropriate namespace for nested modules.
:::

## AdvancedStorage Contract

The given code snippet showcases the `AdvancedStorage` contract that incorporates these storage concepts.

```rust
use odra::{Address, casper_types::U512, Sequence, Mapping};
use odra::prelude::*;
use crate::modules::Token;

#[odra::module]
pub struct AdvancedStorage {
counter: Sequence<u32>,
tokens: Mapping<(String, String), Token>,
}

impl AdvancedStorage {
pub fn current_value(&self) -> u32 {
self.counter.get_current_value()
}

pub fn increment_and_get(&mut self) -> u32 {
self.counter.next_value()
}

pub fn balance_of(&mut self, token_name: String, creator: String, address: Address) -> U512 {
let token = self.tokens.module(&(token_name, creator));
token.balance_of(&address)
}

pub fn mint(&self, token_name: String, creator: String, amount: U512, to: Address) {
let mut token = self.tokens.module(&(token_name, creator));
token.mint(amount, to);
}
}
```

## Conclusion

Advanced storage features in Odra offer robust options for managing contract state. Two key takeaways from this document are:
1. Odra offers a Sequence module, enabling contracts to store and increment a single value.
2. Mappings support composite keys expressed as tuples and can store modules as values.

Understanding these concepts can help developers design and implement more efficient and flexible smart contracts.
Loading

0 comments on commit 6d7efea

Please sign in to comment.