Building a Blueprint Runner

This guide provides a step-by-step approach to building a Blueprint Runner, the primary component of a Blueprint.

Prerequisites

Before you start building your Blueprint Runner, ensure you have:

Rust installed
Tangle CLI installed
A basic understanding of Blueprints
A Blueprint created with the CLI as seen in Step 1 below

Blueprint Runner Structure

A Blueprint Runner consists of:

Entry Point: The runner is the primary component in a blueprint’s main.rs
Jobs Configuration: Build the jobs that will be executed
Router Configuration: Setup for directing job calls to the jobs themselves for handling
Producer Configuration: Setup for the source of events (e.g. blockchain, external APIs)
Consumer Configuration: Setup for the handling of results from jobs
Background Service Configuration: Setup for supporting services (e.g. databases, servers, etc.)

Step-by-Step Guide

Step 1: Setting Up the Project Structure

If you haven’t already created a Blueprint project, you can use the Tangle CLI (if you haven’t installed it yet, see here):

cargo tangle blueprint create --name <BLUEPRINT_NAME>

This creates a workspace with two main packages:

Library Package: Contains your job definitions and core logic
Binary Package: Contains your Blueprint Runner implementation

Step 2: Defining Your Jobs

Before building the runner, define the jobs that your Blueprint will execute. Jobs are defined in the library package:

For more details on defining jobs, see the Jobs documentation.

Step 3: Creating a Producer and a Consumer

To build a Blueprint Runner, you need a producer to listen for events and a consumer to handle the results from jobs.

Step 4: Configuring the Router

The router directs job calls to the appropriate handlers. In the example below, we configure the router with a single route for our defined job and specify that it is on Tangle with the TangleLayer:

This configuration:

Creates a new router
Adds a route for the square job with ID XSQUARE_JOB_ID
Applies the TangleLayer to add metadata to job results
Adds a filter layer to only process jobs that match the service ID

For more details on routers, see the Routers documentation.

Step 5: Defining a Background Service

Some blueprints may require one or more services to run in the background. Any number of background services can be set to run for a Blueprint Runner.

With a background service defined, it just needs to be added to the Blueprint Runner:

Step 6: Configuring a Producer with the Blueprint Runner’s Builder

Producers listen for events and prepare them for processing. The following example uses a TangleProducer as seen in Step 3:

This producer listens for finalized blocks on the Tangle network and converts them into job calls that can be processed by the router.

For more details on producers, see the Producers documentation.

Step 7: Configuring a Consumer with the Blueprint Runner’s Builder

Consumers handle the results of processed jobs. In the example above, we set up a Tangle consumer as seen in Step 3:

This consumer processes job results and can send transactions to the Tangle network based on those results.

For more details on consumers, see the Consumers documentation.

Step 8: Custom Shutdown Logic

Implement customized shutdown logic to handle cleanup and resource release:

The above example simply prints a message when the Blueprint Runner is shutting down.

Step 9: Running the Blueprint Runner

Finally, we run the Blueprint Runner:

// Build and run the Blueprint Runner
let result = BlueprintRunner::builder(tangle_config, env)
    // ... configuration ...
    .run()
    .await;

The run method starts the Blueprint Runner and returns a result indicating whether it ran successfully or encountered an error.

With this, the Blueprint Runner, the centerpoint of your Blueprint is ready to be used!

Next Steps

After building your Blueprint Runner, you might want to explore:

Conclusion

Building a Blueprint Runner involves setting up various components that work together to execute your Tangle Blueprint. By following this guide and adhering to best practices, you can create a robust and efficient Blueprint Runner for your Actively Validated Service on the Tangle Network.

Background Services Overview