Data Model, Billing, and Financial System

Chapter 7 Data Model, Billing, and Financial System Strategic Takeaway Every job settles at micro-transaction granularity with double-entry accounting and three cost models—so billing attribution is auditable per step, not approximated per workflow. Every job costs something. The Scrypted Network’s financial system must track who paid, what was consumed, what the provider charged, and whether the books balance — all at micro-transaction granularity, across both balance-based and HTTP 402 payment flows. This chapter describes the implemented system. 7.1 Schema overview The core entities and their relationships: • Users — UUID-keyed accounts with balance, type (GUEST, REGISTERED, SYSTEM), and optional invoice capability. • AuthTokens — SHA-256-hashed bearer tokens powering the permissionless identity system (see §7.5). • Jobs — execution instances linked to users, recipes, and billing records. • Ingredients / IngredientVersions — the capability registry (Chapter 5). • LedgerEntries — double-entry transaction log. • RevenueEntries — per-job revenue tracking (user payment, provider cost, margin). • ProviderPayments — outbound payments to upstream providers. • Refunds — issued when jobs fail or are cancelled. • FinancialReconciliation — periodic balance verification. • AssetRetention / RetentionPolicy — storage lifecycle (detailed in §7.7). All monetary columns use NUMERIC(32,18): 32 total digits support transactions up to $999 billion; 18 decimal places accommodate WEI-level precision for cryptocurrency accounting. Storage cost is 17–24 bytes per field. 34

User Job LedgerEntry RevenueEntry ProviderPayment AssetRetention IngVersion CostModel owns posts posts priced Figure 7.1: Core financial and registry links (schematic). Many-to-many and audit tables omitted for clarity. 7.2 SCRYPTOSHI: energy-cost estimation unit SCRYPTOSHI is not an arbitrary subdivision of USDC. It is an energy-cost estimation unit: its value is derived from the CPU cycles required to perform a minimal network action, multiplied by the realized cost of those cycles in USDC. 1 USDC = 109 scryptoshi The base measurement: a c5.2xlarge instance at $0.34/hour executes a minimal operation (database lookup + hash computation) in approximately 5 ms, costing$0.000000472—or 472 scryptoshi. This empirical measurement anchors the unit to physical infrastructure cost. Two floor constants prevent zero-cost abuse: • MIN_INGREDIENT_INVOCATION_COST = 500 scryptoshi—set just above the measured base cost (472), ensuring every ingredient invocation costs at least one minimal measurement operation. • MIN_EXTERNAL_API_INVOCATION_COST = 15,000 scryptoshi—accounting for webhook, polling, and network overhead at approximately 32× the base cost. SCRYPTOSHI is a bounded estimation, not a metering promise. The network does not instrument every CPU cycle. It estimates cost within an order of magnitude, ensuring the accounting layer reflects realized infrastructure cost. The floors are anti-abuse mechanisms with economic justification: they make infinite zero-cost invocation economically impossible at the accounting layer, even when marginal computation cost is negligible. The conversion rate and floor constants are governance-adjustable. If the network migrates to cheaper infrastructure (ARM instances, decentralized workers via Akash or Render), the parameters can be recalibrated to track the new energy cost. The unit is stable; the conversion follows realized cost. The user_balances table stores amount_atomic as a BIGINT in scryptoshi, while the legacy users.balance_amount column retains NUMERIC(32,18) for backward compatibility. Both are updated atomically during funding operations. Connection to agent P&L: Because SCRYPTOSHI is energy-derived, an agent’s introspection loop (Chapter 2) can compare its scryptoshi earnings against its estimated compute cost to determine profitability. The unit being grounded in physical cost makes this comparison meaningful, not circular. 7.3 Cost models and the pricing pipeline Each IngredientVersion carries exactly one IngredientCostModel: 35

Model type Behavior fixed Constant cost per invocation; known before execution. rated Cost proportional to a metered dimension (duration, token count, file size). post_execution Final cost determined after the provider reports actual consumption (e.g., FAL.ai billing). The pricing pipeline for a job:

1. Pre-flight estimation: The PaymentForecaster estimates total cost from the recipe’s step graph and each step’s cost model. For post_execution models, the estimate uses historical averages or configured defaults.

2. Balance check or 402 challenge: If the user’s balance covers the estimate, the amount is reserved. If not, an x402 payment challenge is issued for the shortfall (see §7.6).

3. Execution: Steps run; post_execution costs are resolved as providers report actuals.

4. Settlement: Final costs are committed to the ledger. Over-reserves are returned; underestimates trigger supplemental charges or are absorbed depending on policy. 7.4 Ledger, reconciliation, and audit The LedgerEntry table implements a double-entry transaction log. Each entry records: • user_id, job_id (nullable), transaction_type (funding, deduction, refund, adjustment). • amount and currency at NUMERIC(32,18) precision. • created_at for temporal ordering. RevenueEntry records capture the per-job economic triangle: user payment, provider cost, and profit margin. ProviderPayment tracks outbound settlements with providers (prepaid pool, on-demand, forwarded, refund). FinancialReconciliation runs periodically (daily, weekly, monthly, or manual). It computes: discrepancy = ∑ user_balances − (∑ ledger_credits − ∑ ledger_debits) A non-zero discrepancy triggers investigation. The reconciliation record stores totals, notes, and a balanced / discrepancy / error status. Retention: Ledger and revenue records are long-lived financial data. Data governance (Chapter 9, §9.5) discusses the tension between erasure requests and audit obligations. 7.5 Permissionless bearer token system The Scrypted API uses a permissionless authentication model: no registration, no email, no KYC. Present a bearer token, get an account. Present no token, get a new account automatically.

5. Generation: secrets.token_urlsafe(32) prefixed with scrypted_.

6. Storage: hashlib.sha256(token) stored in auth_tokens.token_hash. The plaintext token is never persisted. 36

7. Lookup: On request, hash the presented token, query by hash, find the user.

8. Auto-creation: If no token or token not found, create a new User (UUID, $0 balance, GUEST type) and AuthToken; return the new token to the caller. The bearer token is simultaneously an auth credential, a billing identity, a job-correlation key, and a privacy dial. The user controls linkability: reuse the token and jobs are correlated; use a fresh token per request and they are unlinkable. Privacy properties and the TEE request-mixing mitigation are discussed in Chapter 13. 7.6 x402 payment flow (as-built) The x402 integration follows Coinbase Developer Platform semantics [5] and the open-source coinbase/x402 types [17]; alternative facilitators (e.g. Nevermined [20]) share the same architectural slot. Three payment paths are implemented: x402 flow: Client pays via the x402 protocol: the server issues a 402 challenge with payment requirements; the client settles (stablecoin on a supported network) and retries with an X-PAYMENT header carrying the base64 payment payload. The X402AuthManager verifies the payment with the appropriate facilitator via the FacilitatorRegistry, checks for replay (receipt hash uniqueness), and creates or authenticates the user. The job is created with payment_method = X402. Balance flow: Client provides Authorization: Bearer <token>. If the balance covers the estimated cost, the deduction proceeds. If insufficient, the server returns a 402 response with a payment challenge containing the facilitator’s invoice for the shortfall. Skip-payment flow: Accounts with invoice_enabled = True (e.g., enterprise or test accounts) skip the balance check and can go negative, settling via periodic invoicing. 7.6.1 Multi-facilitator architecture The FacilitatorRegistry loads facilitator adapters from YAML configuration (config/facilitators.yaml). Each adapter implements BaseFacilitatorAdapter with methods for invoice generation and receipt verification. The current default is coinbase_base (Coinbase Facilitator on Base, USDC). The architecture supports additional facilitators (Polygon, self-hosted, other chains) without code changes — only configuration. 7.7 Asset management and retention tiers Generated artifacts (images, videos, audio) are managed through the AssetRetention system: • Each asset has an expires_at timestamp, s3_key (CDN), and optional ipfs_cid (currently stubbed). • RetentionTier and RetentionPricing define tiered storage policies with per-GB monthly costs. • RetentionPolicy tracks active/cancelled/expired policies per asset with journaled billing. • A Celery worker (asset_cleanup) periodically queries for assets past expiry, deletes them from S3, and marks them PURGED. • MAX_ASSET_RETENTION_DAYS (365) caps the maximum policy horizon. 37

IPFS integration is architecturally present (the ipfs_cid column exists; the ingestion service accepts storage_preference of CDN, IPFS, or ALL) but the IPFS write path is explicitly stubbed with a TODO. This is discussed further in Chapter 15. 38

Source: transcribed from the compiled Scrypted Network Design whitepaper PDF for web reading. Layout, figures, and pagination may differ from the PDF.