@layerzerolabs/gated-transaction 0.0.8

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@layerzerolabs/gated-transaction",
+  "version": "0.0.8",
+  "private": false,
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    "types": "./dist/index.d.ts",
+    "require": "./dist/index.cjs",
+    "import": "./dist/index.js",
+    "default": "./dist/index.cjs"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "lodash.isequal": "^4.5.0",
+    "zod": "^3.23.8",
+    "@layerzerolabs/common-activities": "0.0.8",
+    "@layerzerolabs/common-chain-model": "0.0.8",
+    "@layerzerolabs/common-workflow": "0.0.8",
+    "@layerzerolabs/common-utils": "0.0.8",
+    "@layerzerolabs/zod-utils": "0.0.8"
+  },
+  "devDependencies": {
+    "@types/lodash.isequal": "^4.5.8",
+    "tsup": "^8.4.0",
+    "vitest": "^3.2.3",
+    "@layerzerolabs/tsup-configuration": "0.0.8",
+    "@layerzerolabs/typescript-configuration": "0.0.8"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf ./node_modules .turbo ./dist",
+    "dev": "tsup --watch",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix --max-warnings 0",
+    "test": "vitest --run --pass-with-no-tests"
+  }
+}

package/src/gatedTx.ts

@@ -0,0 +1,37 @@
+import type { Transaction } from '@layerzerolabs/common-chain-model';
+import type { FunctionPointer } from '@layerzerolabs/common-utils';
+
+import type { GatedTransaction, GatedTransactionId, OnChainDataComparison } from './types';
+
+/**
+ * Builds a {@link GatedTransaction}
+ */
+export const constructGatedTransaction = <
+    const Name extends string,
+    Tx extends Transaction,
+    Method extends (...args: any[]) => any,
+>(gtx: {
+    name: Name;
+    bundleName?: string;
+    transaction: Tx;
+    check: {
+        functionPointer: FunctionPointer<Method>;
+        params: Parameters<Method>;
+        expectedResult: OnChainDataComparison<Awaited<ReturnType<Method>>>;
+    };
+    uniqueIdKeys?: Record<string, string | number | boolean>;
+    cacheable?: boolean;
+    dependencies?: GatedTransaction[];
+}): GatedTransaction<Name, Tx, Method> => {
+    return gtx;
+};
+
+export const getIdForGatedTransaction = (gtx: GatedTransaction): GatedTransactionId => {
+    const serializedUniqueIdKeys = gtx.uniqueIdKeys
+        ? Object.entries(gtx.uniqueIdKeys)
+              .map(([k, v]) => `${k}:${v}`)
+              .join('-')
+        : '';
+
+    return `${gtx.name}-${gtx.transaction.chainName}-${serializedUniqueIdKeys}`;
+};

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './gatedTx';
+export * from './resolver';
+export * from './types';

package/src/resolver.ts

@@ -0,0 +1,311 @@
+import isEqual from 'lodash.isequal';
+
+import type { ActivityRegistry } from '@layerzerolabs/common-activities';
+import type { Transaction } from '@layerzerolabs/common-chain-model';
+import type { WorkflowFunctions } from '@layerzerolabs/common-workflow';
+
+import { getIdForGatedTransaction } from './gatedTx';
+import type {
+    GatedTransaction,
+    GatedTransactionId,
+    GatedTransactionResult,
+    IGatedTransactionCache,
+    InferOnChainDataTypeFromGatedTransaction,
+    UserInteractionCallbacks,
+} from './types';
+import { GatedTransactionStatus } from './types';
+
+type OnChainCheckResult<DataType = any> = {
+    expectationMet: boolean;
+    onChainData: DataType;
+};
+
+const checkGatedTransaction = async <GatedTx extends GatedTransaction>({
+    registry,
+    gatedTransaction,
+    cachedCheckResult,
+    processedTransaction,
+}: {
+    registry: ActivityRegistry;
+    gatedTransaction: GatedTx;
+    cachedCheckResult?: InferOnChainDataTypeFromGatedTransaction<GatedTx>;
+    processedTransaction?: any;
+}): Promise<OnChainCheckResult<InferOnChainDataTypeFromGatedTransaction<GatedTx>>> => {
+    let onChainData: InferOnChainDataTypeFromGatedTransaction<GatedTx>;
+    if (cachedCheckResult !== undefined) {
+        onChainData = cachedCheckResult;
+    } else {
+        // Always inject the processed transaction as the last parameter when available
+        let params = gatedTransaction.check.params;
+        if (processedTransaction !== undefined) {
+            params = [...gatedTransaction.check.params, processedTransaction];
+        }
+
+        onChainData = await registry.callByPointer(gatedTransaction.check.functionPointer, params);
+    }
+
+    let expectationMet: boolean;
+
+    switch (gatedTransaction.check.expectedResult.operator) {
+        case '=':
+            expectationMet = isEqual(
+                onChainData,
+                gatedTransaction.check.expectedResult.comparisonValue,
+            );
+            break;
+        case '!=':
+            expectationMet = !isEqual(
+                onChainData,
+                gatedTransaction.check.expectedResult.comparisonValue,
+            );
+            break;
+        case '>':
+            expectationMet =
+                (onChainData as number) >
+                (gatedTransaction.check.expectedResult.comparisonValue as number);
+            break;
+        case '>=':
+            expectationMet =
+                (onChainData as number) >=
+                (gatedTransaction.check.expectedResult.comparisonValue as number);
+            break;
+        case '<':
+            expectationMet =
+                (onChainData as number) <
+                (gatedTransaction.check.expectedResult.comparisonValue as number);
+            break;
+        case '<=':
+            expectationMet =
+                (onChainData as number) <=
+                (gatedTransaction.check.expectedResult.comparisonValue as number);
+            break;
+        default:
+            throw new Error(
+                `Gated transaction operator "${gatedTransaction.check.expectedResult.operator}" is not supported`,
+            );
+    }
+
+    return {
+        expectationMet,
+        onChainData,
+    };
+};
+
+const resolveGatedTransaction = async <
+    TxType extends Transaction,
+    ProcessedTxType extends Transaction,
+    GatedTx extends GatedTransaction<string, TxType, any>,
+    ProcessTx extends (transaction: TxType) => Promise<ProcessedTxType>,
+>({
+    activityRegistry,
+    gatedTx,
+    isTransactionSuccessful,
+    processTx,
+    confirmationCallback,
+    fn,
+    cache,
+}: {
+    activityRegistry: ActivityRegistry;
+    gatedTx: GatedTx;
+    processTx: ProcessTx;
+    isTransactionSuccessful: (gtxId: GatedTransactionId) => boolean | undefined;
+    confirmationCallback: NonNullable<UserInteractionCallbacks['confirmationCallback']>;
+    fn: WorkflowFunctions;
+    cache?: IGatedTransactionCache;
+}): Promise<GatedTx & { result: GatedTransactionResult<GatedTx, ProcessedTxType> }> => {
+    const dependencyIds = (gatedTx.dependencies ?? []).map((tx) => getIdForGatedTransaction(tx));
+
+    const dependenciesAreAllProcessed = () =>
+        dependencyIds.every((id) => isTransactionSuccessful(id) != null);
+
+    await fn.condition(dependenciesAreAllProcessed);
+
+    //check that the dependencies succeeded
+    const dependenciesWereSuccessful = dependencyIds.every((id) => isTransactionSuccessful(id));
+
+    if (!dependenciesWereSuccessful) {
+        return {
+            ...gatedTx,
+            result: {
+                status: GatedTransactionStatus.DEPENDENCY_FAILED,
+            },
+        };
+    }
+
+    const initialCheckResult = await checkGatedTransaction({
+        gatedTransaction: gatedTx,
+        registry: activityRegistry,
+        cachedCheckResult: await cache?.getCachedTxCheckData?.(gatedTx),
+    });
+
+    await cache?.cacheSuccessfulTxCheckData?.(gatedTx, initialCheckResult.onChainData);
+
+    if (initialCheckResult.expectationMet) {
+        //already met
+        return {
+            ...gatedTx,
+            result: {
+                status: GatedTransactionStatus.NO_OP,
+            },
+        };
+    }
+
+    //get confirmation before sending
+    const confirmation = await confirmationCallback(gatedTx);
+    if (!confirmation) {
+        return {
+            ...gatedTx,
+            result: {
+                status: GatedTransactionStatus.DENIED,
+            },
+        };
+    }
+
+    //send the tx
+    try {
+        const processed = await processTx(gatedTx.transaction);
+        const finalCheckResult = await checkGatedTransaction({
+            registry: activityRegistry,
+            gatedTransaction: gatedTx,
+            processedTransaction: processed,
+        });
+
+        await cache?.cacheSuccessfulTxCheckData?.(gatedTx, finalCheckResult.onChainData);
+
+        if (finalCheckResult.expectationMet) {
+            //sent and successful
+            return {
+                ...gatedTx,
+                result: {
+                    status: GatedTransactionStatus.SUCCESS,
+                    submittedTransaction: processed,
+                },
+            };
+        } else {
+            //sent and unsuccessful
+            return {
+                ...gatedTx,
+                result: {
+                    status: GatedTransactionStatus.FINAL_CHECK_FAILED,
+                    submittedTransaction: processed,
+                    finalOnChainState: finalCheckResult.onChainData,
+                },
+            };
+        }
+    } catch (e) {
+        //sent and failed
+        return {
+            ...gatedTx,
+            result: {
+                status: GatedTransactionStatus.TRANSACTION_FAILED,
+                transactionError: e,
+            },
+        };
+    }
+};
+
+export const resolveGatedTransactions = async <
+    TxType extends Transaction,
+    ProcessedTxType extends Transaction,
+    GatedTx extends GatedTransaction<string, TxType, any>,
+    ProcessTx extends (transaction: TxType) => Promise<ProcessedTxType>,
+>({
+    activityRegistry,
+    gatedTxes,
+    processTx,
+    fn,
+    cache,
+    userInteractionCallbacks,
+}: {
+    activityRegistry: ActivityRegistry;
+    gatedTxes: GatedTx[];
+    processTx: ProcessTx;
+    fn: WorkflowFunctions;
+    cache?: IGatedTransactionCache;
+    userInteractionCallbacks?: UserInteractionCallbacks;
+}): Promise<(GatedTx & { result: GatedTransactionResult })[]> => {
+    //compute deps
+    const allInternalIds = gatedTxes.map((tx) => getIdForGatedTransaction(tx));
+    const allDeps = gatedTxes.flatMap((tx) => tx.dependencies ?? []);
+    const allExternalDeps = allDeps.filter(
+        (tx) => !allInternalIds.includes(getIdForGatedTransaction(tx)),
+    );
+
+    //prepopulate results for external dependencies
+    //this map is only used for internal status tracking
+    //map id -> was successful
+    const results: Record<GatedTransactionId, boolean> = Object.fromEntries(
+        await Promise.all(
+            allExternalDeps.map(async (tx) => {
+                const checkResult = await checkGatedTransaction({
+                    gatedTransaction: tx,
+                    registry: activityRegistry,
+                    cachedCheckResult: await cache?.getCachedTxCheckData?.(tx),
+                });
+
+                return [getIdForGatedTransaction(tx), checkResult.expectationMet];
+            }),
+        ),
+    );
+
+    const isTransactionSuccessful = (gtxId: GatedTransactionId) => results[gtxId];
+
+    const txFunctions = gatedTxes.map((tx) => async () => {
+        const res = await resolveGatedTransaction<TxType, ProcessedTxType, GatedTx, ProcessTx>({
+            gatedTx: tx,
+            activityRegistry,
+            isTransactionSuccessful,
+            processTx,
+            confirmationCallback:
+                userInteractionCallbacks?.confirmationCallback ?? (async () => true),
+            fn,
+            cache,
+        });
+
+        const resId = getIdForGatedTransaction(res);
+        results[resId] = [GatedTransactionStatus.SUCCESS, GatedTransactionStatus.NO_OP].includes(
+            res.result.status,
+        );
+
+        userInteractionCallbacks?.onResultCallback?.(res);
+        return res;
+    });
+
+    return await Promise.all(txFunctions.map((func) => func()));
+};
+
+export const resolveSequencedGatedTransactions = async <
+    TxType extends Transaction,
+    ProcessedTxType extends Transaction,
+    GatedTx extends GatedTransaction<string, TxType, any>,
+    ProcessTx extends (transaction: TxType) => Promise<ProcessedTxType>,
+>({
+    activityRegistry,
+    gatedTxes,
+    processTx,
+    cache,
+    userInteractionCallbacks,
+    fn,
+}: {
+    activityRegistry: ActivityRegistry;
+    gatedTxes: GatedTx[][];
+    processTx: ProcessTx;
+    fn: WorkflowFunctions;
+    cache?: IGatedTransactionCache;
+    userInteractionCallbacks?: UserInteractionCallbacks;
+}) => {
+    const results = [];
+    for (const seq of gatedTxes) {
+        const result = await resolveGatedTransactions<TxType, ProcessedTxType, GatedTx, ProcessTx>({
+            gatedTxes: seq,
+            activityRegistry,
+            processTx,
+            cache,
+            userInteractionCallbacks,
+            fn,
+        });
+        results.push(result);
+    }
+
+    return results;
+};

package/src/types.ts

@@ -0,0 +1,213 @@
+import z from 'zod/v4';
+
+import type {
+    Transaction,
+    transactionSchema as _transactionSchema,
+} from '@layerzerolabs/common-chain-model';
+import type { FunctionPointer } from '@layerzerolabs/common-utils';
+import { functionSchema } from '@layerzerolabs/zod-utils';
+
+export type OnChainDataComparisonOperator<OnChainDataType> = OnChainDataType extends number
+    ? '<' | '<=' | '=' | '!=' | '>' | '>='
+    : '=' | '!=';
+
+export type OnChainDataComparison<OnChainDataType> = {
+    operator: OnChainDataComparisonOperator<OnChainDataType>;
+    comparisonValue: OnChainDataType;
+};
+
+export type GatedTransactionCheck<
+    Method extends (...args: any[]) => any = (...args: any[]) => unknown,
+> = {
+    functionPointer: FunctionPointer<Method>;
+    params: any[];
+    expectedResult: OnChainDataComparison<Awaited<ReturnType<Method>>>;
+};
+
+export const gatedTransactionSchema = <TransactionSchema extends typeof _transactionSchema>({
+    transactionSchema,
+    name,
+}: {
+    transactionSchema: TransactionSchema;
+    name: z.ZodString | z.ZodLiteral<string>;
+}) =>
+    z.object({
+        name,
+        transaction: transactionSchema,
+        check: z.object({
+            functionPointer: z.any(),
+            params: z.array(z.any()),
+            expectedResult: z.object({
+                operator: z.custom<OnChainDataComparisonOperator<any>>(),
+                comparisonValue: z.any(),
+            }),
+        }),
+    });
+
+// Schema for gated transaction results
+export const gatedTransactionResultSchema = <
+    TransactionSchema extends typeof _transactionSchema,
+    OnchainDataSchema extends z.ZodType,
+>(
+    transactionSchema: TransactionSchema,
+    onchainDataSchema: OnchainDataSchema,
+) =>
+    z.union([
+        z.object({
+            status: z.literal(GatedTransactionStatus.NO_OP),
+        }),
+        z.object({
+            status: z.literal(GatedTransactionStatus.SUCCESS),
+            submittedTransaction: transactionSchema,
+        }),
+        z.object({
+            status: z.literal(GatedTransactionStatus.TRANSACTION_FAILED),
+            transactionError: z.any(),
+        }),
+        z.object({
+            status: z.literal(GatedTransactionStatus.FINAL_CHECK_FAILED),
+            submittedTransaction: transactionSchema,
+            finalOnChainState: onchainDataSchema,
+        }),
+        z.object({
+            status: z.literal(GatedTransactionStatus.DEPENDENCY_FAILED),
+        }),
+        z.object({
+            status: z.literal(GatedTransactionStatus.DENIED),
+        }),
+    ]);
+
+// Schema for processed gated transactions (with results)
+export const processedGatedTransactionSchema = <
+    TransactionSchema extends typeof _transactionSchema,
+    OnchainDataSchema extends z.ZodType,
+>({
+    transactionSchema,
+    onchainDataSchema,
+    name,
+}: {
+    transactionSchema: TransactionSchema;
+    onchainDataSchema: OnchainDataSchema;
+    name: z.ZodString | z.ZodLiteral<string>;
+}) =>
+    gatedTransactionSchema({
+        transactionSchema,
+        name,
+    }).and(
+        z.object({
+            result: gatedTransactionResultSchema(transactionSchema, onchainDataSchema),
+        }),
+    );
+
+type GatedTransactionDependencies = GatedTransaction[];
+
+export type GatedTransaction<
+    Name extends string = string,
+    TxType extends Transaction = Transaction,
+    CheckMethod extends (...args: any[]) => any = (...args: any[]) => any,
+    Dependencies extends GatedTransactionDependencies = GatedTransactionDependencies,
+> = {
+    bundleName?: string;
+    name: Name;
+    transaction: TxType;
+    check: GatedTransactionCheck<CheckMethod>;
+    cacheable?: boolean;
+    uniqueIdKeys?: Record<string, string | number | boolean>;
+    dependencies?: Dependencies;
+};
+
+export type ProcessedGatedTransaction<
+    Name extends string = string,
+    TxType extends Transaction = Transaction,
+    CheckMethod extends (...args: any[]) => any = (...args: any[]) => any,
+> = GatedTransaction<Name, TxType, CheckMethod> & {
+    result: GatedTransactionResult<GatedTransaction<Name, TxType, CheckMethod>, TxType>;
+};
+
+export type InferOnChainDataTypeFromGatedTransaction<GatedTx extends GatedTransaction> =
+    GatedTx extends GatedTransaction<any, any, infer Check> ? Awaited<ReturnType<Check>> : unknown;
+
+export enum GatedTransactionStatus {
+    NO_OP = 'no_op',
+    SUCCESS = 'success',
+    TRANSACTION_FAILED = 'transaction_failed',
+    FINAL_CHECK_FAILED = 'final_check_failed',
+    DEPENDENCY_FAILED = 'dependency_failed',
+    DENIED = 'denied',
+}
+
+type NoOpGatedTransaction = {
+    status: GatedTransactionStatus.NO_OP;
+};
+
+type SuccessfulGatedTransaction<ProcessedTx extends Transaction> = {
+    status: GatedTransactionStatus.SUCCESS;
+    submittedTransaction: ProcessedTx;
+};
+
+type TxFailedGatedTransaction = {
+    status: GatedTransactionStatus.TRANSACTION_FAILED;
+    transactionError: any;
+};
+
+type CheckFailedGatedTransaction<ProcessedTx extends Transaction, State> = {
+    status: GatedTransactionStatus.FINAL_CHECK_FAILED;
+    submittedTransaction: ProcessedTx;
+    finalOnChainState: State;
+};
+
+type DependencyFailedGatedTransaction = {
+    status: GatedTransactionStatus.DEPENDENCY_FAILED;
+};
+
+type DeniedGatedTransaction = {
+    status: GatedTransactionStatus.DENIED;
+};
+
+export type GatedTransactionResult<
+    GatedTx extends GatedTransaction = GatedTransaction,
+    ProcessedTxType extends Transaction = Transaction,
+> =
+    | NoOpGatedTransaction
+    | SuccessfulGatedTransaction<ProcessedTxType>
+    | TxFailedGatedTransaction
+    | CheckFailedGatedTransaction<
+          ProcessedTxType,
+          InferOnChainDataTypeFromGatedTransaction<GatedTx>
+      >
+    | DependencyFailedGatedTransaction
+    | DeniedGatedTransaction;
+
+export const gatedTransactionCacheSchema = z.object({
+    getCachedTxCheckData: functionSchema({
+        input: z.tuple([z.any()]),
+        output: z.promise(z.any()),
+    }) as z.ZodType<
+        <GatedTx extends GatedTransaction>(
+            gtx: GatedTx,
+        ) => Promise<InferOnChainDataTypeFromGatedTransaction<GatedTx> | undefined>
+    >,
+    cacheSuccessfulTxCheckData: functionSchema({
+        input: z.tuple([z.any(), z.any()]),
+        output: z.promise(z.any()),
+    }) as z.ZodType<
+        <GatedTx extends GatedTransaction>(
+            gtx: GatedTx,
+            data: InferOnChainDataTypeFromGatedTransaction<GatedTx>,
+        ) => Promise<void>
+    >,
+});
+
+export type IGatedTransactionCache = z.infer<typeof gatedTransactionCacheSchema>;
+
+/**
+ * name-chain-uniqueIdKeys
+ *
+ * E.g., setDelegate-ethereum-oAppAddress:0xMY_OAPP
+ */
+export type GatedTransactionId = `${string}-${string}-${string}`;
+
+export type UserInteractionCallbacks = {
+    confirmationCallback?: (gtx: GatedTransaction) => Promise<boolean>;
+    onResultCallback?: (result: GatedTransaction & { result: GatedTransactionResult }) => void;
+};