# This file documents some recommended practices for dealing # with multi-commodity transactions. # You might want to examine this tutorial that discusses # multiple-commodity double-entry accounting generally; it is quite # useful. # # http://www.mscs.dal.ca/~selinger/accounting/tutorial.html # All the examples in the starter.pny file use dollars as the # commodity. However, Penny is flexible: you can track any commodity # you want. The simple rule is that all transactions must be # balanced--that is, the sum of the debits must be equal to the sum of # the credits. Each posting can have only one commodity. A debit sum # of one commodity must be offset by a credit sum of the same # commodity. So, let's say you buy 100 shares of F for $1 each. The # following transaction is INVALID so it is commented out: # 2012/12/19 Buy stock # Assets:Checking > $100.00 # Assets:Brokerage < 100 F # That transaction is not balanced. The $100 credit needs an # offsetting $100 debit, and the debit of 100 F needs an offsetting # credit of 100 F. Here's the method I recommend: 2012-10-19 Purchase stock Assets:Brokerage < 100 F Assets:Checking > $1000.00 Basis:F:2012-10-19 > 100 F Basis:F:2012-10-19 < $1000.00 # Offsetting your debit and credit against a single Basis account will # allow you to get more useful information out of your ledger file, as # we will see later. By naming the Basis account as shown here (with # the second sub-account being the commodity symbol, and the third # sub-account being the date on which the commodity was purchased) the # penny-selloff program will be able to help you out later when you # sell the commodity. # You will also want to enter a price into your file. The convert # report will use this information. A price tells the convert report # how to convert one commodity to another. Prices have no effect on # any other Penny report. For instance this price expresses the price # of the prevoius transaction: @ 2012-10-19 F $10.00 # This means that one unit of F is equivalent to $10.00. Prices only # work one way; that is, the price above does NOT tell Penny that # $10.00 is equivalent to one unit of F. If you wanted to express # that, include another price. It is only possible to express that ONE # unit of some commodity is equal to some number of units of another # commodity. For instance, this price would be invalid: # # @ 2012-10-19 100F $1000.00 # Any transaction that has two commodities will have at least four # postings. This is because all transasctions in Penny must always be # balanced, and every debit balance must be offset with a credit # balance of the exact same commodity. # A month later I sell my stock. Let's say it has done very well. 2012-11-19 Sell stock Assets:Brokerage > 100 F Assets:Checking < $1400.00 Basis:F:2012-10-19 < 100 F Basis:F:2012-10-19 > $1400.00 # And a corresponding price: @ 2012-11-19 F $14.00 # At this point, Basis:F:2012-10-19 has a credit balance of # $400.00. This is your capital gain from the sale. You probably want # to close out the Basis:F:2012-10-19 account by transferring its # balance to an income account. (You could even do this in the same # transaction as the stock sale.) 2012-11-19 Capital Gain Basis:F:2012-10-19 < $400.00 {Income:Capital Gain:F:2012-10-19} > $400.00 # That's one way to do it. It's simple enough when you just have # one lot of stock. What if you have a bunch of different lots? # This can happen with dividend reinvestment especially. Here's # an example: 2012-10-19 Purchase stock Assets:Brokerage < 100 LUV Assets:Checking > $1000.00 Basis:LUV:2012-10-19 > 100 LUV Basis:LUV:2012-10-19 < $1000.00 2012-11-19 Purchase stock Assets:Brokerage < 100 LUV Assets:Checking > $1200.00 Basis:LUV:2012-11-19 > 100 LUV Basis:LUV:2012-11-19 < $1200.00 2012-12-19 Purchase stock Assets:Brokerage < 100 LUV Assets:Checking > $1400.00 Basis:LUV:2012-12-19 > 100 LUV Basis:LUV:2012-12-19 < $1400.00 # Okay, time to sell. Get rid of all the LUV. To get the capital gain # right, it must be distributed amongst all the LUV purchases. You # could do this yourself but who wants to? So enter a transaction # like this first: 2012-12-31 Sell stock Assets:Brokerage > 300 LUV Assets:Checking < $4800.00 Proceeds:LUV:2012-12-31 < 300 LUV Proceeds:LUV:2012-12-31 > $4800.00 # At this point your assets and brokerage accounts look good. If you # don't care about capital gains, you can just stop here. But if you # want to close out the Basis accounts, you can use the penny-selloff # program. It creates transactions for you, which you can append to # your Penny file. You pass penny-selloff two arguments: first, the # name of the Proceeds account, and second, the filename to draw from. # penny-selloff 'Proceeds:LUV:2012-12-31' filename # penny-selloff will use all transactions from all the filenames # given. First it will make sure that the given Proceeds account has a # balance that consists of a debit amount and a credit amount with # differing commodities. penny-selloff takes the debit amount to be # the commodity you are selling off, and the credit amount of the # balance is the amount you received in the sale. # penny-selloff then takes the second sub-account from the given # account. Here, it is LUV. It then looks for accounts named # Basis:SUB-ACCOUNT:***. Here it looks for Basis:LUV:***. *** is a # Penny date (and optional time.) All of these accounts that have a # balance are totaled up. This total balance must have a credit # balance that is greater than or equal to the debit balance of the # Proceeds account, and a debit balance whose commodity is the same # commodity as the credit balance of the Proceeds account. # penny-selloff then computes a per-share price of the proceeds and # calculates sale postings for each Basis account that has a # balance. Shares are sold off on a FIFO (first-in, first-out) basis, # so the oldest available shares are sold first. blah blah blah blah # so for example, with the above transactions, running # penny-selloff 'Proceeds:LUV:2012-12-31' stocks.pny # will create a posting that looks like this: ;transaction created by penny-selloff for sale on 2012-12-31 2012-12-31 Realize gain or loss Proceeds:LUV:2012-12-31 < $ 4800.00 Proceeds:LUV:2012-12-31 > LUV 300 Basis:LUV:2012-10-19 < LUV 100 Basis:LUV:2012-10-19 > $ 1000.00 {Income:Capital Gain:LUV:2012-12-31:2012-10-19} > $ 333.33 Basis:LUV:2012-11-19 < LUV 100 Basis:LUV:2012-11-19 > $ 1200.00 {Income:Capital Gain:LUV:2012-12-31:2012-11-19} > $ 400.01 Basis:LUV:2012-12-19 < LUV 100 Basis:LUV:2012-12-19 > $ 1400.00 {Income:Capital Gain:LUV:2012-12-31:2012-12-19} > $ 466.66 # Thus the capital gain shows up in the Capital Gain account, and all # the Basis accounts and the Proceeds account have zero balances. # You could also track commodities other than stocks. Let's say you # buy a house. 2012-12-31 Buy a house {Assets:Real Estate} < HouseA 1 Liabilities:Mortgage > $ 80 000.00 Assets:Savings > $ 20 000.00 'Down payment Basis:House1:2012-12-31 > HouseA 1 Basis:House1:2012-12-31 < $ 100 000.00 @ 2012-12-31 HouseA $100 000.00 # And some more stock purchases that we can use as examples in the # penny-commodities man page: 2012-09-17 Buy stock Assets:Brokerage < 100 YHOO Basis:YHOO:2012-09-17 > 100 YHOO Assets:Checking > $1568.00 Basis:YHOO:2012-09-17 < $1568.00 @ 2012-09-17 YHOO $15.68 2012-11-16 Buy stock Assets:Brokerage < 100 YHOO Basis:YHOO:2012-11-16 > 100 YHOO Assets:Checking > $1786.00 Basis:YHOO:2012-11-16 < $1786.00 @ 2012-11-16 YHOO $17.86 2012-12-18 Buy stock Assets:Brokerage < 100 YHOO Basis:YHOO:2012-12-18 > 100 YHOO Assets:Checking > $1982.00 Basis:YHOO:2012-12-18 < $1982.00 @ 2012-12-18 YHOO $19.82 @ 2012-12-20 YHOO $19.69 # And your house is going up in value: @ 2013-01-01 HouseA $101 000.00 @ 2013-06-01 HouseA $102 000.00 # And an example involving the purchase and sale of stock: 2012-01-03 Buy stock Assets:Brokerage < 100 UNP Assets:Checking > $10800.00 Basis:UNP:2012-01-03 > 100 UNP Basis:UNP:2012-01-03 < $10800.00 2012-12-28 Sell stock Assets:Brokerage > 100 UNP Assets:Checking < $12354.00 Basis:UNP:2012-01-03 < 100 UNP Basis:UNP:2012-01-03 > $12354.00 # Here is another example of a sale using a Proceeds account: 2012-01-03 Buy stock Assets:Brokerage < 100 C Assets:Checking > $3072.00 Basis:C:2012-01-03 > 100 C Basis:C:2012-01-03 < $3072.00 2012-12-03 Sell stock Assets:Brokerage > 100 C Assets:Checking < $3901.00 Proceeds:C:2012-12-03 < 100 C Proceeds:C:2012-12-03 > $3901.00