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: Missing trait implementations for theu256data type:U256Zeroableand a truncated division implementationU256TruncatedDivofDiv<u256>suna.math.u60f18: An unsigned fixed point decimal type based onu256;MulDivtrait 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.
u256 trait implementations
Most Defi applications will use the u256 type to deal with token amounts. Unfortunately the trait implementations are not yet complete. To add support for u256 division/mod operations, add the following:
use suna::math::u256::U256TruncatedDiv;
use suna::math::u256::U256TruncatedDivEq;
use suna::math::u256::U256TruncatedRem;
use suna::math::u256::U256TruncatedRemEq;
let a: u256 = 10.into();
let b: u256 = 2.into();
let c = a / b; // this will now work
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.into();
let shares: u256 = 33.into();
let total_assets: u256 = 853000000000000000000.into();
// 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
corelibtrait 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
5 Nov 9, 2022
73 Dec 30, 2022
19 Aug 8, 2023
149 Aug 1, 2023
26 Feb 3, 2022
125 Dec 3, 2022
7 Feb 29, 2024
92 Dec 7, 2022
777 Jan 4, 2023
226 Dec 27, 2022
165 Dec 18, 2022
0 Nov 7, 2021
38 Dec 19, 2022
2 Sep 25, 2022
1 Mar 7, 2022
6 Nov 22, 2022
15 Mar 16, 2022
6 May 31, 2022
4 Dec 23, 2022
5 Mar 16, 2023
4 Dec 15, 2022
11 Dec 8, 2022
68 Apr 21, 2023
27 Dec 17, 2022
9 Aug 3, 2022
3 Nov 3, 2023
294 Dec 23, 2022
3 Apr 25, 2022