Difference between revisions of "PoP Miner API"

From Veriblock Wiki
Jump to: navigation, search
 
(12 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
<translate>
 
<translate>
  
 +
<!--T:5-->
 +
See: [[PoP_Miner_CommandLine]], [[API]]
  
<!--T:1-->
+
<!--T:6-->
== Introduction ==
+
__TOC__
  
 +
== Introduction == <!--T:1-->
 +
 +
<!--T:7-->
 
The VeriBlock PoP Mining software has an embedded HTTP API that makes available some basic functionality for third-party integrations. By default, this HTTP API is bound to 127.0.0.1:8600. Both the host address and port can be configured in the '''ncpop.properties''' file via the properties: ''http.api.address'' and ''http.api.port'', respectively. If running multiple miners on a single machine, each miner will need at least the port configured uniquely or it will be unable to start the embedded HTTP server.
 
The VeriBlock PoP Mining software has an embedded HTTP API that makes available some basic functionality for third-party integrations. By default, this HTTP API is bound to 127.0.0.1:8600. Both the host address and port can be configured in the '''ncpop.properties''' file via the properties: ''http.api.address'' and ''http.api.port'', respectively. If running multiple miners on a single machine, each miner will need at least the port configured uniquely or it will be unable to start the embedded HTTP server.
  
 +
<!--T:8-->
 
Any requests requiring a message body should be formatted as JSON, and conversely all responses will be formatted as JSON as well.
 
Any requests requiring a message body should be formatted as JSON, and conversely all responses will be formatted as JSON as well.
  
  
 +
<!--T:9-->
 
NOTE: This requires 0.3.12-rc.5 of the PoP Miner CLI or higher.
 
NOTE: This requires 0.3.12-rc.5 of the PoP Miner CLI or higher.
  
 +
<!--T:10-->
 
Sample client to call PoP API: https://github.com/VeriBlock/samples/tree/master/pop/pop-api-client/csharp/PoPClient
 
Sample client to call PoP API: https://github.com/VeriBlock/samples/tree/master/pop/pop-api-client/csharp/PoPClient
  
<!--T:2-->
+
=== Setup the API === <!--T:2-->
=== Setup the API ===
 
  
 +
<!--T:11-->
 
# [OPTIONAL] In "ncpop.properties", configure the http.api.address and http.api.port. If not configured, by default these will be 127.0.0.1:8600
 
# [OPTIONAL] In "ncpop.properties", configure the http.api.address and http.api.port. If not configured, by default these will be 127.0.0.1:8600
 
# Start the PoP Miner. See: https://wiki.veriblock.org/index.php?title=HowTo_run_PoP_Miner
 
# Start the PoP Miner. See: https://wiki.veriblock.org/index.php?title=HowTo_run_PoP_Miner
 
# Ensure the PoP Miner is ready to mine. If the PoP Miner cannot run the "mine" command, then the API will not run the "mine" command either.
 
# Ensure the PoP Miner is ready to mine. If the PoP Miner cannot run the "mine" command, then the API will not run the "mine" command either.
  
<!--T:2-->
+
== API Documentation == <!--T:12-->
== API Documentation ==
 
  
<!--T:3-->
+
=== GET /api/config === <!--T:3-->
=== GET /api/config ===
 
  
 +
<!--T:13-->
 
Lists the effective configuration values. Same as running '''listconfig''' from the command-line. The response will be formatted as a JSON object in which each property name represents the configuration name and the property value represents the configuration value.
 
Lists the effective configuration values. Same as running '''listconfig''' from the command-line. The response will be formatted as a JSON object in which each property name represents the configuration name and the property value represents the configuration value.
  
<!--T:4-->
+
==== Response ==== <!--T:4-->
==== Response ====
 
  
  <nowiki>
+
  <!--T:14-->
 +
<nowiki>
 
{
 
{
 
     "auto.mine.round1": "false",
 
     "auto.mine.round1": "false",
Line 55: Line 62:
 
}</nowiki>
 
}</nowiki>
  
=== PUT /api/config ===
+
=== PUT /api/config === <!--T:15-->
  
 +
<!--T:16-->
 
Updates a single configuration value. Same as running '''setconfig''' from the command-line.
 
Updates a single configuration value. Same as running '''setconfig''' from the command-line.
  
==== Request ====
+
==== Request ==== <!--T:17-->
  
 +
<!--T:18-->
 
Request properties:
 
Request properties:
  
 +
<!--T:19-->
 
{| class="wikitable"
 
{| class="wikitable"
 
! style="text-align:left;"| Property
 
! style="text-align:left;"| Property
Line 80: Line 90:
 
|}
 
|}
  
  <nowiki>
+
  <!--T:20-->
 +
<nowiki>
 
{
 
{
 
     "key": "auto.mine.round4",
 
     "key": "auto.mine.round4",
Line 86: Line 97:
 
}</nowiki>
 
}</nowiki>
  
==== Response ====
+
==== Response ==== <!--T:21-->
  
 +
<!--T:22-->
 
A successful request will return a 200 OK status code response with the following body:
 
A successful request will return a 200 OK status code response with the following body:
 
  <nowiki>
 
  <nowiki>
Line 94: Line 106:
 
]</nowiki>
 
]</nowiki>
  
 +
