Conversation
Removed hardware optimization section and image from the design document.
Feature/server implementation
Stress testing
Add ADR for entries-based execution model and migrate reporting docs
* Introduce `entities` definitions for WAL and transactional structures * Refactor to simplify balance representation and remove generics * Add benchmark for snapshot processing and improve transaction logging * Remove unused tests and streamline imports across the project
…low (#32) * Introduce `Syncer` module for WAL file synchronization and integrate sync logic into `Segment` and `WAL`. * Refactor wait strategy API by renaming `wait_strategy()` to `retry()` and update all references. Simplify WAL buffer logic, enhance segment flushing with `BufWriter`, and optimize transaction processing flow. Add logging for recovery and ledger startup events. * Update transaction handling and entity structures, adjust ledger timeout, and improve buffer and synchronization logic. * Refactor WAL management to support dual-thread execution for writing and committing, enhance synchronization with `Syncer`, improve logging, and update tests and benchmarks accordingly. * Run tests in release mode for improved coverage and performance in `scripts/check.sh`. * Remove all benchmark scripts and related dependencies for `Criterion`. Update code to clean up unused benchmark imports, configurations, and declarations. Simplify configuration logic by reducing unused options in `LedgerConfig` and improving WAL size handling. * Remove `first_tx_id` from `SegmentHeader` and related logic across the codebase. Refactor WAL runner initialization and segment rotation to simplify transaction ID handling and improve clarity.
- Integrate `spin_loop` for improved retry efficiency in WAL and transactor. - Add reusable `Syncer` logic with cached `sync_id` for synchronization operations. - Replace `HashMap` with `FxHashMap` in deduplication cache for performance. - Update dependencies and `Cargo.toml` to include `rustc-hash`.
- Deleted `docs/architecture/benchmarks.md` and replaced it with `docs/load.md`. - Updated `README.md` to include revised throughput and latency data from load testing. - Added support for measuring latency and transactions per second in both async and wait modes within the load generator.
…ve redundant environment sourcing
…s SSH environment variables
…logy (#37) * Add pipeline diagram to documentation for better visualization of transaction flow * improve colors * Update pipeline diagram with improved colors and additional labels to enhance clarity * Add new ADR entries, reorganize documentation structure, and update pipeline diagram for better clarity * Add WAL flow diagram to documentation to visualize write-ahead log processes * Add segment anatomy and seal flow diagrams to documentation for enhanced process visualization * Add logical view diagram to documentation for enhanced system visualization * Standardize terminology across codebase: rename "Processed" to "Computed" and "Snapshotted" to "OnSnapshot" for improved consistency in pipeline and documentation. * Standardize terminology in architecture documentation: rename indexes for consistency and improve clarity by removing redundant details. * Fix incorrect index references in architecture docs for consistency and accuracy
* Revamp README with enhanced structure, updated benchmarks, and comprehensive feature explanations. * Update README: refine phrasing, revise benchmarks, and clarify planned features
* Remove architecture and consistency model documentation files as part of cleanup and internal restructuring. * Update introduction docs: adjust benchmarks and restructure navigation
* Remove architecture and consistency model documentation files as part of cleanup and internal restructuring. * Update introduction docs: adjust benchmarks and restructure navigation * Add `commit_index` to pipeline and update Docker volume paths in docs and README
Removed duplicate documentation section and retained the link.
…nts (#43) * Add tests for WAL recovery: active, closed-unsealed, and sealed segments * Improve formatting in query_cold_path_test.rs for better readability
* Add ADR-012: End-to-End Testing Strategy and Framework * Introduce E2E testing framework and initial tests for ADR-012 * Add Process backend support for E2E testing framework - Introduced `backend_process` module to run nodes as OS processes. - Updated `InlineNode` and `ProcessNode` to load configurations from `Profile`. - Enhanced profiles to support Process backend-specific configurations, including runtime overrides. - Integrated Process backend into `Context` for E2E tests. * Add GitHub Actions workflow for E2E testing with Hetzner Cloud integration * Add matrix grid tests and supporting framework for deterministic E2E integration - Introduced `MatrixGrid` module for shared grid topology and math in matrix-transfer scenarios. - Added `matrix_transfer_grid` and `matrix_concurrent_transfer_grid` E2E tests to verify balance correctness, global zero-sum, and pipeline consistency under load. - Expanded E2E context with batch deposit/transfer helpers and enhanced balance retrieval for efficient bulk operations. - Documented the matrix testing scenario in `matrix-testing-scenario.md` to outline topology, parameters, execution steps, and verified invariants. - Updated profiles to increase account limits for scalable testing.
* Add crash recovery tests and process node lifecycle enhancements - Introduced `simple_crash_recovery` E2E test to verify WAL-based recovery across various segment sizes. - Enhanced `ProcessNode` with `kill()` and `restart()` methods for better lifecycle management. - Extended `E2EContext` with `kill_node`, `restart_node`, and `get_pipeline_index` helpers for streamlined testing workflows. - Updated `ProcessNode` to persist configuration and data directories across restarts. * Add high-level gRPC client and tests for roda-ledger - Introduced `LedgerClient` to provide a simplified interface over the gRPC API, with ergonomic async methods for common operations such as deposits, withdrawals, transfers, balance queries, and transaction status checks. - Added unit tests to verify client functionality, including fire-and-forget, batch operations, wait-for-pipeline-level, transaction queries, and account history retrievals. - Updated the library to expose the gRPC client module when the `grpc` feature is enabled. * Add `LedgerClient::transfer_batch_and_wait` method with tests - Introduced `transfer_batch_and_wait` to `LedgerClient` for bulk transfer operations with wait-level support. - Enhanced test cases for deposit and withdrawal operations. - Refactored test formatting for improved readability. - Updated `LedgerClient` and tests to simplify nested module imports by replacing generated gRPC path usages with higher-level ones. * Refactor RPC client method signatures and tests for consistent formatting - Simplified method signatures in `LedgerClient` by removing unnecessary line breaks. - Improved formatting of test assertions and macro definitions for better readability and maintainability. * Update `backend_process` to inherit stdout and stderr in E2E tests - Modified `Command` in `backend_process.rs` to use `Stdio::inherit()` for better visibility of process output during test execution. * Refactor crash recovery test to simplify WAL segment size handling and iteration logic * Refactor crash recovery test to simplify WAL segment size handling and iteration logic
…46) * Introduce idempotency window and transaction-count-based WAL segments - Documented deterministic idempotency guarantees tied to transaction-count-based active window. - Updated architecture and concepts to reflect transaction-count-based WAL segment rotation logic and fixed deduplication scope. - Proposed ADR-013: Replaced size-based WAL segments and time-based deduplication with transaction-count-based configurations. - Amended existing ADRs and config structures to align with the new deterministic transaction-count model. * Replace size-based WAL segments with transaction-count-based rotation - Updated tests to align with transaction-count-based WAL segment rotation. - Replaced `wal_segment_size_mb` with `transaction_count_per_segment` in codebase, configuration, and documentation. - Updated deduplication logic to support a transaction-based sliding window correlated with segment rotation. - Simplified recovery and dedup cache rebuild logic using transaction IDs instead of time-based windows. - Improved E2E and unit tests to verify deterministic transaction limits across various edge cases. * Add crash recovery mechanism for WAL and clean shutdown marker handling. - Introduced `wal.stop` marker for distinguishing clean shutdowns from crashes. - Implemented `Recover::crash_recover_if_needed` for WAL crash recovery, including CRC validation and truncation of corrupted data at the tail. - Added methods in `Segment` for `wal.stop` marker management (`create`, `delete`, `has_wal_stop`). - Enhanced `Ledger` start/stop lifecycle to support crash recovery and clean shutdown signaling. * Switch WAL segment rotation back to size-based configuration - Replace `transaction_count_per_segment` with `wal_segment_size_mb` across codebase and tests. - Update recovery logic to rebuild dedup cache using timestamps. - Refactor tests to align with size-based WAL segment handling and simplify iteration logic. * Refactor sealing tests to remove unnecessary type casting for `user_ref` parameter.
* Introduce batch transaction handling and load test improvements - Added `TransactionInput` enum to support single and batch transaction processing. - Implemented batch submission APIs (`submit_batch`) across sequencer, transactor, and gRPC handler. - Updated transactor logic for sequential and batch transaction processing with reordering and deduplication. - Added `load_grpc` tool for gRPC-based load testing and updated workflows. - Enhanced E2E test coverage for batch operations and integration scenarios. * Refactor transactor logic to simplify batch transaction ID assignment using `enumerate` and remove unused imports * Expand `TransactionInput` API with public `single`/`batch` methods and update benchmark to use `TransactionInput::Single`. * Add `grpc` feature flag to `load_grpc` in workflow and fix inclusive range in gRPC handler.
* Update Hetzner server type in load-test workflow configuration * Update Hetzner server type in load-test workflow configuration * Increase WAL buffer capacity by 16x for optimized performance under load.
* Introduce WASM Function Registry and Named Operation Support - Added ADR-014: Defined and implemented WASM-based `Operation::Named` for user-defined financial logic. - Deprecated `Operation::Composite` in favor of a versioned, registrable, auditable WASM function registry. - Integrated `wasmtime` as the sandboxed runtime for high-performance, safe execution. - Supported deterministic atomic execution, crash recovery, and Raft replication. - Expanded storage layout with `function_snapshot` and integrated registry management API (`RegisterFunction`, `ListFunctions`, `UnregisterFunction`). - Added tooling for onboarding WASM functions with strict validation and hot path optimizations. - Updated system architecture to include a lock-free execution cache for the Transactor. * Rename `fail_reason` to `status` across all structs, APIs, and documentation for clearer semantics and consistency (ADR-014). * Expand ADR-014 with detailed handling of negative balances, updated terminology, and refined WASM function registry operations. * Integrate WASM runtime and enhance storage for function registry operations (ADR-014). - Added `WasmRuntime` to `Transactor` for executing user-defined named operations. - Introduced `functions` and `function_snapshot` modules for WASM function lifecycle management. - Updated storage engine to ensure `functions` directory is created at startup. - Expanded benchmarks with ADR-014 specific tests for `Transaction::Named` handling. - Refactored `Transactor` to utilize shared `TransactorState` with `WasmRuntimeEngine`. * Switch `Named.params` to fixed-size `[i64; 8]` array (ADR-014). - Updated `Named` protobuf schema to clarify fixed-arity ABI rules. - Refactored `Operation::Named` to use `[i64; 8]` for WASM function parameters. - Simplified parameter handling by removing runtime zero-padding logic. - Optimized Transactor WASM integration for hot path efficiency. - Updated benchmarks, tests, and documentation to reflect changes. * Introduce WASM Function Registry and E2E Tests (ADR-014) - Added `RegisterFunction`, `ListFunctions`, and `UnregisterFunction` gRPC methods to support registrable, versioned WASM function execution. - Updated `ledger.proto` and pipeline logic to enable non-transactional WAL entries for function registration. - Integrated `WasmRuntime` into the Ledger and Snapshot stages for dynamic function handling. - Implemented E2E tests for the function lifecycle and `Operation::Named` execution. - Enhanced load testing with a new `load_wasm` generator to benchmark WASM overhead. * Rename `Named` to `Function` across proto, logic, and tests for improved clarity and consistency. * Remove `functions` module from storage and refactor WASM function lifecycle logic. - Removed the `functions` module from `storage` to centralize WASM function lifecycle management. - Moved function I/O operations (`write_function`, `read_function`, etc.) to `Storage`. - Introduced `WasmRegistry` as a façade for managing the function registry lifecycle. - Updated `Ledger` to delegate all WASM function operations to `WasmRegistry`. - Simplified `function_snapshot` and optimized related file I/O helpers. - Updated tests to reflect the new structure and functionality changes. * Standardize formatting across codebase: updated function definitions, struct initializations, and comments to improve readability and consistency. * Refactor CI and scripts for Clippy and test execution - Updated CI workflow to use `clippy` with `--all-targets` and `--all-features` for stricter linting. - Modified test commands in CI and scripts to include all test types (`--lib`, `--bins`, `--tests`, `--examples`) with `-- * Remove unused WASM function registry code and update CI for stricter checks - Deleted redundant `ledger_context` and related documentation/comments. - Removed unused WASM registry methods from `ledger.rs`. - Updated CI workflow to install `protoc` and ensure stricter Clippy linting with cargo. * Replace `Composite` operation with WASM `Function` (ADR-014) - Removed the `Composite` operation from the codebase, protobuf definitions, and documentation. - Added support for extensible, user-defined multi-step logic using WASM `Function` with fixed-arity parameters. - Updated tests, examples, and documentation to reflect the shift to WASM-based custom operations. * Introduce `ENTRY_LIMIT_EXCEEDED` enforcement for transactions exceeding 255 entries - Updated error documentation to clarify the meaning of `ENTRY_LIMIT_EXCEEDED`. - Added logic in `Transactor` to reject transactions emitting more than 255 ledger entries. - Introduced a new test to validate rollback behavior and proper rejection when the limit is exceeded.
* Expand README and docs: add details on WASM-based programmable ledger * Remove `Composite` operation and fully transition to WASM-based `Func…
* Add docs/internal.md as source-of-truth invariant register (Stage 1: Ledger)
Establish a single numbered-paragraph (§N.M) document that captures every
macro and micro decision, invariant, and internal note for the in-memory
ledger side of the system. Source code will eventually point back to these
paragraph numbers, and ambiguous behaviour is resolved by what this
document says.
Stage 1 covers §1..§11: domain model, pipeline structure, sequencer,
transactor (single-writer rule, dedup integration, zero-sum, rollback),
deduplication and active window, WASM runtime, snapshotter and read-side
indexes, queues and wait strategies, wait levels, ledger-side config knobs,
and tx-id/recovery posture. Storage-side details and the cluster surface
(gRPC/client) are deferred to later stages.
Replace the placeholder docs/04-internals.md (deleted) with docs/internal.md;
update SUMMARY.md and the stale internals pointer in 03-architecture.md.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Remove fragile source-code anchors from docs/internal.md
Source-file and line-number references in invariant docs are fragile and
add ongoing maintenance cost — they break on every refactor and rename.
Strip every [src/...] and [docs/...] anchor; keep stable [ADR-NNNN]
citations since ADR numbers do not move.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Expand docs/internal.md: WAL, Seal, Snapshotter, hot indexes, query path, recovery
Stage 1 was missing the bulk of the in-memory ledger mechanics. Add full
sections covering:
- §7 WAL stage: writer/committer thread split, shared atomics
(last_written_tx_id, last_committed_tx_id, active_segment_sync ArcSwap),
the VecDeque write buffer, the four-step writer per-iteration loop,
the durability forwarding rule (entries reach the Snapshotter only
after fdatasync), pending_records bookkeeping, segment rotation
procedure, committer loop, outbound backpressure, and panic-on-sync
failure policy.
- §8 Snapshotter (apply path): SnapshotMessage variants, the single FIFO
giving read-your-own-writes for free, the per-record apply algorithm
with pending_records gating snapshot_index advance, last_tx_id as
freshness signal, FunctionRegistered handling that loads/unloads the
shared WASM runtime.
- §9 Hot indexes (TransactionIndexer): circle1 direct-mapped tx-slot
table, circle2 entry storage with prev_link account chains,
account_heads, eviction semantics, the power-of-two requirement, and
the sizing rule that ties hot indexes to transaction_count_per_segment.
- §10 Query path: GetTransaction / GetAccountHistory hot resolution,
hot/cold routing on miss, the synchronous callback-channel response
convention, and the non-FIFO query paths (get_balance,
get_transaction_status).
- §11 Seal stage: poll-on-timer loop, per-segment procedure (load, seal,
build_indexes, replay, conditional snapshot), why Seal owns its own
balance vector and function map, snapshot_frequency rule, pre-seal
during recovery, disable_seal for benchmarks.
- §12 Recovery (in-memory orchestration): pre-seal step, snapshot-load
order, sealed/active replay sequence, dedup-window seeding,
failed-transaction replay, no-partial-recovery principle.
The configuration section now lists transaction_count_per_segment,
snapshot_frequency, seal_check_internal, and disable_seal explicitly
(previously they were deferred). gRPC remains deferred to Stage 3.
The previous §7 (Snapshotter) is now §8; §8/§9/§10/§11 (queues, wait
levels, config, tx-id) are now §13/§14/§15/§16.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Strip implementation-detail noise from docs/internal.md
The doc is meant to be a grand reference for understanding the system,
not a re-statement of what the code says. Drop:
- Specific Rust type spellings (Arc<...>, Rc<RefCell<...>>, AtomicI64,
AtomicU64, CachePadded, ArcSwap, RwLock, HashMap, VecDeque,
FxHashMap, SkipMap, TypedFunc, Box<dyn ...>, etc.) where the concept
matters and the type doesn't.
- Atomic memory orderings (Acquire/Release/Relaxed, fetch_add, etc.)
where they don't carry an invariant.
- Pointless initial values ("sequencer_index initialises to 1 not 0",
"last_sequenced_id == sequencer_index − 1") — noise.
- Exact tuning numbers (yield every 10 000 retries, ~32 spins / ~16K
yields / 1ms park, VecDeque sized to input_capacity * 16) where the
shape matters more than the constant.
- crossbeam::ArrayQueue → "single-producer single-consumer queue".
- Specific function-name spellings in step lists (segment.load(),
segment.seal(), Seal::recover_pre_seal, ctx.set_processed_index)
where the action is what the reader needs.
Net: 1438 lines (down from 1498) with the same coverage, less code-grep
in prose.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Cross-checked the user-facing docs against the source and fixed the places where they disagreed with the code: - 01-concepts.md: reverse the natural-language credit/debit prose so it matches the engine convention (`debit` adds, `credit` subtracts in TransactorState/host API). Replace `submit_wait(transactor|wal| snapshot)` placeholders with the real `WaitLevel::Computed/Committed/ OnSnapshot` names. Drop the false "configurable max batch buffer size" claim — there is no such config field — and describe the Writer/Committer split instead. Note the `from == to` Transfer no-op. - 02-api.md: rename every `WaitLevel::Snapshotted` to `OnSnapshot` (the actual enum variant). Restate the dedup window as N to 2N to match the flip-flop cache in `dedup.rs`. - 03-architecture.md: segment-lifecycle table uses `wal_NNNNNN.bin` (matches `storage/layout.rs`), not the imaginary `segment_NNN.wal`. Backpressure paragraph references `wait_strategy` (the real config field) instead of the non-existent `pipeline_mode`. - introduction.md: Level-4 row points at the existing `wasm-runtime.md` instead of the missing `05-contributing.md`. Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.