Double Entry Accounting #4

rafabap · 2017-02-26T00:56:48Z

Hybrid accounting system that uses inventories and double-entry accounting.

The Double-entry is simplified so that it uses only stock accounts (ASSETS, LIABILITIES, EQUITY) and ignores flow accounts (INCOME, EXPENSES). Each account has an inventory of contracts.

Each account can hold only one type of contract in its inventory.

The Agents interact with their accounts via a Book, that provides a series of operations given in BookAPI.

Made changes to ensure a one-to-one mapping between accounts and contract types

davidrpugh · 2017-02-26T11:44:40Z

@rafabap Let's start with the Book interface. First, I do not understand the terminology. A Book seems to be a collection of Account (or Contract) objects in which case why not call this a BalanceSheet? Second if a Book is just a collection of contracts then I think we should only allow adding/removing of contracts from the Book as well as valuing assets liabilities and equity. Logic for updating the value of a particular contract should be pushed elsewhere.

Excuse the Scala, but something like the following...

abstract class Contract {
  
  /** agent for whom the contract is a liability */
  def issuer: Agent

  /** agent for whom the contract is an asset */
  def counterparty: Agent

 /** Objective value of a contract */
  def faceValue: Double

} 


/** Immutable storage container for a particular agent's contracts. */
class BalanceSheet[+C <: Contract] private(agent: UUID, contracts: GenSet[C] ) {

  /** Returns a new BalanceSheet with an additional contract .*/
  def add[C1 >: C](contract: C1): BalanceSheet[C1] = {
    new BalanceSheet(agent, contracts + contract)  
  }

  /** Returns a new BalanceSheet after removing a particular contact. */
  def remove(contract: C): BalanceSheet[C] = {
    new BalanceSheet(agent, contracts - contract)
  } 

  /** Collection of contracts that are assets. */
  def assets: GenSet[C] = {
    contracts.filter(contract => contract.counterparty == agent)
  }

  /** Collection of contracts that are liabilities. */
  def liabilities: GenSet[C] = {
    contracts.filter(contract => contract.issuer == agent)
  }

  /** The value of equity is just the difference between the value of assets and the value of liabilities. 
     * @note the value of equity is subjective and depends on the value function `v` used to value the 
     * underlying contracts.
     */
  def equity(v: (Contract) => Double): Double = {
    assets.map(v).sum - liabilities.map(v).sum
  }

  /** Leverage ratio */
  def leverage(v: (Contract) => Double): Double = {
    assets.map(v).sum / equity(v)
  }
  
}

davidrpugh · 2017-02-26T11:47:09Z

@rafabap I am also confused about the difference between Contract and an Account.

davidrpugh · 2017-02-26T11:56:06Z

My most general comment is that I find the terminology very confusing. I generally do not think of Asset, Liability and Equity as being types of Accounts. But might just be me.

I guess you could have something like...

class DepositAccount private(issuer: UUID, counterparty: UUID, initialDeposit: Double) extends Contract {
  val faceValue = initialDeposit

  def debit(value: Double): DepositAccount = {
    new DepositAccount(issuer, counterparty, initialDeposit - value)
  } 

  def credit(value: Double): DepositAccount = {
    new DepositAccount(issuer, counterparty, initialDeposit + value)
  }

}

val agent: UUID = ???
val bank: UUID = ???

val deposit = DepositContract(bank, agent, 1e6)

in the above

davidrpugh · 2017-02-26T12:07:10Z

@rafabap I just realized that Book used to be called Ledger! I much prefer Ledger as it makes good use of standard accounting terminology (which has been picked up by the blockchain community which I think is useful).

davidrpugh · 2017-02-26T12:23:00Z

@rafabap Some specific comments about the Account class.

Is the account name supposed to uniquely identify the account? If so, then perhaps better to use UUID then String for the type.
Why use an Enum to model different account types? Is the Enum values just to allow you to switch behavior depending on account type?
Where does the Action type imported from? Is this a Java type? Or has this ours?

davidrpugh · 2017-02-26T15:57:22Z

@rafabap Perhaps my lack of comfort with your terminology stems from my being used to Perry Mehrling's terminology. I am reading through the Double-Entry Book-Keeping Wikipedia entry to try and familiarize myself with your terms. Is this the best source?

rafabap · 2017-02-26T17:44:17Z

@davidrpugh sorry for the confusion! Just a few pints to clarify:

double-entry
The Wikipedia article is one of the best resources I've found. The problem is that although the rules are consistent across sources, the terminology isn't!
I'm happy to go back to using Ledger rather than Book.

The types of Account only matter when defining the sign of debits and credits.

double entry vs Inventories

I see our accounting system as a hybrid composed of two parts. The first is the double entry rules, which requires separate accounts implementing their debits and credits. The second is the inventory: a way to keep lists of contracts.

