credits

​

Summary

• Enforcement — per-request middleware that aborts model calls when the user is out of credits (createCreditsMiddleware + TokenLimiter).
• Settlement — background cron that converts held credits into on-chain claims, shipped via ClaimProcessingModule.

​

Environment variables

​

What it contributes

• Tools: none.
• Sub-agents: none.
• Middleware: createCreditsMiddleware (aborts the agent run when the user is out of credits).
• Nest modules (when Redis is configured at construct time):
  • ClaimProcessingModule — cron that settles held credits on chain.
  • FileProcessingSinkModule — FILE_PROCESSING_CREDIT_SINK so pre-flight file-processing LLM usage bills the per-user budget.
  • SubscriptionSinkModule — SUBSCRIPTION_CREDIT_SINK so the subscription middleware mirrors per-DID subscription payload + balance into Redis on every authenticated request.
• HTTP routes: none directly.
• Shared state: none.

​

Production constructor

import { createOracleApp, CreditsPlugin } from '@ixo/oracle-runtime';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL!);

const app = await createOracleApp({
  config,
  plugins: [new CreditsPlugin({ redis, network: 'devnet' })],
});

​

Observing claim settlement

• Boot — one line at startup with the effective settings, e.g. Claim processing initialized: network=… denom=… minimumClaimThreshold=… disableCredits=… matrixAccountRoomId=set|MISSING. Use it to confirm the threshold override and required config actually applied.
• Per tick — one summary line, Cron tick: N user(s) at/above threshold T, then a user=… heldAmount=… — evaluating line per candidate, an explicit SKIP user=… — <reason> for each user the cron drops (below threshold, no subscription payload in Redis, missing oracleClaimsCollectionId, insufficient available credits), and a closing Cron tick complete: submitted=X skipped=Y failed=Z counter.
• Per claim — for every settled claim, the 4-step workflow logs [step 1/4 submitIntent] → [step 2/4 saveToMatrix] → [step 3/4 submitToChain] → [step 4/4 sendToSubsApi], each marked OK or FAILED and carrying the intentTxHash, claimCid, and on-chain chainTxHash values. A successful claim finishes with ✔ SUBMITTED user=… claimCid=…. When held credits exceed the oracle’s per-claim ceiling, the split is announced with heldAmount=… exceeds per-claim max … — splitting into N chunks: ….
• Pricing source — before submitting, the cron logs pricing: fetched on-chain oracle pricing list … and cost: claiming heldAmount=… <denom> | per-claim ceiling maxAmount=… <denom>, so you can confirm the chain-side pricing feeding the split.

​

Opt out / Opt in

const app = await createOracleApp({
  config,
  features: { credits: false }, // never load
});

// Or via env: DISABLE_CREDITS=true

​

Where to read next