[GNC-dev] New balsheet (and P&L report), API considerations, and (slow?) KVP in Account.cpp

Christopher Lam christopher.lck at gmail.com
Tue Aug 14 02:05:16 EDT 2018

Hi John

Thank you - plenty of material here for test cases.

I note your observation that selling a stock at an increased price, in a
book without trading-accounts, without properly booking the capital-gain to
income leads to an incorrect balance-sheet. This is illus by txn-A and
txn-B below. This shouldn't arise -- all cap-gains must be documented
according to documentation - either together with the sell transaction, or
in a separate transaction. So, IMHO the incorrect report as you found out
does not really need fixing.

01-jan-18 Txn-A - buy
Asset:Broker -$10000
Asset:Broker:Stock +100 AAPL (+$10000)

01-jun-18 Txn-B - sell
Asset:Broker +$20000
Asset:Broker:Stock -100 AAPL (-$20000)

01-jun-18 Txn-C - cap-gain
Asset:Broker:Stock 0AAPL (+$10000)
Income:Capital-Gains -$10000

Moreover, about that price-source... I'll try and replicate.

On 13/08/18 22:51, John Ralls wrote:

On Aug 12, 2018, at 10:04 PM, Christopher Lam <christopher.lck at gmail.com>

Hi Jralls

So just wish to double check my understanding of gnucash's data format for
a balance-sheet on date X

There are two possibilities for displaying the right-hand-side

   1. Liabilities + Equity + Retained Earnings + Trading Balances
   2. Liabilities + Equity + Retained Earnings + Unrealized Gains

"Retained Earnings" should be NULL if the user has properly closed the
books on the balance sheet date X.

In my understanding, "Trading Balances" and "Unrealized Gains" are one and
the same -- in balance-sheet.scm the unrealized-gain-collector is only
populated if book->trading-accounts setting is disabled. (btw this causes a
'bug' whereby a book with 'enable-trading-accounts', but was later switched
to 'disable-trading-accounts' will then add both the
unrealized-gain-collector and the trading-balance the right-hand-side).

This seems to be deconstruct current balance-sheet?

(I can't seem to find any unrealized-gain issue... from using different
price-sources... perhaps this is beyond my understanding.)

On 11/08/18 22:41, John Ralls wrote:


Remember that we’ve long advised users that they need not close their
books, they can run a balance sheet report for any day. IMO removing that
capability would be a major breakage.

I suspect that you needed to use trading accounts because you didn’t book
the trading gains and losses as income. Users should do that regardless of
using trading accounts and doing so should make it unnecessary for the
balance sheet report to include trading accounts.

Unrealized gains are another matter entirely and are a result of using
prices from the price database instead of actual cost from the transaction
data. IMO the balance sheet report shouldn’t be taking prices from the
price db and shouldn’t be able to see unrealized gains, but if price source
is going to be an option then an unrealized gains line flows from that so
that users don’t waste a bunch of time chasing an imbalance caused by price

https://bugs.gnucash.org/show_bug.cgi?id=775368 is related because that’s
currently how the balance sheet report gets the “actual” costs.

John Ralls

On Aug 10, 2018, at 11:40 PM, Christopher Lam <christopher.lck at gmail.com>

Hi John

I've managed to make the left-side (activa?) match the right-side (passiva?)


1) it does require closing books on the balance-sheet date

2) it does require adding trading-accounts

The existing balsheet introduces/calculates the "Retained Earnings",
"Trading Gains" and "Unrealized Gains", whereas the current iteration of
new-balsheet will not.

To me this is the easiest method to ensure both sides produce the same
total, and is now technically correct - if the user has not closed their
books, the balance sheet won't balance.

This is giving me a headache :(

Should a new balsheet calculate and report these '(fake) retained
earnings', and 'unrealized gains' ???


On 09/08/18 08:32, John Ralls wrote:

On Aug 8, 2018, at 8:51 AM, Geert Janssens <geert.gnucash at kobaltwit.be>
<geert.gnucash at kobaltwit.be> wrote:

I haven't been following every detail of this. However I note on most
sheets the total assets doesn't match total net worth (or
In most, this is fixed by including the retained earnings.

I believe at least in most European countries the "left hand side" (Assets,
Active) and "right hand side" (Passive or liabilities + equity) of the
multicolumn view should balance (it's called balance sheet for a reason).
That would suggest retained earnings does have to be part of the balance

However I'm not an accountant and perhaps your book is slightly contrived
so I
don't know the exact answer here.

As for the "multi-column" vs one column debate, both present the same data.
The only difference is visual representation or style.

As of recently I have become a strong proponent of separating structure (or
accounting functionality in a different context) from style, I think this
should be delegated to the realm of css. This particular layout variation
IMO be handled by making divs for each large group and either let them
normal flow or use float to move them next to each other. If you will you
have a European style sheet and an American one, or an Australian or

As for "categories", I read Frank's earlier reply as if he agreed that at
least for now the account organization is something to be done in the CoA,
in report code.

The Balance Sheet is indeed supposed to balance, but in normal practice it
balances only when the book is “closed”, i.e. when all of the income and
expense accounts are summed up and added to Equity. In US corporate books
the cumulative total of income and expenses lives in an Equity account
called “Retained Earnings”.

In the pen-and-paper days a  “Trial Balance” was computed outside of the
books before closing as a way to catch errors before making the closing
entries and writing the formal Balance Sheet.

GnuCash's existing Balance Sheet Report creates the “Retained Earnings”
line so that one need not close the books (Tools>Close Book) in order to
get a balanced report. Removing that feature might be more formally correct
but it would mean that users would have to close their book before running
a balance sheet. That would be a big change and I don’t think that we want
to do it. On the other hand “Retained Earnings” isn’t the right term for
many cases, so it would be a useful improvement to make it configurable.

There’s a second problem with the current report as well: If the user does
close their books periodically they’ll have an account for the accumulation
that may well be called “Retained Earnings”. The Balance Sheet Report will
dutifully report the contents of that account and, if there are income and
expenses after the last close, add a second “Retained Earnings” line. That
looks a bit odd and might be confusing; ISTR we’ve had comments on the user
list about just that.


To demonstrate the price difference on assets creating an “Unrealized Gain”
line, I created a fake account with Trading Accounts off and purchased on 1
January 100 shares of a stock for $100, then created a new price for the
stock of $200. The resulting Balance Sheet report is the first screenshot
below. Price source is set to “nearest in time”.

I repeated the process in a new book with trading accounts enabled and got
the second screenshot. As you pointed out, the “Unrealized Gains” line
changes to “Trading Gains”. Selling the stock made no difference on the
report unless I also booked the 10,000 gain to Income:Short Term Cap Gains,
after which the calculated line became “Retained Earnings” as illustrated
by the third screen shot.

I went back and did the sale on the non-trading-accounts book and found
that indeed “Unrealized Gains” didn’t change after I sold the stock; that’s
wrong, it’s a realized gain at that point. Booking the gain to Income
changed the line to “Retained Earnings” as it did with trading accounts
enabled and as expected.

Finally, to illustrate the effect of price source I removed the sell
transaction and changed the price source in report options to “Avg Cost”.
The result is the last screenshot, showing the stock at book value and the
“Unrealized Gains” line at 0.

John Ralls

More information about the gnucash-devel mailing list