Skip to main content
Hot balances refer to balances that perform large volumes of concurrent transactions. If not handled correctly, this can lead to lock contention errors, transaction failures and a poor user experience. Most hot balance scenarios fall into one of the following patterns:
  1. A → N: one source balance funds many destination balances at the same time.
  2. N → A: many source balances fund one destination balance at the same time.
  3. A → B and B → A: the same two balances move funds back and forth at the same time.
This guide explains the different strategies Blnk natively supports to handle these patterns safely. We’ll cover:
  1. Using the queue
  2. Coalescing
  3. Lock wait timeout
  4. Hot-lane routing

​
Using the queue

For high traffic or overlapping balances, we recommend using the default queue-based flow (skip_queue: false). The queue helps Blnk handle contention more effectively and reduces the chance of lock errors by allowing retries, hot-lane routing, and coalescing. Learn more: How Queueing Works.
Note: Lock contention can still happen in queued processing. Workers also acquire distributed balance locks when applying transactions.The difference is that the queue gives Blnk more ways to manage that contention and lower the likelihood of lock-related failures.

​
Coalescing

Available in version 0.14 and later.
Consider a deposit workflow involving one internal source balance funding 1000+ destination balances at the same time, or vice versa, e.g. A → N or N → A. With Coalescing, Blnk identifies the queued transactions based on if they share the same source, destination, and currency, batches them in-memory, and applies them in a single commit. This reduces the number of balance lookups and commits required, improving throughput and performance overall.
Please note: Coalescing only works when skip_queue=false. It doesn’t apply when you skip the queue.

​
How to use

To enable Coalescing, update your Blnk configuration file to include the following settings:
.env
BLNK_TRANSACTION_ENABLE_COALESCING=true
BLNK_TRANSACTION_BATCH_SIZE=1000
SettingsDescription
BLNK_TRANSACTION_ENABLE_COALESCINGTurns queued coalescing on or off.
BLNK_TRANSACTION_BATCH_SIZEControls how many transactions Blnk will try to coalesce in one batch.
For the full Coalescing settings, see transaction configuration.

​
When to use

As a rule of thumb, choose Coalescing when you have traffic bursts with repeated balance overlap and want the queue to drain more efficiently. It is a good fit when:
  • It takes too long for your queue to finish processing the transactions.
  • You see repeated contention on the same balance pair, source, or destination.
  • Your system experiences frequent bursts, with many similar transactions happening at the same time.
  • You want to reduce repeated lock contention errors in the queue and improve throughput.
Coalescing is less useful when:
  • Traffic is low-volume and spread across many balances.
  • You use skip_queue: true to process transactions immediately.

​
Lock wait timeout

Available in version 0.14 and later.
Lock wait timeout lets you set how long Blnk should wait to acquiring distributed balance locks before returning a lock error. This applies to both queued and immediate processing. In queued processing, it affects how long a worker waits before that attempt fails. In immediate processing (skip_queue: true), it affects how long the request waits in the request path before failing. This is especially important for immediate processing. If no timeout is set, a lock conflict can fail the request immediately. Setting a timeout gives the lock time to clear, which can reduce lock errors, but it also means the caller may wait longer for a response.
Note: A shorter timeout keeps requests more responsive, but makes lock errors more likely during contention, while a longer timeout gives contention more time to clear, but increases request latency and how long the caller may remain blocked.

​
How to use

To configure lock wait timeout, update your Blnk configuration with:
.env
BLNK_TRANSACTION_LOCK_WAIT_TIMEOUT=3
SettingsDescription
BLNK_TRANSACTION_LOCK_WAIT_TIMEOUTControls how long Blnk will wait for locks before failing the transaction with a lock error, in integer seconds.
For more lock and queue tuning options, see transaction configuration.

​
When to use

This setting matters most when you want to control how long Blnk waits to acquire a lock before failing. Use it when you need to tune lock wait behavior across your deployment, especially if you expect occasional contention. It is a good fit when:
  • you use skip_queue: true and want a bounded wait time before returning a lock error
  • you want requests to survive short contention spikes
  • lock waits are usually brief and predictable
  • slightly higher latency is acceptable in exchange for fewer lock errors

​
Hot-lane routing

Available in version 0.14 and later.
Consider a workflow where a small number of balance pairs keep receiving heavy concurrent traffic, while the rest of the queue is relatively normal, i.e. A → B and B → A. With hot-lane routing, Blnk identifies queued transactions for a specific source, destination, and currency pair that is showing repeated lock contention, and routes new traffic for that exact pair into a dedicated hot queue. This helps isolate the hottest balance pairs from the rest of your queued traffic, so they stop disturbing normal queue processing.
Please note: Hot-lane routing only works when skip_queue=false. It doesn’t apply when you skip the queue.

​
How to use

To enable hot-lane routing, update your Blnk configuration file to include the following settings:
.env
BLNK_QUEUE_ENABLE_HOT_LANE=true
SettingsDescription
BLNK_QUEUE_ENABLE_HOT_LANETurns hot-lane routing on or off.
For the full Hot-lane routing settings, see queue configuration.

​
When to use

Choose hot-lane routing when contention is concentrated around a small number of balance pairs and you want to isolate that traffic from the rest of the queue. It is a good fit when:
  • A few specific balance pairs repeatedly cause lock contention.
  • A small number of hot pairs are slowing down otherwise healthy queue traffic.
  • You want to isolate the worst offenders without changing correctness behavior.
  • Your normal queue works well overall, but certain balance pairs keep colliding.
It is less useful when:
  • Traffic is broadly distributed with no clear hot pairs.
  • Your main issue is overall worker throughput rather than localized contention. Use Coalescing instead.
  • Most of your traffic is synchronous and bypasses the queue. Consider Lock wait timeout instead.

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.
Tip: Connect to Blnk Cloud to see your Core data.You can view your transactions, manage identities, create custom reports, invite other team members to collaborate, and perform operations on your Core — all in one dashboard.Check out Blnk Cloud →