Difference between revisions of "HowTo Setup vBFI"

From Veriblock Wiki
Jump to: navigation, search
 
(24 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
See: [[Main_Page]]
 
See: [[Main_Page]]
 +
 +
This is for VeriBlock NodeCore.
  
 
__TOC__
 
__TOC__
  
== Background ==
+
== Overview ==
 +
 
 +
vBFI provides the equivalent number of Bitcoin confirmations that a VeriBlock block (and the transactions it contains) has.
 +
 
 +
Third parties require specific numbers of confirmations to confirm a transaction (for example, an exchange accepting incoming deposits). In general, a higher number of confirmations corresponds to more security, with the trade-off of longer waiting period.
  
vBFI provides the equivalent number of bitcoin confirmations that a VeriBlock block has.
+
vBFI provides the best of both worlds:
 +
# Much more security: Bitcoin level security (which depending on the chain can be 100x+ the security that would normally be available after 2 hours).
 +
# Less wait time: About 2 hours under normal network conditions.  
  
 +
Useful links:
  
 +
* https://veriblock.org/vbfi - official home page
 +
* https://vbfi.veriblock.org/ - live UI control for vBFI (this link may change, and will be integrated into the explorer)
 +
* [[How_VeriBlock_PoP_vBFI_Protects_Altchains]]
  
 
== How to set up ==
 
== How to set up ==
 
vBFI is contained within NodeCore. It is an optional plugin, not run by default (to conserve resources).
 
vBFI is contained within NodeCore. It is an optional plugin, not run by default (to conserve resources).
  
It is available with 0.4.13-rc8 and later (TODO - this is a pre-release)
+
It is available with 0.4.13-rc8 and later (TODO - this is a pre-release). Requires both NodeCore and NodeCore CLI to be 0.4.13-rc8+ (older versions of NC_CLI may not return the new fields)
  
# Run a full nodecore instance: [[NodeCore_QuickStart]]
+
# Run a full NodeCore instance: [[NodeCore_QuickStart]]
# Open up port 4567 for bfi
 
 
# Add file bfi.conf
 
# Add file bfi.conf
 
# In nodecore.properties, set bfi.enabled=true
 
# In nodecore.properties, set bfi.enabled=true
Line 22: Line 33:
  
 
'''bfi.conf'''
 
'''bfi.conf'''
 +
 +
Put this next to 'nodecore.properties' file:
  
 
<pre>
 
<pre>
Line 45: Line 58:
 
=== bitcoinConfirmations for each transaction ===
 
=== bitcoinConfirmations for each transaction ===
  
This is available per transaction via the bitcoinConfirmations field:
+
This is available per transaction via the bitcoinConfirmations field.
  
 +
Below is a sample transaction that is a few hours old. Note that a very recent transaction (such as 5 minutes old) will still show bitcoinConfirmations: -11, as Bitcoin Finality has not been achieved yet.
 +
 +
==== NC_CLI ====
 +
 +
From NC_CLI (see: [[NodeCore_CommandLine]] ))
 
<pre>
 
<pre>
gettransactions 2AB3811FD0EDE3B3F89A50926B15AA4C0C2370A4467E6670635A19E5A1CD3AF3 5000
+
gettransaction 2AB3811FD0EDE3B3F89A50926B15AA4C0C2370A4467E6670635A19E5A1CD3AF3 5000
  
 
...
 
...
Line 55: Line 73:
 
</pre>
 
</pre>
  
[[File:Gettx.png|600px]]
+
==== API ====
  
==== JavaScript sample to call API ====
+
There is also a JavaScript sample to call the HTTP API for gettransactions:  
There is also a JavaScript sample to call the http api for gettransactions:  
 
  
 
https://github.com/VeriBlock/nodecore-js/blob/master/packages/core/example/3_get_bfi_score.js
 
https://github.com/VeriBlock/nodecore-js/blob/master/packages/core/example/3_get_bfi_score.js
 +
 +
==== Explorer ====
 +
 +
The VeriBlock explorer shows vBFI confirmations on both the block and the transaction. (the transaction will have the same vBFI confirmations as its containing block).
 +
 +
[[File:Vbfi_explorer_tx.png|800px]]
  
 
=== API results ===
 
=== API results ===
Line 73: Line 96:
 
<instance>/api/chains
 
<instance>/api/chains
 
</pre>
 
</pre>
 +
 +
== End-to-end example ==
 +
 +
