Realm & GUTA Gadgets

These gadgets are used within the circuits run by the network's Realm and Coordinator nodes for aggregating proofs.

GUTAStatsGadget

• File: guta_stats_rs.txt
• Purpose: Represents and aggregates key statistics during GUTA processing (fees, operations counts, slots modified).
• Technical Function: Data structure holding targets for stats. Provides combine_with method for additive aggregation and to_hash for commitment.
• Inputs/Witness: Targets for fees_collected, user_ops_processed, total_transactions, slots_modified.
• Outputs/Computed: Combined stats (via combine_with), hash of stats (to_hash).
• Constraints: combine_with uses addition constraints. to_hash uses packing/hashing.
• Assumptions: Assumes input target values are correct.
• Role: Tracks operational metrics through the aggregation tree.

GlobalUserTreeAggregatorHeaderGadget

• File: guta_header_rs.txt
• Purpose: Defines the standard public input structure for all GUTA-related aggregation circuits. Encapsulates the result of an aggregation step.
• Technical Function: Data structure holding guta_circuit_whitelist root, checkpoint_tree_root, the state_transition (SubTreeNodeStateTransitionGadget) for the GUSR tree segment covered, and aggregated stats (GUTAStatsGadget). Provides to_hash method.
• Inputs/Witness: Component targets/gadgets.
• Outputs/Computed: Hash of the header (to_hash).
• Constraints: to_hash combines hashes of components.
• Assumptions: Assumes input components are correctly formed/verified.
• Role: Standardizes the interface between recursive GUTA circuits, ensuring consistent information propagation and verification.

VerifyEndCapProofGadget

• File: verify_end_cap_rs.txt
• Purpose: Verifies a user's submitted End Cap proof (output of UPS Phase 1) at the entry point of the GUTA aggregation (typically within a Realm node circuit).
• Technical Function: Verifies the End Cap ZK proof, checks its fingerprint against the known constant, matches public inputs against witness data (result/stats), verifies the user's claimed checkpoint root against a historical checkpoint proof, and translates the result into a GlobalUserTreeAggregatorHeaderGadget.
• Inputs/Witness:
  • end_cap_result_gadget, guta_stats: Witness for claimed outputs.
  • checkpoint_historical_merkle_proof: Witness proving user's checkpoint_tree_root_hash was valid historically.
  • verifier_data, proof_target: The End Cap proof itself and its verifier data.
  • known_end_cap_fingerprint_hash: Constant parameter.
• Outputs/Computed: Implements ToGUTAHeader to output a GlobalUserTreeAggregatorHeaderGadget.
• Constraints:
  • Verifies proof_target using verifier_data.
  • Computes fingerprint from verifier_data, connects to known_end_cap_fingerprint_hash.
  • Computes expected public inputs hash from end_cap_result_gadget and guta_stats, connects to proof_target.public_inputs.
  • Verifies checkpoint_historical_merkle_proof using HistoricalRootMerkleProofGadget.
  • Connects historical_proof.historical_root to end_cap_result.checkpoint_tree_root_hash.
  • Constructs output GUTA header using historical_proof.current_root as the checkpoint_tree_root, deriving the state transition from end_cap_result (leaf hashes and user ID), and using the verified guta_stats.
• Assumptions: Assumes witness data is valid initially. Assumes known_end_cap_fingerprint_hash and input default_guta_circuit_whitelist are correct.
• Role: Securely ingests a user's proven session result into the GUTA aggregation, validating it against global rules and historical state before converting it to the standard GUTA format.

VerifyGUTAProofGadget

