Nockchain Public API Source Trace

api-readme-contract

Defines nockchain-api as alpha Tier 1 authority for public API runtime, deployment guidance, risk posture, cache limits, and PMA quickstart.

The README says public gRPC is enabled by --bind-public-grpc-addr, has no auth/authz/rate limiting, exposes NockchainService and NockchainBlockService, and serves block explorer responses from a heaviest-chain cache.

api-binary-bootstrap

Boots the public API binary with the normal Nockchain kernel and prover hot state, enabling the public server only when a bind address is supplied.

The binary parses normal Nockchain CLI flags, maps bind_public_grpc_addr into NockchainAPIConfig, initializes with the Nockchain kernel, and runs the NockApp.

public-grpc-cli-flag

Declares the public gRPC bind flag and private gRPC bind controls that decide endpoint exposure mode.

The public API bind is off by default and recommends 127.0.0.1:5555, while private gRPC defaults to port 5555 unless explicitly overridden.

api-config-driver-toggle

Toggles public gRPC driver installation while always adding the private NockApp gRPC driver.

NockchainAPIConfig distinguishes EnablePublicServer from DisablePublicServer, and init adds public_nockchain::grpc_server_driver only when deploy_public is true.

public-grpc-driver

Connects public gRPC server/listener behavior to NockApp effects, including send-tx effects from wallet/public client flows.

The driver decodes nockchain-grpc send-tx effects and starts a PublicNockchainGrpcServer on the configured socket.

public-service-startup

Starts health, reflection, NockchainService, NockchainBlockService, metrics service, gRPC-Web, CORS, and IP blocklist layers.

The service marks NockchainService serving immediately, block service not-serving until cache seed, installs reflection, API, block explorer, metrics, CORS, gRPC-Web, and blocklist layers.

block-explorer-refresh

Refreshes heaviest-chain state and initializes the block explorer cache before marking block service as serving.

The refresh worker retries cache initialization, only sets NockchainBlockService serving after initialization succeeds, and treats decode errors as fatal.

transaction-accepted-server

Serves TransactionAccepted by peeking the kernel's tx-accepted path and returning accepted/error, with metrics for invalid, decode, peek, and NockApp failures.

The method validates tx_id, builds a tx-accepted peek path, decodes Option<Option<bool>>, and returns accepted false when the peek is empty.

block-explorer-get-blocks

Serves paginated GetBlocks from the block explorer cache and reports current cached height.

GetBlocks requires a page request, clamps client limit to max page size, decodes cursor tokens, reads cache pages, and records latency metrics.

block-explorer-transaction-details

Serves transaction details or pending/not-found state through the block explorer cache.

Transaction details resolve tx_id, load details from cache/kernel, return pending when the cache reports TxPending, and keep pending separate from details.

public-api-proto

Defines the public v2 gRPC service contract for wallet balance/send, tx acceptance, block explorer, transaction details, and metrics.

The proto separates wallet APIs, block explorer APIs, and metrics APIs; transaction responses can be accepted, pending, details, or error depending on method.

public-api-metrics

Names the observability contract for public API balance, send, tx-accepted, heaviest-chain, block explorer cache, latency, and request blocking.

Metrics include cache seed readiness, heaviest-chain age, cache span/coverage, refresh/backfill success, endpoint latency, and request-blocked counts.

wallet-public-tx-accepted

Enforces wallet tx-accepted checks through the public client and formats accepted/not-yet-accepted output.

The wallet rejects tx-accepted unless --client public is selected, validates the tx id as base58 hash, queries the public gRPC server, and renders accepted-by-node status.