View source for HowTo run PoP Miner 0.4.9

See: [[Main_Page]], [[PoP_Miner_CommandLine]], [[PoP_Transaction_LifeCycle]], [[PoP_Miner_Rewards]], [[PoP_Reward_Summary]], [[SegWit_PoP_Miner]], [[PoP_Miner_API]]

__TOC__

== Overview ==

The Proof-of-Proof (PoP) consensus protocol enables a security inheriting blockchain (VeriBlock) to inherit the complete proof-of-work of a security providing blockchain (Bitcoin). For a deeper understanding of the PoP consensus protocol, please refer to the [http://bit.ly/vbk-wp-pop PoP Whitepaper].

A PoP miner serves as the communication and transactional bridge between the VeriBlock blockchain and the Bitcoin blockchain. As often as they wish, a PoP miner will take the most recent blockchain state data from the VeriBlock blockchain, along with an identification of the miner for payout purposes, and publish it to the Bitcoin blockchain via a transaction containing an OP_RETURN with the embedded data. The PoP miner then waits for the transaction to be included in a Bitcoin block. When a publication transaction is confirmed, the miner constructs and submits a Proof-of-Proof transaction" that proves inclusion of the publication in the Bitcoin blockchain as well as ownership of the publication for claiming payout.

PoP mining is a competitive endeavor in which miners compete to have their endorsement of the VeriBlock blockchain state included in the earliest possible Bitcoin block.

== Getting Started ==

* Download the latest NodeCore software suite from the [https://github.com/VeriBlock/nodecore-releases/releases VeriBlock Github repository] and extract the contents of the package.
* Follow the instructions at [[NodeCore QuickStart]] to start a local instance of NodeCore.
* From the ''nodecore-pop-{version}/bin'' folder, run the application:
** For Windows:
*** Run '''nodecore-pop.bat'''
** For Linux/MAC:
*** Run '''nodecore-pop'''. ''NOTE: If you are having trouble running nodecore-pop on Linux, you may need to make nodecore-pop executable: '''chmod a+x nodecore-pop'''''
* On first execution of the application, you will be notified that the application creates a lightweight Bitcoin wallet and that you will be shown a set of "seed words" that can be used to recover your wallet later on. Acknowledge this by typing 'y' and pressing ENTER.
* '''Make note of the seed words. You will not be shown them again'''
* Acknowledge again that you have seen the seed words by typing 'y' and pressing ENTER.

The PoP miner acts as an SPV client of the Bitcoin network to maintain the internal wallet. On the first run of the PoP miner, the Bitcoin blockchain will be downloaded (these are just block headers, not full blocks).

[[File:Vpm_chain_download.png | 800px]]

* Once the Bitcoin blockchain download is completed, you are shown a Bitcoin address to send coins to in order to fund the internal wallet
* Fund the internal wallet by sending BTC to the displayed address and wait for that transaction to be confirmed by the Bitcoin network

When the miner is able to communicate with a synchronized NodeCore, has downloaded the Bitcoin blockchain, and is sufficiently funded, you will see a message: '''PoP Miner: READY'''

[[File:Vpm_ready.png | 800px]]

Congratulations! You are ready to start mining!

== Your First PoP Mine ==

The PoP Miner is pre-configured with a default value for the transaction fee to use when creating Bitcoin transactions. It is expressed in satoshis per KB (1000 bytes) and defaults to 20,000. '''It is highly recommended that you assess the current Bitcoin transaction fee market and configure the miner with an appropriately competitive transaction fee.'''

* To configure the transaction fee, run the 'setfeeperkb' command to change it on runtime or ''setconfig vpm.bitcoin.feePerKB'' to change it on the configuration file. e.g. If you determine 30,000 satoshis/KB is a competitive transaction fee you would configure the miner by running: '''setfeeperkb 30000'''
[[File:Vpm_setconfig_bitcoinfeeperkb.png | 800px]]

''Additional insight regarding transaction fees can be found in the FAQ section below, under the question "How do I set the BTC transaction fee?"''

* To begin a mining operation, type 'mine' and press ENTER

[[File:Vpm_mine.png | 800px]]

A mining operation is variable in the amount of time that it takes to reach completion. The first several steps of getting publication data and submitting a Bitcoin transaction happen very quickly (several seconds). You then have a period of waiting while that transaction waits to be confirmed in a Bitcoin block. Assuming your transaction fee is competitive enough to be included in the next block, you are waiting for that next Bitcoin block to be mined (on average, once every 10 minutes, though much longer times are not uncommon). Once the transaction confirms, you'll again have a rapid sequence of steps in which your transaction is proven to exist in the Bitcoin block and the Proof-of-Proof transaction is submitted to the VeriBlock blockchain.

At this point, the miner continues to listen as new Bitcoin blocks arrive and in the event a Bitcoin blockchain reorganization causes your endorsement transaction to be part of a different block, it will resubmit the Proof-of-Proof transaction.

== Interacting with the Command-Line ==

The PoP miner provides several commands for configuring, interacting and assessing the state of your mining operations. A detailed explanation of each command can be found at [[PoP Miner CommandLine]]

== PoP Miner API ==

See [[PoP_Miner_API]]

== PoP Mining Lifecycle ==

Current Actions

Once the PoP Miner is done, there is nothing more for it to do, check [[HowTo_run_PoP_Miner#viewrecentrewards]] to see about rewards.

{| class="wikitable"
! Action
! Duration
! Description
|-
| INITIAL
| -
| Initial state, to be started
|-
| INSTRUCTION
| 1s-1m+
| Mining Instruction retrieved, Endorsement BTC Transaction to be submitted
|-
| ENDORSEMENT_TRANSACTION
| 1s-90m+
| Endorsement BTC Transaction submitted and to be confirmed
|-
| CONFIRMED
| 0s
| Endorsement BTC Transaction confirmed, waiting for Block of Proof
|-
| BLOCK_OF_PROOF
| 0s
| Block of Proof received, waiting for Endorsement Transaction to be proven
|-
| PROVEN
| 0s
| Endorsement BTC Transaction proven, building BTC Context
|-
| CONTEXT
| 0s
| BTC Context determined, waiting for submission response
|-
| SUBMITTED_POP_DATA
| 4h-5h+
| Publications submitted, waiting for payout block
|-
| COMPLETED
| -
| Completed.
|}


You can expect the next log (from start to end):

<pre>
Mining operation 2ec784e6 started
Mining operation started
	To view details, run command: getoperation 2ec784e6
[2ec784e6] Created BTC transaction '8c7c6d78a6afa516aebf07043ad9d0a0f67463054e43cb6fb607832a8ab78f31'. Fee: 5640 Sat (19929 Sat/KB).
[2ec784e6] BTC endorsement transaction has been confirmed!
[2ec784e6] Operation has completed! Payout: 79.61112001 VBK
</pre>

== Major Changes ==

=== v0.4.9 ===

See: [[NodeCore_0.4.9_ReleaseNotes#VeriBlock_PoP_Miner]]

=== v0.3.8 ===

'''IMPORTANT! Bitcoin fee configuration changes from Fee per ''byte'' to Fee per ''kilobyte''.''' The configuration property in the ncpop.properties file has changed from ''bitcoin.fee.perbyte'' to '''bitcoin.fee.perkb'''. The configuration value should be 1000 times the previous per byte fee (Bitcoin 1 KB = 1000 Bytes). 

The rationale for this decision is that if we assume a normal PoP transaction has a size of ~285 bytes, a +1 increase in the fee per byte results in a 285 Satoshi increase in the final fee (+1 satoshi per byte * 285 bytes). Whereas a +1 increase in the fee per kilobyte results in a "0.285 Satoshi" increase in the final fee (+1 satoshi per kb * 0.285 kb). The net effect is a '''much''' finer granularity of control over the final fee.

Additional changes:
* The minimum transaction fee per KB of 1000 Satoshis / KB can be disabled by setting the configuration value '''bitcoin.minrelayfee.enabled=false'''. This should be used with extreme caution as it is possible transactions below this threshold are ignored by the Bitcoin network.
* The "change" address used in a PoP transaction will now be reused. Given the high volume of transactions we've seen from PoP miners, importing wallets was becoming prohibitive due to the large number of items (address keys) present in the filter.

=== v0.3.0 ===

See: [[Mining_High_Noon#PoP_Miner_Update_for_High_Noon]]

Proof-of-Proof transactions now take place on the Bitcoin MainNet and therefore spend BTC from your PoP miner's wallet.

== Reference ==

=== VeriBlock "Rounds" ===

VeriBlock blocks are classified as belonging to one of four rounds. The pattern of rounds repeats every 20 blocks (ending with a block whose number is divisible by 20, e.g. blocks 65461-65480 is a set and 65481-65500 is the next set).  The round classification within each 20 block set is illustrated below:

[[File:rounds.png|1000px]]

Each set of 20 contains just one Round 4 block, the last block, and is known as a "keystone".

=== application.conf Reference ===

These properties can be set in the application.conf file (in bin folder, located next to nodecore-pop.bat). If this file does not exist, it will be created the first time the miner is run.

These can also be seen from running the "listconfig" command.

{| class="wikitable"
! Parent Config
! Config Key
! Default Value
! Comment
|-
| nodeCoreRpc
| host
| 127.0.0.1
| The NodeCore ip where the PoP Miner will connects to
|-
| nodeCoreRpc
| port
| 10501
| The NodeCore port where the PoP Miner will connects to
|-
| nodeCoreRpc
| ssl
| false
| Specify if the connection between the PoP Miner and the NodeCore should use the SSL protocol
|-
| nodeCoreRpc
| password
| 
| The password which will be used to connect to the NodeCore
|-
| bitcoin
| network
| mainnet
| The network type, there are three options: mainnet, testnet and alphanet
|-
| bitcoin
| maxFee
| 8000
| The maximum transaction fee for any given Bitcoin transaction
|-
| bitcoin
| feePerKB
| 20000
| The Bitcoin transaction fee per kilobyte (1000 bytes)
|-
| bitcoin
| enableMinRelayFee
| true
| // description is missing
|-
| bitcoin
| useLocalhostPeer
| false
| Whether or not to connect to a BTC node in localhost if there's any
|-
| bitcoin
| minimalPeerProtocolVersion
| BLOOM_FILTER
| Experimental The minimal protocol version used to accept or reject the peers, the next protocols are available: MINIMUM, PONG, BLOOM_FILTER, BLOOM_FILTER_BIP111, WITNESS_VERSION and CURRENT
|-
| bitcoin
| maxPeerConnections
| 12
| Experimental Adjust the desired number of connections that we will create to peers
|-
| bitcoin
| peerDiscoveryTimeoutMillis
| 5000
| Experimental This is how many milliseconds we wait for peer discoveries to return their results
|-
| bitcoin
| peerDownloadTxDependencyDepth
| 2147483647
| Experimental Configure download of pending transaction dependencies. A change of values only takes effect for newly connected peers
|-
| bitcoin
| requiredPeerServices
| NONE
| Experimental Convenience for connecting only to peers that can serve specific services. It will configure suitable peer discoveries, the next services are available: NODE_NETWORK, NODE_GETUTXOS, NODE_BLOOM, NODE_WITNESS, NODE_NETWORK_LIMITED and NODE_BITCOIN_CASH
|-
| bitcoin
| minPeerBroadcastConnections
| 0
| Experimental The number of connections that are required before transactions will be broadcast
|-
| bitcoin
| maxPeersToDiscoverCount
| 100
| Experimental Sets the maximum number of peers to discover
|-
| bitcoin
| peerPingIntervalMillis
| 2000
| Experimental Sets the period between pings for an individual peer
|-
| automine
| round1
| false
| Automatically mine whenever a new "Round 1" block is seen by NodeCore
|-
| automine
| round2
| false
| Automatically mine whenever a new "Round 2" block is seen by NodeCore
|-
| automine
| round3
| false
| Automatically mine whenever a new "Round 3" block is seen by NodeCore
|-
| automine
| round4
| false
| Automatically mine whenever a new "Round 4" block is seen by NodeCore
|-
| vpm
| httpApiPort
| 8080
| Port the PoP Miner HTTP API will be listening to
|-
| vpm
| cronSchedule
|
| A schedule on which to mine, see below for further information
|}

'''WARNING:''' It is not recommended to configure both the ''pop.cron.schedule'' and the ''auto.mine.roundN'' properties as it can result in too many unconfirmed transactions chained together.

==== PoP Cron Scheduler ====

Cron expressions are a compact format for expressing a recurring schedule. For help constructing an expression, visit an online tool, such as http://www.cronmaker.com/.
An example schedule that would trigger a mine operation at :00 and :30 minutes every hour is below:

<pre>
pop.cron.schedule=0 0/30 * * * ?
</pre>

=== PoP Application Status Codes ===

Status of the PoP Miner

{| class="wikitable"
! Status
! Description
|-
| RUNNING
| The operation is properly running
|-
| COMPLETE
| The operation has been completed
|-
| FAILED
| The operation has failed
|}

=== PoP Files ===

{| class="wikitable"
! Folder
! File
! Description
|-
| logs
| bitcoinj.nodecore-pop.log
| Log file for BitcoinJ library
|-
| logs
| veriblock.nodecore-pop.log
| Log file for the PoP Miner. It contains any log generated by the miner.
|-
| logs
| veriblock.nodecore-pop-error.log
| Log file for the PoP Miner. It contains only the errors generated by the miner.
|-
| bin
| bitcoin-pop-testnet.spvchain
| Contains the bitcoin block chain headers
|-
| bin
| bitcoin-pop-testnet.wallet
| Bitcoin wallet, this contains your BTC
|-
| bin
| application.conf
| The PoP miner configuration file
|-
| bin
| nodecore-pop.sh
| The script to start the PoP Miner on linux
|-
| bin
| nodecore-pop.bat
| The script to start the PoP Miner on windows
|-
|}

== FAQ ==

=== Does the PoP Miner require BTC or tBTC? ===

For PoP Mining on the VeriBlock Mainnet, BTC is required.

Previously the TestNet PoP Miner required tBTC (testnet BTC) during the "Mining Sunrise" phase.

After VBK MainNet launch, the VBK TestNet PoP Miner uses BTC TestNet (tBTC), and the VBK MainNet PoP Miner uses BTC.

=== How can I see my PoP rewards? ===

See: [[PoP_Miner_Rewards]]

=== Do I need to run a full Bitcoin node? ===
No. The PoP Miner uses the [https://bitcoinj.github.io/ bitcoinj] library to embed a lightweight Bitcoin wallet (and SPV client), such that one does NOT need to run a full Bitcoin node.

=== Does the Bitcoin I send to my PoP Wallet need to be confirmed? ===
Yes. When funding your PoP wallet with "outside" funds, the transaction will need to confirm.

During the course of normal PoP mining, the transactions created by the embedded wallet are considered trusted and therefore the wallet is allowed to create subsequent transactions that spend the pending UTXO. This can also be used by sophisticated PoP miners to upgrade the effective transaction fee of previous unconfirmed transactions by sending new transactions building on the unconfirmed transaction(s) with high fees, resulting in a Child-Pays-For-Parent (CPFP) fee upgrade.

=== How do I set the BTC transaction fee? ===

For "what should the BTC fee be", check: [[PoP_Miner_Rewards#What_should_the_tBTC_Tx_fee_be.3F]]. This section explains how to set the fee.

Either set it in the application.conf file:

<pre>
bitcoin {
    maxFee = 8000
    feePerKB = 20000
}
</pre>

Or set it with the commands:
* For runntime change:
<pre>
 setmaxfee 20000
 setfeeperkb 8000
</pre>
* For file change (restart is required):
<pre>
 setconfig vpm.bitcoin.maxFee 20000
 setconfig vpm.bitcoin.feePerKB 8000
</pre>

Note: Make sure to also set 'maxFee'. This is the absolute maximum you're willing to allow the final transaction fee to be. An average transaction may be around 300 bytes (or, 0.3 KB), so, generally the configured maximum should be at least (0.3 KB x ''feePerKB'').

You can see the current fee by running the 'listconfig' command ([[HowTo_run_PoP_Miner#listconfig]])

=== How to set up a cron schedule for mining ===

Properties file is:

<pre>
pop.cron.schedule=0 0/30 * * * ?
</pre>

Checkout http://www.cronmaker.com/ for help building the expression

=== How to auto-mine every Nth round? ===

The PoP Miner can mine every Nth round. See: [[HowTo_run_PoP_Miner#VeriBlock_.22Rounds.22]]

Within a 20 block window:

* round4 = every 20th block, i.e. keystone (highest reward)
* round1 = 1,4,7,10,13,16,19
* round2 = 2,5,8,11,14,17
* round3 = 3,6,9,12,15,18

Set the application.conf file:

<pre>
autoMine {
    round1 = false
    round2 = false
    round3 = false
    round4 = true
  }
</pre>

Note if you wanted different fees for different rounds, you could have multiple miners run. Miner A could run rounds 1-3 at Fee X, Miner B could run round 4 at fee Y.

Note, it is advised to not use this and the cron expression - pick one or the other.

=== Can I run multiple PoP Miners? ===

Yes. Each instance of the miner will require its own unique wallet file ''(bitcoin-pop.wallet)''. Do not clone wallet files between instances.

The best way to accomplish this is to make copies of the nodecore-pop folder before launching the miner, so that as each new instance is started, it will create a unique wallet file and download the appropriate SPV chain data. As there is an initial download of Bitcoin blocks, it is also recommended to spin up each new instance of the miner only after the previous completes its download.

* Option A: Run multiple instances of a PoP Miner on a single machine.  You will need to clone the ''nodecore-pop'' folder on the machine and use different wallets. '''Do not run the multiple instances of the same executable with the same wallet'''. Each copy will have it's own set of files: [[HowTo_run_PoP_Miner#PoP_Files]]
* Option B: Run instances on multiple different machines, all pointed to the same remote NodeCore instance by setting the application.conf 'host=<remote_IP_Here>' (inside the nodeCoreRpc config block) (also see [[https://wiki.veriblock.org/index.php?title=NodeCore_Networking]] to set up NodeCore to accept connections from the remote PoP miner)

=== Can I import a previous BTC wallet? ===

Yes, just copy bin\bitcoin-pop-*.wallet.

This will carry over the BTC balance.

== Troubleshooting ==

=== PoP Miner takes a very long time to sync Bitcoin network ===

If you notice that your PoP miner is taking a long time to download Bitcoin blocks, or fails to completely sync, you can remove the wallet and nodecore-pop.dat files and start a 'fresh' PoP miner.  Note, in doing this, you will lose any funds or transactions that are current pending, so it is best to routinely withdraw your balance and start fresh wallets if you plan to mine continuously for long periods of time.  The frequency of which you will want to create new wallets will depend entirely on the number of transactions that you submit.

=== "PoP Miner not ready" warning ===

{| class="wikitable"
! Warning
! Solution
|-
| PoP wallet does not contain sufficient funds
| Send Bitcoins to your PoP BTC wallet address. Run commands showbitcoinbalance (it should be greater than zero), and sendbitcointoaddress.
|-
| Waiting for connection to NodeCore
| Ensure an instance of NodeCore is running, and you could connect to it from the NC_CLI and run getinfo
|-
| Waiting for NodeCore to synchronize
| The connected NodeCore is not yet fully synchronized
|--
| Bitcoin blockchain is not downloaded
| Ensure the application.conf file has the a network configured (testnet or mainnet) inside the bitcoin configuration block, and wait for the blockchain to download. There should be a message like "Blockchain downloading: 95%".
|-
| Bitcoin service is not ready
| Check the other warnings. There should be a message like "SUCCESS: Bitcoin service is ready".
|}

=== I do not have any bitcoin ===

For mainnet, acquire Bitcoin via normal means.

For testnet, use a faucet to get test bitcoin. You can find a list of popular Bitcoin testnet faucets here: https://en.bitcoin.it/wiki/Testnet#Faucets.

=== Mining operation action took longer than expected. Operation can be resubmitted. ===

If you get an error, then try running the resubmit command: [[PoP_Miner_CommandLine#resubmit]]

<pre>
ERROR: Mining operation action took longer than expected. Operation can be resubmitted.
</pre>

PoP Transaction must complete within a certain period of time to remain relevant, and hence it times out. For example, if there's an abnormally high amount of context headers, that may cause a timeout.

===Why does the BTC address change each time I run the showAddress command?===

Bitcoin addresses are just a representation of the public key from a public/private key pair. We generate new key pairs every time you run the `showAddress` command. The PoP Miner manages these addresses for you, so you don't have to worry about them. As a privacy best practice, it's best to always use a new address (key pair) every time you receive a payment. The reason the PoP miner (or any Bitcoin wallet) generates a new address each time you receive a payment is for privacy reasons only, because if you use the same address for many transactions, the peers you traded with will be able to identify which other transactions you were involved in, and your identity will be easier to tie to the address. [Credit: A sentence or two for this answer may come from an unknown tech source]


=== Failed to get PoP publication data from NodeCore ===

This kind of error implies that NodeCore is not ready. 

Try to connect to the NC instance with the NC_CLI and run getinfo:

<pre>
Failed to get PoP publication data from NodeCore: Status{code=DEADLINE_EXCEEDED, description=deadline exceeded after 14999412514ns, cause=null}
</pre>

Can you run NC_CLI getinfo?

* Yes --> Then try to repeat the PoP miner operation.
* No --> Troubleshoot NodeCore [[HowTo_run_NodeCore]]

== Command Line Reference ==
See: [[PoP_Miner_CommandLine]]