Deus - Service Entrypoints, API Server, and Schema Migrations

Overview

This section covers the Deus control plane: the daemon entrypoint (deusd), the HTTP server built on chi router, developer Sign-In-With-Ethereum (SIWE) authentication, the route handlers for registry, discovery, invocation, hosting, and dashboard flows, and the forward-only Postgres migration system.

Source version: 0.1.0-phase6

HTTP Server Assembly

Source: deus/internal/server/server.go

The server uses go-chi/chi/v5 with standard middleware: RequestID, RealIP, Recoverer, and Timeout(60s).

Deps

The server is constructed from a Deps struct that holds all long-lived service dependencies:

Route groups

Health check

GET /internal/healthz pings Postgres and the chain client. Only Postgres health affects the ok field; a chain outage still returns HTTP 200 if Postgres is healthy.

Error Envelope

Source: deus/internal/server/errors.go

type APIError struct {
    Error   string         `json:"error"`
    Message string         `json:"message"`
    Detail  map[string]any `json:"detail,omitempty"`
}

writeAPIError sets Content-Type: application/json, writes the status code, and encodes the APIError.

Developer Authentication (SIWE)

Source: deus/internal/server/devauth.go

Owner-scoped routes (service create, publish, pause, delist, deploy, analytics, earnings) use Sign-In-With-Ethereum (EIP-4361):

1. POST /v1/developers/nonce returns a stateless HMAC-bound nonce (5-minute TTL)
2. POST /v1/developers/auth verifies the SIWE message + personal_sign signature, recovers the wallet, and mints a 24-hour HMAC-bound developer token
3. The token travels as X-Developer-Token on owner routes

Bare X-Developer-Wallet / X-Developer-Address headers are accepted only when DEUS_DEV=1.

Key parameters

Nonces are stateless (random || expiry, HMAC-signed). MetaMask-style v values in {27,28} are normalized before recovery.

Registry Routes

Source: deus/internal/server/handlers_registry.go

The resolveServiceID helper maps slugs to UUIDs so every /{id} route accepts both forms.

Discovery Routes

Source: deus/internal/server/handlers_discovery.go

The catalog enriches each listing with headline pricing and tags from the stored manifest.

Invoke Routes

Source: deus/internal/server/handlers_invoke.go

LXP (LayerX Payment) protocol

When the LXP rail is enabled, invoke follows a challenge-response pattern:

1. Unpaid request returns HTTP 402 with an lxp/1 challenge (fresh nonce + pricing terms)
2. Caller retries with X-LayerX-Payment header containing a signed payment intent
3. Successful response carries X-LayerX-Receipt with the payment receipt

Every payment failure returns a fresh 402 challenge. A rail outage returns 503 payment_unavailable.

Dashboard Routes

Source: deus/internal/server/handlers_dashboard.go

The earnings endpoint assembles a LayerXEarnings block when the LXP rail is active, joining deus invocation aggregates with a live LayerX account read for the developer's payee DID.

Postgres Store

Source: deus/internal/store/store.go

The store wraps a pgxpool.Pool and provides a forward-only migration runner:

• Reads .sql files from a directory in lexical order
• Tracks applied versions in schema_migrations
• Each migration runs in its own transaction
• Requires pgcrypto and pgvector extensions

Migrations