Skip to content

docs(l1): tradeoffs of transactional RocksDB modes #4744

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 6, 2025
Merged

docs(l1): tradeoffs of transactional RocksDB modes #4744

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/internal/l1/transactions_tradeoffs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Tradeoffs of using or not Optimistic Transaction DB in RocksDB
Copy link
Preview

Copilot AI Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Heading is grammatically awkward; consider rephrasing for clarity.

Suggested change
# Tradeoffs of using or not Optimistic Transaction DB in RocksDB
# Tradeoffs of Using Optimistic Transaction DB Versus Not Using It in RocksDB

Copilot uses AI. Check for mistakes.


## Advantages of Optimistic Transactions
- Easier to keep consistency between multiple writers.
- Easier to keep consistency with readers.

## Advantages of Pessimistic Transactions
- Lower memory usage?
Copy link
Preview

Copilot AI Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The trailing question mark signals uncertainty. Either provide data/supporting rationale or remove the entry until confirmed.

Suggested change
- Lower memory usage?
- Lower memory usage (confirm).

Copilot uses AI. Check for mistakes.

- No conflict resolution.

## Advantages of Non-Transactional DB
- `delete_range`: much faster key deletion in bulk, useful during healing.
- Lower memory usage (confirm).
Copy link
Preview

Copilot AI Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The '(confirm)' note indicates an unverified claim; replace with concrete information or remove pending validation.

Suggested change
- Lower memory usage (confirm).
- Lower memory usage.

Copilot uses AI. Check for mistakes.

- Secondary instances are either much easier or possible.
Copy link
Preview

Copilot AI Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sentence is ambiguous ('either much easier or possible'). Clarify whether non-transactional mode enables secondary instances at all, or simply reduces complexity.

Suggested change
- Secondary instances are either much easier or possible.
- Secondary instances are only possible in non-transactional mode.

Copilot uses AI. Check for mistakes.


## Alternatives to DB Transactions
- We can use snapshots/secondary instances to provide a consistent view to block production and protocols.
- We can provide crash safety by adding checkpoints or explicit markers so we can go back to the last known consistent version.
- We would need to run a healing pass from that point on startup, to fix possible partial changes to tries.
- We would need to add explicit tests for crashing during writes to make sure we recover correctly.
Comment on lines +12 to +20
Copy link
Preview

Copilot AI Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] Consider explicitly listing required additional mechanisms (healing pass, crash tests, checkpoints) as 'Operational Requirements' to distinguish them from 'Advantages'; current mix may confuse readers about what is a benefit vs. a cost.

Suggested change
- `delete_range`: much faster key deletion in bulk, useful during healing.
- Lower memory usage (confirm).
- Secondary instances are either much easier or possible.
## Alternatives to DB Transactions
- We can use snapshots/secondary instances to provide a consistent view to block production and protocols.
- We can provide crash safety by adding checkpoints or explicit markers so we can go back to the last known consistent version.
- We would need to run a healing pass from that point on startup, to fix possible partial changes to tries.
- We would need to add explicit tests for crashing during writes to make sure we recover correctly.
- Lower memory usage (confirm).
- Secondary instances are either much easier or possible.
## Operational Requirements for Non-Transactional DB
- Healing pass: On startup, a healing pass must be run from the last checkpoint to fix possible partial changes to tries.
- Crash safety: Explicit tests for crashing during writes are needed to ensure correct recovery.
- Checkpoints: Crash safety can be provided by adding checkpoints or explicit markers to allow rollback to the last known consistent version.
- `delete_range`: Used for much faster key deletion in bulk, which is especially useful during the healing process.
## Alternatives to DB Transactions
- We can use snapshots/secondary instances to provide a consistent view to block production and protocols.

Copilot uses AI. Check for mistakes.

Comment on lines +17 to +20
Copy link
Preview

Copilot AI Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] Consider explicitly listing required additional mechanisms (healing pass, crash tests, checkpoints) as 'Operational Requirements' to distinguish them from 'Advantages'; current mix may confuse readers about what is a benefit vs. a cost.

Suggested change
- We can use snapshots/secondary instances to provide a consistent view to block production and protocols.
- We can provide crash safety by adding checkpoints or explicit markers so we can go back to the last known consistent version.
- We would need to run a healing pass from that point on startup, to fix possible partial changes to tries.
- We would need to add explicit tests for crashing during writes to make sure we recover correctly.
- We can use snapshots/secondary instances to provide a consistent view to block production and protocols.
## Operational Requirements for Non-Transactional DB
- We can provide crash safety by adding checkpoints or explicit markers so we can go back to the last known consistent version.
- We would need to run a healing pass from that point on startup, to fix possible partial changes to tries.
- We would need to add explicit tests for crashing during writes to make sure we recover correctly.

Copilot uses AI. Check for mistakes.

- L2 can't recover from peers (at least until Based), so it should probably remain transactional.
Copy link
Preview

Copilot AI Oct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Term 'Based' is unexplained; add a brief definition or link so readers understand the dependency or future milestone.

Suggested change
- L2 can't recover from peers (at least until Based), so it should probably remain transactional.
- L2 can't recover from peers (at least until Based[^based]), so it should probably remain transactional.

Copilot uses AI. Check for mistakes.

Loading