fee refunds: document new fee refund by recipient RPCs (#582)

* Apply suggestions from code review
flashbots · Oct 1, 2024 · 0561a08 · 0561a08
1 parent 0dfc20f
commit 0561a08
Show file tree

Hide file tree

Showing 2 changed files with 90 additions and 1 deletion.
diff --git a/docs/flashbots-auction/advanced/rpc-endpoint.mdx b/docs/flashbots-auction/advanced/rpc-endpoint.mdx
@@ -838,6 +838,85 @@ where
 - `consideredByBuildersAt`: indicates time at which each builder selected the bundle to be included in the target block
 - `sealedByBuildersAt`: indicates time at which each builder sealed a block containing the bundle
 
+### flashbots_getFeeRefundTotalsByRecipient
+
+The `flashbots_getFeeRefundTotalsByRecipient` JSON-RPC method returns the total amount of fee refunds that have been earned by a specific address.  Our refund process calculates these values weekly.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "flashbots_getFeeRefundTotalsByRecipient",
+  "params": [
+    {
+      recipient,       // String, the address to query for fee refunds
+    }
+  ]
+}
+```
+
+The response contains three fields:
+
+```json
+{
+  "pending":"0x17812ea4fbbe314",
+  "received":"0x108d1b27b63a213",
+  "maxBlockNumber":"0x13ddb08"
+}
+```
+
+- `pending`: the total amount of fee refunds that have been earned but not yet received by the recipient
+- `received`: the total amount of fee refunds that have been received by the recipient
+- `maxBlockNumber`: the highest block number for which fee refunds have been processed
+
+### flashbots_getFeeRefundsByRecipient
+
+The `flashbots_getFeeRefundsByRecipient` JSON-RPC method returns detailed information about [fee refunds](/flashbots-protect/gas-fee-refunds) that have been earned by a specific address.  Our refund process calculates these values weekly.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "flashbots_getFeeRefundsByRecipient",
+  "params": [
+    {
+      recipient,       // String, the address to query for fee refunds
+      cursor,          // [optional] String, the cursor to continue from
+    }
+  ]
+}
+```
+
+Responses are paginated and contain the following fields:
+
+```json
+{
+  "refunds": [
+    {
+      "hash": "0x...",
+      "amount": "0x...",
+      "blockNumber": "0x13ddaa4",
+      "status": "pending",
+      "recipient": "0x..."
+    },
+    ...
+  ],
+  "cursor": "0x..."
+}
+```
+
+The `"refunds"` field contains an array of per-order fee refunds, each with the following fields:
+
+- `hash`: the bundle hash or transaction hash associated with the fee refund
+- `amount`: the amount of the fee refund, in wei
+- `blockNumber`: the block number the order was contained in
+- `status`: the status of the fee refund, either "pending" or "received"
+- `recipient`: the address the fee refund is credited to, either the bundle signer or transaction sender
+
+The `"cursor"` field is only included if there are more fee refunds to fetch. To continue fetching fee refunds, include the cursor as the second argument in the next request.
+
+NOTE: This API currently only returns details for bundles included in block 20802497 and later.  To see total fee refunds processed for a specific address since inception, use the `flashbots_getFeeRefundTotalsByRecipient` method.
+
 ### flashbots_setFeeRefundRecipient
 
 The `flashbots_setFeeRefundRecipient` JSON-RPC method allows a user to "delegate" their [fee refunds](/flashbots-auction/advanced/gas-fee-refunds) to a specific wallet address.  Two addresses must be provided, the first is the address associated with the signing key used to authenticate your request, while the second is the address to send refunds to.

diff --git a/docs/flashbots-protect/gas-fee-refunds.md b/docs/flashbots-protect/gas-fee-refunds.md
@@ -44,4 +44,14 @@ For the private transaction API: The refund recipient is the signer used on the
 
 ## How to track refunds
 
-Refunds are tracked from a start date of July 8, 2024. Users wil be able to view refund amounts via an upcoming API.
+Refunds are tracked from a start date of July 8, 2024. Refunds are sent to recipients in batches, and originate from our builder address `0xdf99A0839818B3f120EBAC9B73f82B617Dc6A555`. The recipient can track the status of their refunds using the [`flashbots_getFeeRefundTotalsByRecipient`](/flashbots-auction/advanced/rpc-endpoint#flashbots_getfeerefundtotalsbyrecipient) RPC method.
+
+## Distributed refunds
+
+Refunds have been sent as part of the following on-chain transactions:
+
+| Block Number | Sender                                     | Transaction Hash                                                                                                                                                 | Refunded Amount            |
+|--------------|--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|
+| 20728671     | 0xdf99A0839818B3f120EBAC9B73f82B617Dc6A555 | [0xe4c242dbaf75b0c72bf061cb0b24dfb2ac9b889c8312f85502b819c522143475](https://etherscan.io/tx/0xe4c242dbaf75b0c72bf061cb0b24dfb2ac9b889c8312f85502b819c522143475) | `0.005350659617303609` ETH |
+| 20730702     | 0xdf99A0839818B3f120EBAC9B73f82B617Dc6A555 | [0x7f4b2747bca62e7cb30595bc8fd597d00b111f6e30836f90420a5f596fe6fb20](https://etherscan.io/tx/0x7f4b2747bca62e7cb30595bc8fd597d00b111f6e30836f90420a5f596fe6fb20) | `2.178974530716050227` ETH |
+| 20737357     | 0xdf99A0839818B3f120EBAC9B73f82B617Dc6A555 | [0xa975df43bd397f2a6776811c46d8208df5833b4800f152d5e7df2f96fc20d560](https://etherscan.io/tx/0xa975df43bd397f2a6776811c46d8208df5833b4800f152d5e7df2f96fc20d560) | `1.012930151524122284` ETH |