How to Build a Tangle Blueprint: Test and Deploy

Your team has a useful Rust function on a laptop. It accepts a structured request, does the work, and returns the right answer in a unit test. The first customer asks a harder question: who will run it tomorrow, how will the request reach that process, and what will either of you be able to inspect when the answer is disputed?

That is the point at which an application function becomes a service. Tangle is a coordination network for services that independent parties run. Its contracts record selected registration, service, payment, verification, and lifecycle state while application work runs outside the chain. This guide explains how to build the service, test the same job and runner path locally, and publish a versioned deployment definition for a real network.

A Blueprint is a reusable service template. It describes the executable artifact, the jobs it exposes, their inputs and outputs, the metadata needed to discover them, and any protocol rules around the parties that run it, services, payments, or verification. An operator is the party that runs the Blueprint and executes its jobs. A Service is one configured running instance of the Blueprint with an owner, operator set, payment terms, and lifecycle state. A Job is one callable unit of work inside that Service. The runtime is the process and environment that executes the package. Off-chain means computed outside the blockchain, while on-chain means recorded in blockchain state. An evaluation is a repeatable check that compares observed behavior with an expected rule.

The current Tangle Blueprint documentation uses those three objects as the basic model. The public Blueprint SDK repository supplies Tangle’s Rust software development kit (SDK), runner, command-line interface (CLI), testing utilities, and examples. Anvil is a local Ethereum development network used by the public testing utilities. The testcontainers library starts disposable containers for integration tests such as the maintained example.

The shortest reliable path is:

Scaffold or copy a maintained example.
Add one typed job and route it to one handler.
Run the example’s Anvil-backed integration test.
Package an immutable artifact and metadata.
Deploy the definition to testnet.
Register an operator and exercise the public job path.
Test restart, timeout, duplicate submission, payment, and expiry behavior before calling the service ready.

The command cargo build proves that a Rust package compiles. It does not prove that the operator process can discover a job, execute the intended artifact, submit a result, or recover when the service expires.

Begin with one request and one observable result

Use a video-transcription service as the running example. The customer sends a video reference and a language hint. The job returns transcript segments with timestamps.

Before adding payments or several operators, write down the smallest public contract:

Input:  { video: <reference>, language: <optional language code> }
Output: { segments: [{ start, end, text }], usage: { seconds } }
Failure: invalid input, unavailable media, timeout, or execution error

The input and output are part of the job contract, not a detail left to a particular operator. The caller needs to know whether a retry is safe, whether the response is complete, and which fields can be evaluated.

The Blueprint can run ordinary application logic off-chain. The network coordinates which artifact and operators belong to the service, while the operator runtime performs the transcription. That split keeps large files and model work out of the chain without making the service invisible.

The SDK pieces have different jobs

The names become easier once each one has one responsibility.

SDK or protocol object	Plain-language role	Typical failure
Blueprint artifact	The binary, container, or other runnable package	The image is missing, mutable, or incompatible with the operator
Job handler	The function that performs one kind of work	It accepts malformed input or returns an unstable shape
Job router	A traffic director from job IDs to handlers	A valid job ID points to the wrong function or an unknown ID is accepted
Blueprint Runner	The process that receives job calls and invokes the job router	It cannot start, connect, or submit results
Producer	The adapter that turns an event into a job call	It misses, duplicates, or misdecodes a trigger
Consumer	The adapter that sends a handler result to its destination	It loses result metadata or fails to publish the outcome
Blueprint Manager	The operator process that watches protocol state and runs services	It cannot fetch the artifact, satisfy policy, or recover the process
Service	A configured instance with an owner and operator set	It expires, runs out of funds, or loses an operator

The runtime is the process and environment that executes the package. The Blueprint Runner is part of that runtime for job handling. The Blueprint Manager is the operator-facing process that keeps the off-chain runtime aligned with the on-chain service lifecycle.

The Blueprint Manager documentation describes the operator flow: register for a Blueprint, obtain its artifacts and metadata, and execute assigned services according to the definition and confidentiality policy.

Route a job before you add a network

A job router keeps the job interface explicit. The following is the minimal shape shown in the official job-router documentation:

use blueprint_sdk::Router;

let router = Router::new()
    .route(MY_JOB_ID, my_job)
    .with_context(my_context);

MY_JOB_ID, my_job, and my_context are placeholders from the public example. Replace them with the stable identifier, handler, and resources for the transcription job. The important boundary is the route itself: a job call names a job ID, the job router selects the handler, the handler validates and executes the input, and a consumer receives the result.

A job router is not a correctness system. It can direct a request to the intended handler and reject an unknown job ID. It cannot decide whether a transcript is accurate. That requires a task-specific evaluation, such as a labeled sample with expected words and timestamps.

Keep the first test close to that boundary. Give the handler a valid request, an invalid request, an unavailable media reference, and a timeout. Assert the output shape and the error shape. The Tangle testing guide describes the later Anvil-backed path that adds protocol state around the same runner.

Run the maintained example before inventing a layout

The public repository contains a minimal hello-tangle Blueprint. Its test starts Anvil through the test container utilities, seeds an operator key, starts the Blueprint Runner, submits an application binary interface (ABI)-encoded request, and waits for a job-result event. The example README names those steps and the current test command.

The repository’s current public installation path is:

cargo install cargo-tangle --git https://github.com/tangle-network/blueprint --force
cargo tangle blueprint create --name my-service
cd my-service
cargo build

Pin the SDK revision or released CLI in continuous integration. Installing the moving main branch is convenient for exploration and unsuitable as a reproducibility policy for a production artifact.

The maintained example’s integration test is:

cargo test -p hello-tangle-blueprint --test anvil -- --nocapture

The test requires Docker because the current example starts Anvil through testcontainers. The test is valuable because it checks more than a handler in isolation:

A local Tangle contract state is available.
A temporary operator key is usable.
The Runner’s job router is wired to the job.
The request is encoded and submitted through the protocol path.
A result event arrives with a decodable receipt.

Replace the example’s document job with the transcription job only after the original test passes. That gives a known-good control case when a later failure could come from the handler, the route, the contract fixture, or the runner configuration.

Package the operator runtime

An operator cannot run a source repository description. The operator needs a fetchable artifact, the metadata that explains it, and enough configuration to connect the runtime to the protocol.

The artifact can be a native binary, a container image, or another source supported by the current SDK path. The Blueprint Sources documentation says that sources describe how operators fetch and execute an artifact. The source type is separate from the confidentiality policy.

For a container source, publish a versioned tag and record the immutable digest in your release evidence. Do not point a production definition at a mutable latest tag. If the image changes while the tag stays the same, two operators can believe they are running the same Blueprint while executing different code.

Metadata should answer a caller’s first questions:

Metadata field	Why a caller needs it
Name and description	Whether this is the right service
Job names and schemas	How to form a valid request
Source and version	Which artifact an operator should fetch
Payment terms	What a request may cost and when it settles
Execution policy	Whether ordinary or confidential execution is acceptable
Evidence returned	What the caller can inspect after completion
Failure and expiry rules	Whether it is safe to retry or migrate

The definition manifest is the file that binds this material to a deployable Blueprint. The public CLI uses the --definition option for a definition file in JSON, YAML, or TOML. The current SDK README lists metadata_uri, manager, at least one job, at least one source, and either a metadata hash or a metadata file as the minimum shape for a real-network deployment.

The exact schema can change with the SDK and protocol release. Treat the linked repository and current CLI reference as the source of truth for field names.

Deploy the definition after the local path passes

The current public command shape is:

cargo tangle blueprint deploy tangle \
  --network testnet \
  --definition ./definition.json

This command registers a service definition on the target network. It does not launch an operator on a machine, prove the handler’s output, or test your payment endpoint.

