◢◢ Treasury

The treasury is a representation of the flow of money through the platform, eventually making its way to users.

Flow

To see a general diagram of how the treasury flows, see this diagram.

Glossary

• Vault - A representation of all the money in the system.
• Unallocated funds - Money that is in the vault, but has not been assigned to a community treasury yet.
• Community treasury - The total amount of funds currently assigned to a community.
• Bounty budget - Money that is within a community treasury, with the intention of being used for new bounties or platform rewards in the future.
• Bounty reserve - Money that is within a community treasury, that is currently being used for an existing bounty or platform reward.
• Contributor budget - Money that is within a community treasury, that is to be distributed to users for their behaviour and contributions (i.e. "organic rewards" are distributed on a daily basis to users whose posts have the most positive reactions).
• Unallocated budget - Money that is within a community treasury, but hasn't been assigned to anything yet.
• User wallets - Money that is currently assigned to a user, awaiting payout.
• User payouts - Money that has left the vault and has been sent to a user (i.e. via PayPal).

Ledger

The treasury is powered by a postgres database called the ledger. It is comprised primarily of two tables:

• accounts - a set of key/value pairs representing different accounts (i.e. places that money can be). This table has the following accounts:

  • paid-in (1000) - All money in the vault will have come from this account, which will always be negative.
  • unallocated (1001) - Where unallocated funds are kept.
  • community-treasury (2001)
  • bounty-budget (2002)
  • article-payouts (2003) - Not currently used, but will be where funds attributed to article views will be temporarily kept while processing.
  • post-payouts (2004) - Where funds for organic rewards are temporarily kept while processing, before being distributed to users.
  • users (2005) - Where user wallets are kept.
  • contributor-budget (2006)
  • holding (2007) - Where funds are kept while user payouts are being processed.
  • bounty-reserve (2008)
  • curator-payouts (2009) - Not currently used, but will be where funds attributed to curator rewards will be temporarily kept while processing.
  • moderator-payouts (2010) - Not currently used, but will be where funds attributed to moderator rewards will be temporarily kept while processing.
  • paid-out (3001) - All money that has been paid out to users. This money is no longer in the vault.

• entries - a record of every time money moves from one account (or sub-account, see below) to another. Sometimes several rows can be created for what appears to the user to be a simple transaction (for instance, money passes through holding when processing a user payout).

  This table refers to sub-accounts, which are strings used to separate funds within an account. An example of a sub-account would be for a community treasury. If the community had an ID of 1, the sub-account would be comm-1. However, there can be sub-accounts for anything such as users or bounties, and they are defined by the Strapi app.

  The entries table has the following columns.

  • id - an auto-incremented ID for the transaction
  • description - a human readable description of what the transaction is (Note: this column is also used to store the Xero transaction ID when tracking funds paid into the vault, and in this instance it is not human readable).
  • credit_sub_account - the string representation of the sub-account that funds are going into.
  • debit_sub_account - the string representation of the sub-account that funds are leaving.
  • amount - the amount of money, in dollars
  • credit - the ID of the account that funds are going into.
  • debit - the ID of the account that funds are leaving.
  • created_at - the time of the transaction.
  • root_treasury - the string representation of the sub-account for the community treasury that the funds initially came from.

Paying into the vault

Funds are added to the vault via the Add funds to vault button on the Just About Admin > Vault Overview screen of the Strapi admin panel. This will add a row to the entries table, debitting the paid-in account and crediting the unallocated account.

Payouts

Payouts are made to users who have earned at least $25 and have connected their PayPal account. Users must have a Payout Request in order to be paid. These can be created for all users who qualify by pressing the Create new payout requests button on the Just About Admin > Payout requests screen of the Strapi admin panel.

Note: Only admin users with the Treasurer role can access the Payout Requests section of the admin panel.

Payout Requests are manually approved via this Payout requests screen. Only approved payouts will be processed. If a Payout Request is rejected, the funds will be returned from the holding account to the user wallet in the users account.

The GET /api/cron/process-payouts cron will process all approved payout requests. It is currently not set up to run and is called manually on the first of every month. This will trigger each payout request to be sent to PayPal to process. Upon success, the user's PayPal account will be credited, and the funds will be moved from the holding account to paid-out. The Payout Request will then have its status set to complete.

Payout Requests have the following statuses:

• pending - A newly created Payout Request that still requires manual approval.
• approved - Approved by a treasurer, ready to be processed.
• rejected - Rejected by a treasurer, funds sent back to the user wallet.
• in_progress - The payout process has started.
• payment_made - A success response has been received from PayPal and the payment has been made.
• provider_error - An error response has been received from PayPal.
• unclaimed - PayPal is holding the payment because the user has not verified their PayPal account. They have 30 days to do this or else the money will be refunded.
• ledger_failed - The payment was completed, but the payout was not tracked in the ledger database i.e. no row was added to the entries table.
• complete - The payout was processed successfully.
• failed - There was an issue processing the payment before making the request to PayPal, for instance if the user has no connected their PayPal account, or if their PayPal account does not have a valid email address.

Treasury models

Treasury

This is the main model where treasury configuration is stored. It has a one-to-one relationship with communities, and a lifecycle hook creates one whenever a new community is created.

It has the following fields:

• bountyBudget - How many funds are currently in the community's bounty budget. Note: This is a duplication of data in the ledger and will need to be kept in sync until we remove it.
• contributorBudget - How many funds are currently in the community's contributor budget. Note: This is a duplication of data in the ledger and will need to be kept in sync until we remove it.
• lastResolved - Deprecated - This field was used to track the last time the daily budget was resolved. However, it is no longer necessary.
• lastRanked - The last time the users/articles were ranked.
• minimumPayment - The minimum amount a user must earn to be credited from the treasury. Defaults to $0.50.
• minimumViews - The minumum number of views an article must get to be considered for article rewards. This functionality is not currently available. Defaults to 1.
• contributorBudgetEnd - The day that the contributorBudget should last until. This will be used to calculate the daily budget when rewards are distributed to users.

TreasuryBreakdown

This model determines what percentage of the contributor budget should go towards different automated rewards. It has a one-to-one relationship with the Treasury and is automatically created when a new treasury is created.

It has the following fields:

• popularArticles - Percentage to go towards users responsible for successful articles. This functionality is not currently available.
• forum - Percentage to go towards users who receive a lot of postive reactions on their posts. Note: "forum" is not a word that we use generally, but was at the time this model was created.
• moderators - Funds to go towards rewarding moderators. This functionality is not currently available.
• curators - Funds to go towards rewarding curators. This functionality is not currently available.

Currently this defaults to assigning 100% of the contributor budget to forum as this is the only functionality that exists.

TreasuryRankingBreakdown

This model determines how many users and articles are ranked, and what cut of their budget they should receive per day. It has a one-to-one relationship with the Treasury and is automatically created when a new treasury is created.

It has the following fields:

• forumRanked - The maximum number of users who should be ranked when processing the rewards for most positive reactions to posts. Defaults to 10.
• articlesRanked - The maximum number of articles that should be ranked when processing rewards for most successful reactions. This functionality is not currently available. Defaults to 10.
• curvature - Determines the difference between the rewards for first, second, third place etc. If set to 0, each user/article will receive the same reward. If set to 1, there will be an equal distribution between each reward (i.e. first place wins $10, second place wins $9, third wins $8, etc.). The equation is ([max rank] - [rank] + 1) ^ curvature). Defaults to 0.

TreasuryRunway

This model is deprecated and should not still be used anywhere. It was used to calculate how much of the contributor budget should be spent each day. This is now obsolete thanks to the contributorBudgetEnd field on the Treasury model.

Treasury administration

The treasury is managed via the Strapi admin panel under Just About Admin. The treasury section will only be visible to treasurers.

Treasuries > Manage treasuries

This screen shows a listing of all the treasuries along with breakdowns of how funds within those treasuries are allocated. Click on a treasury to to manage it.

Adding funds

Funds can be added to the treasury via the Add funds button at the top of the screen. You cannot add more funds than there are currently in the unallocated account, and you must provide a description (for instance, where the funds came from).

Overview

This section is where individual community treasuries are managed. From here you can see an overview of funds in the treasury, and where they are allocated. You can also see a list of the last 50 transactions in and out of the community treasury. Note: This will not include funds going leaving bounty and contributor budgets, i.e. if a new bounty is created, the funds going from the bounty budget into the bounty reserve will not be shown in this listing.

Configuration

Treasuries can be configured at the bottom of the screen. Here you can set the bounty budget, contributor budget, etc. as per the fields described in the Treasury models section above.

Updating the bounty budget or the contributor budget will create a new row in the entries table of the ledger, tracking the difference between the current budget and the new budget. Any increases to the bounty or contributor budgets cannot exceed the unallocated total.

Treasuries > Vault overview

The vault overview provides a general view of where funds are currently allocated, including individual treasuries, user wallets, and pending payouts.

The Community treasuries listing shows a simple breakdown of how many funds are in each community, including unallocated funds, bounties and organic reward allocation (i.e. the contributor budget). The bounty allocation is the sum of both the bounty budget, and the total funds already in the bounty reserve.

At the bottom of the screen is a list of the last 50 transactions on the unallocated account. This will mostly consist of funds received from the bank, and outgoing funds to community treasuries or individual users.

Treasuries > Full ledger entries

This screen is simply an overview of the last 50 transactions in the entries table. This show all transactions across the entire ledger, across all accounts.

Treasuries > Audit tools

This screen provides a view of any issues in the ledger. Specifically at the moment this means highlighting any sub-accounts that have a negative balance

Users and User Wallets

To get a view on an individual user's wallet, you must navigate to their overview in the Users section of Just About Admin.

Treasurers will be able to credit a user via the Credit user button. Here you can set which community treasury to credit the user from - if not set, it will come directly from unallocated funds. If a community treasury is set, then you can determine what budget it will come from, the bounty budget or the contributor budget - if not set then it will come from the community treasury's unallocated budget.

On this screen you can also see the last 50 transactions in the user's wallet. This will include funds coming in from communities (or unallocated funds), or outgoing to the holding account. Note: This will not show funds going from the holding account to their PayPal account.