Protocol-level Gasless EVM Execution (Zero-Gas Actors) | Nibiru EVM

[Unique-Divine]

Protocol-level Gasless EVM Execution (Zero-Gas Actors) | Nibiru EVM

• Date Created: 2026-02-07
• Status: Implemented in feat(evm): extend zero gas functionality to allow for any sender to call certain EVM contracts with zero gas #2517, set to go live in Nibiru v2.11.0.

Conceptual Model

sequenceDiagram
    participant User
    participant Ante as EVM Ante Handler
    participant Exec as MsgServer (Execution)
    participant State as Chain State

    User->>Ante: Submit EthTx (to: Allowlisted)
    Note over Ante: AnteStepDetectZeroGas
    Ante->>Ante: Set ZeroGasMarker in Context
    Note over Ante: Skip: Balance Check & Fee Deduction
    Ante->>State: Create Account (if fresh onboarding)
    Ante-->>Exec: Pass Context with Marker
    Note over Exec: Execute Contract Logic
    Note over Exec: Skip: RefundGas
    Exec->>User: Success (Balance Unchanged)

Loading

---

Why This Document Exists (And Who It Is For)

This document is for future maintainers and other developers on the team (knowledge transfer). It may also serve auditors later. The primary goal is to make the zero-gas EVM feature easy to grasp and to avoid future regressions. It is a living doc: it was used to implement the feature and is intended for ongoing maintenance.

Why Zero-Gas Exists: Instant Onboarding for an Onchain Perps Exchange

The main use case is a perpetual onchain future exchange. Zero-gas execution removes the need for users to obtain gas before using the exchange. Users can rely on collateral (e.g. USDC, stNIBI in ERC20 form) or exchange credits held in contract state and start using the app in seconds—without ever holding the chain’s native gas token.

Table of Contents

• Why This Document Exists (And Who It Is For)
• Why Zero-Gas Exists: Instant Onboarding for an Onchain Perps Exchange
• How This Design Question Arose
• How Gas Normally Works (The Five-Step Flow)
• The Flow: Detect, Mark, Skip
  • The Rules: What Qualifies for Zero Gas
  • What We Still Enforce: Account Safety Comes First
• Where This Fits in the Existing EVM Pipeline
  • Zero-Gas Execution Phases: No Charge, No Refund
  • How Ante Signals Execution
• Design Q&A (Audit and Maintenance Notes)
  • Why Ante State Persists (And Why First-Time Users Need It)
• Code Map: What Lives Where
  • What Runs When: Ante vs Execution Across ABCI Phases
  • Entry Point: EVM vs Non-EVM Routing
  • EVM Ante Step Order (And Where Zero-Gas Is Detected)
• The Bypass Points: What We Skip and Why
  • 1. AnteStepVerifyEthAcc: Skip Balance Checks, Keep Everything Else
  • 2. AnteStepCanTransfer: Structural Validity Still Applies
  • 3. AnteStepDeductGas: Fee Collection Is Fully Skipped
  • 4. AnteStepMempoolGasPrice: CheckTx Bypass Only
• Reference Point: How Non-EVM Zero-Gas Already Works
• Operating Zero-Gas: Governance, Validation, and Shutdown
• Plan: Execution Model, Invariants, and Safety
  • Execution Model: Two Phases, One Marker
  • System Invariants (These Must Always Hold)
  • Edge Cases and Failure Modes
  • Detection Placement and Skip Behavior
  • Execution Handling and Test Coverage
  • Test Coverage: Claims Mapped to Tests
  • Constraints and Where They Are Enforced
  • Known Test Coverage Gaps
  • Files and End-to-End Flow
• Appendix
  • Rejected Design: Credit Then Undo

How This Design Question Arose

(Background and initial question that led to this design. If you are reading this
to maintain or audit the system, start at Design Summary (TL;DR) and
The Rules: What Qualifies for Zero Gas.)

1. Question Posed: Suppose we wanted to implement an EVM ante handler that
   allowed a specific type of transaction to run without requiring a
   balance of gas—what code would that handler be related to? Which checks in the
   current ante stack would be relevant and need some custom bypass?

