Jobs

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

Jobs are the core building blocks of a Blueprint Runner. They define the computational tasks that your Blueprint will execute in response to events.

Jobs are event-driven functions

In a Blueprint, jobs are functions that:

Receive inputs from producers
Perform specific computational tasks
Return results that can be processed by consumers

Job Definition

Jobs in a Blueprint are defined in the library package of your project. A job definition consists of:

A unique job ID that identifies the job
A function that implements the job’s logic
Input parameters that the job accepts
Return values that the job produces

Basic Job Structure

Here’s an example of a simple job definition from the Incredible Squaring example:

In this example:

XSQUARE_JOB_ID is a constant that uniquely identifies the job
square is the function that implements the job’s logic
The job takes a single ABI-encoded input parameter x extracted by TangleArg<u64>
The job returns a TangleResult<u64>, which the runner ABI-encodes for submission

Job Context

Jobs can access context information provided by the Blueprint Runner. This context can include:

Configuration settings
Connections to external systems
State information
Utility functions

Context is typically passed to jobs through the router configuration:

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

Job Registration

Jobs need to be registered to a route with the router to be accessible. This is done when defining a Blueprint Runner:

Job Execution Flow

The execution flow of a job in a Blueprint Runner follows these steps:

A producer generates a job call with specific parameters
The router directs the job call to the appropriate job handler
The job executes its logic and produces a result
The result is passed to consumers for further processing

Integration with Other Components

Jobs work closely with other Blueprint Runner components:

Routers: Routers direct job calls to the appropriate job handlers
Producers: Producers generate job calls with specific parameters
Consumers: Consumers process the results of job execution

Next Steps

Now that you understand jobs, it might be helpful to take a look at:

Routers - How to direct job calls to appropriate handlers
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

Test each job with valid input, invalid input, and an execution failure. The handler should reject malformed calls before doing work and return errors that let a consumer decide whether to retry, alert, or stop.

Introduction Routers