@keep-network/coverage-pools

: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/relay-sol@2.0.2 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 <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/ropsten/, 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/<network>/ 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 <<package-structure-table, table>>.

.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 <<dependencies-packages,node packages pulled from the NPM registry>> or <<dependencies-predefined,predefined addresses>> stored in external/<network>/ 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 <package>.

Example: +

yarn add @keep-network/keep-core@1.8.0-dev

1. Add an entry in hardhat.config.ts under external property.

Example: +

  external: {
    contracts: [
      // ...
      {
        artifacts: "node_modules/@keep-network/keep-core/artifacts",
      }
    ],
    deployments: {
      // ...
      ropsten: [
         // ...
        "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/<network>/<contract_name>.json.

Example: external/ropsten/UniswapV2Router.json

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

Example: +

{
  "address": "0xZZabcd0000000000000000000000000000000001",
  "abi": [
     // ...
  ]
}

1. Make sure the directory path is listed in hardhat.config.ts under external.deployments.<network> property.

Example: +

  external: {
    deployments: {
      // ...
      ropsten: [
         // ...
        "./external/ropsten",
      ],
    },
  },

===== Usage in scripts

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

Example:

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.