Difference between revisions of "PoP Miner API"

From Veriblock Wiki
Jump to: navigation, search
(One intermediate revision by one other user not shown)
Line 1: Line 1:
 +
<languages/>
 +
 +
<translate>
 +
 +
 +
<!--T:1-->
 
== Introduction ==
 
== Introduction ==
  
Line 10: Line 16:
 
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 ===
 
=== Setup the API ===
  
Line 17: Line 23:
 
# 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 ==
 
== API Documentation ==
  
 +
<!--T:3-->
 
=== GET /api/config ===
 
=== 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.
 
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 ====
 
==== Response ====
  
Line 97: Line 106:
 
=== GET /api/miner ===
 
=== GET /api/miner ===
  
Lists several miner properties, like the BTC address and ammount, and VBK address.
+
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.
 
The very first time this is called, if the 'y' acknowledgement hasn't been accepted yet, it will also list the wallet seeds.
Line 247: Line 256:
 
     ]
 
     ]
 
}</nowiki>
 
}</nowiki>
 +
 +
</translate>

Revision as of 08:08, 29 July 2019

Other languages:
English


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": ""
}

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
        }
    ]
}