Add README file

Author: Hrom131

README.md

@@ -1 +1,76 @@
-# SPV Contracts
+# SPV Contracts
+
+Smart contract for verifying Bitcoin block headers on EVM-compatible chains using the **Simple Payment Verification (SPV)** method.
+
+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.
+
+## Features
+
+- 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
+
+To run the tests, execute the following command:
+
+```bash
+npm run test
+```
+
+Or to see the coverage, run:
+
+```bash
+npm run coverage
+```
+
+### Local deployment
+
+To deploy the contracts locally, run the following commands (in the different terminals):
+
+```bash
+npm run private-network
+npm run deploy-localhost
+```
+
+### Bindings
+
+The command to generate the bindings is as follows:
+
+```bash
+npm run generate-types
+```

contracts/libs/BlocksStorage.sol

@@ -22,7 +22,7 @@ library BlocksStorage {
         Unknown,
         Pending,
         Stale,
-        Active
+        Confirmed
     }
 
     struct BlockData {
@@ -195,7 +195,7 @@ library BlocksStorage {
             return BlockStatus.Stale;
         }
 
-        return BlockStatus.Active;
+        return BlockStatus.Confirmed;
     }
 
     function getMedianTime(

hardhat.config.ts

@@ -38,38 +38,6 @@ const config: HardhatUserConfig = {
       accounts: privateKey(),
       gasMultiplier: 1.2,
     },
-    chapel: {
-      url: "https://data-seed-prebsc-1-s1.binance.org:8545",
-      accounts: privateKey(),
-      gasMultiplier: 1.2,
-      timeout: 60000,
-    },
-    fuji: {
-      url: `https://avalanche-fuji.infura.io/v3/${process.env.INFURA_KEY}`,
-      accounts: privateKey(),
-      gasMultiplier: 1.2,
-    },
-    bsc: {
-      url: "https://bsc-dataseed.binance.org/",
-      accounts: privateKey(),
-      gasMultiplier: 1.2,
-    },
-    ethereum: {
-      url: `https://mainnet.infura.io/v3/${process.env.INFURA_KEY}`,
-      accounts: privateKey(),
-      gasMultiplier: 1.2,
-    },
-    polygon: {
-      url: `https://matic-mainnet.chainstacklabs.com`,
-      accounts: privateKey(),
-      gasMultiplier: 1.2,
-    },
-    avalanche: {
-      url: `https://api.avax.network/ext/bc/C/rpc`,
-      accounts: privateKey(),
-      gasMultiplier: 1.2,
-      timeout: 60000,
-    },
   },
   solidity: {
     version: "0.8.28",

package.json

@@ -25,9 +25,6 @@
     "private-network-fork": "npx hardhat node --fork https://mainnet.infura.io/v3/$(grep INFURA_KEY .env | cut -d '\"' -f2)",
     "deploy-localhost": "npx hardhat migrate --network localhost",
     "deploy-sepolia": "npx hardhat migrate --network sepolia --verify",
-    "deploy-fuji": "npx hardhat migrate --network fuji --verify",
-    "deploy-ethereum": "npx hardhat migrate --network ethereum --verify",
-    "deploy-avalanche": "npx hardhat migrate --network avalanche --verify",
     "generate-types": "TYPECHAIN_FORCE=true npx hardhat typechain && npx hardhat gobind",
     "generate-docs": "npx hardhat markup",
     "solhint-check": "solhint \"./contracts/**/*.sol\"",

test/helpers/types.ts

@@ -29,5 +29,5 @@ export enum BlockStatus {
   Unknown = 0,
   Pending = 1,
   Stale = 2,
-  Active = 3,
+  Confirmed = 3,
 }

test/libs/BlocksStorage.test.ts

@@ -151,7 +151,7 @@ describe("BlocksStorage", () => {
         if (i > defaultPendingBlocksCount) {
           expect(
             await blocksStorageLib.getBlockStatus(blocksData[i - defaultPendingBlocksCount - 1].blockHash),
-          ).to.be.eq(BlockStatus.Active);
+          ).to.be.eq(BlockStatus.Confirmed);
         }
       }
     });
@@ -202,7 +202,7 @@ describe("BlocksStorage", () => {
         if (i > defaultPendingBlocksCount) {
           expect(
             await blocksStorageLib.getBlockStatus(blocksData[i - defaultPendingBlocksCount - 1].blockHash),
-          ).to.be.eq(BlockStatus.Active);
+          ).to.be.eq(BlockStatus.Confirmed);
         }
       }
     });