@ixo/oracle-runtime 0.0.1

package/dist/plugins/credits/claim-processing.service.js

@@ -0,0 +1,406 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var ClaimProcessingService_1;
+import { Claims, Client, Payments } from '@ixo/oracles-chain-client';
+import { Inject, Injectable, InternalServerErrorException, Logger, Optional, } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { Cron, CronExpression } from '@nestjs/schedule';
+import { getSubscriptionUrlByNetwork } from '@ixo/common';
+import { SqliteSaver } from '@ixo/sqlite-saver';
+import { entrypoint, task, } from '@langchain/langgraph';
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { UcanService } from '../../modules/ucan/ucan.service.js';
+import { TokenLimiter } from './token-limiter.js';
+/** Token used to inject the credits-plugin TokenLimiter instance into the service. */
+export const CLAIM_PROCESSING_TOKEN_LIMITER = Symbol.for('ClaimProcessingTokenLimiter');
+/** IBC denom representing uixo on mainnet. */
+const MAINNET_IBC_DENOM = 'ibc/6BBE9BD4246F8E04948D5A4EEE7164B2630263B9EBB5E7DC5F0A46C62A2FF97B';
+/** Minimum held credits before submitting a claim (prevents spam of tiny txns). */
+const MINIMUM_CLAIM_THRESHOLD = 5000;
+/**
+ * Submits held-credit claims to the chain on a fixed cron. Pulls users with
+ * non-zero held amounts from the credits-plugin `TokenLimiter`, then runs a
+ * LangGraph `entrypoint`+`task` workflow per user:
+ *
+ *   1. submit intent (escrow payment)
+ *   2. sign + save the claim to Matrix
+ *   3. submit the claim on-chain
+ *   4. notify the subscription API
+ *
+ * Splits oversized batches against the oracle's per-claim max. Internal,
+ * agent-invisible — `claimProcessingPlugin` declares `visibility: 'silent'`
+ * and ships no tools.
+ */
+let ClaimProcessingService = ClaimProcessingService_1 = class ClaimProcessingService {
+    configService;
+    ucanService;
+    logger = new Logger(ClaimProcessingService_1.name);
+    denom;
+    claimProcessingCheckpointer;
+    claimProcessingDbPath;
+    tokenLimiter;
+    retryPolicy = {
+        maxAttempts: 3,
+        backoffFactor: 2,
+        initialInterval: 1000,
+    };
+    constructor(configService, ucanService, tokenLimiter) {
+        this.configService = configService;
+        this.ucanService = ucanService;
+        if (!tokenLimiter) {
+            throw new Error('ClaimProcessingService requires a TokenLimiter instance (provide via the CLAIM_PROCESSING_TOKEN_LIMITER token).');
+        }
+        this.tokenLimiter = tokenLimiter;
+        this.denom =
+            this.configService.get('NETWORK') === 'mainnet'
+                ? MAINNET_IBC_DENOM
+                : 'uixo';
+        const sqlitePath = this.configService.getOrThrow('SQLITE_DATABASE_PATH');
+        const claimProcessingFolder = path.join(sqlitePath, 'claim_processing');
+        this.claimProcessingDbPath = path.join(claimProcessingFolder, 'claim-processing.db');
+        try {
+            mkdirSync(claimProcessingFolder, { recursive: true });
+        }
+        catch (err) {
+            this.logger.error(`Failed to create claim processing folder: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err.stack : undefined);
+        }
+        // `@ixo/sqlite-saver` and `@langchain/langgraph` end up referencing two
+        // structurally-identical `BaseCheckpointSaver` instances from
+        // separately-resolved `@langchain/langgraph-checkpoint` copies (one via
+        // core@1.1.42, one via core@1.1.45). Bridge once at construction so the
+        // rest of the service sees a single langgraph-native type.
+        const sqliteSaver = SqliteSaver.fromConnString(this.claimProcessingDbPath);
+        this.claimProcessingCheckpointer =
+            sqliteSaver;
+    }
+    /**
+     * Slice `heldAmount` into chunks no larger than `maxAmount`. Used when the
+     * total held amount exceeds the oracle's per-claim ceiling.
+     */
+    calculateSplits(heldAmount, maxAmount) {
+        if (heldAmount <= maxAmount) {
+            return [heldAmount];
+        }
+        const splits = [];
+        let remaining = heldAmount;
+        while (remaining > 0) {
+            const chunk = Math.min(remaining, maxAmount);
+            splits.push(chunk);
+            remaining -= chunk;
+        }
+        return splits;
+    }
+    /** Step 1 of the workflow: pay the user's claim collection escrow. */
+    submitIntentTask = task({
+        name: 'submitIntent',
+        retry: this.retryPolicy,
+    }, async (params) => {
+        const collectionId = params.subscription.claimCollections.oracleClaimsCollectionId;
+        if (!collectionId) {
+            throw new Error('Oracle claims collection ID not found');
+        }
+        const paymentsClient = new Payments();
+        const hasActiveIntent = await paymentsClient.checkForActiveIntent({
+            userClaimCollection: collectionId,
+            granteeAddress: params.configService
+                .getOrThrow('ORACLE_DID')
+                .replace('did:ixo:', ''),
+        });
+        if (hasActiveIntent) {
+            this.logger.log(`User ${params.userDid} already has an active intent, skipping`);
+            return { success: true, transactionHash: null };
+        }
+        const intent = await paymentsClient.sendPaymentToEscrow({
+            amount: {
+                amount: params.heldAmount.toString(),
+                denom: params.denom,
+            },
+            userClaimCollection: collectionId,
+        });
+        if (intent.code !== 0) {
+            throw new Error(`Failed to send payment to escrow: ${intent.rawLog || 'Unknown error'}`);
+        }
+        this.logger.log(`Successfully sent payment to escrow for user: ${params.userDid} with intent tx hash: ${intent.transactionHash}`);
+        return { success: true, transactionHash: intent.transactionHash };
+    });
+    /** Step 2: build a signed claim and stash it in the oracle's Matrix room. */
+    saveToMatrixTask = task({
+        name: 'saveToMatrix',
+        retry: this.retryPolicy,
+    }, async (params) => {
+        const collectionId = params.subscription.claimCollections.oracleClaimsCollectionId;
+        if (!collectionId) {
+            throw new Error('Oracle claims collection ID not found');
+        }
+        const client = Client.getInstance();
+        await client.init();
+        const claimsClient = new Claims(client);
+        // Reuse the signing mnemonic that boot already pulled out of the
+        // oracle's Matrix account room. When this is null (cron tick beat the
+        // post-Matrix-init boot wiring), fall back to the original lookup so
+        // the claim still goes through.
+        const cachedSigningMnemonic = this.ucanService.getSigningMnemonic();
+        if (!cachedSigningMnemonic) {
+            this.logger.warn('Signing mnemonic not yet loaded by UcanService; falling back to per-claim Matrix lookup for this run');
+        }
+        const cid = await claimsClient.saveSignedClaimToMatrix({
+            accessToken: params.configService.getOrThrow('MATRIX_ORACLE_ADMIN_ACCESS_TOKEN'),
+            claim: {
+                amount: [
+                    {
+                        amount: params.heldAmount.toString(),
+                        denom: params.denom,
+                    },
+                ],
+                body: {
+                    amount: params.heldAmount,
+                    oracleDid: params.configService.getOrThrow('ORACLE_DID'),
+                    oracleEntityDid: params.configService.getOrThrow('ORACLE_ENTITY_DID'),
+                    service: `Chatting With AI ${params.configService.getOrThrow('ORACLE_NAME')}`,
+                    oracleName: params.configService.getOrThrow('ORACLE_NAME'),
+                    userDid: params.userDid,
+                },
+            },
+            collectionId,
+            matrixRoomId: params.configService.get('MATRIX_ACCOUNT_ROOM_ID') ?? '',
+            secpMnemonic: params.configService.getOrThrow('SECP_MNEMONIC'),
+            matrixValuePin: params.configService.getOrThrow('MATRIX_VALUE_PIN'),
+            oracleDid: params.configService.getOrThrow('ORACLE_DID'),
+            network: params.configService.getOrThrow('NETWORK'),
+            decryptedSigningMnemonic: cachedSigningMnemonic ?? undefined,
+        });
+        this.logger.log(`Successfully submitted and saved signed claim ${cid} for user: ${params.userDid}`);
+        return { cid };
+    });
+    /** Step 3: submit the signed claim on-chain against the user's collection. */
+    submitToChainTask = task({
+        name: 'submitToChain',
+        retry: this.retryPolicy,
+    }, async (params) => {
+        const collectionId = params.subscription.claimCollections.oracleClaimsCollectionId;
+        if (!collectionId) {
+            throw new Error('Oracle claims collection ID not found');
+        }
+        const client = Client.getInstance();
+        await client.init();
+        const claimsClient = new Claims(client);
+        const result = await claimsClient.submitClaim({
+            claimId: params.cid,
+            collectionId,
+            useIntent: true,
+            amount: [
+                {
+                    amount: params.heldAmount.toString(),
+                    denom: params.denom,
+                },
+            ],
+        });
+        if (result.code !== 0) {
+            throw new Error(`Failed to submit claim to chain: ${result.rawLog || 'Unknown error'}`);
+        }
+        this.logger.log(`Successfully submitted claim ${params.cid} to chain for user: ${params.userDid}`);
+        return { success: true, transactionHash: result.transactionHash };
+    });
+    /** Step 4: notify the subscription API so it can update the user's balance. */
+    sendToSubsApiTask = task({
+        name: 'sendToSubsApi',
+        retry: this.retryPolicy,
+    }, async (params) => {
+        const subscriptionUrl = this.configService.get('SUBSCRIPTION_URL') ??
+            getSubscriptionUrlByNetwork(params.configService.getOrThrow('NETWORK'));
+        await submitClaimToSubscriptionApi(subscriptionUrl, params.cid);
+        this.logger.log(`Successfully sent claim ${params.cid} to subscription API for user: ${params.userDid}`);
+        return { success: true };
+    });
+    /**
+     * Per-call factory so the langgraph `entrypoint` always picks up the
+     * checkpointer initialized in `constructor`.
+     */
+    getProcessClaimWorkflow() {
+        return entrypoint({
+            checkpointer: this.claimProcessingCheckpointer,
+            name: 'processClaim',
+        }, async (params) => {
+            await this.submitIntentTask(params);
+            const { cid } = await this.saveToMatrixTask(params);
+            await this.submitToChainTask({ ...params, cid });
+            await this.sendToSubsApiTask({ ...params, cid });
+            return { success: true, cid };
+        });
+    }
+    /**
+     * Cron-triggered processor — walks users above the minimum held-credits
+     * threshold, splits oversized batches against the oracle's per-claim max,
+     * and runs the 4-step claim workflow for each. Errors are logged and
+     * isolated per-user so one user's failure doesn't stall the batch.
+     */
+    async processHeldAmount() {
+        const matrixAccountRoomId = this.configService.get('MATRIX_ACCOUNT_ROOM_ID');
+        const disableCredits = Boolean(this.configService.get('DISABLE_CREDITS')) ||
+            !matrixAccountRoomId;
+        if (disableCredits) {
+            this.logger.debug('Claims task submission skipped (DISABLE_CREDITS=true)');
+            return;
+        }
+        const users = await this.tokenLimiter.listUsersWithHeldAmount(MINIMUM_CLAIM_THRESHOLD);
+        this.logger.log(`Processing held amount for ${users.length} users`);
+        for (const [userDid, rawHeldAmount] of users) {
+            try {
+                const heldAmount = Math.round(rawHeldAmount);
+                if (heldAmount < MINIMUM_CLAIM_THRESHOLD) {
+                    this.logger.debug(`Held amount ${heldAmount} for user ${userDid} below threshold ${MINIMUM_CLAIM_THRESHOLD}, skipping`);
+                    continue;
+                }
+                const subscription = await this.tokenLimiter.getSubscriptionPayload(userDid);
+                if (!subscription) {
+                    this.logger.warn(`No subscription found for user: ${userDid}`);
+                    continue;
+                }
+                if (!subscription.claimCollections.oracleClaimsCollectionId) {
+                    this.logger.warn(`No oracle claims collection ID found for user: ${userDid}`);
+                    continue;
+                }
+                const availableCredits = subscription.totalCredits;
+                if (availableCredits < heldAmount) {
+                    this.logger.warn(`Insufficient available credits found for user: ${userDid}`);
+                    continue;
+                }
+                const oraclePricingList = await Payments.getOraclePricingList(this.configService.getOrThrow('ORACLE_ENTITY_DID'));
+                const maxAllowedClaimAmount = oraclePricingList.find((item) => item.denom === this.denom)?.amount;
+                if (!maxAllowedClaimAmount) {
+                    throw new InternalServerErrorException(`Max allowed claim amount not found for denom: ${this.denom}`);
+                }
+                const maxAmount = parseInt(maxAllowedClaimAmount, 10);
+                const splits = this.calculateSplits(heldAmount, maxAmount);
+                const collectionId = subscription.claimCollections.oracleClaimsCollectionId;
+                const subscriptionForProcessing = {
+                    adminAddress: subscription.adminAddress,
+                    claimCollections: {
+                        oracleClaimsCollectionId: collectionId,
+                    },
+                    totalCredits: subscription.totalCredits,
+                };
+                if (splits.length > 1) {
+                    this.logger.log(`Held amount ${heldAmount} for user ${userDid} exceeds max allowed ${maxAmount}. Splitting into ${splits.length} chunks: ${splits.join(', ')}`);
+                    for (let i = 0; i < splits.length; i++) {
+                        const splitAmount = splits[i];
+                        try {
+                            await this.processAmount(userDid, splitAmount, subscriptionForProcessing, {
+                                index: i + 1,
+                                total: splits.length,
+                                originalAmount: heldAmount,
+                            });
+                        }
+                        catch (error) {
+                            this.logger.error(`Error processing split ${i + 1}/${splits.length} for user ${userDid}:`, error instanceof Error ? error.message : String(error), error instanceof Error ? error.stack : undefined);
+                            throw new Error(`Failed to process split ${i + 1}/${splits.length}: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                    this.logger.log(`Successfully processed all ${splits.length} splits for user: ${userDid}`);
+                }
+                else {
+                    this.logger.log(`Processing held amount ${heldAmount} for user ${userDid} (no splitting needed)`);
+                    await this.processAmount(userDid, heldAmount, subscriptionForProcessing);
+                }
+            }
+            catch (error) {
+                this.logger.error(`Error processing held amount for user ${userDid}:`, error instanceof Error ? error.message : String(error), error instanceof Error ? error.stack : undefined);
+                // Don't clear held amount or pending claim - will retry next run.
+            }
+        }
+    }
+    /**
+     * Invoke the LangGraph workflow for a single amount (full or split chunk)
+     * and reconcile the held-amount / pending-claim records on success.
+     */
+    async processAmount(userDid, heldAmount, subscription, splitContext) {
+        if (heldAmount <= 0) {
+            throw new Error(`Invalid held amount: ${heldAmount}. Must be greater than 0.`);
+        }
+        if (splitContext) {
+            this.logger.log(`Processing split ${splitContext.index}/${splitContext.total} (amount: ${heldAmount}, original: ${splitContext.originalAmount}) for user: ${userDid}`);
+        }
+        const internalClaimId = await this.tokenLimiter.getOrCreatePendingClaim(userDid, heldAmount);
+        const workflowParams = {
+            userDid,
+            heldAmount,
+            subscription,
+            internalClaimId,
+            denom: this.denom,
+            configService: this.configService,
+        };
+        // Unique thread ID per split so checkpointer state doesn't collide.
+        const threadId = splitContext
+            ? `${userDid}:${internalClaimId}:split${splitContext.index}`
+            : `${userDid}:${internalClaimId}`;
+        const config = {
+            configurable: {
+                thread_id: threadId,
+            },
+        };
+        const workflow = this.getProcessClaimWorkflow();
+        const result = await workflow.invoke(workflowParams, config);
+        if (result.success && result.cid) {
+            await this.tokenLimiter.clearPendingClaim(userDid);
+            if (splitContext) {
+                await this.tokenLimiter.incrementUserHeldAmount(userDid, -heldAmount);
+                this.logger.log(`Successfully processed split ${splitContext.index}/${splitContext.total} (claim ${result.cid}) and decremented held amount by ${heldAmount} for user: ${userDid}`);
+            }
+            else {
+                await this.tokenLimiter.deleteUserHeldAmount(userDid);
+                this.logger.log(`Successfully processed claim ${result.cid} and cleared held amount and pending claim for user: ${userDid}`);
+            }
+        }
+        else {
+            this.logger.warn(`Workflow completed but result indicates failure for user: ${userDid}${splitContext
+                ? ` (split ${splitContext.index}/${splitContext.total})`
+                : ''}`);
+        }
+    }
+};
+__decorate([
+    Cron(CronExpression.EVERY_MINUTE),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], ClaimProcessingService.prototype, "processHeldAmount", null);
+ClaimProcessingService = ClaimProcessingService_1 = __decorate([
+    Injectable(),
+    __param(2, Optional()),
+    __param(2, Inject(CLAIM_PROCESSING_TOKEN_LIMITER)),
+    __metadata("design:paramtypes", [ConfigService,
+        UcanService,
+        TokenLimiter])
+], ClaimProcessingService);
+export { ClaimProcessingService };
+/**
+ * Submit a saved claim to the subscription-API webhook so the upstream
+ * service can mark it credited. Kept inline (rather than a separate file)
+ * since it's only used here and trivial.
+ */
+export async function submitClaimToSubscriptionApi(subscriptionApiUrl, claimId) {
+    const webhookUrl = `${subscriptionApiUrl}/api/v1/webhook/claim-submitted`;
+    Logger.log('Submitting claim to subscription API', 'SubmitClaimToSubscriptionApi', { webhookUrl, claimId });
+    const response = await fetch(webhookUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ claimId }),
+    });
+    if (!response.ok) {
+        const errorBody = await response.text();
+        Logger.error(`Subscription API error: ${response.status} ${errorBody}`, 'SubmitClaimToSubscriptionApi', { status: response.status, errorBody, claimId });
+        throw new Error(`Subscription API error: ${response.status} ${errorBody}`);
+    }
+    return (await response.json());
+}

package/dist/plugins/credits/credits-middleware.d.ts

@@ -0,0 +1,23 @@
+import { type AgentMiddleware } from 'langchain';
+import type { Logger } from '../../plugin-api/types.js';
+import { type TokenLimiter } from './token-limiter.js';
+export interface CreditsMiddlewareOptions {
+    /** Active limiter. When `null`, the middleware skips silently. */
+    limiter: TokenLimiter | null;
+    /** Optional logger; defaults to a no-op. */
+    logger?: Logger;
+}
+/**
+ * Per-user credit-budget guard. Runs on every model call:
+ *
+ *   - `beforeModel` aborts the call with a polite message when the user
+ *     has no remaining balance.
+ *   - `afterModel` computes the credit cost of the completion (3-priority
+ *     fallback: provider USD cost → per-model pricing → flat rate) and
+ *     deducts it atomically via `TokenLimiter.limit`.
+ *
+ * Silently passes through when `limiter` is `null` — that's how the credits
+ * plugin signals "disabled or no Redis" without breaking the graph.
+ */
+export declare const createCreditsMiddleware: (options: CreditsMiddlewareOptions) => AgentMiddleware;
+//# sourceMappingURL=credits-middleware.d.ts.map

package/dist/plugins/credits/credits-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credits-middleware.d.ts","sourceRoot":"","sources":["../../../src/plugins/credits/credits-middleware.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,WAAW,CAAC;AAEnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,KAAK,YAAY,EAAqB,MAAM,oBAAoB,CAAC;AAQ1E,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IAC7B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAiFD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,wBAAwB,KAChC,eAwFF,CAAC"}

