Skip to main content

recordUsedAllowanceOf

Contract: JBSingleTokenPaymentTerminalStore​‌

Interface: IJBSingleTokenPaymentTerminalStore

Records newly used allowance funds of a project.

The msg.sender must be an IJBSingleTokenPaymentTerminal.

Definition​

function recordUsedAllowanceOf(
  uint256 _projectId,
  uint256 _amount,
  uint256 _currency
)
  external
  override
  nonReentrant
  returns (JBFundingCycle memory fundingCycle, uint256 usedAmount) { ... }
  • Arguments:
    • _projectId is the ID of the project to use the allowance of.
    • _amount is the amount to use from the allowance, as a fixed point number.
    • _currency is the currency of the _amount. Must match the currency of the overflow allowance.
  • The resulting function overrides a function definition from the JBSingleTokenPaymentTerminalStore interface.
  • The function returns:
    • fundingCycle is the funding cycle during which the withdrawal was made.
    • usedAmount is the amount of terminal tokens used, as a fixed point number with the same amount of decimals as its relative terminal.

Body​

  1. Get a reference to the project's first funding cycle.

    // Get a reference to the project's current funding cycle.
    fundingCycle = fundingCycleStore.currentOf(_projectId);

    External references:

  2. Get a reference to the new used overflow allowance for this funding cycle configuration.

    // Get a reference to the new used overflow allowance for this funding cycle configuration.
    uint256 _newUsedOverflowAllowanceOf = usedOverflowAllowanceOf[
      IJBSingleTokenPaymentTerminal(msg.sender)
    ][_projectId][fundingCycle.configuration] + _amount;

    Internal references:

  3. Get a reference to the overflow allowance of the project during the current funding cycle configuration, and the currency the overflow allowance is in terms of.

    // There must be sufficient allowance available.
    (uint256 _overflowAllowanceOf, uint256 _overflowAllowanceCurrency) = IJBController(
      directory.controllerOf(_projectId)
    ).overflowAllowanceOf(
        _projectId,
        fundingCycle.configuration,
        IJBSingleTokenPaymentTerminal(msg.sender),
        IJBSingleTokenPaymentTerminal(msg.sender).token()
      );

    External references:

  4. Make sure there's enough allowance left to accomodate the new used amount.

    // Make sure the new used amount is within the allowance.
    if (_newUsedOverflowAllowanceOf > _overflowAllowanceOf || _overflowAllowanceOf == 0)
      revert INADEQUATE_CONTROLLER_ALLOWANCE();

  5. Make the sure the provided currency matches the expected currency for the overflow allowance.

    // Make sure the currencies match.
    if (_currency != _overflowAllowanceCurrency) revert CURRENCY_MISMATCH();

  6. Get a reference to the terminal's currency.

    // Get a reference to the terminal's currency.
    uint256 _balanceCurrency = IJBSingleTokenPaymentTerminal(msg.sender).currency();

  7. Get a reference to the current distribution limit of the project during the current funding cycle configuration.

    // Get the current funding target
    uint256 distributionLimit =
      directory.controllerOf(_projectId).distributionLimitOf(
        _projectId,
        fundingCycle.configuration,
        terminal
      );

    External references:

  8. Calculate how much of the balance will be used. If the currency of the allowance and the balance are the same, no price conversion is necessary. Otherwise, convert the allowance currency to that of the balance.

    // Convert the amount to this store's terminal's token.
    usedAmount = (_currency == _balanceCurrency)
      ? _amount
      : PRBMath.mulDiv(
        _amount,
        10**_MAX_FIXED_POINT_FIDELITY, // Use _MAX_FIXED_POINT_FIDELITY to keep as much of the `_amount.value`'s fidelity as possible when converting.
        prices.priceFor(_currency, _balanceCurrency, _MAX_FIXED_POINT_FIDELITY)
      );

    Library references:

    Internal references:

    External references:

  9. Make sure the amount being used is available in overflow.

    // The amount being distributed must be available in the overflow.
    if (
      usedAmount >
      _overflowDuring(
        IJBSingleTokenPaymentTerminal(msg.sender),
        _projectId,
        fundingCycle,
        _balanceCurrency
      )
    ) revert INADEQUATE_PAYMENT_TERMINAL_STORE_BALANCE();

    Internal references:

  10. Store the incremented value that tracks how much of a project's allowance was used during the current funding cycle configuration.

    // Store the incremented value.
    usedOverflowAllowanceOf[IJBSingleTokenPaymentTerminal(msg.sender)][_projectId][
      fundingCycle.configuration
    ] = _newUsedOverflowAllowanceOf;

    Internal references:

  11. Store the decremented balance.

    // Update the project's balance.
    balanceOf[IJBSingleTokenPaymentTerminal(msg.sender)][_projectId] =
      balanceOf[IJBSingleTokenPaymentTerminal(msg.sender)][_projectId] -
      usedAmount;

    Internal references: