My broker said I'd made $18,000. The number was an aggregate over a query nobody could show me.

Steffan Kharmaaiarvi — Mon, 31 Aug 2026 16:00:00 +0000

The number sat on my broker's home screen, green, precise to two decimals. Roughly eighteen thousand dollars, earned from investing, over the whole period I'd been at it.

I looked at it for a long time and realised I didn't know what it included.

Dividends — reinvested ones, or only the ones that landed as cash? Before or after the tax withheld in a country I don't live in? Closed positions, or only open ones? Fees? Measured from my first-ever deposit, or from the day I opened this account and transferred everything across?

Each of those moves the number. Some move it by thousands.

That's a familiar shape if you write software: an aggregate whose query you can't see. I spent a while looking for the drill-down and eventually understood there wasn't one to find. The breakdown didn't exist. Nobody was keeping the events — not the broker, not my spreadsheet, not any of the tools I tried.

I'm a self-taught engineer, 24, and I've been contributing to a portfolio monthly for years with financial independence as the actual goal. The strategy is unfashionably boring — broad market exposure, automatic monthly transfer, reinvest, don't touch it — and it worked. The portfolio reached six figures through contributions and time, not through a trade that went right.

Then my income changed, my contributions got uneven, and the balance stopped functioning as feedback. It still went up. But "the balance went up" now had at least four meanings that demanded different responses from me:

I contributed a lot, the market was flat.
I contributed almost nothing, the market carried it.
I contributed steadily and both worked.
I contributed nothing, the market fell, and dividends plus a favourable exchange rate papered over it.

One number, four stories, no way to tell them apart. So I started reconstructing the events by hand, and found five bugs — not in any one product, but in the data model almost all of them share.

Bug 1: the balance is a materialized view with no source table

Every tool I used stored the same thing: a set of positions with prices. Current holdings, current value, correct to the cent.

That model throws away most of what happened. My portfolio didn't stay the same shape — I spent a few years pursuing dividend income toward a $500/month target, then came round to the view that during accumulation, income you immediately reinvest is mostly a taxable event with extra steps. What I converged on was simpler: a global accumulating fund as the core, short-term treasuries, gold.

Look at my holdings today and you'd conclude I'd always been a three-fund accumulator. That's false, and it means the actual history — including the parts I got wrong — isn't learnable from the data.

A holdings screen is a snapshot of the conclusion. I wanted the working:

positions  ← what every tracker stores
   ↑
   │  fold(events)
   │
events     ← what nobody stores
  deposit, buy, sell, dividend, fee,
  withholding, fx_conversion, residence_change

Positions are derivable from events. Events are not derivable from positions. Once you write it that way the direction of the arrow settles the design argument. Contributions in particular stop being a bookkeeping entry that makes the pie bigger and become a first-class record: dated, distinguished from reinvested income, with rhythm, streaks and gaps visible.

Bug 2: `return` is not one function, and two correct implementations disagree on the sign

This is the one that turned a preference into a real problem. I computed my return one way, then another way, and got a different answer — not slightly different, opposite sign.

Minimal reproduction:

Date	Event	Portfolio value
1 Jan	Deposit $1,000	$1,000
1 Jul	Holdings up 50%	$1,500
1 Jul	Deposit $9,000 — the plan is working	$10,500
31 Dec	Holdings fall 10%	$9,450

Time-weighted return — what funds and indices publish — deliberately cancels out the effect of deposit timing by chaining sub-period returns between cash flows:

def twr(sub_period_returns):
    """Geometric chain. Deposit timing has no effect by construction."""
    growth = 1.0
    for r in sub_period_returns:
        growth *= (1 + r)
    return growth - 1

twr([0.50, -0.10])   # 0.35  → +35%

Money-weighted return — XIRR — dates every cash flow and solves for the rate that discounts them to zero:

def xnpv(rate, flows):          # flows: [(date, amount)], deposits negative
    t0 = flows[0][0]
    return sum(a / (1 + rate) ** ((d - t0).days / 365.0) for d, a in flows)

