https://github.com/tangle-network/blueprint
A powerful toolkit for building distributed systems and infrastructure as code.
https://github.com/tangle-network/blueprint
avs cryptography distributed-systems libp2p mpc multi-party-computation networking p2p restaking zero-knowledge
Last synced: 1 day ago
JSON representation
A powerful toolkit for building distributed systems and infrastructure as code.
- Host: GitHub
- URL: https://github.com/tangle-network/blueprint
- Owner: tangle-network
- License: apache-2.0
- Created: 2023-10-19T18:45:48.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-03-30T12:50:29.000Z (about 2 months ago)
- Last Synced: 2026-04-02T08:25:38.835Z (about 2 months ago)
- Topics: avs, cryptography, distributed-systems, libp2p, mpc, multi-party-computation, networking, p2p, restaking, zero-knowledge
- Language: Rust
- Homepage: https://tangle.tools
- Size: 24.6 MB
- Stars: 334
- Watchers: 2
- Forks: 10
- Open Issues: 42
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE-APACHE
- Agents: AGENTS.md
Awesome Lists containing this project
README
Blueprint SDK
A comprehensive toolkit for building, deploying, and managing blueprints on the Tangle Network.
## Overview
The Blueprint SDK is a modular Rust toolkit for building decentralized services—called Blueprints—that run across networks like [Tangle], EigenLayer, and standard EVM chains.
Blueprints turn complex on-chain and off-chain infrastructure into reproducible, deployable units of logic—think Infrastructure-as-Code for crypto systems.
With one SDK, you can design anything from oracles and MPC networks to agent-based AI services or zk-proof markets, and deploy them seamlessly.
The SDK unifies:
- Job orchestration and routing across async, event-driven systems
- P2P networking with secure message handling and round-based protocol support
- Cryptographic primitives and keystore management for signing, verification, and MPC
- EVM and EigenLayer extensions for direct smart contract and restaking integrations
- Testing and benchmarking utilities for reproducible environments and performance tuning
In short, Blueprints let developers move from concept to distributed protocol with minimal friction.
We also have a [documentation site](https://docs.tangle.tools/) on all things [Tangle] to help you get started.
### SDK Components
The following components make up the SDK, providing everything from job creation and routing utilities to specialized
tools for networking and testing.
* [`blueprint-sdk`] - Main crate for the [Tangle] Blueprint SDK, re-exporting all of the following
* [`blueprint-benchmarking`] - Utilities for benchmarking blueprints
* [`blueprint-build-utils`] - Utilities for simplifying build-time tasks (e.g., building contracts, installing dependencies)
* [`blueprint-chain-setup`] - (**Meta-crate**) Utilities for setting local testnets
* [`blueprint-chain-setup-anvil`] - Utilities for setting up [Anvil] testnets
* [`blueprint-clients`] - (**Meta-crate**) Clients for interacting with [Tangle], [Eigenlayer], and other networks
* [`blueprint-client-core`] - Core client primitives and traits
* [`blueprint-client-tangle`] - Client for interacting with the [Tangle] EVM contracts
* [`blueprint-client-eigenlayer`] - Client for interacting with the [Eigenlayer] Network
* [`blueprint-client-evm`] - Client for interacting with the EVM Network
* [`blueprint-contexts`] - Extensions for adding functionality to custom blueprint context types
* [`blueprint-context-derive`] - Derive macros for implementing context extension traits
* [`blueprint-core`] - Core components for building blueprints, primarily job system primitives
* [`blueprint-crypto`] - (**Meta-crate**) Cryptographic utilities
* [`blueprint-crypto-core`] - Core cryptographic utilities (traits, types)
* [`blueprint-crypto-bls`] - Utilities for working with BLS signatures and keys
* [`blueprint-crypto-bn254`] - Utilities for working with BN254 signatures and keys
* [`blueprint-crypto-ed25519`] - Utilities for working with Ed25519 signatures and keys
* [`blueprint-crypto-hashing`] - Cryptographic hashing utilities
* [`blueprint-crypto-k256`] - Utilities for working with [secp256k1] signatures and keys
* [`blueprint-crypto-sr25519`] - Utilities for working with sr25519 signatures and keys
* [`blueprint-keystore`] - Flexible keystore implementation, supporting local and remote signers
* [`blueprint-macros`] - Utility macros for simplifying blueprint development
* [`blueprint-manager`] - A program executor that connects to the [Tangle] network and runs protocols dynamically on the fly
* [`blueprint-manager-bridge`] - IPC bridge for manager-blueprint communication
* [`blueprint-metrics`] (**Meta-crate**) Utilities for collecting metrics
* [`blueprint-metrics-rpc-calls`] - Utilities for collecting metrics from RPC calls
* [`blueprint-networking`] - P2P networking support for blueprints
* [`blueprint-networking-round-based-extension`] - A networking compatibility layer for [round-based] MPC protocols
* [`blueprint-networking-agg-sig-gossip`] - Aggregated signature gossip extension
* [`blueprint-networking-gossip-primitives`] - Gossip protocol primitives
* [`blueprint-pricing-engine`] - Pricing engine for computing resource costs
* [`blueprint-producers-extra`] - Additional protocol-independent event producers
* [`blueprint-profiling`] - Profiling utilities for performance analysis
* [`blueprint-qos`] - Quality of Service monitoring and metrics
* [`blueprint-router`] - A job router for dynamically scheduling jobs
* [`blueprint-runner`] - The blueprint job runner, executing jobs in a protocol-specific manner
* [`blueprint-std`] - Standard library extensions, for use within the SDK
* [`blueprint-stores`] - (**Meta-crate**) Storage providers for blueprints
* [`blueprint-store-local-database`] - A local JSON key-value database
* [`blueprint-remote-providers`] - Remote cloud provider integrations (AWS, GCP, Azure, etc.)
* [`blueprint-tangle-aggregation-svc`] - Tangle aggregation service for BLS signature aggregation
* [`blueprint-tangle-extra`] - Tangle-specific producers, consumers, and extractors
* [`blueprint-evm-extra`] - EVM specific extensions for blueprints
* [`blueprint-eigenlayer-extra`] - Eigenlayer specific extensions for blueprints
* [`blueprint-faas`] - FaaS (Function-as-a-Service) execution support
* [`blueprint-auth`] - Authentication and authorization utilities
* [`blueprint-testing-utils`] - (**Meta-crate**) Utilities for testing blueprints
* [`blueprint-core-testing-utils`] - Core testing utility primitives
* [`blueprint-anvil-testing-utils`] - Utilities for creating and interacting with Anvil testnets
* [`blueprint-eigenlayer-testing-utils`] - Utilities for creating end-to-end tests for Eigenlayer blueprints
[`blueprint-sdk`]: https://docs.rs/blueprint-sdk
[`blueprint-benchmarking`]: https://docs.rs/blueprint-benchmarking
[`blueprint-build-utils`]: https://docs.rs/blueprint-build-utils
[`blueprint-chain-setup`]: https://docs.rs/blueprint-chain-setup
[`blueprint-chain-setup-anvil`]: https://docs.rs/blueprint-chain-setup-anvil
[`blueprint-clients`]: https://docs.rs/blueprint-clients
[`blueprint-client-core`]: https://docs.rs/blueprint-client-core
[`blueprint-client-tangle`]: https://docs.rs/blueprint-client-tangle
[`blueprint-client-eigenlayer`]: https://docs.rs/blueprint-client-eigenlayer
[`blueprint-client-evm`]: https://docs.rs/blueprint-client-evm
[`blueprint-contexts`]: https://docs.rs/blueprint-contexts
[`blueprint-context-derive`]: https://docs.rs/blueprint-context-derive
[`blueprint-core`]: https://docs.rs/blueprint-core
[`blueprint-crypto`]: https://docs.rs/blueprint-crypto
[`blueprint-crypto-core`]: https://docs.rs/blueprint-crypto-core
[`blueprint-crypto-bls`]: https://docs.rs/blueprint-crypto-bls
[`blueprint-crypto-bn254`]: https://docs.rs/blueprint-crypto-bn254
[`blueprint-crypto-ed25519`]: https://docs.rs/blueprint-crypto-ed25519
[`blueprint-crypto-hashing`]: https://docs.rs/blueprint-crypto-hashing
[`blueprint-crypto-k256`]: https://docs.rs/blueprint-crypto-k256
[`blueprint-crypto-sr25519`]: https://docs.rs/blueprint-crypto-sr25519
[`blueprint-keystore`]: https://docs.rs/blueprint-keystore
[`blueprint-macros`]: https://docs.rs/blueprint-macros
[`blueprint-manager`]: https://docs.rs/blueprint-manager
[`blueprint-manager-bridge`]: https://docs.rs/blueprint-manager-bridge
[`blueprint-metrics`]: https://docs.rs/blueprint-metrics
[`blueprint-metrics-rpc-calls`]: https://docs.rs/blueprint-metrics-rpc-calls
[`blueprint-networking`]: https://docs.rs/blueprint-networking
[`blueprint-networking-round-based-extension`]: https://docs.rs/blueprint-networking-round-based-extension
[`blueprint-networking-agg-sig-gossip`]: https://docs.rs/blueprint-networking-agg-sig-gossip
[`blueprint-networking-gossip-primitives`]: https://docs.rs/blueprint-networking-gossip-primitives
[`blueprint-pricing-engine`]: https://docs.rs/blueprint-pricing-engine
[`blueprint-producers-extra`]: https://docs.rs/blueprint-producers-extra
[`blueprint-profiling`]: https://docs.rs/blueprint-profiling
[`blueprint-qos`]: https://docs.rs/blueprint-qos
[`blueprint-router`]: https://docs.rs/blueprint-router
[`blueprint-runner`]: https://docs.rs/blueprint-runner
[`blueprint-std`]: https://docs.rs/blueprint-std
[`blueprint-stores`]: https://docs.rs/blueprint-stores
[`blueprint-store-local-database`]: https://docs.rs/blueprint-store-local-database
[`blueprint-tangle-extra`]: https://docs.rs/blueprint-tangle-extra
[`blueprint-evm-extra`]: https://docs.rs/blueprint-evm-extra
[`blueprint-eigenlayer-extra`]: https://docs.rs/blueprint-eigenlayer-extra
[`blueprint-faas`]: https://docs.rs/blueprint-faas
[`blueprint-auth`]: https://docs.rs/blueprint-auth
[`blueprint-remote-providers`]: https://docs.rs/blueprint-remote-providers
[`blueprint-tangle-aggregation-svc`]: https://docs.rs/blueprint-tangle-aggregation-svc
[`blueprint-tangle-extra`]: https://docs.rs/blueprint-tangle-extra
[`blueprint-testing-utils`]: https://docs.rs/blueprint-testing-utils
[`blueprint-core-testing-utils`]: https://docs.rs/blueprint-core-testing-utils
[`blueprint-anvil-testing-utils`]: https://docs.rs/blueprint-anvil-testing-utils
[`blueprint-eigenlayer-testing-utils`]: https://docs.rs/blueprint-eigenlayer-testing-utils
## 🚀 Getting Started
### 📋 Prerequisites
Ensure you have the following installed:
- [Rust]
- **OpenSSL Development Packages**
#### For Ubuntu/Debian:
```bash
sudo apt update && sudo apt install build-essential cmake libssl-dev pkg-config
```
#### For macOS:
```bash
brew install openssl cmake
```
### 🔧 CLI Installation
You can install the [Tangle] CLI in two ways:
#### 🚩 **Option 1: Install Script (recommended)**
Install the latest stable version of `cargo-tangle` using the installation script:
```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/tangle-network/blueprint/releases/download/cargo-tangle/v0.1.1-beta.7/cargo-tangle-installer.sh | sh
```
#### 🚩 **Option 2: Install from source**
Install the latest git version of `cargo-tangle` using the following command:
```bash
cargo install cargo-tangle --git https://github.com/tangle-network/blueprint --force
```
### ✨ Creating Your First Blueprint
After installation, you can create, build, register, and run your first blueprint against the [Tangle] EVM:
```bash
# Create a new blueprint named "my_blueprint"
cargo tangle blueprint create --name my_blueprint
# Navigate into the blueprint directory and build
cd my_blueprint
cargo build
# Deploy your blueprint to the [Tangle Network]
# Write the contract coordinates used by your service
cat > settings.env <<'EOF'
BLUEPRINT_ID=0
SERVICE_ID=0
TANGLE_CONTRACT=0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9
RESTAKING_CONTRACT=0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512
STATUS_REGISTRY_CONTRACT=0xdC64a140Aa3E981100a9BecA4E685f962f0CF6C9
EOF
# Register the operator with the on-chain contracts (optional)
cargo tangle blueprint register-tangle \
--http-rpc-url https://rpc.tangle.tools \
--ws-rpc-url wss://rpc.tangle.tools \
--keystore-path ./keystore \
--tangle-contract 0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9 \
--restaking-contract 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512 \
--status-registry-contract 0xdC64a140Aa3E981100a9BecA4E685f962f0CF6C9 \
--blueprint-id 0
# Capture the preregistration payload (TLV file written to ./data by default)
cargo tangle blueprint preregister \
--http-rpc-url http://127.0.0.1:8545 \
--ws-rpc-url ws://127.0.0.1:8546 \
--keystore-path ./keystore \
--settings-file ./settings.env
# Run the blueprint manager against local Anvil (or a real RPC)
cargo tangle blueprint run \
--protocol tangle \
--http-rpc-url http://127.0.0.1:8545 \
--ws-rpc-url ws://127.0.0.1:8546 \
--keystore-path ./keystore \
--settings-file ./settings.env
```
The preregistration flow mirrors the production pipeline: the CLI boots the manager
in `REGISTRATION_MODE_ON`, launches the blueprint with `REGISTRATION_CAPTURE_ONLY=1`,
and waits for it to emit `registration_inputs.bin` under
`./data/blueprint--*/`. Each blueprint can use the helper
`blueprint_sdk::registration::write_registration_inputs` to persist its TLV payload
when `BlueprintEnvironment::registration_mode()` returns `true`.
#### Runtime Preferences
`cargo tangle blueprint run` and `cargo tangle blueprint preregister` accept `--preferred-source`
(`native`, `container`, or `wasm`) plus `--vm/--no-vm` so you can control how the manager fetches and
executes artifacts. Pass `--save-runtime-prefs` to write those choices back to `settings.env`
(`PREFERRED_SOURCE` / `USE_VM`) so future commands inherit the same behavior.
Every CLI action that submits a transaction now reports `tx_submitted` / `tx_confirmed`
lines (or JSON objects when `--json` is used), making it easy to track hashes and block
confirmations in logs or CI pipelines.
And your blueprint is ready to go!
The generated workspace includes `metadata/blueprint-metadata.json` for your
public blueprint metadata and `blueprintUi` hosted app contract. Publish that
file to IPFS or HTTPS, then point `metadata_uri` at it during deployment.
Production Tangle Cloud hosting should use `ipfs://` plus an owner-signed
metadata attestation so advanced tier-2 sections can be verified before
rendering.
### Deploying to Testnet/Mainnet
When targeting real [Tangle] networks, provide a blueprint definition manifest that mirrors the on-chain schema. The file can be JSON, YAML, or TOML and must describe the blueprint metadata, jobs, and artifact sources (container images or native binaries). Once authored, pass it via `--definition`:
```bash
cargo tangle blueprint deploy tangle \
--network testnet \
--definition ./definition.json
```
At minimum the manifest requires `metadata_uri`, `manager`, at least one job,
one source, and either:
- `metadata_hash`: a pinned `0x...` keccak256 digest of the canonical metadata JSON payload
- `metadata_file`: a local path that `cargo tangle` will hash for you before deploy
Fields such as schemas or blueprint-specific config are optional and default to
empty values. See `MIGRATION_EVM_ONLY.md` for a detailed example.
For Tangle-hosted blueprint apps, keep the JSON payload itself offchain in
`metadata/blueprint-metadata.json` and only put its URI in `metadata_uri`.
That keeps the onchain footprint small while letting `tangle-cloud` ingest the
full declarative host contract for cards, actions, resource views, theme
tokens, and approved host modules. If provenance checks fail, the host falls
back to the default protocol blueprint experience.
When `metadata_file` is used, the CLI computes the same canonical payload hash
that Tangle Cloud verifies:
- the file must be a top-level JSON object
- the top-level `integrity` envelope is excluded from hashing
- object keys are sorted recursively before hashing
### 🧪 Testing Locally
The `blueprint-anvil-testing-utils` crate exposes `harness_builder_from_env` for `TangleHarness`, which replays the `LocalTestnet.s.sol` broadcast so every integration test runs against deterministic contract state. Useful commands:
```bash
# Client integration tests (Anvil-backed)
cargo test -p blueprint-client-tangle --test anvil
# Pricing engine QoS listener
cargo test -p blueprint-pricing-engine --test evm_listener
# Blueprint runner end-to-end harness
cargo test -p blueprint-manager --test tangle_runner
# Example blueprint harness (router + runner wired together)
cargo test -p hello-tangle-blueprint --test anvil
```
Each suite boots its own Anvil container via `testcontainers`, so Docker is required when running locally or in CI.
> **Note:** The harness loads `crates/chain-setup/anvil/snapshots/localtestnet-state.json` and falls back to the bundled `localtestnet-broadcast.json` if the snapshot is missing or fails validation. Refresh fixtures with `scripts/fetch-localtestnet-fixtures.sh`, and set `RUN_TNT_E2E=1` to opt into the longer suites.
For a keystore-to-runner walkthrough (keys, env vars, harness commands, and manual
`TangleClient` snippets) see [`docs/operators/anvil.md`](docs/operators/anvil.md).
For additional commands, advanced configurations, and complete CLI usage, see the [official CLI reference](https://docs.tangle.tools/developers/cli/reference).
## 📮 Support
For support or inquiries:
- **Issues:** Report bugs or request features via GitHub Issues.
- **Discussions:** Engage with the community in GitHub Discussions.
- For real-time assistance and announcements:
- Join our [Discord server](https://discord.com/invite/cv8EfJu3Tn)
- Join our [Telegram channel](https://t.me/tanglenet)
---
## Key Concepts
**Blueprint SDK** is a Rust framework for building verifiable, decentralized services on [Tangle Network] with built-in x402 payment rails, multi-operator BLS aggregation, and TEE support.
**Blueprint** is a deployable service specification that defines computation logic, verification requirements, and payment flows in a single package. Operators stake TNT tokens to run blueprints, with slashing for incorrect results.
**x402** is an HTTP-native micropayment protocol built into the SDK that enables per-request payments for blueprint services. Agents pay with signed HTTP headers, no accounts or API keys required.
**Operator** is a node runner who stakes economic collateral (TNT tokens) to execute blueprint jobs. Multiple operators can verify the same job through BLS signature aggregation.
**TangleArg / TangleResult** are extractor types that decode on-chain job inputs and encode results for submission back to the [Tangle] contract layer.
**Router** is the job dispatch system (inspired by axum's router pattern) that maps job IDs to handler functions with middleware support via layers.
---
## Frequently Asked Questions
**What is Blueprint SDK?**
Blueprint SDK is a Rust framework for building verifiable services that run on [Tangle Network] with built-in payment rails and multi-operator verification.
**What language does Blueprint SDK use?**
Rust, with edition 2024 and minimum Rust version 1.88. TypeScript and Python SDKs are on the roadmap.
**How does multi-operator verification work?**
Multiple independent operators run the same job and submit BLS-signed results. An aggregation service collects signatures and verifies threshold agreement before on-chain settlement.
**What is x402 and how does it integrate?**
x402 is an HTTP-native micropayment protocol. The SDK includes an x402 gateway crate with axum middleware that handles payment verification, per-job pricing, and on-chain settlement automatically.
**How do I get started?**
Install cargo-tangle (`cargo install cargo-tangle`), scaffold a project with `cargo tangle blueprint create --name my-service`, and follow the examples in the `examples/` directory.
**What verification modes are supported?**
Count-based thresholds (N-of-M operators must agree) and stake-weighted thresholds (percentage of total stake must sign). Both use BLS signature aggregation.
**Does Blueprint SDK support EigenLayer?**
Yes. Full EigenLayer AVS integration with operator registration, BLS aggregation, and contract deployment via the `eigenlayer` feature flag.
## 📜 License
Licensed under either of
* Apache License, Version 2.0
([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license
([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
## 📬 Feedback and Contributions
We welcome feedback and contributions to improve this blueprint.
Please open an issue or submit a pull request on our GitHub repository.
Please let us know if you fork this blueprint and extend it too!
Contributor references:
- [CONTRIBUTING.md](CONTRIBUTING.md)
- [Harness Engineering Playbook](docs/engineering/HARNESS_ENGINEERING_PLAYBOOK.md)
- [Harness Engineering Spec](docs/engineering/HARNESS_ENGINEERING_SPEC.md)
- [Harness Review Checklist](docs/engineering/HARNESS_REVIEW_CHECKLIST.md)
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.
[Rust]: https://www.rust-lang.org/tools/install
[Tangle]: https://tangle.tools
[Tangle Network]: https://tangle.tools
[Eigenlayer]: https://eigenlayer.xyz
[secp256k1]: https://en.bitcoin.it/wiki/Secp256k1
[round-based]: https://crates.io/crates/round-based
[anvil]: https://book.getfoundry.sh/reference/anvil/