• File: verify_guta_proof_rs.txt
• Purpose: Verifies a GUTA proof generated by a lower level in the aggregation hierarchy (e.g., verifying a Realm's proof at the Coordinator level, or verifying sub-realm proofs within a Realm).
• Technical Function: Verifies the input GUTA ZK proof, checks its fingerprint against the GUTA circuit whitelist, and ensures its public inputs match the claimed GUTA header witness.
• Inputs/Witness:
  • guta_proof_header_gadget: Witness for the claimed header of the proof being verified.
  • guta_whitelist_merkle_proof: Witness proving the sub-proof's circuit fingerprint is in the GUTA whitelist.
  • verifier_data, proof_target: The GUTA proof and its verifier data.
• Outputs/Computed: The verified guta_proof_header_gadget.
• Constraints:
  • Verifies proof_target using verifier_data.
  • Computes fingerprint from verifier_data.
  • Verifies guta_whitelist_merkle_proof.
  • Connects guta_proof_header.guta_circuit_whitelist to whitelist_proof.root.
  • Computes expected public inputs hash from guta_proof_header, connects to proof_target.public_inputs.
  • Connects whitelist_proof.value to computed fingerprint.
• Assumptions: Assumes witness data is valid initially.
• Role: The core recursive verification step for GUTA aggregation circuits. Ensures that only valid proofs generated by allowed GUTA circuits are incorporated into higher levels of aggregation.

TwoNCAStateTransitionGadget

• File: two_nca_state_transition_rs.txt
• Purpose: Combines the GUSR state transitions from two independent GUTA proofs (A and B) that modify different branches of the tree, computing the resulting state transition at their Nearest Common Ancestor (NCA).
• Technical Function: Uses UpdateNearestCommonAncestorProofOptGadget to verify the NCA proof witness against the state transitions provided by the input GUTA headers (a_header, b_header). Combines statistics and outputs a new GUTA header for the NCA node.
• Inputs/Witness:
  • a_header, b_header: Verified GUTA headers from the two child proofs.
  • UpdateNearestCommonAncestorProof: Witness containing NCA proof data (partial or full).
• Outputs/Computed: new_guta_header representing the transition at the NCA.
• Constraints:
  • Connects a_header.checkpoint_tree_root == b_header.checkpoint_tree_root.
  • Connects a_header.guta_circuit_whitelist == b_header.guta_circuit_whitelist.
  • Connects a_header.state_transition fields (old/new value, index, level) to update_nca_proof_gadget.child_a fields.
  • Connects b_header.state_transition fields to update_nca_proof_gadget.child_b fields.
  • Computes new_stats = a_header.stats.combine_with(b_header.stats).
  • Constructs new_guta_header using whitelist/checkpoint from children, the NCA state transition details from update_nca_proof_gadget, and new_stats.
• Assumptions: Assumes input headers a_header and b_header have already been verified. Assumes the NCA proof witness is valid initially.
• Role: Enables efficient parallel aggregation by merging results from independent subtrees using cryptographic proofs of their combined effect at the parent node.

GUTAHeaderLineProofGadget

• File: guta_line_rs.txt
• Purpose: Propagates a GUTA state transition upwards along a direct path in the GUSR tree (when there's only one child updating that path segment).
• Technical Function: Uses SubTreeNodeTopLineGadget to recompute the Merkle root hash from the child's transition level up to a specified higher level (e.g., Realm root or global root), using sibling hashes provided as witness.
• Inputs/Witness:
  • child_proof_header: The verified GUTA header from the lower level.
  • siblings: Witness array of Merkle sibling hashes for the path.
  • Height parameters.
• Outputs/Computed: new_guta_header with the state transition updated to reflect the higher level.
• Constraints: Relies on SubTreeNodeTopLineGadget's internal Merkle hashing constraints.
• Assumptions: Assumes child_proof_header is verified. Assumes siblings witness is correct.
• Role: Efficiently moves a verified state transition up the tree hierarchy when merging (NCA) is not required.

VerifyGUTAProofToLineGadget

• File: verify_guta_proof_to_line_rs.txt
• Purpose: Combines verifying a lower-level GUTA proof with immediately propagating its state transition upwards using a line proof.
• Technical Function: Orchestrates VerifyGUTAProofGadget followed by GUTAHeaderLineProofGadget.
• Inputs/Witness: Combines witnesses for both sub-gadgets (proof, header, whitelist proof, siblings).
• Outputs/Computed: new_guta_header at the top of the line.
• Constraints: Instantiates and connects the two sub-gadgets.
• Assumptions: Relies on sub-gadget assumptions.
• Role: A common pattern gadget simplifying the verification and upward propagation of a single GUTA proof branch.

(Coordinator/GUTA Gadgets related to User Registration: GUTARegisterUserCoreGadget, GUTARegisterUserFullGadget, GUTARegisterUsersGadget, GUTAOnlyRegisterUsersGadget, GUTARegisterUsersBatchGadget - Descriptions remain largely the same as the previous detailed version, focusing on GUSR tree updates and User Registration Tree checks.)

GUTANoChangeGadget

• File: guta_no_change_gadget_rs.txt
• Purpose: Creates a GUTA header signifying that the GUSR tree state did not change for this block/subtree, while still potentially updating the referenced checkpoint_tree_root.
• Technical Function: Verifies a checkpoint proof to get the current checkpoint_tree_root and the corresponding user_tree_root from the checkpoint leaf. Constructs a GUTA header with a "no-op" state transition (old=new=user_tree_root at level 0) and zero stats.
• Inputs/Witness:
  • guta_circuit_whitelist: Input constant/parameter.
  • checkpoint_tree_proof: Witness proving checkpoint_leaf existence.
  • checkpoint_leaf_gadget: Witness for the QEDCheckpointLeafCompactWithStateRoots.
• Outputs/Computed: new_guta_header (indicating no GUSR change).
• Constraints: Verifies checkpoint proof (MerkleProofGadget). Verifies consistency between proof value and leaf hash. Constructs header with no-op transition and zero stats.
• Assumptions: Assumes witness proof/leaf data is valid initially. Assumes input guta_circuit_whitelist is correct.
• Role: Allows the GUTA aggregation structure to remain consistent and synchronized with the main Checkpoint Tree advancement even during periods where no user state relevant to GUTA was modified.