JBTerminalStore
Inherits: IJBTerminalStore
Manages all bookkeeping for inflows and outflows of funds from any terminal address.
This contract expects a project's controller to be an IJBController
.
State Variables
_MAX_FIXED_POINT_FIDELITY
Constrains mulDiv
operations on fixed point numbers to a maximum number of decimal points of persisted
fidelity.
uint256 internal constant _MAX_FIXED_POINT_FIDELITY = 18;
DIRECTORY
The directory of terminals and controllers for projects.
IJBDirectory public immutable override DIRECTORY;
PRICES
The contract that exposes price feeds.
IJBPrices public immutable override PRICES;
RULESETS
The contract storing and managing project rulesets.
IJBRulesets public immutable override RULESETS;
balanceOf
A project's balance of a specific token within a terminal.
The balance is represented as a fixed point number with the same amount of decimals as its relative terminal.
mapping(address terminal => mapping(uint256 projectId => mapping(address token => uint256))) public override balanceOf;
usedPayoutLimitOf
The currency-denominated amount of funds that a project has already paid out from its payout limit during the current ruleset for each terminal, in terms of the payout limit's currency.
Increases as projects pay out funds.
The used payout limit is represented as a fixed point number with the same amount of decimals as the terminal it applies to.
mapping(
address terminal
=> mapping(
uint256 projectId
=> mapping(address token => mapping(uint256 rulesetCycleNumber => mapping(uint256 currency => uint256)))
)
) public override usedPayoutLimitOf;
usedSurplusAllowanceOf
The currency-denominated amounts of funds that a project has used from its surplus allowance during the current ruleset for each terminal, in terms of the surplus allowance's currency.
Increases as projects use their allowance.
The used surplus allowance is represented as a fixed point number with the same amount of decimals as the terminal it applies to.
mapping(
address terminal
=> mapping(
uint256 projectId
=> mapping(address token => mapping(uint256 rulesetId => mapping(uint256 currency => uint256)))
)
) public override usedSurplusAllowanceOf;
Functions
constructor
constructor(IJBDirectory directory, IJBPrices prices, IJBRulesets rulesets);
Parameters
Name | Type | Description |
---|---|---|
directory | IJBDirectory | A contract storing directories of terminals and controllers for each project. |
prices | IJBPrices | A contract that exposes price feeds. |
rulesets | IJBRulesets | A contract storing and managing project rulesets. |
currentReclaimableSurplusOf
Returns the number of surplus terminal tokens that would be reclaimed by cashing out a given project's tokens based on its current ruleset and the given total project token supply and total terminal token surplus.
function currentReclaimableSurplusOf(
uint256 projectId,
uint256 cashOutCount,
uint256 totalSupply,
uint256 surplus
)
external
view
override
returns (uint256);
Parameters
Name | Type | Description |
---|---|---|
projectId | uint256 | The ID of the project whose project tokens would be cashed out. |
cashOutCount | uint256 | The number of project tokens that would be cashed out, as a fixed point number with 18 decimals. |
totalSupply | uint256 | The total project token supply, as a fixed point number with 18 decimals. |
surplus | uint256 | The total terminal token surplus amount, as a fixed point number. |
Returns
Name | Type | Description |
---|---|---|
<none> | uint256 | The number of surplus terminal tokens that would be reclaimed, as a fixed point number with the same number of decimals as the provided surplus . |
currentReclaimableSurplusOf
Returns the number of surplus terminal tokens that would be reclaimed from a terminal by cashing out a given number of tokens, based on the total token supply and total surplus.
The returned amount in terms of the specified terminal
's base currency.
The returned amount is represented as a fixed point number with the same amount of decimals as the specified terminal.
function currentReclaimableSurplusOf(
uint256 projectId,
uint256 cashOutCount,
IJBTerminal[] calldata terminals,
JBAccountingContext[] calldata accountingContexts,
uint256 decimals,
uint256 currency
)
external
view
override
returns (uint256);
Parameters
Name | Type | Description |
---|---|---|
projectId | uint256 | The ID of the project whose tokens would be cashed out. |
cashOutCount | uint256 | The number of tokens that would be cashed out, as a fixed point number with 18 decimals. |
terminals | IJBTerminal[] | The terminals that would be cashed out from. If this is an empty array, surplus within all the project's terminals are considered. |
accountingContexts | JBAccountingContext[] | The accounting contexts of the surplus terminal tokens that would be reclaimed. Pass an empty array to use all of the project's accounting contexts. |
decimals | uint256 | The number of decimals to include in the resulting fixed point number. |
currency | uint256 | The currency that the resulting number will be in terms of. |
Returns
Name | Type | Description |
---|---|---|
<none> | uint256 | The amount of surplus terminal tokens that would be reclaimed by cashing out cashOutCount tokens. |
currentSurplusOf
Gets the current surplus amount in a terminal for a specified project.
The surplus is the amount of funds a project has in a terminal in excess of its payout limit.
The surplus is represented as a fixed point number with the same amount of decimals as the specified terminal.
function currentSurplusOf(
address terminal,
uint256 projectId,
JBAccountingContext[] calldata accountingContexts,
uint256 decimals,
uint256 currency
)
external
view
override
returns (uint256);
Parameters
Name | Type | Description |
---|---|---|
terminal | address | The terminal the surplus is being calculated for. |
projectId | uint256 | The ID of the project to get surplus for. |
accountingContexts | JBAccountingContext[] | The accounting contexts of tokens whose balances should contribute to the surplus being calculated. |
decimals | uint256 | The number of decimals to expect in the resulting fixed point number. |
currency | uint256 | The currency the resulting amount should be in terms of. |
Returns
Name | Type | Description |
---|---|---|
<none> | uint256 | The current surplus amount the project has in the specified terminal. |
currentTotalSurplusOf
Gets the current surplus amount for a specified project across all terminals.
function currentTotalSurplusOf(
uint256 projectId,
uint256 decimals,
uint256 currency
)
external
view
override
returns (uint256);
Parameters
Name | Type | Description |
---|---|---|
projectId | uint256 | The ID of the project to get the total surplus for. |
decimals | uint256 | The number of decimals that the fixed point surplus should include. |
currency | uint256 | The currency that the total surplus should be in terms of. |
Returns
Name | Type | Description |
---|---|---|
<none> | uint256 | The current total surplus amount that the project has across all terminals. |
_surplusFrom
Gets a project's surplus amount in a terminal as measured by a given ruleset, across multiple accounting contexts.
This amount changes as the value of the balance changes in relation to the currency being used to measure various payout limits.
function _surplusFrom(
address terminal,
uint256 projectId,
JBAccountingContext[] memory accountingContexts,
JBRuleset memory ruleset,
uint256 targetDecimals,
uint256 targetCurrency
)
internal
view
returns (uint256 surplus);
Parameters
Name | Type | Description |
---|---|---|
terminal | address | The terminal the surplus is being calculated for. |
projectId | uint256 | The ID of the project to get the surplus for. |
accountingContexts | JBAccountingContext[] | The accounting contexts of tokens whose balances should contribute to the surplus being calculated. |
ruleset | JBRuleset | The ID of the ruleset to base the surplus on. |
targetDecimals | uint256 | The number of decimals to include in the resulting fixed point number. |
targetCurrency | uint256 | The currency that the reported surplus is expected to be in terms of. |
Returns
Name | Type | Description |
---|---|---|
surplus | uint256 | The surplus of funds in terms of targetCurrency , as a fixed point number with targetDecimals decimals. |
_tokenSurplusFrom
Get a project's surplus amount of a specific token in a given terminal as measured by a given ruleset (one specific accounting context).
This amount changes as the value of the balance changes in relation to the currency being used to measure the payout limits.
function _tokenSurplusFrom(
address terminal,
uint256 projectId,
JBAccountingContext memory accountingContext,
JBRuleset memory ruleset,
uint256 targetDecimals,
uint256 targetCurrency
)
internal
view
returns (uint256 surplus);