update history page

[chadwhitacre]

Fixes #3455.

[chadwhitacre]

I'm thinking about this.

[chadwhitacre]

http://www.ledger-cli.org/

[chadwhitacre]

I'm thinking that Gratipay should be more normal accounting-wise. Double entry.

[chadwhitacre]

I want to avoid a rabbit hole, but can we move in that direction?

[chadwhitacre]

Properly speaking, every ~user, team, and payout exchange route is an account.

[chadwhitacre]

We should probably have an accounts table and a ledger table. Makes me think of:

http://blog.balancedpayments.com/the-ledger/
http://blog.balancedpayments.com/state-machines/

[chadwhitacre]

Though I believe journal would be a better name than ledger:

http://www.accountingcoach.com/blog/general-ledger-general-journal.

[chadwhitacre]

https://en.wikipedia.org/wiki/Ledger
https://en.wikipedia.org/wiki/General_ledger
https://en.wikipedia.org/wiki/General_journal
https://en.wikipedia.org/wiki/Chart_of_accounts

[chadwhitacre]

The ledger is a permanent summary of all amounts entered in supporting journals which list individual transactions by date. Every transaction flows from a journal to one or more ledgers.

https://en.wikipedia.org/wiki/Ledger

The journal is where double entry bookkeeping entries are recorded by debiting one or more accounts and crediting another one or more accounts with the same total amount. [...] In accounting and bookkeeping, a journal is a record of financial transactions in order by date.

https://en.wikipedia.org/wiki/General_journal

[chadwhitacre]

A journal is also named the book of original entry, from when transactions were written in a journal prior to manually posting them to the accounts in the general ledger or subsidiary ledger.

https://en.wikipedia.org/wiki/General_journal

[chadwhitacre]

Let's say we make an accounts table. An account can be associated with more than one type of entity (~user, team, route). How do we model that?

http://stackoverflow.com/questions/7844460/foreign-key-to-multiple-tables

[chadwhitacre]

http://www.accountingtools.com/debits-and-credits

[chadwhitacre]

Accounts such as Cash, Investment Securities, and Loans Receivable are reported as assets on the bank's balance sheet. Deposits are reported as liabilities and include the balances in its customers' checking and savings accounts as well as certificates of deposit. In effect, your bank statement is just one of thousands of subsidiary records that account for millions of dollars in Deposits that a bank owes to its customers.

http://www.accountingcoach.com/debits-and-credits/explanation/4

[chadwhitacre]

"Basics of Escrow Accounting"
http://www.tdi.texas.gov/title/documents/BASICS.pdf

[chadwhitacre]

That's talking about regulated real estate escrow businesses. For our purposes the most relevant information is:

Escrow Accounting Formula

Assets = Liabilities. There is no equity as in the normal accounting formula.

[chadwhitacre]

I am thinking about re-modeling Gratipay using proper double-entry accounting. We would fold both exchanges and payments (as well as the old transfers table) into a single journal table.

Gratipay's escrow would be fundamentally represented by an escrow asset account, offset by multiple ~user liability accounts. Accounts would be defined relative to Gratipay:

association	account	type	notes
	cash	asset
	accounts receivable	asset	enables asynchronous payin routes
	accounts payable	liability	enables asynchronous payout routes
	processing fee revenues	income	payments from our users
	processing fee expenses	expense	payments to our vendors (Braintree, PayPal)
	earned interest	income
	chargeback expenses	expense
participants	~user	liability
teams	Team	liability

We would implement Gratipay's business rules as triggers acting on the journal. So, for example, charging someone's credit card $10.00 would be a single INSERT of $10 into the journal for an account associated with a payin route (which in turn is associated with a ~user), and would result in the following journal entries:

id (~=relative timestamp)	account	debit	credit
1	cash	10.00	null
2	~user	null	10.00
3	~user	0.59	null
4	processing fee revenues	null	0.59

Though I'm not sure why we can't represent that like this:

id	amount	debit	credit
1	10.00	cash	~user
2	0.59	~user	processing fee revenues

[chadwhitacre]

I'm staring at this, btw:

https://en.wikipedia.org/wiki/Debits_and_credits#Aspects_of_transactions

Also leaning heavily on:

http://www.accountingcoach.com/debits-and-credits/explanation/4

[chadwhitacre]

How about this for a fuller schema?

id	amount	debit	credit	parent	route	payday	recorder
1	10.00	cash	~user	null	1	1	null
2	0.59	~user	processing fee revenues	1	null	1	null

Let's have notes in a separate journal_notes table. That way we can have multiple notes on one journal entry, with some of the notes visible to users and others visible only to admins.

[chadwhitacre]

How would we handle exchange status with this schema?

[chadwhitacre]

Exchange statuses would be computable from the journal. Here's what a pending $10.00 payout would look like:

id	amount	debit	credit	parent	route
3	10.00	~user	accounts payable	null	1

Here's what a successful payout would look like:

id	amount	debit	credit	parent	route
3	10.00	~user	accounts payable	null	1
4	10.00	accounts payable	cash	3	1

Here's what a failed payout would look like:

id	amount	debit	credit	parent	route
3	10.00	~user	accounts payable	null	1
4	10.00	accounts payable	~user	3	null

In other words, we'd need to query for child entries in order to compute transaction state. We could cache this computation in an additional journal.status field, and/or we could include a journal.children array in the schema.

[chadwhitacre]

Moving over to #3618.

[chadwhitacre]

Ready for review @rohitpaulk @rorepo @kzisme et al.

[chadwhitacre]

Alright, forging ahead with self-merge ...