My solution is to combine the two by starting with a standard double-entry ledger havjng a few accounts, and then rather than having a single inventory for the agent, I split it in smaller inventories, each associated to one account. In addition, for clarity, I force that each account includes only one type of contract in its inventory.

prauwolf · 2017-02-27T09:11:43Z

Account.java

+
+    private double balance;
+
+//    private Collateral collateralType;


remove commented variables, unless it is a discussion point whether or not to add them.

prauwolf · 2017-02-27T09:15:35Z

Account.java

+    protected HashSet<Contract> contracts;
+
+
+    void addContract(Contract contract) {


is it intentional that these functions scope are the Java default? It's likely that's best, but I didn't know if some, like addContract, should be public?

prauwolf · 2017-02-27T09:16:00Z

Account.java

+        return availableActions;
+    }
+
+//    public void setCollateralType(Collateral collateralType) {


prauwolf · 2017-02-27T09:17:02Z

Account.java

+    String getName() {
+        return name;
+    }
+}


Should there be a removeContract functionality?

prauwolf · 2017-02-27T09:17:35Z

Account.java

+    String getName() {
+        return name;
+    }
+}


Should the user be able to pull a list of the existing contracts in the contract hashSet?

prauwolf · 2017-02-27T09:41:31Z

Book.java

+        }
+
+        // (dr asset, cr equity)
+        assetAccount.debit(contract.getValue());


Do contracts have a 'getValue()'? Perhaps they should, if they don't. We should discuss contract valuation and how it relates to this system.

I'm not sure if valuation shouldn't be external to the contract, e.g. by means of a function that accepts a contract and returns a value. If it is internal to the contract, then it will be difficult to have different types of valuation. Also, if valuation is done in a more functional way, it will become easier to plug together more complex types of valuation. But that's probably a separate discussion.

prauwolf · 2017-02-27T09:42:58Z

Book.java