2. The Answer: An EVM "zero-balance gas" handler would live in the
   EVM ante stack (x/evm/evmante/). The EVM path is completely separate
   from the non-EVM (Cosmos SDK) ante chain. Several existing steps enforce
   gas/balance requirements and would need conditional bypasses for the special
   transaction type.

How Gas Normally Works (The Five-Step Flow)

At a high level, gas payment for an EVM transaction works as follows:

1. Arrival — The transaction shows up.
2. Check — The signer/sender's balance is verified to cover the transaction cost.
3. Deduct — The full upfront cost (gas limit × gas price) is taken from the sender and sent to the fee collector.
4. Execute — The EVM runs the transaction.
5. Refund — Unused gas is refunded: some funds move from the fee collector back to the sender.

So a user's gas balance G ends up in two places:

• A portion goes to the fee collector (the gas actually consumed).
• A portion stays in the sender's wallet (refund of unused gas).

---

The Flow: Detect, Mark, Skip

Zero-gas transactions are handled by detecting eligibility (see The Rules: What Qualifies for Zero Gas) and then skipping cost checks, fee deduction, and refund. No credit, no undo, no stored amounts.

1. Detect — AnteStepDetectZeroGas checks eligibility; if so, it sets a context marker (see Design Q&A (Audit and Maintenance Notes) for marker semantics). No state mutations.
2. Skip in ante — When the marker is set: MempoolGasPrice → skip. VerifyEthAcc → run validation and account creation; skip only balance vs. tx cost (see What We Still Enforce: Account Safety Comes First). CanTransfer → runs always (see The Bypass Points: What We Skip and Why). DeductGas → skip.
3. Skip in msg_server — RefundGas is skipped when the marker is set (see Design Q&A (Audit and Maintenance Notes): "How does ante-to-execution communication work?").

Access: evm.IsZeroGasEthTx(ctx) returns true when the marker is set. Here's a
skip matrix of differences for the tx when evm.IsZeroGasEthTx(ctx) is true.

Stage	Component	Behavior
Ante	MempoolGasPrice	Skip (mempool min gas price bypass)
Ante	VerifyEthAcc	Run validation + account creation; skip only balance-vs-tx-cost
Ante	CanTransfer	Run always (gas cap + value rules; value no-ops since tx.Value == 0)
Ante	DeductGas	Skip (no fee deduction)
Exec	EthereumTx msg_server	Skip RefundGas

The Rules: What Qualifies for Zero Gas

This is the canonical definition of who is eligible and what is not. Other sections link here.

Eligible: A transaction is zero-gas eligible when:

• tx.To is in the governance-controlled list ZeroGasActors.always_zero_gas_contracts (EVM hex addresses on x/sudo),
• tx.Value == 0,
• Any sender (no sender allowlist for EVM zero-gas).

Not eligible:

• Contract creation (to == nil). Only calls to specific contracts are eligible; the detection step returns without setting the marker when to == nil.
• If tx.To is not in the list or tx.Value != 0, the transaction is treated as a normal EVM tx (no marker set).

Marker propagation: The context from ante must reach the msg_server so RefundGas is skipped for zero-gas txs. Multiple tests assert that the marker is set in ante and visible in the msg_server (see Test Coverage: Claims Mapped to Tests and Constraints and Where They Are Enforced).

What We Still Enforce: Account Safety Comes First

Design requirement: We only waive gas payment (balance vs. tx cost and deduction). All other ante behavior—especially account verification—must remain in place.

• First-time onboarding: A user with no prior chain interaction (no account, no gas balance) can submit their first transaction ever as a zero-gas call to an allowlisted contract. That is only possible if we still create the sender account when missing. If VerifyEthAcc were fully skipped, AnteStepIncrementNonce would run against a nil account and fail with "account is nil", blocking onboarding.
• Consistency: From-address validation and the existence of the sender account are required for correct nonce handling and for the rest of the ante chain. Skipping only gas-related checks (balance vs. cost, fee deduction) keeps security and consistency while enabling gasless execution.

Concretely:

