@pushchain/core 6.0.27-alpha.3 → 6.0.27-alpha.5

package/src/lib/job-spec/preview.js

@@ -0,0 +1,298 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bindJobPreviewAccounts = bindJobPreviewAccounts;
+exports.decodeJobAnswer = decodeJobAnswer;
+exports.previewJobSpec = previewJobSpec;
+const viem_1 = require("viem");
+const read_state_types_1 = require("../read-state/read-state.types");
+const envelopes_1 = require("../read-state/envelopes");
+const errors_1 = require("../market/errors");
+const codec_1 = require("./codec");
+const helpers_1 = require("./helpers");
+const read_1 = require("./read");
+const constants_1 = require("./constants");
+const resolvers = new WeakMap();
+/** @internal Bind the real client's configured CEA resolver without exposing its runtime. */
+function bindJobPreviewAccounts(universal, resolve) {
+    resolvers.set(universal, resolve);
+}
+/** Follow the deployed V2 type codes; uint values above int256.max cannot be compared. */
+function decodeJobAnswer(read, data) {
+    const bytes = BigInt((data.length - 2) / 2);
+    const invalid = () => {
+        throw new errors_1.JobSpecError('INVALID_READ_RESULT', 'The consensus bytes do not contain the selected JobSpec field.');
+    };
+    const word = (at) => {
+        if (at < BigInt(0) || at + BigInt(32) > bytes)
+            return invalid();
+        return BigInt('0x' + data.slice(2 + Number(at) * 2, 66 + Number(at) * 2));
+    };
+    const dynamic = (n) => [6, 7, 9].includes(n.code) || n.children.some(dynamic);
+    const head = (n) => dynamic(n)
+        ? BigInt(1)
+        : n.code === 8
+            ? n.children.reduce((sum, c) => sum + head(c), BigInt(0))
+            : n.code === 10
+                ? BigInt(n.size ?? 0) * head(n.children[0])
+                : BigInt(1);
+    let node = (0, read_1.parseOutputs)(read.outputs);
+    let base = BigInt(0);
+    for (const index of read.field) {
+        let child;
+        let start = base;
+        let slot;
+        if (node.code === 8) {
+            child = node.children[index];
+            if (!child)
+                return invalid();
+            slot =
+                base +
+                    BigInt(32) *
+                        node.children
+                            .slice(0, index)
+                            .reduce((sum, c) => sum + head(c), BigInt(0));
+        }
+        else if (node.code === 9 || node.code === 10) {
+            if (BigInt(index) >= (node.code === 9 ? word(base) : BigInt(node.size ?? 0)))
+                return invalid();
+            child = node.children[0];
+            start += node.code === 9 ? BigInt(32) : BigInt(0);
+            slot = start + BigInt(32) * BigInt(index) * head(child);
+        }
+        else
+            return invalid();
+        base = dynamic(child) ? start + word(slot) : slot;
+        if (base > bytes)
+            return invalid();
+        node = child;
+    }
+    const value = word(base);
+    if (node.code === 6 || node.code === 7) {
+        if (base + BigInt(32) + value > bytes)
+            return invalid();
+        return BigInt.asIntN(256, BigInt((0, viem_1.keccak256)(('0x' +
+            data.slice(2 + Number(base + BigInt(32)) * 2, 2 + Number(base + BigInt(32) + value) * 2)))));
+    }
+    if (node.code === 9)
+        return BigInt.asIntN(256, value);
+    if ((node.code === 1 && value >= BigInt(1) << BigInt(255)) ||
+        (node.code === 3 && value > BigInt(1)) ||
+        (node.code === 4 && value >= BigInt(1) << BigInt(160)))
+        return invalid();
+    return BigInt.asIntN(256, value);
+}
+function compare(value, op, target) {
+    switch (op) {
+        case 'EQUAL':
+            return value === target;
+        case 'NOT_EQUAL':
+            return value !== target;
+        case 'GREATER_THAN':
+            return value > target;
+        case 'GREATER_OR_EQUAL':
+            return value >= target;
+        case 'LESS_THAN':
+            return value < target;
+        case 'LESS_OR_EQUAL':
+            return value <= target;
+    }
+}
+function combine(tree, checks) {
+    const results = tree.of.map((x) => typeof x === 'number' ? checks[x].pass : combine(x, checks));
+    const yes = results.filter((v) => v === true).length;
+    const unknown = results.filter((v) => v === null).length;
+    const required = tree.kind === 'ALL'
+        ? results.length
+        : tree.kind === 'ANY'
+            ? 1
+            : tree.k ?? 0;
+    return yes >= required ? true : yes + unknown < required ? false : null;
+}
+async function previewJobSpec(subject, options) {
+    // Validate and copy before asynchronous work; later caller mutations must not change paid criteria.
+    const input = (0, codec_1.decodeJobSpec)((0, codec_1.encodeJobSpec)(subject), {
+        format: 'params' in subject ? 'template' : 'spec',
+    });
+    options = {
+        ...options,
+        params: options.params && [...options.params],
+        baseline: options.baseline && [...options.baseline],
+        accounts: { ...options.accounts },
+        resume: options.resume && [...options.resume],
+    };
+    if (options.maxTotalFee !== undefined &&
+        (typeof options.maxTotalFee !== 'bigint' || options.maxTotalFee < BigInt(0)))
+        throw new errors_1.JobSpecError('INVALID_AMOUNT', 'maxTotalFee must be a nonnegative bigint.');
+    if (options.baseline) {
+        if (options.baseline.length !== input.reads.length)
+            throw new errors_1.JobSpecError('INVALID_BASELINE', 'Provide one baseline entry per read; use null for unknown entries.');
+        options.baseline.forEach((value) => {
+            if (value !== null)
+                (0, codec_1.int256)(value);
+        });
+    }
+    let spec;
+    if ('params' in input) {
+        if (input.checks.some((c) => c.target === constants_1.PRINCIPAL ||
+            (typeof c.target === 'object' && 'principalBps' in c.target)) &&
+            options.principal === undefined)
+            throw new errors_1.JobSpecError('UNFILLED_PLACEHOLDER', 'Supply principal to resolve principal-based preview targets.');
+        const accounts = { ...options.accounts };
+        const resolve = resolvers.get(options.client.universal);
+        for (const [index, read] of input.reads.entries()) {
+            const chain = `${read.chainNamespace}:${read.chainId}`;
+            const needed = read.fills?.some((f) => f.source === 'WALLET') ||
+                input.checks.some((c) => c.read === index && c.target === 'agentic:wallet');
+            if (needed && !accounts[chain] && options.wallet && resolve)
+                accounts[chain] = await resolve((0, viem_1.getAddress)(options.wallet), chain);
+        }
+        spec = (0, helpers_1.resolveJobSpec)(input, {
+            principal: options.principal ?? BigInt(0),
+            params: options.params ?? [],
+            accounts,
+            origin: viem_1.zeroHash,
+            executeBy: 0,
+            settleWindow: 1,
+        });
+    }
+    else
+        spec = input;
+    const waitOptions = {
+        timeoutMs: options.advanced?.timeout,
+        pollingIntervalMs: options.advanced?.pollingIntervalMs,
+        resultShape: { kind: 'raw' },
+    };
+    let responses;
+    let quoted = BigInt(0);
+    let newlyPaid = BigInt(0);
+    if (options.resume) {
+        if (options.resume.length !== spec.reads.length ||
+            options.resume.some((id) => !/^0x[\da-f]{64}$/i.test(id)) ||
+            new Set(options.resume.map((x) => x.toLowerCase())).size !==
+                options.resume.length)
+            throw new errors_1.JobSpecError('INVALID_PREVIEW_RESUME', 'Provide one distinct request ID per read, in read order.');
+        responses = [];
+        for (const [i, id] of options.resume.entries()) {
+            const response = await options.client.universal.trackRead({ requestId: id }, { resultShape: { kind: 'raw' }, progressHook: options.progressHook });
+            const read = spec.reads[i];
+            let matched = false;
+            try {
+                const actual = response.request.spec;
+                const envelope = (0, envelopes_1.decodeEvmQueryEnvelope)(actual.query);
+                const [target, calldata] = (0, viem_1.decodeAbiParameters)([{ type: 'address' }, { type: 'bytes' }], envelope.payload);
+                matched =
+                    response.requestId.toLowerCase() === id.toLowerCase() &&
+                        actual.account.chainNamespace === read.chainNamespace &&
+                        actual.account.chainId === read.chainId &&
+                        actual.minConfirmations >= read.minConfirmations &&
+                        envelope.queryType === 1 &&
+                        envelope.refType === 0 &&
+                        envelope.blockNumber === actual.blockNumber &&
+                        (0, viem_1.getAddress)(target) === (0, viem_1.getAddress)(read.target) &&
+                        calldata.toLowerCase() ===
+                            (read.selector + read.args.slice(2)).toLowerCase();
+            }
+            catch {
+                /* A request from another schema/query cannot stand in for this logical read. */
+            }
+            if (!matched)
+                throw new errors_1.JobSpecError('PREVIEW_REQUEST_MISMATCH', 'The recorded request does not match this resolved JobSpec read.', { read: i, requestId: id });
+            responses.push(response);
+        }
+        quoted = responses.reduce((sum, response) => sum + response.fees.paid, BigInt(0));
+    }
+    else {
+        const prepared = [];
+        for (const read of spec.reads) {
+            const readOptions = {
+                chain: `${read.chainNamespace}:${read.chainId}`,
+                callData: (read.selector + read.args.slice(2)),
+                minConfirmations: read.minConfirmations,
+                expiryBlocks: options.expiryBlocks,
+                refundTo: options.refundTo,
+                callback: options.callback,
+            };
+            prepared.push(await options.client.universal.prepareRead(read.target, readOptions));
+        }
+        quoted = prepared.reduce((sum, read) => sum + read.value, BigInt(0));
+        if (options.maxTotalFee !== undefined && quoted > options.maxTotalFee)
+            throw new errors_1.JobSpecError('PREVIEW_FEE_EXCEEDED', 'The prepared read fees exceed maxTotalFee. No read was submitted.', { quoted, maxTotalFee: options.maxTotalFee });
+        let batch;
+        try {
+            batch = await options.client.universal.executeReads(prepared, {
+                progressHook: options.progressHook,
+                advanced: options.advanced,
+                waitForCompletion: false,
+            });
+        }
+        catch (cause) {
+            const error = cause;
+            throw new errors_1.JobSpecError('PREVIEW_INCOMPLETE', 'Read submission could not be confirmed. Track the recorded transactions before requesting more reads.', {
+                txHash: error?.txHash,
+                transactionHashes: error?.transactionHashes,
+                pendingTransactionHash: error?.pendingTransactionHash,
+            }, cause);
+        }
+        responses = batch.reads;
+        newlyPaid = quoted;
+    }
+    const requestIds = responses.map((r) => r.requestId);
+    try {
+        responses = await Promise.all(responses.map((r) => r.wait(waitOptions)));
+    }
+    catch (cause) {
+        throw new errors_1.JobSpecError('PREVIEW_INCOMPLETE', 'The paid reads are still recoverable. Resume with these request IDs instead of paying again.', { requestIds, txHashes: responses.map((r) => r.txHash) }, cause);
+    }
+    const reads = responses.map((response, i) => {
+        const value = response.raw?.resultData ?? null;
+        if (response.outcome !== read_state_types_1.READ_OUTCOME.SUCCESS || value === null)
+            return {
+                value,
+                decoded: null,
+                error: response.errorMsg || 'The paid read did not complete successfully.',
+                response,
+            };
+        try {
+            return {
+                value,
+                decoded: decodeJobAnswer(spec.reads[i], value),
+                response,
+            };
+        }
+        catch (e) {
+            return { value, decoded: null, error: e.message, response };
+        }
+    });
+    const checks = spec.checks.map((check) => {
+        let value = reads[check.read].decoded;
+        if (value === null)
+            return { pass: null, value, reason: 'READ_UNAVAILABLE' };
+        if (check.evaluation === 'NUMBER' || check.evaluation === 'PERCENTAGE') {
+            const before = options.baseline?.[check.read];
+            if (before === undefined || before === null)
+                return { pass: null, value: null, reason: 'BASELINE_REQUIRED' };
+            if (check.evaluation === 'PERCENTAGE' && before === BigInt(0))
+                return { pass: null, value: null, reason: 'ZERO_BASELINE' };
+            try {
+                value = (0, codec_1.int256)(value - before);
+                if (check.evaluation === 'PERCENTAGE')
+                    value = (0, codec_1.int256)(value * BigInt(10000)) / before;
+            }
+            catch {
+                return { pass: null, value: null, reason: 'ARITHMETIC_OVERFLOW' };
+            }
+        }
+        return { pass: compare(value, check.operation, check.target), value };
+    });
+    return {
+        reads,
+        checks,
+        pass: combine(spec.logic, checks),
+        fees: {
+            quoted,
+            paid: reads.reduce((sum, r) => sum + r.response.fees.paid, BigInt(0)),
+            newlyPaid,
+        },
+    };
+}
+//# sourceMappingURL=preview.js.map

