> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Handling Hot Balances
> Strategies for managing high-traffic balances and preventing lock contention in Blnk.
export const CtaCallout = props => {
const {title, buttonLabel, href, trackingEvent, buttonTarget, rel = "noopener noreferrer", children} = props;
const handleCtaClick = () => {
if (typeof window === "undefined" || !trackingEvent) {
return;
}
try {
window.dispatchEvent(new CustomEvent("blnk:docs-cta", {
detail: {
name: trackingEvent,
href
}
}));
} catch {}
try {
window.posthog?.capture?.(trackingEvent, {
href
});
} catch {}
const gaPayload = {
cta_href: href
};
try {
window.gtag?.("event", trackingEvent, gaPayload);
} catch {}
try {
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: trackingEvent,
...gaPayload
});
} catch {}
};
const isExternal = typeof href === "string" && (/^https?:\/\//i).test(href);
const target = buttonTarget ?? (isExternal ? "_blank" : undefined);
const linkRel = isExternal ? rel : undefined;
return ;
};
**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 concurrently.
2. **N → A:** many source balances fund one destination balance concurrently.
3. **A → B and B → A:** the same two balances exchange funds concurrently.
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](/guides/concurrency#queueing-transactions).
**Note:** Lock contention can still happen in queued processing. Workers also [acquire distributed balance locks](/guides/concurrency#distributed-redis-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 concurrently funding 1000+ destination balances, 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:
```bash .env theme={"system"}
BLNK_TRANSACTION_ENABLE_COALESCING=true
BLNK_TRANSACTION_BATCH_SIZE=1000
```
| Settings | Description |
| :----------------------------------- | :--------------------------------------------------------------------- |
| `BLNK_TRANSACTION_ENABLE_COALESCING` | Turns queued coalescing on or off. |
| `BLNK_TRANSACTION_BATCH_SIZE` | Controls how many transactions Blnk will try to coalesce in one batch. |
For the full Coalescing settings, see [transaction configuration](/advanced/configuration/transactions#coalescing-settings).
### 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 concurrently.
* 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](/guides/concurrency#distributed-redis-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:
```bash .env theme={"system"}
BLNK_TRANSACTION_LOCK_WAIT_TIMEOUT=3
```
| Settings | Description |
| :----------------------------------- | :--------------------------------------------------------------------------------------------------------------- |
| `BLNK_TRANSACTION_LOCK_WAIT_TIMEOUT` | Controls how long Blnk will wait for locks before failing the transaction with a lock error, in integer seconds. |
For more lock tuning options, see [transaction configuration](/advanced/configuration/transactions#blnk_transaction_lock_wait_timeout). For queue and retry settings, see [queue configuration](/advanced/configuration/queue).
### 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:
```bash .env theme={"system"}
BLNK_QUEUE_ENABLE_HOT_LANE=true
```
| Settings | Description |
| :--------------------------- | :-------------------------------- |
| `BLNK_QUEUE_ENABLE_HOT_LANE` | Turns hot-lane routing on or off. |
For the full Hot-lane routing settings, see [queue configuration](/advanced/configuration/queue#hot-lane-routing-settings).
### 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](#coalescing) instead.
* Most of your traffic is synchronous and bypasses the queue. Consider [Lock wait timeout](#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](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).
Sign up and manage your ledger with our back-office dashboard. You can invite teammates to collaborate and manage your ledger operations directly from the dashboard.