feat: runner docs and examples

Author: Tjemmmic

pages/developers/_meta.ts

@@ -13,6 +13,7 @@ const meta: Meta = {
   },
   "blueprint-sdk": "Introduction",
   "blueprint-contexts": "Contexts",
+  "blueprint-runner": "Blueprint Runner",
   "p2p-networking": "P2P Networking",
   "tangle-avs": "Build a Tangle Blueprint",
   "eigenlayer-avs": "Build an Eigenlayer AVS",

pages/developers/blueprint-runner/_meta.ts

@@ -0,0 +1,13 @@
+import { Meta } from "nextra";
+
+const meta: Meta = {
+  introduction: "Introduction",
+  jobs: "Jobs",
+  routers: "Routers",
+  producers: "Producers",
+  consumers: "Consumers",
+  "background-services": "Background Services",
+  building: "Building a Blueprint Runner",
+};
+
+export default meta;

pages/developers/blueprint-runner/background-services.mdx

@@ -0,0 +1,79 @@
+---
+title: Background Services
+---
+
+import GithubFileReaderDisplay from '/components/GithubFileReaderDisplay';
+
+# Background Services
+
+Background services are optional components in the [Blueprint Runner](/developers/blueprint-runner/introduction) architecture that run continuously to support the operation of your Actively Validated Service (AVS). This document explains how background services work, how to configure them, and best practices for implementation.
+
+## What are Background Services?
+
+Background services refer to any long-running processes that operate independently of job execution. They:
+
+1. Run continuously in the background
+2. Can perform periodic or ongoing tasks
+3. Might maintain state or connections
+4. Support the overall operation of the Blueprint Runner
+
+Unlike job handlers that execute in response to specific requests, background services operate autonomously to provide supporting functionality.
+
+## Common Use Cases
+
+Background services could be used for various purposes in Blueprints, with the following being only a few examples:
+
+### Data Collection and Aggregation
+
+Services that collect and aggregate data, such as an aggregator that submits aggregated signatures to a Blockchain.
+
+### Monitoring and Health Checks
+
+Services that monitor the state of something, such as a health checker that verifies that a Blueprint is running.
+
+## Background Service Configuration
+
+Background services are typically configured in the `main.rs` file of your Blueprint binary, when building the Blueprint Runner. The configuration involves:
+
+### Basic Background Service Setup
+
+The only requirement for a background service is that it implements the `BackgroundService` trait:
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/a9860d2e3a161af63a75d6d800f662d303e92e5b/examples/incredible-squaring/incredible-squaring-lib/src/lib.rs"
+  fromLine={23}
+  toLine={34}
+  title="Defining a Background Service"
+/>
+
+With a background service defined, it is passed into the Blueprint Runner's builder as producers and consumers are:
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/7774ea42c4d3ec3ff7e170626de3ddce511d1f2f/examples/incredible-squaring/incredible-squaring-bin/src/main.rs"
+  fromLine={36}
+  toLine={67}
+  title="Adding a Background Service to the Blueprint Runner"
+/>
+
+For some background services, it may be necessary to add some sort of cleanup code that runs when the Blueprint Runner shuts down. This can be done in the `with_shutdown_handler` method seen in the above code. This specific example just prints a message, but it might end a background process gracefully.
+
+## Integration with Other Components
+
+Background services work closely with other Blueprint Runner components:
+
+- **Routers**: Background services may provide support for [routers](/developers/blueprint-runner/routers), such as caching or state management
+- **Producers**: Background services can support [producers](/developers/blueprint-runner/producers) by maintaining connections or monitoring event sources
+- **Consumers**: Background services can assist [consumers](/developers/blueprint-runner/consumers) with resource management or periodic tasks
+
+## Next Steps
+
+Now that you understand background services, it might be helpful to take a look at:
+
+- [Routers](/developers/blueprint-runner/routers) - How to direct job calls to appropriate handlers
+- [Producers](/developers/blueprint-runner/producers) - How to capture and process events
+- [Consumers](/developers/blueprint-runner/consumers) - How to handle job results
+- [Building a Blueprint Runner](/developers/blueprint-runner/building) - Step-by-step guide to building your own Blueprint Runner
+
+## Conclusion
+
+Background services are powerful components that enhance the capabilities of your Blueprint Runner by providing continuous support operations. By implementing well-designed background services, you can build more robust, efficient, and feature-rich Blueprints.

pages/developers/blueprint-runner/building.mdx

@@ -0,0 +1,178 @@
+---
+title: Building a Blueprint Runner
+---
+
+import GithubFileReaderDisplay from '/components/GithubFileReaderDisplay';
+
+# 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:
+
+1. [Rust](https://www.rust-lang.org/tools/install) installed
+2. [Tangle CLI](../cli/installation.mdx) installed
+3. A basic understanding of [Blueprints](../blueprints/introduction.mdx)
+4. A Blueprint created with the CLI as seen in [Step 1](#step-1-setting-up-the-project-structure) below
+
+## Blueprint Runner Structure
+
+A Blueprint Runner consists of:
+
+1. **Entry Point**: The runner is the primary component in a blueprint's `main.rs`
+2. **[Jobs](/developers/blueprint-runner/jobs) Configuration**: Build the jobs that will be executed
+3. **[Router](/developers/blueprint-runner/routers) Configuration**: Setup for directing job calls to the jobs themselves for handling
+4. **[Producer](/developers/blueprint-runner/producers) Configuration**: Setup for the source of events (e.g. blockchain, external APIs)
+5. **[Consumer](/developers/blueprint-runner/consumers) Configuration**: Setup for the handling of results from jobs
+6. **[Background Service](/developers/blueprint-runner/background-services) 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](../cli/installation.mdx)):
+
+```bash
+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:
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/a9860d2e3a161af63a75d6d800f662d303e92e5b/examples/incredible-squaring/incredible-squaring-lib/src/lib.rs"
+  fromLine={7}
+  toLine={21}
+  title="Job Definition from our Incredible Squaring Example"
+/>
+
+For more details on defining jobs, see the [Jobs documentation](/developers/blueprint-runner/jobs).
+
+### 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.
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/a9860d2e3a161af63a75d6d800f662d303e92e5b/examples/incredible-squaring/incredible-squaring-bin/src/main.rs"
+  fromLine={28}
+  toLine={31}
+  title="Creating a Producer and a Consumer"
+/>
+
+### Step 4: Configuring the Router
+
+The [router](/developers/blueprint-runner/routers) 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`:
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/a9860d2e3a161af63a75d6d800f662d303e92e5b/examples/incredible-squaring/incredible-squaring-bin/src/main.rs"
+  fromLine={33}
+  toLine={48}
+  title="Configuring the Router"
+/>
+
+This configuration:
+1. Creates a new router
+2. Adds a route for the `square` job with ID `XSQUARE_JOB_ID`
+3. Applies the `TangleLayer` to add metadata to job results
+4. Adds a filter layer to only process jobs that match the service ID
+
+For more details on routers, see the [Routers documentation](/developers/blueprint-runner/routers).
+
+### 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.
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/a9860d2e3a161af63a75d6d800f662d303e92e5b/examples/incredible-squaring/incredible-squaring-lib/src/lib.rs"
+  fromLine={23}
+  toLine={34}
+  title="Defining a Background Service"
+/>
+
+With a background service defined, it just needs to be added to the Blueprint Runner:
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/a9860d2e3a161af63a75d6d800f662d303e92e5b/examples/incredible-squaring/incredible-squaring-bin/src/main.rs"
+  fromLine={36}
+  toLine={49}
+  title="Adding a Background Service to the Blueprint Runner"
+/>
+
+### Step 6: Configuring a Producer with the Blueprint Runner's Builder
+
+[Producers](/developers/blueprint-runner/producers) listen for events and prepare them for processing. The following example uses a `TangleProducer` as seen in [Step 3](#step-3-creating-a-producer-and-a-consumer):
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/a9860d2e3a161af63a75d6d800f662d303e92e5b/examples/incredible-squaring/incredible-squaring-bin/src/main.rs"
+  fromLine={36}
+  toLine={54}
+  title="Adding a Producer to the Blueprint Runner"
+/>
+
+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](/developers/blueprint-runner/producers).
+
+### Step 7: Configuring a Consumer with the Blueprint Runner's Builder
+
+[Consumers](/developers/blueprint-runner/consumers) handle the results of processed jobs. In the example above, we set up a Tangle consumer as seen in [Step 3](#step-3-creating-a-producer-and-a-consumer):
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/a9860d2e3a161af63a75d6d800f662d303e92e5b/examples/incredible-squaring/incredible-squaring-bin/src/main.rs"
+  fromLine={36}
+  toLine={60}
+  title="Adding a Consumer to the Blueprint Runner"
+/>
+
+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](/developers/blueprint-runner/consumers).
+
+### Step 8: Custom Shutdown Logic
+
+Implement customized shutdown logic to handle cleanup and resource release:
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/a9860d2e3a161af63a75d6d800f662d303e92e5b/examples/incredible-squaring/incredible-squaring-bin/src/main.rs"
+  fromLine={36}
+  toLine={65}
+  title="Custom Shutdown Logic"
+/>
+
+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:
+
+```rust
+// 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:
+
+- [Advanced Router Features](/developers/blueprint-runner/routers#advanced-router-features)
+- [Producer Patterns](/developers/blueprint-runner/producers#producer-patterns)
+- [Consumer Patterns](/developers/blueprint-runner/consumers#consumer-patterns)
+
+## 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.

pages/developers/blueprint-runner/consumers.mdx

@@ -0,0 +1,99 @@
+---
+title: Consumers
+---
+
+import GithubFileReaderDisplay from '/components/GithubFileReaderDisplay';
+
+# Consumers
+
+Consumers are a vital component of the [Blueprint Runner](/developers/blueprint-runner/introduction) architecture that handle the results of processed jobs. This document explains how consumers work, how to configure them, and best practices for implementation.
+
+## What are Consumers?
+
+In a Blueprint Runner, consumers are responsible for handling the results of job execution. They:
+
+1. Receive results from jobs via the [router](/developers/blueprint-runner/routers)
+2. Process and transform these results as needed
+3. Perform actions based on the results, such as:
+   - Sending transactions to the blockchain
+   - Updating local state
+   - Triggering other processes
+   - Storing data for later use
+   - Emitting events or notifications
+
+Consumers act as the output handlers of your Blueprint Runner, ensuring that job results lead to appropriate actions.
+
+## Consumer Configuration
+
+Consumers are typically configured in the `main.rs` file of your Blueprint binary, when defining the Blueprint Runner. The configuration involves:
+
+1. Creating a consumer
+2. Defining how it processes job results
+3. Connecting it to jobs via the [router](/developers/blueprint-runner/routers)
+
+### Basic Consumer Setup
+
+First, you define the consumer you want to use. For example, a `TangleConsumer` that listens for finalized blocks on Tangle. After which, you pass the consumer to the Blueprint Runner's builder.
+
+```rust
+let env = BlueprintEnvironment::load()?;
+let sr25519_signer = env.keystore().first_local::<SpSr25519>()?;
+let sr25519_pair = env.keystore().get_secret::<SpSr25519>(&sr25519_signer)?;
+let sr25519_signer = TanglePairSigner::new(sr25519_pair.0);
+
+let tangle_client = env.tangle_client().await?;
+let tangle_producer = TangleProducer::finalized_blocks(tangle_client.rpc_client.clone()).await?;
+let tangle_consumer = TangleConsumer::new(tangle_client.rpc_client.clone(), sr25519_signer);
+
+BlueprintRunner::builder(tangle_config, env)
+    .router(router) // Assuming your router is already defined
+    .producer(tangle_producer)
+    .consumer(tangle_consumer)
+    .run()
+    .await?;
+```
+
+## Types of Consumers
+
+Blueprint Runners can utilize various types of consumers depending on the requirements:
+
+### Tangle Consumer
+
+A Tangle Consumer is a consumer that handles transactions on the Tangle, submitting job results for a Blueprint.
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/7774ea42c4d3ec3ff7e170626de3ddce511d1f2f/crates/tangle-extra/src/consumer/mod.rs"
+  fromLine={39}
+  toLine={51}
+  title="Tangle Consumer Definition"
+/>
+
+### EVM Consumer
+
+An EVM Consumer is a consumer that handles transactions on the EVM, submitting job results for a Blueprint.
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/7774ea42c4d3ec3ff7e170626de3ddce511d1f2f/crates/evm-extra/src/consumer/mod.rs"
+  fromLine={44}
+  toLine={54}
+  title="EVM Consumer Definition"
+/>
+
+## Integration with Other Components
+
+Consumers work closely with other Blueprint Runner components:
+
+- **Routers**: [Routers](/developers/blueprint-runner/routers) pass job results to consumers for handling
+- **Producers**: Results handled by consumers may generate new events for [producers](/developers/blueprint-runner/producers) to process
+
+## Next Steps
+
+Now that you understand consumers, learn about:
+
+- [Routers](/developers/blueprint-runner/routers) - How to direct job calls to appropriate handlers
+- [Producers](/developers/blueprint-runner/producers) - How to capture and process events
+- [Building a Blueprint Runner](/developers/blueprint-runner/building) - Step-by-step guide to building your own Blueprint Runner
+
+## Conclusion
+
+Consumers are essential components that translate job results into meaningful actions in your Blueprint Runner. By implementing robust and efficient consumers, you can ensure that your Blueprint operates reliably and effectively.