Suna

Built with auditless/cairo-template

Typesafe opinionated abstractions for developing Cairo 1.0 smart contracts. Originally created to facilitate Yagi Finance smart contract development.

What is included

suna.math.u256: A Zeroable trait implementation for u256
suna.math.u60f18: An unsigned fixed point decimal type based on u256; MulDiv trait and operators

Warning

Suna is an experimental and unaudited library and is subject to a lot of iteration. There may be bugs.

How to use the library

You can directly add Suna to your Scarb dependencies:

[dependencies]
suna = { git = "https://github.com/auditless/suna.git" }

The below examples are illustrative and you can find more functions by reading the code and tests directly.

`Zeroable` trait implementation for `u256`

Most DeFi applications will use the u256 type to deal with token amounts. Unfortunately the trait implementations are not yet complete. This is how you can use the Zeroable implementation:

use suna::math::u256::U256Zeroable;

let number: u256 = 33_u256;
// Check if number is zero
Zeroable::is_zero(0)

`MulDiv` trait

When building a yield/pooling application, you may need a way to calculate how much of an underlying asset a given share owner controls. You can do it as follows:

use suna::math::u60f18::U256MulDiv;

let total_supply: u256 = 10000_u256;
let shares: u256 = 33_u256;
let total_assets: u256 = 853000000000000000000_u256;
// Calculates shares * total_assets / total_supply safely
let assets_owned = U256MulDiv::mul_div(shares, total_assets, total_supply);

An 18-decimal fixed point type `U60F18`

You may also want to maintain certain fractional values such as weights or interest rates in your application using 18 decimals. To do that, you can use our U60F18 type which supports conversion from u256 and many of the standard operators:

use traits::Into;
use suna::math::u60f18::U256ToU60F18;
use suna::math::u60f18::U60F18DivEq;

// Represent an interest rate of 2%
let mut interest_rate: U60F18 = 2.into();
interest_rate /= 100.into();

Design principles

Be useful to developers building production Cairo contracts
Design from first principles with both Rust and smart contract idioms in mind
Build typesafe and efficient abstractions that are consistently designed
Respect and embrace the corelib trait hierarchy
Aspire to build well-documented and declarative code

How to contribute

Read the Cairo 1.0 setup guide at https://github.com/auditless/cairo-template
Check our issues for scoped tasks or propose/request a new one by opening an issue
Submit a PR linking the relevant issue
You may also submit a PR that fixes a bug or nit directly

Thanks to

The Quaireaux team for paving the way for Cairo 1.0 library development
The Scarb contributors for creating a pioneering package manager which we rely on
The OpenZeppelin team for the mulDiv interface
S. Tsuchiya for the cover photo
Last but not least, the StarkWare team for building the first smart contract language that is a joy to use

auditless/suna