Accounts - datacratic/rtbkit GitHub Wiki

Account Structure and Constraints

Accounts consist of a number of Currency Pools and can have one parent and multiple children, meaning that they can be arranged in a tree structure.

A Currency Pool is either a credit pool or a debit pool except for the balance pool, which is computed to equal sum(credit) - sum(debit).

Currency pools only ever increase in value and start at zero: in order for currency to enter an Account, a credit pool must increase, and in order for currency to exit an Account, a debit pool must increase.

Operations which reflect currency moving around must increase a credit and a debit pool by equal amounts. In general, currency does not move around within an Account but rather within an Account tree, so the credit and debit pools being increased will be in different Accounts, specifically between accounts that have a parent/child relationship.

Currency Pools per Account

Here is a list of the credit and debit Currency Pools per Account, and are accessible via the REST API call GET /v1/accounts/:

Credit Debit
budgetIncreases budgetDecreases
allocatedIn allocatedOut
recycledIn recycledOut
commitmentsRetired commitmentsMade
adjustmentsIn adjustmentsOut
spent

Derived Currency Pools per Account tree

From these, we can derive some Currency Pools per Account tree which have useful external meaning, and are accessible via the REST API call GET /v1/accounts//summary:

  • tree.inFlight
    • = sum(commitmentsMade) - sum(commitmentsRetired)
    • total value of all outstanding bids
  • tree.spent
    • = sum(spent)
    • total recorded spent
  • tree.adjustments
    • = sum(adjustmentsIn) - sum(adjustmentsOut)
    • total adjustments made to spent
  • tree.adjustedSpent
    • = tree.spent - tree.adjustments
    • total recorded spent after adjustments (adjustmentsOut count as additional spent, adjustmentsIn count as negative spent)
  • tree.budget
    • = budgetIncreases - budgetDecreases
    • maximum spendable amount according to calls to setBudget()
  • tree.effectiveBudget
    • = sum(budgetIncreases) - sum(budgetDecreases) + sum(recycledIn) - sum(recycledOut) + sum(allocatedIn) - sum(allocatedOut)
    • maximum spendable amount according to internal sums. Should match tree.budget but may be very slightly out of sync (on the order of 0.01%) due to crashes etc
  • tree.available
    • = tree.effectiveBudget - tree.adjustedSpent - tree.inflight = sum(balance)
    • remaining spendable amount in tree

Operations to move currency within an Account tree

(i.e. within a parent/child relationship):

  • child.setBalance:
    • if the balance being set is lower than the current balance, then this will increase the child.recycledOut and parent.recycledIn
    • if the balance being set is higher than the current balance, this will increase child.recycledIn and parent.recycledOut
      • if that is not sufficient, will then increase child.budgetIncreases and parent.allocatedOut
  • child.recuperateTo
    • this will increase child.recycledOut and parent.recycledIn such that child.balance becomes 0

Operations to move currency into or out of an Account tree

  • account.setBudget:
    • should be called only on a root account
    • either budgetIncreases or budgetDecreases increases
    • implicitly increases or decreases tree.budget and tree.available
  • account.authorizeBid:
    • should only be called on a router account when a bid is made
    • commitmentsMade increases
    • implicitly decreases tree.available and increases tree.inFlight
  • account.cancelBid:
    • should only be called on a router account when a bid is cancelled
    • commitmentsRetired increases
    • implicitly decreases tree.inFlight and increases tree.available
  • account.commitBid:
    • should only be called on a post-auction-loop account when a bid response is received (win or loss)
    • commitmentsRetired increases and spent optionally increases by a smaller amount
    • implicitly decreases tree.inFlight and increases tree.available and can increase tree.spent and tree.adjustedSpent
  • account.addAdjustment:
    • this is used rarely, and only to reflect spend that has been mis-recorded due to known errors
    • either adjustmentsIn or adjustmentsOut increases
    • implicitly increases or decreases tree.adjustments, tree.adjustedSpent and tree.available
  • account.importSpend:
    • this is used only for administrative actions
    • spent increases
    • implicitly increases tree.spent and tree.adjustedSpent and decreases tree.available

Graphical Representation of Operations

In the image below you can see how currency flows down from the tree.budget Currency Pool at the top to the Budget Account via setBudget, then to the Router Spend Account via setBalance, to the tree.inFlight Currency Pool via authorizeBid, then to the Post-Auction Loop Spend Account and eventually to the tree.spent Currency Pool via commitBid.

Banker Flows