macro_rules! bootstrap {
(@get_addr) => { ... };
($addr:expr, [$tool:ty $(, $next_tool:ty)* $(,)?]) => { ... };
([$($tool:ty),+ $(,)?]) => { ... };
($addr:expr, $tool:ty) => { ... };
($tool:ty) => { ... };
}Expand description
Macro to bootstrap the runtime for a set of tools. The macro generates the necessary routes for each tool and serves them on the provided address.
§Signed HTTP (Leader <-> Tool authentication)
The runtime can optionally require signed /invoke requests and sign the responses.
Configuration is file-based and loaded from crate::ENV_TOOLKIT_CONFIG_PATH. The file schema
is documented on crate::ToolkitRuntimeConfig.
When enabled (signed_http.mode = "required"), the runtime:
- Rejects unsigned or invalidly signed
/invokerequests (fail-closed). - Verifies the Leader signature against a local allowlist (
allowed_leaders/allowed_leaders_path). - Caches completed responses by deterministic nonce and canonical input hash; in-flight nonce reuse is rejected.
- Returns exact ordered BCS Tool output bytes and signs the nonce-bound v3 Tool response message.
- Keeps nonce replay and cached-response handling entirely offchain.
Operational note: your gateway/proxy must forward the X-Nexus-Sig-* headers in both directions.
The request body, nonce, and unsigned identity headers require authenticated HTTPS transport.
Set both NEXUS_TOOL_TLS_CERT_PATH and NEXUS_TOOL_TLS_KEY_PATH to terminate TLS directly in
the Toolkit server. If TLS terminates at a gateway, the gateway-to-Tool hop must provide an
equivalently protected transport; signed HTTP does not make a plaintext hop safe.
§Example config
{
"invoke_max_body_bytes": 10485760,
"signed_http": {
"mode": "required",
"allowed_leaders_path": "./allowed_leaders.json",
"tools": {
"xyz.dummy.tool@1": {
"response_signing_key": "0000000000000000000000000000000000000000000000000000000000000000",
"replay_cache_ttl_ms": 300000
}
}
}
}§--meta flag
When the binary is invoked with --meta, the macro prints a JSON array of
tool metadata (one entry per tool) to stdout and exits immediately — no HTTP
server is started. This is used by CI pipelines to extract registration data
from a Docker image without running the tool.
./my-tool --meta # prints JSON array and exits§Request body limits
/invoke enforces a Content-Length limit via warp::body::content_length_limit.
Requests without a Content-Length header are rejected.
§Examples
§One tool running on 127.0.0.1:8080
use nexus_toolkit::bootstrap;
#[tokio::main]
async fn main() {
bootstrap!(YourTool);
}§Multiple tools running on 127.0.0.1:8080
use nexus_toolkit::bootstrap;
#[tokio::main]
async fn main() {
bootstrap!([YourTool, AnotherTool]);
}§One tool running on the provided address
use nexus_toolkit::bootstrap;
#[tokio::main]
async fn main() {
bootstrap!(([127, 0, 0, 1], 8081), YourTool);
}§Multiple tools running on the provided address
use nexus_toolkit::bootstrap;
#[tokio::main]
async fn main() {
bootstrap!(([127, 0, 0, 1], 8081), [YourTool, AnotherTool]);
}