BlogBlueprint SDK Guide: Run Rust Services on the Tangle Network
Blueprint SDK Deployment: Run an Operator Job
What does a Rust service need before another operator can run it as a Tangle Blueprint job?
This post is about the Tangle Network protocol, a separate project from Tangle's infrastructure for AI agents. Introduction to Tangle covers the agent infrastructure.
Your Rust service works on your laptop. Another team needs to run it on a different machine, discover its jobs, configure its keys, observe its health, and recover when the first release is wrong. That is where “the binary starts” stops being a deployment plan.
This guide takes one service from a local build to its first test-network job and lists what each step must record. It covers the job contract, the artifact, the runner, the network settings, the first test-network run, and the return path after failure.
On Tangle, a Blueprint is a reusable definition of software that can run as a service. It describes the executable artifact, the jobs it exposes, their inputs and outputs, and what an operator needs to run it. A Service is one live configured instance of a Blueprint. A Job is one callable unit of work inside that Service. An operator supplies the machine, runs the service, responds to jobs, and keeps the instance available.
Three pieces do the work: cargo tangle blueprint create scaffolds the project, cargo tangle blueprint run starts the runner under the Blueprint Manager against a protocol RPC endpoint, and the job router dispatches each job call to its handler.
What the operator observes from them is the service startup, a job’s typed result or error code, and the failure context in the logs.
The tables below list what each check must show.
The Blueprint introduction covers those objects and the roles around them.
The Blueprint SDK is Tangle’s Rust toolkit for building, testing, and running services.
Its SDK documentation describes cargo-tangle, the CLI for creating and operating a project; the Blueprint Runner, which connects job triggers, handlers, and results; the Blueprint Manager, the long-lived operator process that watches chain events and runs services; and optional HTTP gateways.
The companion How Blueprints Work article explains the service lifecycle in broader terms.
The Blueprint Protocol guide covers the operator-facing contract and the evidence a service should publish.
Decide what the operator is agreeing to run
Start with one job rather than with a product name.
Imagine a document-labeling service with a job called classify.
The caller supplies a document reference and a language hint.
The job returns labels, confidence values, the model version, and a request identifier.
That sentence is already a deployment contract. It raises questions that project instructions can leave vague:
- Which document formats are accepted?
- What is the maximum input size?
- Is a URL fetched by the operator, and which hosts are allowed?
- What happens when the document is malformed or unavailable?
- How long may the job run?
- Does a rejected request cost anything?
- Which output fields are stable enough for a consumer to depend on?
- Which version of the service produced the result?
Write those answers into the public service definition and run instructions. If an operator must know a setting to start the service, it belongs in the deployment contract, not in a private handoff message.
This illustrative contract describes the application boundary, not a fixed Tangle metadata schema.
{
"name": "classify",
"input": {
"documentUrl": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
"language": "en"
},
"output": {
"labels": ["invoice"],
"confidence": [0.94],
"modelVersion": "classifier-2026-06"
},
"errors": [
"invalid_input",
"fetch_denied",
"job_timeout",
"internal_failure"
]
}
State in the contract whether the example URL is fetched by the operator runtime or by the caller. That decision changes the network policy, the privacy boundary, the timeout, and the evidence a reviewer should retain.
Create a project that has a runner boundary
The Tangle CLI quickstart documents creating a Blueprint project with:
cargo tangle blueprint create --name document-labeler
The generated project separates job definitions and core logic from the binary that starts the runner. The Blueprint Runner guide calls the runner the primary process of a Blueprint, with these parts:
| Runner part | Plain-language job |
|---|---|
| Entry point | Starts the service process and its configuration |
| Job definition | Describes the callable work and its input and output types |
| Job router | Maps a job identifier to the handler that executes it |
| Producer | Turns an event or request into a job call |
| Consumer | Handles the result after the job finishes |
| Background service | Keeps supporting processes such as an HTTP server or database connection alive |
A job router is an in-process dispatch table, not a network router. It maps an arriving job identifier to its handler; it does not prove that the handler’s result is correct.
The project template that create copies defines one job in its library crate:
use alloy_sol_types::sol;
use blueprint_sdk::Router;
use blueprint_sdk::tangle::extract::{Caller, TangleArg, TangleResult};
pub const HELLO_JOB_ID: u8 = 0;
sol! {
struct HelloRequest {
string name;
}
struct HelloResponse {
string message;
string operator;
}
}
pub async fn hello(
Caller(caller): Caller,
TangleArg(request): TangleArg<HelloRequest>,
) -> TangleResult<HelloResponse> {
let message = format!("Hello, {}!", request.name);
TangleResult(HelloResponse {
message,
operator: format_caller(&caller), // template helper: the caller's address as hex
})
}
pub fn router() -> Router {
Router::new().route(HELLO_JOB_ID, hello)
}
Its binary crate hands that router to the runner with a producer and a consumer:
// The producer listens for JobSubmitted events; the consumer submits results.
BlueprintRunner::builder(TangleConfig::default(), env)
.router(router())
.producer(TangleProducer::new(tangle_client.clone(), service_id))
.consumer(TangleConsumer::new(tangle_client))
.run()
.await
A classify job has the same shape: a sol! request and response, a job ID constant, a handler, and one route call.
The Blueprint SDK repository holds the SDK, runner, CLI, examples, and operator documentation; use the current template and versioned documentation, because command flags and crate names change.
Prove the local path before adding a network
The local loop should produce evidence for success and failure from a clean checkout, before any Tangle network is involved.
cargo test
Then exercise one valid and one invalid classify request through the same runner route an operator will use.
The run should show input validation, the handler result, the error code, and the process behavior after the error.
Use a small test matrix.
| Test | Expected observation | Why an operator cares |
|---|---|---|
| Valid input | Typed result with request identifier | The happy path is visible |
| Missing required field | Stable input error and no partial result | Bad callers cannot wedge the service |
| Unreachable document | Bounded failure and useful log context | External fetches have a return path |
| Long-running request | Timeout or cancellation is explicit | One job cannot occupy the process forever |
| Two concurrent jobs | Results remain associated with the right request | Shared state is not leaking across jobs |
| Process restart | Service returns to a known state | An operator can recover without manual repair |
A passing local test does not prove that an independent operator can run the service. The local machine may have a cached dependency, an open port, a hidden environment variable, or a credential that the published runbook never mentions.
Cargo checks the application; the Blueprint test flow checks how it joins Tangle’s service lifecycle. The Cargo command reference lists the Rust build and test commands.
Make the artifact identifiable
An operator needs three answers before starting a release.
- What artifact am I running?
- Which source and build produced it?
- How can I tell that the artifact I downloaded is the reviewed one?
The artifact may be a native binary, a container image, a WebAssembly module, or another package supported by the deployment path. Publish the source revision, application version, dependency lock state, build target, and integrity value together.
An integrity value is a fingerprint that changes when the artifact changes. For a container, the immutable image digest is more precise than a mutable tag. The Docker image reference documents image identity and the commands for inspecting it.
For a Rust service, keep the lockfile in the deployable project when reproducibility matters. The Cargo lockfile guide explains the difference between the manifest that declares dependencies and the lockfile that records the resolved versions.
Exercise the operator path with a local Tangle network
The Blueprint SDK’s local testing flow runs against a seeded Anvil network, Foundry’s local Ethereum development node. The Testing with Tangle guide starts Tangle Protocol contracts with pre-seeded state, so Blueprint Manager flows run without a public network. The manager reaches the Ethereum Virtual Machine (EVM) node through its RPC endpoints.
Prerequisites are Rust, Foundry’s anvil, and Docker.
Create a local operator keystore, the protected store for signing key material:
cargo tangle key --algo ecdsa --keystore ./local-operator-keys --name anvil-operator
export BLUEPRINT_KEYSTORE_URI="$(pwd)/local-operator-keys"
The test guide shows the manager configuration for a local Tangle EVM run:
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 current SDK runbook names the fixture and settings file your installed version expects.
The local network run should answer two questions: did the process start, and did the job route work?
| Check | Evidence |
|---|---|
| Registration | The Blueprint can be discovered in the local protocol state |
| Startup | The manager starts the service with the published settings |
| Routing | A known job identifier reaches the expected handler |
| Result | The job returns the documented output or error |
| Observation | Logs include service, job, and failure context |
| Restart | The service can be stopped and started without corrupting state |
This is the cheapest place to catch a wrong job identifier, a missing setting, a bad RPC URL, or an incompatible artifact. Fix those before asking a public operator to diagnose them.
Publish the operator settings
The current Blueprint SDK documentation lists the common Tangle EVM settings: the HTTP and WebSocket RPC URLs, the core Tangle contract, the staking contract, an optional status registry contract, and the keystore path. Write each value’s purpose and owner into the runbook.
| Setting | Meaning | Owner or risk |
|---|---|---|
http_rpc_url |
HTTP endpoint for EVM requests | Network availability and rate limits |
ws_rpc_url |
WebSocket endpoint for subscriptions | Event delivery and reconnect behavior |
tangle_contract |
Core protocol contract address | Wrong address can target the wrong deployment |
staking_contract |
Staking and delegation contract address | Network and security configuration |
status_registry_contract |
Optional heartbeat and status registry | Liveness reporting and monitoring |
keystore_path |
Location of operator signing material | Key protection and filesystem permissions |
Do not publish secret values in the Blueprint metadata. Document how an operator supplies them, how they rotate, and what happens when a key is unavailable. Separate developer keys, test keys, operator keys, and consumer keys.
The runtime is where the manager and service processes execute: host, container or virtual machine, filesystem, network policy, and resource limits. The runbook should say which of these the Blueprint requires and which are local choices.
Record the first testnet run
A testnet is a blockchain network for exercising a service before production. It is the first place where the artifact, operator, lifecycle, network, and job behavior meet, and the run should leave a record that a reviewer can read without repeating it.
Record the following.
| Testnet question | Record |
|---|---|
| Can an operator discover the Blueprint? | Network, Blueprint identifier, metadata, and job list |
| Can an operator start the service? | Artifact version, settings source, manager version, and startup logs |
| Can a consumer request work? | Service identifier, job identifier, input class, and request result |
| Does a valid job finish? | Output, elapsed time, and transaction or receipt reference when applicable |
| Does an invalid job fail safely? | Error code, timeout behavior, and service state afterward |
| Can a reviewer inspect health? | Heartbeat or status record, health endpoint, and alert owner |
| Can the release be identified? | Source version, artifact fingerprint, and deployment timestamp |
A trace is the ordered record of an execution: inputs, job calls, outputs, errors, and timing. An evaluation is a repeatable check against a stated expectation. Store both with the artifact identity, so a reviewer can tell a service that ran from one that passed the intended check.
A heartbeat shows that an operator reports status within the expected rules; it does not prove that job results are correct. The operator introduction lists the operator responsibilities: running services, submitting heartbeats, responding to jobs, and keeping uptime.
Decide how payment and evidence relate
Payment is part of the deployment contract when the service charges for creation, a subscription, a quote, or each job.
Tangle’s pricing and payments documentation describes PayOnce, Subscription, and EventDriven pricing models and distinguishes on-chain collection from optional x402 settlement.
x402 is an open payment standard built around HTTP 402 Payment Required.
The server returns payment requirements, the client prepares and authorizes a payment payload, and the server verifies and settles it before returning the resource.
A facilitator is the service that verifies and settles an x402 payment on the server’s behalf.
The Blueprint SDK x402 guide documents an optional gateway that advertises job payment requirements, verifies payments through a facilitator, and turns a paid request into a JobCall, the runner’s internal representation of one job request.
x402 is separate from the on-chain job submission path. Treat these as separate checks:
- Did the service communicate the correct payment requirement?
- Did the client authorize the requested payment?
- Did verification or settlement succeed?
- Did the requested job run and return the expected result?
A paid request can settle while the job fails. The production contract needs an explicit policy for retries, refunds, or support when that happens. Payment acceptance is not evidence of output correctness.
Add confidential execution only when the claim needs it
Some services need stronger claims about where code and data ran.
A trusted execution environment (TEE) is a protected execution area designed to isolate code and data from the surrounding host.
An attestation is a signed statement from trusted hardware or an attestation verifier about the software and environment it observed.
An attestation verifier is the software or service that checks that statement against the expected identity and policy.
On Tangle, a service can declare a confidentiality policy such as tee_required, which requires TEE placement and stops instead of falling back when the operator cannot satisfy it.
The execution confidentiality guide documents this policy boundary, and the service API reference documents the request field.
An attestation can support a statement such as “this operator bound the service to the declared protected execution profile.” It does not prove that the model answered correctly, that the application handled every input safely, or that the operator’s surrounding system has no vulnerabilities. Keep the attestation claim beside its assumptions and expiration rules.
If the Blueprint runs an AI agent, an agent profile is the saved configuration for the model, tools, permissions, instructions, and budget used by a run. The profile is application input; the runtime and attestation are execution-boundary evidence; the result still needs an application evaluation.
Make rollback a tested operation
The readiness question for promotion is whether the team can return to a known working version after an unhealthy release.
Keep the previous artifact and its configuration available until the new release has passed its observation period. Record which operator owns the rollback, which command or deployment action performs it, and which health or job check confirms recovery.
Plan each failure separately.
| Failure | First action | Evidence of recovery |
|---|---|---|
| Process will not start | Restore prior artifact or settings | Manager reaches ready state |
| Job returns invalid output | Stop new traffic and inspect result evidence | Known sample job passes with prior version |
| RPC or event stream fails | Switch to documented endpoint or pause intake | Subscriptions and test job recover |
| Payment accepted, job failed | Apply the documented refund or support rule | Payment and job records reconcile |
| Secret compromised | Revoke and rotate the affected key | New key works and old key is unusable |
| Operator capacity is exhausted | Reduce intake or add an approved operator | Queue and latency return to limits |
Test one rollback before production. A runbook that has never been executed is a hypothesis about recovery.
Keep the release boundary visible
The SDK source, the CLI package, the service artifact, the operator manager, the protocol contracts, and the deployed instance can change at different times. Record their versions separately, and claim only what each record shows: a source change is not a released CLI feature until the installable package contains it, a heartbeat does not show that the classifier answered correctly, and an attestation is not a security review. A testnet run shows that the recorded path worked under recorded conditions; production still needs artifact approval, key management, monitoring, payment handling, security review, and rollback evidence.
Check the Blueprint SDK repository, its examples, and the Tangle documentation again when you pin a version or write an operator runbook.
The practical deployment decision
Use the Blueprint SDK when several operators need to run a common service and consumers need a consistent way to discover it, create an instance, call a job, and inspect lifecycle evidence. Keep a normal private service when one team owns the full runtime and needs no protocol-level operator coordination.
Before publishing, require one clean local run, one seeded-network run, one testnet job, one intentional failure, and one rehearsed rollback. Record the artifact fingerprint, network, Blueprint and Service identifiers, operator and manager versions, job result, failure behavior, monitoring owner, and payment policy.
The next useful deployment is the smallest isolated testnet job that produces those records. Promotion can wait until the return path works.