Financial Workflows Service Entrypoints, API Server, Docs, and Schema Migrations

Overview

This section covers the Deus service shell: the daemon entrypoint, operator CLI, HTTP server assembly, developer sign-in flow, channel and settlement handlers, the repository docs that describe the service contract, and the SQL migrations that create the control-plane schema. The code here is the glue that turns the broader marketplace design into a runnable control plane.

From a workflow perspective, deusd is responsible for bootstrapping storage, applying migrations, wiring service facades, and starting the HTTP server. The server then exposes health and metrics endpoints, mounts developer-auth routes, and delegates financial actions to the gateway and settler services. The docs files define the intended product, architecture, data model, and deployment shape that these entrypoints implement.

Source Files in Scope

Service Entrypoints

deus/cmd/deusctl/main.go

deus/docs/00-index.md still describes the repository as a specification with a scaffold-only status, while this section of the repository already contains implemented entrypoints, HTTP handlers, tests, and migrations. Use the index as the design baseline, not as a live inventory.

deusctl is the operator-facing CLI shell. Its main function calls newRoot().Execute(), writes any error to stderr, and exits with status 1 on failure. The root command is labeled deusctl and described as Deus operator CLI.

deus/cmd/deusd/main.go

deusd is the long-running Go control-plane process. The run function loads configuration, establishes storage, applies migrations, wires service facades, starts the HTTP server, and launches the reserve-reaper goroutine that frees expired channel reservations once per minute.

Key startup behavior:

• telemetry.NewLogger() creates the process logger.
• signal.NotifyContext handles SIGINT and SIGTERM.
• config.Load() reads runtime configuration.
• store.New(ctx, cfg.PostgresURI) opens Postgres.
• db.Migrate(ctx, migDir) runs the SQL migrations from cfg.MigrationsDir, resolving relative paths through moduleRoot().
• chain.New(ctx, cfg.RPCURL, cfg.ChainID) is optional and can fail open in dev mode.
• objstore.New is optional and can fall back to objstore.NewMem(cfg.ObjStoreBucket) in dev mode.
• indexer.New(chainRegistry, db) is created only when the chain registry is available.
• discovery.New is initialized with the embedder and ranking weights.
• registry.NewService(db, chainRegistry, ix) is created and then given the discovery service via SetManifestIndexer.
• pricing.New(db), metering.New(db), channels.New, streams.New, gateway.New, and settlement.NewSettler are wired into the server.
• server.New(server.Deps{}) assembles the HTTP stack.
• http.Server is created with ReadHeaderTimeout: 10 * time.Second.
• The process shuts down by waiting on the signal-derived context, then calling both server shutdown paths with a 15*time.Second timeout.

Dev-mode fallbacks are explicit in the code:

• If chain, object store, or registry wiring fails and cfg.Dev is set, the process logs a warning and continues.
• If the object store never materializes in dev mode, an in-memory store is used.
• If the gateway signing key is absent in dev mode, cfg.PublishPrivateKey is reused.
• If no chain payer is available in dev mode, settlement uses &settlement.DevPayer{}.

Operational commands referenced by the repository docs

deus/README.md exposes the local quick-start and operator commands that support the shell:

The README also states that Postgres must have pgcrypto and pgvector installed, and it shows a local DEUS_POSTGRES_URI example together with DEUS_DEV=1 for relaxed local boot.

HTTP Server and Error Envelope

deus/internal/server/server.go

Server is the HTTP composition root. New creates the router, installs middleware, mounts route groups, and stores the resulting router for Handler to return.

Deps

Server

Methods

handleHealthz reports resp.Chain from Chain.Ping(ctx), but only Store.Ping(ctx) affects resp.OK. A chain outage can still return HTTP 200 as long as Postgres is healthy.

The server installs middleware.RequestID, middleware.RealIP, middleware.Recoverer, and middleware.Timeout(60 * time.Second). It mounts /internal/healthz directly, mounts /internal/metrics via the stub handler, then calls the route-group mount functions for developer auth, registry, discovery, invoke, stream, and dashboard flows.

deus/internal/server/errors.go

APIError is the uniform JSON error envelope.

APIError

Helper

Developer Authentication

deus/internal/server/devauth.go

This file implements the developer sign-in flow based on SIWE. NewDeveloperAuth returns nil when the secret is empty, which makes the SIWE endpoints unavailable and leaves the dev-mode header fallback as the only path. Nonces are stateless and HMAC-bound, and tokens are short-lived HMAC-bound wallet tokens.

DeveloperAuth

Methods

Helper functions

HTTP DTOs

Route handlers

Behavioral details visible in source:

• Request bodies are capped with io.LimitReader at 16 * 1024 bytes.
• SIWE messages are capped at 4096 bytes.
• The code accepts MetaMask-style v values in {27,28} and normalizes them before recovery.
• Domain pinning is optional and enforced only when SIWEDomain is set.
• Token and nonce expiry checks use the injected clock function, which makes the tests deterministic.

