Authors: @Thomas Lavaur

• Status tracker

Reviewers

• Draft
• Verified

Change log

Motivation

The current Mantle Specification (v1.4) has accumulated several areas of unnecessary complexity and inconsistency that hinder readability, maintainability and implementation correctness:

1. Duplicated Ledger logic: every Operation that consumes or creates notes (actually TRANSFER, CHANNEL_DEPOSIT, CHANNEL_WITHDRAW and LEADER_CLAIM) independently re-implement the same validation and execution steps to check that inputs are unspent and unlocked, validating output note format, removing consumed notes from the Ledger and inserting new notes. This duplication increases the possibility of implementation and comprehension error.
2. Unnecessary ZkHash in the Mantle Transaction hash: the mantle_tx_hash function currently computes a classical Blake2b Hash digest and then wraps it in a Poseidon2 ZkHash. This second hashing step is unnecessary and increase complexity, attack surface and reduce the efficiency of deriving the hash. The Mantle Transaction hash is not only consumed inside ZK circuits as a public input but it’s also used to build the block_root in headers. ZK circuits use the Mantle Transaction hash as a signature scheme and a simple modular reduction of the Hash to a field element suffices to achieve the same (exactly as is already done for op_id in the derive_note_id function). Removing the ZkHash step simplifies implementation, increase the efficiency which makes bootstrapping faster and removes an extra Poseidon2 evaluation that may be cryptographically more vulnerable than Blake2b.
3. Embedded gas prices in Mantle Transaction: the current design embeds permanent_storage_gas_price and execution_gas_price inside each Mantle Transaction. In practice the permanent_storage_gas_price is fixed per epoch and is the same for every transaction. The execution_gas_price is composed of a protocol-determined base fee (identical for every transaction in a block) plus a priority tip. Encoding these prices inside the transaction is redundant, inflates transaction size which increase its price. This offers better UX where users don’t have to correctly guess the storage price during epoch transitions.

Proposal

We propose four complementary changes:

1. Refactor the Ledger code into a dedicated Section. We introduce common helper functions for note consumption and creation that are reused by every Operation. This eliminates code duplication and guarantees uniform validation across TRANSFER, CHANNEL_DEPOSIT, CHANNEL_WITHDRAW and LEADER_CLAIM.
2. Simplify mantle_tx_hash to only a classical Blake2b Hash instead of returning a ZkHash. ZK circuits that consumes transaction hash as a public input will instead consume the modular reduction modulo $p$, identical to the treatment of op_id in derive_note_id.
3. Remove gas prices from Mantle Transaction. The permanent_storage_gas_price becomes a protocol parameter fixed per epoch. The execution gas is split into a base fee (protocol-determined, same for all transactions in a block) and a tip (the leftover balance after mandatory fees). The balance validation of a Mantle Transaction checks that the balance covers at least the mandatory fees. Any excess is treated as the execution tip.

Discussion

Ledger Refactoring

The duplicated note validation and ledger manipulation across four Operations is the primary source of specification drift risk. By extracting these into shared functions, reviewers need only audit one code path for correctness. Future Operations that consume or creates notes automatically inherit the same checks.