def xirr(flows):                # bisection: no derivative, no divergence
    lo, hi = -0.9999, 10.0
    for _ in range(200):
        mid = (lo + hi) / 2
        if xnpv(mid, flows) > 0: lo = mid
        else:                    hi = mid
    return (lo + hi) / 2

xirr([(jan1, -1_000), (jul1, -9_000), (dec31, 9_450)])
# -0.0978 with ACT/365 to 31 Dec; -0.0973 measured over a full year → −9.7%

Both are correct. The strategy had a great year; the investor lost $550, because 90% of the money only showed up for the bad half.

A tracker that renders one of these and labels it "your return" is answering a question you may not have asked. I don't think that's dishonesty — it's compression. One percentage is a nicer product decision than two percentages and an explanation. But the compression is exactly where the information I wanted was going.

Once I saw it the whole vocabulary came apart. There are at least four distinct things called "return":

Unrealized gain — revaluation of what I still hold, against what I paid. Says nothing about anything sold, nothing about income.
Realized gain — what I locked in by closing positions. Real, spendable, usually taxable somewhere.
Personal return (XIRR) — the annualised rate my actual money earned, each deposit weighted by how long it was invested. The only common metric that admits a January deposit and a December deposit are not equal contributors to the year.
Portfolio return (TWR) — how the strategy performed with flows removed. The only one comparable to an index, because it's the only one not contaminated by how much money happened to be in at the time.

For an uneven contributor, the gap between the last two isn't noise, it's the finding. A wide divergence means the timing of my contributions, not my fund choices, dominated the year. That's actionable in a way neither number is alone.

Bug 3: rates applied at read time instead of event time

Classic temporal-data mistake, and it's everywhere in this domain.

If a tool converts a contribution I made three years ago at today's exchange rate, my savings history silently resizes itself every time the currency moves. I open the app in March and I contributed $47,000 lifetime; I open it in June and I contributed $44,100. I did not withdraw anything.

# wrong: history is recomputed against the present
total = sum(f.amount * fx_rate_now(f.currency) for f in flows)

# right: a flow is stamped at the rate on its own date; only
# what you hold today is valued at today's rate
total = sum(f.amount * f.fx_rate_at_trade_date for f in flows)

Same rule as storing a price with an order line instead of joining to the product table at render time. Sounds pedantic until you've watched your own record of what you contributed change while you weren't looking, and had to decide which version to believe.

Bug 4: tax is a function of three variables, and one of them is time

Here's the part I got most wrong at the start.

I assumed a fund is a fund: pick the index, find the cheapest vehicle tracking it, buy it. Ticker and expense ratio, done. Inside a single country that's correct advice. Across borders it isn't, because a foreign dividend can pass through two independent tax layers.

Step one, at source. The fund's country takes its cut before the money leaves. For a non-US investor in a US-domiciled fund the statutory US rate is 30%; a treaty commonly reduces that to 15%, but only where your broker holds valid documentation for you, and that paperwork expires.

Step two, at home. Your country of residence then taxes the same dividend under its own rules.

The steps are independent, which produces the result that surprises everybody: moving somewhere with no dividend tax does not make step one disappear.

Step one alone, on an illustrative portfolio throwing off $571/year in dividends from US-domiciled funds:

Tax residence	US treaty status	Withheld at source	Reaches you
United Arab Emirates	No US tax treaty	30% · $171	$400
Portugal	Treaty rate on portfolio dividends	15% · $86	$485
Germany	Treaty rate on portfolio dividends	15% · $86	$485

Same funds, same amounts, same dates. Different residence. Eighty-five dollars a year before anyone has picked a single stock, recurring annually.

So the withholding rate isn't a column on the instrument. It's rate(fund_domicile, tax_residence, as_of_date) — and as_of_date matters because people move. When residence changes the portfolio doesn't move; not one share changes hands. But the rate on every future dividend changes, and sometimes what you're permitted to buy changes too. The honest answer to "how much tax did this portfolio lose?" is the rate that applied at the time, changing partway through, applied to the dividends actually paid in each period.

