How to Build a Tangle Blueprint: Test and Deploy

A Tangle Blueprint is a Rust service package that defines jobs, their typed inputs and outputs, and how operators run those jobs for a network service. The shortest reliable path is to start from a maintained example, make one job pass against local Anvil contracts, and only then create a deployment definition for testnet.

This guide was checked on August 1, 2026 against Blueprint SDK commit 00c3cae, including the current hello-tangle example. Use the linked release and source when commands change; older Blueprint tutorials may show job macros and deployment flows that no longer match the current SDK.

Quick Answer

Build a Blueprint in five steps:

1. Install Rust and the cargo-tangle command.
2. Scaffold a Blueprint or copy the maintained example closest to your service.
3. Define a typed job and add it to a router.
4. Run the job against local Anvil contracts and assert the decoded result.
5. Deploy a versioned definition to testnet, register an operator, and exercise the public service path before mainnet.

Do not treat cargo build as production proof. A Blueprint is ready for real users only after the same packaged artifact, contract configuration, operator process, payment path, and result checks work on the target network.

When a Blueprint Fits

Use a Blueprint when independent operators, on-chain service coordination, cryptographic signing, payment settlement, or accountable job execution are part of the product requirement.

Good fit	Poor fit
Threshold signing or multi-party protocols	A conventional CRUD application
Paid compute run by independent operators	A sub-10ms request path
Services that need on-chain job and result records	A private service that must stay on one company’s infrastructure
Agent-callable services with explicit payment and access rules	A frontend with no operator or protocol requirement

The tradeoff is control. A distributed operator service adds contract state, keys, service registration, deployment artifacts, and network failure modes that a single web server does not have.

Start From a Maintained Example

The current public repository includes examples for Tangle, EigenLayer, x402 payments, API-key access, and multi-operator aggregation. For a first Tangle job, use examples/hello-tangle.

Its local test command is:

git clone https://github.com/tangle-network/blueprint.git
cd blueprint
cargo test -p hello-tangle-blueprint --test anvil -- --nocapture

That test boots local Anvil contracts, starts the Blueprint runner, submits an ABI-encoded job, waits for the on-chain result event, decodes the output, and asserts its fields. It is a more useful starting point than a function-only unit test because it crosses the contract, client, router, and runner boundaries used by the service.

Define a Typed Job

The current example defines Solidity-compatible request and response types, then exposes an asynchronous Rust function:

use alloy_sol_types::sol;
use blueprint_tangle_extra::extract::{Caller, TangleArg, TangleResult};

sol! {
    struct DocumentRequest {
        string docId;
        string contents;
    }

    struct DocumentReceipt {
        string docId;
        string contents;
        string operator;
    }
}

pub async fn create_document(
    Caller(caller): Caller,
    TangleArg(request): TangleArg<DocumentRequest>,
) -> TangleResult<DocumentReceipt> {
    // Perform the service work, then return a typed result.
    TangleResult(DocumentReceipt {
        docId: request.docId,
        contents: request.contents,
        operator: format!("0x{}", hex::encode(caller)),
    })
}

The example’s exact implementation and imports are the canonical reference. The important design rule is that the job contract is explicit: the caller can encode the request, the operator can decode it, and the result can be checked without parsing prose.

Route the Job

The router maps a stable job identifier to the function:

use blueprint_router::Router;

pub const CREATE_DOCUMENT_JOB: u8 = 0;

pub fn router() -> Router {
    Router::new().route(CREATE_DOCUMENT_JOB, create_document)
}

Treat job identifiers and input/output schemas as public API. Changing them after deployment can break callers, operator binaries, or contract metadata even if the Rust project still compiles.

Test the Real Local Path

A useful local test should prove more than “the handler returned Ok.” The maintained hello-tangle test covers these steps:

boot local contracts
-> start the Blueprint runner
-> submit an encoded job through the client
-> wait for the job result event
-> decode the returned bytes
-> assert the receipt fields
-> stop the runner

Add failure cases before deployment:

• malformed or oversized input;
• an unauthorized caller;
• a duplicate submission;
• operator restart during work;
• a timeout while waiting for the result;
• a result that cannot be decoded;
• contract or network configuration that points to the wrong deployment.

For paid HTTP access, use the repository’s x402 example and test payment replay, settlement failure, and job failure separately.

Scaffold With cargo-tangle

The repository documents two installation paths for cargo-tangle: the release installer and a source build. The source path is:

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

Pin the release or source commit in CI rather than installing an unspecified future revision on every run. Record cargo tangle --version, the Blueprint SDK version, and the generated project commit with deployment evidence.

Create the Deployment Definition

Testnet deployment uses a definition file that describes the metadata, jobs, and artifact sources the network should register. The current command shape is:

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

The definition needs a metadata URI, manager information, at least one job, at least one artifact source, and either a metadata hash or a local metadata file for the command to hash. Use immutable container digests, release artifacts, or versioned native binaries. Do not point a production definition at a mutable latest tag.

Register and Run an Operator

Deployment creates the service definition; it does not prove an operator can execute it. The operator path also needs:

• network HTTP and WebSocket endpoints;
• a keystore with the correct operator keys;
• the deployed contract addresses and service identifiers;
• a packaged Blueprint artifact the manager can fetch;
• logs and health checks for the runner process;
• a restart plan that does not lose durable work or payment state.

The current repository documents cargo tangle blueprint register-tangle, preregister, and run commands in its main README. Copy the current flags from that source because contract addresses and CLI options are environment-specific.

Production Proof

Before calling a Blueprint production-ready, retain one inspectable record for each layer:

Layer	Required evidence
Source	repository commit and clean build output
Artifact	immutable digest or checksum
Contracts	network, addresses, deployment transaction, and confirmation
Operator	registration transaction, running version, and health output
Job	input identifier, submission transaction or request, and result event
Correctness	decoded result plus a domain-specific assertion
Payment	amount, asset, recipient, settlement receipt, and job identifier
Recovery	tested behavior for restart, timeout, duplicate request, and partial failure

Production is the whole path, not the deploy command. If one row is missing, label that part untested rather than inferring it from another layer.

FAQ

Do I need Rust to build a Tangle Blueprint?

The current Blueprint SDK and maintained examples are Rust-based. Other languages can call exposed HTTP or on-chain interfaces, but the operator service itself follows the Rust SDK path documented here.

What should I build first?

Add one typed job to the maintained hello-tangle example and make its Anvil test pass. That proves the job can cross the same contract, router, and runner path used by the example before you add payment, networking, or multi-operator behavior.

Is a successful local Anvil test enough for production?

No. It proves the local contract and runner path for that case. You still need a versioned testnet deployment, operator registration, public invocation, failure testing, monitoring, and the same packaged artifact intended for production.

Where is the current SDK reference?

Use the Blueprint repository, Tangle documentation, and the example closest to your service. Prefer links pinned to a release or commit when reproducing a result.