• VerifyEthAcc must not be fully skipped. (1) From address must be valid. (2) Sender account must exist so AnteStepIncrementNonce can run. We still run validation and account creation; only the balance-vs-tx-cost check is skipped when zero-gas.
• CanTransfer runs for zero-gas. It enforces structural validity (gas cap, value); value check no-ops when tx.Value == 0. See The Bypass Points: What We Skip and Why injective node code not available #2 for details.

---

Where This Fits in the Existing EVM Pipeline

Zero-Gas Execution Phases: No Charge, No Refund

For zero-gas txs, ante skips deduction and msg_server skips RefundGas. No charge, no refund. For normal txs, the usual flow applies: ante deducts, execution runs, msg_server calls RefundGas.

How Ante Signals Execution

The ante step sets a marker in the SDK context; the msg_server uses evm.IsZeroGasEthTx(ctx) to decide whether to run RefundGas. See Design Q&A (Audit and Maintenance Notes) ("How does ante-to-execution communication work?") for full marker semantics.

---

Design Q&A (Audit and Maintenance Notes)

These are questions I expect might arise while auditing or modifying the design.
If updating rules or bypass logic, make sure to reevaluate The Rules: What Qualifies for Zero Gas and the Skip matrix.)

Why Ante State Persists (And Why First-Time Users Need It)

In the Cosmos SDK baseapp, ante handler state is not isolated from DeliverTx state: both use the same block-level deliver state cache. When the ante handler succeeds, its branch is merged into that cache immediately (before runMsgs). If the transaction later fails during message execution (EVM revert, consensus error), only the message-execution branch is discarded; ante writes remain and are committed at end of block. CometBFT still calls Commit when a DeliverTx returns an error.

For zero-gas fresh user onboarding, this behavior is desirable: a user with no existing account and no NIBI (gas) balance can submit their first transaction as a zero-gas call to an allowlisted contract. The ante handler creates the sender account when missing (in AnteStepVerifyEthAcc). If that transaction then fails in execution (e.g. contract revert), account creation and any other ante setup still persist—the user is effectively onboarded and can retry or submit other transactions. If ante state were rolled back on message failure, first-time users could not get an account from a zero-gas tx that failed during execution.

Q: What makes a transaction eligible for zero-gas execution?
A: See The Rules: What Qualifies for Zero Gas. In short: tx.To in ZeroGasActors.always_zero_gas_contracts, tx.Value == 0, any sender.

Q: Why is there no sender allowlist for EVM zero-gas?
A: This feature adds a new type of zero-gas tx where anyone who calls a specific set of contracts does not need gas. The main use case is a specific onchain (perpetual) exchange; no sender allowlist keeps it simple and open for any user.

Q: Is contract creation (to == nil) eligible?
A: No. Only calls to specific contracts are eligible. Contract creation is not allowlisted; the detection step returns without setting the marker when to == nil.

Q: Why is ZeroGasMeta an empty struct?
A: In Go it has zero size and is uniquely identified by the runtime. The context value under CtxKeyZeroGasMeta acts as a boolean marker; we only need presence, which is how IsZeroGasEthTx(ctx) uses it.

Q: Who pays for gas in a zero-gas transaction?
A: No one. Zero-gas txs are never charged: ante skips the balance-vs-tx-cost check and fee deduction; the msg_server skips RefundGas. Account verification (including account creation when missing) still runs. The sender's balance is unchanged by gas.

Q: Can the sender use funds for anything other than gas in a zero-gas tx?
A: By design, no. Sponsored transactions are expected to have tx.Value == 0, and allowlisted contracts are trusted not to transfer native balance. While it is theoretically possible for a mis-whitelisted contract to move funds, this is treated as a governance or operational error rather than a design flaw.

Q: How does ante-to-execution communication work?
A: The ante step sets a marker (empty ZeroGasMeta under CtxKeyZeroGasMeta) in the SDK context. The context is preserved into the EthereumTx message handler during DeliverTx. The msg_server uses evm.IsZeroGasEthTx(ctx) to decide whether to run RefundGas. No amounts are stored or passed; only the presence of the marker matters.

