CSV Export for All Wallet Transactions

[thibistaken]

Let's add this feature where a user can export all his wallet transactions, including btc, lbtc, lightning, and swaps. See: https://x.com/ricd40/status/1979857122621104335

[NoSandMan]

This feature should be made compatible with BIP-329 Wallet Labels Export Format.

https://github.com/bitcoin/bips/blob/master/bip-0329.mediawiki

[ethicnology]

bump

@SovereignGG in #2114

Many users have contacted support on how to export their txs in BULL wallet via CSV which they need for filling their tax returns.

Not sure how hard it would be to add this feature, but I am sure many users would really find this useful as its been requested very frequently.

[thibistaken]

Let's define specs better:

• Which tx types are included
• What data field per tx type
• Should be done on BE, not FE
• Filters or no filters?
• Which common columns for all rows, across tx types?

[thibistaken]

As a Bull Bitcoin wallet user, I want to...

• Export all my wallet transactions as a CSV file so that I can use them for personal accounting, record-keeping, etc.
• All transaction types included in a single export so that I have a complete picture of my wallet activity.
• Optionally filter my export by date range so that I can generate reports for specific time periods (e.g. calendar year).
• The export to be generated quickly to have a great user experience.
• The export to be compatible with BIP-329 so that I can import labels into other wallets or tools.

---

Test Cases

Basic Export

• User can trigger a CSV export from the wallet/transactions screen
• Export includes on-chain BTC transactions
• Export includes Liquid BTC (L-BTC) transactions
• Export includes Lightning transactions (send/receive)
• Export includes swap transactions (swap-in, swap-out)
• All transaction types appear in a single CSV file with common columns

CSV Format & Content

• CSV contains common columns across all tx types: date, type, amount (BTC), amount (sats), direction (sent/received), status, txid/payment hash
• Type-specific fields are included where applicable (e.g. on-chain fee, Lightning invoice, swap details)
• Date format is ISO 8601 (YYYY-MM-DD HH:MM:SS UTC)
• Amounts are consistent (sats or BTC, clearly labeled)
• CSV is well-formed (proper escaping, headers, encoding)

Filters

• User can filter export by date range (start date, end date)
• Export without filters returns all transactions
• Export with date range returns only transactions within that range
• Edge case: same start and end date returns only that day's transactions

BIP-329 Compatibility

• Export includes a BIP-329 compatible labels file (or option to export in BIP-329 format)
• Labels format follows the BIP-329 mediawiki spec (JSON lines with type, ref, label)

Error Handling

• User with zero transactions gets an appropriate message (no empty file download)
• Export handles large transaction histories without timeout
• Network error during export shows a clear error message with retry option

Security

• Export is generated server-side (backend), not client-side
• Export is delivered securely to the user's device
• No transaction data is cached or stored on the server after delivery

[thibistaken]

Proposed CSV Format

Based on the actual data models in the codebase (WalletTransaction, Swap, Payjoin, unified Transaction wrapper).

Common Columns (all rows)

Column	Description	Example
date	ISO 8601 UTC	2026-05-15T14:30:00Z
type	Transaction category	onchain, liquid, lightning_send, lightning_receive, chain_swap, payjoin_send, payjoin_receive
direction	Fund flow	incoming, outgoing, self
amount_sats	Amount in sats	150000
amount_btc	Amount in BTC (8 decimals)	0.00150000
fee_sats	Total fee paid (0 if not payer)	450
status	Final status	confirmed, completed, pending, failed, expired
txid	Primary tx identifier (txid or payment hash)	abc123...
network	Chain used	bitcoin, liquid

Type-Specific Columns (blank when not applicable)

Column	Applies To	Description
address	onchain, liquid, payjoin	Destination address
swap_id	lightning, chain_swap	Boltz swap ID
invoice	lightning	LN invoice / BOLT11
preimage	lightning_send	Payment preimage (proof of payment)
swap_fee_sats	lightning, chain_swap	Boltz service fee
send_network	chain_swap	Source chain (bitcoin or liquid)
receive_network	chain_swap	Destination chain
send_txid	chain_swap	Outgoing chain txid
receive_txid	chain_swap	Incoming chain txid

Design Decisions

Why these columns:

• Mirrors the unified Transaction wrapper which already computes txId, timestamp, amountSat, isIncoming/isOutgoing, isBitcoin/isLiquid
• WalletTransaction provides: txId, direction, amountSat, feeSat, confirmationTime, status, network, labels, inputs/outputs
• Swap (3 variants: LnReceive, LnSend, ChainSwap) provides: id, invoice, sendTxid/receiveTxid, preimage, SwapFees breakdown, SwapStatus
• Payjoin provides: id, amountSat, txId, originalTxId, status

Orders excluded — Exchange orders (buy/sell with fiat) are Bull Bitcoin exchange data, not wallet transactions. Tax-relevant exchange activity is already tracked server-side. This export covers wallet activity only.

On BIP-329 compatibility:

• BIP-329 is a JSON Lines format for label export ({"type":"tx","ref":"txid","label":"..."})
• Recommend offering it as a second export option, not merged into the CSV — they serve different purposes (accounting vs wallet interop)

On filters:

• Date range filter (start/end) covers the main tax use case
• Optional: filter by network (bitcoin/liquid/all), filter by type

Sample CSV

date,type,direction,amount_sats,amount_btc,fee_sats,status,txid,network,label,confirmations,address,swap_id,invoice,preimage,swap_fee_sats,send_network,receive_network,send_txid,receive_txid
2026-01-15T10:30:00Z,onchain,incoming,500000,0.00500000,0,confirmed,a1b2c3...,bitcoin,Salary,14502,bc1q...,,,,,,,,
2026-02-01T08:00:00Z,liquid,outgoing,200000,0.00200000,350,confirmed,d4e5f6...,liquid,,6,lq1...,,,,,,,,
2026-03-10T14:22:00Z,lightning_send,outgoing,50000,0.00050000,150,completed,hash123...,bitcoin,,,,,swap456,lnbc500u1...,pre789...,125,,,,
2026-04-05T09:15:00Z,chain_swap,outgoing,1000000,0.01000000,500,completed,swap789...,bitcoin,Move to Liquid,,,,,swap789,,,,250,bitcoin,liquid,tx_send...,tx_recv...