chore: complete blueprint sdk update (#123)

* fix: update contexts, runner structure, and code links wip

* feat: runner docs and examples

* chore: prettier

* chore: fix

* fix: broken link

---------

Co-authored-by: Drew Stone <[email protected]>

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-contexts/_meta.ts

@@ -2,10 +2,11 @@ import { Meta } from "nextra";
 
 const meta: Meta = {
   introduction: "Introduction to Contexts",
-  "keystore-context": "Keystore Context",
+  "eigenlayer-context": "Eigenlayer Context",
   "evm-provider-context": "EVM Provider Context",
+  "keystore-context": "Keystore Context",
+  "services-context": "Services Context",
   "tangle-client-context": "Tangle Client Context",
-  "eigenlayer-context": "Eigenlayer Context",
 };
 
 export default meta;

pages/developers/blueprint-contexts/eigenlayer-context.mdx

@@ -33,10 +33,10 @@ The `EigenlayerContext` trait provides access to core Eigenlayer services and fu
 - Monitor stake across different quorums
 
 <GithubFileReaderDisplay
-  url="https://github.com/tangle-network/blueprint/blob/main/crates/contexts/src/eigenlayer.rs"
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/crates/contexts/src/instrumented_evm_client.rs"
   title="EigenlayerContext Trait Definition"
-  fromLine={5}
-  toLine={9}
+  fromLine={3}
+  toLine={6}
 />
 
 ## Using the Context
@@ -45,37 +45,42 @@ The `EigenlayerContext` trait provides access to core Eigenlayer services and fu
 
 First, define your context struct that implements the `EigenlayerContext` trait:
 
-{/* TODO: Add URL */}
-
 <GithubFileReaderDisplay
-  url=""
-  fromLine={39}
-  toLine={52}
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/examples/incredible-squaring-eigenlayer/src/contexts/aggregator.rs"
+  fromLine={23}
+  toLine={35}
   title="Aggregator Context Definition"
 />
 
-### 2. Use the Context in Jobs
+### 2. Implement methods for the context
 
-You can then use this context in your jobs to access Eigenlayer functionality:
+You can implement methods for the context to provide custom functionality:
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/examples/incredible-squaring-eigenlayer/src/contexts/aggregator.rs"
+  fromLine={245}
+  toLine={261}
+  title="Implementing Methods for the Context"
+/>
+
+### 3. Use the Context in Jobs
 
-{/* TODO: Add URL */}
+You can then use this context in your jobs to access Eigenlayer functionality:
 
 <GithubFileReaderDisplay
-  url=""
-  fromLine={13}
-  toLine={52}
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/examples/incredible-squaring-eigenlayer/src/jobs/initialize_task.rs"
+  fromLine={32}
+  toLine={35}
   title="Using EigenlayerContext in Jobs"
 />
 
-### 3. Instantiate the Context
+### 4. Instantiate the Context
 
 Finally, instantiate your context in your main runner:
 
-{/* TODO: Add URL */}
-
 <GithubFileReaderDisplay
-  url=""
-  fromLine={27}
-  toLine={53}
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/examples/incredible-squaring-eigenlayer/src/main.rs"
+  fromLine={39}
+  toLine={43}
   title="Instantiating the Context"
 />

pages/developers/blueprint-contexts/evm-provider-context.mdx

@@ -13,9 +13,9 @@ The `EvmInstrumentedClientContext` trait provides a standardized [alloy-rs](http
 The `EvmInstrumentedClientContext` trait provides access to an EVM provider:
 
 <GithubFileReaderDisplay
-  url="https://github.com/tangle-network/blueprint/blob/main/crates/contexts/src/instrumented_evm_client.rs"
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/crates/contexts/src/instrumented_evm_client.rs"
   fromLine={3}
-  toLine={7}
+  toLine={6}
   title="EvmInstrumentedClientContext Trait Definition"
 />
 
@@ -26,9 +26,9 @@ The `EvmInstrumentedClientContext` trait provides access to an EVM provider:
 First, define your context struct that implements the `EvmProviderContext` trait:
 
 <GithubFileReaderDisplay
-  url="https://github.com/tangle-network/blueprint/blob/main/crates/macros/context-derive/tests/ui/basic.rs"
-  fromLine={22}
-  toLine={31}
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/crates/macros/context-derive/tests/ui/basic.rs"
+  fromLine={13}
+  toLine={22}
   title="EVM Provider Context Definition"
 />
 
@@ -37,8 +37,8 @@ First, define your context struct that implements the `EvmProviderContext` trait
 You can then use this context to access EVM provider parameters:
 
 <GithubFileReaderDisplay
-  url="https://github.com/tangle-network/blueprint/blob/main/crates/macros/context-derive/tests/ui/basic.rs"
-  fromLine={45}
-  toLine={45}
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/crates/macros/context-derive/tests/ui/basic.rs"
+  fromLine={36}
+  toLine={36}
   title="Accessing EVM Provider Parameters"
 />

pages/developers/blueprint-contexts/introduction.mdx

@@ -4,7 +4,7 @@ title: Introduction to Contexts
 
 ## What is a Context?
 
-In the Gadget SDK, a Context holds utilities and dependencies that a job may need that aren't direct inputs. Think of it as a container for all the external resources and services your job requires to function.
+In the Blueprint SDK, a Context holds utilities and dependencies that a job may need that aren't direct inputs. Think of it as a container for all the external resources and services your job requires to function.
 
 A Context can include various elements such as:
 

pages/developers/blueprint-contexts/keystore-context.mdx

@@ -19,9 +19,9 @@ The `KeystoreContext` trait provides access to a `Keystore` that implements the
 - Key Import/Export - Import existing keys and export key data
 
 <GithubFileReaderDisplay
-  url="https://github.com/tangle-network/blueprint/blob/main/crates/contexts/src/keystore.rs"
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/crates/contexts/src/keystore.rs"
   fromLine={4}
-  toLine={8}
+  toLine={7}
   title="KeystoreContext Trait Definition"
 />
 
@@ -32,9 +32,9 @@ The `KeystoreContext` trait provides access to a `Keystore` that implements the
 First, define your context struct that implements the `KeystoreContext` trait:
 
 <GithubFileReaderDisplay
-  url="https://github.com/tangle-network/blueprint/blob/main/crates/macros/context-derive/tests/ui/basic.rs"
-  fromLine={22}
-  toLine={31}
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/crates/macros/context-derive/tests/ui/basic.rs"
+  fromLine={13}
+  toLine={22}
   title="Keystore Context Definition"
 />
 
@@ -43,8 +43,8 @@ First, define your context struct that implements the `KeystoreContext` trait:
 You can then use this context to access the keystore and perform key operations:
 
 <GithubFileReaderDisplay
-  url="https://github.com/tangle-network/blueprint/blob/main/crates/macros/context-derive/tests/ui/basic.rs"
-  fromLine={44}
-  toLine={44}
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/crates/macros/context-derive/tests/ui/basic.rs"
+  fromLine={35}
+  toLine={35}
   title="Accessing Keystore Functionality"
 />

pages/developers/blueprint-contexts/services-context.mdx

@@ -0,0 +1,49 @@
+---
+title: Services Context
+---
+
+import GithubFileReaderDisplay from '/components/GithubFileReaderDisplay';
+
+# Services Context
+
+The `ServicesContext` trait provides a standardized interface for interacting with the Tangle network in your Blueprint through a Subxt `OnlineClient` with a PolkadotConfig.
+
+## Overview
+
+The `ServicesContext` trait provides access to a Subxt client that enables:
+
+- Fetching Blueprints - Retrieve Blueprints by ID
+- Querying Blueprints - Query Blueprints for an operator
+- Retrieving Blueprint Owners - Return the Owner for a Blueprint
+- Fetching Service Operators - Return a list of operators for a service
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/crates/contexts/src/services.rs"
+  fromLine={3}
+  toLine={9}
+  title="ServicesContext Trait Definition"
+/>
+
+## Using the Context
+
+### 1. Define Your Context
+
+First, define your context struct that implements the `ServicesContext` trait:
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/crates/macros/context-derive/tests/ui/basic.rs"
+  fromLine={13}
+  toLine={22}
+  title="Services Context Definition"
+/>
+
+### 2. Access Services Client Functionality
+
+You can then use this context to access the services client and interact with Tangle services:
+
+<GithubFileReaderDisplay
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/crates/macros/context-derive/tests/ui/basic.rs"
+  fromLine={38}
+  toLine={38}
+  title="Accessing Services Client Functionality"
+/>

pages/developers/blueprint-contexts/tangle-client-context.mdx

@@ -18,9 +18,9 @@ The `TangleClientContext` trait provides access to a Subxt client that enables:
 - RPC Calls - Make direct RPC calls to Tangle nodes
 
 <GithubFileReaderDisplay
-  url="https://github.com/tangle-network/blueprint/blob/main/crates/contexts/src/tangle.rs"
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/crates/contexts/src/tangle.rs"
   fromLine={5}
-  toLine={10}
+  toLine={9}
   title="TangleClientContext Trait Definition"
 />
 
@@ -31,9 +31,9 @@ The `TangleClientContext` trait provides access to a Subxt client that enables:
 First, define your context struct that implements the `TangleClientContext` trait:
 
 <GithubFileReaderDisplay
-  url="https://github.com/tangle-network/blueprint/blob/main/crates/macros/context-derive/tests/ui/basic.rs"
-  fromLine={22}
-  toLine={31}
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/crates/macros/context-derive/tests/ui/basic.rs"
+  fromLine={13}
+  toLine={22}
   title="Tangle Client Context Definition"
 />
 
@@ -42,8 +42,8 @@ First, define your context struct that implements the `TangleClientContext` trai
 You can then use this context to access the Subxt client and interact with Tangle:
 
 <GithubFileReaderDisplay
-  url="https://github.com/tangle-network/blueprint/blob/main/crates/macros/context-derive/tests/ui/basic.rs"
-  fromLine={46}
-  toLine={52}
+  url="https://github.com/tangle-network/blueprint/blob/7d97147417af83ce30f52714c60840c50b9142be/crates/macros/context-derive/tests/ui/basic.rs"
+  fromLine={37}
+  toLine={37}
   title="Accessing Subxt Client Functionality"
 />

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.