Merge pull request #1 from distributed-lab/dev

SPVContract implementation

Author: Hrom131

.solcover.ts

@@ -1,4 +1,4 @@
 module.exports = {
-  skipFiles: [],
+  skipFiles: ["mock/"],
   configureYulOptimizer: true,
 };

README.md

@@ -1,20 +1,50 @@
-# Hardhat template 
+# SPV Contracts
 
-Template hardhat repository for ad-hoc smart contracts development.
+Smart contract for verifying Bitcoin block headers on EVM-compatible chains using the **Simple Payment Verification (SPV)** method.
 
-### How to use
+This contract behaves like an SPV node: it builds a valid chain of Bitcoin block headers, verifies them according to Bitcoin consensus rules, and enables Merkle Proof-based verification of Bitcoin transactions.
 
-The template works out of the box. To clean up the repo, you may need to delete the mock contracts, tests and migration files.
+## Features
 
-#### Compilation
+- Stores and verifies Bitcoin block headers
+- Validates headers using:
+  - Proof of Work (`bits` → `target`)
+  - Median time rule
+  - Chain continuity
+- Handles difficulty adjustment every 2016 blocks
+- Supports pending difficulty epochs before finalization
+- Stores historical targets and supports reorg handling
+
+## Contract: `SPVContract.sol`
+
+### Key Functions
+
+#### `addBlockHeader(bytes calldata blockHeaderRaw)`
+Adds and validates a new block header, updates internal state, and emits an event.
+
+### Validation Rules
+- `prevBlockHash` must point to a known block
+- New `blockHash` must not exist
+- Header `bits` must match the expected network target
+- Header `time` must be > median of last 11 blocks
+- `blockHash` must be less than or equal to the target (valid PoW)
+
+## Storage Structure
+
+- `BlocksData` – stores block headers, timestamps, and chain height
+- `TargetsData` – handles target values and difficulty epochs
+- `pendingTargetHeightCount` – controls target finalization after N blocks
+
+## Dev Info
+### Compilation
 
 To compile the contracts, use the next script:
 
 ```bash
 npm run compile
 ```
 
-#### Test
+### Test
 
 To run the tests, execute the following command:
 
@@ -28,7 +58,7 @@ Or to see the coverage, run:
 npm run coverage
 ```
 
-#### Local deployment
+### Local deployment
 
 To deploy the contracts locally, run the following commands (in the different terminals):
 
@@ -37,28 +67,10 @@ npm run private-network
 npm run deploy-localhost
 ```
 