deus/internal/server/devauth_test.go

The test file proves the auth behavior end to end.

The helper siweMessage builds a message with the URI, Version: 1, Chain ID: 125, Nonce, Issued At, and optional Expiration Time fields. The tests use httptest.NewServer(s.Handler()) to exercise the real router.

Channel and Settlement Handlers

deus/internal/server/handlers_channels.go

This file contains the request handlers that connect the HTTP layer to the financial gateway and settlement services. The handlers are thin: they decode JSON, verify that the needed service dependency exists, and delegate the work.

Runtime guard behavior:

• handleOpenChannel returns 503 if the gateway is unavailable, 401 if the caller is missing from context, and 400 for invalid JSON.
• handleVoucherCosign uses the same gateway and caller checks.
• handleSettleRun returns 503 if the settler is unavailable, 400 for invalid JSON, and 500 if the settlement run fails.

The open-channel and voucher paths are caller-scoped: both explicitly read the caller from the request context before touching the gateway. The settlement-run path is operator-style in the handler body itself; it only requires the settler dependency and a valid JSON body.

Documentation and Operations

deus/docs/00-index.md

The index file is the root of the spec set. It introduces Deus as the marketplace and registry for the agent economy, defines the glossary, and lays out the decision log and cross-cutting conventions. It also shows how the rest of the docs are meant to be read in order.

deus/docs/01-overview.md

This document frames the user problem and solution:

• onboarding friction for machines
• subscriptions that do not fit bursty usage
• anecdotal reputation
• split registry and marketplace products
• custody risk for autonomous spend

It then maps those problems to Deus mechanisms such as pay-per-call usage, PoFQ quality scoring, a single registry-marketplace entity, embedded-wallet spend limits, semantic discovery, free hosting, and zero platform rake. It also defines the personas and success criteria that the runtime shell supports.

deus/docs/02-architecture.md

The architecture spec explains the runtime split:

• Go control plane
• Node execution layer on Paxeer Cloud
• on-chain ServiceRegistry plus Paxeer precompiles
• Postgres and pgvector as the derived mirror
• Next.js console
• Matrix MCP proxy bridge

It also spells out the major flows: service listing, hosted listings, discovery plus invocation, streaming use, confidential calls, and failure behavior such as search fallback, runner failures, settlement retries, policy denials, and chain-RPC failures.

deus/docs/03-data-model.md

The data-model spec establishes authority boundaries between chain, Postgres, and object storage, then defines the service manifest shape and the rebuild invariant. The migration files in this section implement the schema direction described there, including the financial tables for invocations, receipts, channels, vouchers, settlements, spend grants, and deployment state.

deus/docs/13-deployment.md

The deployment doc ties the runtime shell to actual ops:

• placement options for deusd
• hosted execution on Paxeer Cloud
• env vars for Postgres, chain RPC, registry address, settlement anchor, object store, wallet API, embeddings provider, Appwrite, hosting budget, and port
• on-chain deploy order
• daemon-baked MCP proxy rollout
• observability and runbooks
• backups and disaster recovery
• operational invariants

It also states that hosted execution is always Paxeer Cloud, regardless of where the control plane runs, and that the box install path runs deusctl migrate.

Operational references from the docs

Deployment environment variables referenced in deus/docs/13-deployment.md

Schema Migrations

deus/migrations/001_init.sql

This migration creates the initial control-plane schema and is explicitly forward-only and idempotent. It installs pgcrypto and vector, creates the schema_migrations table, and creates the primary control-plane tables:

• developers
• services
• endpoints
• pricing_plans
• embeddings
• quotes
• settlements
• invocations
• receipts
• channels
• vouchers
• spend_grants
• deployments
• index_cursor

It also creates the relevant indexes, including:

• GIN index on services.manifest
• B-tree indexes on service kind/mode/status and quality
• invocation indexes on service, settlement, and caller
• the initial index_cursor row with id = 1

deus/migrations/002_draft_chain_id.sql

This migration drops the NOT NULL constraint from services.chain_id. The result is that a service draft can exist before it has an on-chain identifier.

deus/migrations/003_discovery_search.sql

This migration adds the search fields and indexes used by discovery:

• services.search_document as tsvector
• GIN index on services.search_document
• HNSW index on embeddings.vec
• partial index on active services by kind and status

The file is the schema-side counterpart to the discovery search behavior described in the docs.

Financial Workflow Summary

The source-backed flow across this section is:

1. deusd starts, loads config, and runs migrations.
2. The HTTP server is created with shared dependencies and middleware.
3. Developer auth issues a nonce, verifies SIWE, and mints a short-lived token.
4. Channel handlers call the gateway to open a channel or co-sign a voucher.
5. The settlement handler delegates a window run to the settler.
6. The reserve reaper clears expired channel reservations once per minute.

The code in this section is the control-plane shell around the broader Deus financial and service workflows: it does not implement discovery, wallet policy, hosting execution, or chain contracts itself, but it wires the services that do.