Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/keep-network/coverage-pools

A governable, fee-earning asset pool to cover low-likelihood on-chain events.
https://github.com/keep-network/coverage-pools

Last synced: 18 days ago
JSON representation

A governable, fee-earning asset pool to cover low-likelihood on-chain events.

Awesome Lists containing this project

README 

        
:toc: macro



= Coverage pool



https://github.com/keep-network/coverage-pools/actions/workflows/contracts.yml[image:https://img.shields.io/github/actions/workflow/status/keep-network/coverage-pools/contracts.yml?branch=main&event=push&label=Coverage%20pool%20contracts%20build[Coverage pool contracts build status]]



A governable, fee-earning asset pool to cover low-likelihood on-chain events.



toc::[]



== What is it?



A coverage pool is a flexible new money lego that can be used as a back-stop or

"buyer of last resort" in on-chain financial systems.



Across DeFi, young systems are hiding and shuffling around risk for perceived

security. These risks are part of what drive yield; but stacked atop eachother,

risks are multiplied.



Coverage pools can be used in these systems to offset risk, allowing human or

algorithmic governance to reward underwriters. They're designed as building

blocks rather than a standalone product, allowing system designers and

communities to tailor risk management to their circumstances.



== Goals



1. Pool assets to back risk denominated in a particular asset.

2. Manage those assets without unnecessary reliance on oracles.

3. Allow underwriters to choose the asset exposure that best fits their

   portfolio, increasing capital participation.

4. Share risks and rewards across all underwriters, subject to their asset

   exposure.



The first iteration of the design focuses on backing a single system authority

than can file and approve its own claims against the pool, in the asset the

pool is configured to support. Governance and underwriters are expected to

review and judge the risk of that system authority, as it has the power to

liquidate the pool.



Future iterations could introduce explicit synthetic asset minting for claim

management, though that functionality should be easy to build atop the initial

design.



== Questions



> Doesn't this already exist?



Probably. The ideas behind coverage pools have been picked from a number of

DeFi and TradFi systems. The sum of the parts— choose-your-own-asset pools with

socialized rewards and losses, without outside oracles — is what's interesting

as a building block.



> Why shouldn't I just use Nexus Mutual, Opyn, or another risk management

> solution?



You should! Coverage pools are a component for new on-chain financial systems,

not a replacement for end user applications. If you need to cover a particular

risk of yours, there are a variety of centralized and decentralized options on

the market. If you need to cover risk in a new system... maybe because you're

building a synthetic asset exchange, or a lending platform — coverage pools

might be for you.



== Getting started



* Read the link:./docs/design.adoc[v1 design documentation].

* For questions and support, join the #keep-protocol channel on

https://discord.gg/4R6RGFf[Discord].



== Build, test and deploy



Coverage pool contracts use https://hardhat.org/[*Hardhat*] development

environment. To build and deploy these contracts, please follow the instructions

presented below.



=== Prerequisites



Please make sure you have the following prerequisites installed on your machine:



- https://nodejs.org[Node.js] >12.22.1

- https://yarnpkg.com[Yarn] >1.22.10



=== Build contracts



To build the smart contracts, install node packages first:

```

yarn install

```

Once packages are installed, you can build the smart contracts using:

```

yarn build

```

Compiled contracts will land in the `build/` directory.



*NOTE:* The `coverage-pools` package contains an indirect dependency to

`@summa-tx/[email protected]` package, which downloads one of its sub-dependencies

via unathenticated `git://` protocol. That protocol is no longer supported by

GitHub. This means that in certain situations installation of the package or

update of its dependencies using Yarn may result in `The unauthenticated git

protocol on port 9418 is no longer supported` or `unable to connect to

github.com` error. +

As a workaround, we advise changing Git configuration to use `https://` protocol

instead of `git://` by executing:

```

git config --global url."https://".insteadOf git://

```



=== Test contracts



There are multiple test scenarios living in the `test` directory.

You can run them by doing:

```

yarn test

```



=== Deploy contracts



To deploy all contracts on the given network, please run:

```

yarn deploy --network 

```



If contracts haven't been built yet or changes occurred, this task will build

the contracts before running the deployment script.



==== Deployment artifacts



Once the deployment terminates, a new `deployments` directory containing all

deployment info will be created. It can be directly used by dApps or other client

code as it contains deployment details like chain ID, transaction hash, ABI or

address for each contract.



