Skip to main content

bootstrap

Macro bootstrap 

Source
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 /invoke requests (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]);
}