User Cli Interface

This documentation organizes the three core data query interfaces implemented by RpcProvider (QTreeDataStoreReaderSync<F>, QMetaDataStoreReaderSync<F>, and QEDComboDataStoreReaderSync<F>). It includes interface functions, method details, parameter descriptions, and return value types, focusing on core data query capabilities for blockchain scenarios such as users, contracts, and checkpoints.

Basic Information

• Core Dependent Types:
  • F = GoldilocksField: A prime field type based on Plonky2, used for blockchain data verification and hash calculation.
  • QHashOut<F>: Hash output result type, storing raw data after hash calculation.
  • MerkleProofCore<QHashOut<F>>: Core Merkle proof type, containing information such as the root, value, and sibling nodes required for proof.

Core Structures

RpcProvider

The foundational component for RPC communication, responsible for interacting with Realm nodes (user-specific data) and Coordinator nodes (global public data, e.g., contracts, checkpoints). It supports cross-environment use (non-WASM like servers, WASM like browser extensions).

Structure Definition

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub struct RpcProvider {
    pub client: Arc<Client>,               // HTTP client (for RPC requests)
    pub realm_configs: HashMap<u64, Vec<String>>,  // Realm node config: {Realm ID → List of RPC URLs}
    pub coordinator_configs: HashMap<u64, Vec<String>>,  // Coordinator node config: {Coordinator ID → List of RPC URLs}
    pub users_per_realm: u64,              // Number of users assigned to each Realm (for user-to-Realm routing)
    pub current_user_id: u64,              // ID of the currently active user (for default data requests)
}
}

Key Methods

RpcProvider provides methods for node routing, user/contract/data queries, and transaction submission. Core methods are categorized below:

Auxiliary Structures

RpcConfig & NetworkConfig

Configuration structures for node networks and proxy services, loaded from external config files:

#![allow(unused)]
fn main() {
#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct RpcConfig {
    pub users_per_realm: u64,                // Number of users per Realm
    pub global_user_tree_height: u8,         // Height of the global user Merkle tree
    pub realm_user_tree_height: u8,          // Height of the Realm-specific user Merkle tree
    pub realm_configs: Vec<RealmRpcConfig>,  // List of Realm node configs
    pub coordinator_configs: Vec<CoordinatorRpcConfig>,  // List of Coordinator node configs
    pub prove_proxy_url: Vec<String>,        // List of proof proxy service URLs
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NetworkConfig {  // Extended config for blockchain network
    pub users_per_realm: u64,
    pub global_user_tree_height: u8,
    pub realm_user_tree_height: u8,
    pub realm_configs: Vec<RealmConfig>,     // Same as RealmRpcConfig
    pub coordinator_configs: Vec<CoordinatorConfig>,  // Same as CoordinatorRpcConfig
    pub prover_url: Option<String>,          // Optional prover service URL
    pub prove_proxy_url: Vec<String>,
    pub native_currency: String,             // Native currency symbol (e.g., "PSY")
}
}

Merkle Tree Data Query

This interface focuses on querying roots, leaf hashes, and Merkle proofs of various Merkle trees in the blockchain, covering core scenarios such as users, contracts, checkpoints, deposits, and withdrawals.

1. User-Related Merkle Tree Queries

(1) User Contract State Tree Queries (User-Contract Internal State)

(2) User Contract Tree Queries (User-Contract Association)

(3) User Registration Tree Queries (Global User Registration State)

(4) User Tree Queries (Global User State)

2. Contract-Related Merkle Tree Queries

3. Asset-Related Merkle Tree Queries

(1) Deposit Tree Queries

(2) Withdrawal Tree Queries

4. Checkpoint-Related Merkle Tree Queries

Metadata Query

This interface focuses on querying core blockchain metadata, including complete leaf data for users, contracts, and checkpoints, as well as L2 block states.

1. User Metadata Queries

2. Contract Metadata Queries

3. Checkpoint and L2 Block State Queries

Realm Edge RPC Documentation

This document provides comprehensive documentation for all Realm Edge RPC methods defined in the RealmEdgeRpc trait.

RPC Namespace: qed

Table of Contents

1. User Management
2. User End Cap Submission
3. Checkpoint Data Operations
4. L2 Block State Operations
5. User Registration Tree Operations
6. Checkpoint Tree Operations
7. User Leaf Data Operations
8. User Contract State Tree Operations
9. User Contract Tree Operations
10. User Tree Operations
11. Batch Proof Generation
12. GraphViz Export
13. Data Structures

User Management

1. check_user_id_in_realm

Check if a user ID belongs to this realm.

Method Name: qed_check_user_id_in_realm

Request Parameters:

{
  "user_id": 12345
}

Response:

{
  "result": true
}

Example:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_check_user_id_in_realm",
    "params": [12345],
    "id": 1
  }'

User End Cap Submission

2. submit_user_end_cap

Submit a user end cap proof for processing.

Method Name: qed_submit_user_end_cap

Request Parameters:

{
  "user_ec_input": {
    "core": {
      "checkpoint_id": "123",
      "stats": { ... },
      "state_transition": { ... },
      "new_user_leaf": { ... }
    },
    "contract_state_updates": [ ... ]
  },
  "proof": { ... }
}

Response:

{
  "result": "0x1234567890abcdef..."
}

Checkpoint Data Operations

3. get_checkpoint_leaf_data

Get checkpoint leaf data by checkpoint ID (u64 parameter).

Method Name: qed_get_checkpoint_leaf_data

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QEDCheckpointLeaf

Example:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_checkpoint_leaf_data",
    "params": [100],
    "id": 1
  }'

4. get_checkpoint_leaf_data_f

Get checkpoint leaf data by checkpoint ID (Field parameter).

Method Name: qed_get_checkpoint_leaf_data_f

Request Parameters:

{
  "checkpoint_id": "100"
}

Response: See QEDCheckpointLeaf

L2 Block State Operations

5. get_latest_l2_block_state

Get the latest L2 block state.

Method Name: qed_get_latest_l2_block_state

Request Parameters: None

Response: See QEDL2BlockState

Example:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_latest_l2_block_state",
    "params": [],
    "id": 1
  }'

Response Example:

{
  "result": {
    "checkpoint_id": 100,
    "next_add_withdrawal_id": 50,
    "next_process_withdrawal_id": 45,
    "next_deposit_id": 200,
    "total_deposits_claimed_epoch": 180,
    "next_user_id": 1000,
    "end_balance": 5000000,
    "next_contract_id": 25
  }
}

6. get_l2_block_state

Get L2 block state at a specific checkpoint (u64 parameter).

Method Name: qed_get_l2_block_state

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QEDL2BlockState

7. get_l2_block_state_f

Get L2 block state at a specific checkpoint (Field parameter).

Method Name: qed_get_l2_block_state_f

Request Parameters:

{
  "checkpoint_id": "100"
}

Response: See QEDL2BlockState

User Registration Tree Operations

8. get_user_registration_tree_root

Get the user registration tree root at a specific checkpoint.

Method Name: qed_get_user_registration_tree_root

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QHashOut

Example Response:

{
  "result": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}

Checkpoint Tree Operations

9. get_latest_checkpoint_tree_root

Get the latest checkpoint tree root.

Method Name: qed_get_latest_checkpoint_tree_root

Request Parameters: None

Response: See QHashOut

10. get_checkpoint_tree_root

Get checkpoint tree root at a specific checkpoint (u64 parameter).

Method Name: qed_get_checkpoint_tree_root

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QHashOut

11. get_checkpoint_tree_root_f

Get checkpoint tree root at a specific checkpoint (Field parameter).

Method Name: qed_get_checkpoint_tree_root_f

Request Parameters:

{
  "checkpoint_id": "100"
}

Response: See QHashOut

12. get_checkpoint_tree_leaf_hash

Get a specific checkpoint tree leaf hash (u64 parameters).

Method Name: qed_get_checkpoint_tree_leaf_hash

Request Parameters:

{
  "checkpoint_id": 100,
  "leaf_checkpoint_id": 95
}

Response: See QHashOut

13. get_checkpoint_tree_leaf_hash_f

Get a specific checkpoint tree leaf hash (Field parameters).

Method Name: qed_get_checkpoint_tree_leaf_hash_f

Request Parameters:

{
  "checkpoint_id": "100",
  "leaf_checkpoint_id": "95"
}

Response: See QHashOut

14. get_checkpoint_tree_merkle_proof

Get Merkle proof for a checkpoint tree leaf (u64 parameters).

Method Name: qed_get_checkpoint_tree_merkle_proof

Request Parameters:

{
  "checkpoint_id": 100,
  "leaf_checkpoint_id": 95
}

Response: See MerkleProofCore

15. get_checkpoint_tree_merkle_proof_f

Get Merkle proof for a checkpoint tree leaf (Field parameters).

Method Name: qed_get_checkpoint_tree_merkle_proof_f

Request Parameters:

{
  "checkpoint_id": "100",
  "leaf_checkpoint_id": "95"
}

Response: See MerkleProofCore

16. get_checkpoint_global_state_roots

Get global state roots at a specific checkpoint.

Method Name: qed_get_checkpoint_global_state_roots

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QEDCheckpointGlobalStateRoots

Example Response:

{
  "result": {
    "contract_tree_root": "0x...",
    "deposit_tree_root": "0x...",
    "user_tree_root": "0x...",
    "withdrawal_tree_root": "0x...",
    "user_registration_tree_root": "0x..."
  }
}

User Leaf Data Operations

17. get_user_leaf_data

Get user leaf data at a specific checkpoint (u64 parameters).

Method Name: qed_get_user_leaf_data

Request Parameters:

{
  "checkpoint_id": 100,
  "user_id": 12345
}

Response: See QEDUserLeaf

Example:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_user_leaf_data",
    "params": [100, 12345],
    "id": 1
  }'

18. get_user_leaf_data_f

Get user leaf data at a specific checkpoint (Field parameters).

Method Name: qed_get_user_leaf_data_f

Request Parameters:

{
  "checkpoint_id": "100",
  "user_id": "12345"
}

Response: See QEDUserLeaf

User Contract State Tree Operations

19. get_user_contract_state_tree_root

Get user contract state tree root (u64 parameters).

Method Name: qed_get_user_contract_state_tree_root

Request Parameters:

{
  "checkpoint_id": 100,
  "user_id": 12345,
  "contract_id": 5
}

Response: See QHashOut

20. get_user_contract_state_tree_root_f

Get user contract state tree root (Field parameters).

Method Name: qed_get_user_contract_state_tree_root_f

Request Parameters:

{
  "checkpoint_id": "100",
  "user_id": "12345",
  "contract_id": "5"
}

Response: See QHashOut

21. get_user_contract_state_tree_leaf_hash

Get user contract state tree leaf hash (u64 parameters).

Method Name: qed_get_user_contract_state_tree_leaf_hash

Request Parameters:

{
  "checkpoint_id": 100,
  "user_id": 12345,
  "contract_id": 5,
  "height": 10,
  "leaf_id": 42
}

Response: See QHashOut

22. get_user_contract_state_tree_leaf_hash_f

Get user contract state tree leaf hash (Field parameters).

Method Name: qed_get_user_contract_state_tree_leaf_hash_f

Request Parameters:

{
  "checkpoint_id": "100",
  "user_id": "12345",
  "contract_id": "5",
  "height": 10,
  "leaf_id": "42"
}

Response: See QHashOut

23. get_user_contract_state_tree_merkle_proof

Get Merkle proof for user contract state tree (u64 parameters).

Method Name: qed_get_user_contract_state_tree_merkle_proof

Request Parameters:

{
  "checkpoint_id": 100,
  "user_id": 12345,
  "contract_id": 5,
  "height": 10,
  "leaf_id": 42
}

Response: See MerkleProofCore

24. get_user_contract_state_tree_merkle_proof_f

Get Merkle proof for user contract state tree (Field parameters).

Method Name: qed_get_user_contract_state_tree_merkle_proof_f

Request Parameters:

{
  "checkpoint_id": "100",
  "user_id": "12345",
  "contract_id": "5",
  "height": 10,
  "leaf_id": "42"
}

Response: See MerkleProofCore

User Contract Tree Operations

25. get_user_contract_tree_root

Get user contract tree root (u64 parameters).

Method Name: qed_get_user_contract_tree_root

Request Parameters:

{
  "checkpoint_id": 100,
  "user_id": 12345
}

Response: See QHashOut

26. get_user_contract_tree_root_f

Get user contract tree root (Field parameters).

Method Name: qed_get_user_contract_tree_root_f

Request Parameters:

{
  "checkpoint_id": "100",
  "user_id": "12345"
}

Response: See QHashOut

27. get_user_contract_tree_leaf_hash

Get user contract tree leaf hash (u64 parameters).

Method Name: qed_get_user_contract_tree_leaf_hash

Request Parameters:

{
  "checkpoint_id": 100,
  "user_id": 12345,
  "contract_id": 5
}

Response: See QHashOut

28. get_user_contract_tree_leaf_hash_f

Get user contract tree leaf hash (Field parameters).

Method Name: qed_get_user_contract_tree_leaf_hash_f

Request Parameters:

{
  "checkpoint_id": "100",
  "user_id": "12345",
  "contract_id": "5"
}

Response: See QHashOut

29. get_user_contract_tree_merkle_proof

Get Merkle proof for user contract tree (u64 parameters).

Method Name: qed_get_user_contract_tree_merkle_proof

Request Parameters:

{
  "checkpoint_id": 100,
  "user_id": 12345,
  "contract_id": 5
}

Response: See MerkleProofCore

30. get_user_contract_tree_merkle_proof_f

Get Merkle proof for user contract tree (Field parameters).

Method Name: qed_get_user_contract_tree_merkle_proof_f

Request Parameters:

{
  "checkpoint_id": "100",
  "user_id": "12345",
  "contract_id": "5"
}

Response: See MerkleProofCore

User Tree Operations

31. get_user_tree_root

Get user tree root at a specific checkpoint (u64 parameter).

Method Name: qed_get_user_tree_root

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QHashOut

32. get_user_tree_root_f

Get user tree root at a specific checkpoint (Field parameter).

Method Name: qed_get_user_tree_root_f

Request Parameters:

{
  "checkpoint_id": "100"
}

Response: See QHashOut

33. get_user_tree_leaf_hash

Get user tree leaf hash (u64 parameters).

Method Name: qed_get_user_tree_leaf_hash

Request Parameters:

{
  "checkpoint_id": 100,
  "user_id": 12345
}

Response: See QHashOut

34. get_user_tree_leaf_hash_f

Get user tree leaf hash (Field parameters).

Method Name: qed_get_user_tree_leaf_hash_f

Request Parameters:

{
  "checkpoint_id": "100",
  "user_id": "12345"
}

Response: See QHashOut

35. get_user_bottom_tree_merkle_proof

Get Merkle proof for user bottom tree (u64 parameters).

Method Name: qed_get_user_bottom_tree_merkle_proof

Request Parameters:

{
  "root_level": 5,
  "checkpoint_id": 100,
  "user_id": 12345
}

Response: See MerkleProofCore

36. get_user_bottom_tree_merkle_proof_f

Get Merkle proof for user bottom tree (Field parameters).

Method Name: qed_get_user_bottom_tree_merkle_proof_f

Request Parameters:

{
  "root_level": 5,
  "checkpoint_id": "100",
  "user_id": "12345"
}

Response: See MerkleProofCore

37. get_user_sub_tree_merkle_proof

Get Merkle proof for user sub-tree (u64 parameters).

Method Name: qed_get_user_sub_tree_merkle_proof

Request Parameters:

{
  "checkpoint_id": 100,
  "root_level": 5,
  "leaf_level": 2,
  "leaf_index": 42
}

Response: See MerkleProofCore

38. get_user_sub_tree_merkle_proof_f

Get Merkle proof for user sub-tree (Field parameters).

Method Name: qed_get_user_sub_tree_merkle_proof_f

Request Parameters:

{
  "checkpoint_id": "100",
  "root_level": 5,
  "leaf_level": 2,
  "leaf_index": "42"
}

Response: See MerkleProofCore

39. get_user_tree_merkle_proof

Get Merkle proof for user tree (u64 parameters).

Method Name: qed_get_user_tree_merkle_proof

Request Parameters:

{
  "checkpoint_id": 100,
  "user_id": 12345
}

Response: See MerkleProofCore

Example:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_user_tree_merkle_proof",
    "params": [100, 12345],
    "id": 1
  }'

40. get_user_tree_merkle_proof_f

Get Merkle proof for user tree (Field parameters).

Method Name: qed_get_user_tree_merkle_proof_f

Request Parameters:

{
  "checkpoint_id": "100",
  "user_id": "12345"
}

Response: See MerkleProofCore

Note: This method internally converts field parameters to u64 and calls get_user_tree_merkle_proof.

Batch Proof Generation

41. generate_batch_variable_height_reward_proofs

Generate batch variable height reward Merkle proofs for multiple job IDs.

Method Name: qed_generate_batch_variable_height_reward_proofs

Request Parameters:

{
  "checkpoint_id": 100,
  "job_ids": [
    {
      "topic": "GenerateStandardProof",
      "goal_id": 100,
      "slot_id": 5,
      "circuit_type": "GUTATwoEndCap",
      "group_id": 1,
      "sub_group_id": 0,
      "task_index": 0,
      "data_type": "InputWitness",
      "data_index": 0
    }
  ]
}

Response:

{
  "result": [
    [
      {
        "top_siblings": [...],
        "sibling_branch": "0x...",
        "reward_leaf": "0x...",
        "proof_height": "5",
        "index": "42"
      },
      {
        "topic": "GenerateStandardProof",
        "goal_id": 100,
        ...
      }
    ]
  ]
}

Example:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_generate_batch_variable_height_reward_proofs",
    "params": [100, [...]],
    "id": 1
  }'

GraphViz Export

42. get_graphviz

Get GraphViz representation of the Merkle tree at a specific checkpoint.

Method Name: qed_get_graphviz

Request Parameters:

{
  "checkpoint_id": 100
}

Response:

{
  "result": "digraph G {\n  node1 -> node2;\n  ...\n}"
}

Example:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_graphviz",
    "params": [100],
    "id": 1
  }' | jq -r '.result' | dot -Tpng > tree.png

Data Structures

QHashOut

A hash output wrapper for Plonky2 field elements.

Structure:

#![allow(unused)]
fn main() {
pub struct QHashOut<F: Field>(pub HashOut<F>);
}

JSON Representation:

"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

Description:

• Wraps a Plonky2 HashOut<F> containing 4 field elements
• Serialized as a hexadecimal string (32 bytes)
• Represents a 256-bit hash value

QEDL2BlockState

L2 block state information at a specific checkpoint.

Structure:

#![allow(unused)]
fn main() {
pub struct QEDL2BlockState {
    pub checkpoint_id: u64,
    pub next_add_withdrawal_id: u64,
    pub next_process_withdrawal_id: u64,
    pub next_deposit_id: u64,
    pub total_deposits_claimed_epoch: u64,
    pub next_user_id: u64,
    pub end_balance: u64,
    pub next_contract_id: u32,
}
}

Fields:

Example:

{
  "checkpoint_id": 100,
  "next_add_withdrawal_id": 50,
  "next_process_withdrawal_id": 45,
  "next_deposit_id": 200,
  "total_deposits_claimed_epoch": 180,
  "next_user_id": 1000,
  "end_balance": 5000000,
  "next_contract_id": 25
}

QEDCheckpointLeaf

Checkpoint leaf data containing global chain root and statistics.

Structure:

#![allow(unused)]
fn main() {
pub struct QEDCheckpointLeaf<F: RichField> {
    pub global_chain_root: QHashOut<F>,
    pub stats: QEDCheckpointLeafStats<F>,
}
}

Fields:

QEDCheckpointLeafStats Structure:

#![allow(unused)]
fn main() {
pub struct QEDCheckpointLeafStats<F: RichField> {
    pub fees_collected: F,
    pub user_ops_processed: F,
    pub total_transactions: F,
    pub slots_modified: F,
    pub pm_jobs_completed: PMJobsCompletedStats<F>,
    pub block_time: F,
    pub random_seed: QHashOut<F>,
    pub pm_rewards_commitment: PMRewardCommitment<F>,
    pub da_challenges_claimed: [F; DA_CHALLENGE_WINDOW],
}
}

Example:

{
  "global_chain_root": "0x...",
  "stats": {
    "fees_collected": "1000",
    "user_ops_processed": "50",
    "total_transactions": "75",
    "slots_modified": "30",
    "pm_jobs_completed": {...},
    "block_time": "1234567890",
    "random_seed": "0x...",
    "pm_rewards_commitment": {...},
    "da_challenges_claimed": [...]
  }
}

QEDCheckpointGlobalStateRoots

Global state roots at a specific checkpoint.

Structure:

#![allow(unused)]
fn main() {
pub struct QEDCheckpointGlobalStateRoots<F: RichField> {
    pub contract_tree_root: QHashOut<F>,
    pub deposit_tree_root: QHashOut<F>,
    pub user_tree_root: QHashOut<F>,
    pub withdrawal_tree_root: QHashOut<F>,
    pub user_registration_tree_root: QHashOut<F>,
}
}

Fields:

Example:

{
  "contract_tree_root": "0x1234...",
  "deposit_tree_root": "0x5678...",
  "user_tree_root": "0x9abc...",
  "withdrawal_tree_root": "0xdef0...",
  "user_registration_tree_root": "0x1234..."
}

QEDUserLeaf

User leaf data containing user state information.

Structure:

#![allow(unused)]
fn main() {
pub struct QEDUserLeaf<F: RichField> {
    pub public_key: QHashOut<F>,
    pub user_state_tree_root: QHashOut<F>,
    pub balance: F,
    pub nonce: F,
    pub last_checkpoint_id: F,
    pub event_index: F,
    pub user_id: F,
}
}

Fields:

Example:

{
  "public_key": "0x1234...",
  "user_state_tree_root": "0x5678...",
  "balance": "1000000",
  "nonce": "42",
  "last_checkpoint_id": "100",
  "event_index": "15",
  "user_id": "12345"
}

MerkleProofCore

Generic Merkle proof structure.

Structure:

#![allow(unused)]
fn main() {
pub struct MerkleProofCore<Hash: PartialEq + Copy> {
    pub root: Hash,
    pub value: Hash,
    pub index: u64,
    pub siblings: Vec<Hash>,
}
}

Fields:

Example:

{
  "root": "0x1234...",
  "value": "0x5678...",
  "index": 42,
  "siblings": [
    "0x9abc...",
    "0xdef0...",
    "0x1234..."
  ]
}

