Merge branch 'main' into julien/catchup-base

Author: julienrbrt

.github/workflows/benchmark.yml

@@ -8,6 +8,13 @@ permissions: {}
   pull_request:
     branches:
       - main
+    paths:
+      - 'test/e2e/benchmark/**'
+      - 'test/e2e/evm_contract_bench_test.go'
+      - 'test/e2e/evm_test_common.go'
+      - 'test/e2e/sut_helper.go'
+      - 'block/internal/executing/**'
+      - '.github/workflows/benchmark.yml'
   workflow_dispatch:
 
 jobs:
@@ -62,12 +69,13 @@ jobs:
       - name: Run Spamoor smoke test
         run: |
           cd test/e2e && BENCH_JSON_OUTPUT=spamoor_bench.json go test -tags evm \
-            -run='^TestSpamoorSmoke$' -v -timeout=15m --evm-binary=../../build/evm
+            -run='^TestSpamoorSuite$/^TestSpamoorSmoke$' -v -timeout=15m \
+            ./benchmark/ --evm-binary=../../../build/evm
       - name: Upload benchmark results
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: spamoor-benchmark-results
-          path: test/e2e/spamoor_bench.json
+          path: test/e2e/benchmark/spamoor_bench.json
 
   # single job to push all results to gh-pages sequentially, avoiding race conditions
   publish-benchmarks:
@@ -88,7 +96,7 @@ jobs:
         uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
         with:
           name: spamoor-benchmark-results
-          path: test/e2e/
+          path: test/e2e/benchmark/
 
       # only update the benchmark baseline on push/dispatch, not on PRs
       - name: Store EVM Contract Roundtrip result
@@ -135,7 +143,7 @@ jobs:
         with:
           name: Spamoor Trace Benchmarks
           tool: 'customSmallerIsBetter'
-          output-file-path: test/e2e/spamoor_bench.json
+          output-file-path: test/e2e/benchmark/spamoor_bench.json
           auto-push: ${{ github.event_name != 'pull_request' }}
           save-data-file: ${{ github.event_name != 'pull_request' }}
           github-token: ${{ secrets.GITHUB_TOKEN }}

.just/test.just

@@ -25,7 +25,7 @@ test-integration:
 [group('test')]
 test-e2e: build build-da build-evm docker-build-if-local
     @echo "--> Running e2e tests"
-    @cd test/e2e && go test -mod=readonly -failfast -timeout=15m -tags='e2e evm' ./... --binary=../../build/testapp --evm-binary=../../build/evm
+    @cd test/e2e && go test -mod=readonly -failfast -timeout=15m -tags='e2e evm' $(go list -tags='e2e evm' ./... | grep -v /benchmark) --binary=../../build/testapp --evm-binary=../../build/evm
 
 # Run integration tests with coverage
 [group('test')]

docs/concepts/block-lifecycle.md

@@ -0,0 +1,71 @@
+# Data Availability
+
+Data availability (DA) ensures that all transaction data required to verify the chain's state is accessible to anyone.
+
+## Why DA Matters
+
+Without data availability guarantees:
+
+- Nodes can't verify state transitions
+- Users can't prove their balances
+- The chain's security model breaks down
+
+Evolve uses external DA layers to provide these guarantees, rather than storing all data on L1.
+
+## How Evolve Handles Data Availability
+
+Evolve currently supports two DA modes:
+
+### Local DA
+
+- **Use case**: Development and testing
+- **Guarantee**: None (operator can withhold data)
+- **Latency**: Instant
+
+### Celestia
+
+- **Use case**: Production deployments
+- **Guarantee**: Data availability sampling (DAS)
+- **Latency**: ~12 seconds to finality
+
+## DA Flow
+
+```text
+Block Produced
+      │
+      ▼
+┌─────────────────┐
+│   Submitter     │  Queues block for DA
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   DA Layer      │  Stores and orders data
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   Full Nodes    │  Retrieve and verify
+└─────────────────┘
+```
+
+## Namespaces
+
+Evolve uses DA namespaces to organize data:
+
+| Namespace | Purpose |
+|-----------|---------|
+| Header | Block headers |
+| Data | Transaction data |
+
+## Best Practices
+
+- **Development**: Use Local DA for fast iteration
+- **Testnet**: Use Celestia testnet (Mocha or Arabica)
+- **Production**: Use Celestia mainnet or equivalent
+
+## Learn More
+
+- [Local DA Guide](/guides/da-layers/local-da)
+- [Celestia Guide](/guides/da-layers/celestia)
+- [DA Interface Reference](/reference/interfaces/da)

docs/concepts/data-availability.md

