Protocol Model
Blueprints are easy to explain badly because one word gets used for too many things. Keep the layers separate.
A blueprint is the template. It defines what can be run: jobs, metadata, binaries, app routing, and optional Blueprint Service Manager logic. Operators register for that template. A user requests a service instance from a set of registered operators. That service instance is the thing the user actually uses.
The lifecycle
- A developer publishes a blueprint definition, runnable artifact, metadata, and any blueprint-specific contracts.
- Operators register for the blueprint and publish the endpoint or metadata the app needs to find them.
- A user requests a service instance and selects one or more registered operators.
- Operators approve or join the request.
- The service instance becomes active.
- The user submits jobs to that service instance.
- Apps read chain state, indexed state, and operator APIs to show what happened.
The service instance is the boundary for state, auth, and billing. If a page says the template itself is live, read that as a wording bug. The service instance is live.
Names that should not drift
| Term | Use it for |
|---|---|
| Blueprint | The abstract capability definition. |
| Operator registration | An operator’s on-chain opt-in for a blueprint. |
| Service request | The user’s request to instantiate the blueprint with chosen operators and parameters. |
| Service instance | The live unit created from a request. |
| Job | A state-changing command against a service instance. |
| Query | A read through eth_call, the indexer, or an operator API. |
| Operator API | The off-chain API an operator exposes for live product state and controls. |
| Hosted app | The product UI. It may be first-party, but it is not the blueprint. |
| BSM | Blueprint Service Manager contract logic for blueprint-specific rules. |
Jobs are not reads
Jobs mutate state or ask the operator to perform work. They are the wrong tool for normal app reads.
Use reads for:
- service and operator lists
- health checks
- bot rosters
- order books
- terminal state
- file lists
- price quotes
- proof or attestation lookups
Use jobs for:
- provisioning or deprovisioning
- workflow triggers
- market-making ticks
- service-level commands that should be recorded as protocol activity
This split matters. If reads become jobs, the app gets slow, operators pay more gas than needed, and the protocol history stops meaning “work was requested.”
What the indexer can prove
The indexer can show what the chain observed:
| Indexed state | Useful for |
|---|---|
| Blueprint creation and source updates | Catalogs, audits, and app routing. |
| Operator registration | Discovery, capacity lists, and endpoint metadata. |
| Service requests and approvals | Provisioning status and operator participation. |
| Service instances | Instance pages, ownership, selected operators, and lifecycle. |
| Jobs | User-visible commands, support traces, and billing or settlement context. |
| Heartbeats or status events | Liveness history and incident timelines. |
The indexer cannot prove endpoint honesty, model output quality, exchange execution, or credit redemption. Those need product-specific evidence: operator API probes, contract state, attestations, settlement receipts, SP1 proofs, or signed reports.
Reader map
| Reader | What they need from these docs |
|---|---|
| Consumer | Which service instance they are using, who operates it, what evidence backs the result, and what can fail. |
| Developer | The job schema, query paths, metadata, contracts, app policy, and validation steps. |
| Operator | Hardware, ports, keys, provider credentials, pricing, capacity, health checks, and rollback steps. |
| App builder | How to route the app from metadata, when to use the generic protocol page, and where live product state comes from. |
| Indexer owner | Enough event history to distinguish pending provisioning, operator failure, normal shutdown, and missing data. |
Common mistakes
| Bad wording | Better wording |
|---|---|
| ”Deploy the blueprint for a user." | "Request a service instance from a blueprint." |
| "The operator provisions the blueprint." | "The operator provisions the service instance." |
| "The dapp reads the blueprint for bot state." | "The dapp reads indexed service state and the operator API for bot state." |
| "Submit a job for a normal read." | "Read from the contract, indexer, or operator API." |
| "The hosted app is the blueprint." | "The hosted app is the UI for service instances created from the blueprint.” |