package/dist/plugins/credits/credits-middleware.js

@@ -0,0 +1,154 @@
+import { AIMessageChunk } from '@langchain/core/messages';
+import { createMiddleware } from 'langchain';
+import { mainAgentRequestContextSchema } from '../../graph/main-agent-types.js';
+import { TokenLimiterError } from './token-limiter.js';
+const NOOP_LOGGER = {
+    log: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+/**
+ * Extract `user.did` from the LangGraph runtime context without trusting
+ * its shape. The runtime channel is typed `unknown` in plain middlewares,
+ * so narrowing is the only honest way to read identity off it.
+ */
+function extractUserDid(context) {
+    if (!context || typeof context !== 'object' || !('user' in context)) {
+        return undefined;
+    }
+    const { user } = context;
+    if (!user || typeof user !== 'object' || !('did' in user)) {
+        return undefined;
+    }
+    const { did } = user;
+    return typeof did === 'string' && did.length > 0 ? did : undefined;
+}
+function extractUsageMetadata(message) {
+    if (!message ||
+        typeof message !== 'object' ||
+        !('usage_metadata' in message)) {
+        return undefined;
+    }
+    const meta = message.usage_metadata;
+    if (!meta || typeof meta !== 'object')
+        return undefined;
+    const m = meta;
+    if (typeof m.input_tokens === 'number' &&
+        typeof m.output_tokens === 'number' &&
+        typeof m.total_tokens === 'number') {
+        return {
+            input_tokens: m.input_tokens,
+            output_tokens: m.output_tokens,
+            total_tokens: m.total_tokens,
+        };
+    }
+    return undefined;
+}
+function extractResponseMeta(message) {
+    if (!message ||
+        typeof message !== 'object' ||
+        !('response_metadata' in message)) {
+        return {};
+    }
+    const meta = message.response_metadata;
+    if (!meta || typeof meta !== 'object')
+        return {};
+    const m = meta;
+    const result = {};
+    const usage = m.usage;
+    if (usage &&
+        typeof usage === 'object' &&
+        typeof usage.cost === 'number') {
+        result.providerCost = usage.cost;
+    }
+    if (typeof m.model === 'string') {
+        result.model = m.model;
+    }
+    return result;
+}
+/**
+ * Per-user credit-budget guard. Runs on every model call:
+ *
+ *   - `beforeModel` aborts the call with a polite message when the user
+ *     has no remaining balance.
+ *   - `afterModel` computes the credit cost of the completion (3-priority
+ *     fallback: provider USD cost → per-model pricing → flat rate) and
+ *     deducts it atomically via `TokenLimiter.limit`.
+ *
+ * Silently passes through when `limiter` is `null` — that's how the credits
+ * plugin signals "disabled or no Redis" without breaking the graph.
+ */
+export const createCreditsMiddleware = (options) => {
+    const logger = options.logger ?? NOOP_LOGGER;
+    const { limiter } = options;
+    return createMiddleware({
+        name: 'TokenLimiterMiddleware',
+        beforeModel: async (state, runtime) => {
+            if (!limiter) {
+                logger.debug?.('Credits middleware skipped (limiter unavailable — credits disabled or no Redis)');
+                return;
+            }
+            const userDid = extractUserDid(runtime.context);
+            if (!userDid) {
+                throw new Error('User DID is required for credit limiting');
+            }
+            const remaining = await limiter.getRemaining(userDid);
+            logger.debug?.(`Remaining credits: ${remaining} for user ${userDid}`);
+            if (remaining <= 0) {
+                return {
+                    messages: [
+                        ...state.messages,
+                        new AIMessageChunk({
+                            content: `Looks like you have run out of tokens. Please upgrade your plan or topup your balance. You have ${remaining} tokens remaining.`,
+                        }),
+                    ],
+                };
+            }
+        },
+        afterModel: async (state, runtime) => {
+            if (!limiter)
+                return;
+            try {
+                const userDid = extractUserDid(runtime.context);
+                if (!userDid) {
+                    throw new Error('User DID is required for credit limiting');
+                }
+                const lastMessage = state.messages.at(-1);
+                const usage = extractUsageMetadata(lastMessage);
+                if (!usage) {
+                    // No AI response with usage metadata to deduct against — happens
+                    // when `beforeModel` short-circuited the call, or when the graph
+                    // resumed on a non-AI message. Nothing to bill, skip silently.
+                    return;
+                }
+                const { providerCost, model } = extractResponseMeta(lastMessage);
+                const credits = limiter.creditsForUsage({
+                    providerCost,
+                    inputTokens: usage.input_tokens,
+                    outputTokens: usage.output_tokens,
+                    totalTokens: usage.total_tokens,
+                    model,
+                });
+                logger.log(`[Credits] input=${usage.input_tokens} output=${usage.output_tokens} total=${usage.total_tokens} | credits=${credits}`);
+                const result = await limiter.limit(userDid, credits);
+                logger.debug?.(`Credit limit result: ${JSON.stringify(result)}`);
+            }
+            catch (error) {
+                if (error instanceof TokenLimiterError) {
+                    logger.error(`Credit limit error: ${error.message}`);
+                    return {
+                        messages: [
+                            ...state.messages,
+                            new AIMessageChunk({
+                                content: `Looks like you have run out of tokens. Please upgrade your plan or topup your balance. You have ${error.currentBalance?.toFixed(2) ?? '0'} tokens remaining.`,
+                            }),
+                        ],
+                    };
+                }
+                logger.error(`Error in CreditsMiddleware: ${error instanceof Error ? error.message : String(error)}`);
+                throw error;
+            }
+        },
+        contextSchema: mainAgentRequestContextSchema,
+    });
+};

package/dist/plugins/credits/credits.plugin.d.ts

@@ -0,0 +1,55 @@
+import type { DynamicModule, Type } from '@nestjs/common';
+import type { Redis } from 'ioredis';
+import { z } from 'zod';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin.js';
+import type { AgentMiddleware, PluginContext, PluginManifest } from '../../plugin-api/types.js';
+import { type CreditsNetwork, type ModelPricingLookup } from './token-limiter.js';
+/** Constructor options for the credits plugin. */
+export interface CreditsPluginOptions {
+    /**
+     * The ioredis client used for credit balance + atomic limit. `null`
+     * disables the middleware (e.g. Redis not configured). Forks pass the
+     * same client they already use elsewhere in the app.
+     */
+    redis?: Redis | null;
+    /**
+     * Network tier — required when `redis` is set, so the claim-processing
+     * Nest module can construct its `TokenLimiter` at boot. Omitted in tests
+     * that don't exercise the cron path.
+     */
+    network?: CreditsNetwork;
+    /** Optional per-model pricing lookup; defaults to flat-rate fallback. */
+    modelPricingLookup?: ModelPricingLookup;
+}
+/**
+ * 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` (returned from
+ *     `getNestModules()` when Redis is configured).
+ *
+ * Silent (no agent-visible tools). Stays loaded by default and only opts
+ * out when `DISABLE_CREDITS=true`. When loaded, this plugin also activates
+ * the runtime's Tier-0 `SubscriptionMiddleware`, which gates the HTTP
+ * request before the graph even runs.
+ */
+export declare class CreditsPlugin extends OraclePlugin {
+    static readonly NAME = "credits";
+    readonly name = "credits";
+    readonly version = "1.0.0";
+    readonly manifest: PluginManifest;
+    readonly configSchema: z.ZodObject<{
+        SUBSCRIPTION_URL: z.ZodOptional<z.ZodURL>;
+        SUBSCRIPTION_ORACLE_MCP_URL: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>;
+    readonly autoDetectHint = "DISABLE_CREDITS!=true";
+    private readonly redis;
+    private readonly network?;
+    private readonly modelPricingLookup?;
+    constructor(options?: CreditsPluginOptions);
+    autoDetect(env: NodeJS.ProcessEnv): boolean;
+    getMiddlewares(ctx: PluginContext): AgentMiddleware[];
+    getNestModules(): Array<Type | DynamicModule>;
+}
+//# sourceMappingURL=credits.plugin.d.ts.map

package/dist/plugins/credits/credits.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credits.plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/credits/credits.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,cAAc,EACf,MAAM,2BAA2B,CAAC;AAKnC,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAE5B,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,yEAAyE;IACzE,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAcD;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,SAAQ,YAAY;IAC7C,MAAM,CAAC,QAAQ,CAAC,IAAI,aAAa;IAEjC,QAAQ,CAAC,IAAI,aAAsB;IAEnC,QAAQ,CAAC,OAAO,WAAW;IAE3B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAQ/B;IAEF,SAAkB,YAAY;;;sBAAuB;IAErD,SAAkB,cAAc,2BAA2B;IAE3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAiB;IAE1C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAqB;gBAE7C,OAAO,GAAE,oBAAyB;IAOrC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO;IAI3C,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,eAAe,EAAE;IAsBrD,cAAc,IAAI,KAAK,CAAC,IAAI,GAAG,aAAa,CAAC;CA2BvD"}