Q: How does zero-gas interact with other EVM features (devgas, priority tip, gas estimation)?
A: Zero-gas txs pay no gas fees, so there is no priority tip and no devgas distribution for them. Gas estimation (e.g. eth_estimateGas) uses a path that does not run the ante chain and does not set the zero-gas marker; behavior is unchanged and no special handling is needed.

Q: What is the trust model of this system?
A: The chain does not attempt to sandbox or restrict contract behavior at runtime. Safety relies on governance-controlled allowlisting of trusted contracts. Zero-gas execution is a policy surface, not a permissionless mechanism.

---

Code Map: What Lives Where

This section covers the mechanics: where the code lives, how the ante chain
is modified, what is skipped, and which tests enforce each claim.

What Runs When: Ante vs Execution Across ABCI Phases

Ante handler (definition)
The ante handler is the logic we register: what runs and in what order. In Nibiru it is defined in two places:

• Routing: app.NewAnteHandler(...) in app/ante.go returns a single sdk.AnteHandler that chooses either the non-EVM decorator chain or the EVM ante. For EVM txs it calls evmante.NewAnteHandlerEvm(options).
• EVM ante definition: In x/evm/evmante/all_evmante.go, the EVM handler is a single decorator (AnteHandlerEvm) that runs a fixed list of steps (AnteStepSetupCtx, EthSigVerification, AnteStepDetectZeroGas, …, AnteStepDeductGas, etc.). That list is the "ante handler" for EVM: it defines signature checks, zero-gas detection, balance/cost checks, fee deduction, nonce increment, and so on.

So "the ante handler" = the function we pass to app.SetAnteHandler(...) and the step chain inside evmante. It is independent of when the chain is run; it only describes what runs.

ABCI method mapping (when it runs)
The Cosmos SDK baseapp (internal to the SDK) decides when that ante handler runs. It wires ABCI methods to the same ante handler and (for some methods) to message execution:

• CheckTx — Baseapp runs the registered ante handler (with ctx.IsCheckTx() == true). It does not run message execution (runMsgs). So the ante handler is used to accept or reject the tx for the mempool (e.g. mempool min gas price, balance checks).
• DeliverTx — Baseapp runs the same ante handler again (with deliver context), then, if ante succeeds, runs runMsgs (module message handlers). So the EthereumTx msg_server (including RefundGas) runs only in this phase (and in Simulate).
• Simulate — Typically runs with a simulation flag; ante may run with simulate == true; runMsgs is used for execution simulation. Paths like eth_estimateGas may bypass ante and call execution directly.

So: ante runs in both CheckTx and DeliverTx; runMsgs runs only in DeliverTx (and in Simulate). The evmante code uses sdb.Ctx().IsCheckTx() and evmstate.IsDeliverTx(sdb.Ctx()) to branch (e.g. MempoolGasPrice only in CheckTx; sdb.Commit() only in DeliverTx).

Relevance for zero-gas

• The definition of the ante (in evmante) is where zero-gas is detected (AnteStepDetectZeroGas) and where we skip balance-vs-cost, DeductGas, and MempoolGasPrice.
• The mapping (CheckTx + DeliverTx both running ante) is why the zero-gas marker must be set in ante and why it is visible in the msg_server: the same context flows from ante into runMsgs during DeliverTx. RefundGas is skipped in the msg_server (DeliverTx/Simulate only), not in ante; ante never runs RefundGas.

Entry Point: EVM vs Non-EVM Routing

EVM vs non-EVM transactions are routed in app/ante.go:

// app/ante.go, lines 31-36 (approximate)
if !evm.IsEthTx(tx) {
    anteHandler = NewAnteHandlerNonEVM(keepers.PublicKeepers, options)
    return anteHandler(ctx, tx, sim)
}
anteHandler = evmante.NewAnteHandlerEvm(options)
return anteHandler(ctx, tx, sim)

• File: app/ante.go
• Lines: 31–36 (approximate)

EVM Ante Step Order (And Where Zero-Gas Is Detected)

The EVM ante handler is defined in x/evm/evmante/all_evmante.go:

// x/evm/evmante/all_evmante.go (see current order in repo)
steps := []AnteStep{
    AnteStepSetupCtx,                    // outermost
    EthSigVerification,
    AnteStepValidateBasic,
    AnteStepDetectZeroGas,               // ← detect zero-gas tx, set context marker (before steps that skip)
    AnteStepMempoolGasPrice,             // ← mempool min gas price (CheckTx); skips if zero-gas
    AnteStepBlockGasMeter,
    AnteStepVerifyEthAcc,                // ← validation + account creation always; skip only balance vs. cost if zero-gas
    AnteStepCanTransfer,                 // ← gas cap, value transfer; runs always (value no-ops when 0)
    AnteStepGasWanted,
    AnteStepDeductGas,                   // ← deduct fees from sender; skips if zero-gas
    AnteStepIncrementNonce,
    AnteStepEmitPendingEvent,
    AnteStepFiniteGasLimitForABCIDeliverTx,
}

• File: x/evm/evmante/all_evmante.go

---

The Bypass Points: What We Skip and Why

1. AnteStepVerifyEthAcc: Skip Balance Checks, Keep Everything Else

Validates from address, ensures sender account exists (creates if missing), and checks that the sender’s balance covers the full transaction cost (fees + value). For zero-gas, only the balance-vs-cost check is skipped; validation and account creation still run. See What We Still Enforce: Account Safety Comes First.

Location	File	Lines
Ante step	x/evm/evmante/evmante_can_transfer.go	18–76 (approximate)
Core check	x/evm/evmstate/gas_fees.go	97–117 (approximate)

Key logic in evmstate.CheckSenderBalance: cost := txData.Cost(); balanceWei.ToBig().Cmp(cost) < 0 → insufficient funds.

2. AnteStepCanTransfer: Structural Validity Still Applies

Validates: (1) gasFeeCap >= baseFee, (2) if value > 0, balance >= value. Runs always for zero-gas; value check no-ops when tx.Value == 0 (eligibility requirement). No bypass; structural validity is enforced.

Location	File	Lines
Ante step	x/evm/evmante/evmante_can_transfer.go	82–138 (approximate)

Key checks: Gas fee cap vs base fee (lines 110–116 approx.); value transfer vs balance (lines 121–132 approx.). Gas cap check passes because the effective gas fee cap used in the check is at least the block base fee (see EffectiveGasCapWei in EVM tx types).

3. AnteStepDeductGas: Fee Collection Is Fully Skipped

Deducts transaction fees from the sender and sends them to the fee collector. For zero-gas txs, the entire step is skipped before fee computation.

Location	File	Lines
Ante step	x/evm/evmante/evmante_gas_consume.go	99–159 (approximate)
Fee calc	x/evm/evmstate/gas_fees.go	159–212 (VerifyFee; approximate)
Deduction	x/evm/evmstate/gas_fees.go	119–138 (DeductTxCostsFromUserBalance; approximate)

Primary bypass for zero-gas (runs before VerifyFee):

// evmante_gas_consume.go, lines 104-106
if evm.IsZeroGasEthTx(sdb.Ctx()) {
    return nil
}

A secondary path skips deduction when fees.IsZero() (after VerifyFee); zero-gas txs never reach it.

4. AnteStepMempoolGasPrice: CheckTx Bypass Only

Enforces minimum gas price during CheckTx for mempool admission. Skip this step when the tx is identified as zero-gas.

Location	File	Lines
Ante step	x/evm/evmante/evmante_mempool_fees.go	38–75 (approximate)

---

Reference Point: How Non-EVM Zero-Gas Already Works

The non-EVM path has an existing zero-gas pattern for Wasm MsgExecuteContract:

Component	File	Purpose
AnteDecZeroGasActors	app/ante/fixed_gas.go	Sets fixed zero-gas meter for whitelisted sender+contract
DeductFeeDecorator	app/ante/deduct_fee.go	Skips fee deduction when isZeroGasMeter(ctx) is true
ZeroGasActors state	x/sudo/	Governance-managed whitelist (senders + contracts)

• app/ante/fixed_gas.go, lines 71–109 (approximate)
• app/ante/deduct_fee.go, lines 53–57, 159–169 (isZeroGasMeter) (approximate)

EVM does not use this path; it has its own ante stack, so an analogous mechanism is implemented in x/evm/evmante/.

---

Operating Zero-Gas: Governance, Validation, and Shutdown

Adding or removing zero-gas contracts: The list is governance-controlled: ZeroGasActors.always_zero_gas_contracts. Use the CLI to edit:

nibid tx sudo edit-zero-gas '{"senders":[],"contracts":[],"always_zero_gas_contracts":["0x..."]}'

Validation: ZeroGasActors.Validate() (in x/sudo/msgs.go) ensures each entry in always_zero_gas_contracts (and contracts) is a valid EVM address. See x/sudo/msgs.go and x/sudo/cli/ for the message and CLI implementation.

Emergency disable: Remove or adjust always_zero_gas_contracts via governance (e.g. submit a new ZeroGasActors with an empty or updated list). See also Plan: Execution Model, Invariants, and Safety — Policy.

---

Plan: Execution Model, Invariants, and Safety

Execution Model: Two Phases, One Marker

• The gasless EVM flow has two phases. Ante runs in CheckTx + DeliverTx, and its state writes persist into the block cache when ante succeeds.
• The second phase if EthereumTx, and this msg handler runs only on DeliverTx + Simulate; CheckTx does not execute messages.
• Therefore the marker must be set in ante (CheckTx + DeliverTx) and consumed in msg_server (DeliverTx and EthereumTx).

System Invariants (These Must Always Hold)

• Eligibility: See The Rules: What Qualifies for Zero Gas. tx.To ∈ ZeroGasActors.always_zero_gas_contracts, any sender; tx.Value == 0. No sender allowlist for EVM.
• Skip only gas-related: Balance-vs-cost in VerifyEthAcc, DeductGas, RefundGas skipped when zero-gas. CanTransfer runs. Account verification still runs — see What We Still Enforce: Account Safety Comes First.
• Context marker: Empty ZeroGasMeta under CtxKeyZeroGasMeta; no stored amounts. Access via evm.IsZeroGasEthTx(ctx) / evm.GetZeroGasMeta(ctx). Prereqs: CtxKeyZeroGasMeta, GetZeroGasMeta, ZeroGasMeta in const.go/evm.go; always_zero_gas_contracts in ZeroGasActors (proto, default, validation). Config: EVM ante uses evmstate.Keeper.SudoKeeper.GetZeroGasEvmContracts; SudoKeeper not in AnteHandlerOptions.
• CanTransfer runs always (see The Bypass Points: What We Skip and Why injective node code not available #2

Policy: Sponsored txs pay no validator gas fees; no extra gas caps. Emergency disable: change ZeroGasActors (e.g. via governance) to remove or adjust always_zero_gas_contracts. See Operating Zero-Gas: Governance, Validation, and Shutdown.

Edge cases: Reverted execution (no RefundGas run); execution not attempted (framework reverts); simulation (eth_call/eth_estimateGas) skips ante, no marker.

Edge Cases and Failure Modes

1. Reverted transactions — For zero-gas txs, RefundGas is not run, so there is nothing to undo. Execution can revert; the sender was never charged.
2. Consensus errors — If execution fails before the refund block, the framework reverts the tx. No special logic needed for zero-gas.
3. Simulation (eth_estimateGas, eth_call) — These skip ante and go straight to ApplyEvmMsg. No marker is set; behavior unchanged.

Detection Placement and Skip Behavior

Detection must run before any step that would reject a zero-gas tx. Data: tx.To from evm.UnpackTxData(msgEthTx.Data).GetTo(); SDB shared. Placement: AnteStepDetectZeroGas after AnteStepValidateBasic, before AnteStepMempoolGasPrice.

• Detection: AnteStepDetectZeroGas in x/evm/evmante/evmante_zero_gas.go. Eligibility: see The Rules: What Qualifies for Zero Gas. Set marker only: sdb.SetCtx(sdb.Ctx().WithValue(evm.CtxKeyZeroGasMeta, &evm.ZeroGasMeta{})). No state mutations. Registered in x/evm/evmante/all_evmante.go after ValidateBasic, before MempoolGasPrice.
• Skip behavior when IsZeroGasEthTx(sdb.Ctx()): MempoolGasPrice → skip. VerifyEthAcc → run validation and account creation; skip only balance-vs-tx-cost (see What We Still Enforce: Account Safety Comes First). CanTransfer → runs always. DeductGas → skip.

AnteStepSetupCtx → EthSigVerification → AnteStepValidateBasic
────────────────────────────────────────────────────────────
AnteStepDetectZeroGas   ← eligibility (see The Rules); set marker only
────────────────────────────────────────────────────────────
AnteStepMempoolGasPrice ← skips if zero-gas
AnteStepBlockGasMeter
AnteStepVerifyEthAcc    ← validation + account creation run; skip only balance vs. cost if zero-gas
AnteStepCanTransfer     ← runs always (gas cap, value; value no-ops when 0)
...
AnteStepDeductGas       ← skips if zero-gas
...

Execution Handling and Test Coverage

• Msg_server: In x/evm/evmstate/msg_server.go, run RefundGas only when !evm.IsZeroGasEthTx(rootCtxGasless). Validate always_zero_gas_contracts as EVM addresses in ZeroGasActors.Validate(); see Operating Zero-Gas: Governance, Validation, and Shutdown for CLI.
• Testing: See Test Coverage: Claims Mapped to Tests and Constraints and Where They Are Enforced. Unit: DetectZeroGas, VerifyEthAcc, DeductGas; integration: full ante, msg_server RefundGas skip.

Test Coverage: Claims Mapped to Tests

The following table maps design claims to the tests that validate them. Use this as the canonical reference for regression safety.

Claim	Test(s)	File
Eligibility: ineligible To → no marker	TestAnteStepDetectZeroGas_NonEligible_NoMeta	evmante_zero_gas_test.go
Eligibility: eligible To + value 0 → marker set	TestAnteStepDetectZeroGas_Eligible_SetsMetaNoCredit	evmante_zero_gas_test.go
Eligibility: eligible To + value ≠ 0 → no marker	TestAnteStepDetectZeroGas_Eligible_NonZeroValue_NoMeta	evmante_zero_gas_test.go
Marker set in CheckTx	TestAnteStepDetectZeroGas_SetsMetaInContextWhenCheckTx	evmante_zero_gas_test.go
No balance mutation (bypass approach)	All TestAnteStepDetectZeroGas_* tests	evmante_zero_gas_test.go
VerifyEthAcc: skip balance check for zero-gas; create account when missing	TestVerifyEthAcc_ZeroGas_CreatesAccountWhenMissing, TestVerifyEthAcc case "zero-gas: sender has no balance, account created if missing, VerifyEthAcc passes"	evmante_zero_gas_test.go, evmante_can_transfer_test.go
DeductGas: skip when zero-gas	TestAnteStepDeductGas_SkipsForZeroGasTx	evmante_zero_gas_test.go
Normal tx: no zero-gas marker	TestAnteHandlerEVM "happy: signed tx, sufficient funds", TestEthereumTx_ABCI	all_evmante_test.go, msg_ethereum_tx_test.go
Zero-gas: full ante passes with no balance (first-time onboarding)	TestAnteHandlerEVM "zero-gas: sender with no balance, full ante passes (first-time onboarding)"	all_evmante_test.go
Zero-gas: meta populated after ante, min gas price bypassed	TestAnteHandlerEVM "zero-gas: allowlisted contract, meta populated after all ante steps" (MinGasPrices=1, gas price 0 or 1)	all_evmante_test.go
msg_server: RefundGas skipped; fee collector and sender unchanged	TestMsgEthereumTx_ZeroGas, TestMsgEthereumTx_ZeroGas_WithRefund	msg_ethereum_tx_test.go
Reverted execution: no deduction, no refund	TestMsgEthereumTx_ZeroGas_Reverted	msg_ethereum_tx_test.go

Implicit validations (no dedicated unit test):

• MempoolGasPrice skip: TestAnteHandlerEVM "zero-gas: sender with no balance..." uses MinGasPrices(1) and gas price 0. MempoolGasPrice would reject if it ran; the test passes.
• Simulation (eth_call/eth_estimateGas): Simulation skips ante. Code path in grpc_query.go calls ApplyEvmMsg directly; no test explicitly asserts "eth_call with zero-gas-like tx behaves normally" but the architecture ensures ante is never invoked for these paths. See Known Test Coverage Gaps.

Constraints and Where They Are Enforced

Constraint	Enforced in (file)	Validated by (test or note)
Eligibility: tx.To in list	evmante_zero_gas.go	TestAnteStepDetectZeroGas_NonEligible_NoMeta, TestAnteStepDetectZeroGas_Eligible_SetsMetaNoCredit
Eligibility: tx.Value == 0	evmante_zero_gas.go	TestAnteStepDetectZeroGas_Eligible_NonZeroValue_NoMeta, TestAnteStepDetectZeroGas_Eligible_SetsMetaNoCredit
Contract creation (to == nil) not eligible	evmante_zero_gas.go (returns nil when to == nil)	Implicit (ineligible To covered by NonEligible tests)
Marker propagates to msg_server; RefundGas skipped	msg_server.go	TestMsgEthereumTx_ZeroGas, TestMsgEthereumTx_ZeroGas_WithRefund, TestMsgEthereumTx_ZeroGas_Reverted
VerifyEthAcc: skip only balance check; account creation runs	evmante_can_transfer.go	TestVerifyEthAcc_ZeroGas_CreatesAccountWhenMissing, TestVerifyEthAcc "zero-gas: sender has no balance, account created if missing, VerifyEthAcc passes"
DeductGas skipped when zero-gas	evmante_gas_consume.go	TestAnteStepDeductGas_SkipsForZeroGasTx
MempoolGasPrice skipped when zero-gas	evmante_mempool_fees.go	Implicit (full ante tests with MinGasPrices and gas price 0)
Simulation does not set marker	N/A (ante not invoked)	Unvalidated by dedicated test; architecture (grpc_query.go path)

Known Test Coverage Gaps

MempoolGasPrice zero-gas skip is validated implicitly via full ante chain tests in all_evmante_test.go. A dedicated unit test for this step could strengthen regression safety. Simulation (eth_call/eth_estimateGas) skipping ante is not covered by a dedicated test; the code path is in grpc_query.go.

Files and End-to-End Flow

File	Role
x/evm/const.go, x/evm/evm.go	CtxKeyZeroGasMeta, GetZeroGasMeta, ZeroGasMeta, IsZeroGasEthTx
proto/nibiru/sudo/v1/state.proto, x/sudo/	always_zero_gas_contracts, DefaultZeroGasActors, Validate, getter
x/evm/evmante/evmante_zero_gas.go	AnteStepDetectZeroGas
x/evm/evmante/all_evmante.go	Insert DetectZeroGas in steps
x/evm/evmante/evmante_can_transfer.go	VerifyEthAcc: skip only balance check when zero-gas; CanTransfer: runs for zero-gas
x/evm/evmante/evmante_gas_consume.go	DeductGas: skip when zero-gas
x/evm/evmante/evmante_mempool_fees.go	MempoolGasPrice: skip when zero-gas
x/evm/evmstate/msg_server.go	Skip RefundGas when IsZeroGasEthTx

Flow:

BaseApp.runTx
    ├── 1. Ante (CheckTx + DeliverTx): anteHandler sets marker; skip behavior as above; ante state persisted
    └── 2. runMsgs (DeliverTx + Simulate only): handler receives ctx with marker; skip RefundGas when set

---

Appendix

Rejected Design: Credit Then Undo

An alternative design would temporarily credit the sender, run the normal pipeline (deduct, execute, refund), then undo the net gas payment (reclaim from fee collector and sender). That approach is not implemented. The code uses the conditional bypass above: detect zero-gas, then skip cost checks, deduction, and refund.