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