Packages

.gitignore

@@ -25,4 +25,4 @@ Cargo.lock
 .python-version
 __pycache__
 
-.raito/
+.client_cache/

README.md

@@ -70,7 +70,7 @@ Extend light client with partial transaction validation, but without UTXO checks
 
 Tasks:
 
-* [ ] reassess validation check list (analyze Bitcoin core codebase)
+* [x] reassess validation check list (analyze Bitcoin core codebase)
 * [x] generate & run integration tests e2e instead of Cairo codegen
 * [x] transaction ID calculation
 * [x] transaction root computation
@@ -137,34 +137,12 @@ This will compile all the components:
 scarb build
 ```
 
-This will run unit and integration tests:
+This will tests:
 
 ```bash
 scarb test
 ```
 
-For integration tests ony:
-
-```bash
-scarb run integration_tests
-```
-
-Run for specific test file(s):
-
-```bash
-scarb run integration_tests tests/data/light_481823.json
-```
-
-Re-generate integration test data:
-
-```base
-scarb run regenerate_tests --force
-```
-
-* Without `--force` flag only non-existent files will be created
-* Files are located in [tests/data/](https://github.com/keep-starknet-strange/raito/blob/main/tests/data)
-* If you want to add a new test case, edit [scripts/data/regenerate_tests.sh](https://github.com/keep-starknet-strange/raito/blob/main/scripts/data/regenerate_tests.sh)
-
 ## Build dependencies
 
 Install necessary packages required by Python scripts:

Scarb.lock

@@ -2,14 +2,14 @@
 version = 1
 
 [[package]]
-name = "integration_tests"
+name = "client"
 version = "0.1.0"
 dependencies = [
- "shinigami_consensus",
+ "consensus",
 ]
 
 [[package]]
-name = "shinigami_consensus"
+name = "consensus"
 version = "0.1.0"
 dependencies = [
  "utils",

Scarb.toml

@@ -1,8 +1,8 @@
 [workspace]
-members = ["crates/*"]
+members = ["packages/*"]
 
 [workspace.package]
-description = "Raito is Bitcoin ZK client."
+description = "Bitcoin ZK client."
 cairo-version = "2.8.2"
 version = "0.1.0"
 readme = "README.md"

packages/client/README.md

@@ -0,0 +1,45 @@
+# Bitcoin client in Cairo
+
+This package is a standalone Cairo program (outside of Starknet context) that implements a Bitcoin client which can work in two modes:
+- Light mode: block header validation only
+- Full mode: full Bitcoin consensus validation
+
+## Usage
+
+```sh
+# You have to be in the "packages/client" directory
+scarb run client START_HEIGHT END_HEIGHT BATCH_SIZE MODE STRATEGY
+```
+
+Client expects the following arguments:
+* `START_HEIGHT` height of the initial chain state
+* `END_HEIGHT` height of the final (resulting) chain state
+* `BATCH_SIZE` number of blocks applied per single program run
+* `MODE` either `light` or `full` (default is light)
+* `STRATEGY` either `sequential` or `random` (default is sequential)
+
+## Integration tests
+
+In order to run integration tests:
+
+```sh
+scarb test
+```
+
+Run a specific test file (or several files):
+
+```sh
+# You have to be in the "packages/client" directory
+scarb test tests/data/light_481823.json
+```
+
+Re-generate integration test data:
+
+```sh
+# You have to be in the "packages/client" directory
+scarb run regenerate_tests --force
+```
+
+If you want to just add a new test case, edit `scripts/data/regenerate_tests.sh` and run without `--force` flag.
+
+You can also add/remove ignored scenarios, check out `scripts/data/regenerate_tests.sh` as well.

crates/integration_tests/Scarb.toml → packages/client/Scarb.toml

@@ -1,10 +1,10 @@
 [package]
-name = "integration_tests"
+name = "client"
 version = "0.1.0"
 edition = "2024_07"
 
 [dependencies]
-shinigami_consensus = { path = "../shinigami_consensus" }
+consensus = { path = "../consensus" }
 
 [dev-dependencies]
 cairo_test.workspace = true

packages/client/src/lib.cairo

@@ -0,0 +1,4 @@
+mod main;
+// TODO: scarb cairo-run should support "features" argument
+// so that we can conditionally compile this module
+mod test;

crates/shinigami_consensus/src/main.cairo → packages/client/src/main.cairo

@@ -1,5 +1,5 @@
-use crate::types::block::Block;
-use crate::types::chain_state::{ChainState, BlockValidator};
+use consensus::types::block::Block;
+use consensus::types::chain_state::{ChainState, BlockValidator};
 
 /// Raito program arguments.
 #[derive(Serde)]

crates/integration_tests/src/lib.cairo → packages/client/src/test.cairo

@@ -1,5 +1,5 @@
-use shinigami_consensus::types::block::Block;
-use shinigami_consensus::types::chain_state::{ChainState, BlockValidator};
+use consensus::types::block::Block;
+use consensus::types::chain_state::{ChainState, BlockValidator};
 use core::testing::get_available_gas;
 
 /// Integration testing program arguments.
@@ -18,7 +18,7 @@ struct Args {
 /// Receives arguments in a serialized format (Cairo serde).
 /// Panics in case of a validation error or chain state mismatch.
 /// Prints result to the stdout.
-fn main(mut arguments: Span<felt252>) {
+fn test(mut arguments: Span<felt252>) {
     let Args { mut chain_state, blocks, expected_chain_state } = Serde::deserialize(ref arguments)
         .expect('Failed to deserialize');
 

packages/consensus/README.md

@@ -0,0 +1,8 @@
+# Bitcoin consensus in Cairo
+
+This package is a Cairo library providing primitives for validating Bitcoin consensus.  
+
+It is structured as follows:
+* `types` module contains all Bitcoin specific entities (start your codebase tour with this folder) adapted for recursive verification;
+* `validation` module contains most of the consensus validation logic;
+* `codec` module contains implementation of Bitcoin binary codec for transaction types.

crates/shinigami_consensus/Scarb.toml → packages/consensus/Scarb.toml

@@ -1,5 +1,5 @@
 [package]
-name = "shinigami_consensus"
+name = "consensus"
 version = "0.1.0"
 edition = "2024_07"
 

crates/shinigami_consensus/src/lib.cairo → packages/consensus/src/lib.cairo

@@ -15,5 +15,3 @@ pub mod types {
     pub mod transaction;
     pub mod utxo_set;
 }
-
-mod main;

packages/utils/README.md

@@ -0,0 +1,3 @@
+# Common utilities
+
+This package contains common helpers that are not Bitcoin-specific.

scripts/data/client.sh

@@ -3,7 +3,7 @@
 #set -e;
 #set -o pipefail;
 
-base_dir=".raito"
+base_dir=".client_cache"
 
 start=${1:-0}
 end=${2:-100}
@@ -27,7 +27,7 @@ run_client() {
   fi
 
   arguments=$(python ../../scripts/data/format_args.py $batch_file)
-  output=$(scarb cairo-run --no-build --package integration_tests "$arguments")
+  output=$(scarb cairo-run --no-build --package client --function test "$arguments")
   if [[ "$output" == *"FAIL"* ]]; then
     echo " fail"
     echo $output

scripts/data/integration_tests.sh

@@ -22,7 +22,7 @@ if [ $# -gt 0 ]; then
     test_files="${args[@]}"
 fi
 
-echo "testing e2e scenarios ..."
+echo "running integration tests ..."
 
 for test_file in $test_files; do
     if [ -f "$test_file" ]; then
@@ -33,7 +33,7 @@ for test_file in $test_files; do
             num_ignored=$((num_ignored + 1))
         else
             arguments=$(python ../../scripts/data/format_args.py ${test_file})
-            output=$(scarb cairo-run --no-build "$arguments")
+            output=$(scarb cairo-run --no-build --function test "$arguments")
             gas_spent=$(echo $output | grep -o 'gas_spent=[0-9]*' | sed 's/gas_spent=//')
 
             if [[ "$output" == *"FAIL"* ]]; then