If a transaction occurs in block 2713020, and the UI control shows that has "BTC+3", that is equivalent to "3 Bitcoin confirmations," meaning if an attacker wanted to reverse that transaction would have to perform a 3-block reorganization on Bitcoin (in addition to simultaneously reorging approximately 250-300 VBK blocks). In other words, the transaction has the same (technically, higher) security as a transaction on Bitcoin itself with 3 confirmations.
 +
 +
For example, if a service required "3 Bitcoin confirmations" worth of security to deposit Bitcoin, then that service would want "BTC+3".
 +
 +
[[File:Vbfi_ui_control.png|1200px]]
 +
 +
When checking the specific transaction, it would also show "BTC+3".
 +
 +
[[File:Gettx.png|600px]]
 +
 +
== Is my transaction bitcoin-secure? ==
 +
 +
In its simplest form, vBFI functions almost like a stoplight.
 +
 +
* Green = Proceed. There is bitcoin-level security
 +
* Yellow = Wait, there is not yet bitcoin-level security.
 +
* Red = Wait, there is a fork in-progress, and therefore not yet bitcoin-level security.
 +
 +
[[File:Vbfi_explorer_green2.png|800px]]
 +
 +
[[File:Vbfi_explorer_yellow2.png|800px]]
 +
 +
[[File:Vbfi_explorer_red2.png|800px]]
  
 
== Docker setup ==
 
== Docker setup ==
  
 
<pre>
 
<pre>
 
 
version: '3'
 
version: '3'
 
services:
 
services:
Line 98: Line 146:
 
       - NODECORE_LOG_PATH=/data/logs/
 
       - NODECORE_LOG_PATH=/data/logs/
 
       - NODECORE_LOG_LEVEL=INFO
 
       - NODECORE_LOG_LEVEL=INFO
 
 
</pre>
 
</pre>
  
 
^ In the above case configuration needs to be placed in /root/VeriBlock
 
^ In the above case configuration needs to be placed in /root/VeriBlock
  
== Useful links ==
+
== FAQ ==
 +
 
 +
=== How Long Does Bitcoin Finality Take for VeriBlock with vBFI? ===
 +