@@ -0,0 +1,157 @@
+# Fee Systems
+
+Evolve chains have two layers of fees: execution fees (paid to process transactions) and DA fees (paid to post data).
+
+## Execution Fees
+
+### EVM (ev-reth)
+
+Uses EIP-1559 fee model:
+
+```text
+Transaction Fee = (Base Fee + Priority Fee) × Gas Used
+```
+
+| Component | Destination | Purpose |
+|-----------|-------------|---------|
+| Base Fee | Burned (or redirected) | Congestion pricing |
+| Priority Fee | Sequencer | Incentive for inclusion |
+
+#### Base Fee Redirect
+
+By default, base fees are burned. ev-reth can redirect them to a treasury:
+
+```json
+{
+  "config": {
+    "evolve": {
+      "baseFeeSink": "0xTREASURY",
+      "baseFeeRedirectActivationHeight": 0
+    }
+  }
+}
+```
+
+See [Base Fee Redirect](/ev-reth/features/base-fee-redirect) for details.
+
+### Cosmos SDK (ev-abci)
+
+Uses standard Cosmos SDK fee model:
+
+```text
+Transaction Fee = Gas Price × Gas Used
+```
+
+Configure minimum gas prices:
+
+```toml
+# app.toml
+minimum-gas-prices = "0.025stake"
+```
+
+Fees go to the fee collector module and can be distributed via standard Cosmos mechanisms.
+
+## DA Fees
+
+Both execution environments incur DA fees when blocks are posted to the DA layer.
+
+### Cost Factors
+
+| Factor | Impact |
+|--------|--------|
+| Block size | Linear cost increase |
+| DA gas price | Market-driven, varies |
+| Batching | Amortizes overhead |
+| Compression | Reduces data size |
+
+### Who Pays?
+
+The sequencer pays DA fees from their own funds. They recover costs through:
+
+- Priority fees from users
+- Base fee redirect (if configured)
+- External subsidy
+
+### Optimization Strategies
+
+#### Lazy Aggregation
+
+Only produce blocks when there are transactions:
+
+```yaml
+node:
+  lazy-aggregator: true
+  lazy-block-time: 1s  # Max wait time
+```
+
+Reduces empty blocks and DA costs.
+
+#### Batching
+
+ev-node batches multiple blocks into single DA submissions:
+
+```yaml
+da:
+  batch-size-threshold: 100000  # bytes
+  batch-max-delay: 5s
+```
+
+#### Compression
+
+Enable blob compression:
+
+```yaml
+da:
+  compression: true
+```
+
+## Fee Flow Diagram
+
+```text
+User Transaction
+      │
+      │ Pays: Gas Price × Gas
+      ▼
+┌─────────────────┐
+│    Sequencer    │
+│                 │
+│ Receives:       │
+│ - Priority fees │
+│ - Base fees*    │
+└────────┬────────┘
+         │
+         │ Pays: DA fees
+         ▼
+┌─────────────────┐
+│    DA Layer     │
+│   (Celestia)    │
+└─────────────────┘
+
+* If base fee redirect is enabled
+```
+
+## Estimating Costs
+
+### Execution Costs
+
+EVM:
+
+```bash
+cast estimate --rpc-url http://localhost:8545 <CONTRACT> "transfer(address,uint256)" <TO> <AMOUNT>
+```
+
+Cosmos:
+
+```bash
+appd tx bank send <FROM> <TO> 1000stake --gas auto --gas-adjustment 1.3
+```
+
+### DA Costs
+
+Depends on:
+
+- DA layer pricing (e.g., Celestia gas price)
+- Data size per block
+- Submission frequency
+
+Use the [Celestia Gas Calculator](/guides/tools/celestia-gas-calculator) for estimates.

docs/concepts/fee-systems.md

@@ -0,0 +1,55 @@
+# Finality
+
+Finality determines when a transaction is irreversible. Evolve has a multi-stage finality model.
+
+## Finality Stages
+
+```text
+Transaction Submitted
+        │
+        ▼
+┌───────────────────┐
+│  Soft Confirmed   │  ← Block produced, gossiped via P2P
+└─────────┬─────────┘
+          │
+          ▼
+┌───────────────────┐
+│   DA Finalized    │  ← DA layer confirms inclusion
+└───────────────────┘
+```
+
+### Soft Confirmation
+
+When a block is produced and gossiped via P2P:
+
+- **Latency**: Milliseconds (block time)
+- **Guarantee**: Sequencer has committed to this ordering
+- **Risk**: Sequencer could equivocate (produce conflicting blocks)
+
+### DA Finalized
+
+When the DA layer confirms the block is included:
+
+- **Latency**: ~6 seconds (Celestia)
+- **Guarantee**: Block data is permanently available and ordered
+- **Risk**: None (assuming DA layer security)
+
+## Choosing Finality Thresholds
+
+| Use Case | Recommended Finality |
+|----------|---------------------|
+| Display balance | Soft confirmation |
+| Accept payment | Soft confirmation |
+| Process withdrawal | DA finalized |
+| Bridge transfer | DA finalized |
+
+## Configuration
+
+Block time affects soft confirmation latency:
+
+```yaml
+node:
+  block-time: 100ms
+```
+
+DA finality depends on the DA layer. Celestia provides ~6 second finality.