docs: Add docs for remote facilitator setup (#12)

* docs: Add docs for remote facilitator setup

* fix: lint

* fix: update docs

* fix: update docs

Author: miguelmtzinf

.gitignore

@@ -7,9 +7,6 @@ out/
 /broadcast/*/31337/
 /broadcast/**/dry-run/
 
-# Docs
-docs/
-
 # Dotenv file
 .env
 

docs/gho-stewards.md

@@ -0,0 +1,38 @@
+## Overview
+
+These contracts each control different parameters related to GHO and its facilitators. They allow the Aave DAO and an approved Risk Council to change these parameters, according to set rules and configurations.
+
+Each Steward is designed to have a specific set of segregated responsibilities in an effort to avoid having to redeploy the entire original Steward. Instead, only the specific steward whose responsibilities are affected will have to be redeployed.
+
+### [GhoAaveSteward](/src/contracts/misc/GhoAaveSteward.sol)
+
+This Steward manages parameters related to the GHO token. Specifically, it allows the Risk Council to change the following parameters:
+
+- Borrow Rate
+- Borrow Cap
+- Supply Cap
+
+In addition, the Aave DAO is allowed to change the configuration for the GHO Borrow Rate. This puts restrictions on how much the Risk Council is allowed to change parameters related to the borrow rate. There are 4 parameters that comprise the borrow rate:
+
+- `optimalUsageRatio`
+- `baseVariableBorrowRate`
+- `variableRateSlope1`
+- `variableRateSlope2`
+
+For example, the Aave DAO can specify that the optimalUsageRatio variable may only be changed by 3% at a time.
+
+### [GhoBucketSteward](/src/contracts/misc/GhoBucketSteward.sol)
+
+This Steward allows the Risk Council to set the bucket capacities of controlled facilitators. Additionally, it allows the Aave DAO to add or remove controlled facilitators.
+
+### [GhoCcipSteward](/src/contracts/misc/GhoCcipSteward.sol)
+
+This Steward allows the management of parameters related to CCIP token pools. It allows the Risk Council to update the CCIP bridge limit, and to update the CCIP rate limit configuration.
+
+### [GhoGsmSteward](/src/contracts/misc/GhoGsmSteward.sol)
+
+This Steward allows the Risk Council to update the exposure cap of the GSM, and to update the buy and sell fees of the GSM.
+
+### [RiskCouncilControlled](/src/contracts/misc/RiskCouncilControlled.sol)
+
+This is a helper contract to define the approved Risk Council and enforce its authority to call permissioned functions.

docs/remote-facilitator.md

@@ -0,0 +1,34 @@
+## Overview
+
+The following section explains how remote facilitators for GHO operate and outlines the contracts involved in the setup.
+
+### [OwnableFacilitator](/src/contracts/facilitators/gsm/OwnableFacilitator.sol)
+
+A minimal facilitator contract with minting and burning capabilities, controlled by a single entity. It must be granted the `Facilitator` role on the GHO token with a defined bucket capacity.
+
+This contract can represent a remote minting strategy: it can mint any amount of GHO liquidity on Ethereum, which is then bridged to a remote chain for future use.
+
+### [GhoReserve](/src/contracts/facilitators/gsm/GhoReserve.sol)
+
+It holds GHO liquidity and allows authorized entities to use it up to a defined limit. It is intended for use on remote chains, where GHO is bridged from Ethereum, locked in this reserve, and later distributed by authorized entities through various strategies.
+
+Instead of granting facilitator rights directly on the GHO token to remote facilitators, they are registered as entities in the `GhoReserve`. This indirection is necessary because GHO can only be minted on Ethereum.
+
+A single `GhoReserve` instance can be shared across multiple remote faciltiators, or each remote facilitator can have a dedicated one. Both setups are functionally equivalent, though the shared approach is simpler.
+
+### Remote Facilitators
+
+Remote facilitators function similarly to those on Ethereum, but the way GHO is brought into circulation differs (since GHO can only be minted on Ethereum). Existing minting strategies such as `GhoDirectMinter` (for distribution via Aave V3 Pools) and GSM (for swapping GHO with exogenous assets) can be adapted as remote facilitators using the following setup:
+
+[On Ethereum]
+
+1. An `OwnableFacilitator` contract is deployed to represent the minting strategy on the remote chain. It is granted the `Facilitator` role on the Ethereum `GhoToken` contract, with a defined bucket capacity X.
+2. An amount X of GHO is minted via the `OwnableFacilitator` and bridged to the remote chain (typically via `CCIP`).
+
+[On the Remote Chain]
+
+1. A `GhoReserve` contract is deployed to hold the X GHO bridged from Ethereum. The remote minting strategy is registered as an entity in the `GhoReserve`, granting it permission to use and restore GHO liquidity.
+2. The strategy operates using GHO from the `GhoReserve`, following its internal logic and collateralization rules.
+3. Unused GHO remains in the `GhoReserve`. If the strategy is deprecated or idle for an extended period, the GHO can be transferred out and bridged back to Ethereum for burning.
+
+Note: A `GhoReserve` can support multiple minting strategies concurrently. It's up to the configuration whether to deploy a dedicated `GhoReserve` per strategy or share a single instance among several.