feat: process transactions in groups

[sczembor]

Description

Closes: #XXXX

---

Author Checklist

All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.

I have...

• included the correct type prefix in the PR title
• added ! to the type prefix if API or client breaking change
• added appropriate labels to the PR
• provided a link to the relevant issue or specification
• added a changelog entry to CHANGELOG.md
• included doc comments for public functions
• updated the relevant documentation or specification
• reviewed "Files changed" and left comments if necessary

Summary by Sourcery

Process finalized Bitcoin transactions in grouped batches to handle multiple deposits per transaction, update mint status per output (vout), and ensure correct batch minting in SUI.

New Features:

• Group finalized transactions by tx_id and aggregate their deposit outputs
• Include vout in SQL queries and status updates to track each UTXO individually
• Introduce models for FinalizedTxD1Row and GroupedFinalizedTx to support grouped processing

Enhancements:

• Refactor processFinalizedTransactions to build batch mint arguments per transaction group
• Modify database update statements to bind both tx_id and vout when marking records as minted or failed

Tests:

• Add unit test for processFinalizedTransactions to verify grouping logic and batch mint invocations

[sourcery-ai]

Reviewer's Guide

This PR refactors processFinalizedTransactions to batch multiple deposit outputs per transaction by vout, updates the mint preparation and status‐update logic accordingly, and extends models and tests to support this grouping.

Sequence diagram for grouped processing in processFinalizedTransactions

sequenceDiagram
    participant Indexer
    participant DB
    participant BlocksDB
    participant SuiClient
    Note over Indexer: Start processFinalizedTransactions
    Indexer->>DB: SELECT finalized txs (tx_id, vout, block_hash, block_height)
    DB-->>Indexer: Return FinalizedTxD1Row[]
    Indexer->>Indexer: Group txs by tx_id
    loop For each tx group
        Indexer->>BlocksDB: Get block by block_hash
        BlocksDB-->>Indexer: Return block
        Indexer->>Indexer: Prepare mintBatchArg for each group
    end
    Indexer->>SuiClient: tryMintNbtcBatch(mintBatchArgs)
    SuiClient-->>Indexer: Batch mint result
    loop For each deposit
        Indexer->>DB: UPDATE nbtc_minting SET status (by tx_id, vout)
    end

Loading

Class diagram for updated transaction grouping models

classDiagram
    FinalizedTxD1Row <|-- GroupedFinalizedTx
    class FinalizedTxD1Row {
        +string tx_id
        +number vout
        +string block_hash
        +number block_height
    }
    class GroupedFinalizedTx {
        +string block_hash
        +number block_height
        +FinalizedTxD1Row[] deposits
    }

Loading

File-Level Changes

Change	Details	Files
Group finalized transactions by tx_id and vout for batch minting	Query now selects vout and maps rows to FinalizedTxD1Row Build a Map<tx_id, GroupedFinalizedTx> and iterate over grouped entries Update log to report group count instead of raw row count	packages/btcindexer/src/btcindexer.ts
Handle per‐output (vout) status updates in mint batch	Replace processedTxIds list with processedPks including vout Modify SQL UPDATE statements to include vout and use parameterized updated_at Bind tx_id and vout when preparing batch update calls	packages/btcindexer/src/btcindexer.ts
Extend and rename models to support grouped finalized rows	Rename BlockRecord to FinalizedTxD1Row and add vout, block_hash, block_height Introduce GroupedFinalizedTx interface with deposits array	packages/btcindexer/src/models.ts
Add unit test for grouped transaction processing	Mock .all() to return multiple deposit rows Assert tryMintNbtcBatch is called once for grouped tx_id Verify update statement is bound with tx_id and vout	packages/btcindexer/src/btcindexer.test.ts

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey there - I've reviewed your changes - here's some feedback:

• Consider wrapping the batch of status updates in a single DB transaction to ensure atomicity and avoid partial commits.
• The processedPks variable name is not very descriptive; consider renaming it to something like processedDeposits for better readability.
• Add a test case with multiple deposits for the same tx_id to verify the grouping logic handles batch processing and updates correctly.

Prompt for AI Agents

Please address the comments from this code review:
## Overall Comments
- Consider wrapping the batch of status updates in a single DB transaction to ensure atomicity and avoid partial commits.
- The processedPks variable name is not very descriptive; consider renaming it to something like processedDeposits for better readability.
- Add a test case with multiple deposits for the same tx_id to verify the grouping logic handles batch processing and updates correctly.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[robert-zaremba]

potential bugs. need more clarification

[robert-zaremba]

pre-approving, but requested few changes