Tollbooth Authority

The institution that built the infrastructure.

The metaphors in this project are drawn with admiration from The Phantom Tollbooth by Norton Juster, illustrated by Jules Feiffer (1961). Milo, Tock, the Tollbooth, Dictionopolis, and Digitopolis are creations of Mr. Juster's extraordinary imagination. We just built the payment infrastructure.

The Turnpike Authority

Every turnpike has an authority. Not the operators who run the booths, and not the drivers who pay the fares — but the institution that poured the concrete, erected the signs, and stamped the purchase orders.

The Tollbooth Authority is the Massachusetts Turnpike Authority of the Lightning economy. It doesn't operate any toll booths. It doesn't touch operator BTCPay stores. It never sees user payment data. What it does is simpler and more essential:

• It registers operators who want to run toll booths on the turnpike.
• It collects a modest certification fee — 2% of every fare, minimum 10 sats — paid in advance via Lightning.
• It stamps purchase orders — Schnorr-signed Nostr event certificates (kind 30079) that prove an operator has paid their fee before collecting a fare.
• It never touches the fare itself. The operator collects from the user directly.

The Authority's signature is the proof that the turnpike is legitimate. Without the stamp, the toll booth doesn't open.

Architecture

As of v0.9.0, this Authority is an ~80-line thin consumer of the tollbooth-dpyc wheel. Every piece of generic Authority code — onboarding state machine, Schnorr certificate signer, replay tracker, Neon tenant provisioner, and the full 10-tool MCP surface — lives in the wheel's tollbooth.authority package. This repo's server.py supplies only actor-specific configuration: identity name, human-readable instructions, OperatorRuntime construction, and two register_*_tools(mcp, runtime) calls.

# The entire server.py, distilled
from fastmcp import FastMCP
from tollbooth.authority import (
    AUTHORITY_TOOL_REGISTRY,
    OPERATOR_CREDENTIAL_TEMPLATE,
    register_authority_tools,
)
from tollbooth.runtime import OperatorRuntime, register_standard_tools
from tollbooth.tool_identity import STANDARD_IDENTITIES

mcp = FastMCP("tollbooth-authority", instructions="…")
runtime = OperatorRuntime(
    tool_registry={**STANDARD_IDENTITIES, **AUTHORITY_TOOL_REGISTRY},
    vault_source="env",               # Authority arrives with its own Neon
    purchase_mode="auto",             # derive direct/certified from the registry chain
    service_name="Tollbooth Authority",
    ots_enabled=True,
    operator_credential_template=OPERATOR_CREDENTIAL_TEMPLATE,
)
register_standard_tools(mcp, "authority", runtime, ...)
register_authority_tools(mcp, runtime)

Refactor history:

• v0.5.0 introduced OperatorRuntime and delegated standard tools to the wheel — ~1,900 lines → ~970.
• v0.19.0 required+verified proof on every tool that names it; the local _verify_operator_proof helper was promoted to wheel-side tollbooth.identity_proof.require_proof.
• v0.21.0 (wheel) promoted 6 supporting modules (onboarding, nostr_signing, replay, tenant_provisioner, role_migration, settings) from forked Authority code into tollbooth.authority.*.
• v0.22.0 (wheel) promoted the 10 Authority @tool definitions into register_authority_tools(mcp, runtime).
• v0.9.0 (this release) deleted the eight now-redundant modules and slimmed server.py from ~970 lines to ~80. NorthAmerica and NewEngland followed suit in their own 0.4.0 releases.

Three-Party Protocol

The Tollbooth ecosystem is a three-party protocol spanning three repositories:

The Wider DPYC Federation

The three-party protocol above is the core, but the Authority certifies a wider federation of independent MCP services, all built on the same tollbooth-dpyc SDK:

How It Works

1. Register. An operator connects to the Authority via Horizon MCP and calls register_operator(npub=...). The Authority creates a ledger entry and provisions an isolated Neon schema for the operator.

2. Fund. The operator calls purchase_credits with the number of sats they want to pre-fund. The Authority returns a Lightning invoice from its own BTCPay Server. The operator pays. After settlement, check_payment credits the balance.

3. Certify. When a user wants to buy credits from an operator, the operator's server calls certify_credits. The Authority deducts the 2% ad valorem fee (via the @runtime.paid_tool decorator), signs a Schnorr-based Nostr event certificate, and returns it.

4. Verify. The operator's tollbooth-dpyc library verifies the certificate using the Authority's Nostr npub. Only if the stamp is valid does the operator create a Lightning invoice for the user. No stamp, no fare.

Nostr Certificate Format (kind 30079)

Certificates are Schnorr-signed Nostr events (NIP-33 parameterized replaceable events) rather than Ed25519 JWTs. Each certificate contains the operator npub in a p tag, the certified amount and protocol in t/L tags, an expiration tag, and the content field holds the structured claim data. Verification uses BIP-340 Schnorr signatures against the Authority's Nostr npub.

DPYC Registry Enforcement

The Authority checks the dpyc-community members.json registry at certification time. Operators must have "status": "active" in the registry. The registry is HTTP-cached with a configurable TTL. Design is fail-closed: if the registry is unreachable, certification is denied.

Upstream Topology Is Registry Metadata

Parent Authority relationships live in the dpyc-community registry — each Authority's upstream_authority_npub points at its sponsor. Operator MCPs resolve their certifying Authority via resolve_authority_service(operator_npub) walking that registry chain; no per-Authority env var configures the upstream. The Authority's own certify_credits simply collects the ad valorem fee from its operator's pre-funded balance and signs the certificate — no per-transaction upstream call.

Ad Valorem Pricing

certify_credits is registered as a @runtime.paid_tool with 2% ad valorem pricing on the amount_sats parameter (minimum 10 sats). The fee is debited by the decorator, and the cost is read from runtime._last_debit_cost — no double computation.

OTS Notarization

OpenTimestamps notarization is enabled (ots_enabled=True on the runtime). Ledger state can be notarized and verified through the standard notarize_ledger and get_notarization_proof tools provided by the wheel.

Anti-Replay (ReplayTracker)

Every certificate includes a unique JTI (JWT ID). The Authority tracks seen JTIs in an in-memory ordered dict with TTL-based pruning. This prevents certificate replay attacks even if a certificate is intercepted before expiration.

MCP Tools

All tools are now wheel-defined and registered by the two register_*_tools calls in server.py. For the full canonical tables (Authority tools mounted by register_authority_tools, standard tools mounted by register_standard_tools) see the tollbooth-dpyc README. The short version: