API Reference

Makechain exposes a single gRPC service (MakechainService) for reading and writing state. The service supports grpc-web for browser clients and server reflection for runtime discovery.

Write Operations

Submit signed messages for inclusion in the consensus pipeline.

RPC	Description
`SubmitMessage`	Submit a single signed message (verify, validate, mempool)
`BatchSubmitMessages`	Submit multiple signed messages with per-message acceptance results
`DryRunMessage`	Validate a message against current state without submitting

Read Operations

Query the current state of projects, accounts, refs, and commits. All list operations support cursor-based pagination (max 200 items per page).

Projects

RPC	Description
`GetProject`	Get project metadata and status by project ID
`GetProjectByName`	Look up a project by `owner_address` and project name
`SearchProjects`	Search projects by name prefix with pagination
`ListProjects`	List projects with optional owner filter and pagination
`GetProjectActivity`	Recent messages for a specific project
`GetMergeRequest`	Get an active merge request by target project and request ID
`ListMergeRequests`	List active merge requests targeting a project
`ListMergeRequestsByRequester`	List active merge requests opened by a specific `owner_address`

Git Objects

RPC	Description
`GetRef`	Get a single ref by project ID and ref name
`ListRefs`	List all refs in a project with pagination
`GetRefLog`	Get the update history of a ref
`GetCommit`	Get commit metadata by project ID and commit hash
`ListCommits`	List commits in a project with pagination
`GetCommitAncestors`	Walk the commit graph and return ancestor chain
`ListCollaborators`	List project collaborators with pagination

Accounts

RPC	Description
`GetAccount`	Get account metadata, keys, storage units, project count, verifications, and link count by `owner_address`
`GetAccountActivity`	Recent messages for a specific `owner_address`
`GetKey`	Inspect a single key entry for an `owner_address` (scope, allowed projects, added_at)
`ListKeys`	List all keys registered to an `owner_address` with pagination
`ListVerifications`	List verified external addresses for an `owner_address`
`ListLinks`	List links for an `owner_address` (follows, stars)
`ListLinksByTarget`	List accounts that link to a target `owner_address` or project
`ListReactions`	List reactions from an `owner_address` (likes on commits)
`ListReactionsByTarget`	List `owner_address` values that reacted to a target commit

Blocks & Messages

RPC	Description
`GetBlock`	Get a committed block by block number (includes transaction chunks)
`ListBlocks`	List recent committed blocks (newest first)
`GetMessage`	Look up a committed message by its BLAKE3 hash
`ListMessages`	List committed messages across a range of blocks

Proofs

RPC	Description
`GetOperationProof`	Get a QMDB operation (inclusion) proof for a public state key
`GetExclusionProof`	Get a QMDB exclusion proof for a public state key
`VerifyOperationProof`	Verify a previously obtained operation proof against the current committed root
`GetStorageQuotaProof`	Get a QMDB proof bundle for an account's active storage grants

Node Operations

RPC	Description
`GetNodeStatus`	Current block height, mempool size, pending blocks, network, version, and uptime
`GetHealth`	Liveness and readiness probe for load balancers
`GetChainStats`	Cumulative chain analytics (total messages, projects, accounts, blocks)
`GetSnapshotInfo`	Current snapshot status (block number, entry count, state root)
`GetMempoolInfo`	Mempool size and per-type message counts

Streaming

RPC	Description
`SubscribeMessages`	Server-streaming RPC for live message updates
`SubscribeBlocks`	Server-streaming RPC for live block updates

SubscribeMessages supports filtering by:

project_id — only receive messages for a specific project
types — only receive specific message types (e.g., only COMMIT_BUNDLE)

Connection

The default gRPC endpoint is localhost:50051. Use --grpc-addr to configure.

# gRPC (native clients)
grpcurl -plaintext localhost:50051 list
 
# CLI client
cargo run --bin cli -- --endpoint http://localhost:50051 account get --owner-address 0x0000000000000000000000000000000000000001

REST Gateway

A Cloudflare Workers gateway translates HTTP REST requests into gRPC calls. This is the recommended way for browser clients, mobile apps, and any HTTP-native integration to interact with Makechain.

All endpoints return JSON
Input validated with Zod schemas
SSE streaming for real-time message and block updates
gRPC-web passthrough for clients that prefer raw protobuf

Merge-request REST surfaces:

GET /v1/projects/{projectId}/merge-requests
GET /v1/projects/{projectId}/merge-requests/{requestId}
GET /v1/accounts/{ownerAddress}/merge-requests

On the REST surface, merge-request source_ref and target_ref are exposed as hex-encoded bytes so arbitrary non-UTF-8 ref names round-trip without loss.

See the REST API reference for complete endpoint documentation, or try the interactive API explorer to call endpoints directly from your browser.

grpc-web

Browser clients can also connect via grpc-web (HTTP/1.1) directly. The node accepts HTTP/1.1 requests and translates them to gRPC internally via tonic-web. CORS headers are configured to allow cross-origin requests.

Edit this page on GitHub