feat: Add Redis lock strategy (#4617)

simzzz · konstantinabl · commit be9ec8b26758 · 2025-11-28T11:54:31.000+02:00
Signed-off-by: Simeon Nakov &lt;simeon.nakov@limechain.tech&gt;
Signed-off-by: Konstantina Blazhukova &lt;konstantina.blajukova@gmail.com&gt;
diff --git a/.env.http.example b/.env.http.example
@@ -62,6 +62,11 @@ OPERATOR_KEY_MAIN=               # Operator private key used to sign transaction
 # ========== TRANSACTION POOL ========
 # PENDING_TRANSACTION_STORAGE_TTL=30 # Time-to-live (TTL) in seconds for transaction payloads stored in Redis
 
+# ========== LOCK SERVICE ===========
+# LOCK_MAX_HOLD_MS=30000 # Maximum time in milliseconds a lock can be held before automatic force-release
+# LOCAL_LOCK_MAX_ENTRIES=1000 # Maximum number of lock entries stored in memory
+# LOCK_QUEUE_POLL_INTERVAL_MS=50 # Interval in milliseconds between queue position checks when waiting for a lock
+
 # ========== HBAR RATE LIMITING ==========
 # HBAR_RATE_LIMIT_TINYBAR=25000000000 # Total HBAR budget (250 HBARs)
 # HBAR_RATE_LIMIT_DURATION=86400000 # HBAR budget limit duration (1 day)
diff --git a/.env.ws.example b/.env.ws.example
@@ -59,6 +59,11 @@ SUBSCRIPTIONS_ENABLED=true       # Must be true for the WebSocket server to func
 # ========== TRANSACTION POOL ========
 # PENDING_TRANSACTION_STORAGE_TTL=30 # Time-to-live (TTL) in seconds for transaction payloads stored in Redis
 
+# ========== LOCK SERVICE ===========
+# LOCK_MAX_HOLD_MS=30000 # Maximum time in milliseconds a lock can be held before automatic force-release
+# LOCAL_LOCK_MAX_ENTRIES=1000 # Maximum number of lock entries stored in memory
+# LOCK_QUEUE_POLL_INTERVAL_MS=50 # Interval in milliseconds between queue position checks when waiting for a lock
+
 # ========== OTHER SETTINGS ==========
 # CLIENT_TRANSPORT_SECURITY=false # Enable or disable TLS for both networks
 # USE_ASYNC_TX_PROCESSING=true   # If true, returns tx hash immediately after prechecks
diff --git a/charts/hedera-json-rpc-relay/values.yaml b/charts/hedera-json-rpc-relay/values.yaml
@@ -123,6 +123,11 @@ config:
   # REDIS_RECONNECT_DELAY_MS:
   # MULTI_SET:
 
+  # ========== LOCK SERVICE CONFIGURATION ==========
+  # LOCK_MAX_HOLD_MS:
+  # LOCAL_LOCK_MAX_ENTRIES:
+  # LOCK_QUEUE_POLL_INTERVAL_MS:
+
   # ========== DEVELOPMENT & TESTING ==========
   # LOG_LEVEL: 'trace'
 
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -69,7 +69,6 @@ Unless you need to set a non-default value, it is recommended to only populate o
 | `JUMBO_TX_ENABLED`                          | "true"                                | Controls how large transactions are handled during `eth_sendRawTransaction`. When set to `true`, transactions up to 128KB can be sent directly to consensus nodes without using Hedera File Service (HFS), as long as contract bytecode doesn't exceed 24KB. When set to `false`, all transactions containing contract deployments use the traditional HFS approach. This feature leverages the increased transaction size limit to simplify processing of standard Ethereum transactions. |
 | `LIMIT_DURATION`                            | "60000"                               | The maximum duration in ms applied to IP-method based rate limits.                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `LOCAL_LOCK_MAX_ENTRIES`                    | "1000"                                | Maximum number of lock entries stored in memory. Prevents unbounded memory growth.                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `LOCAL_LOCK_MAX_LOCK_TIME`                  | "30000"                               | Timer to auto-release if lock not manually released (in ms).                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `MAX_GAS_ALLOWANCE_HBAR`                    | "0"                                   | The maximum amount, in hbars, that the JSON-RPC Relay is willing to pay to complete the transaction in case the senders don't provide enough funds. Please note, in case of fully subsidized transactions, the sender must set the gas price to `0` and the JSON-RPC Relay must configure the `MAX_GAS_ALLOWANCE_HBAR` parameter high enough to cover the entire transaction cost.                                                                                                         |
 | `MAX_TRANSACTION_FEE_THRESHOLD`             | "15000000"                            | Used to set the max transaction fee. This is the HAPI fee which is paid by the relay operator account.                                                                                                                                                                                                                                                                                                                                                                                     |
 | `MIRROR_NODE_AGENT_CACHEABLE_DNS`           | "true"                                | Flag to set if the mirror node agent should cacheable DNS lookups, using better-lookup library.                                                                                                                                                                                                                                                                                                                                                                                            |
@@ -107,6 +106,8 @@ Unless you need to set a non-default value, it is recommended to only populate o
 | `TX_DEFAULT_GAS`                            | "400000"                              | Default gas for transactions that do not specify gas.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `TXPOOL_API_ENABLED`                        | "false"                               | Enables all txpool related methods.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `USE_ASYNC_TX_PROCESSING`                   | "true"                                | Set to `true` to enable `eth_sendRawTransaction` to return the transaction hash immediately after passing all prechecks, while processing the transaction asynchronously in the background.                                                                                                                                                                                                                                                                                                |
+| `LOCK_MAX_HOLD_MS`                          | "30000"                               | Maximum time in milliseconds a lock can be held before automatic force-release. This TTL prevents deadlocks when transaction processing hangs or crashes. Default is 30 seconds.                                                                                                                                                                                                                                                                                                           |
+| `LOCK_QUEUE_POLL_INTERVAL_MS`               | "50"                                  | Interval in milliseconds between queue position checks when waiting for a lock. Lower values provide faster lock acquisition but increase Redis load. Default is 50ms.                                                                                                                                                                                                                                                                                                                     |
 | `USE_MIRROR_NODE_MODULARIZED_SERVICES`      | null                                  | Controls routing of Mirror Node traffic through modularized services. When set to `true`, enables routing a percentage of traffic to modularized services. When set to `false`, ensures traffic follows the traditional non-modularized flow. When not set (i.e. `null` by default), no specific routing preference is applied. As Mirror Node gradually transitions to a fully modularized architecture across all networks, this setting will eventually default to `true`.              |
 
 ## Server
diff --git a/packages/config-service/src/services/globalConfig.ts b/packages/config-service/src/services/globalConfig.ts
@@ -368,11 +368,6 @@ const _CONFIG = {
     required: false,
     defaultValue: 1000,
   },
-  LOCAL_LOCK_MAX_LOCK_TIME: {
-    type: 'number',
-    required: false,
-    defaultValue: 30000,
-  },
   LOG_LEVEL: {
     type: 'string',
     required: false,
@@ -659,6 +654,16 @@ const _CONFIG = {
     required: false,
     defaultValue: true,
   },
+  LOCK_MAX_HOLD_MS: {
+    type: 'number',
+    required: false,
+    defaultValue: 30000,
+  },
+  LOCK_QUEUE_POLL_INTERVAL_MS: {
+    type: 'number',
+    required: false,
+    defaultValue: 50,
+  },
   USE_MIRROR_NODE_MODULARIZED_SERVICES: {
     type: 'boolean',
     required: false,
diff --git a/packages/relay/src/lib/services/lockService/LocalLockStrategy.ts b/packages/relay/src/lib/services/lockService/LocalLockStrategy.ts
@@ -6,6 +6,8 @@ import { randomUUID } from 'crypto';
 import { LRUCache } from 'lru-cache';
 import { Logger } from 'pino';
 
+import { LockService } from './LockService';
+
 /**
  * Represents the internal state for a lock associated with a given address.
  */
@@ -71,7 +73,7 @@ export class LocalLockStrategy {
     // Start a 30-second timer to auto-release if lock not manually released
     state.lockTimeoutId = setTimeout(() => {
       this.forceReleaseExpiredLock(address, sessionKey);
-    }, ConfigService.get('LOCAL_LOCK_MAX_LOCK_TIME'));
+    }, ConfigService.get('LOCK_MAX_HOLD_MS'));
 
     return sessionKey;
   }
@@ -83,13 +85,13 @@ export class LocalLockStrategy {
    * @param sessionKey - The session key of the lock holder
    */
   async releaseLock(address: string, sessionKey: string): Promise<void> {
-    if (this.logger.isLevelEnabled('debug')) {
-      const holdTime = Date.now() - state.acquiredAt!;
+    const state = this.localLockStates.get(address);
+
+    if (this.logger.isLevelEnabled('debug') && state?.acquiredAt) {
+      const holdTime = Date.now() - state.acquiredAt;
       this.logger.debug(`Releasing lock for address ${address} and session key ${sessionKey} held for ${holdTime}ms.`);
     }
 
-    const state = this.localLockStates.get(address);
-
     // Ensure only the lock owner can release
     if (state?.sessionKey === sessionKey) {
       await this.doRelease(state);
@@ -103,17 +105,17 @@ export class LocalLockStrategy {
    * @returns The LockState object associated with the address
    */
   private getOrCreateState(address: string): LockState {
-    address = address.toLowerCase();
-    if (!this.localLockStates.has(address)) {
-      this.localLockStates.set(address, {
+    const normalizedAddress = LockService.normalizeAddress(address);
+    if (!this.localLockStates.has(normalizedAddress)) {
+      this.localLockStates.set(normalizedAddress, {
         mutex: new Mutex(),
         sessionKey: null,
         acquiredAt: null,
         lockTimeoutId: null,
       });
     }
 
-    return this.localLockStates.get(address)!;
+    return this.localLockStates.get(normalizedAddress)!;
   }
 
   /**
diff --git a/packages/relay/src/lib/services/lockService/LockService.ts b/packages/relay/src/lib/services/lockService/LockService.ts
@@ -26,9 +26,9 @@ export class LockService {
    * 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.
+   * @returns A promise that resolves to a unique session key, or null if acquisition fails (fail open).
    */
-  async acquireLock(address: string): Promise<string> {
+  async acquireLock(address: string): Promise<string | null> {
     return await this.strategy.acquireLock(address);
   }
 
@@ -42,4 +42,14 @@ export class LockService {
   async releaseLock(address: string, sessionKey: string): Promise<void> {
     await this.strategy.releaseLock(address, sessionKey);
   }
+
+  /**
+   * Normalizes an address to lowercase for consistent key generation across lock strategies.
+   *
+   * @param address - The address to normalize.
+   * @returns The normalized address.
+   */
+  static normalizeAddress(address: string): string {
+    return address.toLowerCase();
+  }
 }
diff --git a/packages/relay/src/lib/services/lockService/LockStrategyFactory.ts b/packages/relay/src/lib/services/lockService/LockStrategyFactory.ts
@@ -5,6 +5,7 @@ import { RedisClientType } from 'redis';
 
 import { LockStrategy } from '../../types';
 import { LocalLockStrategy } from './LocalLockStrategy';
+import { RedisLockStrategy } from './RedisLockStrategy';
 
 /**
  * Factory for creating LockStrategy instances.
@@ -23,11 +24,10 @@ export class LockStrategyFactory {
    */
 
   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');
+      return new RedisLockStrategy(redisClient, logger.child({ name: 'redis-lock-strategy' }));
     }
 
-    return new LocalLockStrategy(logger);
+    return new LocalLockStrategy(logger.child({ name: 'local-lock-strategy' }));
   }
 }
diff --git a/packages/relay/src/lib/services/lockService/RedisLockStrategy.ts b/packages/relay/src/lib/services/lockService/RedisLockStrategy.ts
diff --git a/packages/relay/src/lib/types/lock.ts b/packages/relay/src/lib/types/lock.ts
diff --git a/packages/relay/tests/lib/services/lockService/LocalLockStrategy.spec.ts b/packages/relay/tests/lib/services/lockService/LocalLockStrategy.spec.ts
diff --git a/packages/relay/tests/lib/services/lockService/RedisLockStrategy.spec.ts b/packages/relay/tests/lib/services/lockService/RedisLockStrategy.spec.ts

Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,7 @@ import { RedisClientType } from 'redis';`
`5`	`5`
`6`	`6`	`import { LockStrategy } from '../../types';`
`7`	`7`	`import { LocalLockStrategy } from './LocalLockStrategy';`
	`8`	`+import { RedisLockStrategy } from './RedisLockStrategy';`
`8`	`9`
`9`	`10`	`/**`
`10`	`11`	`* Factory for creating LockStrategy instances.`
`@@ -23,11 +24,10 @@ export class LockStrategyFactory {`
`23`	`24`	`*/`
`24`	`25`
`25`	`26`	`static create(redisClient: RedisClientType \| undefined, logger: Logger): LockStrategy {`
`26`		`- // TODO: Remove placeholder errors once strategies are implemented`
`27`	`27`	`if (redisClient) {`
`28`		`- // throw new Error('Redis lock strategy not yet implemented');`
	`28`	`+ return new RedisLockStrategy(redisClient, logger.child({ name: 'redis-lock-strategy' }));`
`29`	`29`	`}`
`30`	`30`
`31`		`- return new LocalLockStrategy(logger);`
	`31`	`+ return new LocalLockStrategy(logger.child({ name: 'local-lock-strategy' }));`
`32`	`32`	`}`
`33`	`33`	`}`