Skip to content

v0.13.0-rc1 - Route-surface gates & async jobs

Pre-release
Pre-release

Choose a tag to compare

View all tags
@bussyjd bussyjd released this 08 Jul 12:39
v0.13.0-rc1
bfaa4c0
This commit was signed with the committer’s verified signature.
bussyjd JeanDaniel Bussy
SSH Key Fingerprint: n8xXg3wKOiM2hpkA4hEBxSGV5bhx8k3rBcc023WaEDQ
Verified
Learn about vigilant mode.

Obol banner

v0.13.0-rc1 - Route-surface gates & async jobs

One offer, many routes — sell a free health check, a paid inference route, and an identity-gated endpoint from a single ServiceOffer, and take long-running paid jobs that settle up front and deliver later.

This release candidate rolls up the route-surface gating, async job-broker, x402 security/spec-fidelity hardening, and x402scan discovery work staged in integration/v0.13.0-rc1, on top of the v0.13.0-rc0 agent-runtime line. Unlike rc0, the full release smoke is green — 16/16 flows — validated from the integration tip on real hardware with remote inference.

Get started by declaring a route table with obol sell http --route and listing it with obol sell register x402scan.

Note

Paid routes settle over x402 on base-sepolia (→ base for production). Identity-gated routes use Sign-In-With-X (EIP-4361/CAIP-122) and never touch the facilitator — a wallet just proves control of an address.

Warning

This software is early alpha, you could lose what you put in. Please use caution when it comes to non-testnet assets. This is a pre-release candidate: do not promote to v0.13.0 until the GA follow-up below (publish the job-broker image) is addressed.

Install / Upgrade

# Install this release candidate
OBOL_RELEASE=v0.13.0-rc1 bash <(curl -s https://stack.obol.org)

# Run the stack
obol stack init && obol stack up

# Sell one offer with mixed gate classes
obol sell http my-api --upstream my-svc --port 8080 \
  --route "path=/health,gate=free" \
  --route "path=/v1/chat/completions,gate=paid" \
  --route "path=/private,gate=auth"

Release Highlights

Multi-route gate classes — one offer, mixed free / paid / identity routes

A ServiceOffer can now declare an explicit route table (spec.routes[]) instead of a single paid catch-all. Each route carries a gate class the x402-verifier enforces per-request, and the published OpenAPI advertises exactly the gate the verifier charges (no discovery/enforcement drift):

  • gate=free — proxied without payment,
  • gate=paid — answered with a 402 challenge until settled,
  • gate=auth — identity-gated by Sign-In-With-X.
obol sell http my-api --upstream my-svc --port 8080 \
  --route "path=/health,gate=free" \
  --route "path=/v1/chat/completions,gate=paid" \
  --route "path=/private,gate=auth"

Undeclared sibling paths fail closed. This is the canonical way to monetize a mixed API surface — a free probe, a paid hot path, and a members-only route — from one offer.

Async job offers — pay up front, deliver later

For work that takes minutes rather than one request/response, --async splits purchase from delivery. The verifier settles payment at accept time and hands the request to a job-broker (behind a NetworkPolicy and, when configured, an HMAC on the verifier→broker hop); the broker replays the call with no deadline and serves the result later, retrieved with the same wallet that paid (SIWx-gated, no second payment).

obol sell http my-audit --async --job-ttl 15m --upstream my-svc --port 8080
# submit → 402 → pay → 202 { jobId, statusUrl, resultUrl, jobToken }
#        → poll statusUrl → GET resultUrl (Authorization: Bearer <jobToken>)

x402 security & spec-fidelity hardening

The paid gateway and route surface were hardened against the review findings on the source PRs:

  • Broker trust boundary — NetworkPolicy pinning job-broker ingress to the verifier pod, plus an optional HMAC over the contract headers (upstreamURL/offer/upstreamAuth) so a pod that slips past the network layer still cannot forge an arbitrary-URL, attacker-credentialed job.
  • Login-CSRF guard on /auth/verify (application/json required, cross-site Sec-Fetch-Site rejected, SameSite=Strict session cookie).
  • Open-redirect fix — sanitizeNextPath rejects backslash-escaped off-origin targets.
  • OpenAPI/verifier gate-drift fix — discovery can no longer advertise a route free that the gate charges.
  • Fail-closed exact-only tables and reserved-path validation at admission.
  • sign-in-with-x interop — the standard SIGN-IN-WITH-X header is accepted, and the 401 challenge advertises the extension (fresh nonce, supported EVM chains) so a stock x402 client can construct the credential.

x402scan discovery

obol sell register x402scan submits the storefront's public origin to the x402scan.com index, signing the registry's Sign-In-With-X challenge via the agent's remote-signer (no key material in the CLI). A local preflight warns when the origin is unreachable, advertises no operations, or collapses many offers into one shared /openapi.json (which reads as a single blurry product to crawlers — one origin per offer is the clean shape).

obol sell register x402scan

Smaller wins

  • job-broker dev image - OBOL_DEVELOPMENT now rewrites :latest image pins to the local dev tag, so the freshly-built job-broker runs instead of ImagePullBackOff-ing against an unpublished registry ref.
  • Live smoke coverage - three previously-unit-only features now have end-to-end flows: identity-gated SIWx routes, async job offers, and multi-route gate classes + per-offer hostname binding.

Breaking changes / Migration notes

  • No breaking changes. New spec.routes[] is additive — offers with no route table keep the implicit paid catch-all.

Validation — release smoke

Full flows/release-smoke.sh run from the integration tip (bfaa4c0) on a wiped k3d cluster, with inference served remotely (external OBOL_LLM_ENDPOINT, gemma4). All 16 flows PASS — release smoke passed.

Flow Result
flow-01-prerequisites PASS
flow-02-stack-init-up PASS
flow-03-inference PASS
flow-04-agent PASS
flow-05-network PASS
flow-06-sell-setup PASS
flow-07-sell-verify PASS
flow-08-buy PASS
flow-09-lifecycle PASS
flow-10-anvil-facilitator PASS
flow-16-sell-agent PASS
flow-17-sell-mcp PASS
flow-19-sell-auth (new — SIWx identity gate) PASS
flow-20-async-job (new — async job-broker) PASS
flow-21-route-surface (new — gate classes + hostname/P1b) PASS
flow-11-dual-stack PASS

The RC-gated live-chain flows (flow-13/flow-14, RELEASE_SMOKE_INCLUDE_OBOL*) were not run in this pass — they require a funded Base Sepolia wallet + paid RPC, which the validation host did not carry.

Known issues / GA follow-ups

  • Publish the job-broker image. It is absent from .github/workflows/docker-publish-x402.yml, so a production (non-OBOL_DEVELOPMENT) install would ImagePullBackOff on ghcr.io/obolnetwork/job-broker:latest. Add it to the publish matrix before promoting to v0.13.0.
  • eth-mainnet eRPC has no public fallback. The single obol-gcp mainnet upstream intermittently trips its own circuit breaker; consider a publicnode fallback like base-sepolia already has.

Superseded PRs

This integration release folds in and supersedes: #697 (x402scan register CLI), #717 (multi-routes + async jobs), #718 (route-surface hardening), #719 (job-broker dev-image fix), #720 / #721 / #722 (live smoke coverage). Promoted to main via #723.

What's Changed

Full Changelog: v0.13.0-rc0...v0.13.0-rc1

Assets 2
Loading