ceremonyclient/protobufs/application.proto

syntax = "proto3";

package quilibrium.node.application.pb;

option go_package = "source.quilibrium.com/quilibrium/monorepo/node/protobufs";

message Message {
  bytes hash = 1;
  bytes address = 2;
  bytes payload = 3;
}

// The HypergraphPhaseSet defines the specific phase set for further operation.
enum HypergraphPhaseSet {
  HYPERGRAPH_PHASE_SET_VERTEX_ADDS = 0;
  HYPERGRAPH_PHASE_SET_VERTEX_REMOVES = 1;
  HYPERGRAPH_PHASE_SET_HYPEREDGE_ADDS = 2;
  HYPERGRAPH_PHASE_SET_HYPEREDGE_REMOVES = 3;
}

message HypersyncMetadata {
  uint64 leaves = 1;
  bytes root_commitment = 2;
}

// Defines the request for comparison of hypergraph data
message HypergraphComparisonQuery {
  // The shard to compare.
  bytes shard_key = 1;
  // The phase set to compare.
  HypergraphPhaseSet phase_set = 2;
  // The branch path (sequence of nibble indices) in the vector commitment tree.
  repeated int32 path = 3;
  // The commitment for the node at this path.
  bytes commitment = 4;
  // For branch nodes, a list of its immediate children (by index) and their
  // commitments. When the list is empty, it means either the node is a leaf or
  // no children diff info is needed.
  repeated BranchChild children = 5;
  // If set, the comparison response will contain the data of leaves if present
  // in the results.
  bool include_leaf_data = 6;
  // The expected commit root the client wants to sync against. When set, the
  // server will attempt to find a snapshot with a matching commit root. If no
  // matching snapshot exists, the server may return the latest available.
  bytes expected_root = 7;
}

// Defines the response containing the commitment for a node and (optionally)
// its immediate children. The children are identified by their index (0–63) and
// their commitments.
message HypergraphComparisonResponse {
  // The branch path for this node.
  repeated int32 path = 1;
  // The commitment for the node at this path.
  bytes commitment = 2;
  // If non-empty, a list of children for which the node can report commitments.
  // (For instance, if the node is a branch you may want to send the commitment
  // for each child.)
  repeated BranchChild children = 3;
  // If set, indicates the response is for the root of the given set tree.
  bool is_root = 4;
}

// Defines the child commitment.
message BranchChild {
  // The index on the branch's children.
  int32 index = 1;
  // The commitment of the data.
  bytes commitment = 2;
}

// Defines the data of the leaf.
message LeafData {
  // The full key of the leaf.
  bytes key = 1;
  // The value for the leaf.
  bytes value = 2;
  // The hash target if any.
  bytes hash_target = 3;
  // The size, represented as big endian unsigned bytes.
  bytes size = 4;
  // The underlying data backing the leaf, if a vertex.
  bytes underlying_data = 5;
}

// Defines the bidirectional sync payload options.
message HypergraphComparison {
  oneof payload {
    HypergraphComparisonQuery query = 1;
    HypergraphComparisonResponse response = 2;
    LeafData leaf_data = 3;
    HypersyncMetadata metadata = 4;
  }
}

// Multiproof contains the cryptographic proof data
message Multiproof {
  bytes multicommitment = 1;
  bytes proof = 2;
}

// Path represents a sequence of indices through the tree
message Path {
  repeated uint64 indices = 1;
}

// TraversalSubProof contains proof data for a single path traversal
message TraversalSubProof {
  repeated bytes commits = 1;
  repeated bytes ys = 2;
  repeated Path paths = 3;
}

// TraversalProof is the main proof structure for tree traversals
message TraversalProof {
  Multiproof multiproof = 1;
  repeated TraversalSubProof sub_proofs = 2;
}

message GetChildrenForPathRequest {
  // The shard key
  bytes shard_key = 1;
  // The path to request
  repeated uint32 path = 2;
  // The phase set to compare.
  HypergraphPhaseSet phase_set = 3;
}

message TreePathLeaf {
  // The key associated with the leaf
  bytes key = 1;
  // The raw value associated with the leaf
	bytes value = 2;
  // The hash target of the leaf, if applicable
	bytes hash_target = 3;
  // The commitment of the leaf
	bytes commitment = 4;
  // The big endian encoded size of the leaf
	bytes size = 5;
}

message TreePathBranch {
  // The prefix segment of the branch that exists only within the branch
  repeated uint32 prefix = 1;
  // The commitment of the branch
	bytes commitment = 2;
  // The big endian encoded size of the branch
	bytes size = 3;
  // The number of leaves under the branch
	uint64 leaf_count = 4;
  // The longest branch length under the branch
	uint32 longest_branch = 5;
  // The full path prefix to the branch
	repeated uint32 full_prefix = 6;
}

message TreePathSegment {
  uint32 index = 1;
  oneof segment {
    TreePathLeaf leaf = 2;
    TreePathBranch branch = 3;
  }
}

message TreePathSegments {
  repeated TreePathSegment segments = 1;
}

