Kresko Protocol

This repository contains the code for the Kresko Protocol. Kresko Protocol supports creating and managing crypto-backed synthetic assets. Prices for synthetic assets are derived from combination of oracle providers (on-demand/push).

Protocol uses the EIP-2535 architecture. It enables composability through flexibile storage patterns while allowing users to access all core functionality with a single contract address.

This readme is a usage/integration guide that assumes understanding of Solidity (especially EIP-2535), Foundry, Hardhat and core concepts of Kresko.

Usage

A justfile exists for running things.

Using just commands

just installed: just <command>.

just not installed: npx just <command>.

Setup

Quick Setup

Install missing tools (bun, foundry, pm2), forge dependencies and run dry deploy

just setup

Only tools & deps can be installed with

just deps

Manual Setup

Create .env file from example

cp .env.example .env

Tools

bun

curl -fsSL https://bun.sh/install | bash

PM2 is required for anvil & forge development network

bun a -g pm2

Foundry

Install foundry:

curl -L https://foundry.paradigm.xyz | bash

and

foundryup

Dependencies

Install forge dependencies

forge install

Install node dependencies

bun install --yarn

Compiling

Foundry

Compile the contracts

forge build

Check your setup by running the forge deployment script

bun f:dry

or

just d

Hardhat

Compile the contracts

bun hh:compile

Check your setup by running the hardhat deployment script

bun hh:dry

Testing

NOTE: Primary test coverage uses hardhat. Forge tests are a work in progress

Hardhat

Run tests with against a local deployment fixture

bun hh:test

Foundry

forge test

Deployment

Hardhat

Spins up hardhat node and runs deployment

bun hh:dev

Foundry

(requires PM2: bun a -g pm2)

Spins up anvil and runs deployment

just l

Observe deployment script logs

pm2 logs 1

Restart the network

just r

Stop the network

just k

VSCode extensions

• Patterns in this repository have broken lsp support with these extensions: hardhat, solidity.

• Recommendation is to rather use this fork: vsc-solidity.

About ERC-2535 (Diamonds) and things

General

• External functionality lives in Facets, Use IKresko.sol or the artifact generated using hardhat-diamond-abi for aggregate ABI.

• Logic (mostly) lives inside internal library functions. These libraries are then attached globally to structs for convenience.

• Storage is accessed with inline assembly slot pointer assignment. To access the storage (+ attached library functions) simply call these storage getter functions anywhere.

• Vault, Factory and KreskoAsset contracts do not live inside the diamond scope.

State

Nay

• Do not add new state variables to the beginning or middle of structs. Doing this makes the new state variable overwrite existing state variable data and all state variables after the new state variable reference the wrong storage location.

• Do not put structs directly in structs unless you don’t plan on ever adding more state variables to the inner structs. You won't be able to add new state variables to inner structs in upgrades. This makes sense because a struct uses a fixed number of storage locations. Adding a new state variable to an inner struct would cause the next state variable after the inner struct to be overwritten. Structs that are in mappings can be extended in upgrades, because those structs are stored in random locations based on keccak256 hashing.

• Do not add new state variables to structs that are used in arrays.

• Do not use the same namespace string for different structs. This is obvious. Two different structs at the same location will overwrite each other.

Yay

• To add new state variables to the DiamondStorage pattern (eg. MinterState or ms), add them to the end of the struct so it is not possible for existing functions to overwrite state variables at new storage locations.

• Above also applies to structs inside mappings.

• State variable names can be changed - but it might be confusing if different facets use different names for the same storage.

Learning references

https://eip2535diamonds.substack.com/p/compliance-with-eip-2535-diamonds

https://github.com/solidstate-network/solidstate-solidity

https://eip2535diamonds.substack.com/p/how-eip2535-diamonds-reduces-gas

Contributions

Contributions to Kresko Protocol are encouraged, feel free to open an issue or pull request.
All contributions are licensed under BUSL-1.1.

Contact

Critical bug disclosures and inquiries should be directed to: