feat: create LockService class + relevant interfaces (#4605)

Signed-off-by: Simeon Nakov <[email protected]>
Signed-off-by: Konstantina Blazhukova <[email protected]>

Author: simzzz

package-lock.json

@@ -53,6 +53,7 @@
   "dependencies": {
     "@hashgraph/json-rpc-config-service": "file:../config-service",
     "@hashgraph/sdk": "^2.63.0",
+    "async-mutex": "^0.5.0",
     "axios": "^1.4.0",
     "axios-retry": "^4.5.0",
     "better-lookup": "^1.3.0",

packages/relay/package.json

@@ -17,3 +17,5 @@ export * from './rateLimiterService/RedisRateLimitStore';
 export * from './rateLimiterService/rateLimiterService';
 export * from './transactionPoolService/LocalPendingTransactionStorage';
 export * from './transactionPoolService/transactionPoolService';
+export * from './lockService/LockService';
+export * from './lockService/LockStrategyFactory';

packages/relay/src/lib/services/index.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import { LockStrategy } from '../../types/lock';
+
+/**
+ * Service that manages transaction ordering through distributed locking.
+ * Uses a strategy pattern to support both local (in-memory) and distributed (Redis) locking.
+ */
+export class LockService {
+  /**
+   * The underlying lock strategy implementation (Local or Redis).
+   */
+  private readonly strategy: LockStrategy;
+
+  /**
+   * Creates a new LockService instance.
+   *
+   * @param strategy - The lock strategy implementation to use.
+   */
+  constructor(strategy: LockStrategy) {
+    this.strategy = strategy;
+  }
+
+  /**
+   * Acquires a lock for the specified address.
+   * Blocks until the lock is available (no timeout on waiting).
+   *
+   * @param address - The sender address to acquire the lock for.
+   * @returns A promise that resolves to a unique session key.
+   */
+  async acquireLock(address: string): Promise<string> {
+    return await this.strategy.acquireLock(address);
+  }
+
+  /**
+   * Releases a lock for the specified address.
+   * Only succeeds if the session key matches the current lock holder.
+   *
+   * @param address - The sender address to release the lock for.
+   * @param sessionKey - The session key obtained during lock acquisition.
+   */
+  async releaseLock(address: string, sessionKey: string): Promise<void> {
+    await this.strategy.releaseLock(address, sessionKey);
+  }
+}

packages/relay/src/lib/services/lockService/LockService.ts

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import { Logger } from 'pino';
+import { RedisClientType } from 'redis';
+
+import { LockStrategy } from '../../types/lock';
+
+/**
+ * Factory for creating LockStrategy instances.
+ *
+ * Encapsulates the logic for selecting the appropriate lock strategy implementation
+ * based on available infrastructure (Redis vs in-memory).
+ */
+export class LockStrategyFactory {
+  /**
+   * Creates a LockStrategy instance.
+   *
+   * @param redisClient - Optional Redis client. If provided, creates Redis-backed lock strategy;
+   *                      otherwise creates local in-memory lock strategy.
+   * @param logger - Logger instance for the lock strategy.
+   * @returns A LockStrategy implementation.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  static create(redisClient: RedisClientType | undefined, logger: Logger): LockStrategy {
+    // TODO: Remove placeholder errors once strategies are implemented
+    if (redisClient) {
+      throw new Error('Redis lock strategy not yet implemented');
+    }
+
+    throw new Error('Local lock strategy not yet implemented');
+  }
+}

packages/relay/src/lib/services/lockService/LockStrategyFactory.ts

@@ -13,3 +13,4 @@ export * from './spendingPlanConfig';
 export * from './registry';
 export * from './debug';
 export * from './rateLimiter';
+export * from './lock';

packages/relay/src/lib/types/index.ts

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Interface for lock strategy implementations.
+ * Strategies handle the actual locking mechanism (local in-memory or distributed via Redis).
+ *
+ * @remarks
+ * Implementations must normalize addresses (e.g., lowercase) internally to ensure consistency.
+ */
+export interface LockStrategy {
+  /**
+   * Acquires a lock for the specified address.
+   * Blocks until the lock is available or timeout is reached.
+   *
+   * @param address - The address to acquire the lock for (will be normalized by implementation).
+   * @returns A promise that resolves to a unique session key upon successful acquisition.
+   */
+  acquireLock(address: string): Promise<string>;
+
+  /**
+   * Releases a lock for the specified address.
+   * Only succeeds if the provided session key matches the current lock holder.
+   *
+   * @param address - The address to release the lock for (will be normalized by implementation).
+   * @param sessionKey - The session key proving ownership of the lock.
+   * @returns A promise that resolves when the lock is released or rejected if not owner.
+   */
+  releaseLock(address: string, sessionKey: string): Promise<void>;
+}