+        Account liabilityAccount = liabilityAccountsMap.get(liabilityType);
+
+        //Todo: What do we do if we can't pay??!! At the moment I'm calling my owner to raise liquidity
+        if (cashAccount.getBalance() < amount) {


We should probably decide how we're going to deal with errors in the library.

@prauwolf Agreed. I don't know much about the Java conventions regarding checked vs unchecked exceptions, etc. I think we need some kind of LiquidityException that will be thrown in the event that an agent does not have liquid resources available to make required payments. Ideally this would also be expressed in the return type of the method (which would force the caller of the method to explicitly deal with the possibility that an exception would be returned.

prauwolf · 2017-02-27T09:44:20Z

Book.java

+     * If I've sold an asset, debit cash and credit asset
+     * @param amount the *value* of the asset
+     */
+    public void sellAsset(double amount, Class<? extends Contract> assetType) {


As implemented, what class should be calling 'sellAsset'?

prauwolf · 2017-02-27T09:45:34Z

Book.java

+     * @param me the owner of the Book
+     * @return an ArrayList of Actions that are available to me at this moment
+     */
+    public ArrayList<Action> getAvailableActions(Agent me) {


Let's discuss actions in the code review. I really like the idea. Perhaps we should have some kind of interface which defines a list of actions, since we'd probably use them in a variety of contexts.

prauwolf · 2017-02-27T09:46:13Z

Book.java

+
+        for (Contract contract : assetAccount.contracts) {
+            Asset asset = (Asset) contract;
+            if (asset.priceFell()) {


Can you explain this in a bit more detail in the review?

bherd · 2017-02-27T10:12:40Z

Book.java

+        assetAccounts = new HashSet<>();
+        liabilityAccounts = new HashSet<>();
+        equityAccounts = new HashSet<>();
+


Is it strictly necessary to have different hash sets holding the same account objects? Although (I think) Java stores values by reference, I fear there might be situations where, for some reason, the account object gets copied and thus ends up being 'forked'.

Would it be better to use just one single data structure accounts and use clever access functions to get and set the type of content that is relevant? For example, to return all accounts from accounts in a lazy way (i.e. as a stream), you could define the following function (sorry, haven't checked if it compiles):

Stream<Object> getAccounts() { return accounts.entrySet().stream.map(Map.Entry::getValue); }

To return all accounts of a particular type, you could define the following function:

Stream<Object> getAccountsOfType(AccountType t) { return accounts.entrySet().stream().filter(entry -> entry.getKey() == t).map(Map.Entry::getValue); }

In order to turn the streams into lists, you could also define a general function:

List<?> toList(Stream<Object> s) { return s.collect(Collectors.toList()); }

The same could, of course be done in the opposite direction, i.e. to set objects in the map. You could then get rid of the other data structures and only keep a single source of truth.

As I said, I haven't checked whether the snippets compile, so please take them with a pinch of salt :)

bherd · 2017-02-27T10:14:43Z

Book.java

+        // These hashmaps are used to access the correct account for a given type of contract.
+        // Note that separate hashmaps are needed for asset accounts and liability accounts: the same contract
+        // type (such as Loan) can sometimes be an asset and sometimes a liability.
+        assetAccountsMap = new HashMap<>();


General question: is thread safety an issue at this point in time? If yes, then this would require some sort of synchronisation, because HashMaps and HashSets are (as far as I'm aware) not thread-safe.

davidrpugh · 2017-02-27T13:19:33Z

@rafabap and @bherd Based on our discussion today we decided to move forward with a message passing solution for handling interaction between Ledger / Book and Transactions, etc. I think we should take a hard look at Akka. Existence of widely used Java and Scala APIs is nice and using the Actor model as our concurrency solution will help constrain our design space in general...

Made a static, legal `doubleEntry(Account debitAccount, Account creditAccount, double amount)` function

A `Ledger` now has: - a set of `Account`s - two sets of `Contract`s to act as inventory (one for assets and one for liabilities) By splitting the inventory from the accounts, I have avoided issues to do with searching of the inventories etc. The invariants maintained: - each `Account` corresponds to one type of `Contract`, and the sum of the value of the contracts of that type equals the balance of the account. This invariant is not hard-coded but will be. - Assets = Liabilities + Equity (guaranteed by the double entry)

rafabap · 2017-03-07T15:05:14Z

Hi all, I have implemented most of the comments received so far and during the code review. The concurrent implementation of the Ledger is left for a future date.

I have followed David's advice and decided to split the inventories from the Accounts. Therefore, a Ledger has, on the one hand, a set of accounts; and on the other hand, an inventory of contracts (the inventory is split into assets and liabilities for convenience).

Searching etc. of the inventory is done using functional calls as suggested by Ben.

The invariants provided by the framework are:

Assets = Liabilities + Equity, as guaranteed by the double entry
For each type of Contract, there exists an Account associated with it. The invariant is that the sum of the value of all contracts of that type is equal to the balance of the account. This invariant is not hard-coded yet.

rafabap added 4 commits February 10, 2017 10:53

Added accounting files

aa2ab65

One account <=> One Contract Type

c3b561b

Made changes to ensure a one-to-one mapping between accounts and contract types

Delete Ledger.java

2ac4b8b

Delete Collateral.java

a8299c2

prauwolf reviewed Feb 27, 2017

View reviewed changes

bherd reviewed Feb 27, 2017

View reviewed changes

rafabap added 2 commits February 27, 2017 14:40

Private debit/credit, created doubleEntry function

e78734e

Made a static, legal `doubleEntry(Account debitAccount, Account creditAccount, double amount)` function

rafabap added 2 commits March 7, 2017 15:24

Deleted Book

cb9c049

Deleted BookAPI

d225f11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Double Entry Accounting #4

Double Entry Accounting #4

rafabap commented Feb 26, 2017

davidrpugh commented Feb 26, 2017

davidrpugh commented Feb 26, 2017

davidrpugh commented Feb 26, 2017 •

edited

Loading

davidrpugh commented Feb 26, 2017

davidrpugh commented Feb 26, 2017

davidrpugh commented Feb 26, 2017

rafabap commented Feb 26, 2017

prauwolf Feb 27, 2017

prauwolf Feb 27, 2017

prauwolf Feb 27, 2017

prauwolf Feb 27, 2017

prauwolf Feb 27, 2017

prauwolf Feb 27, 2017

bherd Feb 27, 2017

prauwolf Feb 27, 2017

davidrpugh Feb 28, 2017

prauwolf Feb 27, 2017

prauwolf Feb 27, 2017

prauwolf Feb 27, 2017

bherd Feb 27, 2017 •

edited

Loading

bherd Feb 27, 2017

davidrpugh commented Feb 27, 2017

rafabap commented Mar 7, 2017


		private double balance;

		// private Collateral collateralType;

		protected HashSet<Contract> contracts;


		void addContract(Contract contract) {

Double Entry Accounting #4

Are you sure you want to change the base?

Double Entry Accounting #4

Conversation

rafabap commented Feb 26, 2017

davidrpugh commented Feb 26, 2017

davidrpugh commented Feb 26, 2017

davidrpugh commented Feb 26, 2017 • edited Loading

davidrpugh commented Feb 26, 2017

davidrpugh commented Feb 26, 2017

davidrpugh commented Feb 26, 2017

rafabap commented Feb 26, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bherd Feb 27, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidrpugh commented Feb 27, 2017

rafabap commented Mar 7, 2017

davidrpugh commented Feb 26, 2017 •

edited

Loading

bherd Feb 27, 2017 •

edited

Loading