feat(cli): database pruning tool for historical trie data (#123)

* feat(db): add database pruning tool for historical trie data

- Add prune subcommand to katana db utility
- Support two modes: prune all history or keep last N blocks
- Include safety checks and proper error handling
- Efficiently handle bulk deletions using database cursors

* feat: add progress monitoring and visualization for database pruning

- Add indicatif dependency for progress bar visualization
- Implement multi-level progress bars showing overall and per-table progress
- Add counting passes to determine total entries for accurate progress tracking
- Show table names, current/total entries, elapsed time, and entries per second
- Visual progress bars with cyan/blue styling for better user experience

---------

Co-authored-by: Ammar Arif <evergreenkary@gmail.com>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

Author: 3 people

AGENT.md

@@ -0,0 +1,29 @@
+# Katana Development Guide
+
+## Build Commands
+- `cargo build` - Build the project
+- `cargo test` - Run all tests  
+- `cargo test <test_name>` - Run a specific test
+- `cargo test -p <crate_name>` - Run tests for a specific crate
+- `cargo clippy` - Run linter
+- `make test-artifacts` - Prepare test database and SNOS artifacts
+
+## Code Style
+- **Formatting**: Uses rustfmt with 100 char width, group imports by StdExternalCrate
+- **Imports**: std → external crates → local crates, use explicit paths `use crate::module::Type`
+- **Naming**: snake_case functions, constructors use `new()`, `from_*()`, `with_*()` patterns
+- **Error Handling**: Use `thiserror` for custom errors, `anyhow` for general error handling, always use `Result<T>` types
+- **Visibility**: Clear `pub` boundaries, comprehensive `///` docs for public APIs
+- **Async**: Use `async/await` with `?` operator for error propagation
+- **Types**: Use `Arc<>` for shared ownership, prefer owned types over references in function signatures
+
+## Testing
+- Test modules use `#[cfg(test)]` 
+- Use descriptive test names that explain the scenario being tested
+- Use `rstest` for parameterized tests, `assert_matches` for pattern matching
+- Run `make test-artifacts` before running tests that need database fixtures
+
+## Architecture
+- Workspace with multiple crates under `crates/` directory
+- Each crate focuses on specific functionality (rpc, storage, executor, etc.)
+- Use workspace dependencies for consistent versioning across crates

Cargo.lock

@@ -100,7 +100,6 @@ cairo-lang-starknet-classes = "2.11.2"
 cairo-lang-utils = "2.11.2"
 # Some types that we used from cairo-vm implements the `Arbitrary` trait,
 # only under the `test_utils` feature. So we expose through this feature.
-cairo-vm = { version = "1.0.2", features = [ "test_utils" ] }
 anyhow = "1.0.89"
 arbitrary = { version = "1.3.2", features = [ "derive" ] }
 assert_fs = "1.1"
@@ -109,6 +108,7 @@ async-trait = "0.1.82"
 auto_impl = "1.2.0"
 base64 = "0.21.2"
 bigdecimal = "0.4.1"
+cairo-vm = { version = "1.0.2", features = [ "test_utils" ] }
 camino = { version = "1.1.2", features = [ "serde1" ] }
 chrono = { version = "0.4.24", features = [ "serde" ] }
 clap = { version = "4.5.16", features = [ "derive", "env" ] }
@@ -194,13 +194,13 @@ tonic-build = "0.11"
 tonic-reflection = "0.11"
 tonic-web = "0.11"
 # WASM-compatible gRPC deps
+criterion = "0.5.1"
+pprof = { version = "0.13.0", features = [ "criterion", "flamegraph" ] }
+slot = { git = "https://github.com/cartridge-gg/slot", rev = "1298a30" }
 tonic-web-wasm-client = "0.6.0"
 wasm-prost = { version = "0.13", package = "prost" }
 wasm-tonic = { version = "0.12", default-features = false, features = [ "codegen", "gzip", "prost" ], package = "tonic" }
 wasm-tonic-build = { version = "0.12", default-features = false, features = [ "prost" ], package = "tonic-build" }
-criterion = "0.5.1"
-pprof = { version = "0.13.0", features = [ "criterion", "flamegraph" ] }
-slot = { git = "https://github.com/cartridge-gg/slot", rev = "1298a30" }
 # alloy core
 alloy-primitives = { version = "0.8", default-features = false }
 alloy-sol-types = { version = "0.8", default-features = false }
@@ -213,10 +213,10 @@ alloy-rpc-types-eth = { version = "0.4", default-features = false }
 alloy-signer = { version = "0.4", default-features = false }
 alloy-transport = { version = "0.4", default-features = false }
 
+bitvec = "1.0.1"
 starknet = "0.14.0"
 starknet-crypto = "0.7.1"
 starknet-types-core = { version = "0.1.8", features = [ "arbitrary", "hash" ] }
-bitvec = "1.0.1"
 # macro
 proc-macro2 = "1.0"
 quote = "1.0"
@@ -238,3 +238,10 @@ opentelemetry-stackdriver = { version = "0.27.0", features = [ "propagator" ] }
 # alloy
 # macro
 blockifier = { git = "https://github.com/dojoengine/sequencer", rev = "5d737b9c9", default-features = false }
+
+[patch.crates-io]
+# NOTE: remove this patch once this PR is merged <https://github.com/starknet-io/types-rs/pull/132>
+#
+# This patch fixes an issue where we're unable to correctly evaluate the accurate size
+# for constructing `Felt` from unstructured data (Arbitrary).
+starknet-types-core = { git = "https://github.com/kariy/types-rs", rev = "0f6ae31" }

Cargo.toml

@@ -9,7 +9,7 @@ version.workspace = true
 [dependencies]
 katana-chain-spec.workspace = true
 katana-cli.workspace = true
-katana-db.workspace = true
+katana-db = { workspace = true, features = [ "arbitrary" ] }
 katana-primitives.workspace = true
 katana-rpc-types.workspace = true
 katana-utils.workspace = true
@@ -22,6 +22,7 @@ clap.workspace = true
 clap_complete.workspace = true
 comfy-table = "7.1.1"
 const_format = "0.2.33"
+indicatif = "0.17.8"
 inquire = "0.7.5"
 piltover = { git = "https://github.com/keep-starknet-strange/piltover.git", rev = "45263e8" }
 rand.workspace = true
@@ -39,9 +40,14 @@ vergen = { version = "9.0.0", features = [ "build", "cargo", "emit_and_set" ] }
 vergen-gitcl = { version = "1.0.0", features = [ "build", "cargo", "rustc", "si" ] }
 
 [dev-dependencies]
+katana-provider.workspace = true
+
+arbitrary.workspace = true
 assert_matches.workspace = true
+proptest = "1.0"
 rstest.workspace = true
 starknet.workspace = true
+tempfile.workspace = true
 
 [features]
 default = [ "cartridge", "init-slot", "jemalloc", "katana-cli/explorer" ]