feat: nonce ordering with locks

.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)

.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

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'
 

docs/configuration.md

@@ -68,6 +68,7 @@ Unless you need to set a non-default value, it is recommended to only populate o
 | `IP_RATE_LIMIT_STORE`                       | null                                  | Specifies the rate limit store to use for IP-based rate limiting: valid values are "LRU", "REDIS", with the possibility to be extended with a custom implementation (see [Store Selection](rate-limiting.md#store-selection)). If unset, falls back to Redis when `REDIS_ENABLED=true`, otherwise uses in-memory LRU.                                                                                                                                                                      |
 | `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.                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `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.                                                                                                                                                                                                                                                                                                                                                                                            |
@@ -105,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