docs: gas calculator

[tac0turtle]

Overview

[github-actions]

The latest Buf updates on your PR. Results from workflow CI and Release / buf-check (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	⏩ skipped	✅ passed	✅ passed	Oct 30, 2025, 1:07 PM

[claude]

Claude finished @tac0turtle's task —— View job

---

Code Review Complete ✓

Tasks

• Read all changed files
• Review Vue component (CelestiaGasEstimator.vue)
• Review documentation (celestia-gas-calculator.md)
• Review Go test changes (serialization_test.go)
• Review VitePress config changes
• Address julienrbrt's review comment
• Provide comprehensive feedback

---

Summary

This PR adds comprehensive documentation and tooling for estimating Celestia DA costs. Overall, this is a well-implemented feature with good separation of concerns. The Vue component is robust and well-structured, the documentation is clear, and the integration is clean. Below are detailed findings organized by category.

---

🟢 Strengths

1. Excellent component architecture: The Vue component follows Vue 3 Composition API best practices with computed properties, reactive state, and proper separation of concerns.

2. Comprehensive calculations: Gas estimation logic accurately mirrors Celestia's DefaultEstimateGas with proper handling of blob chunking (500 KiB limit).

3. User-friendly UI: Interactive donut chart, transaction mix customization, and real-time calculations provide excellent UX.

4. Thorough documentation: Clear explanation of each section with proper warnings about estimation accuracy.

5. Proper test coverage: TestHeaderSerializationSize ensures the hardcoded HEADER_BYTES = 175 constant stays in sync with actual serialization.

---

🟡 Code Quality & Architecture

CelestiaGasEstimator.vue (1365 lines)

Positive findings:

• Clean reactive state management with proper computed properties
• Input sanitization (sanitizeNumber, sanitizeInteger) prevents invalid values
• Proper handling of edge cases (division by zero, NaN checks)
• CSS variables for theming work well with VitePress light/dark modes
• Good use of TypeScript types for data structures

Areas for improvement:

1. Component size (Line 1-1365):

   • At 1365 lines, this component could benefit from decomposition. Consider extracting:
     • Chart visualization into TransactionMixChart.vue
     • Transaction mix controls into TransactionMixEditor.vue
     • Results breakdown into CostEstimationResults.vue
   • This would improve maintainability and testability

2. Magic numbers (Lines 475-486):

   const HEADER_BYTES = 175;
   const FIRST_TX_SURCHARGE = 10_000;
   const SECONDS_PER_MONTH = 30 * 24 * 60 * 60;
   const SECONDS_PER_YEAR = 365 * 24 * 60 * 60;
   const DATA_CHUNK_BYTES = 500 * 1024;
   
   const GAS_PARAMS = Object.freeze({
       fixedCost: 65_000,
       gasPerBlobByte: 8,
       perBlobStaticGas: 0,
       shareSizeBytes: 482,
   });

   • ✅ Good use of Object.freeze for GAS_PARAMS
   • ✅ Constants are well-named and commented
   • ⚠️ Consider adding JSDoc comments explaining the source of these values (e.g., link to Celestia docs/code)

3. EVM transaction type data (Lines 504-565):

   const EVM_TX_TYPES: EvmTxType[] = [...]

   • These calldata sizes (68, 100, 164, 196, 228 bytes) should include a comment explaining the calculation
   • Example: Are these including function selector (4 bytes) + encoded parameters?
   • Consider adding a reference or calculation formula

4. Data chunking logic (Lines 768-784):

   const dataChunks = computed(() => {
       // ...
       while (remaining > 0) {
           const bytes = Math.min(DATA_CHUNK_BYTES, remaining);
           const shares = Math.max(1, Math.ceil(bytes / shareSize));
           const gas = shares * shareSize * gasPerByte;
           chunks.push({ bytes, shares, gas });
           remaining -= bytes;
       }
       return chunks;
   });

   • ✅ Correctly handles blob chunking
   • ✅ Matches the 500 KiB limit referenced in the docs
   • 💡 Consider adding a test case comment showing example: "500 KiB = 512,000 bytes"

5. Input validation (Lines 592-617):

   const headerCountInput = computed({
       get: () => headerCount.value,
       set: (value: number) => {
           const sanitized = sanitizeInteger(value, 1);
           headerCount.value = sanitized;
       },
   });

   • ✅ Good pattern for sanitizing inputs
   • ⚠️ Consider adding user feedback when values are clamped/sanitized (e.g., a warning message)

---

🟡 Security

Low risk findings:

1. No input injection risks: All user inputs are numeric and properly sanitized
2. No external API calls: All calculations are client-side
3. No sensitive data handling: No authentication, API keys, or user data storage

Recommendations:

• ✅ Current implementation is secure for its use case
• 💡 If future updates add external API calls for live parameter fetching (mentioned in docs line 255), ensure proper input validation and HTTPS

---

🟡 Performance & Resource Efficiency

Findings:

1. Computed properties (Lines 619-881):

   • ✅ Excellent use of Vue's computed properties for reactive calculations
   • ✅ Calculations are only re-run when dependencies change
   • ✅ No performance concerns for the complexity involved

2. SVG chart rendering (Lines 128-146):

   <circle
       v-for="segment in mixSegments"
       :key="segment.id"
       class="mix-visual__segment"
       cx="18" cy="18" r="15.9155"
       :stroke="segment.color"
       :stroke-dasharray="segment.dashArray"
       :stroke-dashoffset="segment.dashOffset"
   />

   • ✅ Efficient SVG-based donut chart
   • ✅ No canvas or heavy rendering libraries needed

3. CSS scoped styles (Lines 938-1365):

   • ✅ All styles are scoped to component
   • ✅ Responsive grid layouts with proper breakpoints
   • ✅ Good use of CSS custom properties for theming

---

🟡 Testing & Reliability

types/serialization_test.go (Lines 398-429)

Positive findings:

• ✅ TestHeaderSerializationSize is an excellent guard against unintentional protocol changes
• ✅ Test is clear and has a descriptive comment explaining why it exists
• ✅ Proper use of t.Parallel() for test isolation

Addressing julienrbrt's review comment:

julienrbrt suggested adding a comment linking this test to the default CelestiaGasEstimator values. This is a critical suggestion because:

// types/serialization_test.go:427
assert.Equal(t, len(blob), 175, "Serialized header size has changed")

This 175 value directly corresponds to:

// CelestiaGasEstimator.vue:475
const HEADER_BYTES = 175;

Recommendation:
Add a comment in serialization_test.go (around line 401) like:

// TestHeaderSerializationSize verifies the serialized size of a header remains constant.
// If this test fails, it means the size of the header has changed, which may impact
// network bandwidth, storage requirements, and protocol compatibility. Review the changes
// carefully and update the expected size if the change is intentional.
//
// IMPORTANT: This value is also used in the Celestia Gas Calculator documentation tool.
// If you update this value, also update HEADER_BYTES in:
// docs/.vitepress/components/CelestiaGasEstimator.vue (line 475)
func TestHeaderSerializationSize(t *testing.T) {

---

🟡 Documentation & Developer Experience

celestia-gas-calculator.md

Positive findings:

• ✅ Clear structure with numbered sections
• ✅ Proper warnings about estimation accuracy (line 11)
• ✅ Good explanation of how the calculator works
• ✅ Future features are documented (Cosmos SDK mode, live parameter fetching)

Suggestions:

1. Add mathematical formulas (Section 4, line 44):

   • Consider adding the actual gas calculation formula:

   ### Gas Calculation Formula
   
   For each submission:

   Total Gas = Fixed Gas + Header Gas + Data Gas

   Where:

   • Fixed Gas = (Header Transactions + Data Blob Count) × 65,000
   • Header Gas = Header Shares × Share Size × Gas Per Byte
   • Data Gas = Data Shares × Share Size × Gas Per Byte

2. Link to Celestia documentation (Line 33):

   • Add reference link to Celestia's official gas parameters documentation

3. Example scenario (Optional):

   • Add a worked example showing a complete calculation for a typical rollup

---

🟢 Configuration Changes

docs/.vitepress/config.ts (Lines 319-322)

{
    text: "Celestia Gas Calculator",
    link: "/guides/celestia-gas-calculator",
},

• ✅ Properly added to sidebar navigation
• ✅ Correct section (How To Guides)

docs/.vitepress/theme/index.ts (Line 7, 18)

import CelestiaGasEstimator from '../components/CelestiaGasEstimator.vue'
// ...
app.component('CelestiaGasEstimator', CelestiaGasEstimator)

• ✅ Component properly registered globally
• ✅ Follows VitePress component registration pattern

docs/.vitepress/theme/style.css (Lines 167-170)

.gas-calculator .VPDoc .container,
.gas-calculator .VPDoc .content-container {
    max-width: 100% !important;
}

• ✅ Allows the calculator to use full width
• ✅ Only applies to pages with pageClass: gas-calculator
• ⚠️ Using !important is necessary here but document why (overriding VitePress defaults)

---

🔴 Critical Issues

None found. This is production-ready code.

---

📋 Action Items

High Priority

1. Add cross-reference comment in serialization_test.go (addresses julienrbrt's review)
   • Link the test to the Vue component's HEADER_BYTES constant
   • Ensures future maintainers update both values together

Medium Priority

2. Add JSDoc comments to magic numbers in CelestiaGasEstimator.vue

   • Document the source of HEADER_BYTES = 175
   • Document the source of gas parameters (link to Celestia docs)
   • Document EVM transaction calldata size calculations

3. Add formula section to documentation

   • Include the gas calculation formula
   • Link to official Celestia documentation

Low Priority (Future Enhancements)

4. Consider component decomposition for CelestiaGasEstimator.vue

   • Extract chart, editor, and results into separate components
   • Improves testability and maintainability

5. Add user feedback for sanitized inputs

   • Show a subtle warning when input values are clamped
   • Improves UX transparency

---

🎯 Conclusion

This is an excellent addition to the documentation. The implementation is solid, calculations are accurate, and the UX is intuitive. The main action item is addressing julienrbrt's comment about cross-referencing the test with the Vue component constant.

Recommendation: Approve with minor comment addition (addressing julienrbrt's feedback).

Great work on this comprehensive gas estimation tool! 🚀

[github-actions]

PR Preview Action v1.6.2
Preview removed because the pull request was closed.
2025-10-31 11:45 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.40%. Comparing base (da374bf) to head (e960ded).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2791      +/-   ##
==========================================
+ Coverage   62.24%   62.40%   +0.15%     
==========================================
  Files          82       82              
  Lines        7221     7273      +52     
==========================================
+ Hits         4495     4539      +44     
- Misses       2186     2189       +3     
- Partials      540      545       +5     

Flag	Coverage Δ
combined	62.40% <ø> (+0.15%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[julienrbrt]

nice!!

[julienrbrt]

Maybe we should add a comment, saying when this test fails, update the default CelestiGasEstimator as well: https://github.com/evstack/ev-node/pull/2791/files#diff-bf9b5e4d4b451dab229349bc1252812c0a07fa43bd5e4b9d62db53779c6dbaa7R475