Emergency commit

AGENTS.md

@@ -0,0 +1,89 @@
+# AGENTS.md
+
+## Repo overview
+- This is a fork of the Mina blockchain repository for the L2 project Zeko.
+- Zeko-specific code lives under `src/app/zeko`.
+- Changes to upstream Mina code are either prefixed with `zeko_` or marked by a `ZEKO NOTE` comment.
+
+## Key directories
+- `src/app/zeko/circuits`: zero-knowledge circuits for the rollup smart contract.
+- `src/app/zeko/circuits/design`: rollup and bridge design docs/specs (see notes below).
+- `src/app/zeko/da_layer`: multisig DA layer code.
+- `src/app/zeko/sequencer`: off-chain service that accepts transactions, proves them, sends to DA nodes, collects signatures, then submits to L1.
+- `src/app/zeko/sequencer/prover`: proving service used by the sequencer.
+
+## Build
+- Build the Zeko project with:
+  - `dune build ./src/app/zeko/sequencer`
+- The build can take longer than 10 seconds; prefer running with a longer timeout (e.g., 120s) in CI or local scripts.
+
+## Project language
+- OCaml (Dune build system).
+
+## Design docs (circuits)
+- Primary, current spec: `src/app/zeko/circuits/design/rollup-centralized-spec.md`.
+- `src/app/zeko/circuits/design/README.md` notes that other files may be out of date; treat `src/app/zeko/circuits/design/old` as historical context only.
+- Core rollup model: outer (L1) and inner (L2) accounts with action states; commits synchronize a prefix of the outer action state into the inner account; inner steps append to outer action state and advance its length.
+- Commit semantics: sequencer supplies a transaction SNARK and a `valid_while` range; commit action records ledger hash, inner action state, synchronized outer action state, and length; `valid_while` range must be bounded.
+- Rollup state includes `sequencer`, `pause_key`, `da_key`, and `acc_set`; pause is an emergency switch and can be updated via governance.
+- Transaction logic differences: failed transactions are not processed; time preconditions exist (currently unimplemented) and commits must use compatible slot ranges.
+- Bridge/token transfer (see `bridge-explanation.md`, `bridge-spec.md`): deposits are witnessed on the rollup outer account and finalized on L2 if followed by a commit before timeout; withdrawals are witnessed on L2 and finalized on L1 after a delay; helper accounts track last processed indices to prevent double spends; cancellations are handled via timeout and helper indices.
+- Bridge governance: may be separate from rollup governance; circuits can enforce vk hash matching across inner/outer bridge accounts; a failsafe design rotates multiple outer bank accounts to limit impact of a circuit bug.
+
+## Circuits (code concepts)
+- Action states are typed fields with optional length tracking (`rollup_state.ml`); inner app state stores the outer action state+length, outer app state stores the ledger hash, inner action state+length, sequencer key, pause key, DA multisig commitment, and account-set root.
+- Outer actions are either `Commit` (rollup step summary) or `Witness` (arbitrary action payload); inner actions are `Witness` only (`rollup_state.ml`).
+- `rule_commit.ml` verifies the transaction SNARK, DA multisig signatures over the target ledger hash, slot-range bounds, and action-state-extension proofs; it updates outer app state, emits a `Commit` action, and requires a sequencer signature as a child update.
+- `rule_commit.ml` has an emergency branch that verifies `Verify_emergency_folders` (Verify_both_ases + Count_commits), enforces a `max_sequencer_inactivity` gap, and allows commit without the sequencer precondition if no commits occurred since the last one.
+- `rule_action_witness.ml` posts a `Witness` action on L1 and forbids actions while paused; `rule_pause.ml` lets the pause key sign an update that sets `paused = true`.
+- `rule_inner_sync.ml` advances the inner account’s stored outer action state using an A.S.E. proof; `rule_inner_action_witness.ml` posts inner `Witness` actions.
+- `txn_rules.ml` builds the rollup transaction SNARK with branches for signed commands, zkapp commands (proved/unproved), and merge; the statement type is `Txn_state.Zeko_stmt`.
+- `txn_state.ml` defines the rollup SNARK statement, including source/target ledger hashes, account-set roots, slot ranges, and local zkapp state (must be empty at commit).
+- `ase.ml` implements action-state-extension folding circuits (with/without length) and is used by commit and inner sync to prove action-state progression.
+- `account_set.ml`/`indexed_merkle_tree.ml` implement the indexed merkle tree used for the account-set root recorded in the outer state.
+- `multisig.ml` defines DA-layer multisig checking; only the commitment hash is stored in the outer state (`da_key`).
+- Bridge circuits use `bridge_state.ml` for enable/disable window parameters and helper-user indices; `bridge_rules.ml` wires deposit/withdrawal/cancel/enable/disable rules for Mina and custom tokens.
+- `folder.ml`/`folder.mli` implement a generic recursive “state machine” folding circuit (leaf/extend/merge rules) used by action-state extension proofs; it folds arrays of elements with optional mid-proof selection and configurable iteration counts.
+
+## DA layer (code concepts)
+- Each DA node stores and signs diffs that deterministically transform a source ledger hash into a target ledger hash; signatures attest the node can reconstruct the target ledger.
+- `diff.ml` defines the DA diff format: source ledger hash, changed accounts (index + account), optional command with action-step flags, and a timestamp (V2 adds time; V1 is time-less).
+- `core.ml` validates a posted diff by checking source hash, DB presence/genesis, unique indices, and recomputed target hash; it also validates receipt-chain updates for included commands before signing the target hash and persisting the diff.
+- `rpc.ml` exposes Async.Rpc endpoints for posting diffs, fetching diffs, checking presence, listing keys, and fetching signatures/ledger-hash chains.
+- `node.ml` runs the server with a local KV DB, signs ledger hashes, supports syncing from other nodes, and can return the signature for a target hash.
+- `client.ml` provides RPC helpers with retry logic and (for sequencer usage) enforces ordered posting of diffs; it also includes optional relational DB tables for cached diffs/signatures.
+- `db.ml` is the KV storage for diffs plus an index and migration marker; `migrations.ml` handles version upgrades (e.g., adding the top-level version tag).
+
+## Sequencer (core flow)
+- `zeko_sequencer.ml` is the main orchestrator: it validates incoming user commands, applies them to the local ledger/IMT, queues proofs, posts DA diffs, and periodically commits to L1.
+- Transaction application uses `zeko_transaction_logic.ml`, which applies Mina signed payments and zkapp commands to the local ledger, updates the indexed merkle tree, and returns `Txn_snark_witness` segments plus a sparse source ledger for proof inputs.
+- Command validation checks pool capacity, minimum fee (dynamic based on prover queue size), slot-range bounds, and signature/proof validity via `verifier.ml` before applying to state.
+- Applied zkapp commands have events/actions persisted to the archive; fee accumulation is tracked in local KV state and periodically converted into a fee-transfer command.
+- DA integration: after applying a command, the sequencer builds a `Da_layer.Diff` from changed accounts and enqueues it to all DA nodes in order; commits use DA multisig signatures over the target ledger hash.
+- Proof generation uses a parallel merger (`Parallel_merger` via `zeko_sequencer.ml`) with three stages: `Base` creates per-transaction snarks, `Merge` combines two snarks into a larger proof, and `Commit` finalizes a batch into an L1 zkapp command.
+- `committer.ml` assembles the outer commit proof: it proves the txn snark, validates A.S.E. proofs, includes DA multisig witness, and constructs the rollup commit account update; it also persists commit witnesses for manual resend.
+- `update_inner_account` (in `zeko_sequencer.ml`) syncs L1 actions into the L2 inner account using an inner-sync proof, then applies a dummy-fee zkapp command locally to advance action state before committing.
+- `prover/lib/prover.ml` is the prover worker: it handles txn-snark branches (signed/zkapp/merge), folder/A.S.E. proofs, inner sync, and outer commit proofs; `prover/lib/client.ml` sends jobs via a message queue and caches A.S.E. proofs in Postgres.
+- `executor.ml` is the L1 sender: it signs zkapp commands, infers/refreshes nonce, retries on transient failures, and serializes submissions to avoid nonce races.
+
+## Circuits (engineering knowhow)
+- Zkapp action payloads are limited to ~100 field elements; large data should be compressed into hashes or split across transactions (emergency DA uses a single account per tx).
+- Action payload encoding is done via `zeko_util.var_to_actions`, which pushes a struct’s field elements into actions as data-as-hash.
+- Action-state extension proofs (A.S.E.) are built with `ase.ml` + `folder.ml`; these are the canonical way to prove action-state progression with bounded iterations.
+- Emergency commits rely on a counted-commit fold: `Count_commits` produces `{source_action_state; target_action_state; n_commits}` and the emergency rule requires `n_commits = 0` and that counting starts right after the last commit action.
+- Valid-while ranges are inclusive in Mina; commit rules enforce max window size and subset checks against transaction snark slot ranges.
+
+## Mina zkApp model (transaction logic)
+- zkApp transactions are a call forest of account updates; execution walks the forest with a call stack, deriving `caller_id` based on `may_use_token` and parent relationships.
+- Each account update checks: account/ledger inclusion, account preconditions, protocol-state preconditions, valid-while range, and authorization (proof or signature) against the transaction commitment.
+- Transaction commitments are computed from the account-update call forest; `use_full_commitment` switches between transaction and full commitments for authorization and replay protection.
+- Permissions gate every field update (balance, app state, action state, permissions, delegate, nonce, voting-for, zkapp URI, verification key); updates are applied only when the corresponding permission controller authorizes.
+- Action state update logic pushes events into action slots and may shift slots; in Zeko this shift can be forced by the sequencer (no time-based shifting).
+- Receipt chain hashes are updated for account updates authorized by proof/signature, using the full transaction commitment and the account-update index.
+- Account creation fees are handled inside zkapp logic; they may be deducted from balance or from fee excess depending on flags.
+- Failed zkapp updates are disallowed on Zeko: local_state.success must hold for the last account update; failed transactions are rejected rather than partially applied.
+
+## Transaction SNARK structure
+- Transaction snarks support base proofs for signed commands and zkapp command segments, plus merge proofs that combine two proofs into one.
+- Zkapp command segments are categorized by authorization pattern: `Opt_signed`, `Opt_signed_opt_signed`, or `Proved`; proved segments require a side-loaded verification key.
+- The zkapp snark uses implied merkle roots from account+path to validate ledger inclusion and ensures consistent commitments across segments.

src/app/zeko/circuits/count_commits.ml

@@ -0,0 +1,69 @@
+open Snark_params.Tick
+open Zeko_util
+
+module Definition = struct
+  module Stmt = struct
+    type t =
+      { source_action_state : Rollup_state.Outer_action_state.t
+      ; target_action_state : Rollup_state.Outer_action_state.t
+      ; n_commits : Checked32.t
+      }
+    [@@deriving snarky]
+  end
+
+  module Elem = Rollup_state.Outer_action
+
+  let dummy_elem =
+    Rollup_state.Outer_action.Witness
+      { aux = Field.zero
+      ; children_digest = Rollup_state.Zkapp_call_forest.Digest.empty
+      ; slot_range = Slot_range.infinite
+      }
+
+  module Init = struct
+    type t = { original_action_state : Rollup_state.Outer_action_state.t }
+    [@@deriving snarky]
+  end
+
+  let init ~check:_ ({ original_action_state } : Init.var) : Stmt.var Checked.t
+      =
+    Checked.return
+      ( { source_action_state = original_action_state
+        ; target_action_state = original_action_state
+        ; n_commits = Checked32.Checked.zero
+        }
+        : Stmt.var )
+
+  let step (action : Rollup_state.Outer_action.var)
+      ({ source_action_state; target_action_state; n_commits } : Stmt.var) =
+    let* target_action_state =
+      Rollup_state.Outer_action.push_var action target_action_state
+    in
+    let*| n_commits =
+      let* increment =
+        if_ ~typ:Checked32.typ action.is_commit
+          ~then_:Checked32.(Checked.constant one)
+          ~else_:Checked32.Checked.zero
+      in
+      Checked32.Checked.add n_commits increment
+    in
+    Stmt.{ source_action_state; target_action_state; n_commits }
+
+  let name = "count_commits"
+
+  let leaf_iterations =
+    Zeko_constants.Folder_iterations.Count_commits.leaf_iterations
+
+  let leaf_option_iterations =
+    Zeko_constants.Folder_iterations.Count_commits.leaf_option_iterations
+
+  let extend_iterations =
+    Zeko_constants.Folder_iterations.Count_commits.extend_iterations
+
+  let extend_option_iterations =
+    Zeko_constants.Folder_iterations.Count_commits.extend_option_iterations
+
+  let wrap_domain = Some `N14
+end
+
+include Folder.Make (Definition) ()

src/app/zeko/circuits/design/rollup-centralized-explanation.md

@@ -10,6 +10,7 @@ It should be possible to have a stake in the rollup.
 And above all, it should be secure.
 
 To that end, here is a summary of what we want from the core protocol:
+
 - The core rollup protocol does not handle transfer of value/MINA.
 - There is an associated token called ZEKO, using the fungible
   token standard, minted on the L1.
@@ -25,10 +26,14 @@ To that end, here is a summary of what we want from the core protocol:
   to ensure that sequencer does not waste work synchronizing something that
   might be rolled back immediately.
 - Actions on the outside:
-  + Witness (witness arbitrary account update)
-  + Commit (sequencer committed)
+  - Witness (witness arbitrary account update)
+  - Commit (sequencer committed)
 - There is a backup special committee that can pause the rollup.
   Being paused is indicated by a field on the outer account.
+- There is an emergency DA rule that allows committing without the DA multisig.
+  It proves, inside the circuit, that a sequence of account updates was applied
+  to transform a source ledger into a target ledger and that those updates were
+  posted as actions on a dedicated emergency DA account.
 
 How can we implement transfers of tokens on top of this?
 Consider the coremost MINA case:
@@ -42,6 +47,7 @@ of actions.
 Withdrawals happen correspondingly, the other way around.
 We also wish to support timeouts on deposits.
 We do this by regarding a deposit as having three states:
+
 - Unknown
 - Accepted
 - Rejected
@@ -117,6 +123,42 @@ can profit from those deposits being processed.
 
 To prevent this from happening, we also specify a maximum size for the slot range.
 
+## Emergency commit
+
+When the sequencer goes offline, we need a way to unblock the system
+without decentralization of sequencing already in place.
+
+An emergency commit may be issued by anyone once enough time has
+passed since the upper bound of the last commit slot range.
+That upper bound witnesses the latest possible time a commit could
+have occurred; if the current slot is past it by a fixed margin,
+then no commit has happened since.
+
+Malicious sequencer can not pick a very large upper bound, since the slot range is capped by max_valid_size.
+
+However, we can only certify “no commit happened” relative to one of
+the last five outer action states. To make this check viable,
+the sequencer must maintain rolling commits over at least five slots
+within the max_sequencer_inactivity window. With a sufficiently
+large window (e.g., on the order of a month), this obligation is
+trivial for a healthy sequencer.
+
+### Emergency DA rule (actions-based DA)
+
+In emergency mode we replace the DA multisig check with an emergency DA proof.
+The rule applies a single account update to a sparse ledger opening and emits
+an action that contains:
+  - source ledger hash
+  - target ledger hash
+  - account index (derived from the ledger path)
+  - the updated account
+
+Because zkApp actions are limited in size, the emergency DA rule only supports
+one account update per transaction. We then fold a list of such actions with a
+folder proof to produce an action-state transition, and the emergency commit
+requires that the DA proof's source/target ledgers match the transaction SNARK.
+The emergency DA account's action state is used as an on-chain precondition.
+
 ## ZEKO token
 
 The ZEKO token will use the

src/app/zeko/circuits/design/rollup-centralized-spec.md

@@ -62,6 +62,16 @@ val max_valid_while_size : nat
 
 val zeko_token_owner : account_id
 
+(* Emergency DA account for action-based DA proofs. *)
+val emergency_da_pk : public_key
+
+type emergency_da_action =
+  { source_ledger : ledger_hash
+  ; target_ledger : ledger_hash
+  ; account_index : nat
+  ; account : account
+  }
+
 (* Commit work to L1. *)
 let do_commit
   ~txn_snark
@@ -141,6 +151,91 @@ let do_commit
     }
   ]
 
+(* Emergency DA rule: apply a single account update to a sparse ledger opening
+   and emit an action containing source/target ledger hashes, account index, and account. *)
+let do_emergency_da_step ~ledger_opening ~account_update =
+  let source_ledger = ledger_opening.root in
+  let target_ledger = apply_account ledger_opening account_update in
+  let account_index = index_from_path ledger_opening.path in
+  [ { public_key = emergency_da_pk
+    ; actions = [ emergency_da_action
+        { source_ledger
+        ; target_ledger
+        ; account_index
+        ; account = account_update
+        }
+      ]
+    }
+  ]
+
+let count_commits original_action_state actions =
+  let f (acc_action_state, n) = function
+    | (Commit _) as action ->
+      List.append action acc_action_state, n + 1
+    | (Witness _) as action ->
+      List.append action acc_action_state, n
+  in
+  List.fold_left ~init:(original_action_state, 0) ~f actions
+
+val max_sequencer_inactivity : nat
+
+(* Emergency commit in case of sequencer's inactivity *)
+let do_emergency_commit
+  ~txn_snark
+  ~valid_while
+  ~new_actions
+  ~new_inner_actions
+  ~old_inner_action_state_length
+  ~unsynchronized_actions
+  ~pause_key
+  ~da_key
+  ~outer_action_state_before_last_commit
+  ~last_commit
+  ~actions_since_last_commit
+  ~emergency_da_action_state
+  =
+  let [ commit ] =
+    do_commit
+      ~txn_snark
+      ~valid_while
+      ~new_actions
+      ~new_inner_actions
+      ~old_inner_action_state_length
+      ~unsynchronized_actions
+      ~pause_key
+      ~da_key
+  in
+
+  (* Count commits since last commit *)
+  let (target_action_state, n_commits) = count_commits
+    (List.append last_commit outer_action_state_before_last_commit)
+    actions_since_last_commit
+  in
+
+  (* Check that there has not been any commit after last commit *)
+  assert n_commits = 0 ;
+
+  (* Check that count_commits is matching the precondition *)
+  assert target_action_state = commit.preconditions.action_state ;
+
+  (* Check that enought time elapsed since last commit *)
+  assert commit.preconditions.valid_while.lower - last_commit.valid_while.upper >= max_sequencer_inactivity;
+
+  (* Replace DA multisig with emergency DA action-state precondition. *)
+  assert emergency_da_action_state matches commit.preconditions.target_ledger ;
+
+  (* Remove sequencer preconditions *)
+  [ { commit with
+      children = []
+    ; preconditions.app_state.sequencer = Ignore
+    ; children =
+        [ { public_key = emergency_da_pk
+          ; preconditions.action_state = emergency_da_action_state
+          }
+        ]
+    }
+  ]
+
 let do_witness_outer ~aux ~children ~valid_while =
   [ { public_key = zeko_pk
     ; actions = [ Witness { aux ; children ; valid_while } ]