stellarium-ts 0.14.0 → 0.16.0

package/dist/client/operatorClient.d.ts

@@ -1,4 +1,5 @@
-export interface PaymentSubmission {
+export type PaymentSubmission = FixedPaymentSubmission | InferencePaymentSubmission;
+export interface FixedPaymentSubmission {
     voucher: {
         requestId: string;
         invocationId: string;
@@ -10,6 +11,27 @@ export interface PaymentSubmission {
         publicKey: string;
     };
 }
+/** The provider reports the call's usage; the operator charges it at the voucher's rates, up to `maxAmount`. */
+export interface InferencePaymentSubmission {
+    voucher: {
+        kind: 'inference';
+        requestId: string;
+        invocationId: string;
+        maxAmount: number;
+        inputCostMicroUsdcPerMillionTokens: number;
+        outputCostMicroUsdcPerMillionTokens: number;
+        maxTokens: number;
+        recipientAddress: string;
+        signature: string;
+        expiresAt: string;
+        invocationHash: string;
+        publicKey: string;
+    };
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
 export declare const SETTLE_PAYMENT_MAX_RETRIES = 5;
 export declare const SETTLE_PAYMENT_BASE_DELAY_MS = 1000;
 /** Per attempt. A timed-out attempt is retried like a network error. */

package/dist/client/operatorClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operatorClient.d.ts","sourceRoot":"","sources":["../../src/client/operatorClient.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAC9B,OAAO,EAAE;QACL,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,MAAM,CAAC;QACf,gBAAgB,EAAE,MAAM,CAAC;QACzB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;KACrB,CAAA;CACJ;AAED,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAC5C,eAAO,MAAM,4BAA4B,OAAO,CAAC;AACjD,wEAAwE;AACxE,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAmBhD,qBAAa,cAAc;IACX,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAhC,YAA6B,GAAG,EAAE,MAAM,GAAG,SAAS,EAAI;IAExD;;;OAGG;IACG,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+B7D;CACJ"}
+{"version":3,"file":"operatorClient.d.ts","sourceRoot":"","sources":["../../src/client/operatorClient.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,iBAAiB,GAAG,sBAAsB,GAAG,0BAA0B,CAAC;AAEpF,MAAM,WAAW,sBAAsB;IACnC,OAAO,EAAE;QACL,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,MAAM,CAAC;QACf,gBAAgB,EAAE,MAAM,CAAC;QACzB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;KACrB,CAAA;CACJ;AAED,gHAAgH;AAChH,MAAM,WAAW,0BAA0B;IACvC,OAAO,EAAE;QACL,IAAI,EAAE,WAAW,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;QAClB,kCAAkC,EAAE,MAAM,CAAC;QAC3C,mCAAmC,EAAE,MAAM,CAAC;QAC5C,SAAS,EAAE,MAAM,CAAC;QAClB,gBAAgB,EAAE,MAAM,CAAC;QACzB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;KACrB,CAAA;IACD,KAAK,EAAE;QACH,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;KACxB,CAAA;CACJ;AAED,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAC5C,eAAO,MAAM,4BAA4B,OAAO,CAAC;AACjD,wEAAwE;AACxE,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAmBhD,qBAAa,cAAc;IACX,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAhC,YAA6B,GAAG,EAAE,MAAM,GAAG,SAAS,EAAI;IAExD;;;OAGG;IACG,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+B7D;CACJ"}

package/dist/client/operatorClient.js

@@ -4,7 +4,7 @@ export const SETTLE_PAYMENT_BASE_DELAY_MS = 1000;
 export const SETTLE_PAYMENT_TIMEOUT_MS = 10_000;
 /**
  * Transient failures. Resending is safe even if an earlier attempt reached the operator: it stores a
- * unique receipt per (requestId, invocationId) before paying, so a repeat is rejected with 409.
+ * unique receipt per (requestId, invocationId), so a repeat is rejected with 409.
  * Rejections (400, 401, 404, 409, 422) are not retried because they won't change.
  */
 const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);

package/dist/db/db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/db/db.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,KAAK,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAE7C,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAU1D,wGAAwG;AACxG,wBAAsB,YAAY,CAAC,QAAQ,GAAE,MAA8B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAI9F;AAED,wBAAsB,YAAY,CAAC,EAAE,EAAE,QAAQ,iBA0I9C"}
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/db/db.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,KAAK,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAE7C,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAY1D,wGAAwG;AACxG,wBAAsB,YAAY,CAAC,QAAQ,GAAE,MAA8B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAI9F;AAED,wBAAsB,YAAY,CAAC,EAAE,EAAE,QAAQ,iBA8I9C"}

package/dist/db/db.js

@@ -6,8 +6,10 @@ export const DEFAULT_DATABASE_PATH = './requestscript.db';
  * Version 1 dropped `UNIQUE (base_url)` from `resource` and added uniqueness to the function tables.
  * Version 2 added `resource_function.restricted`.
  * Version 3 added `resource.website` and the `description` columns of the resource tables.
+ * Version 4 renamed `resource_function_payment_manifest.cost_lamports` to `cost_micro_usdc` (payments moved to USDC).
+ * Version 5 added `resource_function.kind` and per-token inference pricing, which made `cost_micro_usdc` nullable.
  */
-const SCHEMA_VERSION = 3;
+const SCHEMA_VERSION = 5;
 /** Opens (or creates) the node database and brings its schema up to date. Pass ':memory:' for tests. */
 export async function openDatabase(filename = DEFAULT_DATABASE_PATH) {
     const db = await open({ filename, driver: sqlite3.Database });
@@ -63,6 +65,7 @@ export async function createTables(db) {
             return_type TEXT NOT NULL,
             description TEXT,
             restricted INTEGER NOT NULL DEFAULT 0,
+            kind TEXT NOT NULL DEFAULT 'fixed',
             created_at TEXT NOT NULL,
             updated_at TEXT NOT NULL,
 
@@ -88,7 +91,10 @@ export async function createTables(db) {
         CREATE TABLE IF NOT EXISTS resource_function_payment_manifest (
             id INTEGER PRIMARY KEY AUTOINCREMENT,
             resource_function_id INTEGER NOT NULL,
-            cost_lamports INTEGER NOT NULL,
+            -- Null for inference functions, which are priced per million tokens instead.
+            cost_micro_usdc INTEGER,
+            input_cost_micro_usdc_per_million_tokens INTEGER,
+            output_cost_micro_usdc_per_million_tokens INTEGER,
             recipient_address TEXT NOT NULL,
             created_at TEXT NOT NULL,
             updated_at TEXT NOT NULL,

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export { StellariumNode, resolveConfig, type StellariumNodeOptions } from './server.js';
 export type { NodeConfig } from './service.js';
-export type { StellariumResource, StellariumResourceFunction, StellariumResourceFunctionParameter, StellariumResourceFunctionPaymentManifest } from './resource/repository.js';
-export { CombinationResourceInvoker, invocationHash, paymentVoucherPayload, type PaymentVoucher } from './resource/invoker.js';
+export type { StellariumFixedPaymentManifest, StellariumInferencePaymentManifest, StellariumResource, StellariumResourceFunction, StellariumResourceFunctionKind, StellariumResourceFunctionParameter, StellariumResourceFunctionPaymentManifest, } from './resource/repository.js';
+export { CombinationResourceInvoker, inferenceVoucherPayload, invocationHash, paymentVoucherPayload, type InferenceEstimate, type InferencePaymentVoucher, type PaymentVoucher, } from './resource/invoker.js';
+export { inferenceCharge, MAX_TOKENS_PARAMETER, type InferenceResult, type InferenceUsage } from './resource/inference.js';
+export type { InferencePaymentSubmission, PaymentSubmission } from './client/operatorClient.js';
 export { grantHash, grantPayload, grantRenewalPayload, grantRequestPayload, grantsHash, CLOCK_SKEW_TOLERANCE_MS, invocationAuthorizationPayload, MAX_AUTHORIZATION_LIFETIME_MS, MAX_GRANT_CHAIN_LENGTH, MAX_GRANT_LIFETIME_MS, type Capability, type Grant, type GrantRenewalRequest, type GrantRequest, type InvocationAuthorization, } from './grant/grant.js';
 export type { ApproveGrant, GrantApproval, GrantOptions } from './grant/service.js';
 export type { GrantKey } from './grant/repository.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACxF,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,mCAAmC,EAAE,yCAAyC,EAAE,MAAM,0BAA0B,CAAC;AAE/K,OAAO,EAAE,0BAA0B,EAAE,cAAc,EAAE,qBAAqB,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE/H,OAAO,EACH,SAAS,EACT,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,UAAU,EACV,uBAAuB,EACvB,8BAA8B,EAC9B,6BAA6B,EAC7B,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,uBAAuB,GAC/B,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACpF,YAAY,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACxF,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EACR,8BAA8B,EAC9B,kCAAkC,EAClC,kBAAkB,EAClB,0BAA0B,EAC1B,8BAA8B,EAC9B,mCAAmC,EACnC,yCAAyC,GAC5C,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACH,0BAA0B,EAC1B,uBAAuB,EACvB,cAAc,EACd,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC3H,YAAY,EAAE,0BAA0B,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEhG,OAAO,EACH,SAAS,EACT,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,UAAU,EACV,uBAAuB,EACvB,8BAA8B,EAC9B,6BAA6B,EAC7B,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,uBAAuB,GAC/B,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACpF,YAAY,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -1,5 +1,6 @@
 export { StellariumNode, resolveConfig } from './server.js';
 // The voucher wire format, so the operator and other settlers can test against the real signer.
-export { CombinationResourceInvoker, invocationHash, paymentVoucherPayload } from './resource/invoker.js';
+export { CombinationResourceInvoker, inferenceVoucherPayload, invocationHash, paymentVoucherPayload, } from './resource/invoker.js';
+export { inferenceCharge, MAX_TOKENS_PARAMETER } from './resource/inference.js';
 // Grant wire format, so other implementations can test against the real signer.
 export { grantHash, grantPayload, grantRenewalPayload, grantRequestPayload, grantsHash, CLOCK_SKEW_TOLERANCE_MS, invocationAuthorizationPayload, MAX_AUTHORIZATION_LIFETIME_MS, MAX_GRANT_CHAIN_LENGTH, MAX_GRANT_LIFETIME_MS, } from './grant/grant.js';

package/dist/resource/inference.d.ts

@@ -0,0 +1,38 @@
+import type { ResourceFunctionCallParameter } from "requestscript";
+import type { StellariumInferencePaymentManifest, StellariumResourceFunction, StellariumResourceFunctionPaymentManifest } from "./repository.js";
+/** The parameter every inference function takes: the most output tokens the caller allows. */
+export declare const MAX_TOKENS_PARAMETER = "maxTokens";
+/** Token counts an inference function reports for one call. */
+export interface InferenceUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+/** What an inference function's `exec` returns. Callers' scripts see only `value`. */
+export interface InferenceResult {
+    value: unknown;
+    usage: InferenceUsage;
+}
+/** The per-million-token rates a charge is computed from. */
+export interface InferenceRates {
+    inputCostMicroUsdcPerMillionTokens: number;
+    outputCostMicroUsdcPerMillionTokens: number;
+}
+export declare function isInferenceManifest(manifest: StellariumResourceFunctionPaymentManifest | undefined): manifest is StellariumInferencePaymentManifest;
+export declare function isInferenceFunction(fn: Pick<StellariumResourceFunction, 'kind'>): boolean;
+/**
+ * Micro-USDC owed for `inputTokens` and `outputTokens` at `rates`, rounded up.
+ * Computed exactly in BigInt. Throws if the charge isn't a safe integer.
+ * The operator keeps a copy (apps/operator/src/inference.ts) that must stay in sync.
+ */
+export declare function inferenceCharge(rates: InferenceRates, inputTokens: number, outputTokens: number): number;
+/** The call's `maxTokens` value, or undefined unless it is a positive int32. */
+export declare function parseMaxTokens(parameters: ResourceFunctionCallParameter[]): number | undefined;
+/** The usage an inference `exec` reported, or undefined if it isn't two nonnegative safe integers. */
+export declare function parseInferenceResult(result: unknown): InferenceResult | undefined;
+/**
+ * Throws unless an inference function declares an int32 `maxTokens` parameter and, when paid,
+ * an inference payment manifest with nonnegative integer rates and an `estimateInputTokens` function.
+ * A function that isn't an inference function may not carry an inference manifest.
+ */
+export declare function validateInferenceFunction(fn: StellariumResourceFunction): void;
+//# sourceMappingURL=inference.d.ts.map

package/dist/resource/inference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inference.d.ts","sourceRoot":"","sources":["../../src/resource/inference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,KAAK,EAAE,kCAAkC,EAAE,0BAA0B,EAAE,yCAAyC,EAAE,MAAM,iBAAiB,CAAC;AAEjJ,8FAA8F;AAC9F,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAIhD,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,cAAc,CAAC;CACzB;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC3B,kCAAkC,EAAE,MAAM,CAAC;IAC3C,mCAAmC,EAAE,MAAM,CAAC;CAC/C;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,yCAAyC,GAAG,SAAS,GAAG,QAAQ,IAAI,kCAAkC,CAEnJ;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,IAAI,CAAC,0BAA0B,EAAE,MAAM,CAAC,GAAG,OAAO,CAEzF;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAQxG;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,UAAU,EAAE,6BAA6B,EAAE,GAAG,MAAM,GAAG,SAAS,CAG9F;AAED,sGAAsG;AACtG,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAajF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,0BAA0B,GAAG,IAAI,CAsB9E"}

package/dist/resource/inference.js

@@ -0,0 +1,74 @@
+/** The parameter every inference function takes: the most output tokens the caller allows. */
+export const MAX_TOKENS_PARAMETER = 'maxTokens';
+const INT32_MAX = 2_147_483_647;
+export function isInferenceManifest(manifest) {
+    return typeof manifest === 'object' && manifest !== null && 'inputCostMicroUsdcPerMillionTokens' in manifest;
+}
+export function isInferenceFunction(fn) {
+    return fn.kind === 'inference';
+}
+function isNonnegativeSafeInteger(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+/**
+ * Micro-USDC owed for `inputTokens` and `outputTokens` at `rates`, rounded up.
+ * Computed exactly in BigInt. Throws if the charge isn't a safe integer.
+ * The operator keeps a copy (apps/operator/src/inference.ts) that must stay in sync.
+ */
+export function inferenceCharge(rates, inputTokens, outputTokens) {
+    const micros = BigInt(inputTokens) * BigInt(rates.inputCostMicroUsdcPerMillionTokens)
+        + BigInt(outputTokens) * BigInt(rates.outputCostMicroUsdcPerMillionTokens);
+    const charge = (micros + 999999n) / 1000000n;
+    if (charge > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new Error('Inference charge exceeds the largest safe integer');
+    }
+    return Number(charge);
+}
+/** The call's `maxTokens` value, or undefined unless it is a positive int32. */
+export function parseMaxTokens(parameters) {
+    const value = parameters.find(parameter => parameter.name === MAX_TOKENS_PARAMETER)?.value;
+    return Number.isInteger(value) && value > 0 && value <= INT32_MAX ? value : undefined;
+}
+/** The usage an inference `exec` reported, or undefined if it isn't two nonnegative safe integers. */
+export function parseInferenceResult(result) {
+    if (typeof result !== 'object' || result === null || !('usage' in result)) {
+        return undefined;
+    }
+    const { value, usage } = result;
+    if (typeof usage !== 'object' || usage === null) {
+        return undefined;
+    }
+    const { inputTokens, outputTokens } = usage;
+    if (!isNonnegativeSafeInteger(inputTokens) || !isNonnegativeSafeInteger(outputTokens)) {
+        return undefined;
+    }
+    return { value, usage: { inputTokens, outputTokens } };
+}
+/**
+ * Throws unless an inference function declares an int32 `maxTokens` parameter and, when paid,
+ * an inference payment manifest with nonnegative integer rates and an `estimateInputTokens` function.
+ * A function that isn't an inference function may not carry an inference manifest.
+ */
+export function validateInferenceFunction(fn) {
+    if (!isInferenceFunction(fn)) {
+        if (isInferenceManifest(fn.paymentManifest)) {
+            throw new Error(`Function ${fn.name} has per-token pricing but is not declared with kind 'inference'`);
+        }
+        return;
+    }
+    const maxTokens = fn.parameters.find(parameter => parameter.name === MAX_TOKENS_PARAMETER);
+    if (maxTokens?.type !== 'int32') {
+        throw new Error(`Inference function ${fn.name} must take a '${MAX_TOKENS_PARAMETER}: int32' parameter`);
+    }
+    if (!fn.paymentManifest) {
+        return;
+    }
+    if (!isInferenceManifest(fn.paymentManifest)
+        || !isNonnegativeSafeInteger(fn.paymentManifest.inputCostMicroUsdcPerMillionTokens)
+        || !isNonnegativeSafeInteger(fn.paymentManifest.outputCostMicroUsdcPerMillionTokens)) {
+        throw new Error(`Inference function ${fn.name} must price input and output tokens as nonnegative integer micro-USDC per million tokens`);
+    }
+    if (typeof fn.estimateInputTokens !== 'function') {
+        throw new Error(`Paid inference function ${fn.name} must declare estimateInputTokens`);
+    }
+}

package/dist/resource/invoker.d.ts

@@ -1,6 +1,7 @@
 import { Resource, ResourceFunctionCallParameter, ResourceInvoker } from "requestscript";
 import type { GrantService } from "../grant/service.js";
-import { ResourceRepository } from "./repository.js";
+import { type InferenceUsage } from "./inference.js";
+import { ResourceRepository, type StellariumInferencePaymentManifest } from "./repository.js";
 export interface PaymentVoucher {
     requestId: string;
     invocationId: string;
@@ -11,6 +12,30 @@ export interface PaymentVoucher {
     invocationHash: string;
     publicKey: string;
 }
+/**
+ * A voucher for an inference function. It signs the provider's per-million-token rates and the call's
+ * `maxTokens` instead of an amount: the operator charges the usage the provider reports at those rates,
+ * up to `maxAmount`.
+ */
+export interface InferencePaymentVoucher {
+    kind: 'inference';
+    requestId: string;
+    invocationId: string;
+    maxAmount: number;
+    inputCostMicroUsdcPerMillionTokens: number;
+    outputCostMicroUsdcPerMillionTokens: number;
+    maxTokens: number;
+    recipientAddress: string;
+    signature: string;
+    expiresAt: string;
+    invocationHash: string;
+    publicKey: string;
+}
+/** What a provider's `POST /v1/run/resource/estimate` answers. */
+export interface InferenceEstimate {
+    inputTokens: number;
+    maxAmount: number;
+}
 /**
  * Hash binding a voucher to one function call. Providers recompute it from the
  * request they receive and compare it to `voucher.invocationHash`.
@@ -30,24 +55,52 @@ export declare function paymentVoucherPayload(voucher: Omit<PaymentVoucher, "sig
     invocationHash: string;
     publicKey: string;
 };
+/**
+ * The object `createInferenceVoucher` signs: every inference voucher field except `signature`.
+ * Key order is part of the signed bytes.
+ */
+export declare function inferenceVoucherPayload(voucher: Omit<InferencePaymentVoucher, "signature">): {
+    kind: "inference";
+    requestId: string;
+    invocationId: string;
+    maxAmount: number;
+    inputCostMicroUsdcPerMillionTokens: number;
+    outputCostMicroUsdcPerMillionTokens: number;
+    maxTokens: number;
+    recipientAddress: string;
+    expiresAt: string;
+    invocationHash: string;
+    publicKey: string;
+};
+export declare function isInferenceVoucher(voucher: PaymentVoucher | InferencePaymentVoucher): voucher is InferencePaymentVoucher;
+export declare const PAYMENT_VOUCHER_LIFETIME_MS: number;
+/** Inference can run for minutes, and the operator refuses a voucher that expired before the provider settled it. */
+export declare const INFERENCE_VOUCHER_LIFETIME_MS: number;
 export declare const EXTERNAL_INVOKE_MAX_RETRIES = 3;
 export declare const EXTERNAL_INVOKE_BASE_DELAY_MS = 500;
 /** Per attempt. A timed-out attempt is retried like a network error. */
 export declare const EXTERNAL_INVOKE_TIMEOUT_MS = 30000;
+/** Per attempt, for calls to inference functions. Every attempt fits within `INFERENCE_VOUCHER_LIFETIME_MS`. */
+export declare const INFERENCE_INVOKE_TIMEOUT_MS = 120000;
 export declare class CombinationResourceInvoker implements ResourceInvoker {
     private readonly resourceRepository;
-    private readonly costLimitLamports;
+    private readonly costLimitMicroUsdc;
     private readonly publicKey;
     private readonly privateKey;
     private readonly grantService?;
-    /** Without a `grantService`, calls to restricted remote functions fail. */
-    constructor(resourceRepository: ResourceRepository, costLimitLamports: number, publicKey: string, privateKey: string, grantService?: GrantService | undefined);
+    private readonly inferenceCostLimitMicroUsdc;
+    /**
+     * Without a `grantService`, calls to restricted remote functions fail.
+     * `inferenceCostLimitMicroUsdc` caps an inference voucher's `maxAmount`, and defaults to `costLimitMicroUsdc`.
+     */
+    constructor(resourceRepository: ResourceRepository, costLimitMicroUsdc: number, publicKey: string, privateKey: string, grantService?: GrantService | undefined, inferenceCostLimitMicroUsdc?: number);
     /**
      * Invoke a function on a resource.
      * If the resource has a baseUrl, it will be invoked as a remote function.
      * If the function is restricted, it attaches an authorization from a held grant.
      * If the resource has a paymentManifest, it will create a payment voucher and pass it to the resource.
-     * Otherwise, it will be invoked as a local function.
+     * A paid inference function is first priced by the provider's estimate endpoint.
+     * Otherwise, it will be invoked as a local function. A local inference function's usage is returned beside its value.
      *
      * @param resource - The resource to invoke
      * @param functionName - The name of the function to invoke
@@ -59,7 +112,11 @@ export declare class CombinationResourceInvoker implements ResourceInvoker {
         error: {
             message: string;
         } | null;
+        usage?: InferenceUsage;
     }>;
+    /** Asks the provider what a call to a paid inference function will cost at most. */
+    private estimate;
     createPaymentVoucher(recipientAddress: string, amount: number, resourcePath: string, resourceName: string, functionName: string, parameters: ResourceFunctionCallParameter[]): PaymentVoucher;
+    createInferenceVoucher(manifest: StellariumInferencePaymentManifest, maxAmount: number, maxTokens: number, resourcePath: string, resourceName: string, functionName: string, parameters: ResourceFunctionCallParameter[]): InferencePaymentVoucher;
 }
 //# sourceMappingURL=invoker.d.ts.map

package/dist/resource/invoker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"invoker.d.ts","sourceRoot":"","sources":["../../src/resource/invoker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,6BAA6B,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEzF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,cAAc;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC1B,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,6BAA6B,EAAE,GAC5C,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC;;;;;;;;EAG/E;AAED,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAC7C,eAAO,MAAM,6BAA6B,MAAM,CAAC;AACjD,wEAAwE;AACxE,eAAO,MAAM,0BAA0B,QAAS,CAAC;AA2BjD,qBAAa,0BAA2B,YAAW,eAAe;IAGlD,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IAAsB,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAAU,OAAO,CAAC,QAAQ,CAAC,SAAS;IAAU,OAAO,CAAC,QAAQ,CAAC,UAAU;IAAU,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IADxN,2EAA2E;IAC3E,YAA6B,kBAAkB,EAAE,kBAAkB,EAAmB,iBAAiB,EAAE,MAAM,EAAmB,SAAS,EAAE,MAAM,EAAmB,UAAU,EAAE,MAAM,EAAmB,YAAY,CAAC,EAAE,YAAY,YAAA,EAAI;IAC1O;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,6BAA6B,EAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,GAAG,CAAC;QAAC,KAAK,EAAE;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAC,CAAC,CAgE7J;IAED,oBAAoB,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,6BAA6B,EAAE,GAAG,cAAc,CAQ5L;CACJ"}
+{"version":3,"file":"invoker.d.ts","sourceRoot":"","sources":["../../src/resource/invoker.ts"],"names":[],"mappings":"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"}

package/dist/resource/invoker.js

@@ -1,4 +1,5 @@
 import { hashData, signData } from "../crypto/utils.js";
+import { inferenceCharge, isInferenceFunction, isInferenceManifest, parseInferenceResult, parseMaxTokens } from "./inference.js";
 /**
  * Hash binding a voucher to one function call. Providers recompute it from the
  * request they receive and compare it to `voucher.invocationHash`.
@@ -15,20 +16,36 @@ export function paymentVoucherPayload(voucher) {
     const { requestId, invocationId, amount, recipientAddress, expiresAt, invocationHash, publicKey } = voucher;
     return { requestId, invocationId, amount, recipientAddress, expiresAt, invocationHash, publicKey };
 }
+/**
+ * The object `createInferenceVoucher` signs: every inference voucher field except `signature`.
+ * Key order is part of the signed bytes.
+ */
+export function inferenceVoucherPayload(voucher) {
+    const { kind, requestId, invocationId, maxAmount, inputCostMicroUsdcPerMillionTokens, outputCostMicroUsdcPerMillionTokens, maxTokens, recipientAddress, expiresAt, invocationHash, publicKey } = voucher;
+    return { kind, requestId, invocationId, maxAmount, inputCostMicroUsdcPerMillionTokens, outputCostMicroUsdcPerMillionTokens, maxTokens, recipientAddress, expiresAt, invocationHash, publicKey };
+}
+export function isInferenceVoucher(voucher) {
+    return voucher.kind === 'inference';
+}
+export const PAYMENT_VOUCHER_LIFETIME_MS = 1000 * 60 * 2;
+/** Inference can run for minutes, and the operator refuses a voucher that expired before the provider settled it. */
+export const INFERENCE_VOUCHER_LIFETIME_MS = 1000 * 60 * 10;
 export const EXTERNAL_INVOKE_MAX_RETRIES = 3;
 export const EXTERNAL_INVOKE_BASE_DELAY_MS = 500;
 /** Per attempt. A timed-out attempt is retried like a network error. */
 export const EXTERNAL_INVOKE_TIMEOUT_MS = 30_000;
+/** Per attempt, for calls to inference functions. Every attempt fits within `INFERENCE_VOUCHER_LIFETIME_MS`. */
+export const INFERENCE_INVOKE_TIMEOUT_MS = 120_000;
 /**
  * POST to a remote resource, retrying network errors, 429s, and 5xx responses up to
  * `EXTERNAL_INVOKE_MAX_RETRIES` times with exponential backoff (500ms, 1s, 2s).
  * Other 4xx responses are returned immediately since retrying won't change them.
  * Throws the last network error if every attempt fails to connect.
  */
-async function fetchWithRetry(url, init) {
+async function fetchWithRetry(url, init, timeoutMs = EXTERNAL_INVOKE_TIMEOUT_MS) {
     for (let attempt = 0;; attempt++) {
         try {
-            const response = await fetch(url, { ...init(), signal: AbortSignal.timeout(EXTERNAL_INVOKE_TIMEOUT_MS) });
+            const response = await fetch(url, { ...init(), signal: AbortSignal.timeout(timeoutMs) });
             if (response.status !== 429 && response.status < 500) {
                 return response;
             }
@@ -46,24 +63,30 @@ async function fetchWithRetry(url, init) {
 }
 export class CombinationResourceInvoker {
     resourceRepository;
-    costLimitLamports;
+    costLimitMicroUsdc;
     publicKey;
     privateKey;
     grantService;
-    /** Without a `grantService`, calls to restricted remote functions fail. */
-    constructor(resourceRepository, costLimitLamports, publicKey, privateKey, grantService) {
+    inferenceCostLimitMicroUsdc;
+    /**
+     * Without a `grantService`, calls to restricted remote functions fail.
+     * `inferenceCostLimitMicroUsdc` caps an inference voucher's `maxAmount`, and defaults to `costLimitMicroUsdc`.
+     */
+    constructor(resourceRepository, costLimitMicroUsdc, publicKey, privateKey, grantService, inferenceCostLimitMicroUsdc = costLimitMicroUsdc) {
         this.resourceRepository = resourceRepository;
-        this.costLimitLamports = costLimitLamports;
+        this.costLimitMicroUsdc = costLimitMicroUsdc;
         this.publicKey = publicKey;
         this.privateKey = privateKey;
         this.grantService = grantService;
+        this.inferenceCostLimitMicroUsdc = inferenceCostLimitMicroUsdc;
     }
     /**
      * Invoke a function on a resource.
      * If the resource has a baseUrl, it will be invoked as a remote function.
      * If the function is restricted, it attaches an authorization from a held grant.
      * If the resource has a paymentManifest, it will create a payment voucher and pass it to the resource.
-     * Otherwise, it will be invoked as a local function.
+     * A paid inference function is first priced by the provider's estimate endpoint.
+     * Otherwise, it will be invoked as a local function. A local inference function's usage is returned beside its value.
      *
      * @param resource - The resource to invoke
      * @param functionName - The name of the function to invoke
@@ -92,14 +115,41 @@ export class CombinationResourceInvoker {
             if (resourceFunction.restricted && !chain) {
                 return { value: null, error: { message: `Failed to invoke ${resource.name}.${functionName}: it requires a grant from ${url}, and this node holds none that covers the call` } };
             }
-            let paymentVoucher;
-            if (resourceFunction.paymentManifest) {
+            const manifest = resourceFunction.paymentManifest;
+            const inference = isInferenceFunction(resourceFunction);
+            if (manifest && inference) {
+                console.log(`Resource function ${resource.name}.${functionName} is a paid inference function, creating payment voucher...`);
+                // Peers' manifests aren't validated on receipt.
+                if (!isInferenceManifest(manifest) || !Number.isSafeInteger(manifest.inputCostMicroUsdcPerMillionTokens) || manifest.inputCostMicroUsdcPerMillionTokens < 0
+                    || !Number.isSafeInteger(manifest.outputCostMicroUsdcPerMillionTokens) || manifest.outputCostMicroUsdcPerMillionTokens < 0) {
+                    return { value: null, error: { message: `Failed to invoke ${resource.name}.${functionName}: its payment manifest has no valid per-token pricing` } };
+                }
+                const maxTokens = parseMaxTokens(parameters);
+                if (maxTokens === undefined) {
+                    return { value: null, error: { message: `Failed to invoke ${resource.name}.${functionName}: maxTokens must be a positive int32` } };
+                }
+                const estimate = await this.estimate(url, target, chain);
+                if ('error' in estimate) {
+                    return { value: null, error: { message: `Failed to invoke ${resource.name}.${functionName}: ${estimate.error}` } };
+                }
+                // The provider may pick the input estimate, but maxAmount must follow from it at the advertised rates.
+                if (inferenceCharge(manifest, estimate.inputTokens, maxTokens) !== estimate.maxAmount) {
+                    return { value: null, error: { message: `Failed to invoke ${resource.name}.${functionName}: the provider's estimate doesn't match its advertised rates` } };
+                }
+                if (estimate.maxAmount > this.inferenceCostLimitMicroUsdc) {
+                    throw new Error(`Function ${functionName} may cost up to ${estimate.maxAmount} micro-USDC, which exceeds the inference cost limit of ${this.inferenceCostLimitMicroUsdc} micro-USDC`);
+                }
+                requestBody.paymentVoucher = this.createInferenceVoucher(manifest, estimate.maxAmount, maxTokens, resource.path, resource.name, functionName, parameters);
+            }
+            else if (manifest) {
                 console.log(`Resource function ${resource.name}.${functionName} has a payment manifest, creating payment voucher...`);
-                if (resourceFunction.paymentManifest.costLamports > this.costLimitLamports) {
-                    throw new Error(`Function ${functionName} cost ${resourceFunction.paymentManifest.costLamports} lamports, which exceeds the cost limit of ${this.costLimitLamports} lamports`);
+                if (isInferenceManifest(manifest)) {
+                    return { value: null, error: { message: `Failed to invoke ${resource.name}.${functionName}: it has per-token pricing but isn't an inference function` } };
+                }
+                if (manifest.costMicroUsdc > this.costLimitMicroUsdc) {
+                    throw new Error(`Function ${functionName} cost ${manifest.costMicroUsdc} micro-USDC, which exceeds the cost limit of ${this.costLimitMicroUsdc} micro-USDC`);
                 }
-                paymentVoucher = this.createPaymentVoucher(resourceFunction.paymentManifest.recipientAddress, resourceFunction.paymentManifest.costLamports, resource.path, resource.name, functionName, parameters);
-                requestBody.paymentVoucher = paymentVoucher;
+                requestBody.paymentVoucher = this.createPaymentVoucher(manifest.recipientAddress, manifest.costMicroUsdc, resource.path, resource.name, functionName, parameters);
             }
             // The voucher is created once and reused on every attempt, so the operator's
             // requestId/invocationId check prevents a retried call from being settled twice.
@@ -110,7 +160,7 @@ export class CombinationResourceInvoker {
                 headers: {
                     'Content-Type': 'application/json',
                 },
-            }));
+            }), inference ? INFERENCE_INVOKE_TIMEOUT_MS : EXTERNAL_INVOKE_TIMEOUT_MS);
             if (!result.ok) {
                 // The provider's JSON error is more useful than the status text, which can be empty.
                 const detail = await result.json().then((body) => body?.error, () => undefined);
@@ -126,16 +176,62 @@ export class CombinationResourceInvoker {
                 return { value: null, error: { message: `Function ${functionName} not found in resource ${resource.name}` } };
             }
             const result = await fn.exec(parameters);
+            if (isInferenceFunction(fn)) {
+                const inferenceResult = parseInferenceResult(result);
+                if (!inferenceResult) {
+                    return { value: null, error: { message: `Inference function ${functionName} must return { value, usage: { inputTokens, outputTokens } }` } };
+                }
+                return { value: inferenceResult.value, error: null, usage: inferenceResult.usage };
+            }
             return { value: result, error: null };
         }
     }
+    /** Asks the provider what a call to a paid inference function will cost at most. */
+    async estimate(url, target, chain) {
+        let response;
+        try {
+            // The authorization is signed per attempt, since the provider refuses a reused nonce.
+            response = await fetchWithRetry(`${url}/v1/run/resource/estimate`, () => ({
+                method: 'POST',
+                body: JSON.stringify(chain && this.grantService ? { ...target, authorization: this.grantService.authorize(chain, target) } : target),
+                headers: { 'Content-Type': 'application/json' },
+            }));
+        }
+        catch (error) {
+            return { error: `estimate failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+        const body = await response.json().catch(() => undefined);
+        if (!response.ok) {
+            return { error: `estimate failed: ${typeof body?.error === 'string' ? body.error : `${response.status} ${response.statusText}`.trim()}` };
+        }
+        const { inputTokens, maxAmount } = body ?? {};
+        if (!Number.isSafeInteger(inputTokens) || inputTokens < 0 || !Number.isSafeInteger(maxAmount) || maxAmount < 0) {
+            return { error: 'the provider returned an invalid estimate' };
+        }
+        return { inputTokens: inputTokens, maxAmount: maxAmount };
+    }
     createPaymentVoucher(recipientAddress, amount, resourcePath, resourceName, functionName, parameters) {
         const requestId = crypto.randomUUID();
         const invocationId = crypto.randomUUID();
-        // Expire in 2 minutes
-        const expiresAt = new Date(Date.now() + 1000 * 60 * 2).toISOString();
+        const expiresAt = new Date(Date.now() + PAYMENT_VOUCHER_LIFETIME_MS).toISOString();
         const hash = invocationHash(resourcePath, resourceName, functionName, parameters);
         const signature = signData(paymentVoucherPayload({ requestId, invocationId, amount, recipientAddress, expiresAt, invocationHash: hash, publicKey: this.publicKey }), this.privateKey);
         return { requestId, invocationId, amount, recipientAddress, signature, expiresAt, invocationHash: hash, publicKey: this.publicKey };
     }
+    createInferenceVoucher(manifest, maxAmount, maxTokens, resourcePath, resourceName, functionName, parameters) {
+        const unsigned = {
+            kind: 'inference',
+            requestId: crypto.randomUUID(),
+            invocationId: crypto.randomUUID(),
+            maxAmount,
+            inputCostMicroUsdcPerMillionTokens: manifest.inputCostMicroUsdcPerMillionTokens,
+            outputCostMicroUsdcPerMillionTokens: manifest.outputCostMicroUsdcPerMillionTokens,
+            maxTokens,
+            recipientAddress: manifest.recipientAddress,
+            expiresAt: new Date(Date.now() + INFERENCE_VOUCHER_LIFETIME_MS).toISOString(),
+            invocationHash: invocationHash(resourcePath, resourceName, functionName, parameters),
+            publicKey: this.publicKey,
+        };
+        return { ...unsigned, signature: signData(inferenceVoucherPayload(unsigned), this.privateKey) };
+    }
 }

package/dist/resource/repository.d.ts

@@ -1,11 +1,22 @@
-import { Resource, ResourceFunction, ResourceFunctionParameter } from "requestscript";
+import { Resource, ResourceFunction, ResourceFunctionCallParameter, ResourceFunctionParameter } from "requestscript";
 import { Database } from "sqlite";
 import type { StoredPeer } from "../peer/repository.js";
-export interface StellariumResourceFunctionPaymentManifest {
+/** A flat price per call. */
+export interface StellariumFixedPaymentManifest {
     id?: number;
-    costLamports: number;
+    costMicroUsdc: number;
     recipientAddress: string;
 }
+/** Per-token pricing for an inference function. Either rate may be 0. */
+export interface StellariumInferencePaymentManifest {
+    id?: number;
+    inputCostMicroUsdcPerMillionTokens: number;
+    outputCostMicroUsdcPerMillionTokens: number;
+    recipientAddress: string;
+}
+export type StellariumResourceFunctionPaymentManifest = StellariumFixedPaymentManifest | StellariumInferencePaymentManifest;
+/** Fixed functions return one value. Inference functions run AI inference and are priced per token. */
+export type StellariumResourceFunctionKind = 'fixed' | 'inference';
 export interface StellariumResourceFunctionParameter extends ResourceFunctionParameter {
     description?: string;
 }
@@ -16,6 +27,13 @@ export interface StellariumResourceFunction extends ResourceFunction {
     paymentManifest?: StellariumResourceFunctionPaymentManifest;
     /** Callers need a grant from the hosting node. Announced to peers so callers can tell. */
     restricted?: boolean;
+    /** Absent means 'fixed'. An inference function takes a `maxTokens: int32` parameter and its `exec` returns `{ value, usage }`. */
+    kind?: StellariumResourceFunctionKind;
+    /**
+     * Input tokens a call will use, for pricing its voucher before inference runs. Required on paid inference
+     * functions. It runs only on the hosting node and, like `exec`, is never announced.
+     */
+    estimateInputTokens?: (args: ResourceFunctionCallParameter[]) => Promise<number>;
 }
 export interface StellariumResource extends Resource {
     id: number;

package/dist/resource/repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/resource/repository.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/resource/repository.ts"],"names":[],"mappings":"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"}