message GetChildrenForPathResponse {
  repeated TreePathSegments path_segments = 1;
}

// A bidirectional streaming service in which nodes send queries for a
// particular hypergraph shard phase set (identified by its key, phase and path)
// and the other responds with the commitment for that branch and its children.
// Note: this should be used for synchronization purposes only – attempting to
// use this as a query service will explicitly reveal the query data to the
// node.
service HypergraphComparisonService {
  rpc HyperStream(stream HypergraphComparison) returns (stream HypergraphComparison);
  rpc GetChildrenForPath(GetChildrenForPathRequest) returns (GetChildrenForPathResponse);

  // PerformSync provides a client-driven sync interface. Unlike HyperStream
  // which requires both sides to walk in lockstep, PerformSync uses a simple
  // request/response pattern where the client navigates the server's tree
  // and fetches data as needed.
  rpc PerformSync(stream HypergraphSyncQuery) returns (stream HypergraphSyncResponse);
}

// HypergraphSyncQuery wraps request types for the client-driven sync RPC.
message HypergraphSyncQuery {
  oneof request {
    HypergraphSyncGetBranchRequest get_branch = 1;
    HypergraphSyncGetLeavesRequest get_leaves = 2;
  }
}

// HypergraphSyncResponse wraps response types for the client-driven sync RPC.
message HypergraphSyncResponse {
  oneof response {
    HypergraphSyncBranchResponse branch = 1;
    HypergraphSyncLeavesResponse leaves = 2;
    HypergraphSyncError error = 3;
  }
}

// HypergraphSyncGetBranchRequest queries for branch information at a path.
message HypergraphSyncGetBranchRequest {
  // The shard key (35 bytes: L1 bloom filter (3) + L2 app address (32)).
  bytes shard_key = 1;
  // The phase set to query.
  HypergraphPhaseSet phase_set = 2;
  // The path to query. Empty path queries the root.
  repeated int32 path = 3;
  // The expected root commitment the client wants to sync against. When set,
  // the server will attempt to find a snapshot with a matching root. If empty,
  // the server uses the latest available snapshot.
  bytes expected_root = 4;
}

// HypergraphSyncBranchResponse contains branch information at the queried path.
message HypergraphSyncBranchResponse {
  // The full path to this node, including any compressed prefix.
  // This may be longer than the requested path due to path compression.
  repeated int32 full_path = 1;
  // The commitment (hash) for this node.
  bytes commitment = 2;
  // Child information. Empty if this is a leaf node.
  repeated HypergraphSyncChildInfo children = 3;
  // True if this node is a leaf (has no children).
  bool is_leaf = 4;
  // The number of leaves under this node (for progress estimation).
  uint64 leaf_count = 5;
}

// HypergraphSyncChildInfo contains summary information about a child node.
message HypergraphSyncChildInfo {
  // The child index (0-63 for a 64-ary tree).
  int32 index = 1;
  // The commitment (hash) for this child.
  bytes commitment = 2;
}

// HypergraphSyncGetLeavesRequest requests all leaves under a subtree.
message HypergraphSyncGetLeavesRequest {
  // The shard key.
  bytes shard_key = 1;
  // The phase set to query.
  HypergraphPhaseSet phase_set = 2;
  // The path to the subtree root.
  repeated int32 path = 3;
  // Maximum number of leaves to return (0 = server default).
  uint32 max_leaves = 4;
  // Continuation token for pagination. Empty for first request.
  bytes continuation_token = 5;
  // The expected root commitment the client wants to sync against. When set,
  // the server will attempt to find a snapshot with a matching root. If empty,
  // the server uses the latest available snapshot.
  bytes expected_root = 6;
}

// HypergraphSyncLeavesResponse contains leaves from the requested subtree.
message HypergraphSyncLeavesResponse {
  // Echoed path from the request.
  repeated int32 path = 1;
  // The leaves under this path (reuses existing LeafData message).
  repeated LeafData leaves = 2;
  // Continuation token if more leaves remain. Empty if this is the last batch.
  bytes continuation_token = 3;
  // Total number of leaves under this path (for progress tracking).
  uint64 total_leaves = 4;
}

// HypergraphSyncError reports an error during sync.
message HypergraphSyncError {
  // Error code for programmatic handling.
  HypergraphSyncErrorCode code = 1;
  // Human-readable error message.
  string message = 2;
  // The path where the error occurred, if applicable.
  repeated int32 path = 3;
}

// HypergraphSyncErrorCode enumerates possible sync errors.
enum HypergraphSyncErrorCode {
  HYPERGRAPH_SYNC_ERROR_UNKNOWN = 0;
  HYPERGRAPH_SYNC_ERROR_INVALID_SHARD_KEY = 1;
  HYPERGRAPH_SYNC_ERROR_INVALID_PATH = 2;
  HYPERGRAPH_SYNC_ERROR_NODE_NOT_FOUND = 3;
  HYPERGRAPH_SYNC_ERROR_SNAPSHOT_UNAVAILABLE = 4;
  HYPERGRAPH_SYNC_ERROR_INTERNAL = 5;
}