There's an elegant wrinkle: an Irish-domiciled UCITS fund holding US stocks pays 15% at the fund level under the US–Ireland treaty, and Ireland charges nothing further on distributions to non-residents. So an investor in a country with no US treaty can end up at 15% instead of 30% on the same underlying index, purely because of where the fund is registered.

The obvious conclusion is that everyone outside the US should hold Irish UCITS. I believed that for about a week, then ran it per holding, and it fell apart:

switch A:  net  +$32/yr   worth doing
switch B:  net   −$7/yr   the fund barely pays dividends, so there was
                          almost no withholding to save — and the UCITS
                          alternative's higher expense ratio is charged
                          against the entire position, not just the income

Counting only tax saved makes every row look free. The tax saving scales with dividend yield; the expense-ratio penalty scales with your entire balance. Different denominators. Which wins depends on the fund, your portfolio size, your residence, and the fund's own costs — and it can flip as the position grows. Lower withholding doesn't mean better; it means one term in the equation improved.

Bug 5: the state transition nobody emits an event for

A non-US person's estate can be exposed to US estate tax on US-situs assets above $60,000 — a category that includes US-domiciled ETFs and individual US stocks — at rates reaching 40% on the excess. Not income tax. Estate tax. Whether it bites, and how hard, depends on treaty coverage, available deductions, how assets are held, and the circumstances of the estate. It's a line worth knowing you've crossed, not a bill anyone can compute for you.

A long-term index investor crosses it in an ordinary month of an ordinary year. No email, no warning, no change of state anywhere — because from the dashboard's point of view nothing happened. The threshold isn't in the model, so no event fires.

I'd crossed it long before I knew it existed.

The rule I ended up caring about most

When a metric can't be computed, say so. Never print a zero.

# a hole in the history and a genuine zero must not render identically
@dataclass
class Metric:
    value: Decimal | None
    confidence: Literal["exact", "approximate", "unavailable"]
    reason: str | None      # "no valuation recorded around 2024-03-11 cash flow"

TWR needs a portfolio valuation around every external cash flow. Where one is missing, the standard workaround is an approximation — and it should be labelled as an approximation, not blended into a headline figure. You cannot reconstruct a valuation nobody recorded. I tried.

What I built

BorderFolio — a contribution-first portfolio tracker for long-term international investors. Statements in (PDF, CSV, a screenshot of a broker app, or typed by hand), history out. No broker credentials and no permanent connection, because I didn't want to hold anyone's login, including my own.

It keeps contributions as a first-class record, splits the result into its actual components (contributions, market growth, income, fees and withholding, realized and unrealized), reports personal return and portfolio return side by side, keeps monthly snapshots so the past stays the past, and resolves withholding per instrument from fund domicile and configured residence — showing both sides of a structural switch, not just the flattering one.

What it can't do, out loud: it's statement-import based rather than live API, so you upload something once a month. Every calculation is only as good as the records imported, and a missing statement is a hole the tool shows rather than interpolates over. The portfolio-return number genuinely improves as monthly history accumulates, and I can't make that instant. The cross-border figures are informational estimates from published treaty rates and fund documents — not tax advice, and blind to your personal circumstances. Nothing in it, including my own portfolio's shape, is a recommendation.

The free tier is enough to see whether the idea holds up on your own numbers.

What I'd most like from this crowd is the thing this domain punishes hardest: a number that's confidently, plausibly, quietly incorrect. The interesting failures in a tool like this aren't crashes. If you find one, I want to know about it more than I want a signup — admin@borderfolio.app, or in the comments.

The full arithmetic behind all four return metrics, with worked examples, is in how to track portfolio performance. The two-step withholding model and how each rate is resolved is in the methodology.

BorderFolio provides informational portfolio analytics only. Nothing here is investment, financial, legal or tax advice, and no figure in this article is a recommendation to buy, sell or hold any security. Illustrative figures are exactly that. Tax rules change and depend on individual circumstances — verify anything that matters with a qualified adviser in your jurisdiction.

DEV Community: Steffan Kharmaaiarvi