@chainlink/cre-sdk 0.0.0 → 0.0.1-alpha

package/dist/sdk/utils/config/index.js

@@ -0,0 +1,46 @@
+import { getRequest } from '../get-request';
+export const getConfigFromExecuteRequest = (executeRequest) => {
+    const config = executeRequest.config;
+    const configString = Buffer.from(config).toString();
+    try {
+        return JSON.parse(configString);
+    }
+    catch (e) {
+        if (typeof configString === 'string') {
+            return configString;
+        }
+        if (e instanceof Error) {
+            console.error(e.message);
+            console.error(e.stack);
+        }
+        throw e;
+    }
+};
+export const getConfig = () => {
+    const executeRequest = getRequest();
+    return getConfigFromExecuteRequest(executeRequest);
+};
+const standardValidate = async (schema, input) => {
+    let result = schema['~standard'].validate(input);
+    if (result instanceof Promise)
+        result = await result;
+    /**
+     * If the `issues` field exists, the validation failed
+     * @see https://github.com/standard-schema/standard-schema?tab=readme-ov-file#how-do-i-accept-standard-schemas-in-my-library
+     */
+    if (result.issues) {
+        throw new Error(JSON.stringify(result.issues, null, 2));
+    }
+    return result.value;
+};
+export const configHandler = async ({ configParser, configSchema, } = {}) => {
+    const config = getConfig();
+    let parsedConfig = config;
+    if (configParser) {
+        parsedConfig = configParser(config);
+    }
+    if (configSchema) {
+        parsedConfig = await standardValidate(configSchema, parsedConfig);
+    }
+    return parsedConfig;
+};

package/dist/sdk/utils/do-request-async.d.ts

@@ -0,0 +1,12 @@
+import { type Mode } from '../../generated/sdk/v1alpha/sdk_pb';
+type Params = {
+    capabilityId: string;
+    method: string;
+    mode: Mode;
+    payload: {
+        typeUrl: string;
+        value: Uint8Array;
+    };
+};
+export declare const doRequestAsync: ({ capabilityId, method, mode, payload }: Params) => number;
+export {};

package/dist/sdk/utils/do-request-async.js

@@ -0,0 +1,17 @@
+import { create, toBinary } from '@bufbuild/protobuf';
+import { CapabilityRequestSchema, } from '../../generated/sdk/v1alpha/sdk_pb';
+import { hostBindings } from '../runtime/host-bindings';
+import { getLastCallbackId, incrementCallbackId } from './capabilities/callback-id';
+export const doRequestAsync = ({ capabilityId, method, mode, payload }) => {
+    const callbackId = getLastCallbackId(mode);
+    incrementCallbackId(mode);
+    const req = create(CapabilityRequestSchema, {
+        id: capabilityId,
+        method,
+        payload,
+        callbackId,
+    });
+    const reqBytes = toBinary(CapabilityRequestSchema, req);
+    hostBindings.callCapability(reqBytes);
+    return callbackId;
+};

package/dist/sdk/utils/error-boundary.d.ts

@@ -0,0 +1,2 @@
+export declare const errorBoundary: (e: any) => void;
+export declare const withErrorBoundary: (fn: () => Promise<void>) => Promise<void>;

package/dist/sdk/utils/error-boundary.js

@@ -0,0 +1,30 @@
+import { DonModeError, NodeModeError } from '../runtime/errors';
+export const errorBoundary = (e) => {
+    // TODO: links should be configurable
+    if (e instanceof DonModeError || e instanceof NodeModeError) {
+        console.log(`
+
+
+[${e.constructor.name}]: ${e.message}.
+
+Learn more about mode switching here: https://documentation-preview-git-cre-priv-577744-chainlink-labs-devrel.vercel.app/cre/getting-started/part-2-fetching-data#step-2-understand-the-runinnodemode-pattern
+
+
+`);
+    }
+    else if (e instanceof Error) {
+        console.log(e.message);
+        console.log(e.stack);
+    }
+    else {
+        console.log(e);
+    }
+};
+export const withErrorBoundary = async (fn) => {
+    try {
+        await fn();
+    }
+    catch (e) {
+        errorBoundary(e);
+    }
+};

package/dist/sdk/utils/get-request.d.ts

@@ -0,0 +1 @@
+export declare const getRequest: () => import("../../generated/sdk/v1alpha/sdk_pb").ExecuteRequest;

package/dist/sdk/utils/get-request.js

@@ -0,0 +1,15 @@
+import { fromBinary } from '@bufbuild/protobuf';
+import { ExecuteRequestSchema } from '../../generated/sdk/v1alpha/sdk_pb';
+export const getRequest = () => {
+    const argsString = getWasiArgs();
+    const args = JSON.parse(argsString);
+    // SDK expects exactly 2 args:
+    // 1st is the script name
+    // 2nd is the base64 encoded request
+    if (args.length !== 2) {
+        throw new Error('Invalid request: must contain payload');
+    }
+    const base64Request = args[1];
+    const bytes = Buffer.from(base64Request, 'base64');
+    return fromBinary(ExecuteRequestSchema, bytes);
+};

package/dist/sdk/utils/hex-utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Hex conversion utilities for blockchain data
+ *
+ * Note: BigInt utilities are available in ../utils
+ * Use val.bigint() or bigIntToProtoBigInt() for BigInt conversions
+ */
+import type { Hex } from 'viem';
+/**
+ * Convert hex string to Uint8Array
+ */
+export declare const hexToBytes: (hexStr: string) => Uint8Array;
+/**
+ * Convert Uint8Array to hex string with 0x prefix
+ */
+export declare const bytesToHex: (bytes: Uint8Array) => Hex;
+/**
+ * Encode hex as base64 string
+ * @param hex
+ * @returns
+ */
+export declare const hexToBase64: (hex: string) => string;

package/dist/sdk/utils/hex-utils.js

@@ -0,0 +1,31 @@
+/**
+ * Convert hex string to Uint8Array
+ */
+export const hexToBytes = (hexStr) => {
+    if (!hexStr.startsWith('0x')) {
+        throw new Error(`Invalid hex string: ${hexStr}`);
+    }
+    const hex = hexStr.slice(2);
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = Number.parseInt(hex.substr(i, 2), 16);
+    }
+    return bytes;
+};
+/**
+ * Convert Uint8Array to hex string with 0x prefix
+ */
+export const bytesToHex = (bytes) => {
+    return `0x${Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('')}`;
+};
+/**
+ * Encode hex as base64 string
+ * @param hex
+ * @returns
+ */
+export const hexToBase64 = (hex) => {
+    const cleanHex = hex.startsWith('0x') ? hex.slice(2) : hex;
+    return Buffer.from(cleanHex, 'hex').toString('base64');
+};

package/dist/sdk/utils/index.d.ts

@@ -0,0 +1,7 @@
+export * from './error-boundary';
+export { withErrorBoundary } from './error-boundary';
+export * from './hex-utils';
+export * from './send-response-value';
+export * from './values/consensus_aggregators';
+export * from './values/serializer_types';
+export * from './values/value';

package/dist/sdk/utils/index.js

@@ -0,0 +1,7 @@
+export * from './error-boundary';
+export { withErrorBoundary } from './error-boundary';
+export * from './hex-utils';
+export * from './send-response-value';
+export * from './values/consensus_aggregators';
+export * from './values/serializer_types';
+export * from './values/value';

package/dist/sdk/utils/lazy-promise.d.ts

@@ -0,0 +1,59 @@
+/**
+ * LazyPromise is a utility class that implements the Promise interface
+ * but defers execution of the actual work until the promise is first accessed.
+ *
+ * This is useful when you want to return a promise immediately without
+ * starting the async work, but ensure the work begins as soon as someone
+ * tries to await, .then(), .catch(), or .finally() the promise.
+ *
+ * Example usage:
+ * ```typescript
+ * const lazyPromise = new LazyPromise(() => {
+ *   // This expensive operation won't start until the promise is accessed
+ *   return fetch('/api/data');
+ * });
+ *
+ * // Promise is returned immediately, no work done yet
+ * // Work starts when you await it:
+ * const result = await lazyPromise;
+ * ```
+ *
+ * This abstraction has been created for calling capabilities in a non-blocking way.
+ */
+export declare class LazyPromise<T> implements Promise<T> {
+    private readonly factory;
+    /** Tracks whether the factory function has been executed */
+    private started;
+    /** The actual promise that gets created when work starts */
+    private promise;
+    /**
+     * Creates a new LazyPromise
+     * @param factory - Function that returns the value or promise to resolve with
+     */
+    constructor(factory: () => T | Promise<T>);
+    /**
+     * Ensures the factory function has been executed and the promise is created.
+     * This is called by all promise methods (.then, .catch, .finally) to start the work.
+     */
+    private ensureStarted;
+    /**
+     * Attaches callbacks for the resolution and/or rejection of the Promise.
+     * This triggers the lazy execution if it hasn't started yet.
+     */
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    /**
+     * Attaches a callback for only the rejection of the Promise.
+     * This triggers the lazy execution if it hasn't started yet.
+     */
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<T | TResult>;
+    /**
+     * Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected).
+     * This triggers the lazy execution if it hasn't started yet.
+     */
+    finally(onfinally?: (() => void) | null): Promise<T>;
+    /**
+     * Required to make this behave like a native Promise.
+     * This allows instanceof checks and proper string representation.
+     */
+    [Symbol.toStringTag]: string;
+}

package/dist/sdk/utils/lazy-promise.js

@@ -0,0 +1,81 @@
+/**
+ * LazyPromise is a utility class that implements the Promise interface
+ * but defers execution of the actual work until the promise is first accessed.
+ *
+ * This is useful when you want to return a promise immediately without
+ * starting the async work, but ensure the work begins as soon as someone
+ * tries to await, .then(), .catch(), or .finally() the promise.
+ *
+ * Example usage:
+ * ```typescript
+ * const lazyPromise = new LazyPromise(() => {
+ *   // This expensive operation won't start until the promise is accessed
+ *   return fetch('/api/data');
+ * });
+ *
+ * // Promise is returned immediately, no work done yet
+ * // Work starts when you await it:
+ * const result = await lazyPromise;
+ * ```
+ *
+ * This abstraction has been created for calling capabilities in a non-blocking way.
+ */
+export class LazyPromise {
+    factory;
+    /** Tracks whether the factory function has been executed */
+    started = false;
+    /** The actual promise that gets created when work starts */
+    promise;
+    /**
+     * Creates a new LazyPromise
+     * @param factory - Function that returns the value or promise to resolve with
+     */
+    constructor(factory) {
+        this.factory = factory;
+    }
+    /**
+     * Ensures the factory function has been executed and the promise is created.
+     * This is called by all promise methods (.then, .catch, .finally) to start the work.
+     */
+    ensureStarted() {
+        if (!this.started) {
+            this.started = true;
+            try {
+                const result = this.factory();
+                this.promise = Promise.resolve(result);
+            }
+            catch (err) {
+                this.promise = Promise.reject(err);
+            }
+        }
+    }
+    /**
+     * Attaches callbacks for the resolution and/or rejection of the Promise.
+     * This triggers the lazy execution if it hasn't started yet.
+     */
+    then(onfulfilled, onrejected) {
+        this.ensureStarted();
+        return this.promise.then(onfulfilled, onrejected);
+    }
+    /**
+     * Attaches a callback for only the rejection of the Promise.
+     * This triggers the lazy execution if it hasn't started yet.
+     */
+    catch(onrejected) {
+        this.ensureStarted();
+        return this.promise.catch(onrejected);
+    }
+    /**
+     * Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected).
+     * This triggers the lazy execution if it hasn't started yet.
+     */
+    finally(onfinally) {
+        this.ensureStarted();
+        return this.promise.finally(onfinally);
+    }
+    /**
+     * Required to make this behave like a native Promise.
+     * This allows instanceof checks and proper string representation.
+     */
+    [Symbol.toStringTag] = 'Promise';
+}

package/dist/sdk/utils/prepare-runtime.d.ts

@@ -0,0 +1,6 @@
+/**
+ * This function is used to prepare the runtime for the SDK to work.
+ * It should be called as a part of SDK initialization.
+ * It exposes NodeJS Buffer in global namespace, so it can be bundled and used in workflow code.
+ */
+export declare const prepareRuntime: () => void;

package/dist/sdk/utils/prepare-runtime.js

@@ -0,0 +1,9 @@
+import { Buffer } from 'node:buffer';
+/**
+ * This function is used to prepare the runtime for the SDK to work.
+ * It should be called as a part of SDK initialization.
+ * It exposes NodeJS Buffer in global namespace, so it can be bundled and used in workflow code.
+ */
+export const prepareRuntime = () => {
+    globalThis.Buffer = Buffer;
+};

package/dist/sdk/utils/random/get-rand.d.ts

@@ -0,0 +1,3 @@
+import type { Mode } from '../../../generated/sdk/v1alpha/sdk_pb';
+import { Rand } from './random';
+export declare const getRand: (mode: Mode.DON | Mode.NODE) => Rand;

package/dist/sdk/utils/random/get-rand.js

@@ -0,0 +1,6 @@
+import { hostBindings } from '../../runtime/host-bindings';
+import { Rand } from './random';
+export const getRand = (mode) => {
+    const seed = BigInt(hostBindings.randomSeed(mode));
+    return new Rand(seed);
+};

package/dist/sdk/utils/random/random.d.ts

@@ -0,0 +1,35 @@
+export declare class Source {
+    private s0;
+    private s1;
+    constructor(seed: bigint);
+    Seed(seed: bigint): void;
+    private splitMix64;
+    private next;
+    Int63(): bigint;
+    Uint32(): number;
+    Uint64(): bigint;
+    Int31(): number;
+    Float64(): number;
+    Int63n(n: bigint): bigint;
+    Int31n(n: number): number;
+    Intn(n: number): number;
+    Int(): number;
+    Float32(): number;
+    Perm(n: number): number[];
+}
+export declare class Rand {
+    private src;
+    constructor(seed: bigint);
+    Float64(): number;
+    Float32(): number;
+    Int63(): bigint;
+    Int63n(n: bigint): bigint;
+    Int31(): number;
+    Int31n(n: number): number;
+    Int(): number;
+    Intn(n: number): number;
+    Uint32(): number;
+    Uint64(): bigint;
+    Perm(n: number): number[];
+    Seed(seed: bigint): void;
+}

package/dist/sdk/utils/random/random.js

@@ -0,0 +1,123 @@
+// Full TypeScript port of Go's math/rand
+// Complete API: Int63, Uint64, Uint32, Int31, Int, Float64, Float32, Int63n, Int31n, Intn, Perm, Seed
+// See: https://cs.opensource.google/go/go/+/refs/tags/go1.22.0:src/math/rand/rand.go
+export class Source {
+    s0 = 0n;
+    s1 = 0n;
+    constructor(seed) {
+        this.Seed(seed);
+    }
+    Seed(seed) {
+        seed = BigInt.asUintN(64, seed);
+        this.s0 = this.splitMix64(seed);
+        this.s1 = this.splitMix64(this.s0);
+    }
+    splitMix64(seed) {
+        seed = (seed + 0x9e3779b97f4a7c15n) & 0xffffffffffffffffn;
+        let z = seed;
+        z = ((z ^ (z >> 30n)) * 0xbf58476d1ce4e5b9n) & 0xffffffffffffffffn;
+        z = ((z ^ (z >> 27n)) * 0x94d049bb133111ebn) & 0xffffffffffffffffn;
+        return z ^ (z >> 31n);
+    }
+    next() {
+        const s1 = this.s0;
+        let s0 = this.s1;
+        this.s0 = s0;
+        s0 ^= s0 << 23n;
+        this.s1 = s0 ^ s1 ^ (s0 >> 17n) ^ (s1 >> 26n);
+        return BigInt.asUintN(64, this.s1 + s1);
+    }
+    Int63() {
+        return this.next() & 0x7fffffffffffffffn;
+    }
+    Uint32() {
+        return Number(this.next() >> 32n) >>> 0;
+    }
+    Uint64() {
+        return this.next();
+    }
+    Int31() {
+        return Number(this.Int63() >> 32n);
+    }
+    Float64() {
+        // Use top 53 bits like Go's implementation: Int63() >> 11
+        return Number(this.Int63() >> 11n) * (1.0 / 9007199254740992.0); // 1.0 / (1 << 53)
+    }
+    Int63n(n) {
+        if (n <= 0n)
+            throw new Error('invalid argument to Int63n');
+        const max = (1n << 63n) - ((1n << 63n) % n);
+        let v;
+        do {
+            v = this.Int63();
+        } while (v >= max);
+        return v % n;
+    }
+    Int31n(n) {
+        if (n <= 0)
+            throw new Error('invalid argument to Int31n');
+        return Number(this.Int63n(BigInt(n)));
+    }
+    Intn(n) {
+        return this.Int31n(n);
+    }
+    Int() {
+        return Number(this.Int63() >> 32n);
+    }
+    Float32() {
+        // Use top 24 bits for float32 precision
+        return Number(this.Int63() >> 40n) * (1.0 / 8388608.0); // 1.0 / (1 << 23)
+    }
+    Perm(n) {
+        const m = new Array(n);
+        for (let i = 0; i < n; i++)
+            m[i] = i;
+        for (let i = 1; i < n; i++) {
+            const j = Number(this.Int63n(BigInt(i + 1)));
+            [m[i], m[j]] = [m[j], m[i]];
+        }
+        return m;
+    }
+}
+export class Rand {
+    src;
+    constructor(seed) {
+        this.src = new Source(seed);
+    }
+    Float64() {
+        return this.src.Float64();
+    }
+    Float32() {
+        return this.src.Float32();
+    }
+    Int63() {
+        return this.src.Int63();
+    }
+    Int63n(n) {
+        return this.src.Int63n(n);
+    }
+    Int31() {
+        return this.src.Int31();
+    }
+    Int31n(n) {
+        return this.src.Int31n(n);
+    }
+    Int() {
+        return this.src.Int();
+    }
+    Intn(n) {
+        return this.src.Intn(n);
+    }
+    Uint32() {
+        return this.src.Uint32();
+    }
+    Uint64() {
+        return this.src.Uint64();
+    }
+    Perm(n) {
+        return this.src.Perm(n);
+    }
+    Seed(seed) {
+        this.src.Seed(seed);
+    }
+}

package/dist/sdk/utils/safeJsonStringify.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Supports stringifying an object with bigints, treating bigints as strings.
+ * @param obj - The object to stringify
+ * @returns The stringified object
+ */
+export declare const safeJsonStringify: (obj: any) => string;

package/dist/sdk/utils/safeJsonStringify.js

@@ -0,0 +1,6 @@
+/**
+ * Supports stringifying an object with bigints, treating bigints as strings.
+ * @param obj - The object to stringify
+ * @returns The stringified object
+ */
+export const safeJsonStringify = (obj) => JSON.stringify(obj, (_, value) => (typeof value === 'bigint' ? value.toString() : value), 2);

package/dist/sdk/utils/secrets/await-async-secret.d.ts

@@ -0,0 +1 @@
+export declare const awaitAsyncSecret: (callbackId: number) => Promise<string>;

package/dist/sdk/utils/secrets/await-async-secret.js

@@ -0,0 +1,29 @@
+import { create, fromBinary, toBinary } from '@bufbuild/protobuf';
+import { AwaitSecretsRequestSchema, AwaitSecretsResponseSchema, } from '../../../generated/sdk/v1alpha/sdk_pb';
+import { SecretsError } from '../secrets-error';
+export const awaitAsyncSecret = async (callbackId) => {
+    // Create proper AwaitSecretsRequest protobuf message
+    const awaitSecretRequest = create(AwaitSecretsRequestSchema, {
+        ids: [callbackId],
+    });
+    // Encode to protobuf bytes
+    const awaitSecretRequestBytes = toBinary(AwaitSecretsRequestSchema, awaitSecretRequest);
+    const response = awaitSecrets(awaitSecretRequestBytes, 1024 * 1024);
+    // Convert array of numbers to Uint8Array if needed
+    const responseBytes = Array.isArray(response) ? new Uint8Array(response) : response;
+    // Decode as AwaitSecretsResponse first
+    const awaitResponse = fromBinary(AwaitSecretsResponseSchema, responseBytes);
+    // Get the specific secretId response for our callback ID
+    const secretResponses = awaitResponse.responses[callbackId];
+    if (!secretResponses || !secretResponses.responses.length) {
+        throw new Error(`No response found for callback ID ${callbackId}`);
+    }
+    const secretResponse = secretResponses.responses[0];
+    if (secretResponse.response.case === 'secret') {
+        return secretResponse.response.value.value;
+    }
+    if (secretResponse.response.case === 'error') {
+        throw new SecretsError(secretResponse.response.value.error);
+    }
+    throw new Error(`No secret found for callback ID ${callbackId}`);
+};

package/dist/sdk/utils/secrets/do-get-secret.d.ts

@@ -0,0 +1 @@
+export declare const doGetSecret: (id: string) => number;

package/dist/sdk/utils/secrets/do-get-secret.js

@@ -0,0 +1,14 @@
+import { create, toBinary } from '@bufbuild/protobuf';
+import { GetSecretsRequestSchema, Mode } from '../../../generated/sdk/v1alpha/sdk_pb';
+import { hostBindings } from '../../runtime/host-bindings';
+import { getLastCallbackId, incrementCallbackId } from '../capabilities/callback-id';
+export const doGetSecret = (id) => {
+    const callbackId = getLastCallbackId(Mode.DON);
+    incrementCallbackId(Mode.DON);
+    const request = create(GetSecretsRequestSchema, {
+        requests: [{ id }],
+        callbackId,
+    });
+    const result = hostBindings.getSecrets(toBinary(GetSecretsRequestSchema, request), 1024 * 1024);
+    return callbackId;
+};

package/dist/sdk/utils/secrets/get-secret.d.ts

@@ -0,0 +1 @@
+export declare const getSecret: (id: string) => Promise<any>;

package/dist/sdk/utils/secrets/get-secret.js

@@ -0,0 +1,10 @@
+import { runtimeGuards } from '../../runtime/runtime';
+import { LazyPromise } from '../lazy-promise';
+import { awaitAsyncSecret } from './await-async-secret';
+import { doGetSecret } from './do-get-secret';
+export const getSecret = (id) => {
+    // Getting secrets should only be possible in DON mode
+    runtimeGuards.assertDonSafe();
+    const callbackId = doGetSecret(id);
+    return new LazyPromise(async () => awaitAsyncSecret(callbackId));
+};

package/dist/sdk/utils/secrets-error.d.ts

@@ -0,0 +1,3 @@
+export declare class SecretsError extends Error {
+    constructor(message: string);
+}

package/dist/sdk/utils/secrets-error.js

@@ -0,0 +1,6 @@
+export class SecretsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SecretsError';
+    }
+}

package/dist/sdk/utils/send-error.d.ts

@@ -0,0 +1 @@
+export declare const sendError: (error: string | Error) => void;

package/dist/sdk/utils/send-error.js

@@ -0,0 +1,16 @@
+import { create, toBinary } from '@bufbuild/protobuf';
+import { ExecutionResultSchema } from '../../generated/sdk/v1alpha/sdk_pb';
+import { hostBindings } from '../runtime/host-bindings';
+export const sendError = (error) => {
+    // Create ExecutionResult with error
+    const execResult = create(ExecutionResultSchema, {
+        result: {
+            case: 'error',
+            value: error instanceof Error ? error.message : error,
+        },
+    });
+    // Marshal to protobuf bytes
+    const encoded = toBinary(ExecutionResultSchema, execResult);
+    // Send the result
+    hostBindings.sendResponse(encoded);
+};

package/dist/sdk/utils/send-response-value.d.ts

@@ -0,0 +1,2 @@
+import type { Value } from './';
+export declare const sendResponseValue: (value: Value) => void;