RPC Reference

Complete reference for all MakechainService gRPC methods. All byte fields use raw bytes in gRPC and hex encoding in the CLI.

Pagination

List operations support cursor-based pagination. Pass limit (max 200) and receive a next_cursor in the response. Pass next_cursor as cursor in the next request to fetch the next page. An empty next_cursor means no more results.

Error Handling

All RPCs return standard gRPC status codes:

Code	Meaning
`NOT_FOUND`	Requested resource doesn't exist
`INVALID_ARGUMENT`	Malformed request (e.g., invalid hash length)
`RESOURCE_EXHAUSTED`	Rate limit exceeded
`INTERNAL`	Server-side error (state lock poisoned, etc.)

Write Operations

SubmitMessage

Submit a single signed message for consensus inclusion.

rpc SubmitMessage(SubmitMessageRequest) returns (SubmitMessageResponse)

Request: A fully signed Message (with hash, signature, signer, and data fields populated).

Response:

hash (bytes) — BLAKE3 hash of the accepted message
accepted (bool) — whether the message was added to the mempool
error (string) — error description if rejected

Rejection reasons: invalid signature, failed structural validation, failed state pre-check (unknown key, wrong scope), rate limited, mempool full, duplicate hash.

BatchSubmitMessages

Submit up to 100 signed messages atomically. Each message is validated independently.

rpc BatchSubmitMessages(BatchSubmitRequest) returns (BatchSubmitResponse)

Request: messages — array of signed Message objects (max 100).

Response:

results — per-message result (hash, accepted, error)
accepted_count / rejected_count — summary counters

DryRunMessage

Validate a message against current state without adding it to the mempool.

rpc DryRunMessage(DryRunMessageRequest) returns (DryRunMessageResponse)

Request: A signed Message.

Response:

valid (bool) — would this message be accepted?
error (string) — validation error if invalid

Projects

GetProject

Get project metadata by project ID.

rpc GetProject(GetProjectRequest) returns (GetProjectResponse)

Request: project_id (32 bytes)

Response: Project metadata including name, description, license, visibility, owner_mid, status ("active"/"archived"/"removed"), fork_source, ref_count, collaborator_count, commit_count, and per-project limits (max_refs, max_collaborators, max_commits).

GetProjectByName

Look up a project by owner MID and project name.

rpc GetProjectByName(GetProjectByNameRequest) returns (GetProjectResponse)

Request:

owner_mid (uint64)
name (string)

Response: Same as GetProject.

SearchProjects

Search projects by name prefix.

rpc SearchProjects(SearchProjectsRequest) returns (ListProjectsResponse)

Request:

query (string) — name prefix to match
owner_mid (uint64) — filter by owner (0 = all owners)
limit (uint32) — max results (default 50, max 200)

Response: projects array + next_cursor for pagination.

ListProjects

List all projects with optional owner filter.

rpc ListProjects(ListProjectsRequest) returns (ListProjectsResponse)

Request:

owner_mid (uint64) — filter by owner (0 = all)
limit (uint32)
cursor (bytes) — pagination cursor

GetProjectActivity

Get recent messages for a project.

rpc GetProjectActivity(GetProjectActivityRequest) returns (GetProjectActivityResponse)

Request:

project_id (32 bytes)
limit (uint32) — max messages (default 50)
types (repeated MessageType) — filter by type (empty = all)

Response: messages — array of MessageEntry (hash, type, timestamp, mid, signer).

Refs

GetRef

Get a single ref by project and ref name.

rpc GetRef(GetRefRequest) returns (GetRefResponse)

Request:

project_id (32 bytes)
ref_name (bytes) — e.g., refs/heads/main

Response: project_id, ref_name, ref_type (BRANCH/TAG), hash (current commit), nonce.

ListRefs

List all refs in a project.

rpc ListRefs(ListRefsRequest) returns (ListRefsResponse)

Request: project_id, limit, cursor

Response: refs array + next_cursor.

GetRefLog

Get the update history of a ref (like git reflog).

rpc GetRefLog(GetRefLogRequest) returns (GetRefLogResponse)

Request:

project_id (32 bytes)
ref_name (bytes)
limit (uint32)

Response: entries — array of RefLogEntry (nonce, old_hash, new_hash, timestamp, mid).

Commits

GetCommit

Get commit metadata by hash.

rpc GetCommit(GetCommitRequest) returns (GetCommitResponse)

Request: project_id (32 bytes), commit_hash (32 bytes)

Response: CommitMeta with hash, parents, tree_root, author_mid, author_timestamp, title, message_hash.

ListCommits

List commits in a project.

rpc ListCommits(ListCommitsRequest) returns (ListCommitsResponse)

Request: project_id, limit, cursor

Response: commits array + next_cursor.

GetCommitAncestors

Walk the first-parent commit ancestry chain.

rpc GetCommitAncestors(GetCommitAncestorsRequest) returns (GetCommitAncestorsResponse)

Request:

project_id (32 bytes)
commit_hash (32 bytes) — starting commit
limit (uint32) — max ancestors to return

Response: ancestors — array of CommitMeta in reverse chronological order.

Collaborators

ListCollaborators

List collaborators for a project.

rpc ListCollaborators(ListCollaboratorsRequest) returns (ListCollaboratorsResponse)

Request: project_id, limit, cursor

Response: collaborators — array of CollaboratorEntry (mid, permission, added_at) + next_cursor.

Accounts

GetAccount

Get account metadata and summary.

rpc GetAccount(GetAccountRequest) returns (GetAccountResponse)

Request: mid (uint64)

Response: mid, storage_units, project_count, key_count, verification_count, username, bio, avatar, website.

GetAccountByKey

Look up an account by its Ed25519 public key.

rpc GetAccountByKey(GetAccountByKeyRequest) returns (GetAccountResponse)

Request: key (32 bytes — Ed25519 public key)

Response: Same as GetAccount.

GetAccountActivity

Get recent messages authored by an account.

rpc GetAccountActivity(GetAccountActivityRequest) returns (GetAccountActivityResponse)

Request:

mid (uint64)
limit (uint32)

Response: messages — array of MessageEntry.

Keys

GetKey

Inspect a single key entry.

rpc GetKey(GetKeyRequest) returns (GetKeyResponse)

Request: mid (uint64), key (32 bytes — public key)

Response: mid, key, scope (OWNER/SIGNING/AGENT), added_at, allowed_projects (for AGENT-scoped keys).

ListKeys

List all keys registered to an account.

rpc ListKeys(ListKeysRequest) returns (ListKeysResponse)

Request: mid, limit, cursor

Response: keys array + next_cursor.

Verifications

ListVerifications

List verified external addresses for an account.

rpc ListVerifications(ListVerificationsRequest) returns (ListVerificationsResponse)

Request: mid, limit, cursor

Response: verifications — array of VerificationEntry (address, type, chain_id, added_at) + next_cursor.

Blocks & Messages

GetBlock

Get a committed block by number.

rpc GetBlock(GetBlockRequest) returns (GetBlockResponse)

Request: block_number (uint64)

Response: block (full Block with header, hash, chunks, transactions), message_count.

ListBlocks

List recent committed blocks (newest first).

rpc ListBlocks(ListBlocksRequest) returns (ListBlocksResponse)

Request:

start (uint64) — starting block number (0 = latest)
limit (uint32) — max blocks to return

Response: blocks array.

GetMessage

Look up a committed message by its BLAKE3 hash.

rpc GetMessage(GetMessageRequest) returns (GetMessageResponse)

Request: hash (32 bytes)

Response: message (full Message), block_number (which block it was committed in).

ListMessages

List committed messages across a range of blocks.

rpc ListMessages(ListMessagesRequest) returns (ListMessagesResponse)

Request:

start_block (uint64) — start of range (0 = latest)
end_block (uint64) — end of range (0 = same as start)
limit (uint32) — max messages

Response: messages — array of MessageEntry.

Node Operations

GetNodeStatus

Current node status.

rpc GetNodeStatus(GetNodeStatusRequest) returns (GetNodeStatusResponse)

Response: block_height, mempool_size, pending_blocks, network (devnet/testnet/mainnet), version, uptime_seconds.

GetChainStats

Cumulative chain analytics.

rpc GetChainStats(GetChainStatsRequest) returns (GetChainStatsResponse)

Response: total_messages, total_projects, total_accounts, total_blocks, total_refs, total_commits.

GetHealth

Liveness and readiness probe for load balancers.

rpc GetHealth(GetHealthRequest) returns (GetHealthResponse)

Response: live (bool), ready (bool), block_height.

GetSnapshotInfo

Current snapshot persistence status.

rpc GetSnapshotInfo(GetSnapshotInfoRequest) returns (GetSnapshotInfoResponse)

Response: block_number, entry_count, state_root, estimated_size_bytes.

GetMempoolInfo

Mempool size and per-type message breakdown.

rpc GetMempoolInfo(GetMempoolInfoRequest) returns (GetMempoolInfoResponse)

Response: total_pending, by_type (map of MessageType → count).

Streaming

SubscribeMessages

Server-streaming RPC for live message updates. Receives every message as it's committed to a block.

rpc SubscribeMessages(SubscribeRequest) returns (stream Message)

Request:

project_id (bytes) — filter to a specific project (empty = all)
types (repeated MessageType) — filter by message type (empty = all)

Stream: Continuous stream of Message objects.

SubscribeBlocks

Server-streaming RPC for live block updates.

rpc SubscribeBlocks(SubscribeBlocksRequest) returns (stream GetBlockResponse)

Stream: Continuous stream of GetBlockResponse for each committed block.

Rate Limiting

All write operations (SubmitMessage, BatchSubmitMessages) are rate-limited per account (MID). The default configuration allows 100 burst tokens with 10 tokens/second refill. When rate-limited, the RPC returns RESOURCE_EXHAUSTED.

Read operations and streaming RPCs are not rate-limited.