diff --git a/api-reference/bidder/autodeposit.mdx b/api-reference/bidder/autodeposit.mdx new file mode 100644 index 00000000..f9c296f7 --- /dev/null +++ b/api-reference/bidder/autodeposit.mdx @@ -0,0 +1,4 @@ +--- +title: Add Auto Deposit +openapi: post /v1/bidder/auto_deposit/{amount} +--- \ No newline at end of file diff --git a/api-reference/bidder/autodepositstatus.mdx b/api-reference/bidder/autodepositstatus.mdx new file mode 100644 index 00000000..974ec2ef --- /dev/null +++ b/api-reference/bidder/autodepositstatus.mdx @@ -0,0 +1,4 @@ +--- +title: Get Auto Deposit Status +openapi: get /v1/bidder/auto_deposit_status +--- \ No newline at end of file diff --git a/api-reference/bidder/cancelautodeposit.mdx b/api-reference/bidder/cancelautodeposit.mdx new file mode 100644 index 00000000..640f4e26 --- /dev/null +++ b/api-reference/bidder/cancelautodeposit.mdx @@ -0,0 +1,4 @@ +--- +title: Cancel Auto Deposit +openapi: post /v1/bidder/cancel_auto_deposit +--- \ No newline at end of file diff --git a/api-reference/bidder/getmindeposit.mdx b/api-reference/bidder/getmindeposit.mdx deleted file mode 100644 index b23f7b7e..00000000 --- a/api-reference/bidder/getmindeposit.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Retrieve Min Deposit -openapi: get /v1/bidder/get_min_deposit ---- diff --git a/api-reference/bidder/withdraw.mdx b/api-reference/bidder/withdraw.mdx new file mode 100644 index 00000000..8cfb1668 --- /dev/null +++ b/api-reference/bidder/withdraw.mdx @@ -0,0 +1,4 @@ +--- +title: Withdraw Deposit +openapi: post /v1/bidder/withdraw +--- \ No newline at end of file diff --git a/api-reference/bidder/withdrawfromwindows.mdx b/api-reference/bidder/withdrawfromwindows.mdx new file mode 100644 index 00000000..7b5cd7e1 --- /dev/null +++ b/api-reference/bidder/withdrawfromwindows.mdx @@ -0,0 +1,4 @@ +--- +title: Withdraw Deposit From Windows +openapi: post /v1/bidder/withdraw_from_windows +--- \ No newline at end of file diff --git a/api-reference/debug/canceltx.mdx b/api-reference/debug/canceltx.mdx new file mode 100644 index 00000000..e2cf4f24 --- /dev/null +++ b/api-reference/debug/canceltx.mdx @@ -0,0 +1,4 @@ +--- +title: Cancel Transaction +openapi: post /v1/debug/cancel_transaction/{txHash} +--- \ No newline at end of file diff --git a/api-reference/debug/pendingtxs.mdx b/api-reference/debug/pendingtxs.mdx new file mode 100644 index 00000000..791670cc --- /dev/null +++ b/api-reference/debug/pendingtxs.mdx @@ -0,0 +1,4 @@ +--- +title : Pending Transactions +openapi: get /v1/debug/pending_transactions +--- \ No newline at end of file diff --git a/api-reference/debug/topology.mdx b/api-reference/debug/topology.mdx new file mode 100644 index 00000000..f24f44ae --- /dev/null +++ b/api-reference/debug/topology.mdx @@ -0,0 +1,4 @@ +--- +title: Topology +openapi: get /v1/debug/topology +--- \ No newline at end of file diff --git a/bidder-openapi-spec.json b/bidder-openapi-spec.json index 94b87c05..75855b76 100644 --- a/bidder-openapi-spec.json +++ b/bidder-openapi-spec.json @@ -2,13 +2,102 @@ "openapi": "3.0.0", "info": { "title": "Bidder API", - "version": "1.0.0-alpha-oas3", + "version": "1.0.0-oas3", "license": { "name": "Business Source License 1.1", "url": "https://github.com/primev/mev-commit/blob/main/LICENSE" } }, "paths": { + "/v1/bidder/auto_deposit/{amount}": { + "post": { + "summary": "AutoDeposit", + "description": "AutoDeposit is called by the bidder node to add deposit in the bidder registry and move funds automatily from one window to another.", + "operationId": "Bidder_AutoDeposit", + "responses": { + "200": { + "description": "A successful response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/v1AutoDepositResponse" + } + } + } + }, + "default": { + "description": "An unexpected error response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/googlerpcStatus" + } + } + } + } + }, + "parameters": [ + { + "name": "amount", + "description": "Amount of ETH to be deposited in wei.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "windowNumber", + "description": "Optional window number for querying deposit. If not specified, the current block number is used.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "uint64" + } + }, + { + "name": "blockNumber", + "description": "Optional block number for querying deposit. If specified, calculate window based on this block number.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "uint64" + } + } + ] + } + }, + "/v1/bidder/auto_deposit_status": { + "get": { + "summary": "AutoDepositStatus", + "description": "AutoDepositStatus is called by the bidder node to get the status of the auto deposit.", + "operationId": "Bidder_AutoDepositStatus", + "responses": { + "200": { + "description": "A successful response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/v1AutoDepositStatusResponse" + } + } + } + }, + "default": { + "description": "An unexpected error response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/googlerpcStatus" + } + } + } + } + } + } + }, "/v1/bidder/bid": { "post": { "summary": "SendBid", @@ -58,6 +147,45 @@ } } }, + "/v1/bidder/cancel_auto_deposit": { + "post": { + "summary": "CancelAutoDeposit", + "description": "CancelAutoDeposit is called by the bidder node to cancel the auto deposit.", + "operationId": "Bidder_CancelAutoDeposit", + "responses": { + "200": { + "description": "A successful response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/v1CancelAutoDepositResponse" + } + } + } + }, + "default": { + "description": "An unexpected error response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/googlerpcStatus" + } + } + } + } + }, + "parameters": [ + { + "name": "withdraw", + "in": "query", + "required": false, + "schema": { + "type": "boolean" + } + } + ] + } + }, "/v1/bidder/deposit/{amount}": { "post": { "summary": "Deposit", @@ -159,18 +287,18 @@ ] } }, - "/v1/bidder/get_min_deposit": { - "get": { - "summary": "GetMinDeposit", - "description": "GetMinDeposit is called by the bidder to get the minimum deposit required in the bidder registry to make bids.", - "operationId": "Bidder_GetMinDeposit", + "/v1/bidder/withdraw": { + "post": { + "summary": "Withdraw", + "description": "Withdraw is called by the bidder to withdraw deposit from the bidder registry.", + "operationId": "Bidder_Withdraw", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/v1DepositResponse" + "$ref": "#/components/schemas/v1WithdrawResponse" } } } @@ -185,21 +313,33 @@ } } } - } + }, + "parameters": [ + { + "name": "windowNumber", + "description": "Optional window number for withdrawing deposits. If not specified, the last window number is used.", + "in": "query", + "required": false, + "schema": { + "type": "string", + "format": "uint64" + } + } + ] } }, - "/v1/bidder/withdraw": { + "/v1/bidder/withdraw_from_windows": { "post": { - "summary": "Withdraw", - "description": "Withdraw is called by the bidder to withdraw deposit from the bidder registry.", - "operationId": "Bidder_Withdraw", + "summary": "WithdrawFromWindows", + "description": "WithdrawFromWindows is called by the bidder node to withdraw funds from multiple windows.", + "operationId": "Bidder_WithdrawFromWindows", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/v1WithdrawResponse" + "$ref": "#/components/schemas/v1WithdrawFromWindowsResponse" } } } @@ -217,13 +357,17 @@ }, "parameters": [ { - "name": "windowNumber", - "description": "Optional window number for withdrawing deposits. If not specified, the last window number is used.", + "name": "windowNumbers", + "description": "Window numbers for withdrawing deposits.", "in": "query", - "required": false, + "required": true, + "explode": true, "schema": { - "type": "string", - "format": "uint64" + "type": "array", + "items": { + "type": "string", + "format": "uint64" + } } } ] @@ -232,6 +376,18 @@ }, "components": { "schemas": { + "bidderapiv1AutoDeposit": { + "type": "object", + "properties": { + "amount": { + "type": "string" + }, + "windowNumber": { + "type": "string", + "format": "uint64" + } + } + }, "bidderapiv1Bid": { "type": "object", "example": { @@ -270,6 +426,13 @@ "type": "string", "format": "int64", "description": "Timestamp at which the bid ends decaying." + }, + "revertingTxHashes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Optional array of tx hashes that are allowed to revert or be discarded." } }, "description": "Unsigned bid message from bidders to the bidder mev-commit node.", @@ -303,6 +466,74 @@ }, "additionalProperties": {} }, + "v1AutoDepositResponse": { + "type": "object", + "example": { + "amount_per_window": "1000000000000000000", + "start_block_number": "1" + }, + "properties": { + "startBlockNumber": { + "type": "string", + "format": "uint64" + }, + "amountPerWindow": { + "type": "string" + } + }, + "description": "Response on AutoDeposit request.", + "title": "AutoDeposit response" + }, + "v1AutoDepositStatusResponse": { + "type": "object", + "example": { + "isWorking": true, + "window_balances": [ + { + "amount": "1000000000000000000", + "window_number": 1 + }, + { + "amount": "1000000000000000000", + "window_number": 2 + }, + { + "amount": "1000000000000000000", + "window_number": 3 + } + ] + }, + "properties": { + "windowBalances": { + "type": "array", + "items": { + "$ref": "#/components/schemas/bidderapiv1AutoDeposit" + } + }, + "isWorking": { + "type": "boolean" + } + }, + "description": "AutoDeposit status from the bidder registry.", + "title": "AutoDeposit status response" + }, + "v1CancelAutoDepositResponse": { + "type": "object", + "example": { + "window_numbers": [1, 2, 3] + }, + "properties": { + "windowNumbers": { + "type": "array", + "items": { + "type": "string", + "format": "uint64" + } + } + }, + "description": "CancelAutoDeposit deposit from the bidder registry.", + "title": "CancelAutoDeposit response" + }, "v1Commitment": { "type": "object", "properties": { @@ -357,6 +588,13 @@ "type": "string", "format": "int64", "description": "Timestamp at which the commitment is published." + }, + "revertingTxHashes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Optional array of tx hashes that are allowed to revert or be discarded." } } }, @@ -378,6 +616,35 @@ "description": "Get deposit for bidder in the bidder registry.", "title": "Deposit response" }, + "v1WithdrawFromWindowsResponse": { + "type": "object", + "example": { + "withdraw_responses": [ + { + "amount": "1000000000000000000", + "window_number": 1 + }, + { + "amount": "1000000000000000000", + "window_number": 2 + }, + { + "amount": "1000000000000000000", + "window_number": 3 + } + ] + }, + "properties": { + "withdrawResponses": { + "type": "array", + "items": { + "$ref": "#/components/schemas/v1WithdrawResponse" + } + } + }, + "description": "Withdraw deposit from the bidder registry.", + "title": "Withdraw from multiple windows response" + }, "v1WithdrawResponse": { "type": "object", "example": { diff --git a/debug-openapi-spec.json b/debug-openapi-spec.json new file mode 100644 index 00000000..c00e4fc1 --- /dev/null +++ b/debug-openapi-spec.json @@ -0,0 +1,216 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Debug API", + "version": "1.0.0", + "license": { + "name": "Business Source License 1.1", + "url": "https://github.com/primev/mev-commit/blob/main/LICENSE" + } + }, + "paths": { + "/v1/debug/cancel_transaction/{txHash}": { + "post": { + "summary": "CancelTransaction", + "description": "CancelTransaction is called by the provider to cancel a transaction sent from this wallet.", + "operationId": "DebugService_CancelTransaction", + "responses": { + "200": { + "description": "A successful response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/v1CancelTransactionResponse" + } + } + } + }, + "default": { + "description": "An unexpected error response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/googlerpcStatus" + } + } + } + } + }, + "parameters": [ + { + "name": "txHash", + "description": "Hex string encoding of the hash of the transaction that the bidder wants to cancel.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ] + } + }, + "/v1/debug/pending_transactions": { + "get": { + "summary": "GetPendingTransactions", + "description": "GetPendingTransactions is called by the provider to get the pending transactions for the wallet.", + "operationId": "DebugService_GetPendingTransactions", + "responses": { + "200": { + "description": "A successful response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/v1PendingTransactionsResponse" + } + } + } + }, + "default": { + "description": "An unexpected error response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/googlerpcStatus" + } + } + } + } + } + } + }, + "/v1/debug/topology": { + "get": { + "summary": "GetTopology", + "description": "GetTopology is called by the user to get the topology of the node. The topology\nincludes connectivity information about the node.", + "operationId": "DebugService_GetTopology", + "responses": { + "200": { + "description": "A successful response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/v1TopologyResponse" + } + } + } + }, + "default": { + "description": "An unexpected error response.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/googlerpcStatus" + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "googlerpcStatus": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "details": { + "type": "array", + "items": { + "$ref": "#/components/schemas/protobufAny" + } + } + } + }, + "protobufAny": { + "type": "object", + "properties": { + "@type": { + "type": "string" + } + }, + "additionalProperties": {} + }, + "protobufNullValue": { + "type": "string", + "description": "`NullValue` is a singleton enumeration to represent the null value for the\n`Value` type union.\n\nThe JSON representation for `NullValue` is JSON `null`." + }, + "v1CancelTransactionResponse": { + "type": "object", + "example": { + "txHash": "71c1348f2d7ff7e814f9c3617983703435ea7446de420aeac488bf1de35737e8" + }, + "properties": { + "txHash": { + "type": "string", + "description": "Hex string encoding of the hash of the transaction that the bidder wants to cancel.", + "pattern": "[a-fA-F0-9]{64}" + } + }, + "description": "Hash of the cancellation transaction request.", + "title": "Cancel response", + "required": ["txHash"] + }, + "v1PendingTransactionsResponse": { + "type": "object", + "properties": { + "pendingTransactions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/v1TransactionInfo" + }, + "description": "List of pending transactions in the provider provider_registry." + } + }, + "description": "Transaction info returned by the provider.", + "title": "Pending transactions list", + "required": ["pendingTransactions"] + }, + "v1TopologyResponse": { + "type": "object", + "properties": { + "topology": { + "type": "object", + "description": "Topology of the node." + } + }, + "description": "Topology of the node.", + "title": "Topology", + "required": ["topology"] + }, + "v1TransactionInfo": { + "type": "object", + "example": { + "created": "2009-11-10 23:00:00 +0000 UTC m=+0.000000001", + "nonce": 1234, + "txHash": "71c1348f2d7ff7e814f9c3617983703435ea7446de420aeac488bf1de35737e8" + }, + "properties": { + "txHash": { + "type": "string", + "description": "Hex string encoding of the hash of the transaction that the bidder wants to include in the block.", + "pattern": "[a-fA-F0-9]{64}" + }, + "nonce": { + "type": "string", + "format": "int64", + "description": "Nonce used for the transaction." + }, + "created": { + "type": "string", + "description": "Time when the transaction was created." + } + }, + "description": "Transaction info returned by the provider.", + "title": "Transaction info", + "required": ["txHash", "nonce", "created"] + } + } + } +} diff --git a/get-started/bidders/bidder-node-commands.mdx b/get-started/bidders/bidder-node-commands.mdx index cf5e0b1c..07f7f777 100644 --- a/get-started/bidders/bidder-node-commands.mdx +++ b/get-started/bidders/bidder-node-commands.mdx @@ -37,8 +37,55 @@ This command will allow you to withdraw funds from the specific [window](/concep Window number is the number where the bidder deposited funds. ```shell ❯_ terminal -cast send 0x7ffa86fF89489Bca72Fec2a978e33f9870B2Bd25 "withdrawBidderAmountFromWindow(address,uint256)" $ADDRESS \ ---rpc-url https://chainrpc.testnet.mev-commit.xyz --private-key $KEY +curl -X POST http://localhost:13523/v1/bidder/withdraw?windowNumber=1 \ +``` + +## Autodeposit Funds + +The auto deposit feature allows you to automate the process of depositing funds for multiple windows ahead. This is useful for ensuring your bidder account always has funds available for future windows. + +Autodeposit will split the initial deposit amount across the specified number of windows. The deposit amount is the total amount to be deposited across all windows. Currently default amount of windows is 3. + +By setting up auto deposit, you can deposit funds for a specific window and automate the process for subsequent windows, reducing the need for manual intervention. + +The withdrawal functionality allows you to withdraw deposited funds from specific windows. This can be useful if you need to reclaim funds that were previously deposited. + +## Start Auto Deposit + +To start the auto deposit process: + +```shell ❯_ terminal +curl -X POST http://localhost:13523/v1/bidder/auto_deposit/{amount} +``` + +## Get Auto Deposit Status + +To get the status of the auto deposit process: + +```shell ❯_ terminal +curl -s http://localhost:13523/v1/bidder/auto_deposit_status +``` + +## Cancel Auto Deposit + +To cancel the auto deposit process: + +```shell ❯_ terminal +curl -X POST http://localhost:13523/v1/bidder/cancel_auto_deposit?withdraw=true +``` + +This will stop the ongoing auto deposit process. + +## Withdraw Funds + +To withdraw funds from the several windows, you can use the following command: + +```shell ❯_ terminal +curl -X POST http://localhost:13523/v1/bidder/withdraw_from_windows + -H "Content-Type: application/json" \ + -d '{ + "windows": [1, 2, 3] + }' ``` ## Checking the Balance of your Wallet diff --git a/mint.json b/mint.json index cfffb8c1..c49feeb8 100644 --- a/mint.json +++ b/mint.json @@ -130,8 +130,20 @@ "pages": [ "api-reference/bidder/sendbid", "api-reference/bidder/getdeposit", - "api-reference/bidder/getmindeposit", - "api-reference/bidder/deposit" + "api-reference/bidder/deposit", + "api-reference/bidder/withdraw", + "api-reference/bidder/withdrawfromwindows", + "api-reference/bidder/autodeposit", + "api-reference/bidder/autodepositstatus", + "api-reference/bidder/cancelautodeposit" + ] + }, + { + "group": "Debug", + "pages": [ + "api-reference/debug/canceltx", + "api-reference/debug/pendingtxs", + "api-reference/debug/topology" ] } ], diff --git a/provider-openapi-spec.json b/provider-openapi-spec.json index b4bb1595..ad353f1b 100644 --- a/provider-openapi-spec.json +++ b/provider-openapi-spec.json @@ -2,7 +2,7 @@ "openapi": "3.0.0", "info": { "title": "Provider API", - "version": "1.0.0-alpha-oas3", + "version": "1.0.0", "license": { "name": "Business Source License 1.1", "url": "https://github.com/primev/mev-commit/blob/main/LICENSE"