Deus - Receipts, Vouchers, Metering, and Storage

Overview

The financial primitives layer provides EIP-712 signing for quotes and receipts, deterministic Merkle root hashing for receipt batches, caller-funded payment channels with co-signed vouchers, an invocation metering ledger, and Postgres-backed persistence for all financial state.

EIP-712 Signing

Source: deus/internal/receipts/eip712.go

The Signer creates and verifies EIP-712 typed data for quotes, receipts, and vouchers. It is constructed from a chain ID, a verifying-contract address, and a hex-encoded private key.

Signed message types

Method	EIP-712 type	Returns
`SignQuote`	`DeusQuote`	`{digest, signature}` (0x-hex)
`SignReceipt`	`DeusReceipt`	`{digest, signature}` (0x-hex)
`VoucherDigest`	`DeusVoucher`	digest only (unsigned)
`VerifyQuote`	recovers signer	matches `GatewayAddress`
`VerifyVoucherCaller`	recovers signer	matches `callerWallet`

All signing methods use the same domain pattern: EIP712Domain with name, version, chainId, and verifyingContract. Signatures are normalized to {27,28} recovery bytes.

Utility functions

Function	Description
`RecoverSigner`	Recovers address from digest + signature
`HashPayload`	JSON-marshal + Keccak-256 hash (0x-hex)
`WeiString`	Formats `*big.Int` as decimal wei string

Merkle Root Construction

Source: deus/internal/receipts/merkle.go

MerkleRoot builds deterministic roots over receipt digests with domain separation:

Leaves prefixed with 0x00 before hashing
Internal nodes prefixed with 0x01 before hashing
First layer is sorted (order-independent output)
Odd layers duplicate the trailing node

Channel Voucher Lifecycle

Source: deus/internal/channels/channels.go, deus/internal/channels/voucher.go

Channel operations

Method	Description
`Open`	Validates cap, checks on-chain funding (when available), opens channel row
`Reserve`	Decrements available balance atomically
`Void`	Releases reserved balance without charging
`Finalize`	Applies charge, cumulative spend, voucher nonce, and signature
`Active`	Loads current open channel for a caller

Channels have a fixed 10-minute window. On-chain escrow funding bounds the off-chain cap when EscrowReader is configured.

Voucher operations

Method	Description
`BuildPending`	Computes next cumulative total, increments nonce, returns unsigned EIP-712 digest
`Cosign`	Loads channel, enforces monotonic nonce, verifies caller signature, commits atomically

The Cosign write path atomically updates the channel row and inserts the voucher row in a single transaction.

Metering Ledger

Source: deus/internal/metering/ledger.go

Method	Description
`Reserve`	Inserts a reserved invocation (idempotent on `idempotency_key`), reloads it
`Finalize`	Marks invocation delivered and charged
`Void`	Releases reservation without charging

InsertReservedInvocation uses ON CONFLICT (idempotency_key) DO NOTHING and reloads the existing row on conflict.

Postgres Store

Source: deus/internal/store/store.go

The Store wraps a pgxpool.Pool and provides forward-only migrations. Key tables:

Table	Purpose
`developers`	Developer identity + payee DID
`services`	Service listings with manifest, status, quality
`embeddings`	pgvector embedding vectors
`pricing_plans`	Per-operation pricing (wei + USDX)
`invocations`	Invocation lifecycle (reserved/ok/voided)
`receipts`	Signed receipt envelopes
`settlements`	Settlement windows
`deployments`	Hosted deployment state

InvocationRow

Key fields: ID, IdempotencyKey, ServiceID, CallerDID, Units, PriceWei, Outcome, LatencyMS, Rail, ChannelID, CreatedAt.

ReceiptRow

Key fields: InvocationID, Digest, GatewaySig, RunnerSig.