package/src/lib/job-spec/read.d.ts

@@ -0,0 +1,20 @@
+import { type AbiParameter, type Hex } from 'viem';
+import type { PrepareJobReadOptions, PreparedJobRead, ExecuteJobReadOptions } from './types';
+import type { ReadOptions } from '../read-state/read-params';
+export declare function inheritReadLabel(source: PreparedJobRead, target: PreparedJobRead): void;
+export declare function jobReadLabel(read: PreparedJobRead): string | undefined;
+/** Same logical call as a JobSpec read, through the normal paid universal-read path. */
+export declare function jobReadOptions(read: PreparedJobRead, options?: ExecuteJobReadOptions): ReadOptions;
+export declare function outputTypes(params: readonly AbiParameter[]): Hex;
+/** Pure ABI preparation, independent of read fees, RPCs and the request preflight. */
+export declare function prepareJobRead(options: PrepareJobReadOptions): PreparedJobRead;
+export interface OutputNode {
+    code: number;
+    children: OutputNode[];
+    size?: number;
+}
+export declare function parseOutputs(outputs: Hex): OutputNode;
+export declare function validateJobRead(r: PreparedJobRead & {
+    field?: number[];
+    minConfirmations?: number;
+}): void;

package/src/lib/job-spec/read.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inheritReadLabel = inheritReadLabel;
+exports.jobReadLabel = jobReadLabel;
+exports.jobReadOptions = jobReadOptions;
+exports.outputTypes = outputTypes;
+exports.prepareJobRead = prepareJobRead;
+exports.parseOutputs = parseOutputs;
+exports.validateJobRead = validateJobRead;
+const viem_1 = require("viem");
+const abi_layout_1 = require("../agentic/codec/abi-layout");
+const errors_1 = require("../market/errors");
+const labels = new WeakMap();
+function inheritReadLabel(source, target) {
+    const value = labels.get(source);
+    if (value &&
+        value.selector === source.selector &&
+        value.outputs === source.outputs &&
+        value.target === source.target.toLowerCase())
+        labels.set(target, value);
+}
+function jobReadLabel(read) {
+    const value = labels.get(read);
+    return value &&
+        value.selector === read.selector &&
+        value.outputs === read.outputs &&
+        value.target === read.target.toLowerCase()
+        ? value.name
+        : undefined;
+}
+/** Same logical call as a JobSpec read, through the normal paid universal-read path. */
+function jobReadOptions(read, options = {}) {
+    validateJobRead(read);
+    if (read.fills?.length)
+        throw new errors_1.JobSpecError('UNFILLED_PLACEHOLDER', 'Resolve WALLET/PARAM holes before sending a prepared read.');
+    return {
+        ...options,
+        chain: `${read.chainNamespace}:${read.chainId}`,
+        callData: (read.selector + read.args.slice(2)),
+    };
+}
+function outputTypes(params) {
+    function type(p, depth) {
+        if (depth > 16)
+            throw new errors_1.JobSpecError('INVALID_READ', 'Output type nesting exceeds 16.');
+        const a = /^(.*)\[(\d*)\]$/.exec(p.type);
+        if (a) {
+            const base = { ...p, type: a[1] };
+            if (!a[2])
+                return [9, ...type(base, depth + 1)];
+            const n = Number(a[2]);
+            if (n < 1 || n > 255)
+                throw new errors_1.JobSpecError('INVALID_READ', 'Fixed output arrays must contain 1..255 elements.');
+            return [10, n, ...type(base, depth + 1)];
+        }
+        if (p.type === 'tuple')
+            return tuple(p.components, depth + 1);
+        if (/^uint(\d+)?$/.test(p.type))
+            return [1];
+        if (/^int(\d+)?$/.test(p.type))
+            return [2];
+        if (p.type === 'bool')
+            return [3];
+        if (p.type === 'address')
+            return [4];
+        if (/^bytes([1-9]|[12]\d|3[0-2])$/.test(p.type))
+            return [5];
+        if (p.type === 'bytes')
+            return [6];
+        if (p.type === 'string')
+            return [7];
+        throw new errors_1.JobSpecError('INVALID_READ', `Unsupported ABI output ${p.type}.`);
+    }
+    function tuple(items, depth) {
+        if (items.length < 1 || items.length > 255)
+            throw new errors_1.JobSpecError('INVALID_READ', 'An output tuple needs 1..255 fields.');
+        return [8, items.length, ...items.flatMap((p) => type(p, depth))];
+    }
+    return ('0x' +
+        tuple(params, 0)
+            .map((x) => x.toString(16).padStart(2, '0'))
+            .join(''));
+}
+/** Pure ABI preparation, independent of read fees, RPCs and the request preflight. */
+function prepareJobRead(options) {
+    try {
+        if (!/^eip155:[1-9]\d*$/.test(options.chain))
+            throw new errors_1.JobSpecError('CHAIN_UNSUPPORTED', 'JobSpec reads currently support EVM chain identifiers only.');
+        const candidates = options.abi.filter((x) => x.type === 'function' &&
+            x.name === options.functionName &&
+            x.inputs.length === (options.args?.length ?? 0));
+        if (candidates.length !== 1)
+            throw new errors_1.JobSpecError('INVALID_READ', 'Select one exact function ABI for this read, including overloaded functions.');
+        const fn = candidates[0];
+        if (!['view', 'pure'].includes(fn.stateMutability))
+            throw new errors_1.JobSpecError('INVALID_READ', 'A JobSpec read must use a view or pure function.');
+        const fills = [];
+        const lower = (p, value, indices, depth) => {
+            if (depth > 16)
+                throw new errors_1.JobSpecError('INVALID_READ', 'Read arguments are nested too deeply.');
+            const marker = value === 'agentic:wallet';
+            const param = value && typeof value === 'object' && 'param' in value
+                ? value.param
+                : undefined;
+            if (marker || param !== undefined) {
+                if (marker && p.type !== 'address')
+                    throw new errors_1.JobSpecError('INVALID_READ', 'WALLET read arguments must be addresses.');
+                if (!marker && !/^u?int(\d+)?$/.test(p.type))
+                    throw new errors_1.JobSpecError('INVALID_READ', 'PARAM read arguments must be static integers.');
+                if (!marker &&
+                    (!Number.isInteger(param) || Number(param) < 0 || Number(param) > 255))
+                    throw new errors_1.JobSpecError('INVALID_READ', 'Invalid template parameter index.');
+                const word = ((0, abi_layout_1.argumentLocation)(fn.inputs, indices, 'Read placeholder').offset -
+                    4) /
+                    32;
+                if (word > 255)
+                    throw new errors_1.JobSpecError('INVALID_READ', 'Read placeholder is outside the uint8 word range.');
+                fills.push({
+                    word,
+                    source: marker ? 'WALLET' : 'PARAM',
+                    ...(!marker ? { param: Number(param) } : {}),
+                });
+                return marker ? viem_1.zeroAddress : BigInt(0);
+            }
+            const a = /^(.*)\[(\d*)\]$/.exec(p.type);
+            if (a) {
+                if (!Array.isArray(value))
+                    throw new errors_1.JobSpecError('INVALID_READ', 'Array argument must be an array.');
+                return value.map((v, i) => lower({ ...p, type: a[1] }, v, [...indices, i], depth + 1));
+            }
+            if (p.type === 'tuple') {
+                const fields = p
+                    .components;
+                return fields.map((field, i) => lower(field, Array.isArray(value)
+                    ? value[i]
+                    : value?.[field.name ?? ''], [...indices, i], depth + 1));
+            }
+            return value;
+        };
+        const values = fn.inputs.map((p, i) => lower(p, options.args?.[i], [i], 0));
+        const [chainNamespace, chainId] = options.chain.split(':');
+        const prepared = {
+            chainNamespace,
+            chainId,
+            target: (0, viem_1.getAddress)(options.target),
+            selector: (0, viem_1.toFunctionSelector)(fn),
+            args: (0, viem_1.encodeAbiParameters)(fn.inputs, values),
+            outputs: outputTypes(fn.outputs),
+            ...(fills.length ? { fills } : {}),
+        };
+        labels.set(prepared, {
+            selector: prepared.selector,
+            outputs: prepared.outputs,
+            target: prepared.target.toLowerCase(),
+            name: fn.name,
+            parameters: fn.outputs,
+        });
+        return prepared;
+    }
+    catch (cause) {
+        if (cause instanceof errors_1.JobSpecError)
+            throw cause;
+        throw new errors_1.JobSpecError('INVALID_READ', 'The read arguments or ABI are invalid.', undefined, cause);
+    }
+}
+function parseOutputs(outputs) {
+    if (!(0, viem_1.isHex)(outputs) || outputs.length % 2 !== 0 || outputs.length > 8194)
+        throw new errors_1.JobSpecError('INVALID_READ', 'Invalid output type layout.');
+    const bytes = outputs
+        .slice(2)
+        .match(/../g)
+        ?.map((x) => parseInt(x, 16)) ?? [];
+    let pos = 0;
+    function read(depth) {
+        if (depth > 16 || pos >= bytes.length)
+            throw new errors_1.JobSpecError('INVALID_READ', 'Invalid output type layout.');
+        const code = bytes[pos++];
+        const n = { code, children: [] };
+        if (code === 8 || code === 10) {
+            n.size = bytes[pos++];
+            if (!n.size)
+                throw new errors_1.JobSpecError('INVALID_READ', 'An output tuple/array cannot be empty.');
+            if (code === 8)
+                for (let i = 0; i < n.size; i++)
+                    n.children.push(read(depth + 1));
+            else
+                n.children.push(read(depth + 1));
+        }
+        else if (code === 9)
+            n.children.push(read(depth + 1));
+        else if (code < 1 || code > 7)
+            throw new errors_1.JobSpecError('INVALID_READ', 'Unknown output type code.');
+        return n;
+    }
+    const root = read(0);
+    if (root.code !== 8 || pos !== bytes.length)
+        throw new errors_1.JobSpecError('INVALID_READ', 'Outputs must encode exactly one root tuple.');
+    return root;
+}
+function validateJobRead(r) {
+    if (r.chainNamespace !== 'eip155' ||
+        !/^[1-9]\d*$/.test(r.chainId) ||
+        !(0, viem_1.isAddress)(r.target) ||
+        !/^0x[\da-f]{8}$/i.test(r.selector) ||
+        !(0, viem_1.isHex)(r.args) ||
+        r.args.length % 2)
+        throw new errors_1.JobSpecError('INVALID_READ', 'Invalid EVM JobSpec read.');
+    let node = parseOutputs(r.outputs);
+    const field = r.field ?? [0];
+    if (field.length < 1 || field.length > 16)
+        throw new errors_1.JobSpecError('INVALID_READ', 'Output field path must have 1..16 indexes.');
+    for (const i of field) {
+        if (!Number.isInteger(i) ||
+            i < 0 ||
+            i > 255 ||
+            ![8, 9, 10].includes(node.code) ||
+            (node.code !== 9 && i >= (node.size ?? 0)))
+            throw new errors_1.JobSpecError('INVALID_READ', 'Output field path does not resolve.');
+        node = node.children[node.code === 8 ? i : 0];
+    }
+    if ([8, 10].includes(node.code))
+        throw new errors_1.JobSpecError('INVALID_READ', 'Choose a scalar or dynamic-length output field.');
+}
+//# sourceMappingURL=read.js.map