Operating

Queue Configuration

Configure queue names, sharding, concurrency, retries, hot-lane routing, and worker monitoring in Blnk.

This page covers the settings that control how Blnk queues, routes, retries, and monitors background work for transactions, webhooks, indexing, inflight expiry, and scheduled inflight commits.

For transaction batching, locking, and coalescing settings, see Transaction configuration.

Queue settings

Use these settings to control queue names, sharding, concurrency, retries, and worker monitoring for normal queued processing.

BLNK_QUEUE_TRANSACTION=new:transaction
BLNK_QUEUE_NUMBER_OF_QUEUES=20
BLNK_QUEUE_TRANSACTION_WORKER_CONCURRENCY=4
BLNK_QUEUE_MAX_RETRY_ATTEMPTS=5
BLNK_QUEUE_INSUFFICIENT_FUND_RETRIES=false
BLNK_QUEUE_WEBHOOK=new:webhook
BLNK_QUEUE_INDEX=new:index
BLNK_QUEUE_INFLIGHT_EXPIRY=new:inflight-expiry
BLNK_QUEUE_INFLIGHT_COMMIT=new:inflight-commit
BLNK_QUEUE_WEBHOOK_CONCURRENCY=20
BLNK_QUEUE_MONITORING_PORT=5004

{
  "queue": {
    "transaction_queue": "new:transaction",
    "number_of_queues": 20,
    "transaction_worker_concurrency": 4,
    "max_retry_attempts": 5,
    "insufficient_fund_retries": false,
    "webhook_queue": "new:webhook",
    "index_queue": "new:index",
    "inflight_expiry_queue": "new:inflight-expiry",
    "inflight_commit_queue": "new:inflight-commit",
    "webhook_concurrency": 20,
    "monitoring_port": "5004"
  }
}

BLNK_QUEUE_NUMBER_OF_QUEUES

Blnk hashes the source balance ID and assigns the transaction to one of the configured queue shards. More queues allow more unrelated balances to process in parallel.

This helps reduce collisions before execution, but it does not replace locking. If many transactions still target the same balances, increasing the shard count alone will not solve the hotspot.

See instead: Sharding balances.

BLNK_QUEUE_TRANSACTION_WORKER_CONCURRENCY

This controls how many normal queued transaction tasks can execute at the same time.

Higher concurrency can improve throughput when work is spread across unrelated balances. It can also increase lock contention when many tasks overlap on the same balances. Increase it gradually and watch for contention before raising it further.

See also: Sharding balances.

BLNK_QUEUE_MAX_RETRY_ATTEMPTS

This sets the maximum number of times Blnk will try a queued transaction again after a temporary failure such as lock contention, insufficient funds, etc.

In simple terms:

• If a queued transaction fails for a reason that may clear on its own, Blnk can try it again
• If it keeps failing, Blnk stops after this limit instead of retrying forever.

BLNK_QUEUE_INSUFFICIENT_FUND_RETRIES

This controls whether Blnk should retry queued transactions that fail because the source balance does not have enough funds.

Leave this disabled when an insufficient-funds result should be treated as final. Enable it only when the balance may change shortly after the first attempt, for example:

• another queued credit is still being processed
• funds are expected to arrive from another part of your workflow
• transaction ordering means the balance may be sufficient on a later retry

Backpressure settings

When Redis memory or pending task count exceeds configured limits, Blnk rejects new queue enqueues and returns 503 Service Unavailable with QUEUE_BACKPRESSURE. See API error codes.

Backpressure is enabled by default.

BLNK_QUEUE_ENABLE_BACKPRESSURE=true
BLNK_QUEUE_BACKPRESSURE_MEMORY_PERCENT=85
BLNK_QUEUE_BACKPRESSURE_MAX_PENDING_TASKS=0
BLNK_QUEUE_BACKPRESSURE_CHECK_INTERVAL=500ms

{
  "queue": {
    "enable_backpressure": true,
    "backpressure_memory_percent": 85,
    "backpressure_max_pending_tasks": 0,
    "backpressure_check_interval": 500000000
  }
}

Hot-lane routing settings

Use these settings to isolate repeatedly contended balance pairs into a dedicated queue.

BLNK_QUEUE_ENABLE_HOT_LANE=false
BLNK_QUEUE_HOT_QUEUE_NAME=hot_transactions
BLNK_QUEUE_HOT_QUEUE_CONCURRENCY=1
BLNK_QUEUE_HOT_PAIR_TTL=300
BLNK_QUEUE_HOT_PAIR_LOCK_CONTENTION_THRESHOLD=3
BLNK_QUEUE_REJECT_LOCK_CONTENTION_IMMEDIATELY=false

{
  "queue": {
    "enable_hot_lane": false,
    "hot_queue_name": "hot_transactions",
    "hot_queue_concurrency": 1,
    "hot_pair_ttl": 300,
    "hot_pair_lock_contention_threshold": 3,
    "reject_lock_contention_immediately": false
  }
}

BLNK_QUEUE_ENABLE_HOT_LANE

Hot-lane routing is Blnk’s contention-aware queue routing strategy.

Blnk tracks repeated lock-contention events for a specific source|destination|currency pair. When contention crosses the configured threshold, BLNK_QUEUE_HOT_PAIR_LOCK_CONTENTION_THRESHOLD, Blnk promotes that pair into a hot state. New queued transactions for that pair are then routed to a dedicated hot queue instead of the normal queue shards.

This helps isolate the hottest balance pairs from the rest of your queued traffic, so they stop disturbing normal queue processing.

BLNK_QUEUE_REJECT_LOCK_CONTENTION_IMMEDIATELY

This setting changes what queued workers do after a lock-contention failure.

When set to true, Blnk rejects the transaction immediately if the required lock is busy. When set to false, the worker treats the failure as retryable and retries it up to BLNK_QUEUE_MAX_RETRY_ATTEMPTS.

Best practices

• Enable hot-lane routing when only a few balance pairs keep colliding.
• Use a shorter TTL for short bursts so pairs return to the normal queue sooner after traffic settles. Use a longer TTL when the same pairs stay hot for longer periods.
• Lower the threshold if hot pairs are not moving into the hot lane fast enough. This makes Blnk promote contended pairs sooner instead of letting them keep slowing down the normal queue.
• Only enable immediate rejection when you do not want Blnk to retry lock-contention failures.