The `deployments/` directory contains a separate sub-directory for each network, e.g.

`deployments/sepolia/`, `deployments/mainnet/`. For a convenient usage of the

package we publish the deployment artifacts in a separate package for every

network. The package contains deployment artifacts under `artifacts/` directory,

which is a a copy of `deployments//` directory.



===== Export mode



Apart from deployments saved in the `deployments/` folder the details will be also

stored in a lightweight file `export.json`, which contains a handy summary of the

deployment info for all contracts in one place. However, it doesn't contain the

deployment transaction hash making it inappropriate for some use cases relying on

this field.



Please note that it is also possible to export deployment details for all supported

networks into a single file using `--export-all` option. This can be useful for

dApps supporting multiple networks at once.



For more details see `hardhat-deploy` plugin https://github.com/wighawag/hardhat-deploy#exporting-deployments[documentation].



==== Published package structure



Deployed contracts are packaged and published to the NPM registry. 



Separate packages for every network are created according to the rules described in

https://github.com/keep-network/keep-core/blob/main/docs/rfc/rfc-18-release-management.adoc[RFC-18].



A package follows a directory structure described in the <>.



.Published package structure

[[package-structure-table]]

[%autowidth,cols="1,3"]

|===

|Path|Description



|`artifacts/`

|Deployment artifacts for the given network, see <>



|`build/contracts/`

|Compiled contracts artifacts, see <>



|`contracts/`

|Contracts source code



|`export.json`

|Single-file deployment export, see <>

|===



==== Deployment parametrization



The deployment scripts parametrization is handled by environment variables.



Following parameters are supported:



[cols="1,2,1"]

|===

|Variable|Description|Default



|`INITIAL_SWAP_STRATEGY`

|Initial swap strategy which will be used by the risk manager.

This should be the name of one of the `ISignerBondsSwapStrategy` implementations.

|`SignerBondsManualSwap`

|===



==== External dependencies



Deployment scripts require external contract dependencies. The scripts support

dependencies as <>

or <> stored in `external//` directory.



For more details see `hardhat-deploy` plugin https://github.com/wighawag/hardhat-deploy#importing-deployment-from-other-projects-with-truffle-support[documentation].



[[dependencies-packages]]

===== Node packages



To add an external package dependency: 



1. Add a package dependency with `yarn add `.

+

Example:

+

```sh

yarn add @keep-network/[email protected]

```



2. Add an entry in `hardhat.config.ts` under `external` property.

+

Example:

+

```js

  external: {

    contracts: [

      // ...

      {

        artifacts: "node_modules/@keep-network/keep-core/artifacts",

      }

    ],

    deployments: {

      // ...

      sepolia: [

         // ...

        "node_modules/@keep-network/keep-core/artifacts",

      ],

    },

  },

```



This solution support both Hardhat and Truffle artifacts.



[[dependencies-predefined]]

===== Predefined artifacts



To add a predefined single contract dependency for a given network:



1. Create a file under `external//.json`.

+

Example: `external/sepolia/UniswapV2Router.json`



2. Save an address and optionally an ABI for the contract in the file.

+

Example:

+

```json

{

  "address": "0xZZabcd0000000000000000000000000000000001",

  "abi": [

     // ...

  ]

}

```



3. Make sure the directory path is listed in `hardhat.config.ts` under

`external.deployments.` property.

+

Example:

+

```js

  external: {

    deployments: {

      // ...

      sepolia: [

         // ...

        "./external/sepolia",

      ],

    },

  },

```



===== Usage in scripts



External artifacts can be used in scripts with `deployments.get` or `deployments.getOrNull`

functions.



Example:

```js

const KeepToken = await deployments.get("KeepToken")

deployments.log(`using external KeepToken at ${KeepToken.address}`)

```



==== Deployment scripts structure and tags



The deployment script is divided into multiple sub-scripts placed in the

`deploy` directory. It uses the

https://github.com/wighawag/hardhat-deploy#deploy-scripts-tags-and-dependencies[tags and dependencies]

system provided by the `hardhat-deploy` plugin. Such a structure allows to

run arbitrary parts of the entire deployment by using the tag mechanism. For

example, to deploy only the `AssetPool` contract (with their dependencies),

a following command can be used:

```

yarn deploy --network localhost --tags AssetPool

```

Multiple deployment sub-scripts also improves the readability and allows

specifying dependencies between components in an explicit way.