-#### Bindings
+### Bindings
 
 The command to generate the bindings is as follows:
 
 ```bash
 npm run generate-types
-```
-
-> See the full list of available commands in the `package.json` file.
-
-### Integrated plugins
-
-- Hardhat official `ethers` + `ethers-v6`
-- [`Typechain`](https://www.npmjs.com/package/@typechain/hardhat)
-- [`hardhat-migrate`](https://www.npmjs.com/package/@solarity/hardhat-migrate), [`hardhat-markup`](https://www.npmjs.com/package/@solarity/hardhat-markup), [`hardhat-gobind`](https://www.npmjs.com/package/@solarity/hardhat-gobind)
-- [`hardhat-zkit`](https://www.npmjs.com/package/@solarity/hardhat-zkit), [`chai-zkit`](https://www.npmjs.com/package/@solarity/chai-zkit)
-- [`hardhat-contract-sizer`](https://www.npmjs.com/package/hardhat-contract-sizer)
-- [`hardhat-gas-reporter`](https://www.npmjs.com/package/hardhat-gas-reporter)
-- [`solidity-coverage`](https://www.npmjs.com/package/solidity-coverage)
-
-### Other niceties
-
-- The template comes with presetup `prettier` and `solhint` that lint the project via `husky` before compilation hook.
-- The `.env.example` file is provided to check what is required as ENVs
-- Preinstalled `@openzeppelin/contracts` and `@solarity/solidity-lib`
+```

contracts/SPVContract.sol

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+
+import {BlockHeader, BlockHeaderData} from "./libs/BlockHeader.sol";
+import {BlocksStorage} from "./libs/BlocksStorage.sol";
+import {TargetsStorage} from "./libs/targets/TargetsStorage.sol";
+import {TargetsHelper} from "./libs/targets/TargetsHelper.sol";
+
+contract SPVContract is Initializable {
+    using BlockHeader for bytes;
+    using BlocksStorage for BlocksStorage.BlocksData;
+    using TargetsStorage for TargetsStorage.TargetsData;
+
+    bytes32 public constant SPV_CONTRACT_STORAGE_SLOT =
+        keccak256("spv.contract.spv.contract.storage");
+
+    error PrevBlockDoesNotExist(bytes32 prevBlockHash);
+    error BlockAlreadyExists(bytes32 blockHash);
+
+    error InvalidTarget(bytes32 blockTarget, bytes32 networkTarget);
+    error InvalidBlockHash(bytes32 actualBlockHash, bytes32 blockTarget);
+    error InvalidBlockTime(uint32 blockTime, uint32 medianTime);
+
+    event BlockHeaderAdded(uint256 indexed blockHeight, bytes32 indexed blockHash);
+
+    struct SPVContractStorage {
+        BlocksStorage.BlocksData blocksData;
+        TargetsStorage.TargetsData targets;
+        uint256 pendingTargetHeightCount;
+    }
+
+    function __SPVContract_init(
+        uint256 pendingBlockCount_,
+        uint256 pendingTargetHeightCount_
+    ) external initializer {
+        SPVContractStorage storage $ = _getSPVContractStorage();
+
+        $.blocksData.initialize(pendingBlockCount_);
+        $.targets.initialize();
+
+        $.pendingTargetHeightCount = pendingTargetHeightCount_;
+    }
+
+    function _getSPVContractStorage() internal pure returns (SPVContractStorage storage _spvs) {
+        bytes32 slot_ = SPV_CONTRACT_STORAGE_SLOT;
+
+        assembly {
+            _spvs.slot := slot_
+        }
+    }
+
+    function addBlockHeader(bytes calldata blockHeaderRaw_) external {
+        SPVContractStorage storage $ = _getSPVContractStorage();
+
+        (BlockHeaderData memory blockHeader_, bytes32 blockHash_) = blockHeaderRaw_
+            .parseBlockHeaderData();
+
+        require(!$.blocksData.blockExists(blockHash_), BlockAlreadyExists(blockHash_));
+        require(
+            $.blocksData.blockExists(blockHeader_.prevBlockHash),
+            PrevBlockDoesNotExist(blockHeader_.prevBlockHash)
+        );
+
+        uint256 blockHeight_ = $.blocksData.getBlockHeight(blockHeader_.prevBlockHash) + 1;
+
+        _tryConfirmPendingTarget(blockHeight_);
+
+        bytes32 target_ = _getRequiredTarget(blockHeight_, blockHeader_.prevBlockHash);
+
+        _validateBlockRules(blockHeader_, blockHash_, target_);
+
+        $.blocksData.addBlock(
+            blockHeader_,
+            blockHash_,
+            blockHeight_,
+            TargetsStorage.getBlockWork(target_)
+        );
+
+        if (TargetsStorage.isTargetAdjustmentBlock(blockHeight_)) {
+            $.targets.updatePendingTarget(
+                blockHeight_,
+                blockHash_,
+                $.blocksData.getBlockTimeByBlockHeight(
+                    blockHeight_ - TargetsStorage.DIFFICULTY_ADJSTMENT_INTERVAL
+                ),
+                blockHeader_.time
+            );
+        }
+
+        emit BlockHeaderAdded(blockHeight_, blockHash_);
+    }
+
+    function _getRequiredTarget(
+        uint256 blockHeight_,
+        bytes32 prevBlockHash_
+    ) internal view returns (bytes32 target_) {
+        SPVContractStorage storage $ = _getSPVContractStorage();
+
+        uint256 blockTargetEpoch_ = TargetsStorage.countTargetEpoch(blockHeight_);
+        bool isPendingTargetRequired_ = blockTargetEpoch_ == $.targets.getPendingEpoch();
+
+        if (isPendingTargetRequired_) {
+            uint256 epochBlockNumber_ = TargetsStorage.getEpochBlockNumber(blockHeight_);
+
+            for (uint256 i = 0; i < epochBlockNumber_ - 1; ++i) {
+                prevBlockHash_ = $.blocksData.getPrevBlockHash(prevBlockHash_);
+            }
+
+            target_ = $.targets.getPendingTarget(prevBlockHash_);
+        } else {
+            target_ = $.targets.getTarget(blockTargetEpoch_);
+        }
+
+        assert(target_ > 0);
+    }
+
+    function _tryConfirmPendingTarget(uint256 blockHeight_) internal {
+        SPVContractStorage storage $ = _getSPVContractStorage();
+
+        if (!$.targets.hasPendingTarget() || blockHeight_ < $.pendingTargetHeightCount) {
+            return;
+        }
+
+        uint256 lastActiveBlockHeight_ = blockHeight_ - $.pendingTargetHeightCount;
+
+        if (TargetsStorage.isTargetAdjustmentBlock(lastActiveBlockHeight_)) {
+            $.targets.confirmPendingTarget(
+                $.blocksData.getBlockHashByBlockHeight(lastActiveBlockHeight_)
+            );
+        }
+    }
+
+    function _validateBlockRules(
+        BlockHeaderData memory blockHeader_,
+        bytes32 blockHash_,
+        bytes32 target_
+    ) internal view {
+        SPVContractStorage storage $ = _getSPVContractStorage();
+
+        bytes32 blockTarget_ = TargetsHelper.bitsToTarget(blockHeader_.bits);
+
+        require(target_ == blockTarget_, InvalidTarget(blockTarget_, target_));
+        require(blockHash_ <= blockTarget_, InvalidBlockHash(blockHash_, blockTarget_));
+
+        uint32 medianTime_ = $.blocksData.getMedianTime(blockHeader_.prevBlockHash);
+
+        require(blockHeader_.time > medianTime_, InvalidBlockTime(blockHeader_.time, medianTime_));
+    }
+}

contracts/libs/BlockHeader.sol

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import {LibBit} from "solady/src/utils/LibBit.sol";
+
+struct BlockHeaderData {
+    bytes32 prevBlockHash;
+    bytes32 merkleRoot;
+    uint32 version;
+    uint32 time;
+    uint32 nonce;
+    bytes4 bits;
+}
+
+library BlockHeader {
+    using LibBit for uint256;
+
+    uint256 public constant BLOCK_HEADER_DATA_LENGTH = 80;
+
+    error InvalidBlockHeaderDataLength();
+
+    function getBlockHeaderHash(bytes calldata blockHeaderRaw_) internal pure returns (bytes32) {
+        bytes32 rawBlockHash_ = sha256(abi.encode(sha256(blockHeaderRaw_)));
+
+        return reverseHash(rawBlockHash_);
+    }
+
+    function parseBlockHeaderData(
+        bytes calldata blockHeaderRaw_
+    ) internal pure returns (BlockHeaderData memory headerData_, bytes32 blockHash_) {
+        require(
+            blockHeaderRaw_.length == BLOCK_HEADER_DATA_LENGTH,
+            InvalidBlockHeaderDataLength()
+        );
+
+        headerData_ = BlockHeaderData({
+            version: uint32(_reverseBytes(blockHeaderRaw_[0:4])),
+            prevBlockHash: reverseHash(bytes32(blockHeaderRaw_[4:36])),
+            merkleRoot: reverseHash(bytes32(blockHeaderRaw_[36:68])),
+            time: uint32(_reverseBytes(blockHeaderRaw_[68:72])),
+            bits: bytes4(uint32(_reverseBytes(blockHeaderRaw_[72:76]))),
+            nonce: uint32(_reverseBytes(blockHeaderRaw_[76:80]))
+        });
+        blockHash_ = getBlockHeaderHash(blockHeaderRaw_);
+    }
+
+    function toRawBytes(BlockHeaderData memory headerData_) internal pure returns (bytes memory) {
+        return
+            abi.encodePacked(
+                _reverseUint32(headerData_.version),
+                reverseHash(headerData_.prevBlockHash),
+                reverseHash(headerData_.merkleRoot),
+                _reverseUint32(headerData_.time),
+                _reverseUint32(uint32(headerData_.bits)),
+                _reverseUint32(headerData_.nonce)
+            );
+    }
+
+    function reverseHash(bytes32 blockHash_) internal pure returns (bytes32) {
+        return bytes32(uint256(blockHash_).reverseBytes());
+    }
+
+    function _reverseBytes(bytes calldata bytesToConvert_) private pure returns (uint256) {
+        return uint256(bytes32(bytesToConvert_)).reverseBytes();
+    }
+
+    function _reverseUint32(uint32 input_) private pure returns (uint32) {
+        return
+            ((input_ & 0x000000FF) << 24) |
+            ((input_ & 0x0000FF00) << 8) |
+            ((input_ & 0x00FF0000) >> 8) |
+            ((input_ & 0xFF000000) >> 24);
+    }
+}