From 42106e5302ff1e2b155c879a8f1675b4dfd27754 Mon Sep 17 00:00:00 2001 From: Kerber0x Date: Mon, 20 May 2024 15:29:10 +0100 Subject: [PATCH 1/2] docs(epoch-manager): add readme to epoch manager --- .../liquidity_hub/epoch-manager/README.md | 105 +++--------------- 1 file changed, 13 insertions(+), 92 deletions(-) diff --git a/contracts/liquidity_hub/epoch-manager/README.md b/contracts/liquidity_hub/epoch-manager/README.md index 054ea4814..a08f08de8 100644 --- a/contracts/liquidity_hub/epoch-manager/README.md +++ b/contracts/liquidity_hub/epoch-manager/README.md @@ -1,99 +1,20 @@ -# CosmWasm Starter Pack +# Epoch Manager -This is a template to build smart contracts in Rust to run inside a -[Cosmos SDK](https://github.com/cosmos/cosmos-sdk) module on all chains that enable it. -To understand the framework better, please read the overview in the -[cosmwasm repo](https://github.com/CosmWasm/cosmwasm/blob/master/README.md), -and dig into the [cosmwasm docs](https://www.cosmwasm.com). -This assumes you understand the theory and just want to get coding. +The Epoch Manager is a contract which sole purpose is to create epochs on the Migaloo ecosystem. -## Creating a new repo from template +## How it works -Assuming you have a recent version of Rust and Cargo installed -(via [rustup](https://rustup.rs/)), -then the following should get you a new repo to start a contract: +When the contract is instantiated, a start epoch and the epoch configuration are set up. The epoch configuration defines +the duration of an epoch and when the genesis epoch is, i.e. the first epoch. -Install [cargo-generate](https://github.com/ashleygwilliams/cargo-generate) and cargo-run-script. -Unless you did that before, run this line now: +Once the genesis epoch is created, after the epoch duration has passed, anyone can create a new epoch by calling the +`CreateEpoch` message. This action will create a new epoch, i.e. increase the epoch id by one, and alert the contracts +that have registered for the hook. -```sh -cargo install cargo-generate --features vendored-openssl -cargo install cargo-run-script -``` +## Epoch Hook -Now, use it to create your new contract. -Go to the folder in which you want to place it and run: +There are two actions that only the owner of the Epoch Manager can call for: `AddHook` and `RemoveHook`. These add a contract +to the `HOOKS` list. -**Latest** - -```sh -cargo generate --git https://github.com/CosmWasm/cw-template.git --name PROJECT_NAME -``` - -For cloning minimal code repo: - -```sh -cargo generate --git https://github.com/CosmWasm/cw-template.git --name PROJECT_NAME -d minimal=true -``` - -**Older Version** - -Pass version as branch flag: - -```sh -cargo generate --git https://github.com/CosmWasm/cw-template.git --branch --name PROJECT_NAME -``` - -Example: - -```sh -cargo generate --git https://github.com/CosmWasm/cw-template.git --branch 0.16 --name PROJECT_NAME -``` - -You will now have a new folder called `PROJECT_NAME` (I hope you changed that to something else) -containing a simple working contract and build system that you can customize. - -## Create a Repo - -After generating, you have a initialized local git repo, but no commits, and no remote. -Go to a server (eg. github) and create a new upstream repo (called `YOUR-GIT-URL` below). -Then run the following: - -```sh -# this is needed to create a valid Cargo.lock file (see below) -cargo check -git branch -M main -git add . -git commit -m 'Initial Commit' -git remote add origin YOUR-GIT-URL -git push -u origin main -``` - -## CI Support - -We have template configurations for both [GitHub Actions](.github/workflows/Basic.yml) -and [Circle CI](.circleci/config.yml) in the generated project, so you can -get up and running with CI right away. - -One note is that the CI runs all `cargo` commands -with `--locked` to ensure it uses the exact same versions as you have locally. This also means -you must have an up-to-date `Cargo.lock` file, which is not auto-generated. -The first time you set up the project (or after adding any dep), you should ensure the -`Cargo.lock` file is updated, so the CI will test properly. This can be done simply by -running `cargo check` or `cargo unit-test`. - -## Using your project - -Once you have your custom repo, you should check out [Developing](./Developing.md) to explain -more on how to run tests and develop code. Or go through the -[online tutorial](https://docs.cosmwasm.com/) to get a better feel -of how to develop. - -[Publishing](./Publishing.md) contains useful information on how to publish your contract -to the world, once you are ready to deploy it on a running blockchain. And -[Importing](./Importing.md) contains information about pulling in other contracts or crates -that have been published. - -Please replace this README file with information about your specific project. You can keep -the `Developing.md` and `Publishing.md` files as useful referenced, but please set some -proper description in the README. +These contracts must implement the `EpochChangedHookMsg` interface, which is the signature of the message that will be +executed on the hooks when a new epoch is created. The hook contains the current `Epoch`, specifying the id and start_time. From 1d6ffbcc495507940099b2e13a29c908df17f887 Mon Sep 17 00:00:00 2001 From: Kerber0x Date: Tue, 21 May 2024 11:03:55 +0100 Subject: [PATCH 2/2] docs(epoch-manager): add epoch details and hook mechanismm diagram --- .../liquidity_hub/epoch-manager/README.md | 31 ++++++++++++++----- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/contracts/liquidity_hub/epoch-manager/README.md b/contracts/liquidity_hub/epoch-manager/README.md index a08f08de8..361294c2c 100644 --- a/contracts/liquidity_hub/epoch-manager/README.md +++ b/contracts/liquidity_hub/epoch-manager/README.md @@ -1,20 +1,37 @@ # Epoch Manager -The Epoch Manager is a contract which sole purpose is to create epochs on the Migaloo ecosystem. +The Epoch Manager is a contract which sole purpose is to create epochs on the Migaloo ecosystem, acting like a clock for +the other contracts. + +An `Epoch` is a period of time that is defined by the `duration` parameter on `EpochConfig`, and they are used by other +contracts to take timely actions. For example, the Bonding Manager uses epochs to calculate the rewards for the bonders, +while the Incentive Manager uses epochs to calculate the incentive rewards for its users. ## How it works -When the contract is instantiated, a start epoch and the epoch configuration are set up. The epoch configuration defines -the duration of an epoch and when the genesis epoch is, i.e. the first epoch. +The epoch configuration is set up when the contract is instantiated. The epoch configuration defines +the duration of an epoch and when the genesis epoch is gonna take place, i.e. the first epoch. Once the genesis epoch is created, after the epoch duration has passed, anyone can create a new epoch by calling the -`CreateEpoch` message. This action will create a new epoch, i.e. increase the epoch id by one, and alert the contracts -that have registered for the hook. +`CreateEpoch` message. This action will create a new epoch by increasing the epoch id by one, adjust the start time for +the new epoch and alert the contracts that have registered for the hook. ## Epoch Hook -There are two actions that only the owner of the Epoch Manager can call for: `AddHook` and `RemoveHook`. These add a contract -to the `HOOKS` list. +There are two actions that only the owner of the Epoch Manager can execute: `AddHook` and `RemoveHook`. These add or +remove a contract to the `HOOKS` list. These contracts must implement the `EpochChangedHookMsg` interface, which is the signature of the message that will be executed on the hooks when a new epoch is created. The hook contains the current `Epoch`, specifying the id and start_time. + +```mermaid +--- +title: Epoch Manager Hook Mechanism +--- +flowchart +E[Epoch Manager] -->|on_epoch_created| C1[Contract 1] +E -.->|CreateEpoch| E +E -->|on_epoch_created| C2[Contract 2] +E -->|on_epoch_created| N[...] +E -->|on_epoch_created| CN[Contract N] +``` \ No newline at end of file