A testnet definition should use a real metadata URI or a reproducible metadata file and an artifact that operators can fetch. For a confidential workload, the current Tangle documentation places the policy under metadata.execution_profile.confidentiality. The policy values include any, tee_preferred, tee_required, and standard_required. The execution confidentiality guide explains that policy in detail.

An illustrative fragment looks like this:

{
  "metadata": {
    "name": "transcription-service",
    "execution_profile": {
      "confidentiality": "any"
    }
  },
  "sources": [
    {
      "kind": "container",
      "registry": "ghcr.io",
      "image": "example/transcription-service",
      "tag": "0.1.0"
    }
  ]
}

This fragment is an illustrative shape, not a complete deployment file. Use the current public schema for the full metadata_uri, manager, job, and hash fields.

The point of a manifest is accountability across the handoff. The developer publishes what should run. The operator fetches the declared artifact. The service records which Blueprint and operator set it uses. The caller can compare the returned evidence with the declared contract.

Run the operator process separately from deployment

The operator flow has its own configuration. The current SDK docs show remote procedure call (RPC) endpoints, a keystore path, contract addresses, a settings file, and a chosen protocol. The public local command shape is:

cargo tangle blueprint run \
  --protocol tangle-evm \
  --http-rpc-url http://127.0.0.1:8545 \
  --ws-rpc-url ws://127.0.0.1:8546 \
  --keystore-path ./local-operator-keys \
  --settings-file ./settings.env

The endpoints above are local examples from the public testing guide. Use the target network’s current RPC endpoints and contract configuration for testnet or mainnet.

An operator needs more than a process that stays alive. The operator runbook should answer:

How is the signing key created, stored, rotated, and backed up?
Which artifact version and digest is running?
What happens when the process restarts while a job is in flight?
How are duplicate job calls identified?
What does a health endpoint report, and what does it omit?
How are payment records linked to job records?
What happens when an operator leaves or a Service reaches its time-to-live?

The service’s time-to-live, or TTL, is the period after which protocol checks can stop accepting jobs or billing. A TTL of 0 means that the Service has no expiry. The current service lifecycle guide warns that expiry does not necessarily perform application cleanup or refund behavior. Stateful or custodial Blueprints need an escape hatch, a migration path, or an explicit termination flow.

Treat production as a chain of proof obligations

The simplest production mistake is to treat each green layer as proof of the next. A green build does not prove the container was published. A successful deployment does not prove an operator registered. An accepted payment does not prove a job completed. A returned transcript does not prove its words are correct.

Keep one record for each layer:

Layer	Evidence to retain	What it does not prove
Source	Repository revision and dependency lockfile	That the deployed artifact matches it
Build	Reproducible build output	That the operator used that output
Artifact	Registry reference and immutable digest	That the process started successfully
Definition	Network, deployment transaction, metadata URI, and hash	That a customer can invoke the service
Operator	Registration state, running version, and health result	That the handler returns correct work
Job	Request identifier, trigger, result event, and output	That the output passes a domain evaluation
Payment	Amount, asset, payer, recipient, settlement result, and job ID	That a service fulfilled the job
Recovery	Restart, timeout, duplicate, operator exit, and expiry tests	That an untested failure will behave well

This table is also an evaluation plan. For the transcription Blueprint, include a small labeled set with word-error or timestamp tolerances, an invalid-media case, a long-media timeout, and a retry case. Keep the evaluation separate from the payment receipt and from the operator health check.

The failure paths are part of the Blueprint

The job is accepted but the runner is offline

The protocol may record a request while no operator process is ready to execute it. The Service needs a timeout, a retry policy, and a way to distinguish queued work from completed work. The caller should never infer completion from an accepted request alone.

Operators return different results

For deterministic work, the Blueprint can compare outputs or use a threshold rule. For transcription, different models and decoding settings can produce different punctuation or segmentation even when the content is acceptable. Define normalization and tolerance before comparing results. Disagreement should create an inspectable state, not an invisible winner.

The same bug reaches every operator

Multiple operators are not independent if they run the same faulty image or dependency. A task evaluation or reference check is still required for shared bugs.

A paid request is replayed

The payment layer and the job layer need a correlation identifier and an idempotency policy. Idempotency means that retrying the same request does not create a second job. x402 is an open protocol for programmatic payment over the Hypertext Transfer Protocol (HTTP). It provides payment headers and settlement information, while the Blueprint must decide whether the same job call can be accepted twice. The current Tangle x402 guide documents a 202 Accepted enqueue result and replay controls for restricted delegated-caller mode.

The Service expires while customers still depend on it

Renewal is a new operational agreement. If the current operators will not renew, a stateful Blueprint needs a migration or exit path. Build that path before customers store durable state behind the service.

When a Blueprint is the wrong abstraction

A conventional web service is usually the better choice when one company should control the whole request path, the data is already trusted to that company, and the latency budget leaves no room for protocol coordination.

A Blueprint fits when the product needs independently operated services, explicit operator registration, protocol-recorded lifecycle, machine payment, cryptographic evidence, or a defined economic consequence for a detected violation.

The extra machinery has real costs:

Operators must manage keys, artifacts, RPC connections, and upgrades.
Customers must understand Service state, payment, and expiry.
Verification can add duplicate execution, proof generation, or review delay.
Protocol failures become part of the product’s support burden.
A public definition can make metadata and lifecycle state more visible than a private deployment would.

Choose the smallest Blueprint that tests the requirement you have. Do not add three operators because a diagram looks better. Add them when the failure they reduce matters to a customer and the result rule can distinguish agreement from truth.

A practical readiness check

Before moving from testnet to a production proposal, ask the following:

Can a new reader form a valid job request from public metadata?
Can the maintained Anvil test submit a request and decode the result?
Is the artifact immutable and recoverable if the registry is unavailable?
Can the operator restart without losing or duplicating durable work?
Does the caller know the difference between accepted, running, completed, rejected, and expired?
Does every verification statement name the property it supports?
Does the payment record link to the exact job and Service?
Can a customer leave or migrate if the Service expires?

If one answer is no, record it as an untested boundary. The next useful change is the one that turns that boundary into an observable test.

What is a Tangle Blueprint?

A Tangle Blueprint is a reusable definition for a service that operators can run. It packages jobs, artifacts, metadata, and optional protocol logic for registration, payments, verification, and lifecycle behavior.

What is the difference between a Blueprint and a Service?

The Blueprint is the reusable template. The Service is one configured instance created from that template with an owner, operator set, payment terms, and lifecycle state.

Do I need Rust to build a Blueprint?

The current public Blueprint SDK and its maintained examples use Rust. Another application can call a Blueprint through its public HTTP or on-chain interface, but the operator package follows the Rust SDK path described in the public repository.

Is an Anvil test enough for production?

No. Anvil is a local Ethereum development network used by the public testing utilities. It can prove that a local contract and runner path works for a case. It cannot prove that a testnet operator, immutable artifact, payment route, monitoring system, or recovery policy works.

What does a job router do?

A job router maps a job identifier to the handler that should execute it. It helps the Runner dispatch work and reject unknown jobs. It does not evaluate whether the handler’s output is correct.

Where should I find current CLI flags?

Use the official Blueprint SDK repository, the Tangle SDK documentation, and the maintained example closest to your service. CLI flags and contract fields can change, so pin the version used by your build and update the commands with that release.

Public sources

The Blueprint SDK repository is the source for the public CLI, examples, and release state. The Tangle Blueprint introduction defines Blueprint, Service, Job, and operator roles. The Tangle testing guide documents the seeded Anvil flow. The service lifecycle guide documents expiry, renewal, and migration constraints. The Blueprint lifecycle explanation gives the object model behind the commands in this guide.

Once the deployment path is clear, the next question is what a Blueprint can prove about the work it runs. That question is the subject of How Tangle Verifies Work. For the service-building path that follows verification, continue with building AI services on Tangle.