Verification: The proof can be verified by hashing the value with siblings along the path according to the index bits.

SubmitUserEndCapNonProofInput

Input data for submitting user end cap (without proof).

Structure:

#![allow(unused)]
fn main() {
pub struct SubmitUserEndCapNonProofInput<F: RichField> {
    pub core: SubmitUserEndCapNonProofCoreInput<F>,
    pub contract_state_updates: Vec<QEDContractStateUpdateHistory<F>>,
}

pub struct SubmitUserEndCapNonProofCoreInput<F: RichField> {
    pub checkpoint_id: F,
    pub stats: GUTAStats<F>,
    pub state_transition: UPSEndCapResultCompact<F>,
    pub new_user_leaf: QEDUserLeaf<F>,
}
}

Fields:

Core Fields:

QProvingJobDataID

Proving job data identifier.

Structure:

#![allow(unused)]
fn main() {
pub struct QProvingJobDataID {
    pub topic: QJobTopic,
    pub goal_id: u64,
    pub slot_id: u64,
    pub circuit_type: ProvingJobCircuitType,
    pub group_id: u32,
    pub sub_group_id: u32,
    pub task_index: u32,
    pub data_type: ProvingJobDataType,
    pub data_index: u8,
}
}

Fields:

Serialization: Serialized as a 32-byte array.

Example:

{
  "topic": "GenerateStandardProof",
  "goal_id": 100,
  "slot_id": 5,
  "circuit_type": "GUTATwoEndCap",
  "group_id": 1,
  "sub_group_id": 0,
  "task_index": 0,
  "data_type": "InputWitness",
  "data_index": 0
}

VariableHeightRewardMerkleProof

Variable height Merkle proof for reward distribution.

Structure:

#![allow(unused)]
fn main() {
pub struct VariableHeightRewardMerkleProof {
    pub top_siblings: Vec<VariableHeightProofSibling>,
    pub sibling_branch: QHashOut<F>,
    pub reward_leaf: QHashOut<F>,
    pub proof_height: F,
    pub index: F,
}

pub struct VariableHeightProofSibling {
    pub sibling_branch: QHashOut<F>,
    pub sibling_reward_leaf: QHashOut<F>,
}
}

Fields:

Example:

{
  "top_siblings": [
    {
      "sibling_branch": "0x1234...",
      "sibling_reward_leaf": "0x5678..."
    }
  ],
  "sibling_branch": "0x9abc...",
  "reward_leaf": "0xdef0...",
  "proof_height": "5",
  "index": "42"
}

Field Type Notes

Throughout this API, F represents a field element type (typically GoldilocksField).

Field Element Conversion:

• Methods with _f suffix accept field elements as strings (e.g., "12345")
• Methods without _f suffix accept native types (e.g., 12345)
• Field elements are internally represented as u64 values in the Goldilocks field

Best Practices:

• Use u64 variants for better performance when possible
• Use Field variants when working with circuit inputs/outputs
• Always validate checkpoint_id exists before querying
• Handle RPC errors gracefully (missing data, invalid parameters)

Error Handling

All RPC methods return RpcResult<T> which can contain errors in the following format:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Error description"
  },
  "id": 1
}

Common Error Codes:

• -32000: Server error (checkpoint not found, data unavailable)
• -32602: Invalid parameters
• -32603: Internal error

Usage Examples

Complete Workflow Example

# 1. Check if user belongs to realm
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_check_user_id_in_realm",
    "params": [12345],
    "id": 1
  }'

# 2. Get latest L2 block state
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_latest_l2_block_state",
    "params": [],
    "id": 2
  }'

# 3. Get user leaf data at checkpoint
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_user_leaf_data",
    "params": [100, 12345],
    "id": 3
  }'

# 4. Get Merkle proof for user
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_user_tree_merkle_proof",
    "params": [100, 12345],
    "id": 4
  }'

Method Summary

Document Version: 1.0
Last Updated: 2025-10-24
Total RPC Methods: 42

Coordinator Edge RPC Documentation

This document provides comprehensive documentation for all Coordinator Edge RPC methods defined in the CoordinatorEdgeRpc trait.

RPC Namespace: qed

Table of Contents

1. User Management
2. Contract Management
3. Block Operations
4. GUTA Submission
5. Checkpoint Operations
6. Checkpoint Sync
7. L2 Block State Operations
8. User Registration Tree Operations
9. User Tree Operations
10. Contract Function Tree Operations
11. Contract Tree Operations
12. Deposit Tree Operations
13. Withdrawal Tree Operations
14. Checkpoint Tree Operations
15. Reward Proofs Generation
16. Realm Status Operations
17. Data Structures

User Management

1. register_user

Register a new user with ZK public key.

Method Name: qed_register_user

Request Parameters:

{
  "public_key": {
    "fingerprint": "0x1234...",
    "public_key_param": "0x5678..."
  }
}

Response:

{
  "result": "ok"
}

Example:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_register_user",
    "params": [{
      "fingerprint": "0x...",
      "public_key_param": "0x..."
    }],
    "id": 1
  }'

2. get_user_id

Get user ID by public key hash.

Method Name: qed_get_user_id

Request Parameters:

{
  "public_key": "0x1234567890abcdef..."
}

Response:

{
  "result": 12345
}

Example:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_user_id",
    "params": ["0x1234..."],
    "id": 1
  }'

Contract Management

3. deploy_contract

Deploy a new smart contract.

Method Name: qed_deploy_contract

Request Parameters:

{
  "deploy_contract": {
    "deployer": "0x1234...",
    "code_definition": {
      "state_tree_height": 10,
      "functions": [...]
    },
    "function_whitelist": ["0x..."]
  }
}

Response:

{
  "result": "ok"
}

Example:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_deploy_contract",
    "params": [{
      "deployer": "0x...",
      "code_definition": {...},
      "function_whitelist": [...]
    }],
    "id": 1
  }'

4. get_contract_leaf_data

Get contract leaf data by contract ID (u64 parameter).

Method Name: qed_get_contract_leaf_data

Request Parameters:

{
  "contract_id": 5
}

Response: See QEDContractLeaf

5. get_contract_leaf_data_f

Get contract leaf data by contract ID (Field parameter).

Method Name: qed_get_contract_leaf_data_f

Request Parameters:

{
  "contract_id": "5"
}

Response: See QEDContractLeaf

6. get_contract_code_definition

Get contract code definition by contract ID (u64 parameter).

Method Name: qed_get_contract_code_definition

Request Parameters:

{
  "contract_id": 5
}

Response: See ContractCodeDefinition

7. get_contract_code_definition_f

Get contract code definition by contract ID (Field parameter).

Method Name: qed_get_contract_code_definition_f

Request Parameters:

{
  "contract_id": "5"
}

Response: See ContractCodeDefinition

Block Operations

8. build_block

Trigger building a new block/checkpoint.

Method Name: qed_build_block

Request Parameters: None

Response:

{
  "result": "ok"
}

Example:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_build_block",
    "params": [],
    "id": 1
  }'

GUTA Submission

9. submit_guta

Submit GUTA (Global User Tree Aggregator) result with proof.

Method Name: qed_submit_guta

Request Parameters:

{
  "input": {
    "realm_id": 1,
    "checkpoint_id": 100,
    "guta_stats": {...},
    "top_line_proof": {...},
    "checkpoint_tree_root": "0x...",
    "proof_id": {...}
  },
  "proof": {...},
  "realm_id": 1
}

Response:

{
  "result": "ok"
}

10. submit_guta_v1

Submit GUTA result with serialized proof (v1 format).

Method Name: qed_submit_guta_v1

Request Parameters:

{
  "input": {...},
  "proof": "0x...",
  "realm_id": 1
}

Response:

{
  "result": null
}

11. submit_realm_result

Submit realm processing result to coordinator.

Method Name: qed_submit_realm_result

Request Parameters:

{
  "realm_result": {
    "header": {
      "realm_id": 1,
      "checkpoint_id": 100,
      "start_realm_root": "0x...",
      "end_realm_root": "0x...",
      "guta_stats": {...},
      "root_job_id": {...}
    },
    "proof": "0x..."
  }
}

Response:

{
  "result": null
}

Checkpoint Operations

12. get_latest_checkpoint

Get latest checkpoint information.

Method Name: qed_get_latest_checkpoint

Request Parameters: None

Response:

{
  "result": {
    "checkpoint_id": 100
  }
}

13. latest_checkpoint

Get latest checkpoint ID (simple version).

Method Name: qed_latest_checkpoint

Request Parameters: None

Response:

{
  "result": 100
}

14. get_latest_checkpoint_id

Get latest checkpoint ID.

Method Name: qed_get_latest_checkpoint_id

Request Parameters: None

Response:

{
  "result": 100
}

Example:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_latest_checkpoint_id",
    "params": [],
    "id": 1
  }'

15. get_checkpoint_leaf_data

Get checkpoint leaf data by checkpoint ID (u64 parameter).

Method Name: qed_get_checkpoint_leaf_data

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QEDCheckpointLeaf

16. get_checkpoint_leaf_data_f

Get checkpoint leaf data by checkpoint ID (Field parameter).

Method Name: qed_get_checkpoint_leaf_data_f

Request Parameters:

{
  "checkpoint_id": "100"
}

Response: See QEDCheckpointLeaf

17. get_checkpoint_global_state_roots

Get global state roots at a specific checkpoint.

Method Name: qed_get_checkpoint_global_state_roots

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QEDCheckpointGlobalStateRoots

Checkpoint Sync

18. get_checkpoint_sync_info

Get checkpoint sync information for a realm.

Method Name: qed_get_checkpoint_sync_info

Request Parameters:

{
  "realm_id": 1,
  "checkpoint_id": 100
}

Response: See CheckpointSyncInfo

19. get_checkpoint_sync_info_compact

Get compact checkpoint sync information.

