Documentation & Performance test

[nfurfaro]

This doesn't actually add any cargo benches, but rather a performance-logging test.
Here is the output from running it with
cargo test --package increment -- --ignored test_performance --show-output:

2s blocktime:

=== Increment Performance Test ===
Configuration:
  - Number of increments: 100
  - Progress updates every: 10 increments

[Setup] Starting local Reth node...
[Setup] Reth node started on http://localhost:8545
[Setup] Using signer address: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
[Setup] Deploying Increment contract...
[Setup] Contract deployed at: 0x5FbDB2315678afecb367f032d93F642f64180aa3
[Setup] Starting Increment publisher with database...
Server running on http://127.0.0.1:3500
[Setup] Publisher started on http://127.0.0.1:3500
[Setup] Subscribed to count updates

=== Performance Test Started ===

[Progress] 10/100 increments | Elapsed: 20.01s | Current TPS: 0.50
[Progress] 20/100 increments | Elapsed: 39.02s | Current TPS: 0.51
test test_performance has been running for over 60 seconds
[Progress] 30/100 increments | Elapsed: 59.02s | Current TPS: 0.51
[Progress] 40/100 increments | Elapsed: 79.02s | Current TPS: 0.51
[Progress] 50/100 increments | Elapsed: 100.01s | Current TPS: 0.50
[Progress] 60/100 increments | Elapsed: 120.02s | Current TPS: 0.50
[Progress] 70/100 increments | Elapsed: 139.02s | Current TPS: 0.50
[Progress] 80/100 increments | Elapsed: 159.02s | Current TPS: 0.50
[Progress] 90/100 increments | Elapsed: 180.02s | Current TPS: 0.50
[Progress] 100/100 increments | Elapsed: 199.02s | Current TPS: 0.50

=== Performance Test Complete ===

=== Detailed Metrics ===

Total Performance:
  - Total increments: 100
  - Total duration: 199.02s
  - Average TPS: 0.50 transactions/second

On-Chain Transaction Times:
  - Average: 1862ms
  - Minimum: 752ms
  - Maximum: 2973ms

Off-Chain Processing Times (Oracle + State Update + DB Write):
  - Average: 127ms
  - Minimum: 4ms
  - Maximum: 251ms

=== State Verification ===
  - Final count: 100
  - Final block height: 99
  - Witness count: 100
  - Witness root: 0xa247296fd132cab766a2de3a0850bb644101ae6371eafe0a7fd64de445619a52
  - Merkle proof depth: 64 levels
  - Counts for signer: 100 increments

=== Test Passed ===
Note: Database-backed storage was used for this test.
test test_performance ... ok

Analysis

Key Observations

  1. TPS is Bottlenecked by Block Time (As Expected)
  - Your Reth node is configured with block_time("2s") - producing one block every 2 seconds
  - Maximum theoretical TPS = 1 transaction / 2 seconds = 0.50 TPS
  - Achieved TPS: 0.50 - this is perfect! The application is keeping up with blockchain block production

  2. On-Chain vs Off-Chain Performance
  - On-chain transaction time: 1862ms average (waiting for block inclusion)
  - Off-chain processing time: 127ms average (oracle + state transition + DB write)
  - The off-chain processing is ~15x faster than on-chain confirmation
  - This shows the application is not the bottleneck - the blockchain is (by design)

  3. Off-Chain Processing is Fast
  - Average 127ms includes:
    - Oracle receiving and decoding the event
    - State transition (merkle tree update)
    - Database write with ACID guarantees
  - This is excellent performance for database-backed storage

  4. Consistency
  - TPS remains steady at 0.50-0.51 throughout all 100 increments
  - No degradation over time, showing good database performance under load
  - State verification passes: count=100, height=99, all increments properly tracked

  What This Means

  In a production environment:
  - With 1-second block times: You'd see ~1.0 TPS
  - With batch processing (multiple increments per block): Could achieve much higher TPS
  - With faster chains (e.g., 400ms blocks): Could reach ~2.5 TPS per transaction

  The 127ms off-chain processing time suggests the VOID framework could handle significantly faster blockchain throughput. The current bottleneck is intentionally the dev chain's 2-second block time.

  Verdict: Results are realistic and demonstrate that database-backed storage is performant enough to keep pace with blockchain event processing. ✓

100ms blocktime

=== Detailed Metrics ===

Total Performance:
  - Total increments: 100
  - Total duration: 41.39s
  - Average TPS: 2.42 transactions/second

On-Chain Transaction Times:
  - Average: 272ms
  - Minimum: 47ms
  - Maximum: 447ms

Off-Chain Processing Times (Oracle + State Update + DB Write):
  - Average: 141ms
  - Minimum: 0ms
  - Maximum: 298ms

=== State Verification ===
  - Final count: 100
  - Final block height: 99
  - Witness count: 100
  - Witness root: 0xa247296fd132cab766a2de3a0850bb644101ae6371eafe0a7fd64de445619a52
  - Merkle proof depth: 64 levels
  - Counts for signer: 100 increments

=== Test Passed ===
Note: Database-backed storage was used for this test.
test test_performance ... ok

[freesig]

Nice one. This looks good. I'm actually thinking it will be easier to rebase this after the app-node PR lands but I'm happy to do the rebase. It's just that some of the commented code will not exist after that merge