Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update doc framework #9

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed docs/.gitbook/assets/image (3).png
Binary file not shown.
Binary file removed docs/.gitbook/assets/image (6) (1).png
Binary file not shown.
Binary file removed docs/.gitbook/assets/image (6).png
Binary file not shown.
Binary file removed docs/.gitbook/assets/image (8).png
Binary file not shown.
20 changes: 20 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Dependencies
/node_modules

# Production
/build

# Generated files
.docusaurus
.cache-loader

# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*
8 changes: 8 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,11 @@ A Job is the term used to refer to a smart contract that wishes an external enti

Credits are used to pay keepers for their work. A job can either top up your credits [with tokens](tokenomics/job-payment-mechanisms/token-payments.md), or by mining credits with time by [staking liquidity](tokenomics/job-payment-mechanisms/credit-mining.md).

### Local Development

```
yarn
yarn start
```

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
62 changes: 0 additions & 62 deletions docs/SUMMARY.md

This file was deleted.

3 changes: 3 additions & 0 deletions docs/babel.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
1 change: 1 addition & 0 deletions docs/docs/cli/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# CLI
File renamed without changes.
File renamed without changes.
File renamed without changes.
1 change: 1 addition & 0 deletions docs/docs/core/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Core
2 changes: 1 addition & 1 deletion docs/core/jobs.md → docs/docs/core/jobs.md
Original file line number Diff line number Diff line change
Expand Up @@ -218,7 +218,7 @@ There are some considerations the job wishing to migrate must take into account

Here's a graphic representation to visualize the resulting changes in the credits of a job that goes through a successful migration.

![](../.gitbook/assets/jobmigration.png)
![](./img/jobmigration.png)



File renamed without changes.
21 changes: 21 additions & 0 deletions docs/docs/intro.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
---
sidebar_position: 1
---
# Introduction

_These docs are in active development by the Keep3r community._

The Keep3r Network is a decentralized network for projects that need external devops, and for external teams to find keeper jobs.

## [Keepers](core/keepers.md)

A Keeper is the term used to refer to an external address that executes a job. This can be as simplistic as calling a transaction, or as complex as requiring extensive off-chain logic. The scope of Keep3r network is not to manage these jobs themselves, but to allow contracts to register as jobs for keepers, and keepers to register themselves as available to perform jobs. It is up to the individual keeper to set up their DevOps and infrastructure and create their own rules based on what transactions they deem profitable.

## [Jobs](core/jobs.md)

A Job is the term used to refer to a smart contract that wishes an external entity to perform an action. They would like the action to be performed in "good will" and not have a malicious result. For this reason they register as a job, and keepers can then execute on their contract. Both relying on the Keep3r ecosystem to mediate in the event of a dispute.

## [Credits](tokenomics/job-payment-mechanisms/)

Credits are used to pay keepers for their work. A job can either top up your credits [with tokens](tokenomics/job-payment-mechanisms/token-payments.md), or by mining credits with time by [staking liquidity](tokenomics/job-payment-mechanisms/credit-mining.md).

4 changes: 4 additions & 0 deletions docs/registry.md → docs/docs/registry.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
sidebar_position: 2
---

# Registry

## Beta Addresses
Expand Down
2 changes: 2 additions & 0 deletions docs/docs/roles/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Roles

File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
1 change: 1 addition & 0 deletions docs/docs/technical/peripherals/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Peripherals
1 change: 1 addition & 0 deletions docs/docs/tokenomics/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Tokenomics
Original file line number Diff line number Diff line change
Expand Up @@ -5,23 +5,23 @@ There are 2 ways for a Job Manager to pay keepers to upkeep their job:
* Credit Mining
* Token Payments

## [Credit Mining](credit-mining.md)
## [Credit Mining](./credit-mining.md)

A Job can pay their keepers via credits obtained by Credit Mining.

The Credit Mining mechanism allows anyone to provide liquidity on a [Keep3r Liquidity Pool](../keep3r-liquidity-pools.md) \(kLP\) and stake their kLP tokens on the [Keep3rJobFundableLiquidity](../../technical/peripherals/ikeep3rjobfundableliquidity.md) contract in order to start the mining of KP3R credits.
The Credit Mining mechanism allows anyone to provide liquidity on a [Keep3r Liquidity Pool](../keep3r-liquidity-pools.md) \(kLP\) and stake their kLP tokens on the [Keep3rJobFundableLiquidity](../../technical/peripherals/IKeep3rJobFundableLiquidity.md) contract in order to start the mining of KP3R credits.

The credits mined can only be used to pay for job works within the network and can't be withdrawn.

Similar to [Jobs](../../core/jobs.md) & [Keepers](../../core/keepers.md), the credits can be slashed and/or revoked via the Slasher or Governance.

## [Token Payments](token-payments.md)
## [Token Payments](./token-payments.md)

A Job can pay their keepers via token payments.

The token payment mechanism allows anyone to deposit ERC20s and set a rate of which they want to perform the payouts for the upkeep of their jobs.

Job Managers can also add on [`directTokenPayment()`](../../technical/peripherals/ikeep3rjobworkable.md) and [`worked()`](../../technical/peripherals/ikeep3rjobworkable.md) functions on their jobs, in order for the protocol to auto-calculate their job payouts based on the amount of gas spent on the particular upkeep transaction.
Job Managers can also add on [`directTokenPayment()`](../../technical/peripherals/IKeep3rJobWorkable.md) and [`worked()`](../../technical/peripherals/IKeep3rJobWorkable.md) functions on their jobs, in order for the protocol to auto-calculate their job payouts based on the amount of gas spent on the particular upkeep transaction.

Similar to [Jobs](../../core/jobs.md) & [Keepers](../../core/keepers.md), the credits can be slashed and/or revoked via the Slasher or Governance.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

A Job can generate new credits with time, by bonding Keep3r Liquidity Pool tokens `kLP` to it. Liquidities will be handled by the [Keep3r Liquidity Pools](../keep3r-liquidity-pools.md).

