From 12e84bda1e1940333ba8fb649d289c0fd5303a98 Mon Sep 17 00:00:00 2001
From: Matthias <xmatthias@outlook.com>
Date: Fri, 27 Nov 2020 10:29:45 +0100
Subject: [PATCH] Add developer docs for Protections

---
 docs/developer.md            | 47 +++++++++++++++++++++++++++++++++++-
 docs/includes/protections.md |  2 +-
 2 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/docs/developer.md b/docs/developer.md
index 662905d65..86e9b1078 100644
--- a/docs/developer.md
+++ b/docs/developer.md
@@ -94,7 +94,7 @@ Below is an outline of exception inheritance hierarchy:
 +---+ StrategyError
 ```
 
-## Modules
+## Plugins
 
 ### Pairlists
 
@@ -173,6 +173,51 @@ In `VolumePairList`, this implements different methods of sorting, does early va
         return pairs
 ```
 
+### Protections
+
+Best read the [Protection documentation](configuration.md#protections) to understand protections.
+This Guide is directed towards Developers who want to develop a new protection.
+
+No protection should use datetime directly, but use the provided `date_now` variable for date calculations. This preserves the ability to backtest protections.
+
+!!! Tip "Writing a new Protection"
+    Best copy one of the existing Protections to have a good example.
+
+#### Implementation of a new protection
+
+All Protection implementations must have `IProtection` as parent class.
+For that reason, they must implement the following methods:
+
+* `short_desc()`
+* `global_stop()`
+* `stop_per_pair()`.
+
+`global_stop()` and `stop_per_pair()` must return a ProtectionReturn tuple, which consists of:
+
+* lock pair - boolean
+* lock until - datetime - until when should the pair be locked (will be rounded up to the next new candle)
+* reason - string, used for logging and storage in the database
+
+The `until` portion should be calculated using the provided `calculate_lock_end()` method.
+
+#### Global vs. local stops
+
+Protections can have 2 different ways to stop trading for a limited :
+
+* Per pair (local)
+* For all Pairs (globally)
+
+##### Protections - per pair
+
+Protections that implement the per pair approach must set `has_local_stop=True`.
+The method `stop_per_pair()` will be called once, whenever a sell order is closed, and the trade is therefore closed.
+
+##### Protections - global protection
+
+These Protections should do their evaluation across all pairs, and consequently will also lock all pairs from trading (called a global PairLock).
+Global protection must set `has_global_stop=True` to be evaluated for global stops.
+The method `global_stop()` will be called on every iteration, so they should not do too heavy calculations (or should cache the calculations across runs).
+
 ## Implement a new Exchange (WIP)
 
 !!! Note
diff --git a/docs/includes/protections.md b/docs/includes/protections.md
index 644b98e64..aaf5bbff4 100644
--- a/docs/includes/protections.md
+++ b/docs/includes/protections.md
@@ -1,6 +1,6 @@
 ## Protections
 
-Protections will protect your strategy from unexpected events and market conditions.
+Protections will protect your strategy from unexpected events and market conditions by temporarily stop trading for either one pair, or for all pairs.
 
 !!! Note
     Not all Protections will work for all strategies, and parameters will need to be tuned for your strategy.