Method Name: qed_get_checkpoint_sync_info_compact

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See [QEDCheckpointSyncInfoCompact](#qedcheckpointsyncinfo compact)

L2 Block State Operations

20. get_latest_l2_block_state

Get the latest L2 block state.

Method Name: qed_get_latest_l2_block_state

Request Parameters: None

Response: See QEDL2BlockState

Example Response:

{
  "result": {
    "checkpoint_id": 100,
    "next_add_withdrawal_id": 50,
    "next_process_withdrawal_id": 45,
    "next_deposit_id": 200,
    "total_deposits_claimed_epoch": 180,
    "next_user_id": 1000,
    "end_balance": 5000000,
    "next_contract_id": 25
  }
}

21. get_l2_block_state

Get L2 block state at a specific checkpoint (u64 parameter).

Method Name: qed_get_l2_block_state

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QEDL2BlockState

22. get_l2_block_state_f

Get L2 block state at a specific checkpoint (Field parameter).

Method Name: qed_get_l2_block_state_f

Request Parameters:

{
  "checkpoint_id": "100"
}

Response: See QEDL2BlockState

User Registration Tree Operations

23. get_user_registration_tree_root

Get user registration tree root at a specific checkpoint (u64 parameter).

Method Name: qed_get_user_registration_tree_root

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QHashOut

24. get_user_registration_tree_root_f

Get user registration tree root at a specific checkpoint (Field parameter).

Method Name: qed_get_user_registration_tree_root_f

Request Parameters:

{
  "checkpoint_id": "100"
}

Response: See QHashOut

25. get_user_registration_tree_leaf_hash

Get user registration tree leaf hash (u64 parameters).

Method Name: qed_get_user_registration_tree_leaf_hash

Request Parameters:

{
  "checkpoint_id": 100,
  "leaf_index": 42
}

Response: See QHashOut

26. get_user_registration_tree_leaf_hash_f

Get user registration tree leaf hash (Field parameters).

Method Name: qed_get_user_registration_tree_leaf_hash_f

Request Parameters:

{
  "checkpoint_id": "100",
  "leaf_index": "42"
}

Response: See QHashOut

27. get_user_registration_tree_merkle_proof

Get Merkle proof for user registration tree (u64 parameters).

Method Name: qed_get_user_registration_tree_merkle_proof

Request Parameters:

{
  "checkpoint_id": 100,
  "leaf_index": 42
}

Response: See MerkleProofCore

28. get_user_registration_tree_merkle_proof_f

Get Merkle proof for user registration tree (Field parameters).

Method Name: qed_get_user_registration_tree_merkle_proof_f

Request Parameters:

{
  "checkpoint_id": "100",
  "leaf_index": "42"
}

Response: See MerkleProofCore

User Tree Operations

29. get_user_tree_root

Get user tree root at a specific checkpoint (u64 parameter).

Method Name: qed_get_user_tree_root

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QHashOut

30. get_user_tree_root_f

Get user tree root at a specific checkpoint (Field parameter).

Method Name: qed_get_user_tree_root_f

Request Parameters:

{
  "checkpoint_id": "100"
}

Response: See QHashOut

31. get_user_sub_tree_merkle_proof

Get Merkle proof for user sub-tree.

Method Name: qed_get_user_sub_tree_merkle_proof

Request Parameters:

{
  "checkpoint_id": 100,
  "root_level": 5,
  "leaf_level": 2,
  "leaf_index": 42
}

Response: See MerkleProofCore

32. get_user_top_tree_merkle_proof

Get Merkle proof for user top tree.

Method Name: qed_get_user_top_tree_merkle_proof

Request Parameters:

{
  "checkpoint_id": 100,
  "leaf_level": 2,
  "leaf_index": 42
}

Response: See MerkleProofCore

33. get_user_top_tree_cap_root

Get user top tree cap root.

Method Name: qed_get_user_top_tree_cap_root

Request Parameters:

{
  "checkpoint_id": 100,
  "cap_level": 3,
  "cap_index": 10
}

Response: See QHashOut

34. get_user_latest_top_tree_cap_root

Get latest user top tree cap root.

Method Name: qed_get_user_latest_top_tree_cap_root

Request Parameters:

{
  "cap_level": 3,
  "cap_index": 10
}

Response: See QHashOut

35. get_user_leaf_data

Get user leaf data at a specific checkpoint.

Method Name: qed_get_user_leaf_data

Request Parameters:

{
  "checkpoint_id": 100,
  "user_id": 12345
}

Response: See QEDUserLeaf

36. get_user_tree_merkle_proof

Get Merkle proof for user tree (u64 parameters).

Method Name: qed_get_user_tree_merkle_proof

Request Parameters:

{
  "checkpoint_id": 100,
  "user_id": 12345
}

Response: See MerkleProofCore

37. get_user_tree_merkle_proof_f

Get Merkle proof for user tree (Field parameters).

Method Name: qed_get_user_tree_merkle_proof_f

Request Parameters:

{
  "checkpoint_id": "100",
  "user_id": "12345"
}

Response: See MerkleProofCore

Contract Function Tree Operations

38. get_contract_function_tree_root

Get contract function tree root (u64 parameters).

Method Name: qed_get_contract_function_tree_root

Request Parameters:

{
  "checkpoint_id": 100,
  "contract_id": 5
}

Response: See QHashOut

39. get_contract_function_tree_root_f

Get contract function tree root (Field parameters).

Method Name: qed_get_contract_function_tree_root_f

Request Parameters:

{
  "checkpoint_id": "100",
  "contract_id": "5"
}

Response: See QHashOut

40. get_contract_function_tree_leaf_hash

Get contract function tree leaf hash (u64 parameters).

Method Name: qed_get_contract_function_tree_leaf_hash

Request Parameters:

{
  "checkpoint_id": 100,
  "contract_id": 5,
  "function_id": 3
}

Response: See QHashOut

41. get_contract_function_tree_leaf_hash_f

Get contract function tree leaf hash (Field parameters).

Method Name: qed_get_contract_function_tree_leaf_hash_f

Request Parameters:

{
  "checkpoint_id": "100",
  "contract_id": "5",
  "function_id": "3"
}

Response: See QHashOut

42. get_contract_function_tree_merkle_proof

Get Merkle proof for contract function tree (u64 parameters).

Method Name: qed_get_contract_function_tree_merkle_proof

Request Parameters:

{
  "checkpoint_id": 100,
  "contract_id": 5,
  "function_id": 3
}

Response: See MerkleProofCore

43. get_contract_function_tree_merkle_proof_f

Get Merkle proof for contract function tree (Field parameters).

Method Name: qed_get_contract_function_tree_merkle_proof_f

Request Parameters:

{
  "checkpoint_id": "100",
  "contract_id": "5",
  "function_id": "3"
}

Response: See MerkleProofCore

Contract Tree Operations

44. get_contract_tree_root

Get contract tree root at a specific checkpoint (u64 parameter).

Method Name: qed_get_contract_tree_root

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QHashOut

45. get_contract_tree_root_f

Get contract tree root at a specific checkpoint (Field parameter).

Method Name: qed_get_contract_tree_root_f

Request Parameters:

{
  "checkpoint_id": "100"
}

Response: See QHashOut

46. get_contract_tree_leaf_hash

Get contract tree leaf hash (u64 parameters).

Method Name: qed_get_contract_tree_leaf_hash

Request Parameters:

{
  "checkpoint_id": 100,
  "contract_id": 5
}

Response: See QHashOut

47. get_contract_tree_leaf_hash_f

Get contract tree leaf hash (Field parameters).

Method Name: qed_get_contract_tree_leaf_hash_f

Request Parameters:

{
  "checkpoint_id": "100",
  "contract_id": "5"
}

Response: See QHashOut

48. get_contract_tree_merkle_proof

Get Merkle proof for contract tree (u64 parameters).

Method Name: qed_get_contract_tree_merkle_proof

Request Parameters:

{
  "checkpoint_id": 100,
  "contract_id": 5
}

Response: See MerkleProofCore

49. get_contract_tree_merkle_proof_f

Get Merkle proof for contract tree (Field parameters).

Method Name: qed_get_contract_tree_merkle_proof_f

Request Parameters:

{
  "checkpoint_id": "100",
  "contract_id": "5"
}

Response: See MerkleProofCore

Deposit Tree Operations

50. get_deposit_tree_root

Get deposit tree root at a specific checkpoint (u64 parameter).

Method Name: qed_get_deposit_tree_root

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QHashOut

51. get_deposit_tree_root_f

Get deposit tree root at a specific checkpoint (Field parameter).

Method Name: qed_get_deposit_tree_root_f

Request Parameters:

{
  "checkpoint_id": "100"
}

Response: See QHashOut

52. get_deposit_tree_leaf_hash

Get deposit tree leaf hash (u64 parameters).

Method Name: qed_get_deposit_tree_leaf_hash

Request Parameters:

{
  "checkpoint_id": 100,
  "deposit_id": 42
}

Response: See QHashOut

53. get_deposit_tree_leaf_hash_f

Get deposit tree leaf hash (Field parameters).

Method Name: qed_get_deposit_tree_leaf_hash_f

Request Parameters:

{
  "checkpoint_id": "100",
  "deposit_id": "42"
}

Response: See QHashOut

54. get_deposit_tree_merkle_proof

Get Merkle proof for deposit tree (u64 parameters).

Method Name: qed_get_deposit_tree_merkle_proof

Request Parameters:

{
  "checkpoint_id": 100,
  "deposit_id": 42
}

Response: See MerkleProofCore

55. get_deposit_tree_merkle_proof_f

Get Merkle proof for deposit tree (Field parameters).

Method Name: qed_get_deposit_tree_merkle_proof_f

Request Parameters:

{
  "checkpoint_id": "100",
  "deposit_id": "42"
}

Response: See MerkleProofCore

Withdrawal Tree Operations

56. get_withdrawal_tree_root

Get withdrawal tree root at a specific checkpoint (u64 parameter).

Method Name: qed_get_withdrawal_tree_root

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QHashOut

57. get_withdrawal_tree_root_f

Get withdrawal tree root at a specific checkpoint (Field parameter).

Method Name: qed_get_withdrawal_tree_root_f

Request Parameters:

{
  "checkpoint_id": "100"
}

Response: See QHashOut

58. get_withdrawal_tree_leaf_hash

Get withdrawal tree leaf hash (u64 parameters).

Method Name: qed_get_withdrawal_tree_leaf_hash

Request Parameters:

{
  "checkpoint_id": 100,
  "withdrawal_id": 42
}

Response: See QHashOut

59. get_withdrawal_tree_leaf_hash_f

Get withdrawal tree leaf hash (Field parameters).

Method Name: qed_get_withdrawal_tree_leaf_hash_f

Request Parameters:

{
  "checkpoint_id": "100",
  "withdrawal_id": "42"
}

Response: See QHashOut

60. get_withdrawal_tree_merkle_proof

Get Merkle proof for withdrawal tree (u64 parameters).

Method Name: qed_get_withdrawal_tree_merkle_proof

Request Parameters:

{
  "checkpoint_id": 100,
  "withdrawal_id": 42
}

Response: See MerkleProofCore

61. get_withdrawal_tree_merkle_proof_f

Get Merkle proof for withdrawal tree (Field parameters).

Method Name: qed_get_withdrawal_tree_merkle_proof_f

Request Parameters:

{
  "checkpoint_id": "100",
  "withdrawal_id": "42"
}

Response: See MerkleProofCore

Checkpoint Tree Operations

62. get_latest_checkpoint_tree_root

Get the latest checkpoint tree root.

Method Name: qed_get_latest_checkpoint_tree_root

Request Parameters: None

Response: See QHashOut

63. get_checkpoint_tree_root

Get checkpoint tree root at a specific checkpoint (u64 parameter).

Method Name: qed_get_checkpoint_tree_root

Request Parameters:

{
  "checkpoint_id": 100
}

Response: See QHashOut

64. get_checkpoint_tree_root_f

Get checkpoint tree root at a specific checkpoint (Field parameter).

Method Name: qed_get_checkpoint_tree_root_f

Request Parameters:

{
  "checkpoint_id": "100"
}

Response: See QHashOut

65. get_checkpoint_tree_leaf_hash

Get checkpoint tree leaf hash (u64 parameters).

Method Name: qed_get_checkpoint_tree_leaf_hash

Request Parameters:

{
  "checkpoint_id": 100,
  "leaf_checkpoint_id": 95
}

Response: See QHashOut

66. get_checkpoint_tree_leaf_hash_f

Get checkpoint tree leaf hash (Field parameters).

Method Name: qed_get_checkpoint_tree_leaf_hash_f

Request Parameters:

{
  "checkpoint_id": "100",
  "leaf_checkpoint_id": "95"
}

Response: See QHashOut

67. get_checkpoint_tree_merkle_proof

Get Merkle proof for checkpoint tree (u64 parameters).

Method Name: qed_get_checkpoint_tree_merkle_proof

Request Parameters:

{
  "checkpoint_id": 100,
  "leaf_checkpoint_id": 95
}

Response: See MerkleProofCore

68. get_checkpoint_tree_merkle_proof_f

Get Merkle proof for checkpoint tree (Field parameters).

Method Name: qed_get_checkpoint_tree_merkle_proof_f

Request Parameters:

{
  "checkpoint_id": "100",
  "leaf_checkpoint_id": "95"
}

Response: See MerkleProofCore

Reward Proofs Generation

69. generate_batch_variable_height_reward_proofs

Generate batch variable height reward Merkle proofs for multiple job IDs.

Method Name: qed_generate_batch_variable_height_reward_proofs

Request Parameters:

{
  "checkpoint_id": 100,
  "job_ids": [
    {
      "topic": "GenerateStandardProof",
      "goal_id": 100,
      "slot_id": 5,
      "circuit_type": "GUTATwoEndCap",
      "group_id": 1,
      "sub_group_id": 0,
      "task_index": 0,
      "data_type": "InputWitness",
      "data_index": 0
    }
  ]
}

Response:

{
  "result": [
    [
      {
        "top_siblings": [...],
        "sibling_branch": "0x...",
        "reward_leaf": "0x...",
        "proof_height": "5",
        "index": "42"
      },
      {
        "topic": "GenerateStandardProof",
        "goal_id": 100,
        ...
      }
    ]
  ]
}

70. get_graphviz

Get GraphViz representation of the job dependency graph at a specific checkpoint.

Method Name: qed_get_graphviz

Request Parameters:

{
  "checkpoint_id": 100
}

Response:

{
  "result": "digraph G {\n  node1 -> node2;\n  ...\n}"
}

Example:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_graphviz",
    "params": [100],
    "id": 1
  }' | jq -r '.result' | dot -Tpng > graph.png

