Financial Workflows

Overview

This layer connects the authenticated caller identity, the wallet rail, the on-chain service registry, and the manifest schema that describes each listing. It is the part of Deus that turns a signed agent request into a validated service record, an on-chain registration, and a mirrored listing in the local store.

The code here is split across three concerns: request identity and trust boundaries in deus/internal/auth/auth.go, EVM and wallet transport in deus/internal/chain/*.go and deus/internal/wallet/client.go, and listing validation plus manifest hashing in deus/internal/registry/*.go and deus/pkg/manifest/*.go. The chain binding in deus/internal/chain/bindings/service_registry.go is the contract-facing core that the registry service uses to create, update, and observe service state on Paxeer chain 125.

Architecture Overview

Caller Authentication

Caller Identity Resolution

deus/internal/auth/auth.go

Caller is the authenticated agent identity passed through request context. Middleware extracts it from HTTP headers and either forwards the request with context attached or returns a JSON 401 response. ResolveRequest is the low-level header parser and is the only place that decides whether a request is treated as an agent bearer call or a dev-mode fallback.

Data shape

Functions

Header behavior

ResolveRequest accepts a Bearer token only when the Authorization header starts with Bearer . In dev mode, a missing bearer can still produce a Caller if X-Caller-DID is present, and a missing DID can fall back to the token itself when the token starts with did:. If no DID can be resolved, it fails before the request reaches the handler.

Chain Access

Chain Client

deus/internal/chain/client.go

Client wraps ethclient.Client and verifies that the connected RPC endpoint is on the expected chain. DefaultChainID is 125, and New can reject a connection if the remote chain ID does not match the expected value.

Data shape

Methods

Constructor dependencies

New fails fast when rpcURL is empty, closes the RPC connection if the chain ID check fails, and preserves the configured chain ID even when verification is skipped.

Chain Client Checks

deus/internal/chain/client_test.go

On Chain Payer and Settlement

deus/internal/chain/payer.go

Payer is the chain-backed settlement executor. It holds the settler key, the chain client, the settlement anchor address, and ABI handles for the payment channel and settlement anchor contracts. It is the component that actually submits payout and settlement transactions after off-chain work has been accepted.

Data shapes

Methods

Constructor dependencies

NewPayer rejects a nil chain client, an empty anchor address, or an invalid private key. PayoutDeveloper also rejects the unset placeholder 0xescrow-dev, validates amountWei as base-10, submits payout, waits for mining, and confirms that the receipt status is successful. AnchorSettlement decodes the Merkle root with decodeRoot, verifies that it is exactly 32 bytes, and then submits anchor with the developer address, root, total value, and count.

Payment Streams Precompile

deus/internal/chain/precompiles.go

PaymentStreams is a calldata and read helper for the Paxeer precompile at 0x0000000000000000000000000000000000000906. It does not own transactions; it builds calldata for stream lifecycle operations and performs the accrued read against the precompile.

Data shapes

Methods

Constructor dependencies

Accrued packs the accrued call, uses CallContract against PaymentStreamsAddr, and requires exactly one returned *big.Int. If decoding fails or the output shape does not match, it returns an explicit error.

Service Registry Binding

deus/internal/chain/bindings/service_registry.go

This generated binding is the contract surface used by the registry service to register listings, update them, and listen for contract events. ServiceRegistryMetaData carries the generated ABI JSON, and ServiceRegistryABI is the deprecated alias to ServiceRegistryMetaData.ABI.

Contract metadata values

Core wrapper types

Event payloads

Iterator types

Methods

The event watch methods use WatchLogs, wrap the stream in event.NewSubscription, and forward unpacked events into the sink channel until the sink, the quit channel, or sub.Err() ends the subscription. The iterator variants perform the same unpacking work for historical log scans and stop when Close unsubscribes the underlying subscription.

The generated ABI exposes the following contract errors: InvalidStatus, NotOwner, NotOwnerOrGovernor, ServiceNotFound, and ZeroAddress.

The read methods are also mirrored on ServiceRegistrySession and ServiceRegistryCallerSession with preset CallOpts, and the write methods are mirrored on ServiceRegistrySession and ServiceRegistryTransactorSession with preset TransactOpts.

Service Registry Orchestration

deus/internal/chain/registry.go

Registry is the chain transaction façade used by the higher-level registry service. It binds a deployed ServiceRegistry contract, signs transactions with the caller-provided private key, waits for receipts, and extracts the ServiceRegistered event that contains the on-chain service id.

Data shapes

Request and result shapes

Methods

Constructor dependencies

Register trims an optional 0x prefix from PrivateKeyHex, constructs a keyed transactor, submits the transaction, waits for the receipt, and checks for ReceiptStatusSuccessful. After a successful receipt, it walks the logs from the registry address, parses the first ServiceRegistered event it can decode, and returns the chain service id, tx hash, and block number. If the event is absent, it returns chain: ServiceRegistered event not found.

FilterRegistered uses a bind.FilterOpts starting at fromBlock, requests all service and owner matches with nil filters, and collects the unpacked ServiceRegistryServiceRegistered values until the iterator finishes.

Chain Client Checks

deus/internal/chain/client_test.go

Wallet Clients

Wallet HTTP Client

deus/internal/wallet/client.go

HTTPClient is the remote wallet transport. It forwards the caller bearer token to the wallet API, submits JSON bodies, maps HTTP 403 into PolicyDenied, and returns transaction hashes or stream identifiers for the spending rail. AuthorizeSpend is a configuration guard in this implementation; the actual policy enforcement happens on the money-moving call path when the wallet responds with 403.

Data shapes

Request and result shapes

Methods

Constructor and request dependencies

Every request sets Content-Type: application/json and Authorization: Bearer . do also caps the response body read to 1 MiB, maps 403 responses into PolicyDenied, and returns the parsed wallet response when the call succeeds. OpenStream sends stop_time only when it is greater than zero, and streamToken maps an empty token to the zero address string so native PAX streams do not require an explicit token address.

Dev client stub

Methods

Wallet Client Checks

deus/internal/wallet/client_test.go

Registry Orchestration

Listing Service

deus/internal/registry/registry.go

Service is the orchestrator that creates draft listings, publishes them on chain, mirrors chain state back into the store, and optionally pushes raw listing payloads into a manifest indexer. It is the highest-level workflow in this section and ties together manifest validation, storage, chain registration, and discovery indexing.

Data shapes

Interface

Request and result shapes

Methods

Constructor dependencies

Create validates the raw manifest bytes with manifest.ValidateBytes, then runs ValidateManifest and rejects manifests that fail schema or business rules. It normalizes the requested owner, verifies that it matches the manifest owner, hashes the manifest with manifest.Hash, creates or updates the developer record, inserts the draft service with status draft, and then calls syncChildren to persist endpoint and pricing rows. When embedIdx is present, it indexes the raw manifest after the draft row is inserted.

Publish loads the service row, looks up the developer wallet, and rejects the call when the provided owner does not match the stored wallet. It reparses and revalidates the stored manifest, requires an active deployment when Mode is hosted, computes both the manifest hash and pricing commitment hash, and sends the chain registration through chain.Registry.Register. After the transaction succeeds, it mirrors the chain service id and hashes back into the store, pushes the raw manifest into embedIdx when configured, and asks indexer.Sync to advance discovery from the mined block number.

The helper hexToBytes32 requires exactly 64 hexadecimal characters after 0x stripping, and syncChildren writes one endpoint row and one pricing row per manifest operation and pricing entry.

Registry Validation

deus/internal/registry/validate.go

ValidationResult is the structured validation outcome returned by CreateResult. It separates schema success from warnings, so a reachable listing can still surface a proxy URL warning without blocking the workflow.

Data shape

Functions

ValidateManifest always calls manifest.Validate first. When a manifest is in proxy mode and has a non-empty endpoint.proxy_url, it probes the URL with a HEAD request that times out after three seconds and appends a warning when the target is unreachable or returns a 500-level status. The warning does not prevent Create or Publish from continuing if the manifest is otherwise valid.

Manifest Model and Schema

Manifest Model

deus/pkg/manifest/manifest.go

Manifest is the machine-readable description of a Deus service. It captures identity, ownership, deployment mode, operations, pricing, routing hints, SLA targets, and optional attestation metadata. Operation, Pricing, Endpoint, and SLA are the nested data shapes that carry the per-operation and service-level details.

Data shapes

Nested shapes

Canonicalization and Hashing

deus/pkg/manifest/canonical.go

CanonicalVersion is 1. CanonicalJSON marshals the manifest, rehydrates it into generic JSON, sorts object keys recursively, and returns stable UTF-8 bytes for hashing. Hash returns keccak256(canonical_json(manifest)) as a hex string, and PricingCommitmentHash hashes only schema_version and pricing after applying the same recursive sort logic.

Functions

Parse uses DisallowUnknownFields, so extra keys are rejected before schema validation runs.

Schema Validation

deus/pkg/manifest/schema.go

compiledSchema compiles the embedded schema once with sync.Once. Validate marshals the manifest, validates it against the embedded schema, and then enforces business rules that the schema alone cannot express. ValidateBytes is the raw JSON entrypoint used by the listing service.

Functions

Business rules

Embedded Schema Contract

deus/pkg/manifest/schema.json

Manifest Validation Checks

deus/pkg/manifest/manifest_test.go

State Management

The workflow moves through a small set of explicit states that are proven in code.

The local mirror writes draft rows first, then transitions them to active only after the chain receipt is mined and the ServiceRegistered event is decoded. The contract binding reflects the same lifecycle via event emissions and status constants.

Error Handling

Each layer wraps its own failure mode and keeps the context specific:

• auth.Middleware returns a fixed 401 JSON body for missing or invalid agent bearer credentials.
• chain.New wraps dial failures, chain ID fetch failures, and chain ID mismatches with chain: prefixes.
• Payer validates the private key, anchor address, payout amount, and Merkle root before broadcasting.
• chain.Registry.Register reports private key parsing errors, transactor setup errors, transaction submission errors, receipt wait errors, and missing ServiceRegistered events separately.
• HTTPClient.do maps wallet 403 responses into PolicyDenied so the caller can see cap_wei, while other 4xx and 5xx responses become formatted transport errors.
• ValidateManifest returns structured ValidationResult data, and the listing service decides whether that result is fatal.

Integration Points

• deus/internal/auth/auth.go supplies Caller to downstream services through request context.
• deus/internal/registry/registry.go consumes manifest.ValidateBytes, manifest.Validate, manifest.Hash, and manifest.PricingCommitmentHash.
• deus/internal/registry/registry.go depends on chain.Registry for on-chain registration and on the store for draft and active mirrors.
• deus/internal/wallet/client.go forwards the caller bearer token to the wallet rail and interprets policy denials from the wallet API.
• deus/internal/chain/registry.go bridges the higher-level registry service to deus/internal/chain/bindings/service_registry.go.
• deus/internal/chain/precompiles.go and deus/internal/chain/payer.go cover stream and settlement side effects that sit outside the listing mirror.

Request Flows

Create and Publish a Listing

Wallet Spend and Stream Rails