Banker - datacratic/rtbkit GitHub Wiki

The Banker is the mechanism that RTBkit uses to authorize and track spending.

RTBkit ships with a standard Banker implementation (the Master Banker System) which will be described here but it is worth noting that it isn't a requirement to use this particular implementation. Any implementation that meets the same interface can be used in its place.

Design and Rationale of the Master Banker System

The primary requirement driving the design of the Master Banker and associated infrastructure (Slave Bankers, Accounts, Shadow Accounts, Currency Pools etc) is that it function in a distributed fashion using high-latency, low-bandwidth, unreliable links.

The Master Banker is a data store with a REST API which is responsible for managing and persisting Accounts in the Banker Database. Accounts contain Currency Pools and can have one parent and multiple children, meaning they can be arranged in a tree structure. See Accounts for more details and Pacing to find out how to use this tree structure to control spend and pacing. Currency Pools track amounts of money on a per-currency basis (e.g. one Currency Pool could contain 10M microUSD and 15M microEUR). They are stored as integers in order to avoid rounding errors, and automatically handle scaling conversions within a currency such as between USD, microUSD and USD CPM, but not across currencies, such as between USD and EUR.

Within an Account tree, the leaf Accounts are Spend Accounts while the others are Budget Accounts. Spend accounts can have non-zero spent Currency Pools.

RTBkit Routers and Post-Auction Loops have an on-board Slave Banker (which can be considered to be a Banker Proxy) which maintains Shadow Accounts linked to the Spend Accounts in the Master Banker (and in fact it is the Routers and Post-Auction Loops that create these Spend Accounts underneath whichever Budget Account an Agent declares that it is bidding with, see Agent Configuration and Filtering). Routers and Post-Auction Loops operate on their local Shadow Accounts and their local Slave Banker is responsible for keeping the Shadow Accounts in sync with their counterparts in the Master Banker.

The design of the Accounts themselves was driven by this synchronization requirement: the Currency Pools in Accounts are laid out such that any given Currency Pool in any given Account can only be mutated by one process. Furthermore, Currency Pools can only ever go up in value, meaning that the 'most recent' version of a Currency Pool is the one with a higher value. This lowers the synchronization overhead.