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