RPC Reference

This page follows protocol/SPECIFICATION.md as the normative source of truth.

This page documents the canonical V2 RPC contract from protocol/SPECIFICATION.md.

Write operations

`SubmitMessage`

Accepts a fully signed Message.

In V2, all committed block messages are user-submitted and carry Ed25519 envelopes. Disabled relay-era message families must be rejected.

`BatchSubmitMessages`

Accepts a bounded list of signed Message values and returns per-message results.

`DryRunMessage`

Validates a signed Message against current state without mempool admission.

Merge-request reads

`GetMergeRequest`

Returns one active merge request identified by (project_id, request_id).

Field	Type	Description
`project_id`	bytes (32)	Target project ID
`request_id`	bytes (32)	Content-addressed merge request ID

Returns NOT_FOUND if the merge request is absent, removed, or pruned.

`ListMergeRequests`

Returns active merge requests under a target project prefix with cursor-based pagination and an optional requester_owner_address filter.

Field	Type	Description
`project_id`	bytes (32)	Target project ID
`limit`	uint32	Page size (max 200)
`cursor`	bytes	Opaque pagination cursor
`requester_owner_address`	bytes (20)	Optional requester filter

Results are ordered by forward-key lexicographic order (equivalent to request_id order within a project).

`ListMergeRequestsByRequester`

Returns active merge requests opened by a specific owner_address, ordered by reverse-key lexicographic order.

Field	Type	Description
`owner_address`	bytes (20)	Requester owner address
`limit`	uint32	Page size (max 200)
`cursor`	bytes	Opaque pagination cursor

`MergeRequestSummary`

All three merge-request RPCs return MergeRequestSummary entries with the following fields:

Field	Type	Description
`request_id`	bytes (32)	Content-addressed merge request ID
`project_id`	bytes (32)	Target (upstream) project ID
`requester_owner_address`	bytes (20)	Original requester's owner address
`source_project_id`	bytes (32)	Source fork-descendant project ID
`source_ref`	bytes	Branch or ref name in the source project
`source_commit_hash`	bytes (32)	Head commit of proposed changes
`target_ref`	bytes	Suggested target ref in upstream
`title`	string	Short description
`added_at`	uint32	Timestamp from the `MERGE_REQUEST_ADD` message

Closure attribution is not available from canonical state. To determine whether a merge request was withdrawn by the requester or closed by a maintainer, inspect finalized MERGE_REQUEST_REMOVE messages for the same (project_id, request_id) pair.

Project and account selectors

V2 selectors are address-native.

Message	V2 field
`GetProjectResponse`	`owner_address`
`GetProjectByNameRequest`	`owner_address`
`SearchProjectsRequest`	`owner_address`
`ListProjectsRequest`	`owner_address`
`GetAccountRequest`	`owner_address`
`GetAccountResponse`	`owner_address`, `username`
`GetKeyRequest`	`owner_address`
`ListKeysRequest`	`owner_address`
`GetAccountActivityRequest`	`owner_address`
`ListVerificationsRequest`	`owner_address`

GetAccount(owner_address) returns a default-zero account view even when no account row has been materialized.

GetAccountResponse.username is the canonical username when the account has effective active storage and an active reservation. It is the empty string when the account has no effective active username.

Links, reactions, and history

These transport fields are also address-native in V2:

Message	V2 field
`ListLinksRequest`	`owner_address`
`LinkEntry`	`target_owner_address`, `source_owner_address`
`ListLinksByTargetRequest`	`target_owner_address`
`ListReactionsRequest`	`owner_address`
`ReactionEntry`	`source_owner_address`
`RefLogEntry`	`owner_address`
`GetStorageQuotaProofRequest`	`owner_address`
`GetStorageQuotaProofResponse`	`owner_address`

Commit metadata

CommitMeta uses author_address.

Merge request transport

Merge-request transport fields source_ref and target_ref remain raw protobuf bytes fields. REST/OpenAPI surfaces expose them as hex-encoded byte strings so non-UTF-8 ref names are lossless.

Verification transport

Any V2 transport surface that returns verification records must expose enough proof metadata to round-trip canonical claim semantics.

For ETH verifications that means:

verification_type
address
chain_id
claim_key_type
claim_block_hash

For SOL verifications:

claim_key_type is zero or omitted
claim_block_hash is empty

Block and sync transport

The canonical persisted and streamed verification unit is the pair:

Block
ExecutionPayload

Relevant V2 responses include the exact committed ExecutionPayload:

GetBlockResponse
GetSyncTargetResponse
SyncBlocksResponse
SubscribeBlocks

V2 transports must preserve canonical account-message order directly in the committed payloads.

Edit this page on GitHub