Once `kLPs` are added to a job with [`addLiquidityToJob`](../../technical/peripherals/ikeep3rjobfundableliquidity.md#addliquiditytojob-address-_job-address-_liquidity-uint256-_amount-external), the job starts immediately to mine new KP3R credits, that can be collectable only by the keepers, in reward for working the job. The credit mining system requires no further action from the `jobOwner`.
Once `kLPs` are added to a job with [`addLiquidityToJob`](../../technical/peripherals/IKeep3rJobFundableLiquidity.md#addliquiditytojob-address-_job-address-_liquidity-uint256-_amount-external), the job starts immediately to mine new KP3R credits, that can be collectable only by the keepers, in reward for working the job. The credit mining system requires no further action from the `jobOwner`.

{% hint style="info" %}
KP3R Credits can only be rewarded within the protocol, requiring an unbonding period that gives time to disputers to detect keepers and jobs that act in bad faith
Expand All @@ -14,9 +14,9 @@ KP3R Credits can only be rewarded within the protocol, requiring an unbonding pe

To handle KP3R credits minting and quoting, **Keep3r introduces reward periods, in which KP3R quote remains stable for each pair, and gas-efficiently processed**. These quotes are used within the protocol to mint credits and reward keepers.

The underlying KP3R of the liquidity provided, should generate the same amount of KP3R every [`inflationPeriod`](../../technical/peripherals/ikeep3rparameters.md#inflationperiod-uint256-_period-external), thereby minting the proportional amount each [`rewardPeriod`](../../technical/peripherals/ikeep3rparameters.md#rewardperiodtime-uint256-_days-external) as KP3R credits for the job. These credits are only to be earned by keepers when working the job, and by the end of each `rewardPeriod`, unused credits older than previous `rewardPeriodStart` are meant to expire.
The underlying KP3R of the liquidity provided, should generate the same amount of KP3R every [`inflationPeriod`](../../technical/peripherals/IKeep3rParameters.md#inflationperiod-uint256-_period-external), thereby minting the proportional amount each [`rewardPeriod`](../../technical/peripherals/IKeep3rParameters.md#rewardperiodtime-uint256-_days-external) as KP3R credits for the job. These credits are only to be earned by keepers when working the job, and by the end of each `rewardPeriod`, unused credits older than previous `rewardPeriodStart` are meant to expire.

![Credit mining without work](../../.gitbook/assets/image%20%284%29.png)
![Credit mining without work](./img/image-4.png)

When a new `rewardPeriod` starts, the first keeper to work the first job will:

Expand All @@ -37,23 +37,23 @@ A `worked()` transaction that has to update quotes and reward the job is more ga

To determine the value of a certain liquidity, Keep3r uses a TWAP calculation to get the average quote of a pair in the last completed period. The same calculation is applied to quote rewards for keepers \(that spend gas in ETH and receive KP3R rewards\), using a predefined KP3R/WETH pool as an oracle.

* A job will mint the result of [`quoteLiquidity`](../../technical/peripherals/ikeep3rjobfundableliquidity.md#quoteliquidity-address-_liquidity-uint256-_amount-uint256-_periodcredits-external) every `rewardPeriodTime`
* A job will mint the result of [`quoteLiquidity`](../../technical/peripherals/IKeep3rJobFundableLiquidity.md#quoteliquidity-address-_liquidity-uint256-_amount-uint256-_periodcredits-external) every `rewardPeriodTime`
* `quoteLiquidity` will use the average quote for the last `epoch`for the given liquidity
* Remaining credits will be updated to current quotes each time a `rewardPeriod` starts

#### Job Credit accountance

At every time, a job will have its **current credits** \(already rewarded and stored as [`jobLiquidityCredits`](../../technical/peripherals/ikeep3rjobfundableliquidity.md#jobperiodcredits-address-_job-uint256-_amount-external)\) and **pending mined credits** to be rewarded \(aggregated with current credits in [`totalJobCredits`](../../technical/peripherals/ikeep3rjobfundableliquidity.md#totaljobcredits-address-_job-uint256-_amount-external)\).
At every time, a job will have its **current credits** \(already rewarded and stored as [`jobLiquidityCredits`](../../technical/peripherals/IKeep3rJobFundableLiquidity.md#jobperiodcredits-address-_job-uint256-_amount-external)\) and **pending mined credits** to be rewarded \(aggregated with current credits in [`totalJobCredits`](../../technical/peripherals/IKeep3rJobFundableLiquidity.md#totaljobcredits-address-_job-uint256-_amount-external)\).

A keeper will be able to run the job, as long as `totalJobCredits` is greater than the payment. If `jobLiquidityCredits` are not enough to pay the keeper, then the keeper will have to reward the job by rewarding the job with its mined credits.

In a normal case scenario, a job should be rewarded once every reward period starts, and burn all remaining credits from the expired period \(the one previous to the last full period\).

![Normal case scenario](../../.gitbook/assets/image%20%289%29.png)
![Normal case scenario](./img/image-9.png)

In a deficitary job scenario, when the job is spending more KP3R in a period than it should be rewarded, the job will be able to keep on paying keepers, but the minting period will start to shrink, having to mint more frequently.

![Deficitary job scenario](../../.gitbook/assets/image%20%287%29.png)
![Deficitary job scenario](./img/image-7.png)

Each time, the reward period will be shorter, as the job is not being rewarded the full amount for a period, but only the proportional relation of the time that passed since the last reward, and the `rewardPeriod`.

Expand All @@ -63,17 +63,17 @@ Ultimately, when the job has not enough `totalJobCredits` to reward the keeper f

At particular times, a job can make a payment of up to 2 times its `jobPeriodCredits`, as long as all the credits minted have not yet expired.

![Credits spending greater than jobPeriodCredits](../../.gitbook/assets/image%20%282%29.png)
![Credits spending greater than jobPeriodCredits](./img/image-2.png)

**Updating Credits**

Since quotes can change every epoch, Keep3r recalculates every period how many KP3R a job should be mined each period, aggregated by [`jobPeriodCredits`](../../technical/peripherals/ikeep3rjobfundableliquidity.md#jobperiodcredits-address-_job-uint256-_amount-external).
Since quotes can change every epoch, Keep3r recalculates every period how many KP3R a job should be mined each period, aggregated by [`jobPeriodCredits`](../../technical/peripherals/IKeep3rJobFundableLiquidity.md#jobperiodcredits-address-_job-uint256-_amount-external).

![Credit mining with quote change](../../.gitbook/assets/image%20%285%29.png)
![Credit mining with quote change](./img/image-5.png)

Since KP3R/WETH is also stored and **stable inside periods**, keeper payments are also updated to current quotes.

![Work scenario with quote change](../../.gitbook/assets/image%20%281%29.png)
![Work scenario with quote change](./img/image-1.png)

#### Removing Liquidity

Expand Down
67 changes: 67 additions & 0 deletions docs/docusaurus.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
// @ts-check
// Note: type annotations allow type checking and IDEs autocompletion

const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');

/** @type {import('@docusaurus/types').Config} */
const config = {
title: 'The Keep3r Network',
tagline: 'All the Jobs That’s Fit to Network.',
url: 'https://keep3r.network/',
baseUrl: '/',
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
favicon: 'img/favicon.ico',
noIndex: true,
i18n: {
defaultLocale: 'en',
locales: ['en'],
},

presets: [
[
'classic',
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
sidebarPath: require.resolve('./sidebars.js'),
editUrl: 'https://github.com/keep3r-network/keep3r-network-v2',
},
theme: {
customCss: require.resolve('./src/css/custom.css'),
},
}),
],
],

themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
colorMode: {
defaultMode: 'dark',
disableSwitch: true,
respectPrefersColorScheme: false,
},
navbar: {
title: 'Keep3r',
logo: {
alt: 'Keep3r',
src: 'img/logo.svg',
},
items: [
{
href: 'https://github.com/facebook/docusaurus',
label: 'GitHub',
position: 'right',
},
],
},
prism: {
theme: lightCodeTheme,
darkTheme: darkCodeTheme,
},
}),
};

module.exports = config;
43 changes: 43 additions & 0 deletions docs/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
{
"name": "keepr-doc",
"version": "1.0.0",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
"serve": "docusaurus serve",
"write-translations": "docusaurus write-translations",
"write-heading-ids": "docusaurus write-heading-ids"
},
"dependencies": {
"@docusaurus/core": "2.1.0",
"@docusaurus/preset-classic": "2.1.0",
"@mdx-js/react": "^1.6.22",
"clsx": "^1.2.1",
"prism-react-renderer": "^1.3.5",
"react": "^17.0.2",
"react-dom": "^17.0.2"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "2.1.0"
},
"browserslist": {
"production": [
">0.5%",
"not dead",
"not op_mini all"
],
"development": [
"last 1 chrome version",
"last 1 firefox version",
"last 1 safari version"
]
},
"engines": {
"node": ">=16.14"
}
}
35 changes: 35 additions & 0 deletions docs/sidebars.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
/**
* Creating a sidebar enables you to:
- create an ordered group of docs
- render a sidebar for each doc of that group
- provide next/previous navigation

The sidebars can be generated from the filesystem, or explicitly defined here.

Create as many sidebars as you want.
*/

// @ts-check

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
// By default, Docusaurus generates a sidebar from the docs folder structure
// sidebar: [{type: 'autogenerated', dirName: '.'}],

// But you can create a sidebar manually
sidebar: [
{type: 'autogenerated', dirName: '.'},
{
type: 'link',
label: 'Github',
href: 'https://github.com/keep3r-network/keep3r-network-v2',
className: 'sidebarspace',
}, {
type: 'link',
label: 'Keep3r V1 Docs',
href: 'https://v1.docs.keep3r.network/',
},
],
};

module.exports = sidebars;
Loading