It depends; unusually fast or slow BTC and VBK blocks can both contribute to faster or slower than normal confirmation, and in the event of an active attack on the VeriBlock network, Bitcoin Finality will be delayed until the attack stops (or falls far enough behind the main VeriBlock chain that it's publications to Bitcoin could never create a fork which the VeriBlock fork resolution protocol would accept). Under normal network conditions it generally takes 1.5 to 2.5 hours. This is based on VeriBlock's 11 Bitcoin block finality delay; all transactions in blocks at or before a keystone which is published to Bitcoin will receive Bitcoin Finality after 11 additional Bitcoin blocks in the absence of an attack.
 +
 
 +
=== Why is VeriBlock's Bitcoin Finality with vBFI 1.5-2.5 Hours, Instead of Just 10 Minutes Behind Bitcoin? ===
 +
For security reasons, VeriBlock's fork resolution protocol has a number of settlement Bitcoin blocks which vBFI must wait for, so vBFI takes longer than simply the inclusion of a PoP publication in Bitcoin.
 +
 
 +
vBFI depends on the possibility of causing a VeriBlock reorg without having to cause a Bitcoin reorg. Once a Bitcoin reorg (of 1 block or greater) is mathematically required to create a VeriBlock fork at a particular height, Bitcoin Finality is achieved for that VeriBlock keystone and all previous blocks on the VeriBlock network.
 +
 
 +
Most of the long delay is due to protecting against edge-cases which could cause security issues, ex an attacker controlling 20x or 100x the current VeriBlock hashrate; the ~2 hour delay time (or more pedantically, the 11-block Bitcoin delay) gives a margin of error above the amount of time VeriBlock's modified LWMA difficulty adjustment algorithm takes to fully adjust to major influxes of network hashrate. The extra margin of error compensates for abnormal good/bad (either could favor the attacker in different scenarios) behavior. Having the finality delay much shorter (ex: 3 BTC blocks ~= 30 min) would mean an attacker could create a permanently-better chain that they could withhold and perform long-range organizations.
 +
 
 +
=== Is vBFI a Gradient? If 2 Hours is Full-Bitcoin Security, is 1 Hour Half-Bitcoin Security? ===
 +
No.
 +
There are two security measurements:
 +
 
 +
(1) VeriBlock hashing power: This is a gradient, and in normal network conditions it greatly increases with each block. An attacker starting an attack several Bitcoin blocks after the first Bitcoin publication of the first keystone block they are trying to reorganize will have to use increasing quantities of VeriBlock hashrate to build a viable fork in order to catch up with the regular network.
 +
 
 +
(2) Bitcoin hashing power: This is what really matters, and it is binary. If vBFI <= 0, then an attacker with sufficient hashrate (which may be 10x or more of VeriBlock's legitimate hashrate) will be able to create a VeriBlock reorganization without having to cause a Bitcoin reorganization. If vBFI > 0, then an attacker will have to simultaneously attack the VeriBlock blockchain with significantly more than the legitimate hashrate and reorganize Bitcoin's blockchain as well. As a result, vBFI is effectively binary; vBFI <= 0 means the attacker does not have to attack Bitcoin, vBFI > 0 means the attacker does have to attack Bitcoin to produce a reorg on VeriBlock.
 +
 
 +
Once vBFI indicates Bitcoin-level security, each additional Bitcoin block behaves like a Bitcoin confirmation; the attacker would have to reorganize more Bitcoin blocks to have the opportunity to reorg the VeriBlock blockchain at or below that particular height.
 +
 
 +
If a 3rd party wanted "2 bitcoin confirmations", then they would wait for vBFI = 2, which could be about 2-2.5 hours under normal network conditions.
 +
 
 +
vBFI doesn't work in terms of "percentages" of protection in the sense that -3 would equate to 50% of Bitcoin or something, but negative vBFI values could be used dynamically based on a risk assessment of someone doing a 200%, 500%, 10000%, etc. attack on VeriBlock. As an approximate example, at -3 vBFI the attacker would have to produce VBK blocks far faster than the regular network, but a long-term attack could do this more slowly than a short-term attack, which would require a lower peak hashing power committed for a longer duration. It's important to note that the security of negative vBFI values has nothing to do with (partial) Bitcoin-level security because an attack could be done purely by consuming a large amount of computing power to attack VeriBlock itself, leaving Bitcoin alone.
  
* https://veriblock.org/vbfi - official home page
+
vBFI is binary; either you don't yet have BTC finality (-1 or lower) and an attacker with sufficient VBK hashrate could perform a 51% attack (although the closer to 0 the value gets, the more hashpower the attacker needs), and vBFI +1 or higher does require a BTC reorg in order to perform a double-spend.
* https://vbfi.veriblock.org/ - live UI control for vBFI (this link may change, and will be integrated into the explorer)
+
 
* [[How_VeriBlock_PoP_vBFI_Protects_Altchains]] - explanation
+
=== How Long Does Altchain vBFI Take? ===
 +
In general, Altchain vBFI is about 1 hour behind VeriBlock vBFI. It requires first VeriBlock vBFI to be finalized, and then the altchain to reach finalization based on publications finalized by vBFI. In other terms, the altchain must be finalized based on VeriBlock (so a VeriBlock reorg would be required to reorg the altchain), and the VeriBlock blocks that provide finalization to the altchain must be finalized to Bitcoin, so the end result would be a Bitcoin reorg would be required to perform the VeriBlock reorg required to perform an altchain reorg. As a result, Altchain vBFI could be 2.5-3.5 hours under normal network conditions.
 +
 
 +
While this is still faster than most 3rd party deposits, Altchain vBFI is more about providing Bitcoin-level security than fast confirmation times. Additionally, the confirmation times that many services currently use for many blockchains is far below what is truly sufficient for security; for example many exchanges allow $1M (or $10M, etc.) deposits to be confirmed on blockchains in 2 hours, despite a 2-hour reorg on the blockchain costing far less than $1M and thus being economically feasible.

Latest revision as of 13:20, 12 May 2022

See: Main_Page

This is for VeriBlock NodeCore.

Overview

vBFI provides the equivalent number of Bitcoin confirmations that a VeriBlock block (and the transactions it contains) has.

Third parties require specific numbers of confirmations to confirm a transaction (for example, an exchange accepting incoming deposits). In general, a higher number of confirmations corresponds to more security, with the trade-off of longer waiting period.

vBFI provides the best of both worlds:

  1. Much more security: Bitcoin level security (which depending on the chain can be 100x+ the security that would normally be available after 2 hours).
  2. Less wait time: About 2 hours under normal network conditions.

Useful links:

How to set up

vBFI is contained within NodeCore. It is an optional plugin, not run by default (to conserve resources).

It is available with 0.4.13-rc8 and later (TODO - this is a pre-release). Requires both NodeCore and NodeCore CLI to be 0.4.13-rc8+ (older versions of NC_CLI may not return the new fields)

  1. Run a full NodeCore instance: NodeCore_QuickStart
  2. Add file bfi.conf
  3. In nodecore.properties, set bfi.enabled=true

If you run getdiagnosticinfo, you will see this flag enabled.

bfi.conf

Put this next to 'nodecore.properties' file:

bfi {
    blockChainNetwork = mainnet
    nodeCoreRpcHost = "127.0.0.1:10500"
    httpApiBindPort = 4567
    httpApiNotificationsTest = true
    forkThreatThreshold = 2
    forkThreatRatioThreshold = 0.8
}

nodecore.properties

# Enable BFI
bfi.enabled=true

Get results

bitcoinConfirmations for each transaction

This is available per transaction via the bitcoinConfirmations field.

Below is a sample transaction that is a few hours old. Note that a very recent transaction (such as 5 minutes old) will still show bitcoinConfirmations: -11, as Bitcoin Finality has not been achieved yet.

NC_CLI

From NC_CLI (see: NodeCore_CommandLine ))

gettransaction 2AB3811FD0EDE3B3F89A50926B15AA4C0C2370A4467E6670635A19E5A1CD3AF3 5000

...
"bitcoinConfirmations": 4,
...

API

There is also a JavaScript sample to call the HTTP API for gettransactions:

https://github.com/VeriBlock/nodecore-js/blob/master/packages/core/example/3_get_bfi_score.js

Explorer

The VeriBlock explorer shows vBFI confirmations on both the block and the transaction. (the transaction will have the same vBFI confirmations as its containing block).

Vbfi explorer tx.png

API results

Two supported APIs are:

#Summary ping that 
<instance>/api/ping

#detailed chain data
<instance>/api/chains

End-to-end example

If a transaction occurs in block 2713020, and the UI control shows that has "BTC+3", that is equivalent to "3 Bitcoin confirmations," meaning if an attacker wanted to reverse that transaction would have to perform a 3-block reorganization on Bitcoin (in addition to simultaneously reorging approximately 250-300 VBK blocks). In other words, the transaction has the same (technically, higher) security as a transaction on Bitcoin itself with 3 confirmations.

For example, if a service required "3 Bitcoin confirmations" worth of security to deposit Bitcoin, then that service would want "BTC+3".

Vbfi ui control.png

When checking the specific transaction, it would also show "BTC+3".

Gettx.png

Is my transaction bitcoin-secure?

In its simplest form, vBFI functions almost like a stoplight.

  • Green = Proceed. There is bitcoin-level security
  • Yellow = Wait, there is not yet bitcoin-level security.
  • Red = Wait, there is a fork in-progress, and therefore not yet bitcoin-level security.

Vbfi explorer green2.png

Vbfi explorer yellow2.png

Vbfi explorer red2.png

Docker setup

version: '3'
services:
  nodecore:
    container_name: nodecore
    image: docker-internal.veriblock.com/nodecore:0.4.13-rc.8
    expose:
      - 7500 # p2p
      - 10500 # rpc
      - 10600 # api
      - 4567 # bfi
    ports:
      - "7501:7501"
      - "10500:10500"
      - "127.0.0.1:10600:10600"
      - "127.0.0.1:4567:4567"
    volumes:
      - /root/VeriBlock:/data:Z
    environment:
      - NODECORE_LOG_PATH=/data/logs/
      - NODECORE_LOG_LEVEL=INFO

^ In the above case configuration needs to be placed in /root/VeriBlock

FAQ

How Long Does Bitcoin Finality Take for VeriBlock with vBFI?

It depends; unusually fast or slow BTC and VBK blocks can both contribute to faster or slower than normal confirmation, and in the event of an active attack on the VeriBlock network, Bitcoin Finality will be delayed until the attack stops (or falls far enough behind the main VeriBlock chain that it's publications to Bitcoin could never create a fork which the VeriBlock fork resolution protocol would accept). Under normal network conditions it generally takes 1.5 to 2.5 hours. This is based on VeriBlock's 11 Bitcoin block finality delay; all transactions in blocks at or before a keystone which is published to Bitcoin will receive Bitcoin Finality after 11 additional Bitcoin blocks in the absence of an attack.

Why is VeriBlock's Bitcoin Finality with vBFI 1.5-2.5 Hours, Instead of Just 10 Minutes Behind Bitcoin?

For security reasons, VeriBlock's fork resolution protocol has a number of settlement Bitcoin blocks which vBFI must wait for, so vBFI takes longer than simply the inclusion of a PoP publication in Bitcoin.

vBFI depends on the possibility of causing a VeriBlock reorg without having to cause a Bitcoin reorg. Once a Bitcoin reorg (of 1 block or greater) is mathematically required to create a VeriBlock fork at a particular height, Bitcoin Finality is achieved for that VeriBlock keystone and all previous blocks on the VeriBlock network.

Most of the long delay is due to protecting against edge-cases which could cause security issues, ex an attacker controlling 20x or 100x the current VeriBlock hashrate; the ~2 hour delay time (or more pedantically, the 11-block Bitcoin delay) gives a margin of error above the amount of time VeriBlock's modified LWMA difficulty adjustment algorithm takes to fully adjust to major influxes of network hashrate. The extra margin of error compensates for abnormal good/bad (either could favor the attacker in different scenarios) behavior. Having the finality delay much shorter (ex: 3 BTC blocks ~= 30 min) would mean an attacker could create a permanently-better chain that they could withhold and perform long-range organizations.

Is vBFI a Gradient? If 2 Hours is Full-Bitcoin Security, is 1 Hour Half-Bitcoin Security?

No. There are two security measurements:

(1) VeriBlock hashing power: This is a gradient, and in normal network conditions it greatly increases with each block. An attacker starting an attack several Bitcoin blocks after the first Bitcoin publication of the first keystone block they are trying to reorganize will have to use increasing quantities of VeriBlock hashrate to build a viable fork in order to catch up with the regular network.

(2) Bitcoin hashing power: This is what really matters, and it is binary. If vBFI <= 0, then an attacker with sufficient hashrate (which may be 10x or more of VeriBlock's legitimate hashrate) will be able to create a VeriBlock reorganization without having to cause a Bitcoin reorganization. If vBFI > 0, then an attacker will have to simultaneously attack the VeriBlock blockchain with significantly more than the legitimate hashrate and reorganize Bitcoin's blockchain as well. As a result, vBFI is effectively binary; vBFI <= 0 means the attacker does not have to attack Bitcoin, vBFI > 0 means the attacker does have to attack Bitcoin to produce a reorg on VeriBlock.

Once vBFI indicates Bitcoin-level security, each additional Bitcoin block behaves like a Bitcoin confirmation; the attacker would have to reorganize more Bitcoin blocks to have the opportunity to reorg the VeriBlock blockchain at or below that particular height.

If a 3rd party wanted "2 bitcoin confirmations", then they would wait for vBFI = 2, which could be about 2-2.5 hours under normal network conditions.

vBFI doesn't work in terms of "percentages" of protection in the sense that -3 would equate to 50% of Bitcoin or something, but negative vBFI values could be used dynamically based on a risk assessment of someone doing a 200%, 500%, 10000%, etc. attack on VeriBlock. As an approximate example, at -3 vBFI the attacker would have to produce VBK blocks far faster than the regular network, but a long-term attack could do this more slowly than a short-term attack, which would require a lower peak hashing power committed for a longer duration. It's important to note that the security of negative vBFI values has nothing to do with (partial) Bitcoin-level security because an attack could be done purely by consuming a large amount of computing power to attack VeriBlock itself, leaving Bitcoin alone.

vBFI is binary; either you don't yet have BTC finality (-1 or lower) and an attacker with sufficient VBK hashrate could perform a 51% attack (although the closer to 0 the value gets, the more hashpower the attacker needs), and vBFI +1 or higher does require a BTC reorg in order to perform a double-spend.

How Long Does Altchain vBFI Take?

In general, Altchain vBFI is about 1 hour behind VeriBlock vBFI. It requires first VeriBlock vBFI to be finalized, and then the altchain to reach finalization based on publications finalized by vBFI. In other terms, the altchain must be finalized based on VeriBlock (so a VeriBlock reorg would be required to reorg the altchain), and the VeriBlock blocks that provide finalization to the altchain must be finalized to Bitcoin, so the end result would be a Bitcoin reorg would be required to perform the VeriBlock reorg required to perform an altchain reorg. As a result, Altchain vBFI could be 2.5-3.5 hours under normal network conditions.

While this is still faster than most 3rd party deposits, Altchain vBFI is more about providing Bitcoin-level security than fast confirmation times. Additionally, the confirmation times that many services currently use for many blockchains is far below what is truly sufficient for security; for example many exchanges allow $1M (or $10M, etc.) deposits to be confirmed on blockchains in 2 hours, despite a 2-hour reorg on the blockchain costing far less than $1M and thus being economically feasible.