1. Summary

The TaxCollector stores data about each CollateralType's stability fee. It also collects fees from currently opened SAFEs and distributes them to the AccountingEngine and to other auxiliary system components such as the StabilityFeeTreasury.

2. Contract Variables & Functions

Variables

• authorizedAccounts[usr: address] - addAuthorization/removeAuthorization/isAuthorized - auth mechanisms

• collateralTypes[collateralType: bytes32] - mapping with data about each collateral type

• secondaryReceiverAllotedTax[collateralType: bytes32] - total percentage of a CollateralType's fees that goes to secondary tax receivers

• usedSecondaryReceiver[receiver: address] - whether an address is already used as a secondary receiver

• secondaryReceiverAccounts[receiver: address] - whether an address is already marked as a secondary tax receiver

• secondaryReceiverRevenueSources[receiver: address] - number of collateral types that give part of their stability fees to secondary receivers

• secondaryTaxReceivers[bytes32: collateralType, uint256: receiverId] - data about a secondary receiver for a specific collateral type

• safeEngine - address of the SAFEEngine. Cannot be changed after contract deployment

• primaryTaxReceiver - main receiver of stability fees (usually the AccountingEngine)

• globalStabilityFee - base stability fee applied to all collateral types

• secondaryReceiverNonce - total amount of secondary receivers ever added

• maxSecondaryReceivers - maximum amount of secondary receivers that can receive fees from one collateral type

• latestSecondaryReceiver - the first secondary receiver the contract starts to loop from when distributing fees

• collateralList - list of all collateral types added to the collector

• secondaryReceiverList - list of all secondary tax receivers who receive fees from at least one collateral type

Data Structures

• CollateralType:

  • stabilityFee - per second fee applied to SAFEs backed by a specific asset

  • updateTime - latest timestamp of when the system collected fees from SAFEs backed by a specific collateral

• TaxReceiver - struct containing data about an auxiliary address that receives stability fees. It cannot be the AccountingEngine (because it is already considered a primary tax receiver). Contains:

  • canTakeBackTax - whether the system can impose a penalty on the receiver and take back previously distributed stability fees (in case the stability fee is negative)

  • taxPercentage - percentage of a collateral's stability fees distributed to this receiver

Functions

• initializeCollateralType(collateralType: bytes32) - add a new collateral type

• modifyParameters() - add/remove tax receivers, set stability fees etc

• addSecondaryReceiver(collateralType: bytes32, percentage: uint256, receiver: address)- add a new secondary receiver

• modifySecondaryReceiver(collateral: bytes32, position: uint256, percentage: uint256) - modify a receiver's data or remove them from the receiver list

• collectedManyTax(start: uint256, end: uint256) - check if the contract is up to date with taxation (on multiple collateral types)

• taxManyOutcome(start: uint256, end: uint256) public view returns (bool ok, int rad) - check how many fees would be collected if multiple collateral types (between indexes start and end in collateralList) would be taxed at once

• taxSingleOutcome(collateralType: bytes32) public view returns (uint, int) - check the amount of fees that would be collected if a single collateral type was taxed

• secondaryReceiversAmount() public view returns (uint) - return the amount of unique secondary receivers added to the collector

• collateralListLength() public view returns (uint) - return the length of collateralList

• isSecondaryReceiver(receiverId: uint256) public view returns (uint) - check if an id in the secondaryReceiverList was allocated to a receiver

• taxMany(start: uint256, end: uint256) - collect tax from multiple collateral types that are between start and end in collateralList

• taxSingle(collateralType: bytes32) public returns (uint) - collect fees from a single collateral type

• splitTaxIncome(collateral: bytes32, debt: uint256, deltaRate: int256) - loop through tax receivers in order to distribute tax

Events

• AddAuthorization - emitted when a new address becomes authorized. Contains:

  • account - the new authorized account

• RemoveAuthorization - emitted when an address is de-authorized. Contains:

  • account - the address that was de-authorized

• CollectTax: emitted when a collateral type is taxed (the system collects stability fees from SAFEs backed by a specific asset). Contains:

  • collateralType - collateral type being taxed

  • latestAccumulatedRate - accumulator of total stability fees that have been applied tocollateralType SAFEs since the taxed collateral has been accepted into the system

  • deltaRate - difference between the new (latestAccumulatedRate) and the old accumulated rate for the currently taxed collateral type

• DistributeTax - emitted when the system distributes fees to a specific recipient. Contains:

  • collateralType - collateral type being taxed

  • target - stability fee receiver

  • taxCut - portion of the total tax to be distributed that goes to target

3. Walkthrough

The taxation process starts with governance setting up the globalStabilityFee and every collateral's stabilityFee. Governance also needs to set a primaryTaxReceiver (usually the AccountingEngine) and add secondaryReceivers for each collateral type (e.g the StabilityFeeTreasury).

To collect stability fees, external actors (such as protocol token holders or keepers) can call taxMany (to collect stability fees from multiple collateral types) or taxSingle. The primaryTaxReceiver is guaranteed to receive a non zero amount of stability fees. If there are any secondaryReceivers set up for a specific collateral, each one will get TaxReceiver.taxPercentage percentage of the distributed fees.