Realm Status Operations

71. get_current_realm_status_on_coordinator

Get current realm status on the coordinator.

Method Name: qed_get_current_realm_status_on_coordinator

Request Parameters:

{
  "realm_id": 1
}

Response: See BasicRealmStatusOnCoordinator

Example Response:

{
  "result": {
    "realm_id": 1,
    "checkpoint_id": 100,
    "realm_root_hash": "0x..."
  }
}

72. get_current_checkpoint_id

Get current coordinator checkpoint ID.

Method Name: qed_get_current_checkpoint_id

Request Parameters: None

Response:

{
  "result": 100
}

73. get_latest_block_updates_from_coordinator

Get latest block updates from coordinator for a realm within a checkpoint range.

Method Name: qed_get_latest_block_updates_from_coordinator

Request Parameters:

{
  "realm_id": 1,
  "from_checkpoint": 95,
  "to_checkpoint": 100
}

Response:

{
  "result": [
    {
      "latest_checkpoint_id": 100,
      "description": null,
      "source_coordinator_edge_id": null,
      "sync_timestamp": 1234567890,
      "compact": {...},
      "realm_root": "0x..."
    }
  ]
}

74. wait_until_coordinator_completed

Wait until coordinator completes a specific checkpoint for a realm.

Method Name: qed_wait_until_coordinator_completed

Request Parameters:

{
  "realm_id": 1,
  "checkpoint_id": 100
}

Response: See GlobalBlockUpdateFromCoordinator

Data Structures

QHashOut

A hash output wrapper for Plonky2 field elements.

Structure:

#![allow(unused)]
fn main() {
pub struct QHashOut<F: Field>(pub HashOut<F>);
}

JSON Representation:

"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

Description:

• Wraps a Plonky2 HashOut<F> containing 4 field elements
• Serialized as a hexadecimal string (32 bytes)
• Represents a 256-bit hash value

QEDL2BlockState

L2 block state information at a specific checkpoint.

Structure:

#![allow(unused)]
fn main() {
pub struct QEDL2BlockState {
    pub checkpoint_id: u64,
    pub next_add_withdrawal_id: u64,
    pub next_process_withdrawal_id: u64,
    pub next_deposit_id: u64,
    pub total_deposits_claimed_epoch: u64,
    pub next_user_id: u64,
    pub end_balance: u64,
    pub next_contract_id: u32,
}
}

Fields:

Example:

{
  "checkpoint_id": 100,
  "next_add_withdrawal_id": 50,
  "next_process_withdrawal_id": 45,
  "next_deposit_id": 200,
  "total_deposits_claimed_epoch": 180,
  "next_user_id": 1000,
  "end_balance": 5000000,
  "next_contract_id": 25
}

QEDCheckpointLeaf

Checkpoint leaf data containing global chain root and statistics.

Structure:

#![allow(unused)]
fn main() {
pub struct QEDCheckpointLeaf<F: RichField> {
    pub global_chain_root: QHashOut<F>,
    pub stats: QEDCheckpointLeafStats<F>,
}
}

Fields:

QEDCheckpointGlobalStateRoots

Global state roots at a specific checkpoint.

Structure:

#![allow(unused)]
fn main() {
pub struct QEDCheckpointGlobalStateRoots<F: RichField> {
    pub contract_tree_root: QHashOut<F>,
    pub deposit_tree_root: QHashOut<F>,
    pub user_tree_root: QHashOut<F>,
    pub withdrawal_tree_root: QHashOut<F>,
    pub user_registration_tree_root: QHashOut<F>,
}
}

Fields:

Example:

{
  "contract_tree_root": "0x1234...",
  "deposit_tree_root": "0x5678...",
  "user_tree_root": "0x9abc...",
  "withdrawal_tree_root": "0xdef0...",
  "user_registration_tree_root": "0x1234..."
}

QEDUserLeaf

User leaf data containing user state information.

Structure:

#![allow(unused)]
fn main() {
pub struct QEDUserLeaf<F: RichField> {
    pub public_key: QHashOut<F>,
    pub user_state_tree_root: QHashOut<F>,
    pub balance: F,
    pub nonce: F,
    pub last_checkpoint_id: F,
    pub event_index: F,
    pub user_id: F,
}
}

Fields:

Example:

{
  "public_key": "0x1234...",
  "user_state_tree_root": "0x5678...",
  "balance": "1000000",
  "nonce": "42",
  "last_checkpoint_id": "100",
  "event_index": "15",
  "user_id": "12345"
}

MerkleProofCore

Generic Merkle proof structure.

Structure:

#![allow(unused)]
fn main() {
pub struct MerkleProofCore<Hash: PartialEq + Copy> {
    pub root: Hash,
    pub value: Hash,
    pub index: u64,
    pub siblings: Vec<Hash>,
}
}

Fields:

Example:

{
  "root": "0x1234...",
  "value": "0x5678...",
  "index": 42,
  "siblings": [
    "0x9abc...",
    "0xdef0...",
    "0x1234..."
  ]
}

ZKPublicKeyInfo

Zero-knowledge public key information.

Structure:

#![allow(unused)]
fn main() {
pub struct ZKPublicKeyInfo<F: RichField> {
    pub fingerprint: QHashOut<F>,
    pub public_key_param: QHashOut<F>,
}
}

Fields:

Example:

{
  "fingerprint": "0x1234...",
  "public_key_param": "0x5678..."
}

QBCDeployContract

Contract deployment command.

Structure:

#![allow(unused)]
fn main() {
pub struct QBCDeployContract<F: RichField> {
    pub deployer: QHashOut<F>,
    pub code_definition: ContractCodeDefinition,
    pub function_whitelist: Vec<QHashOut<F>>,
}
}

Fields:

Example:

{
  "deployer": "0x1234...",
  "code_definition": {
    "state_tree_height": 10,
    "functions": [...]
  },
  "function_whitelist": ["0x5678..."]
}

ContractCodeDefinition

Contract code definition structure.

Structure:

