Blockcore

Every Pull Request (PR) must be associated with a PR review policy tag. These tags determine the level of scrutiny and the specific requirements for testing and verification required before a change can be merged. The policy levels are:

• pr-review-critical: Highest level of scrutiny. Requires review by at least two core devs, all tests (Unit and Integration) passing for both author and reviewers, and synchronization of all 4 chains (Bitcoin main/test, Stratis main/test) to an agreed height.
• pr-review-high: Requires review by at least two core devs, all tests (Unit and Integration) passing for both author and reviewers, and synchronization of all 4 chains (Bitcoin main/test, Stratis main/test) to an agreed height.
• pr-review-medium: Requires review by at least two core devs (author and reviewer) and all tests (Unit and Integration) passing.
• pr-review-low: Requires review by at least one core dev and all tests (Unit and Integration) passing.

TRACE level logs should be used to record execution flow so that the exact path of object instances can be inspected.

Best Practices:

• Distinguishable Branches: Ensure every important execution path branch is distinguishable. You can achieve this by placing a log in one branch, or in both if necessary. If a branch is rarely executed (the 'abnormal' case), logging only in that branch is sufficient to inform the reader that the 'normal' path was taken.
• Coverage: Logs should provide enough information to reconstruct the state transitions. For example, in a loop, log the state at each iteration rather than just the final exit state to capture the number of operations performed.

while (true)
{
    uint256 hash = await this.UTXOSet.Rewind();
    ChainedBlock rewinded = this.Chain.GetBlock(hash);
    if (rewinded == null)
    {
        // Log the specific branch to distinguish it from the successful path
        this.logger.LogTrace("Rewound to '{0}', which is still not a part of the current best chain, rewinding further.", hash);
        continue;
    }

    // Log the successful path
    this.logger.LogTrace("Rewound to '{0}'.", hash);
    this.Tip = rewinded;
    this.Puller.SetLocation(rewinded);
    break;
}

The Blockcore Proof of Stake (PoS) protocol faces several theoretical and practical security challenges that developers and operators should be aware of:

Nothing-at-Stake (NAS)

Validators may have a financial incentive to mine on every fork of the blockchain. This can disrupt consensus and make it difficult for honest nodes to identify the chain with the majority of honest staking power, potentially confusing nodes during Initial Block Download (IBD).

Stake Grinding

A validator attempts to bias randomness in their favor by modifying block headers. An attacker with a small amount of stake can scan blockchain history to find opportunities to win blocks and then manipulate subsequent headers to consecutively win blocks.

The IBD (Initial Block Download) Problem

During initial sync, a node might be presented with a 'fake chain' (a chain not accepted by the majority of stakers). If the fork is beyond the maxreorg parameter, the local node cannot rewind and may become stuck on the wrong chain.

Mitigations implemented in Blockcore:

• Checkpoints: The software includes regularly hard-coded checkpoints of the correct chain to prevent nodes from following fake chains.
• Connection Restrictions: During IBD, a node will only accept outgoing connections to mitigate the risk of being fed a fake chain by malicious peers.

General PoS Considerations

• Complexity: The protocol is more complex than Proof of Work (PoW), which may introduce unknown attack vectors.
• Decentralization: PoS is often considered less decentralized due to the reliance on checkpoints for IBD and the requirement for a majority of nodes to have synchronized global time.
• 51% Attack Recovery: In the event of a 51% attack, user intervention (such as utilizing checkpoints) may be required to recover the network.

To improve performance when logging large volumes of data, use the AsyncWrapper target in your NLog.config.

Note on Reliability: Async logging may result in lost logs if the program crashes unexpectedly, as logs might not be flushed to disk. For development where crashes are expected, use a standard File target. For testing features where you expect stability, use AsyncWrapper.

If you handle exceptions manually and want to ensure logs are saved before a crash, call NLog.LogManager.Flush().

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" autoReload="true">
  <targets>
    <target name="debugAllFile" xsi:type="AsyncWrapper" queueLimit="10000" overflowAction="Block" batchSize="1000">
      <target xsi:type="File" fileName="debug.txt" layout="[${longdate:universalTime=true} ${threadid}${mdlc:item=id}] ${level:uppercase=true}: ${callsite} ${message}" encoding="utf-8" />
    </target>
    <target xsi:type="null" name="null" formatMessage="false" />
  </targets>

  <rules>
    <logger name="*" minlevel="Trace" writeTo="null" final="true" />
    <logger name="*" minlevel="Trace" writeTo="debugAllFile" />
  </rules>
</nlog>

Smart Contract Whitelisting integrates with the Proof of Authority (PoA) voting feature. The process works as follows:

1. Hashing: The system hashes the bytecode of any contract creation transaction.
2. Validation: The resulting hash is checked against the federation's whitelist.
3. Enforcement: If the hash is not in the whitelist, the contract deployment fails.

Validation Layers

• Consensus Rule: The system uses a full-validation consensus rule called AllowedCodeHashLogic. Full validation is required because the whitelist repository itself is updated via full-validation rules. This prevents issues during chain reorgs where a hash might be removed from the whitelist.
• Mempool Validation: The mempool pre-validates incoming transactions using the same consensus rule. If a transaction's code hash is not whitelisted, it will not be considered for inclusion in a block.

Note: A transaction might be accepted into the mempool but fail to be included in a block if the contract's code hash is removed from the whitelist between the time of mempool entry and the time of mining.