chore: add blockSubscribe api docs

docs/src/developing/clients/jsonrpc-api.md

@@ -85,6 +85,8 @@ gives a convenient interface for the RPC methods.
 
 Unstable methods may see breaking changes in patch releases and may not be supported in perpetuity.
 
+- [blockSubscribe](jsonrpc-api.md#blocksubscribe---unstable-disabled-by-default)
+- [blockUnsubscribe](jsonrpc-api.md#blockunsubscribe)
 - [slotsUpdatesSubscribe](jsonrpc-api.md#slotsupdatessubscribe---unstable)
 - [slotsUpdatesUnsubscribe](jsonrpc-api.md#slotsupdatesunsubscribe)
 - [voteSubscribe](jsonrpc-api.md#votesubscribe---unstable-disabled-by-default)
@@ -3443,6 +3445,339 @@ Result:
 {"jsonrpc": "2.0","result": true,"id": 1}
 ```
 
+### blockSubscribe - Unstable, disabled by default
+
+**This subscription is unstable and only available if the validator was started
+with the `--rpc-pubsub-enable-block-subscription` flag. The format of this
+subscription may change in the future**
+
+Subscribe to receive notification anytime a new block is Confirmed or Finalized.
+
+#### Parameters:
+
+- `filter: <string>|<object>` - filter criteria for the logs to receive results by account type; currently supported:
+  - "all" - include all transactions in block
+  - `{ "mentionsAccountOrProgram": <string> }` - return only transactions that mention the provided public key (as base-58 encoded string). If no mentions in a given block, then no notification will be sent.
+- `<object>` - (optional) Configuration object containing the following optional fields:
+  - (optional) [Commitment](jsonrpc-api.md#configuring-state-commitment)
+  - (optional) `encoding: <string>` - encoding for Account data, either "base58" (*slow*), "base64", "base64+zstd" or "jsonParsed".
+    "jsonParsed" encoding attempts to use program-specific state parsers to return more human-readable and explicit account state data. If "jsonParsed" is requested but a parser cannot be found, the field falls back to base64 encoding, detectable when the `data` field is type `<string>`. Default is "base64".
+  - (optional) `transactionDetails: <string>` - level of transaction detail to return, either "full", "signatures", or "none". If parameter not provided, the default detail level is "full".
+  - (optional) `showRewards: bool` - whether to populate the `rewards` array. If parameter not provided, the default includes rewards.
+
+#### Results:
+
+- `integer` - subscription id \(needed to unsubscribe\)
+
+#### Example:
+
+Request:
+```json
+{"jsonrpc": "2.0", "id": "1", "method": "blockSubscribe", "params": ["all"]}
+```
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "method": "blockSubscribe",
+  "params": [
+    {"mentionsAccountOrProgram": "LieKvPRE8XeX3Y2xVNHjKlpAScD12lYySBVQ4HqoJ5op"},
+    {
+      "commitment": "confirmed",
+      "encoding": "base64",
+      "showRewards": true,
+      "transactionDetails": "full"
+    }
+  ]
+}
+```
+
+Result:
+```json
+{"jsonrpc": "2.0","result": 0,"id": 1}
+```
+
+#### Notification Format:
+
+The notification will be an object with the following fields:
+
+-`slot: <u64>` - The corresponding slot.
+- `err: <object | null>` - Error if something went wrong publishing the notification otherwise null.
+- `block: <object | null>` - A block object as seen in the [getBlock](jsonrpc-api.md#getblock) RPC HTTP method.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "blockNotification",
+  "params": {
+    "result": {
+      "context": {
+        "slot": 112301554
+      },
+      "value": {
+        "slot": 112301554,
+        "block": {
+          "previousBlockhash": "GJp125YAN4ufCSUvZJVdCyWQJ7RPWMmwxoyUQySydZA",
+          "blockhash": "6ojMHjctdqfB55JDpEpqfHnP96fiaHEcvzEQ2NNcxzHP",
+          "parentSlot": 112301553,
+          "transactions": [
+            {
+              "transaction": [
+                "OpltwoUvWxYi1P2U8vbIdE/aPntjYo5Aa0VQ2JJyeJE2g9Vvxk8dDGgFMruYfDu8/IfUWb0REppTe7IpAuuLRgIBAAkWnj4KHRpEWWW7gvO1c0BHy06wZi2g7/DLqpEtkRsThAXIdBbhXCLvltw50ZnjDx2hzw74NVn49kmpYj2VZHQJoeJoYJqaKcvuxCi/2i4yywedcVNDWkM84Iuw+cEn9/ROCrXY4qBFI9dveEERQ1c4kdU46xjxj9Vi+QXkb2Kx45QFVkG4Y7HHsoS6WNUiw2m4ffnMNnOVdF9tJht7oeuEfDMuUEaO7l9JeUxppCvrGk3CP45saO51gkwVYEgKzhpKjCx3rgsYxNR81fY4hnUQXSbbc2Y55FkwgRBpVvQK7/+clR4Gjhd3L4y+OtPl7QF93Akg1LaU9wRMs5nvfDFlggqI9PqJl+IvVWrNRdBbPS8LIIhcwbRTkSbqlJQWxYg3Bo2CTVbw7rt1ZubuHWWp0mD/UJpLXGm2JprWTePNULzHu67sfqaWF99LwmwjTyYEkqkRt1T0Je5VzHgJs0N5jY4iIU9K3lMqvrKOIn/2zEMZ+ol2gdgjshx+sphIyhw65F3J/Dbzk04LLkK+CULmN571Y+hFlXF2ke0BIuUG6AUF+4214Cu7FXnqo3rkxEHDZAk0lRrAJ8X/Z+iwuwI5cgbd9uHXZaGT2cvhRs7reawctIXtX1s3kTqM9YV+/wCpDLAp8axcEkaQkLDKRoWxqp8XLNZSKial7Rk+ELAVVKWoWLRXRZ+OIggu0OzMExvVLE5VHqy71FNHq4gGitkiKYNFWSLIE4qGfdFLZXy/6hwS+wq9ewjikCpd//C9BcCL7Wl0iQdUslxNVCBZHnCoPYih9JXvGefOb9WWnjGy14sG9j70+RSVx6BlkFELWwFvIlWR/tHn3EhHAuL0inS2pwX7ZQTAU6gDVaoqbR2EiJ47cKoPycBNvHLoKxoY9AZaBjPl6q8SKQJSFyFd9n44opAgI6zMTjYF/8Ok4VpXEESp3QaoUyTI9sOJ6oFP6f4dwnvQelgXS+AEfAsHsKXxGAIUDQENAgMEBQAGBwgIDg8IBJCER3QXl1AVDBADCQoOAAQLERITDAjb7ugh3gOuTy==",
+                "base64"
+              ],
+              "meta": {
+                "err": null,
+                "status": {
+                  "Ok": null
+                },
+                "fee": 5000,
+                "preBalances": [
+                  1758510880,
+                  2067120,
+                  1566000,
+                  1461600,
+                  2039280,
+                  2039280,
+                  1900080,
+                  1865280,
+                  0,
+                  3680844220,
+                  2039280
+                ],
+                "postBalances": [
+                  1758505880,
+                  2067120,
+                  1566000,
+                  1461600,
+                  2039280,
+                  2039280,
+                  1900080,
+                  1865280,
+                  0,
+                  3680844220,
+                  2039280
+                ],
+                "innerInstructions": [
+                  {
+                    "index": 0,
+                    "instructions": [
+                      {
+                        "programIdIndex": 13,
+                        "accounts": [
+                          1,
+                          15,
+                          3,
+                          4,
+                          2,
+                          14
+                        ],
+                        "data": "21TeLgZXNbtHXVBzCaiRmH"
+                      },
+                      {
+                        "programIdIndex": 14,
+                        "accounts": [
+                          3,
+                          4,
+                          1
+                        ],
+                        "data": "6qfC8ic7Aq99"
+                      },
+                      {
+                        "programIdIndex": 13,
+                        "accounts": [
+                          1,
+                          15,
+                          3,
+                          5,
+                          2,
+                          14
+                        ],
+                        "data": "21TeLgZXNbsn4QEpaSEr3q"
+                      },
+                      {
+                        "programIdIndex": 14,
+                        "accounts": [
+                          3,
+                          5,
+                          1
+                        ],
+                        "data": "6LC7BYyxhFRh"
+                      }
+                    ]
+                  },
+                  {
+                    "index": 1,
+                    "instructions": [
+                      {
+                        "programIdIndex": 14,
+                        "accounts": [
+                          4,
+                          3,
+                          0
+                        ],
+                        "data": "7aUiLHFjSVdZ"
+                      },
+                      {
+                        "programIdIndex": 19,
+                        "accounts": [
+                          17,
+                          18,
+                          16,
+                          9,
+                          11,
+                          12,
+                          14
+                        ],
+                        "data": "8kvZyjATKQWYxaKR1qD53V"
+                      },
+                      {
+                        "programIdIndex": 14,
+                        "accounts": [
+                          9,
+                          11,
+                          18
+                        ],
+                        "data": "6qfC8ic7Aq99"
+                      }
+                    ]
+                  }
+                ],
+                "logMessages": [
+                  "Program QMNeHCGYnLVDn1icRAfQZpjPLBNkfGbSKRB83G5d8KB invoke [1]",
+                  "Program QMWoBmAyJLAsA1Lh9ugMTw2gciTihncciphzdNzdZYV invoke [2]"
+                ],
+                "preTokenBalances": [
+                  {
+                    "accountIndex": 4,
+                    "mint": "iouQcQBAiEXe6cKLS85zmZxUqaCqBdeHFpqKoSz615u",
+                    "uiTokenAmount": {
+                      "uiAmount": null,
+                      "decimals": 6,
+                      "amount": "0",
+                      "uiAmountString": "0"
+                    },
+                    "owner": "LieKvPRE8XeX3Y2xVNHjKlpAScD12lYySBVQ4HqoJ5op"
+                  },
+                  {
+                    "accountIndex": 5,
+                    "mint": "iouQcQBAiEXe6cKLS85zmZxUqaCqBdeHFpqKoSz615u",
+                    "uiTokenAmount": {
+                      "uiAmount": 11513.0679,
+                      "decimals": 6,
+                      "amount": "11513067900",
+                      "uiAmountString": "11513.0679"
+                    },
+                    "owner": "rXhAofQCT7NN9TUqigyEAUzV1uLL4boeD8CRkNBSkYk"
+                  },
+                  {
+                    "accountIndex": 10,
+                    "mint": "Saber2gLauYim4Mvftnrasomsv6NvAuncvMEZwcLpD1",
+                    "uiTokenAmount": {
+                      "uiAmount": null,
+                      "decimals": 6,
+                      "amount": "0",
+                      "uiAmountString": "0"
+                    },
+                    "owner": "CL9wkGFT3SZRRNa9dgaovuRV7jrVVigBUZ6DjcgySsCU"
+                  },
+                  {
+                    "accountIndex": 11,
+                    "mint": "Saber2gLauYim4Mvftnrasomsv6NvAuncvMEZwcLpD1",
+                    "uiTokenAmount": {
+                      "uiAmount": 15138.514093,
+                      "decimals": 6,
+                      "amount": "15138514093",
+                      "uiAmountString": "15138.514093"
+                    },
+                    "owner": "LieKvPRE8XeX3Y2xVNHjKlpAScD12lYySBVQ4HqoJ5op"
+                  }
+                ],
+                "postTokenBalances": [
+                  {
+                    "accountIndex": 4,
+                    "mint": "iouQcQBAiEXe6cKLS85zmZxUqaCqBdeHFpqKoSz615u",
+                    "uiTokenAmount": {
+                      "uiAmount": null,
+                      "decimals": 6,
+                      "amount": "0",
+                      "uiAmountString": "0"
+                    },
+                    "owner": "LieKvPRE8XeX3Y2xVNHjKlpAScD12lYySBVQ4HqoJ5op"
+                  },
+                  {
+                    "accountIndex": 5,
+                    "mint": "iouQcQBAiEXe6cKLS85zmZxUqaCqBdeHFpqKoSz615u",
+                    "uiTokenAmount": {
+                      "uiAmount": 11513.103028,
+                      "decimals": 6,
+                      "amount": "11513103028",
+                      "uiAmountString": "11513.103028"
+                    },
+                    "owner": "rXhAofQCT7NN9TUqigyEAUzV1uLL4boeD8CRkNBSkYk"
+                  },
+                  {
+                    "accountIndex": 10,
+                    "mint": "Saber2gLauYim4Mvftnrasomsv6NvAuncvMEZwcLpD1",
+                    "uiTokenAmount": {
+                      "uiAmount": null,
+                      "decimals": 6,
+                      "amount": "0",
+                      "uiAmountString": "0"
+                    },
+                    "owner": "CL9wkGFT3SZRRNa9dgaovuRV7jrVVigBUZ6DjcgySsCU"
+                  },
+                  {
+                    "accountIndex": 11,
+                    "mint": "Saber2gLauYim4Mvftnrasomsv6NvAuncvMEZwcLpD1",
+                    "uiTokenAmount": {
+                      "uiAmount": 15489.767829,
+                      "decimals": 6,
+                      "amount": "15489767829",
+                      "uiAmountString": "15489.767829"
+                    },
+                    "owner": "BeiHVPRE8XeX3Y2xVNrSsTpAScH94nYySBVQ4HqgN9at"
+                  }
+                ],
+                "rewards": []
+              }
+            }
+          ],
+          "blockTime": 1639926816,
+          "blockHeight": 101210751
+        },
+        "err": null
+      }
+    },
+    "subscription": 14
+  }
+}
+```
+
+### blockUnsubscribe
+
+Unsubscribe from block notifications
+
+#### Parameters:
+
+- `<integer>` - subscription id to cancel
+
+#### Results:
+
+- `<bool>` - unsubscribe success message
+
+#### Example:
+
+Request:
+```json
+{"jsonrpc":"2.0", "id":1, "method":"blockUnsubscribe", "params":[0]}
+```
+
+Response:
+```json
+{"jsonrpc": "2.0","result": true,"id": 1}
+```
+
 ### logsSubscribe
 
 Subscribe to transaction logging