Skip to content

fix(bridge): match a virtual-account deposit to its IBEX credit when Bridge reports it (ENG-891) - #546

Merged
islandbitcoin merged 2 commits into
mainfrom
eng-891-va-realtime
Nov 20, 2026
Merged

islandbitcoin merged 2 commits into
mainfrom
eng-891-va-realtime

Conversation

@islandbitcoin

Copy link
Copy Markdown
Contributor

What

When Bridge reports a virtual-account deposit payment_processed, Flash records its IBEX credit at that moment, if IBEX has already made the credit. Recording means the ERPNext settle row, the deposit row Completed, and the user's notification. This is ENG-891, PR 3 of 3.

Why

The deposit route's real-time step ran only for event_category === "transfer". Virtual-account deposits arrive as virtual_account.activity, with the state in event_object.type, so they skipped it.

Since #545, IBEX Hub's webhook records a deposit when IBEX reports the credit, but only if Bridge's deposit row already exists. IBEX usually settles a minute or two before Bridge's event lands. In that order the IBEX webhook finds no deposit row, and the deposit waited for the hourly matcher. This PR covers that order from the Bridge side.

How

  • matchBridgeDepositNow (src/app/bridge/match-ibex-deposits.ts) runs the hourly matcher's own per-customer logic for one deposit: account by Bridge customer, its USDT wallet, IBEX crypto receives settled from 15 minutes before the event, exact tx-hash join, then recordIbexCryptoReceive. It checks first whether the hash is already processed. It never throws and returns one of recorded, already_processed, no_ibex_credit or failed.
  • deposit.ts: a virtual_account.activity event with type payment_processed and a tx hash (receipt.destination_tx_hash, else destination.tx_hash, as the deposit row stores it) calls it. The call happens:
    • after the deposit row, the ERPNext audit row and the event's idempotency lock, so a redelivered event does not match again;
    • without awaiting it, so IBEX reads never hold Bridge's response.
  • No reconcileByTxHash for these events. It would file a bridge_without_ibex orphan and alert whenever Bridge's event beats IBEX's credit. Recording the credit already runs that reconcile, and the hourly deposit check flags real orphans after 6 hours.
  • The transfer-category gate is unchanged.

Ordering, after this PR

Order Who records
IBEX credit, then Bridge event (usual) this PR, when Bridge's event lands
Bridge event, then IBEX credit IBEX Hub webhook (#545), when IBEX reports it
either delivery lost hourly matcher (#543)

Every path goes through recordIbexCryptoReceive. It locks on the hash and skips a processed receive, so the user is notified once.

Tests

  • deposit.spec.ts:
    • a virtual-account payment_processed event matches with the right transfer, customer and hash;
    • no reconcileByTxHash call;
    • the response does not wait for the match;
    • a rejected match still answers 200;
    • funds_received, payment_submitted and an event with no hash do not match;
    • a transfer event keeps its reconcile and does not match;
    • a redelivered event does not match.
  • match-ibex-deposits.spec.ts (matchBridgeDepositNow):
    • records a credit settled two minutes before the event;
    • a hash in different case still matches;
    • already processed: skipped without IBEX reads;
    • no_ibex_credit when IBEX has nothing yet;
    • failure on each read and on recording;
    • a receive recorded meanwhile counts as already processed.
  • The other deposit-route specs mock the matcher; their behaviour is unchanged.
  • Local:
    • 26 suites, 497 tests across app/bridge and services/bridge, all passing;
    • eslint, prettier 3.6.2 and typos clean;
    • tsc shows only the two existing local graphql*-server.ts errors.

Not tested: a real Bridge virtual-account event. The next real deposit on production is the proof.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Gn2VCc25BAQjEu33uLycvP

…Bridge reports it (ENG-891)

The Bridge deposit route's real-time step only ran for transfer events;
virtual-account deposits arrive as virtual_account.activity and skipped it,
so they waited for the hourly matcher unless IBEX Hub's webhook came second.

A virtual_account.activity payment_processed event with a tx hash now runs
matchBridgeDepositNow, the hourly matcher's per-customer read and tx hash
join for that one deposit, after the deposit row, audit row and event lock,
without holding Bridge's response. It does not call reconcileByTxHash, which
would file a false "no IBEX receive" orphan whenever Bridge's event beats
IBEX's credit; recording the credit runs that reconcile itself. With IBEX
Hub's webhook, whichever event comes second records the deposit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gn2VCc25BAQjEu33uLycvP
@linear

linear Bot commented Nov 20, 2026

Copy link
Copy Markdown

ENG-891

…atch window in tests (ENG-891)

Review fixes for the virtual-account real-time match.

- WEBHOOKS.md (deposit.completed) and the recordIbexCryptoReceive docstring
  listed two recorders. They now name all three: the payment_processed
  event on the Bridge deposit route (via matchBridgeDepositNow) when IBEX
  has already credited, IBEX Hub's organization webhook when Bridge's event
  came first, and the hourly matcher for a delivery either one missed. The
  no_bridge_deposit comment says the Bridge deposit route picks up the
  first case, with the hourly matcher as backstop.
- The window test only checked the read's account and sort, so it passed
  with CREDIT_LEAD_MS at 0 or at 7 days. It now matches a credit settled
  14 minutes before Bridge's event and refuses one settled 16 minutes
  before; it fails with either of those values.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gn2VCc25BAQjEu33uLycvP

@bobodread876 bobodread876 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simon review clean after one fix round; CI green on b0c6ce8, deposit route and matcher specs run.

@islandbitcoin
islandbitcoin merged commit 2840a50 into main Nov 20, 2026
16 checks passed
@islandbitcoin
islandbitcoin deleted the eng-891-va-realtime branch November 20, 2026 17:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants