Routers

SDK source (GitHub): https://github.com/tangle-network/blueprint/tree/main/crates/runner

A router in the Blueprint Runner maps each job ID to the handler that runs it, validates the parameters, and returns the result.

How a router dispatches a job call

In a Blueprint Runner, a router acts as a traffic director for job execution. When a job is called, the router:

Identifies the correct handler for the job based on the job ID
Validates the job parameters
Passes the parameters to the job handler
Returns the result to the consumer

If no route matches the job ID, the call is rejected before any handler runs.

Router Configuration

Routers are configured when building the Blueprint Runner in the main.rs file of your Blueprint’s binary. The configuration involves:

Creating a new router
Defining routes for each job you have, mapping a job ID to each job in its route
Setting a context for the router, which will contain any resources needed by the jobs

Basic Router Setup

A simple router setup might look like this, assuming you have already created a job and context:

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

Below is a real example from our Incredible Squaring Blueprint Example:

Layers

Layers are used to filter job calls based on certain criteria. There are two places layers can be used:

A specific Route:
- A job can be given a layer. This can be seen in the above code example, where the job is wrapped in the TangleLayer. This adds Tangle metadata to job results for the consumer.
A whole Router:
- A layer can be used to filter job calls based on criteria you control (for example, metadata from Tangle extractors).

Producers in, consumers out

Routers work closely with other Blueprint Runner components:

Producers: Producers pass job calls to the router for processing
Consumers: The router passes job results to Consumers for handling

Next Steps

Now that you understand routers, check out:

Producers - How to capture and process events
Consumers - How to handle job results
Building a Blueprint Runner - Step-by-step guide to building your own Blueprint Runner

Before You Ship

Submit at least one job per route and one unknown job ID. The router should dispatch known calls to the intended handler, reject unknown calls clearly, and preserve the error shape your consumers expect.

Jobs Producers