Skip to content

feat(fees): tip within a proven fee - #1125

Merged
erhant merged 5 commits into
devfrom
erhant/proven-fee-tips
Nov 18, 2026
Merged

erhant merged 5 commits into
devfrom
erhant/proven-fee-tips

Conversation

@erhant

@erhant erhant commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

🎯 Purpose

A privacy-preserving transaction that pays its fee inside the proof (the proof credits a reserve to the fee inbox) has no explicit tip today. FeeTxView::tip() returns 0 for these transactions. The only tip they pay is implicit: any surplus that is dust, or that can't be refunded, is kept as tip at settlement. The sequencer can't know that surplus before execution, so it can't rank these transactions by tip.

This PR adds an explicit tip to the in-proof fee. The proof commits to it, so it can't be changed after proving. Once this lands, the tip-per-gas mempool ordering from #880 ranks in-proof private transactions too, without further changes. This PR doesn't depend on #880; either can merge first.

⚙️ Approach

  • Circuit I/O: FeeTransfer (prover input) and ProvenFee (committed output) each gain tip: Fee. The circuit copies the tip into the output. The fee transfer itself is unchanged.
  • Fee view: FeeTxView::Private gains tip, and tip() returns it. Classify reads it from proven_fee, or 0 when the proof commits no fee.
  • Static validity: validate_static_tx now requires reserve ≥ flat fee + tip for private transactions. Sequencer admission (screen) already calls it, so the head-state check (PrivateFeeBelowHead) covers the tip.
  • Settlement (settle_private_transaction):
    • the cycle budget is priced from reserve − tip;
    • the reserve must cover actual + tip, otherwise PrivateFeeBelowRequired;
    • the tip goes to revenue_tip and to the receipt;
    • the surplus beyond actual + tip follows the existing rules: it is refunded if it is above MIN_PRIVATE_REFUND and refundable, and otherwise added to the tip.

The fee fallback goes through the same settlement path, so it pays the tip too.

  • FFI: FfiProvenFee (core_ffi, ffi_types, indexer_ffi) and the wallet's FfiPrivateFee each gain tip. Both headers are updated.
  • Indexer protocol: ProvenFee carries the tip in both conversion directions.
  • Explorer: a new "Proven Fee Tip" row on the transaction details page.
  • Wallet: the existing --tip / FeeParams.tip now applies to in-proof fees as well: reserve pricing adds it, the proof commits it, and the dry-run report shows it.
  • Artifacts: rebuilt, and devnet configs regenerated, because the circuit's image ID changed.

🧪 How to Test

RISC0_DEV_MODE=1 cargo test -p chain_state -p fee_core -p core_ffi -p ffi_types -p indexer_service_protocol
RISC0_DEV_MODE=1 cargo test -p sequencer_core --all-features

New and updated tests:

  • a_private_transaction_pays_its_proven_tip_before_the_refund (chain_state): the tip is paid to the producer, the surplus beyond fee + tip is refunded, and a reserve one short of fee + tip is rejected.
  • private_view_needs_its_verification_storage_and_tip_in_reserve (fee_core): the static check accounts for the tip.
  • The classify test checks that a committed tip appears in the view. The FFI and indexer round-trip tests use a nonzero tip.

From the wallet, --tip N on a private send now shows tip N in the dry-run report's reserve line.

🔗 Dependencies

None, although this PR is independent of yet related to #880.

🔜 Future Work

  • Repricing after PrivateFeeBelowHead keeps the user's tip fixed and only follows base fees. Raising the tip automatically was left out on purpose.

📋 PR Completion Checklist

  • Complete PR description
  • Implement the core functionality
  • Add/update tests
  • Add/update documentation and inline comments

@erhant erhant self-assigned this Nov 13, 2026
@erhant
erhant marked this pull request as ready for review November 16, 2026 16:10
@erhant
erhant force-pushed the erhant/proven-fee-tips branch from 26eb45f to 74268b5 Compare November 16, 2026 16:32
@github-actions

Copy link
Copy Markdown

Suggested reviewers

These code owners were requested because this pull request touches areas they know best (see CODEOWNERS). Each is asked to focus on the files listed under their name.

Reviewer Why Files
agureev Integration tests, LEE privacy-preserving circuit, LEE state machine, Indexer, Built-in programs 9
jonesmarvin8 LEE privacy-preserving circuit, LEE state machine 5
moudyellaz LEE privacy-preserving circuit, LEE state machine, Indexer, Wallet 10
schouhy LEE privacy-preserving circuit, LEE state machine, Chain state and storage, Local deployment and devnet configs, Indexer, Wallet, Test fixtures 15
arjentix Local deployment and devnet configs, Indexer, Wallet, Test fixtures 8
Pravdyvy FFI bindings, Indexer, Wallet, Test fixtures 14

agureev

Integration tests (/integration_tests/tests/async_payouts.rs)

LEE privacy-preserving circuit (/lee/privacy_preserving_circuit/)

LEE state machine (/lee/state_machine/)

Indexer (/lez/explorer_service/)

Built-in programs (/lez/programs/fee/)

jonesmarvin8

LEE privacy-preserving circuit (/lee/privacy_preserving_circuit/)

LEE state machine (/lee/state_machine/)

moudyellaz

LEE privacy-preserving circuit (/lee/privacy_preserving_circuit/)

LEE state machine (/lee/state_machine/)

Indexer (/lez/indexer/)

Wallet (/lez/wallet/)

schouhy

LEE privacy-preserving circuit (/lee/privacy_preserving_circuit/)

LEE state machine (/lee/state_machine/)

Chain state and storage (/lez/chain_state/)

Local deployment and devnet configs (/lez/configs/)

Indexer (/lez/explorer_service/)

Wallet (/lez/wallet/)

Test fixtures (/test_fixtures/)

arjentix

Local deployment and devnet configs (/lez/configs/)

Indexer (/lez/explorer_service/)

Wallet (/lez/wallet/)

Test fixtures (/test_fixtures/)

Pravdyvy

FFI bindings (/lez/core_ffi/, /lez/ffi_types/, /lez/indexer/ffi/)

6 files

Indexer (/lez/indexer/)

Wallet (/lez/wallet/)

Test fixtures (/test_fixtures/)

Files without another code owner (2)

@erhant
erhant force-pushed the erhant/proven-fee-tips branch from f585a63 to f35cc3f Compare November 17, 2026 19:41
Comment thread lez/chain_state/src/apply.rs Resolved

@jonesmarvin8 jonesmarvin8 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

lgtm, left a minor nit.

@erhant
erhant force-pushed the erhant/proven-fee-tips branch from 0826aa6 to 660186e Compare November 18, 2026 19:39
@erhant
erhant merged commit dcbd318 into dev Nov 18, 2026
83 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants