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

# Transaction Configuration

> Configure transaction processing, batching, locking, and coalescing 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 <section className="cta-callout not-prose relative my-8 w-full min-w-0 overflow-hidden rounded-xl border border-zinc-200 p-5 dark:border-white/10">
      <div className="cta-callout-noise" aria-hidden="true" />
      <div className="cta-callout-layout">
        {title ? <div className="cta-callout-title-row">
            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 28 28" width="14" height="14" className="cta-callout-icon shrink-0 text-zinc-800 dark:text-zinc-200" aria-hidden="true">
              <g fill="none" fillRule="nonzero">
                <path d="M28 0v28H0V0h28ZM14.691833333333335 27.134333333333334l-0.012833333333333334 0.0023333333333333335 -0.08283333333333333 0.04083333333333334 -0.023333333333333334 0.004666666666666667 -0.016333333333333335 -0.004666666666666667 -0.08283333333333333 -0.04083333333333334c-0.011666666666666667 -0.004666666666666667 -0.022166666666666668 -0.0011666666666666668 -0.028000000000000004 0.005833333333333334l-0.004666666666666667 0.011666666666666667 -0.019833333333333335 0.49933333333333335 0.005833333333333334 0.023333333333333334 0.011666666666666667 0.015166666666666667 0.12133333333333333 0.08633333333333333 0.0175 0.004666666666666667 0.014000000000000002 -0.004666666666666667 0.12133333333333333 -0.08633333333333333 0.014000000000000002 -0.018666666666666668 0.004666666666666667 -0.019833333333333335 -0.019833333333333335 -0.4981666666666667c-0.0023333333333333335 -0.011666666666666667 -0.0105 -0.019833333333333335 -0.019833333333333335 -0.021Zm0.3091666666666667 -0.13183333333333336 -0.015166666666666667 0.0023333333333333335 -0.21583333333333335 0.1085 -0.011666666666666667 0.011666666666666667 -0.0035000000000000005 0.012833333333333334 0.021 0.5016666666666667 0.005833333333333334 0.014000000000000002 0.009333333333333334 0.008166666666666668 0.23450000000000004 0.1085c0.014000000000000002 0.004666666666666667 0.026833333333333334 0 0.03383333333333334 -0.009333333333333334l0.004666666666666667 -0.016333333333333335 -0.03966666666666667 -0.7163333333333334c-0.0035000000000000005 -0.014000000000000002 -0.011666666666666667 -0.023333333333333334 -0.023333333333333334 -0.025666666666666667Zm-0.8341666666666667 0.0023333333333333335a0.026833333333333334 0.026833333333334334 0 0 0 -0.0315 0.007000000000000001l-0.007000000000000001 0.016333333333333335 -0.03966666666666667 0.7163333333333334c0 0.014000000000000002 0.008166666666666668 0.023333333333333334 0.019833333333333335 0.028000000000000004l0.0175 -0.0023333333333333335 0.23450000000000004 -0.1085 0.011666666666666667 -0.009333333333333334 0.004666666666666667 -0.012833333333333334 0.019833333333333335 -0.5016666666666667 -0.0035000000000000005 -0.014000000000000002 -0.011666666666666667 -0.011666666666666667 -0.21466666666666667 -0.10733333333333334Z" strokeWidth="1.1667" />
                <path fill="currentColor" d="M14 2.916666666666667A1.75 1.75 0 0 1 15.750000000000002 4.666666666666667v6.302333333333334L21.207666666666668 7.816666666666667a1.75 1.75 0 0 1 1.75 3.031L17.5 14l5.457666666666667 3.151166666666667a1.75 1.75 0 0 1 -1.75 3.031l-5.457666666666667 -3.1500000000000004V23.333333333333336a1.75 1.75 0 0 1 -3.5 0v-6.302333333333334L6.792333333333334 20.183333333333337a1.75 1.75 0 1 1 -1.75 -3.031L10.5 14 5.042333333333334 10.848833333333333a1.75 1.75 0 0 1 1.75 -3.031l5.457666666666667 3.1500000000000004V4.666666666666667A1.75 1.75 0 0 1 14 2.916666666666667Z" strokeWidth="1.1667" />
              </g>
            </svg>
            <p className="cta-callout-title min-w-0 font-semibold text-zinc-800 dark:text-zinc-200">
              {title}
            </p>
          </div> : null}
        <div className={`cta-callout-body text-sm leading-normal text-zinc-800 dark:text-zinc-200${title ? " cta-callout-body--indented" : ""}`}>
          {children}
        </div>
        <a href={href} target={target} rel={linkRel} onClick={handleCtaClick} data-docs-cta={trackingEvent || undefined} className="cta-callout-button inline-flex items-center justify-center gap-1 rounded-full bg-white px-3 py-1.5 text-sm font-semibold transition hover:bg-zinc-100 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-white/50 dark:bg-white dark:hover:bg-zinc-200">
          {buttonLabel}
          <span className="cta-callout-button-arrow" aria-hidden="true">
            →
          </span>
        </a>
      </div>
    </section>;
};

This page covers the settings that control how Blnk executes, batches, and locks transactions.

For queue names, sharding, retries, and hot-lane routing, see [Queue configuration](/advanced/configuration/queue).

***

## Transaction settings

Use these settings to control transaction batching, worker behavior, and queued validation.

<CodeGroup>
  ```bash blnk.env theme={"system"}
  BLNK_TRANSACTION_MAX_QUEUE_SIZE=1000
  BLNK_TRANSACTION_MAX_WORKERS=10
  BLNK_TRANSACTION_INDEX_QUEUE_PREFIX=transactions
  BLNK_TRANSACTION_ENABLE_QUEUED_CHECKS=false
  ```

  ```json blnk.json theme={"system"}
  {
    "transaction": {
      "batch_size": 1000,
      "max_queue_size": 1000,
      "max_workers": 10,
      "index_queue_prefix": "transactions",
      "enable_queued_checks": false
    }
  }
  ```
</CodeGroup>

|                                         | Description                                                                                                                                                                                                                                                        | Default        |
| :-------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |
| `BLNK_TRANSACTION_MAX_QUEUE_SIZE`       | In-memory **channel buffer size** for the batch worker used by `ProcessTransactionInBatches` (not a Redis queue depth limit).                                                                                                                                      | `1000`         |
| `BLNK_TRANSACTION_MAX_WORKERS`          | Concurrency for **batch and reconciliation** transaction workers. For the main Redis-backed **queued** transaction pool, use `BLNK_QUEUE_TRANSACTION_WORKER_CONCURRENCY` and [hot-lane settings](/advanced/configuration/queue#hot-lane-routing-settings) instead. | `10`           |
| `BLNK_TRANSACTION_INDEX_QUEUE_PREFIX`   | **Collection / index name prefix** for **transaction search** documents (e.g. Typesense), not a Redis transaction queue name.                                                                                                                                      | `transactions` |
| `BLNK_TRANSACTION_ENABLE_QUEUED_CHECKS` | Includes queued debits when loading balances for pre-transaction validation.                                                                                                                                                                                       | `false`        |

***

## Coalescing settings

Use Coalescing settings to improve performance and throughput under load when working with [hot balances](/guides/hot-balances#coalescing).

<CodeGroup>
  ```bash blnk.env theme={"system"}
  BLNK_TRANSACTION_BATCH_SIZE=1000
  BLNK_TRANSACTION_ENABLE_COALESCING=true
  BLNK_TRANSACTION_DISABLE_BATCH_REFERENCE_CHECK=false
  ```

  ```json blnk.json theme={"system"}
  {
    "transaction": {
      "batch_size": 1000,
      "enable_coalescing": true,
      "disable_batch_reference_check": false
    }
  }
  ```
</CodeGroup>

|                                                  | Description                                                                                                           | Default |
| :----------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- | :------ |
| `BLNK_TRANSACTION_BATCH_SIZE`                    | Maximum number of compatible queued transactions Blnk tries to process in one coalesced batch.                        | `1000`  |
| `BLNK_TRANSACTION_ENABLE_COALESCING`             | Enables coalesced execution for normal queued transaction processing.                                                 | `true`  |
| `BLNK_TRANSACTION_DISABLE_BATCH_REFERENCE_CHECK` | Disables reference validation across a coalesced batch before commit. When `false`, reference checking stays enabled. | `false` |

### `BLNK_TRANSACTION_ENABLE_COALESCING`

When Coalescing is enabled, 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 works best when queued traffic arrives in bursts and many transactions overlap on the same balances.

<Card title="Coalescing for hot balances" icon="flame" href="/guides/hot-balances#coalescing">
  Higher throughput on contended balances.
</Card>

### `BLNK_TRANSACTION_DISABLE_BATCH_REFERENCE_CHECK`

This controls whether Blnk validates transaction references across the batch before commit.

Leaving it as `false` (the default) is safer because it helps catch duplicate or conflicting references within the same batch, ensuring that your transactions remain idempotent.

<Warning>
  **Please note:** Disabling reference checks may reduce some overhead, but it also increases the risk of duplicate-reference issues slipping through batched execution.
</Warning>

***

## Lock settings

Use these settings to control [distributed balance locks](/guides/concurrency#distributed-redis-balance-locks) for direct and queued transaction processing, including coalesced batch execution.

<CodeGroup>
  ```bash blnk.env theme={"system"}
  BLNK_TRANSACTION_LOCK_DURATION=1m
  BLNK_TRANSACTION_LOCK_WAIT_TIMEOUT=3s
  ```

  ```json blnk.json theme={"system"}
  {
    "transaction": {
      "lock_duration": 60,
      "lock_wait_timeout": 3
    }
  }
  ```
</CodeGroup>

|                                      | Description                                                                                                                                                           | Default |
| :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
| `BLNK_TRANSACTION_LOCK_DURATION`     | How long a distributed balance lock can live once acquired, in **seconds** (non-zero values).                                                                         | `60`    |
| `BLNK_TRANSACTION_LOCK_WAIT_TIMEOUT` | How long Blnk waits when acquiring **transaction balance locks** (shared path for direct and queued processing, including coalesced batch execution), in **seconds**. | `3`     |

### `BLNK_TRANSACTION_LOCK_WAIT_TIMEOUT`

This controls how long a transaction should wait when [acquiring a lock](/guides/concurrency#distributed-redis-balance-locks) before the transaction fails with a lock error.

If locks are not acquired in time, the **operation fails with a lock error**. For a **direct** (`skip_queue=true`) request, that is typically returned to the client. For **queued** work, workers may retry or reject depending on [queue settings](/advanced/configuration/queue#queue-settings), e.g.  `BLNK_QUEUE_REJECT_LOCK_CONTENTION_IMMEDIATELY` and `BLNK_QUEUE_MAX_RETRY_ATTEMPTS`.

<Tip>
  **Tip:** Keep the default value unless transactions regularly outlive the lock window. This config is especially important for transactions that bypass the queue.
</Tip>

***

## Hash chain settings

<Info>Available in version 0.15.0 and later.</Info>

The optional [transaction hash chain](/transactions/hash) seals applied transactions into a global tamper-evident sequence. It is **disabled by default**. When enabled, a background processor backfills unchained rows and appends new transactions after a trailing delay.

Run `blnk verify-chain` from your Core deployment to check chain integrity.

In `blnk.json`, `poll_interval` and `trailing_delay` are **integer seconds**. Environment variables accept Go duration format (for example `5s`, `30s`).

<CodeGroup>
  ```bash blnk.env theme={"system"}
  BLNK_TRANSACTION_HASHCHAIN_ENABLED=false
  BLNK_TRANSACTION_HASHCHAIN_POLL_INTERVAL=5s
  BLNK_TRANSACTION_HASHCHAIN_BATCH_SIZE=1000
  BLNK_TRANSACTION_HASHCHAIN_TRAILING_DELAY=30s
  ```

  ```json blnk.json theme={"system"}
  {
    "transaction": {
      "hash_chain": {
        "enabled": false,
        "poll_interval": 5,
        "batch_size": 1000,
        "trailing_delay": 30
      }
    }
  }
  ```
</CodeGroup>

|                                             | Description                                                                                                                            | Default      |
| :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------- | :----------- |
| `BLNK_TRANSACTION_HASHCHAIN_ENABLED`        | Enables the background hash-chain processor.                                                                                           | `false`      |
| `BLNK_TRANSACTION_HASHCHAIN_POLL_INTERVAL`  | How often the processor polls for unchained transactions. Env: Go duration (for example `5s`). JSON: seconds.                          | `5s` / `5`   |
| `BLNK_TRANSACTION_HASHCHAIN_BATCH_SIZE`     | Maximum transactions sealed per processor batch.                                                                                       | `1000`       |
| `BLNK_TRANSACTION_HASHCHAIN_TRAILING_DELAY` | Wait time before sealing the newest transactions, so in-flight writes can settle. Env: Go duration (for example `30s`). JSON: seconds. | `30s` / `30` |

<Card title="Transaction hashing" icon="link" href="/transactions/hash">
  Per-row hashes, chain verification, and sealed fields.
</Card>

***

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

<CtaCallout title="Connect your ledger to Blnk Cloud" href="https://cloud.blnkfinance.com/auth/sign-up?utm_source=blnk_docs&utm_medium=documentation&utm_campaign=need-help" buttonLabel="Open Blnk Cloud" trackingEvent="clicked_cloud_signup">
  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.
</CtaCallout>