<!--T:23-->
 
An unsuccessful action will return a 500 Server Error status code with some explanation for the failure in the body:
 
An unsuccessful action will return a 500 Server Error status code with some explanation for the failure in the body:
 
  <nowiki>
 
  <nowiki>
Line 104: Line 117:
 
]</nowiki>
 
]</nowiki>
  
=== GET /api/miner ===
+
=== GET /api/miner === <!--T:24-->
  
Lists several miner properties, like the BTC address and ammount, and VBK address.
+
<!--T:25-->
 +
Lists several miner properties, like the BTC address and amount, and VBK address.
  
 +
<!--T:26-->
 
The very first time this is called, if the 'y' acknowledgement hasn't been accepted yet, it will also list the wallet seeds.
 
The very first time this is called, if the 'y' acknowledgement hasn't been accepted yet, it will also list the wallet seeds.
  
 +
<!--T:27-->
 
NOTE: pass in '-skipAck' from the command line on startup to bypass the 'y' acknowledgement and therefore automate a fully new instance
 
NOTE: pass in '-skipAck' from the command line on startup to bypass the 'y' acknowledgement and therefore automate a fully new instance
  
==== Response ====
+
==== Response ==== <!--T:28-->
  
 +
<!--T:29-->
 
<pre>
 
<pre>
 
             {
 
             {
Line 128: Line 145:
 
</pre>
 
</pre>
  
=== GET /api/operations ===
+
=== GET /api/operations === <!--T:30-->
  
 +
<!--T:31-->
 
Lists the current running operations. Same as running '''listoperations''' from the command-line.
 
Lists the current running operations. Same as running '''listoperations''' from the command-line.
  
==== Response ====
+
==== Response ==== <!--T:32-->
  
 +
<!--T:33-->
 
<pre>
 
<pre>
 
[
 
[
Line 153: Line 172:
 
</pre>
 
</pre>
  
=== GET /api/operations/:id ===
+
=== GET /api/operations/:id === <!--T:34-->
  
 +
<!--T:35-->
 
Gets the details of the specified operation. Same as running '''getoperation''' from the command-line. ''':id''' is to be substituted with an actual operation ID, e.g. GET /api/operations/797b3b15
 
Gets the details of the specified operation. Same as running '''getoperation''' from the command-line. ''':id''' is to be substituted with an actual operation ID, e.g. GET /api/operations/797b3b15
  
==== Response ====
+
==== Response ==== <!--T:36-->
  
  <nowiki>{
+
  <!--T:37-->
 +
<nowiki>{
 
     "operationId": "ce3c3e8b",
 
     "operationId": "ce3c3e8b",
 
     "status": "RUNNING",
 
     "status": "RUNNING",
Line 191: Line 212:
 
}</nowiki>
 
}</nowiki>
  
=== POST /api/mine ===
+
=== GET /api/lastbitcoinblock === <!--T:38-->
 +
 
 +
<!--T:39-->
 +
NOTE: Available in latest beta version: [[SegWit_PoP_Miner]]
 +
 
 +
<!--T:40-->
 +
Gets the last known bitcoin block. Same as running '''showlastbitcoinblock''' from the command-line.
 +
 
 +
==== Response ==== <!--T:41-->
 +
 
 +
<!--T:42-->
 +
<nowiki>{
 +
  "header": "0000002005B2B5EF66F47670478DD6462E020E8F9A49BAD1B4C85F6E36C0D675000000007959A7784C5CF4AE38D3EF8ED8E14548FFE3E87A4E39A37AE233001B83B26C854D4E925DFFFF001DA60E33E8",
 +
  "hash": "000000001DD4FAC03E838027EB10FCEB031F14AD0DE943B4F8AB82D0B31F3899",
 +
  "height": 1580114
 +
}
 +
</nowiki>
  
 +
=== POST /api/quit === <!--T:43-->
 +
 +
<!--T:44-->
 +
NOTE: Available in latest beta version: [[SegWit_PoP_Miner]]
 +
 +
<!--T:45-->
 +
Sends a shutdown command to the pop miner. Same as running '''quit''' from the command-line.
 +
 +
<!--T:46-->
 +
Since nodecore-pop-0.4.8-dev.24 it's possible to restart the PoP miner by adding the optional restart parameter: "/api/quit?restart=true"
 +
 +
==== Response ==== <!--T:47-->
 +
 +
<!--T:48-->
 +
<nowiki>{
 +
  "failed": false,
 +
  "messages": []
 +
}
 +
</nowiki>
 +
 +
=== POST /api/mine === <!--T:49-->
 +
 +
<!--T:50-->
 
Begins a new mining operation. Same as running '''mine''' from the command-line.
 
Begins a new mining operation. Same as running '''mine''' from the command-line.
  
==== Request ====
+
==== Request ==== <!--T:51-->
  
 +
<!--T:52-->
 
Request properties:
 
Request properties:
  
 +
<!--T:53-->
 
{| class="wikitable"
 
{| class="wikitable"
 
! style="text-align:left;"| Property
 
! style="text-align:left;"| Property
Line 211: Line 273:
 
|}
 
|}
  
  <nowiki>
+
  <!--T:54-->
 +
<nowiki>
 
{
 
{
 
     "block": 32040
 
     "block": 32040
 
}</nowiki>
 
}</nowiki>
  
 +
<!--T:55-->
 
By not specifying a block number the most recent VeriBlock block will be endorsed. An empty JSON object must be sent in the body:
 
By not specifying a block number the most recent VeriBlock block will be endorsed. An empty JSON object must be sent in the body:
  
  <nowiki>{}</nowiki>
+
  <!--T:56-->
 +
<nowiki>{}</nowiki>
  
==== Response ====
+
==== Response ==== <!--T:57-->
  
 +
<!--T:58-->
 
If the miner is able to successfully begin a new operation a 200 OK response will be return with the following body:
 
If the miner is able to successfully begin a new operation a 200 OK response will be return with the following body:
  
  <nowiki>{
+
  <!--T:59-->
 +
<nowiki>{
 
     "operationId": "c692ed9e",
 
     "operationId": "c692ed9e",
 
     "failed": false,
 
     "failed": false,
Line 239: Line 306:
 
}</nowiki>
 
}</nowiki>
  
 +
<!--T:60-->
 
If the miner is unable to begin a 200 OK response will be returned, but will contain the following body:
 
If the miner is unable to begin a 200 OK response will be returned, but will contain the following body:
  
  <nowiki>{
+
  <!--T:61-->
 +
<nowiki>{
 
     "failed": true,
 
     "failed": true,
 
     "messages": [
 
     "messages": [

Latest revision as of 20:29, 7 February 2022

Other languages:
English


See: PoP_Miner_CommandLine, API

Introduction

The VeriBlock PoP Mining software has an embedded HTTP API that makes available some basic functionality for third-party integrations. By default, this HTTP API is bound to 127.0.0.1:8600. Both the host address and port can be configured in the ncpop.properties file via the properties: http.api.address and http.api.port, respectively. If running multiple miners on a single machine, each miner will need at least the port configured uniquely or it will be unable to start the embedded HTTP server.

Any requests requiring a message body should be formatted as JSON, and conversely all responses will be formatted as JSON as well.


NOTE: This requires 0.3.12-rc.5 of the PoP Miner CLI or higher.

Sample client to call PoP API: https://github.com/VeriBlock/samples/tree/master/pop/pop-api-client/csharp/PoPClient

Setup the API

  1. [OPTIONAL] In "ncpop.properties", configure the http.api.address and http.api.port. If not configured, by default these will be 127.0.0.1:8600
  2. Start the PoP Miner. See: https://wiki.veriblock.org/index.php?title=HowTo_run_PoP_Miner
  3. Ensure the PoP Miner is ready to mine. If the PoP Miner cannot run the "mine" command, then the API will not run the "mine" command either.

API Documentation

GET /api/config

Lists the effective configuration values. Same as running listconfig from the command-line. The response will be formatted as a JSON object in which each property name represents the configuration name and the property value represents the configuration value.

Response

{
    "auto.mine.round1": "false",
    "pop.cron.schedule": "",
    "bitcoin.fee.max": "8000",
    "bitcoin.fee.perkb": "20000",
    "http.api.port": "8600",
    "bitcoin.minrelayfee.enabled": "false",
    "nodecore.rpc.password": "",
    "nodecore.rpc.ssl": "false",
    "nodecore.rpc.cert.chain.path": "",
    "http.api.address": "127.0.0.1",
    "bitcoin.network": "mainnet",
    "nodecore.rpc.host": "127.0.0.1",
    "pop.action.timeout": "90",
    "nodecore.rpc.port": "10501",
    "auto.mine.round4": "false",
    "auto.mine.round3": "false",
    "auto.mine.round2": "false"
}

PUT /api/config

Updates a single configuration value. Same as running setconfig from the command-line.

Request

Request properties:

Property Constraint Data Type Description
key Required String Represents the name of a configuration property to set. Possible values are listed under GET /api/config.
value Required String Represents the value to be set for a given configuration property. The value should be a string but must be convertible to the appropriate type for that configuration property. (E.g. "auto.mine.round1" must have a value of "true" or "false")
{
    "key": "auto.mine.round4",
    "value": "true"
}

Response

A successful request will return a 200 OK status code response with the following body:

[
    {}
]

An unsuccessful action will return a 500 Server Error status code with some explanation for the failure in the body:

[
    {
        "details": [
            "Property 'pop.action.timeout' requires a positive integer value representing the number of seconds to wait before timing out."
        ]
    }
]

GET /api/miner

Lists several miner properties, like the BTC address and amount, and VBK address.

The very first time this is called, if the 'y' acknowledgement hasn't been accepted yet, it will also list the wallet seeds.

NOTE: pass in '-skipAck' from the command line on startup to bypass the 'y' acknowledgement and therefore automate a fully new instance

Response

            {
              "minerAddress": "V9uC3ywS12qW4ESD9783eZXVU3voMo",
              "bitcoinAddress": "1CRb4b5u2AYdaoovgV9aQWV3kSt9x66rJq",
              "bitcoinBalance": 0,
              "walletSeed": [
                "1548958861",
                "cave",
                "conduct",
                "pottery"
              ]
            }

GET /api/operations

Lists the current running operations. Same as running listoperations from the command-line.

Response

[
    {
        "operationId": "ce3c3e8b",
        "endorsedBlockNumber": 22,
        "state": "RUNNING",
        "action": "Waiting for transaction to be included in Bitcoin block",
        "message": ""
    },
    {
        "operationId": "736be6e4",
        "endorsedBlockNumber": 22,
        "state": "RUNNING",
        "action": "Waiting for transaction to be included in Bitcoin block",
        "message": ""
    }
]

GET /api/operations/:id

Gets the details of the specified operation. Same as running getoperation from the command-line. :id is to be substituted with an actual operation ID, e.g. GET /api/operations/797b3b15

Response

{
    "operationId": "ce3c3e8b",
    "status": "RUNNING",
    "currentAction": "WAIT",
    "miningInstruction": {
        "publicationData": [
            ...
        ],
        "endorsedBlockHeader": [
            ...
        ],
        "lastBitcoinBlock": [
            ...
        ],
        "minerAddress": [
            ...
        ],
        "endorsedBlockContextHeaders": [
            [
                ...
            ]
        ]
    },
    "transaction": [
        ...
    ],
    "submittedTransactionId": "2897ba47dfed819879ebe3c5cdbb17e56fcc15d49e3cb42331d2c683b949aeb3",
    "merklePath": "",
    "detail": "",
    "popTransactionId": ""
}

GET /api/lastbitcoinblock

NOTE: Available in latest beta version: SegWit_PoP_Miner

Gets the last known bitcoin block. Same as running showlastbitcoinblock from the command-line.

Response

{
  "header": "0000002005B2B5EF66F47670478DD6462E020E8F9A49BAD1B4C85F6E36C0D675000000007959A7784C5CF4AE38D3EF8ED8E14548FFE3E87A4E39A37AE233001B83B26C854D4E925DFFFF001DA60E33E8",
  "hash": "000000001DD4FAC03E838027EB10FCEB031F14AD0DE943B4F8AB82D0B31F3899",
  "height": 1580114
}

POST /api/quit

NOTE: Available in latest beta version: SegWit_PoP_Miner

Sends a shutdown command to the pop miner. Same as running quit from the command-line.

Since nodecore-pop-0.4.8-dev.24 it's possible to restart the PoP miner by adding the optional restart parameter: "/api/quit?restart=true"

Response

{
  "failed": false,
  "messages": []
}

POST /api/mine

Begins a new mining operation. Same as running mine from the command-line.

Request

Request properties:

Property Constraint Data Type Description
block Optional Integer Represents a specific block number to endorse in this mining operation.
{
    "block": 32040
}

By not specifying a block number the most recent VeriBlock block will be endorsed. An empty JSON object must be sent in the body:

{}

Response

If the miner is able to successfully begin a new operation a 200 OK response will be return with the following body:

{
    "operationId": "c692ed9e",
    "failed": false,
    "messages": [
        {
            "code": "V201",
            "message": "Mining operation started",
            "details": [
                "To view details, run command: getoperation c692ed9e"
            ],
            "error": false
        }
    ]
}

If the miner is unable to begin a 200 OK response will be returned, but will contain the following body:

{
    "failed": true,
    "messages": [
        {
            "code": "V412",
            "message": "Miner is not ready",
            "details": [
                "Waiting for connection to NodeCore",
                "Bitcoin blockchain is not downloaded",
                "Bitcoin service is not ready"
            ],
            "error": true
        }
    ]
}