Design Crypto Tax Reporting - System Design | WinJob

Problem Statement: Crypto Tax Reporting Platform

Section 1 focuses on understanding for a Koinly/CoinTracker-class crypto tax platform.

Koinly and CoinTracker win on breadth of exchange connectors, not raw blockchain TPS.
Tax reporting is an accounting pipeline: ingest, normalize, match transfers, dispose lots, export forms.
Users tolerate 15-minute sync lag if totals reconcile to exchange statements.
Form 8949 row must trace to disposal lots with acquisition and proceeds timestamps.
Wash sale logic applies to crypto securities-like assets in US guidance—call out uncertainty explicitly.
Missing cost basis is the #1 support ticket; design a queue with user attestation and CPA override.
DeFi swaps create taxable disposals even when users think they only 'moved' tokens.
NFT mints and royalties need separate classification rules in the normalization layer.
Stablecoin transfers are not tax-neutral if they realize FX on disposition of another asset.
Internal transfers between owned wallets must net to zero gain with matched lot moves.
Hard fork airdrops create income events at FMV on receipt—indexer must tag event type.
Staking rewards accrue ordinary income at receipt FMV before later disposal.
Mempool-level data is unnecessary; confirmed chain events plus CEX ledgers suffice.
CAP: user-facing report totals are CP in PostgreSQL; chain index is AP with repair jobs.
Idempotent ingest keys combine exchange_id, external_tx_id, and wallet_id.
Tax year partition keeps hot queries bounded during April peak.
Penny drift between Schedule D and sum of 8949 rows fails audit—use integer cents.
OAuth tokens for exchanges live in KMS-wrapped vault with scoped read-only permissions.
CPA multi-user org needs read-only export without write access to basis overrides.
Recompute version bumps when user changes FIFO→HIFO; prior reports stay immutable.
Corporate actions table adjusts lot quantities for splits before disposal matching.
Spam airdrop filter prevents dust attacks from polluting lot queues.
GDPR delete must cascade PII while retaining anonymized audit aggregates where legal.
Interviewers probe whether you separate pricing oracle from lot engine for testability.

Interview metrics to cite

Koinly-class aggregation
multi-chain wallet sync
FIFO/LIFO/HIFO lots
Form 8949 export

Implementation notes

Tax platform SLO for Problem Statement: Crypto Tax Reporting Platform: report build p95 < 3 minutes after sync complete; ingest lag p95 < 10 minutes off-peak.

Basis engine stores amounts in integer cents with currency_code USD for MVP.

Immutable report_version increments when user changes cost basis method.

javaOne Dark Pro

1 public record TaxContext1(String userId, int taxYear, String method) {}

pythonOne Dark Pro

1 def holding_period_days(acquired_ts: int, disposed_ts: int) -> int:
2     return max(0, (disposed_ts - acquired_ts) // 86400)

typescriptOne Dark Pro

1 export function isLongTerm(days: number): boolean {
2   return days > 365;
3 }

Why interviewers care

Crypto Tax Reporting interviews reward crisp scope, explicit trade-offs, and failure stories—not generic microservice diagrams.

Interview checkpoint

Name one failure story for Problem Statement: Crypto Tax Reporting Platform that proves you understand real outages, not happy-path diagrams.

Key Highlights

•Koinly-class aggregation
•multi-chain wallet sync
•FIFO/LIFO/HIFO lots
•Form 8949 export

1	def holding_period_days(acquired_ts: int, disposed_ts: int) -> int:
2	return max(0, (disposed_ts - acquired_ts) // 86400)