From 6577d8e4f603d77618c35a2e70dd1681002651f3 Mon Sep 17 00:00:00 2001
From: Antony Denyer <git@antonydenyer.co.uk>
Date: Thu, 4 Aug 2022 12:39:28 +0100
Subject: [PATCH] Add information about emptyBlockPeriodSeconds (#246)

* Add information about emptyBlockPeriodSeconds

Co-authored-by: rolandtyler <88206508+rolandtyler@users.noreply.github.com>
Co-authored-by: baptiste-b-pegasys <85155432+baptiste-b-pegasys@users.noreply.github.com>
---
 .../configure/consensus-protocols/qbft.md     | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/docs/configure-and-manage/configure/consensus-protocols/qbft.md b/docs/configure-and-manage/configure/consensus-protocols/qbft.md
index 2a54a660..0dc935fa 100644
--- a/docs/configure-and-manage/configure/consensus-protocols/qbft.md
+++ b/docs/configure-and-manage/configure/consensus-protocols/qbft.md
@@ -241,6 +241,59 @@ To update an existing network with a new `blockperiodseconds`:
 1. To verify the changes after the transition block, call
   [`istanbul_getValidators`](../../../reference/api-methods.md#istanbul_getvalidators), specifying `latest`.
 
+### Configure empty block period
+
+A block is produced every block period, whether there are transactions or not. This can lead to your network being bloated with many empty blocks, especially if you have a low block period such as one second. Configuring `emptyBlockPeriodSeconds` helps to reduce the number of empty blocks produced in your network. You can specify `emptyBlockPeriodSeconds` using the config section or with a transition.
+
+!!! example
+
+    ```bash
+    "transitions": [{
+      "block": ...,
+      "blockPeriodSeconds": 2
+      "emptyBlockPeriodSeconds": 60
+    }]
+    ```
+
+In the preceding example, a block is produced every two seconds if there are transactions pending to be mined. If no transactions are pending, then blocks are not produced until after 60 seconds.
+
+The blocks produced with those settings could have timestamps similar to the following:
+
+```yaml
+block: 10
+timestamp: 07:00:00
+transactions: 1
+
+block: 11
+timestamp: 07:00:02
+transactions: 3
+
+block: 12
+timestamp: 07:01:02
+transactions: 0
+
+block: 13
+timestamp: 07:02:02
+transactions: 0
+
+block: 14
+timestamp: 07:02:08
+transactions: 2
+
+block: 15
+timestamp: 07:02:42
+transactions: 1
+
+block: 16
+timestamp: 07:03:12
+transactions: 1
+
+```
+
+!!! Note
+
+    If `emptyBlockPeriodSeconds` is less than `blockPeriodSeconds`, empty blocks continue to be produced at the rate specefied in `blockPeriodSeconds`.
+
 ### Swap validator management methods
 
 To swap between block header validator selection and contract validator selection methods in an existing network: