compact-core-compact-transaction-model

name: compact-core:compact-transaction-model description: This skill should be used when the user asks about Midnight transaction execution, guaranteed vs fallible phases, kernel.checkpoint(), transaction composition, state conflicts, DUST fees, gas limits, proof verification, partial transaction success, transaction merging, atomic swaps, or how Compact circuits map to on-chain execution. Also triggered by mentions of "transaction semantics", "fallible phase", "guaranteed phase", "checkpoint", "well-formedness", "Impact VM", or "Zswap offers". version: 0.1.0

Compact Transaction Model & Execution Semantics

This skill covers how Compact circuits map to on-chain transaction execution: the three-stage lifecycle (well-formedness, guaranteed, fallible), kernel.checkpoint() placement, transaction composition, merging for atomic swaps, the state model, and the fee/gas system. For contract anatomy and circuit/witness design, see compact-structure. For ledger ADT types and state design, see compact-ledger. For token minting, sending, and receiving, see compact-tokens.

Transaction Lifecycle Overview

Every Midnight transaction passes through three sequential stages. Failure at each stage has different consequences.

Execution flow from the developer's perspective:

Compact circuit call
  -> Proof generation (client-side)
    -> Well-formedness check (stateless validation)
      -> Guaranteed phase (proof verification, fees, Zswap)
        -> Fallible phase (contract state mutations)
          -> State update (if "strong")

The key insight: a transaction that fails in the fallible phase is a partial success, not a full rejection. The guaranteed-phase effects (fee collection, Zswap coin movements, guaranteed transcript operations) persist on the ledger. Only the fallible section's effects are rolled back.

Guaranteed vs Fallible Phases

Guaranteed Phase

Operations in the guaranteed phase either all succeed or the transaction is not included in the ledger at all.

Fallible Phase

Operations in the fallible phase may fail without reversing guaranteed-phase effects.

Key Rules

• Fees for ALL phases are collected in the guaranteed phase. If the fallible phase fails, fees are still consumed (forfeited).
• ZK proofs are verified only in the guaranteed phase.
• Contract deployments execute entirely in the fallible phase. A deployment failure is a partial success: fees are spent but the contract is not created.
• If a circuit contains no kernel.checkpoint() call, the entire circuit body maps to the guaranteed phase only. There is no fallible section.

kernel.checkpoint()

kernel.checkpoint() splits a circuit into guaranteed and fallible sections. Everything before the call executes in the guaranteed phase; everything after executes in the fallible phase. It maps to the ckpt opcode in the Impact VM.

// Assumes ledger declarations:
//   export ledger balance: Map<Bytes<32>, Uint<64>>;
//   export ledger transferCount: Counter;
//   witness localSecretKey(): Bytes<32>;

export circuit transfer(to: Bytes<32>, amount: Uint<64>): [] {
  // --- GUARANTEED PHASE ---
  // These operations are atomic: all succeed or the transaction is rejected
  const sk = localSecretKey();
  const sender = persistentHash<Bytes<32>>(sk);
  const current = balance.lookup(disclose(sender));
  assert(disclose(current >= amount), "Insufficient balance");
  transferCount.increment(1);

  kernel.checkpoint();

  // --- FALLIBLE PHASE ---
  // These operations may fail without reversing the guaranteed phase
  balance.insert(disclose(sender), disclose((current - amount) as Uint<64>));
  balance.insert(disclose(to), disclose((balance.lookup(disclose(to)) + amount) as Uint<64>));
}

Checkpoint Rules

When to Use checkpoint

Place kernel.checkpoint() when you need operations that:

• Depend on state that may conflict with concurrent transactions
• Perform complex state mutations that you can tolerate failing
• Deploy contracts as part of a larger workflow

Keep critical invariants (authorization checks, fee collection, proof-dependent logic) before the checkpoint in the guaranteed section.

Transaction Composition

A single Midnight transaction can contain multiple contract calls or deployments. These execute sequentially.

Cross-contract calls (one contract calling another contract's circuit within the same execution) are not yet available. To compose operations across contracts, include multiple contract calls in a single transaction. Each call executes independently against its own contract state, but within the shared transaction context.

Transaction Merging

Midnight supports transaction merging to enable atomic swaps and multi-party transactions.

Atomic Swap Pattern

Transaction merging enables atomic swaps: Alice creates a transaction spending her coins, Bob creates a transaction spending his coins, and the two merge into a single atomic transaction. Because at least one party's transaction has no contract calls, the merge is valid. The Pedersen commitment binding guarantees neither party can alter the other's contribution.

State Model

Each contract on Midnight maintains state as two components:

State Lifecycle During Execution

1. The contract's current state is loaded from the ledger before each call.
2. A context object (contract address, newly allocated coins, block time, block hash, block's 32-bit max timestamp divergence) and an empty effects set are placed on the Impact VM stack alongside the state. Both context and effects are flagged as weak.

   Caution: Currently, only the first two of these are correctly initialized!

3. The Impact program executes, mutating the state on the stack. The propagation rules for weakness are opcode-specific.
4. The resulting effects are compared to the declared effects in the transcript; mismatches cause failure.
5. The resulting state is stored only if it is "strong" (not weak). If the state has been weakened — for example, by copying context or effects data into it — the call fails.

Concurrency and Conflicts

• Within a block, transactions are applied sequentially. If two transactions write to the same contract state, the second executes against the state left by the first.
• A transaction that reads or writes state another transaction also modifies may conflict if the second transaction's proof was generated against the pre-first-transaction state.
• Practical advice: use append-only data structures (Merkle trees, counters, sets with insert-only patterns) to minimize conflict windows. Avoid read-modify-write patterns on shared mutable state when possible.

Fees & Gas

DUST is Midnight's shielded network resource used exclusively to pay for transaction fees. It is a non-transferable resource derived from NIGHT.

Developers do not set gas prices directly. The declared gas bound in each transcript determines the maximum cost, and the network's dynamic pricing converts this to a DUST amount at inclusion time.

Proof Verification

ZK proof verification happens automatically and is not directly controlled by the contract developer.

The proof for each contract call is generated client-side when the user invokes a circuit. The verifier key is stored in the contract state (set at deployment) and looked up during the guaranteed phase. If verification fails, the entire transaction is rejected (not included in the ledger). Developers write Compact circuits; the compiler and runtime handle proof generation and verification.

Common Mistakes

Reference Routing