stellarium-ts 0.19.0 → 0.20.0

package/dist/resource/repository.js

@@ -1,5 +1,34 @@
 import { isFreshExpiry, safeVerifyData } from "../crypto/utils.js";
 import { isInferenceManifest } from "./inference.js";
+/** The one function a contract's resource has. It runs the contract's latest version. */
+export const CONTRACT_FUNCTION = 'run';
+export function isContractManifest(manifest) {
+    return typeof manifest === 'object' && manifest !== null && 'priceMicroUsdPerMillionTokens' in manifest;
+}
+export function isContractFunction(fn) {
+    return fn.kind === 'contract';
+}
+/** The resource a contract is served as. Its function always has a manifest, so every call needs a voucher. */
+export function contractResource(contract, baseUrl, priceMicroUsdPerMillionTokens, recipientOrganizationId) {
+    return {
+        id: 0,
+        baseUrl,
+        metadata: {},
+        path: contract.path,
+        name: contract.name,
+        description: contract.description ?? undefined,
+        functions: [{
+                name: CONTRACT_FUNCTION,
+                kind: 'contract',
+                parameters: contract.parameters,
+                returnType: contract.returnType,
+                exec: async () => {
+                    throw new Error('Contracts are run by the resource invoker');
+                },
+                paymentManifest: { priceMicroUsdPerMillionTokens, recipientOrganizationId },
+            }],
+    };
+}
 /**
  * The object a node signs to broadcast its resources. Key order is part of the signed bytes.
  * Functions' `exec` implementations are dropped by JSON serialization on both ends.
@@ -25,49 +54,53 @@ export class ResourceRepository {
     resources;
     baseUrl;
     organizationId;
-    // The connection is shared, so transactions are serialized to keep them from nesting.
-    writes = Promise.resolve();
-    /** `organizationId` is the operator organization this node is enrolled in, which is paid for its functions. */
-    constructor(db, resources = [], baseUrl = '', organizationId) {
+    contracts;
+    /**
+     * `organizationId` is the operator organization this node is enrolled in, which is paid for its functions.
+     * The contracts deployed to the node are its resources too, after the registered ones.
+     */
+    constructor(db, resources = [], baseUrl = '', organizationId, contracts) {
         this.db = db;
         this.resources = resources;
         this.baseUrl = baseUrl;
         this.organizationId = organizationId;
+        this.contracts = contracts;
     }
-    serialize(work) {
-        const run = this.writes.then(work, work);
-        this.writes = run.catch(() => undefined);
-        return run;
+    /** A resource registered on this node. */
+    isRegistered(resource) {
+        return this.resources.some(r => r.path === resource.path && r.name === resource.name);
     }
-    transaction(work) {
-        return this.serialize(async () => {
-            await this.db.exec('BEGIN IMMEDIATE');
-            try {
-                const result = await work();
-                await this.db.exec('COMMIT');
-                return result;
-            }
-            catch (error) {
-                await this.db.exec('ROLLBACK');
-                throw error;
-            }
-        });
+    /** A resource this node hosts: registered, or a contract deployed to it. */
+    async isInternal(resource) {
+        return this.isRegistered(resource) || await this.contracts?.repository.owner(resource.path, resource.name) !== undefined;
     }
-    isInternal(resource) {
-        return this.resources.some(r => r.path === resource.path && r.name === resource.name);
+    /** A resource learned from a peer. */
+    async isLearned(path, name) {
+        return await this.db.get('SELECT id FROM resource WHERE path = ? AND name = ?', [path, name]) !== undefined;
+    }
+    async contractResources() {
+        if (!this.contracts) {
+            return [];
+        }
+        const { repository, price, organizationId } = this.contracts;
+        return (await repository.allLatest()).map(contract => contractResource(contract, this.baseUrl, price(), organizationId()));
+    }
+    async contractResource(path, name) {
+        const contract = await this.contracts?.repository.latest(path, name);
+        return contract && contractResource(contract, this.baseUrl, this.contracts.price(), this.contracts.organizationId());
     }
     /**
      * Saves a resource learned from the starting peer, if it isn't known yet. Resources hosted
      * by this node and resources already known are left alone, so startup can run on every boot.
      */
     async learn(resource) {
-        if (this.isInternal(resource) || resource.baseUrl === this.baseUrl) {
+        if (await this.isInternal(resource) || resource.baseUrl === this.baseUrl) {
             return;
         }
-        await this.transaction(async () => {
-            const existing = await this.db.get('SELECT id FROM resource WHERE path = ? AND name = ?', [resource.path, resource.name]);
+        await this.db.transaction(async (tx) => {
+            const existing = await tx.get('SELECT id FROM resource WHERE path = ? AND name = ?', [resource.path, resource.name]);
             if (!existing) {
-                await this.insert(resource, null);
+                await this.insert(tx, resource, null);
             }
         });
     }
@@ -83,15 +116,17 @@ export class ResourceRepository {
             return { ok: false };
         }
         const rejected = [];
-        await this.transaction(async () => {
-            for (const resource of resources) {
-                if (resource.baseUrl !== peer.baseUrl || this.isInternal(resource)) {
+        // Checked before the transaction, whose work may use only its own connection.
+        const internal = await Promise.all(resources.map(resource => this.isInternal(resource)));
+        await this.db.transaction(async (tx) => {
+            for (const [index, resource] of resources.entries()) {
+                if (resource.baseUrl !== peer.baseUrl || internal[index]) {
                     rejected.push(resourceKey(resource));
                     continue;
                 }
-                const existing = await this.db.get('SELECT * FROM resource WHERE path = ? AND name = ?', [resource.path, resource.name]);
+                const existing = await tx.get('SELECT * FROM resource WHERE path = ? AND name = ?', [resource.path, resource.name]);
                 if (!existing) {
-                    await this.insert(resource, peer.id);
+                    await this.insert(tx, resource, peer.id);
                     continue;
                 }
                 // Unowned rows came from the starting peer; the peer they point at may claim them.
@@ -100,37 +135,39 @@ export class ResourceRepository {
                     rejected.push(resourceKey(resource));
                     continue;
                 }
-                await this.deleteFunctions(existing.id);
-                await this.db.run('UPDATE resource SET base_url = ?, website = ?, description = ?, peer_id = ?, updated_at = ? WHERE id = ?', [resource.baseUrl, optionalWebsite(resource.website), optionalText(resource.description), peer.id, new Date().toISOString(), existing.id]);
-                await this.insertFunctions(existing.id, resource.functions);
+                await this.deleteFunctions(tx, existing.id);
+                await tx.run('UPDATE resource SET base_url = ?, website = ?, description = ?, peer_id = ?, updated_at = ? WHERE id = ?', [resource.baseUrl, optionalWebsite(resource.website), optionalText(resource.description), peer.id, new Date().toISOString(), existing.id]);
+                await this.insertFunctions(tx, existing.id, resource.functions);
             }
         });
         return { ok: true, rejected };
     }
-    async insert(resource, peerId) {
+    async insert(tx, resource, peerId) {
         const createdAt = new Date().toISOString();
-        const result = await this.db.run('INSERT INTO resource (path, name, base_url, website, description, peer_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)', [resource.path, resource.name, resource.baseUrl, optionalWebsite(resource.website), optionalText(resource.description), peerId, createdAt, createdAt]);
-        if (!result.changes || result.lastID === undefined) {
+        const row = await tx.get('INSERT INTO resource (path, name, base_url, website, description, peer_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?) RETURNING id', [resource.path, resource.name, resource.baseUrl, optionalWebsite(resource.website), optionalText(resource.description), peerId, createdAt, createdAt]);
+        if (!row) {
             throw new Error('Failed to create resource');
         }
-        await this.insertFunctions(result.lastID, resource.functions);
+        await this.insertFunctions(tx, row.id, resource.functions);
     }
-    async insertFunctions(resourceId, functions) {
+    async insertFunctions(tx, resourceId, functions) {
         const createdAt = new Date().toISOString();
         for (const fn of functions) {
-            const functionResult = await this.db.run('INSERT INTO resource_function (resource_id, name, return_type, description, restricted, kind, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)', [resourceId, fn.name, fn.returnType, optionalText(fn.description), fn.restricted === true ? 1 : 0, fn.kind === 'inference' ? 'inference' : 'fixed', createdAt, createdAt]);
-            const functionId = functionResult.lastID;
+            const functionRow = await tx.get('INSERT INTO resource_function (resource_id, name, return_type, description, restricted, kind, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?) RETURNING id', [resourceId, fn.name, fn.returnType, optionalText(fn.description), fn.restricted === true ? 1 : 0, fn.kind === 'inference' || fn.kind === 'contract' ? fn.kind : 'fixed', createdAt, createdAt]);
+            const functionId = functionRow.id;
             for (const parameter of fn.parameters) {
-                await this.db.run('INSERT INTO resource_function_parameter (resource_function_id, name, parameter_type, description, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)', [functionId, parameter.name, parameter.type, optionalText(parameter.description), createdAt, createdAt]);
+                await tx.run('INSERT INTO resource_function_parameter (resource_function_id, name, parameter_type, description, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)', [functionId, parameter.name, parameter.type, optionalText(parameter.description), createdAt, createdAt]);
             }
             const manifest = fn.paymentManifest;
             if (manifest) {
-                const inference = isInferenceManifest(manifest);
-                await this.db.run('INSERT INTO resource_function_payment_manifest (resource_function_id, cost_micro_usd, input_cost_micro_usd_per_million_tokens, output_cost_micro_usd_per_million_tokens, recipient_organization_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)', [
+                const inference = isInferenceManifest(manifest) ? manifest : undefined;
+                const contract = isContractManifest(manifest) ? manifest : undefined;
+                await tx.run('INSERT INTO resource_function_payment_manifest (resource_function_id, cost_micro_usd, input_cost_micro_usd_per_million_tokens, output_cost_micro_usd_per_million_tokens, price_micro_usd_per_million_tokens, recipient_organization_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)', [
                     functionId,
-                    inference ? null : manifest.costMicroUsd,
-                    inference ? manifest.inputCostMicroUsdPerMillionTokens : null,
-                    inference ? manifest.outputCostMicroUsdPerMillionTokens : null,
+                    inference || contract ? null : manifest.costMicroUsd,
+                    inference ? inference.inputCostMicroUsdPerMillionTokens : null,
+                    inference ? inference.outputCostMicroUsdPerMillionTokens : null,
+                    contract ? contract.priceMicroUsdPerMillionTokens : null,
                     manifest.recipientOrganizationId ?? null,
                     createdAt,
                     createdAt,
@@ -138,14 +175,14 @@ export class ResourceRepository {
             }
         }
     }
-    async deleteFunctions(resourceId) {
+    async deleteFunctions(tx, resourceId) {
         const functionIds = 'SELECT id FROM resource_function WHERE resource_id = ?';
-        await this.db.run(`DELETE FROM resource_function_payment_manifest WHERE resource_function_id IN (${functionIds})`, [resourceId]);
-        await this.db.run(`DELETE FROM resource_function_parameter WHERE resource_function_id IN (${functionIds})`, [resourceId]);
-        await this.db.run('DELETE FROM resource_function WHERE resource_id = ?', [resourceId]);
+        await tx.run(`DELETE FROM resource_function_payment_manifest WHERE resource_function_id IN (${functionIds})`, [resourceId]);
+        await tx.run(`DELETE FROM resource_function_parameter WHERE resource_function_id IN (${functionIds})`, [resourceId]);
+        await tx.run('DELETE FROM resource_function WHERE resource_id = ?', [resourceId]);
     }
     async getInternalResource(path, name) {
-        return this.resources.find(r => r.path === path && r.name === name);
+        return this.resources.find(r => r.path === path && r.name === name) ?? await this.contractResource(path, name);
     }
     async getResource(key) {
         const resource = this.resources.find(r => resourceKey(r) === key);
@@ -156,6 +193,10 @@ export class ResourceRepository {
         const pathName = key.split('.');
         const name = pathName.pop();
         const path = pathName.join('.');
+        const contract = await this.contractResource(path, name);
+        if (contract) {
+            return contract;
+        }
         const result = await this.db.get('SELECT * FROM resource WHERE path = ? AND name = ?', [path, name]);
         if (!result) {
             return undefined;
@@ -170,19 +211,25 @@ export class ResourceRepository {
             }
         };
     }
-    /** This node's resources, with its base URL and its organization as the recipient of every paid function. */
+    /**
+     * This node's resources, with its base URL and its organization as the recipient of every paid function:
+     * the registered ones, then its contracts by path and name.
+     */
     async getInternalResources() {
-        return this.resources.map(r => ({
+        const registered = this.resources.map(r => ({
             ...r,
             baseUrl: this.baseUrl,
             functions: r.functions.map((fn) => fn.paymentManifest
                 ? { ...fn, paymentManifest: { ...fn.paymentManifest, recipientOrganizationId: this.organizationId } }
                 : fn),
         }));
+        return [...registered, ...await this.contractResources()];
     }
     /** Learned resources in insertion order. A negative `limit` means no limit. */
     async getExternalResources(offset = 0, limit = -1) {
-        const results = await this.db.all('SELECT * FROM resource ORDER BY id LIMIT ? OFFSET ?', [limit, offset]);
+        const results = await this.db.all('SELECT * FROM resource ORDER BY id LIMIT ? OFFSET ?', 
+        // Postgres refuses a negative limit, and SQLite needs one before an offset.
+        [limit < 0 ? Number.MAX_SAFE_INTEGER : limit, offset]);
         return Promise.all(results.map(async (r) => ({
             id: r.id,
             path: r.path,
@@ -212,11 +259,11 @@ export class ResourceRepository {
             exec: async () => undefined,
             paymentManifest: await this.getResourceFunctionPaymentManifest(fn.id),
             restricted: fn.restricted === 1 || undefined,
-            kind: fn.kind === 'inference' ? 'inference' : undefined,
+            kind: fn.kind === 'inference' || fn.kind === 'contract' ? fn.kind : undefined,
         };
     }
     async getResourceFunctions(resourceId) {
-        const rows = await this.db.all('SELECT * FROM resource_function WHERE resource_id = ?', [resourceId]);
+        const rows = await this.db.all('SELECT * FROM resource_function WHERE resource_id = ? ORDER BY name', [resourceId]);
         return Promise.all(rows.map(async (f) => ({
             id: f.id,
             name: f.name,
@@ -226,7 +273,7 @@ export class ResourceRepository {
             exec: async () => undefined,
             paymentManifest: await this.getResourceFunctionPaymentManifest(f.id),
             restricted: f.restricted === 1 || undefined,
-            kind: f.kind === 'inference' ? 'inference' : undefined,
+            kind: f.kind === 'inference' || f.kind === 'contract' ? f.kind : undefined,
         })));
     }
     async getResourceParameters(resourceFunctionId) {
@@ -241,6 +288,13 @@ export class ResourceRepository {
         if (!result) {
             return undefined;
         }
+        if (result.price_micro_usd_per_million_tokens !== null) {
+            return {
+                id: result.id,
+                priceMicroUsdPerMillionTokens: result.price_micro_usd_per_million_tokens,
+                recipientOrganizationId: result.recipient_organization_id ?? undefined,
+            };
+        }
         if (result.cost_micro_usd === null) {
             return {
                 id: result.id,
@@ -260,12 +314,13 @@ export class ResourceRepository {
      * Both are in a fixed order, so offsets stay stable as resources are learned.
      */
     async getResources(offset, limit) {
-        const internal = (await this.getInternalResources()).slice(offset, offset + limit);
+        const all = await this.getInternalResources();
+        const internal = all.slice(offset, offset + limit);
         const remaining = limit - internal.length;
         if (remaining <= 0) {
             return internal;
         }
-        const externalOffset = Math.max(0, offset - this.resources.length);
+        const externalOffset = Math.max(0, offset - all.length);
         return [...internal, ...await this.getExternalResources(externalOffset, remaining)];
     }
 }

package/dist/resource/settlement.d.ts

@@ -22,4 +22,9 @@ export interface PaymentRefusal {
  * scheduled after returning, so it doesn't delay the caller, and failures go to `onSettleError`.
  */
 export declare function settlePaidCall(operatorClient: OperatorClient, voucher: PaymentVoucher | InferencePaymentVoucher, call: () => Promise<InvokeResult>, onSettleError: (error: unknown, message: string) => void): Promise<InvokeResult | PaymentRefusal>;
+/**
+ * Captures a billed run with the tokens it executed, or releases it, after the response: nothing waits on
+ * settlement.
+ */
+export declare function settleRunLater(operatorClient: OperatorClient, runId: string, outcome: 'capture' | 'release', tokens: number, onSettleError: (error: unknown, message: string) => void): void;
 //# sourceMappingURL=settlement.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"settlement.d.ts","sourceRoot":"","sources":["../../src/resource/settlement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,6BAA6B,CAAC;AACrF,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,KAAK,uBAAuB,EAAsB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAErG,sFAAsF;AACtF,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClC,KAAK,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAYD;;;;GAIG;AACH,wBAAsB,cAAc,CAChC,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,cAAc,GAAG,uBAAuB,EACjD,IAAI,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,EACjC,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GACzD,OAAO,CAAC,YAAY,GAAG,cAAc,CAAC,CAuCxC"}
+{"version":3,"file":"settlement.d.ts","sourceRoot":"","sources":["../../src/resource/settlement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,6BAA6B,CAAC;AACrF,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,KAAK,uBAAuB,EAAsB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAErG,sFAAsF;AACtF,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClC,KAAK,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAYD;;;;GAIG;AACH,wBAAsB,cAAc,CAChC,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,cAAc,GAAG,uBAAuB,EACjD,IAAI,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,EACjC,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GACzD,OAAO,CAAC,YAAY,GAAG,cAAc,CAAC,CAuCxC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC1B,cAAc,EAAE,cAAc,EAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GACzD,IAAI,CAYN"}

package/dist/resource/settlement.js

@@ -57,3 +57,22 @@ export async function settlePaidCall(operatorClient, voucher, call, onSettleErro
     settle();
     return result;
 }
+/**
+ * Captures a billed run with the tokens it executed, or releases it, after the response: nothing waits on
+ * settlement.
+ */
+export function settleRunLater(operatorClient, runId, outcome, tokens, onSettleError) {
+    setTimeout(async () => {
+        try {
+            if (outcome === 'capture') {
+                await operatorClient.captureRun({ runId, tokens });
+            }
+            else {
+                await operatorClient.releaseRun({ runId });
+            }
+        }
+        catch (error) {
+            onSettleError(error, `Failed to ${outcome} run ${runId}`);
+        }
+    }, 0);
+}

package/dist/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAgC,MAAM,SAAS,CAAC;AAEhF,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAM1E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAK5C,MAAM,WAAW,eAAe;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B;AAED,UAAU,YAAY;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,eAAe,CAAC;CAC/B;AAoCD;;;GAGG;AACH,KAAK,SAAS,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAAC,CAAC;AAE3F,OAAO,QAAQ,SAAS,CAAC;IACrB,UAAU,cAAc;QACpB,SAAS,CAAC,EAAE,SAAS,CAAC;KACzB;CACJ;AAkBD,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,eAAO,MAAM,aAAa,MAAM,CAAC;AAwKjC;;;;GAIG;AACH,QAAA,MAAM,MAAM,EAAE,kBAAkB,CAAC,YAAY,CAqa5C,CAAC;eAGa,MAAM"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAgC,MAAM,SAAS,CAAC;AAEhF,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAQ1E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAK5C,MAAM,WAAW,eAAe;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B;AAED,UAAU,YAAY;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,eAAe,CAAC;CAC/B;AAsCD;;;GAGG;AACH,KAAK,SAAS,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAAC,CAAC;AAE3F,OAAO,QAAQ,SAAS,CAAC;IACrB,UAAU,cAAc;QACpB,SAAS,CAAC,EAAE,SAAS,CAAC;KACzB;CACJ;AAkBD,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,eAAO,MAAM,aAAa,MAAM,CAAC;AAkOjC;;;;GAIG;AACH,QAAA,MAAM,MAAM,EAAE,kBAAkB,CAAC,YAAY,CAigB5C,CAAC;eAGa,MAAM"}

package/dist/routes.js

@@ -1,10 +1,11 @@
 import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 import rateLimit from '@fastify/rate-limit';
-import { interpretParsed, parseScript, RequestScriptError, TokenMeter } from 'requestscript';
+import { decodeValue, interpretParsed, parseScript, RequestScriptError, TokenMeter, valueToJson } from 'requestscript';
 import { looksLikeJwt } from './client/runTokens.js';
-import { inferenceVoucherPayload, invocationHash, isInferenceVoucher, paymentVoucherPayload } from './resource/invoker.js';
+import { contractVoucherPayload, inferenceVoucherPayload, invocationHash, isContractVoucher, isInferenceVoucher, MAX_CONTRACT_DEPTH, paymentVoucherPayload } from './resource/invoker.js';
 import { estimateInputTokens, inferenceCharge, isInferenceFunction, isInferenceManifest, parseMaxTokens } from './resource/inference.js';
-import { settlePaidCall } from './resource/settlement.js';
+import { settlePaidCall, settleRunLater } from './resource/settlement.js';
+import { isContractFunction, isContractManifest } from './resource/repository.js';
 import { safeVerifyData } from './crypto/utils.js';
 import { InvalidPublicKeyError } from './grant/service.js';
 // Body schemas check only the shape the handlers rely on. Signed payloads (resources) are
@@ -94,15 +95,37 @@ const inferenceVoucherSchema = {
         publicKey: { type: 'string' },
     },
 };
+const contractVoucherSchema = {
+    type: 'object',
+    required: ['kind', 'requestId', 'invocationId', 'maxAmount', 'priceMicroUsdPerMillionTokens', 'recipientOrganizationId', 'signature', 'expiresAt', 'invocationHash', 'publicKey'],
+    properties: {
+        kind: { const: 'contract' },
+        requestId: { type: 'string' },
+        invocationId: { type: 'string' },
+        maxAmount: { type: 'integer', minimum: 0 },
+        priceMicroUsdPerMillionTokens: { type: 'integer', minimum: 0 },
+        recipientOrganizationId: { type: 'string' },
+        signature: { type: 'string' },
+        expiresAt: { type: 'string' },
+        invocationHash: { type: 'string' },
+        publicKey: { type: 'string' },
+    },
+};
 const resourceRunRequestSchema = {
     type: 'object',
     required: ['resourcePath', 'resourceName', 'functionName', 'parameters'],
     properties: {
         ...resourceCallProperties,
-        // An inference voucher has `kind` and no `amount`, so at most one shape matches.
-        paymentVoucher: { oneOf: [fixedVoucherSchema, inferenceVoucherSchema] },
+        // Inference and contract vouchers have their own `kind`, and no `amount`, so at most one shape matches.
+        paymentVoucher: { oneOf: [fixedVoucherSchema, inferenceVoucherSchema, contractVoucherSchema] },
+        contractDepth: { type: 'integer', minimum: 1 },
     },
 };
+const contractRequestSchema = {
+    type: 'object',
+    required: ['source'],
+    properties: { source: { type: 'string' }, description: { type: 'string', maxLength: 2048 } },
+};
 const resourceEstimateRequestSchema = {
     type: 'object',
     required: ['resourcePath', 'resourceName', 'functionName', 'parameters'],
@@ -162,7 +185,7 @@ function isValidPaymentVoucher(voucher, resourceFunction, manifest, request, org
         }
         return safeVerifyData(inferenceVoucherPayload(voucher), voucher.publicKey, voucher.signature);
     }
-    if (isInferenceFunction(resourceFunction) || isInferenceManifest(manifest)) {
+    if (isInferenceFunction(resourceFunction) || isInferenceManifest(manifest) || isContractFunction(resourceFunction) || isContractManifest(manifest)) {
         return false;
     }
     if (voucher.amount < manifest.costMicroUsd) {
@@ -170,6 +193,37 @@ function isValidPaymentVoucher(voucher, resourceFunction, manifest, request, org
     }
     return safeVerifyData(paymentVoucherPayload(voucher), voucher.publicKey, voucher.signature);
 }
+/**
+ * A contract voucher is valid when it is bound to this exact call, signed by its public key, unexpired, pays
+ * this node's organization, and agrees to at least this node's current price.
+ */
+function isValidContractVoucher(voucher, request, organizationId, price) {
+    const expectedHash = invocationHash(request.resourcePath, request.resourceName, request.functionName, request.parameters);
+    if (voucher.invocationHash !== expectedHash || !organizationId || voucher.recipientOrganizationId !== organizationId) {
+        return false;
+    }
+    const expiresAt = Date.parse(voucher.expiresAt);
+    if (!Number.isFinite(expiresAt) || expiresAt <= Date.now() || voucher.priceMicroUsdPerMillionTokens < price) {
+        return false;
+    }
+    return safeVerifyData(contractVoucherPayload(voucher), voucher.publicKey, voucher.signature);
+}
+/** Splits `path.Name` or `path.Name@version`. */
+function contractRef(ref) {
+    const at = ref.indexOf('@');
+    const qualified = at === -1 ? ref : ref.slice(0, at);
+    const version = at === -1 ? undefined : ref.slice(at + 1);
+    const dot = qualified.lastIndexOf('.');
+    if (dot <= 0 || dot === qualified.length - 1 || version === '') {
+        return undefined;
+    }
+    return { path: qualified.slice(0, dot), name: qualified.slice(dot + 1), version };
+}
+/** A contract as `GET /v1/contracts` lists it. Its source is public, so callers can read what a call does. */
+function contractView(contract) {
+    const { path, name, version, parameters, returnType, ownerOrganizationId, description, source, createdAt } = contract;
+    return { path, name, version, parameters, returnType, ownerOrganizationId, description, source, createdAt };
+}
 /**
  * Encapsulates the routes
  * @param fastify Encapsulated Fastify Instance
@@ -262,7 +316,10 @@ const routes = async (fastify, options) => {
                         type: parameter.type,
                         description: parameter.description,
                     })),
-                    paymentManifest: !fn.paymentManifest ? undefined : isInferenceManifest(fn.paymentManifest) ? {
+                    paymentManifest: !fn.paymentManifest ? undefined : isContractManifest(fn.paymentManifest) ? {
+                        priceMicroUsdPerMillionTokens: fn.paymentManifest.priceMicroUsdPerMillionTokens,
+                        recipientOrganizationId: fn.paymentManifest.recipientOrganizationId,
+                    } : isInferenceManifest(fn.paymentManifest) ? {
                         inputCostMicroUsdPerMillionTokens: fn.paymentManifest.inputCostMicroUsdPerMillionTokens,
                         outputCostMicroUsdPerMillionTokens: fn.paymentManifest.outputCostMicroUsdPerMillionTokens,
                         recipientOrganizationId: fn.paymentManifest.recipientOrganizationId,
@@ -271,7 +328,7 @@ const routes = async (fastify, options) => {
                         recipientOrganizationId: fn.paymentManifest.recipientOrganizationId,
                     },
                     restricted: fn.restricted || undefined,
-                    kind: isInferenceFunction(fn) ? 'inference' : undefined,
+                    kind: isInferenceFunction(fn) || isContractFunction(fn) ? fn.kind : undefined,
                 })),
                 baseUrl: resource.baseUrl,
             })),
@@ -317,36 +374,28 @@ const routes = async (fastify, options) => {
         const caller = request.runCaller;
         const billed = caller.kind === 'client' && caller.organizationId !== options.service.config.organizationId;
         const runId = billed ? randomUUID() : undefined;
-        let resourceInvoker = options.service.resourceInvoker;
         if (billed) {
             const authorization = await options.service.operatorClient.authorizeRun({ token: caller.token, runId: runId, source: runRequest.source });
             if (!authorization.ok) {
                 return reply.status(authorization.status).send({ error: authorization.error });
             }
-            resourceInvoker = options.service.resourceInvoker.forRun({ runId: runId });
         }
+        // The run token's claims, or null for an API-key run, so the name is always reserved.
+        const jwt = caller.kind === 'client' ? caller.payload : null;
+        // Contracts the script calls on this node see who pays for the run: the client's organization, or this node's own.
+        const { organizationId, publicKey } = options.service.config;
+        const runFor = { org: caller.kind === 'client' ? caller.organizationId : organizationId ?? null, node: publicKey };
+        const resourceInvoker = options.service.resourceInvoker.forScript({ runId, jwt, depth: 0, caller: runFor });
         // Nothing waits on settlement, so it doesn't delay the response.
-        const settle = (outcome, tokens) => runId && setTimeout(async () => {
-            try {
-                if (outcome === 'capture') {
-                    await options.service.operatorClient.captureRun({ runId, tokens });
-                }
-                else {
-                    await options.service.operatorClient.releaseRun({ runId });
-                }
-            }
-            catch (error) {
-                fastify.log.error(error, `Failed to ${outcome} run ${runId}`);
-            }
-        }, 0);
+        const settle = (outcome, tokens) => runId
+            && settleRunLater(options.service.operatorClient, runId, outcome, tokens, (error, message) => fastify.log.error(error, message));
         const meter = new TokenMeter();
         try {
             const result = await interpretParsed(script, {
                 resourceResolver: options.service.resourceResolver,
                 resourceInvoker,
                 meter,
-                // The run token's claims, or null for an API-key run, so the name is always reserved.
-                builtins: { jwt: caller.kind === 'client' ? caller.payload : null },
+                builtins: { jwt },
             });
             settle('capture', meter.tokens);
             return reply.status(200).send({ returnValue: result.returnValue ?? null, usage: { tokens: meter.tokens } });
@@ -442,6 +491,35 @@ const routes = async (fastify, options) => {
             return reply;
         }
         const { resource, resourceFunction } = call;
+        // A contract is always paid for with a contract voucher, since its paid calls are paid by its caller.
+        if (isContractFunction(resourceFunction)) {
+            const contract = await options.service.contractRepository.latest(resource.path, resource.name);
+            if (!contract) {
+                return reply.status(400).send({ error: 'Resource not found' });
+            }
+            if (!isContractVoucher(paymentVoucher)) {
+                return reply.status(402).send({ error: 'A contract voucher is required' });
+            }
+            const { organizationId, priceMicroUsdPerMillionTokens } = options.service.config;
+            if (!isValidContractVoucher(paymentVoucher, resourceRequest, organizationId, priceMicroUsdPerMillionTokens ?? 0)) {
+                return reply.status(400).send({ error: 'Invalid payment voucher' });
+            }
+            if (await options.service.grantService.isBlocked(paymentVoucher.publicKey)) {
+                return reply.status(403).send({ error: 'Caller is blocked' });
+            }
+            const depth = resourceRequest.contractDepth ?? 1;
+            if (depth > MAX_CONTRACT_DEPTH) {
+                return reply.status(400).send({ error: `Contracts may call each other at most ${MAX_CONTRACT_DEPTH} deep` });
+            }
+            const result = await options.service.contractService.serve(paymentVoucher, contract, resourceRequest.parameters, depth);
+            if ('refused' in result) {
+                return reply.status(result.refused.status).send({ error: result.refused.error });
+            }
+            return result;
+        }
+        if (isContractVoucher(paymentVoucher)) {
+            return reply.status(400).send({ error: 'Invalid payment voucher' });
+        }
         // Payment manifests are per function. A paid function is never run without a valid voucher.
         const paymentManifest = resourceFunction.paymentManifest;
         if (paymentManifest) {
@@ -478,6 +556,64 @@ const routes = async (fastify, options) => {
         return result;
     });
     // End Run Routes
+    // Start Contract Routes
+    /** The node's admin, or an organization's API client, from `requireRunAuthorization`. */
+    const contractCaller = (request) => {
+        const caller = request.runCaller;
+        return caller.kind === 'apiKey' ? caller : { kind: 'client', token: caller.token, organizationId: caller.organizationId };
+    };
+    /**
+     * Deploys a version of a contract, which becomes one of this node's resources. Another organization's
+     * API client pays the node's deploy fee from its run hold.
+     */
+    fastify.post('/contracts', { schema: { body: contractRequestSchema }, preValidation: requireRunAuthorization }, async (request, reply) => {
+        const { source, description } = request.body;
+        const result = await options.service.contractService.deploy(source, description, contractCaller(request));
+        if (!result.ok) {
+            return reply.status(result.status).send({ error: result.error });
+        }
+        return reply.status(201).send(result.contract);
+    });
+    /** Every version of every contract on this node, with its source. */
+    fastify.get('/contracts', { schema: { querystring: pageQuerySchema } }, async (request) => {
+        const { items, nextOffset } = await getPage(request.query, (offset, limit) => options.service.contractRepository.list(offset, limit));
+        return { contracts: items.map(contractView), nextOffset };
+    });
+    /**
+     * A contract's state variables, every scope, with values as JSON. Only its owner and this node's admin may
+     * read them: a contract shares its state with callers through what it returns.
+     */
+    fastify.get('/contracts/:ref/state', { preValidation: requireRunAuthorization }, async (request, reply) => {
+        const ref = contractRef(request.params.ref);
+        if (!ref || ref.version !== undefined) {
+            return reply.status(400).send({ error: 'Name a contract as path.Name: state belongs to every version' });
+        }
+        const result = await options.service.contractService.readState(ref.path, ref.name, contractCaller(request));
+        if (!result.ok) {
+            return reply.status(result.status).send({ error: result.error });
+        }
+        return {
+            variables: result.variables.map(({ variable, scope, value, updatedAt }) => ({
+                name: variable,
+                scope,
+                value: valueToJson(decodeValue(value)),
+                updatedAt,
+            })),
+        };
+    });
+    /** Deletes `path.Name@version`, or every version of `path.Name`. */
+    fastify.delete('/contracts/:ref', { preValidation: requireRunAuthorization }, async (request, reply) => {
+        const ref = contractRef(request.params.ref);
+        if (!ref) {
+            return reply.status(400).send({ error: 'Name a contract as path.Name or path.Name@version' });
+        }
+        const result = await options.service.contractService.delete(ref.path, ref.name, ref.version, contractCaller(request));
+        if (!result.ok) {
+            return reply.status(result.status).send({ error: result.error });
+        }
+        return { success: true };
+    });
+    // End Contract Routes
     // Start Grant Routes
     /** Issues a root grant to the request's signer, if the node's approval hook allows it. */
     fastify.post('/grants/request', {