From bace36fb407bc3c2bd45c185680c46df7217edcf Mon Sep 17 00:00:00 2001 From: Ryan Schneider Date: Mon, 30 Sep 2024 12:14:01 -0700 Subject: [PATCH 1/4] fee refunds: document new fee refund by receipient RPCs --- .../advanced/rpc-endpoint.mdx | 79 +++++++++++++++++++ docs/flashbots-protect/gas-fee-refunds.md | 12 ++- 2 files changed, 90 insertions(+), 1 deletion(-) diff --git a/docs/flashbots-auction/advanced/rpc-endpoint.mdx b/docs/flashbots-auction/advanced/rpc-endpoint.mdx index 119c0d0a8..64196f99e 100644 --- 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 processed for a specific address. + +```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 processed but not yet sent to the recipient +- `received`: the total amount of fee refunds that have been processed and sent to 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 that have been processed for a specific address. + +```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 +{ + "orders": [ + { + "hash": "0x...", + "amount": "0x...", + "blockNumber": "0x13ddaa4", + "status": "pending", + "recipient": "0x..." + }, + ... + ], + "cursor": "0x..." +} +``` + +The `"orders"` field contains an array of fee refund orders, 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 index 922673c46..e9229f758 100644 --- 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 | From 22ec9b1c5032a7e4ce0396ccb2f0eaab5ef1496a Mon Sep 17 00:00:00 2001 From: Ryan Schneider Date: Mon, 30 Sep 2024 15:17:39 -0700 Subject: [PATCH 2/4] fixup: changes based on comments from Shea --- docs/flashbots-auction/advanced/rpc-endpoint.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/flashbots-auction/advanced/rpc-endpoint.mdx b/docs/flashbots-auction/advanced/rpc-endpoint.mdx index 64196f99e..d7788628a 100644 --- a/docs/flashbots-auction/advanced/rpc-endpoint.mdx +++ b/docs/flashbots-auction/advanced/rpc-endpoint.mdx @@ -840,7 +840,7 @@ where ### flashbots_getFeeRefundTotalsByRecipient -The `flashbots_getFeeRefundTotalsByRecipient` JSON-RPC method returns the total amount of fee refunds that have been processed for a specific address. +The `flashbots_getFeeRefundTotalsByRecipient` JSON-RPC method returns the total amount of fee refunds that have been processed for a specific address. Our refund process calculates these values weekly. ```json { @@ -865,13 +865,13 @@ The response contains three fields: } ``` -- `pending`: the total amount of fee refunds that have been processed but not yet sent to the recipient +- `pending`: the total amount of fee refunds not yet received by the recipient - `received`: the total amount of fee refunds that have been processed and sent to 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 that have been processed for a specific address. +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 { From 84077ed3502b2aec0a861270368afbb53f8c4b44 Mon Sep 17 00:00:00 2001 From: Ryan Schneider Date: Tue, 1 Oct 2024 11:25:10 -0700 Subject: [PATCH 3/4] Apply suggestions from code review --- docs/flashbots-auction/advanced/rpc-endpoint.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/flashbots-auction/advanced/rpc-endpoint.mdx b/docs/flashbots-auction/advanced/rpc-endpoint.mdx index d7788628a..6dcb45d9a 100644 --- a/docs/flashbots-auction/advanced/rpc-endpoint.mdx +++ b/docs/flashbots-auction/advanced/rpc-endpoint.mdx @@ -840,7 +840,7 @@ where ### flashbots_getFeeRefundTotalsByRecipient -The `flashbots_getFeeRefundTotalsByRecipient` JSON-RPC method returns the total amount of fee refunds that have been processed for a specific address. Our refund process calculates these values weekly. +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 { @@ -865,8 +865,8 @@ The response contains three fields: } ``` -- `pending`: the total amount of fee refunds not yet received by the recipient -- `received`: the total amount of fee refunds that have been processed and sent to the recipient +- `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 @@ -891,7 +891,7 @@ Responses are paginated and contain the following fields: ```json { - "orders": [ + "refunds": [ { "hash": "0x...", "amount": "0x...", @@ -905,7 +905,7 @@ Responses are paginated and contain the following fields: } ``` -The `"orders"` field contains an array of fee refund orders, each with the following fields: +The `"refund"` 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 From 80ee4e85b5e15a2fad6c3e84636f8336e75a2331 Mon Sep 17 00:00:00 2001 From: Ryan Schneider Date: Tue, 1 Oct 2024 12:24:51 -0700 Subject: [PATCH 4/4] Apply suggestions from code review --- docs/flashbots-auction/advanced/rpc-endpoint.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/flashbots-auction/advanced/rpc-endpoint.mdx b/docs/flashbots-auction/advanced/rpc-endpoint.mdx index 6dcb45d9a..414bcd9aa 100644 --- a/docs/flashbots-auction/advanced/rpc-endpoint.mdx +++ b/docs/flashbots-auction/advanced/rpc-endpoint.mdx @@ -905,7 +905,7 @@ Responses are paginated and contain the following fields: } ``` -The `"refund"` field contains an array of per-order fee refunds, each with the following fields: +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