From e5362f7f6f3982c600f2368041115277dc96ef24 Mon Sep 17 00:00:00 2001
From: clemlak <clementlakhal@gmail.com>
Date: Tue, 28 Nov 2023 19:33:31 +0400
Subject: [PATCH] chore: custom strategy guide (wip)

---
 contracts/strategies/README.md | 56 +++++++++++++++++++++++++++++++---
 1 file changed, 51 insertions(+), 5 deletions(-)

diff --git a/contracts/strategies/README.md b/contracts/strategies/README.md
index ea454339..8cf5680d 100644
--- a/contracts/strategies/README.md
+++ b/contracts/strategies/README.md
@@ -1,9 +1,55 @@
-# Portfolio Strategies
+# Writing a custom strategy
 
-Portfolio pools can either use the *default* strategy or rely on an external custom strategy. The latter allows for custom logic to be executed within the pool at specific points in its lifecycle: after the creation of a pool or before a swap.
+## Introduction
 
-Portfolio will rely on specific callback functions that the custom strategy contracts must implement. These functions can be found in the [IStrategy](../interfaces/IStrategy.sol) interface, but it is recommended to inherit from the [StrategyTemplate](./StrategyTemplate.sol) abstract contract to get some default features such as the `onlyPortfolio` modifier.
+Portfolio pools can either use the *default* strategy or rely on an external custom strategy. The latter option allows custom logic to be executed within the pool at specific points in its lifecycle: after the creation of a pool or during a swap.
 
-## Writing a custom Strategy
+Portfolio will rely on specific functions that the custom strategy contracts must implement. These functions can be found in the [IStrategy](../interfaces/IStrategy.sol) interface, but it is recommended to inherit from the [StrategyTemplate](./StrategyTemplate.sol) abstract contract to get some default features such as the `onlyPortfolio` modifier.
 
-(wip)
+## Strategy functions
+
+### Swap Lifecycle
+
+```
+ ┌────┐┌─────────┐     ┌────────┐
+ │User││Portfolio│     │Strategy│
+ └─┬──┘└────┬────┘     └───┬────┘
+   │        │              │
+   │ swap() │              │
+   │───────>│              │
+   │        │              │
+   │        │validatePool()│
+   │        │─────────────>│
+   │        │              │
+   │        │ beforeSwap() │
+   │        │─────────────>│
+   │        │              │
+   │        │validateSwap()│
+   │        │─────────────>│
+ ┌─┴──┐┌────┴────┐     ┌───┴────┐
+ │User││Portfolio│     │Strategy│
+ └────┘└─────────┘     └────────┘
+ ```
+
+### `afterCreate()`
+
+```solidity
+    function afterCreate(
+        uint64 poolId,
+        bytes calldata strategyArgs
+    ) external returns (bool success);
+```
+
+This function is called after the creation of a pool and allows the strategy to perform any initialization logic. The `strategyArgs` parameter is the same as the one passed to the `createPool` function of the Portfolio contract.
+
+### `beforeSwap()`
+
+```solidity
+    function beforeSwap(
+        uint64 poolId,
+        bool sellAsset,
+        address swapper
+    ) external returns (bool success, int256 invariant);
+```
+
+This function is called before a swap is executed and must return a boolean indicating whether the swap should be allowed or not, along with the current invariant.