stellarium-ts 0.19.0 → 0.20.0

package/dist/client/operatorClient.d.ts

@@ -1,3 +1,4 @@
+import type { ContractPaymentVoucher } from "../resource/invoker.js";
 export type PaymentSubmission = FixedPaymentSubmission | InferencePaymentSubmission;
 export interface FixedPaymentVoucher {
     kind?: undefined;
@@ -52,6 +53,33 @@ export interface RunAuthorizationRequest {
     runId: string;
     source: string;
 }
+/** What a node sends to authorize a call to one of its contracts. Matches apps/operator/src/runs/runService.ts. */
+export interface ContractRunAuthorizationRequest {
+    /** The caller's voucher. Its `invocationId` is the run's id. */
+    voucher: ContractPaymentVoucher;
+    /** The contract's source, which the operator prices. */
+    source: string;
+}
+/**
+ * The operator's answer to a contract call: a hold for the run named by the voucher's `invocationId`, or
+ * `free` when the caller is in this node's organization, which doesn't pay itself. `payerOrganizationId` is
+ * the organization paying for the call, which the contract sees as `caller.org`. Older operators omit it.
+ */
+export type ContractRunAuthorizeResult = {
+    ok: true;
+    free: boolean;
+    payerOrganizationId?: string;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+/** What the operator knows of this node. */
+export interface OperatorSession {
+    organizationId: string;
+    /** The node's listed price per million script tokens. Absent from older operators. */
+    priceMicroUsdPerMillionTokens?: number;
+}
 /** The operator's hold for a run: up to `heldMicroUsd` for the script's tokens and its paid calls together. */
 export type RunAuthorizeResult = {
     ok: true;
@@ -86,9 +114,7 @@ export declare class OperatorClient {
      * enrolls the node first; a node that is already enrolled ignores the token. Throws if the node is
      * not enrolled or the operator refuses.
      */
-    session(enrollmentToken?: string, baseUrl?: string): Promise<{
-        organizationId: string;
-    }>;
+    session(enrollmentToken?: string, baseUrl?: string): Promise<OperatorSession>;
     /**
      * Asks the operator to hold the voucher's amount (or `maxAmount`) on the payer's balance, before
      * running the paid function. An unreachable operator is reported as a 503 refusal.
@@ -99,6 +125,11 @@ export declare class OperatorClient {
      * it. An unreachable operator is reported as a 503 refusal.
      */
     authorizeRun(request: RunAuthorizationRequest): Promise<RunAuthorizeResult>;
+    /**
+     * Asks the operator to hold a contract call's cost on the caller's organization, or on the caller's run,
+     * before running the contract. An unreachable operator is reported as a 503 refusal.
+     */
+    authorizeContractRun(request: ContractRunAuthorizationRequest): Promise<ContractRunAuthorizeResult>;
     /** Charges a held run for the tokens its script executed, and releases the rest of its hold. */
     captureRun(request: {
         runId: string;

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

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

package/dist/client/operatorClient.js

@@ -103,6 +103,21 @@ export class OperatorClient {
         const { heldMicroUsd, maxTokens } = result.body;
         return { ok: true, heldMicroUsd, maxTokens };
     }
+    /**
+     * Asks the operator to hold a contract call's cost on the caller's organization, or on the caller's run,
+     * before running the contract. An unreachable operator is reported as a 503 refusal.
+     */
+    async authorizeContractRun(request) {
+        const result = await this.hold('/runs/contract/authorize', request);
+        if (!result.ok)
+            return result;
+        const body = result.body;
+        return {
+            ok: true,
+            free: body?.status === 'free',
+            ...(typeof body?.payerOrganizationId === 'string' ? { payerOrganizationId: body.payerOrganizationId } : {}),
+        };
+    }
     /** Charges a held run for the tokens its script executed, and releases the rest of its hold. */
     async captureRun(request) {
         await this.settle('/runs/capture', request);

package/dist/contract/repository.d.ts

@@ -0,0 +1,49 @@
+import type { NodeDatabase } from "../db/database.js";
+export interface ContractParameter {
+    name: string;
+    /** A RequestScript type string, e.g. 'int32' or '[]string'. */
+    type: string;
+}
+export interface StoredContract {
+    path: string;
+    name: string;
+    version: string;
+    source: string;
+    parameters: ContractParameter[];
+    returnType: string;
+    /** The organization that deployed it, which owns every version. Null when the node's admin did. */
+    ownerOrganizationId: string | null;
+    description: string | null;
+    createdAt: string;
+}
+/** Why `save` refused a contract. */
+export type SaveContractRefusal = 'version_exists' | 'owned_by_another';
+/**
+ * Contracts deployed to this node. Versions are immutable, and every version of a contract belongs to the
+ * organization that deployed its first one.
+ */
+export declare class ContractRepository {
+    private readonly db;
+    constructor(db: NodeDatabase);
+    /**
+     * Saves a new version. `ownerOrganizationId` null is the node's admin, which may add versions to any
+     * contract; they stay owned by the contract's owner.
+     */
+    save(contract: Omit<StoredContract, 'createdAt'>): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        refused: SaveContractRefusal;
+    }>;
+    /** The contract's latest version. */
+    latest(path: string, name: string): Promise<StoredContract | undefined>;
+    /** The owner of the contract at `path.name`: an organization, null for the node's admin, or undefined if there is none. */
+    owner(path: string, name: string): Promise<string | null | undefined>;
+    /** The latest version of every contract, ordered by path and name. */
+    allLatest(): Promise<StoredContract[]>;
+    /** One page of every version, ordered by path, name and deploy time. */
+    list(offset: number, limit: number): Promise<StoredContract[]>;
+    /** Deletes one version, or every version when `version` is omitted. False when there was nothing to delete. */
+    delete(path: string, name: string, version?: string): Promise<boolean>;
+}
+//# sourceMappingURL=repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/contract/repository.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,mGAAmG;IACnG,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACrB;AAyCD,qCAAqC;AACrC,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;AAExE;;;GAGG;AACH,qBAAa,kBAAkB;IACf,OAAO,CAAC,QAAQ,CAAC,EAAE;IAA/B,YAA6B,EAAE,EAAE,YAAY,EAAI;IAEjD;;;OAGG;IACG,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,OAAO,EAAE,mBAAmB,CAAA;KAAE,CAAC,CAgB3H;IAED,qCAAqC;IAC/B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAG5E;IAED,2HAA2H;IACrH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAG1E;IAED,sEAAsE;IAChE,SAAS,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAE3C;IAED,wEAAwE;IAClE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAGnE;IAED,+GAA+G;IACzG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK3E;CACJ"}

package/dist/contract/repository.js

@@ -0,0 +1,80 @@
+import { compareVersions } from "requestscript";
+function toContract(row) {
+    return {
+        path: row.path,
+        name: row.name,
+        version: row.version,
+        source: row.source,
+        parameters: JSON.parse(row.parameters),
+        returnType: row.return_type,
+        ownerOrganizationId: row.owner_organization_id,
+        description: row.description,
+        createdAt: row.created_at,
+    };
+}
+/** The latest version of each contract in `rows`, ordered by path and name. */
+function latestOf(rows) {
+    const latest = new Map();
+    for (const row of rows) {
+        const key = `${row.path}.${row.name}`;
+        const current = latest.get(key);
+        if (!current || compareVersions(row.version, current.version) > 0) {
+            latest.set(key, row);
+        }
+    }
+    return [...latest.values()].map(toContract);
+}
+/**
+ * Contracts deployed to this node. Versions are immutable, and every version of a contract belongs to the
+ * organization that deployed its first one.
+ */
+export class ContractRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Saves a new version. `ownerOrganizationId` null is the node's admin, which may add versions to any
+     * contract; they stay owned by the contract's owner.
+     */
+    async save(contract) {
+        return this.db.transaction(async (tx) => {
+            const existing = await tx.all('SELECT * FROM contract WHERE path = ? AND name = ?', [contract.path, contract.name]);
+            const owner = existing.length > 0 ? existing[0].owner_organization_id : contract.ownerOrganizationId;
+            if (contract.ownerOrganizationId !== null && owner !== contract.ownerOrganizationId) {
+                return { ok: false, refused: 'owned_by_another' };
+            }
+            if (existing.some(row => row.version === contract.version)) {
+                return { ok: false, refused: 'version_exists' };
+            }
+            await tx.run('INSERT INTO contract (path, name, version, source, parameters, return_type, owner_organization_id, description, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)', [contract.path, contract.name, contract.version, contract.source, JSON.stringify(contract.parameters), contract.returnType, owner, contract.description, new Date().toISOString()]);
+            return { ok: true };
+        });
+    }
+    /** The contract's latest version. */
+    async latest(path, name) {
+        const rows = await this.db.all('SELECT * FROM contract WHERE path = ? AND name = ?', [path, name]);
+        return latestOf(rows)[0];
+    }
+    /** The owner of the contract at `path.name`: an organization, null for the node's admin, or undefined if there is none. */
+    async owner(path, name) {
+        const row = await this.db.get('SELECT owner_organization_id FROM contract WHERE path = ? AND name = ? LIMIT 1', [path, name]);
+        return row ? row.owner_organization_id : undefined;
+    }
+    /** The latest version of every contract, ordered by path and name. */
+    async allLatest() {
+        return latestOf(await this.db.all('SELECT * FROM contract ORDER BY path, name'));
+    }
+    /** One page of every version, ordered by path, name and deploy time. */
+    async list(offset, limit) {
+        const rows = await this.db.all('SELECT * FROM contract ORDER BY path, name, created_at, version LIMIT ? OFFSET ?', [limit, offset]);
+        return rows.map(toContract);
+    }
+    /** Deletes one version, or every version when `version` is omitted. False when there was nothing to delete. */
+    async delete(path, name, version) {
+        const result = version === undefined
+            ? await this.db.run('DELETE FROM contract WHERE path = ? AND name = ?', [path, name])
+            : await this.db.run('DELETE FROM contract WHERE path = ? AND name = ? AND version = ?', [path, name, version]);
+        return result.changes > 0;
+    }
+}

package/dist/contract/service.d.ts

@@ -0,0 +1,103 @@
+import { type Resource, type ResourceFunctionCallParameter, type ResourceResolver } from "requestscript";
+import type { OperatorClient } from "../client/operatorClient.js";
+import { type CombinationResourceInvoker, type ContractHost, type ContractPaymentVoucher, type ScriptContext } from "../resource/invoker.js";
+import { type ResourceRepository } from "../resource/repository.js";
+import { type InvokeResult } from "../resource/settlement.js";
+import type { NodeConfig } from "../service.js";
+import type { ContractRepository, StoredContract } from "./repository.js";
+import { type ContractStateRepository, type ContractStateRow } from "./state.js";
+export declare const DEFAULT_MAX_CONTRACT_SOURCE_BYTES: number;
+/** The longest a call waits for earlier calls of the same stateful contract on this node. */
+export declare const CONTRACT_LOCK_TIMEOUT_MS = 30000;
+/** Who deploys or deletes a contract: the node's admin with its API key, or an organization's API client with a run token. */
+export type ContractCaller = {
+    kind: 'apiKey';
+} | {
+    kind: 'client';
+    token: string;
+    organizationId: string;
+};
+/** A refusal, with the HTTP status a route answers. */
+export type ContractRefusal = {
+    ok: false;
+    status: number;
+    error: string;
+};
+export interface DeployedContract {
+    path: string;
+    name: string;
+    version: string;
+    /** What the deploy cost the caller's organization, in micro-USD. */
+    feeMicroUsd: number;
+}
+/**
+ * Deploys, deletes and runs the contracts on this node. A contract's latest version is one of the node's
+ * resources, with one function, `run`. Calls to it are billed by the tokens it executes, through a run the
+ * operator holds on the caller's organization or on the caller's own run, which also pays for the paid calls
+ * the contract makes.
+ */
+export declare class ContractService implements ContractHost {
+    private readonly contracts;
+    private readonly state;
+    private readonly resources;
+    private readonly resolver;
+    private readonly invoker;
+    private readonly operatorClient;
+    private readonly config;
+    private readonly log;
+    /** Tells peers about this node's resources again, after a contract is deployed or deleted. Set once the node listens. */
+    announce?: () => void;
+    /** The latest call holding each stateful contract (`path.Name`) on this node. */
+    private readonly locks;
+    /** How long a call waits for earlier calls of the same stateful contract. */
+    lockTimeoutMs: number;
+    constructor(contracts: ContractRepository, state: ContractStateRepository, resources: ResourceRepository, resolver: ResourceResolver, invoker: CombinationResourceInvoker, operatorClient: OperatorClient, config: NodeConfig, log?: (error: unknown, message: string) => void);
+    /**
+     * Saves a new version of a contract. A deploy by another organization's API client pays this node's
+     * deploy fee from the client's run hold, and is charged only if the contract is saved.
+     */
+    deploy(source: string, description: string | undefined, caller: ContractCaller): Promise<{
+        ok: true;
+        contract: DeployedContract;
+    } | ContractRefusal>;
+    /** Deletes a version, or every version, of a contract. Its owner or the node's admin may. */
+    delete(path: string, name: string, version: string | undefined, caller: ContractCaller): Promise<{
+        ok: true;
+    } | ContractRefusal>;
+    /** The contract's state variables and their scopes, for its owner and the node's admin. */
+    readState(path: string, name: string, caller: ContractCaller): Promise<{
+        ok: true;
+        variables: ContractStateRow[];
+    } | ContractRefusal>;
+    /**
+     * Runs a contract for another node's call, paid by its voucher, which the route has checked. The operator
+     * holds the call's cost as a run named by the voucher's `invocationId`, unless the caller is in this
+     * node's organization. `depth` is how many contracts deep the call is. The contract sees the payer the
+     * operator authorized, and the voucher's key, as `caller`.
+     */
+    serve(voucher: ContractPaymentVoucher, contract: StoredContract, parameters: ResourceFunctionCallParameter[], depth: number): Promise<InvokeResult | {
+        refused: {
+            status: number;
+            error: string;
+        };
+    }>;
+    invokeLocal(resource: Resource, parameters: ResourceFunctionCallParameter[], context: ScriptContext): Promise<InvokeResult>;
+    /** Runs a contract under a held run, then captures the tokens it executed, or releases the run if it couldn't run. */
+    private runBilled;
+    /**
+     * Runs a contract's script. Its calls are made at `context.depth`, and billed to `context.runId` when set.
+     * A script that fails is reported as the call's error, as a failing function is.
+     *
+     * A contract with state variables runs one call at a time on this node, and saves its state only if the
+     * run succeeds. A call that re-enters a contract already running in its own chain skips the lock, and
+     * whichever of the two saves second finds the state changed and fails, so no update is lost.
+     */
+    private run;
+    /**
+     * Waits for the contract's previous calls on this node, then holds it until the returned release is
+     * called. Answers undefined if the wait passes `lockTimeoutMs`, which breaks a cycle of calls between
+     * nodes that leads back here.
+     */
+    private lock;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/contract/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/contract/service.ts"],"names":[],"mappings":"AACA,OAAO,EAAoD,KAAK,QAAQ,EAAE,KAAK,6BAA6B,EAAE,KAAK,gBAAgB,EAAyC,MAAM,eAAe,CAAC;AAClM,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAuB,KAAK,0BAA0B,EAAE,KAAK,YAAY,EAAE,KAAK,sBAAsB,EAAsB,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACtL,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,KAAK,YAAY,EAAkC,MAAM,2BAA2B,CAAC;AAC9F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,KAAK,uBAAuB,EAAE,KAAK,gBAAgB,EAAoC,MAAM,YAAY,CAAC;AAEnH,eAAO,MAAM,iCAAiC,QAAY,CAAC;AAC3D,6FAA6F;AAC7F,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAW/C,8HAA8H;AAC9H,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5G,uDAAuD;AACvD,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E,MAAM,WAAW,gBAAgB;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;CACvB;AAID;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,YAAY;IAS5C,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAfxB,yHAAyH;IACzH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAC1D,6EAA6E;IAC7E,aAAa,SAA4B;IAEzC,YACqB,SAAS,EAAE,kBAAkB,EAC7B,KAAK,EAAE,uBAAuB,EAC9B,SAAS,EAAE,kBAAkB,EAC7B,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,0BAA0B,EACnC,cAAc,EAAE,cAAc,EAC9B,MAAM,EAAE,UAAU,EAClB,GAAG,GAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAwD,EACnH;IAEJ;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,QAAQ,EAAE,gBAAgB,CAAA;KAAE,GAAG,eAAe,CAAC,CAiFzJ;IAED,6FAA6F;IACvF,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG,eAAe,CAAC,CAiBrI;IAED,2FAA2F;IACrF,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,SAAS,EAAE,gBAAgB,EAAE,CAAA;KAAE,GAAG,eAAe,CAAC,CAS1I;IAED;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,sBAAsB,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,6BAA6B,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG;QAAE,OAAO,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC,CAUzM;IAEK,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,6BAA6B,EAAE,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA4BhI;IAED,sHAAsH;YACxG,SAAS;IAYvB;;;;;;;OAOG;YACW,GAAG;IAyCjB;;;;OAIG;YACW,IAAI;CA4BrB"}

package/dist/contract/service.js

@@ -0,0 +1,297 @@
+import { randomUUID } from "node:crypto";
+import { interpretParsed, parseScript, RequestScriptError, TokenMeter, typeToString } from "requestscript";
+import { MAX_CONTRACT_DEPTH } from "../resource/invoker.js";
+import { CONTRACT_FUNCTION } from "../resource/repository.js";
+import { settlePaidCall, settleRunLater } from "../resource/settlement.js";
+import { DEFAULT_MAX_CONTRACT_STATE_BYTES } from "./state.js";
+export const DEFAULT_MAX_CONTRACT_SOURCE_BYTES = 64 * 1024;
+/** The longest a call waits for earlier calls of the same stateful contract on this node. */
+export const CONTRACT_LOCK_TIMEOUT_MS = 30_000;
+const refuse = (status, error) => ({ ok: false, status, error });
+/**
+ * Deploys, deletes and runs the contracts on this node. A contract's latest version is one of the node's
+ * resources, with one function, `run`. Calls to it are billed by the tokens it executes, through a run the
+ * operator holds on the caller's organization or on the caller's own run, which also pays for the paid calls
+ * the contract makes.
+ */
+export class ContractService {
+    contracts;
+    state;
+    resources;
+    resolver;
+    invoker;
+    operatorClient;
+    config;
+    log;
+    /** Tells peers about this node's resources again, after a contract is deployed or deleted. Set once the node listens. */
+    announce;
+    /** The latest call holding each stateful contract (`path.Name`) on this node. */
+    locks = new Map();
+    /** How long a call waits for earlier calls of the same stateful contract. */
+    lockTimeoutMs = CONTRACT_LOCK_TIMEOUT_MS;
+    constructor(contracts, state, resources, resolver, invoker, operatorClient, config, log = (error, message) => console.error(message, error)) {
+        this.contracts = contracts;
+        this.state = state;
+        this.resources = resources;
+        this.resolver = resolver;
+        this.invoker = invoker;
+        this.operatorClient = operatorClient;
+        this.config = config;
+        this.log = log;
+    }
+    /**
+     * Saves a new version of a contract. A deploy by another organization's API client pays this node's
+     * deploy fee from the client's run hold, and is charged only if the contract is saved.
+     */
+    async deploy(source, description, caller) {
+        const maxBytes = this.config.maxContractSourceBytes ?? DEFAULT_MAX_CONTRACT_SOURCE_BYTES;
+        if (Buffer.byteLength(source) > maxBytes) {
+            return refuse(413, `Contracts may be at most ${maxBytes} bytes`);
+        }
+        let script;
+        try {
+            script = parseScript(source);
+        }
+        catch (error) {
+            return refuse(400, `Invalid contract: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const declaration = script.declaration;
+        if (declaration.kind !== 'contract') {
+            return refuse(400, 'Invalid contract: deploy a contract script, not a request');
+        }
+        if (declaration.path.length === 0) {
+            return refuse(400, 'Invalid contract: give it a path, such as com.example.Name');
+        }
+        if (!declaration.returnType) {
+            return refuse(400, 'Invalid contract: declare its return type, such as contract com.example.Name(...): string');
+        }
+        const path = declaration.path.join('.');
+        const { name, version } = declaration;
+        if (this.resources.isRegistered({ path, name }) || await this.resources.isLearned(path, name)) {
+            return refuse(409, `${path}.${name} is already a resource on the network`);
+        }
+        const ownerOrganizationId = caller.kind === 'client' ? caller.organizationId : null;
+        const owner = await this.contracts.owner(path, name);
+        if (owner !== undefined && ownerOrganizationId !== null && owner !== ownerOrganizationId) {
+            return refuse(409, `${path}.${name} belongs to another organization`);
+        }
+        const save = () => this.contracts.save({
+            path,
+            name,
+            version,
+            source,
+            parameters: declaration.parameters.map(parameter => ({ name: parameter.name, type: typeToString(parameter.type) })),
+            returnType: typeToString(declaration.returnType),
+            ownerOrganizationId,
+            description: description ?? null,
+        });
+        const saved = (feeMicroUsd) => {
+            this.announce?.();
+            return { ok: true, contract: { path, name, version, feeMicroUsd } };
+        };
+        const versionExists = () => refuse(409, `${path}.${name}@${version} already exists: contracts are immutable, so deploy a new version`);
+        const fee = this.config.contractDeployFeeMicroUsd ?? 0;
+        const billed = caller.kind === 'client' && caller.organizationId !== this.config.organizationId && fee > 0;
+        if (!billed) {
+            const result = await save();
+            return result.ok ? saved(0) : result.refused === 'version_exists' ? versionExists() : refuse(409, `${path}.${name} belongs to another organization`);
+        }
+        const organizationId = this.config.organizationId;
+        if (!organizationId) {
+            return refuse(503, 'This node isn\'t enrolled in an organization, so it can\'t charge the deploy fee');
+        }
+        const runId = randomUUID();
+        const authorization = await this.operatorClient.authorizeRun({ token: caller.token, runId, source });
+        if (!authorization.ok) {
+            return refuse(authorization.status, authorization.error);
+        }
+        const voucher = this.invoker.createPaymentVoucher(organizationId, fee, path, name, 'deploy', [{ name: 'version', value: version }], runId);
+        let refusal;
+        const result = await settlePaidCall(this.operatorClient, voucher, async () => {
+            const result = await save();
+            if (result.ok) {
+                return { value: true, error: null };
+            }
+            refusal = result.refused === 'version_exists' ? versionExists() : refuse(409, `${path}.${name} belongs to another organization`);
+            return { value: null, error: { message: refusal.error } };
+        }, this.log);
+        // The deploy ran no script, so the run is charged nothing beyond the fee's receipt.
+        settleRunLater(this.operatorClient, runId, 'capture', 0, this.log);
+        if ('refused' in result) {
+            return refuse(result.refused.status, result.refused.error);
+        }
+        return refusal ?? saved(fee);
+    }
+    /** Deletes a version, or every version, of a contract. Its owner or the node's admin may. */
+    async delete(path, name, version, caller) {
+        const owner = await this.contracts.owner(path, name);
+        if (owner === undefined) {
+            return refuse(404, `No contract ${path}.${name}`);
+        }
+        if (caller.kind === 'client' && owner !== caller.organizationId) {
+            return refuse(403, `${path}.${name} belongs to another organization`);
+        }
+        if (!await this.contracts.delete(path, name, version)) {
+            return refuse(404, `No contract ${path}.${name}@${version}`);
+        }
+        // State outlives a version, so a new one keeps it, but not the contract.
+        if (await this.contracts.owner(path, name) === undefined) {
+            await this.state.deleteContract(path, name);
+        }
+        this.announce?.();
+        return { ok: true };
+    }
+    /** The contract's state variables and their scopes, for its owner and the node's admin. */
+    async readState(path, name, caller) {
+        const owner = await this.contracts.owner(path, name);
+        if (owner === undefined) {
+            return refuse(404, `No contract ${path}.${name}`);
+        }
+        if (caller.kind === 'client' && owner !== caller.organizationId) {
+            return refuse(403, `${path}.${name} belongs to another organization`);
+        }
+        return { ok: true, variables: await this.state.list(path, name) };
+    }
+    /**
+     * Runs a contract for another node's call, paid by its voucher, which the route has checked. The operator
+     * holds the call's cost as a run named by the voucher's `invocationId`, unless the caller is in this
+     * node's organization. `depth` is how many contracts deep the call is. The contract sees the payer the
+     * operator authorized, and the voucher's key, as `caller`.
+     */
+    async serve(voucher, contract, parameters, depth) {
+        const authorization = await this.operatorClient.authorizeContractRun({ voucher, source: contract.source });
+        if (!authorization.ok) {
+            return { refused: { status: authorization.status, error: authorization.error } };
+        }
+        const context = { jwt: null, depth, caller: { org: authorization.payerOrganizationId ?? null, node: voucher.publicKey } };
+        if (authorization.free) {
+            return this.run(contract, parameters, context);
+        }
+        return this.runBilled(voucher.invocationId, contract, parameters, context);
+    }
+    async invokeLocal(resource, parameters, context) {
+        const failed = (reason) => ({ value: null, error: { message: `Failed to invoke ${resource.name}.${CONTRACT_FUNCTION}: ${reason}` } });
+        const depth = (context.depth ?? 0) + 1;
+        if (depth > MAX_CONTRACT_DEPTH) {
+            return failed(`contracts may call each other at most ${MAX_CONTRACT_DEPTH} deep`);
+        }
+        const contract = await this.contracts.latest(resource.path, resource.name);
+        if (!contract) {
+            return failed('the contract was deleted');
+        }
+        // A script that doesn't say who it runs for is this node's own.
+        const caller = context.caller ?? { org: this.config.organizationId ?? null, node: this.config.publicKey };
+        const runContext = { jwt: context.jwt ?? null, depth, caller, contracts: context.contracts };
+        if (context.runId === undefined) {
+            return this.run(contract, parameters, runContext);
+        }
+        // A billed script pays for the contract as another node's script would, from its run's hold.
+        const organizationId = this.config.organizationId;
+        if (!organizationId) {
+            return failed('this node is not enrolled in an organization that can be paid');
+        }
+        const costLimit = this.config.contractCostLimitMicroUsd ?? this.config.costLimitMicroUsd;
+        const voucher = this.invoker.createContractVoucher(organizationId, this.config.priceMicroUsdPerMillionTokens ?? 0, costLimit, resource.path, resource.name, CONTRACT_FUNCTION, parameters, context.runId);
+        const authorization = await this.operatorClient.authorizeContractRun({ voucher, source: contract.source });
+        if (!authorization.ok) {
+            return failed(authorization.error);
+        }
+        return this.runBilled(voucher.invocationId, contract, parameters, runContext);
+    }
+    /** Runs a contract under a held run, then captures the tokens it executed, or releases the run if it couldn't run. */
+    async runBilled(runId, contract, parameters, context) {
+        const meter = new TokenMeter();
+        try {
+            const result = await this.run(contract, parameters, { ...context, runId }, meter);
+            settleRunLater(this.operatorClient, runId, 'capture', meter.tokens, this.log);
+            return result;
+        }
+        catch (error) {
+            settleRunLater(this.operatorClient, runId, 'release', meter.tokens, this.log);
+            throw error;
+        }
+    }
+    /**
+     * Runs a contract's script. Its calls are made at `context.depth`, and billed to `context.runId` when set.
+     * A script that fails is reported as the call's error, as a failing function is.
+     *
+     * A contract with state variables runs one call at a time on this node, and saves its state only if the
+     * run succeeds. A call that re-enters a contract already running in its own chain skips the lock, and
+     * whichever of the two saves second finds the state changed and fails, so no update is lost.
+     */
+    async run(contract, parameters, context, meter) {
+        const label = `${contract.path}.${contract.name}`;
+        const failed = (reason) => ({ value: null, error: { message: `Contract ${label}@${contract.version} failed: ${reason}` } });
+        const script = parseScript(contract.source);
+        const stateful = script.body.some(statement => statement.kind === 'varDecl' && statement.state !== undefined);
+        let release;
+        if (stateful && !context.contracts?.includes(label)) {
+            release = await this.lock(label);
+            if (!release) {
+                return failed(`it is busy: other calls held it for ${this.lockTimeoutMs / 1000} seconds`);
+            }
+        }
+        try {
+            const result = await interpretParsed(script, {
+                resourceResolver: this.resolver,
+                resourceInvoker: this.invoker.forScript({ ...context, contracts: [...context.contracts ?? [], label] }),
+                parameters: Object.fromEntries(parameters.map(parameter => [parameter.name, parameter.value])),
+                meter,
+                builtins: { jwt: context.jwt, caller: context.caller },
+                state: stateful ? { get: (variable, scope) => this.state.get(contract.path, contract.name, variable, scope) } : undefined,
+            });
+            if (result.state.length > 0) {
+                const maxBytes = this.config.maxContractStateBytes ?? DEFAULT_MAX_CONTRACT_STATE_BYTES;
+                const committed = await this.state.commit(contract.path, contract.name, result.state, maxBytes);
+                if (!committed.ok) {
+                    return failed(committed.reason === 'conflict'
+                        ? 'its state changed during the call, so nothing was saved; try again'
+                        : `its state would be ${committed.bytes} bytes, more than this node's ${maxBytes}, so nothing was saved`);
+                }
+            }
+            return { value: result.returnValue, error: null };
+        }
+        catch (error) {
+            if (error instanceof RequestScriptError) {
+                return failed(error.message);
+            }
+            throw error;
+        }
+        finally {
+            release?.();
+        }
+    }
+    /**
+     * Waits for the contract's previous calls on this node, then holds it until the returned release is
+     * called. Answers undefined if the wait passes `lockTimeoutMs`, which breaks a cycle of calls between
+     * nodes that leads back here.
+     */
+    async lock(label) {
+        const previous = this.locks.get(label) ?? Promise.resolve();
+        let release;
+        const held = new Promise(resolve => {
+            release = resolve;
+        });
+        const tail = previous.then(() => held);
+        this.locks.set(label, tail);
+        void tail.then(() => {
+            if (this.locks.get(label) === tail) {
+                this.locks.delete(label);
+            }
+        });
+        let timer;
+        const acquired = await Promise.race([
+            previous.then(() => true),
+            new Promise(resolve => {
+                timer = setTimeout(() => resolve(false), this.lockTimeoutMs);
+            }),
+        ]);
+        clearTimeout(timer);
+        if (!acquired) {
+            // Gives up its turn, so the calls behind it go on once the earlier ones finish.
+            release();
+            return undefined;
+        }
+        return release;
+    }
+}