From 2a4f0e18803361e056daf918f27e317e3a353f38 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 14 Jul 2026 01:13:11 +0000 Subject: [PATCH] docs: document MINIMUM_CLAIM_THRESHOLD and credits claim-settlement logs --- .../reference/bundled-plugins/credits.mdx | 20 +++++++++++++++++++ .../reference/environment-variables.mdx | 1 + 2 files changed, 21 insertions(+) diff --git a/build-an-oracle/reference/bundled-plugins/credits.mdx b/build-an-oracle/reference/bundled-plugins/credits.mdx index 7375830..0363069 100644 --- a/build-an-oracle/reference/bundled-plugins/credits.mdx +++ b/build-an-oracle/reference/bundled-plugins/credits.mdx @@ -31,6 +31,7 @@ Silent (no agent-visible tools). When loaded, this plugin also activates the run | `SUBSCRIPTION_URL` | no | Subscription API URL. | | `SUBSCRIPTION_ORACLE_MCP_URL` | no | Subscription Agentic Oracles MCP server URL. | | `DISABLE_CREDITS` | no | Set to `'true'` to skip the plugin entirely. | +| `MINIMUM_CLAIM_THRESHOLD` | no | Positive integer. Held-credit threshold at or above which the settlement cron submits a user's accumulated credits as an on-chain claim. Defaults to `1000` when unset; invalid values log a warning and fall back to the default. Tune per-oracle to trade off transaction cost against settlement latency. | | `NETWORK` | no | Read but not owned (declared by the core base env schema). Required by the cron module. | ## What it contributes @@ -63,6 +64,25 @@ const app = await createOracleApp({ Without a Redis client the middleware loads in pass-through mode and the cron modules are skipped. +## Observing claim settlement + +The settlement cron emits structured logs under the `[Credits/Claims]` prefix — grep for that tag to trace a claim end-to-end. + +- **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=… — ` 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=… | per-claim ceiling maxAmount=… `, so you can confirm the chain-side pricing feeding the split. + +The credit-charging path (`TokenLimiter.creditsForUsage`) also logs a `source=` marker on every request so you can see which of the three pricing fallbacks priced a call: + +| Source | When it fires | +| --- | --- | +| `source=provider-cost` | Provider (e.g. OpenRouter) returned a real USD cost with the response. | +| `source=model-pricing` | Provider cost was missing; per-model input/output pricing was found in cache. | +| `source=flat-rate` | Neither of the above; the flat-rate token-to-credit fallback ran. | + +Each line includes `costUsd=$…` and `→ N credits (network=…)`, which makes it easy to spot sub-1-credit charges rounding to `0`. + ## Opt out / Opt in ```ts diff --git a/build-an-oracle/reference/environment-variables.mdx b/build-an-oracle/reference/environment-variables.mdx index 1ba9aa2..c88b522 100644 --- a/build-an-oracle/reference/environment-variables.mdx +++ b/build-an-oracle/reference/environment-variables.mdx @@ -113,6 +113,7 @@ Only required when the named plugin is loaded. | `credits` | `SUBSCRIPTION_URL` | No | URL. | | `credits` | `SUBSCRIPTION_ORACLE_MCP_URL` | No | URL. | | `credits` | `DISABLE_CREDITS` | No | Enum — exactly `'true'` or `'false'` (any other value fails env validation). `'true'` disables the credit-enforcement middleware; the plugin's `autoDetect` also excludes the whole plugin when `DISABLE_CREDITS=true`. | +| `credits` | `MINIMUM_CLAIM_THRESHOLD` | No | Positive integer (coerced from string). Held-credit threshold at or above which the claim-processing cron settles a user's accumulated credits on-chain. Defaults to `1000` when unset. Invalid values (non-positive, non-numeric) log a warning and fall back to the default. | | `tasks` | `REDIS_URL` | Yes (when loaded) | Triggers autoDetect. | | `tasks` | `TASKS_MAX_PER_USER` | No | Coerced positive int; default `50`. Max scheduled tasks per user. | | `tasks` | `TASKS_RUN_LOCK_TTL_SEC` | No | Coerced positive int; default `600`. Per-run lock TTL (seconds). |