Update from code changes: credits claim threshold and settlement logs

build-an-oracle/reference/bundled-plugins/credits.mdx

@@ -1,6 +1,6 @@
 ---
 title: "credits"
 description: "Enforces per-user credit budgets and settles held credits to the chain on a cron."
 icon: "coins"
 ---
 
@@ -20,7 +20,7 @@
 Owns the full credit lifecycle:
 
 - **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`.
 
 Silent (no agent-visible tools). When loaded, this plugin also activates the runtime's Tier-0 `SubscriptionMiddleware`, which gates the HTTP request before the graph even runs.
 
@@ -29,9 +29,10 @@
 | Var | Required | Description |
 | --- | --- | --- |
 | `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
 
@@ -39,7 +40,7 @@
 - **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.
@@ -61,8 +62,27 @@
 });
 ```
 
 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=… — <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.
+
+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

build-an-oracle/reference/environment-variables.mdx

@@ -1,12 +1,12 @@
 ---
 title: "Environment variables"
 description: "Tier-0 (core) vars the runtime always requires, plus per-plugin vars contributed by each bundled plugin's configSchema."
 icon: "key"
 ---
 
 ## How env validation works
 
 The runtime composes one big Zod schema at boot: the **Tier-0 base schema** (always required) plus every loaded plugin's **`configSchema`**. `process.env` is validated against the merged schema. Missing required vars fail boot with `[boot-error] Plugin '<name>' env validation failed for '<field>'`.
 
 Disabling a plugin (via `features` or `autoDetect`) removes its env requirements automatically.
 
@@ -43,7 +43,7 @@
 | --- | --- | --- | --- |
 | `SQLITE_DATABASE_PATH` | string | — | Required. Must persist across restarts. |
 
 ### Blocksync / chain
 
 | Variable | Type | Default | Notes |
 | --- | --- | --- | --- |
@@ -71,7 +71,7 @@
 | `OPEN_ROUTER_API_KEY` | string | — | Required if `LLM_PROVIDER=openrouter`. |
 | `NEBIUS_API_KEY` | string | — | Required if `LLM_PROVIDER=nebius`. |
 
 Cross-field check (`validateLlmProviderKey`): the API key for the selected `LLM_PROVIDER` must be present — `OPEN_ROUTER_API_KEY` when `LLM_PROVIDER=openrouter` (the default), `NEBIUS_API_KEY` when `LLM_PROVIDER=nebius`. A missing key fails boot with a named-field error (e.g. `OPEN_ROUTER_API_KEY` / `NEBIUS_API_KEY`) rather than a generic upstream 401 at request time. The per-role model ids are hardcoded per provider — there is no env var to swap the main model id (use the `resolveModel` hook for that).
 
 ### Misc
 
@@ -105,7 +105,7 @@
 | `composio` | `COMPOSIO_BASE_URL` | No | Defaults to `https://composio.ixo.earth`. |
 | `sandbox` | `SANDBOX_MCP_URL` | Yes | Must be a valid URL. |
 | `skills` | `SKILLS_CAPSULES_BASE_URL` | No | URL. Defaults to `https://capsules.skills.ixo.earth`. |
 | `slack` | `SLACK_BOT_OAUTH_TOKEN` | Yes | Triggers autoDetect. |
 | `slack` | `SLACK_APP_TOKEN` | No | |
 | `slack` | `SLACK_USE_SOCKET_MODE` | No | Defaults to `'true'`. |
 | `slack` | `SLACK_MAX_RECONNECT_ATTEMPTS` | No | Coerced to number; default `10`. |
@@ -113,14 +113,15 @@
 | `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). |
 | `tasks` | `TASKS_MIN_CRON_INTERVAL_SEC` | No | Coerced positive int; default `300`. Minimum allowed cron interval (seconds). |
 | `matrix-group-chats` | `CHANNEL_MEMORY_SYNC_INTERVAL_MS` | No | Coerced int, min `1000`; default `60000`. Debounce window between a write and the Matrix snapshot upload. |
 | `matrix-group-chats` | `GROUP_CHAT_ACTIVE_THREAD_TTL_MS` | No | Coerced int, min `60000`; default `1800000`. How long a thread stays "active with the bot" after a reply. |
 | `matrix-group-chats` | `GROUP_CHAT_REQUIRE_POWER_LEVEL` | No | Coerced int, min `0`; default `0`. Extra minimum power level the bot must have before posting (`0` = use the room default). |
 | `matrix-group-chats` | `GROUP_CHAT_ROOM_INFO_TTL_MS` | No | Coerced int, min `60000`; default `1800000`. How long roomInfo (membership, DM flag) stays cached. |
 | `vfs` | `VFS_MAX_READ_LINES` | No | Coerced positive int; default `2000`. Max lines a single `vfs_read` window returns. |
 | `vfs` | `VFS_REQUEST_TIMEOUT_MS` | No | Coerced positive int; default `20000`. Per-request timeout to the VFS worker. |