#![allow(unused)]
fn main() {
pub struct ContractCodeDefinition {
    pub state_tree_height: u16,
    pub functions: Vec<ContractFunctionCodeDefinition>,
}

pub struct ContractFunctionCodeDefinition {
    pub method_id: u32,
    pub num_inputs: u32,
    pub num_outputs: u32,
    pub vm_type: u32,
    pub code: Vec<u8>,
}
}

Fields:

Function Fields:

Example:

{
  "state_tree_height": 10,
  "functions": [
    {
      "method_id": 12345678,
      "num_inputs": 2,
      "num_outputs": 1,
      "vm_type": 1,
      "code": [0x01, 0x02, ...]
    }
  ]
}

QEDContractLeaf

Contract leaf data.

Structure:

#![allow(unused)]
fn main() {
pub struct QEDContractLeaf<F: RichField> {
    pub deployer: QHashOut<F>,
    pub function_tree_root: QHashOut<F>,
    pub state_tree_height: F,
}
}

Fields:

Example:

{
  "deployer": "0x1234...",
  "function_tree_root": "0x5678...",
  "state_tree_height": "10"
}

CheckpointSyncInfo

Checkpoint synchronization information.

Structure:

#![allow(unused)]
fn main() {
pub struct CheckpointSyncInfo<F: RichField> {
    pub latest_checkpoint_id: u64,
    pub description: Option<String>,
    pub source_coordinator_edge_id: Option<String>,
    pub sync_timestamp: u64,
    pub compact: QEDCheckpointSyncInfoCompact<F>,
    pub realm_root: QHashOut<F>,
}
}

Fields:

QEDCheckpointSyncInfoCompact

Compact checkpoint synchronization information.

Structure:

#![allow(unused)]
fn main() {
pub struct QEDCheckpointSyncInfoCompact<F: RichField> {
    pub l2_block_state: QEDL2BlockState,
    pub stats: QEDCheckpointLeafStats<F>,
    pub state_roots: QEDCheckpointGlobalStateRoots<F>,
    pub checkpoint_tree_update_siblings: Vec<QHashOut<F>>,
    pub regsitered_users_start_pivot_siblings: Vec<QHashOut<F>>,
    pub registered_users: Vec<ZKPublicKeyInfo<F>>,
    pub old_checkpoint_leaf_hash: QHashOut<F>,
    pub slot: u64,
}
}

Fields:

SubmitGUTARealmResultAPINoProofInput

GUTA submission input without proof.

Structure:

#![allow(unused)]
fn main() {
pub struct SubmitGUTARealmResultAPINoProofInput<F: RichField> {
    pub realm_id: u64,
    pub checkpoint_id: u64,
    pub guta_stats: GUTAStats<F>,
    pub top_line_proof: DeltaMerkleProofCore<QHashOut<F>>,
    pub checkpoint_tree_root: QHashOut<F>,
    pub proof_id: QProvingJobDataID,
}
}

Fields:

QProvingJobDataID

Proving job data identifier.

Structure:

#![allow(unused)]
fn main() {
pub struct QProvingJobDataID {
    pub topic: QJobTopic,
    pub goal_id: u64,
    pub slot_id: u64,
    pub circuit_type: ProvingJobCircuitType,
    pub group_id: u32,
    pub sub_group_id: u32,
    pub task_index: u32,
    pub data_type: ProvingJobDataType,
    pub data_index: u8,
}
}

Fields:

Serialization: Serialized as a 32-byte array.

VariableHeightRewardMerkleProof

Variable height Merkle proof for reward distribution.

Structure:

#![allow(unused)]
fn main() {
pub struct VariableHeightRewardMerkleProof {
    pub top_siblings: Vec<VariableHeightProofSibling>,
    pub sibling_branch: QHashOut<F>,
    pub reward_leaf: QHashOut<F>,
    pub proof_height: F,
    pub index: F,
}

pub struct VariableHeightProofSibling {
    pub sibling_branch: QHashOut<F>,
    pub sibling_reward_leaf: QHashOut<F>,
}
}

Fields:

BasicRealmStatusOnCoordinator

Basic realm status on the coordinator.

Structure:

#![allow(unused)]
fn main() {
pub struct BasicRealmStatusOnCoordinator<F: RichField> {
    pub realm_id: u64,
    pub checkpoint_id: u64,
    pub realm_root_hash: QHashOut<F>,
}
}

Fields:

Example:

{
  "realm_id": 1,
  "checkpoint_id": 100,
  "realm_root_hash": "0x1234..."
}

GlobalBlockUpdateFromCoordinator

Type alias for CheckpointSyncInfo<F>.

#![allow(unused)]
fn main() {
pub type GlobalBlockUpdateFromCoordinator<F> = CheckpointSyncInfo<F>;
}

See CheckpointSyncInfo for structure details.

RealmDataForCoordinator

Realm data submitted to coordinator.

Structure:

#![allow(unused)]
fn main() {
pub struct RealmDataForCoordinator<F: RichField> {
    pub header: RealmDataForCoordinatorHeader<F>,
    pub proof: Vec<u8>,
}

pub struct RealmDataForCoordinatorHeader<F: RichField> {
    pub realm_id: u64,
    pub checkpoint_id: u64,
    pub start_realm_root: QHashOut<F>,
    pub end_realm_root: QHashOut<F>,
    pub guta_stats: GUTAStats<F>,
    pub root_job_id: QProvingJobDataID,
}
}

Fields:

Header Fields:

Field Type Notes

Throughout this API, F represents a field element type (typically GoldilocksField).

Field Element Conversion:

• Methods with _f suffix accept field elements as strings (e.g., "12345")
• Methods without _f suffix accept native types (e.g., 12345)
• Field elements are internally represented as u64 values in the Goldilocks field

Best Practices:

• Use u64 variants for better performance when possible
• Use Field variants when working with circuit inputs/outputs
• Always validate checkpoint_id exists before querying
• Handle RPC errors gracefully (missing data, invalid parameters)

Error Handling

All RPC methods return RpcResult<T> which can contain errors in the following format:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Error description"
  },
  "id": 1
}

Common Error Codes:

• -32000: Server error (checkpoint not found, data unavailable)
• -32602: Invalid parameters
• -32603: Internal error
• -32001: Not found error

Usage Examples

Complete User Registration Workflow

# 1. Register a new user
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_register_user",
    "params": [{
      "fingerprint": "0x...",
      "public_key_param": "0x..."
    }],
    "id": 1
  }'

# 2. Get user ID by public key
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_user_id",
    "params": ["0x..."],
    "id": 2
  }'

# 3. Get user leaf data
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_user_leaf_data",
    "params": [100, 12345],
    "id": 3
  }'

Contract Deployment Workflow

# 1. Deploy contract
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_deploy_contract",
    "params": [{
      "deployer": "0x...",
      "code_definition": {
        "state_tree_height": 10,
        "functions": [...]
      },
      "function_whitelist": [...]
    }],
    "id": 1
  }'

# 2. Get contract leaf data
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_contract_leaf_data",
    "params": [5],
    "id": 2
  }'

# 3. Get contract code definition
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_contract_code_definition",
    "params": [5],
    "id": 3
  }'

Checkpoint Query Workflow

# 1. Get latest checkpoint ID
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_latest_checkpoint_id",
    "params": [],
    "id": 1
  }'

# 2. Get checkpoint leaf data
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_checkpoint_leaf_data",
    "params": [100],
    "id": 2
  }'

# 3. Get checkpoint global state roots
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "qed_get_checkpoint_global_state_roots",
    "params": [100],
    "id": 3
  }'

Method Summary

Document Version: 1.0
Last Updated: 2025-10-24
Total RPC Methods: 74