Skip to main content

FundingCycles

Git Source

Mainnet: 0xf507B2A1dD7439201eb07F11E1d62AfB29216e2E

Inherits: TerminalUtility, IFundingCycles

Manage funding cycle configurations, accounting, and scheduling.

State Variables

SECONDS_IN_DAY

uint256 private constant SECONDS_IN_DAY = 86400;

_packedConfigurationPropertiesOf

mapping(uint256 => uint256) private _packedConfigurationPropertiesOf;

_packedIntrinsicPropertiesOf

mapping(uint256 => uint256) private _packedIntrinsicPropertiesOf;

_metadataOf

mapping(uint256 => uint256) private _metadataOf;

_targetOf

mapping(uint256 => uint256) private _targetOf;

_tappedOf

mapping(uint256 => uint256) private _tappedOf;

BASE_WEIGHT

The weight used for each project's first funding cycle.

uint256 public constant override BASE_WEIGHT = 1e24;

MAX_CYCLE_LIMIT

The maximum value that a cycle limit can be set to.

uint256 public constant override MAX_CYCLE_LIMIT = 32;

latestIdOf

The ID of the latest funding cycle for each project.

mapping(uint256 => uint256) public override latestIdOf;

count

The total number of funding cycles created, which is used for issuing funding cycle IDs.

Funding cycles have IDs > 0.

uint256 public override count = 0;

Functions

get

Get the funding cycle with the given ID.

function get(uint256 _fundingCycleId) external view override returns (FundingCycle memory);

Parameters

NameTypeDescription
_fundingCycleIduint256The ID of the funding cycle to get.

Returns

NameTypeDescription
<none>FundingCycle_fundingCycle The funding cycle.

queuedOf

The funding cycle that's next up for a project, and therefor not currently accepting payments.

This runs roughly similar logic to _configurable.

function queuedOf(uint256 _projectId) external view override returns (FundingCycle memory);

Parameters

NameTypeDescription
_projectIduint256The ID of the project being looked through.

Returns

NameTypeDescription
<none>FundingCycle_fundingCycle The queued funding cycle.

currentOf

The funding cycle that is currently active for the specified project.

This runs very similar logic to _tappable.

function currentOf(uint256 _projectId) external view override returns (FundingCycle memory fundingCycle);

Parameters

NameTypeDescription
_projectIduint256The ID of the project being looked through.

Returns

NameTypeDescription
fundingCycleFundingCycleThe current funding cycle.

currentBallotStateOf

The currency ballot state of the project.

function currentBallotStateOf(uint256 _projectId) external view override returns (BallotState);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to check for a pending reconfiguration.

Returns

NameTypeDescription
<none>BallotStateThe current ballot's state.

constructor

constructor(ITerminalDirectory _terminalDirectory) TerminalUtility(_terminalDirectory);

Parameters

NameTypeDescription
_terminalDirectoryITerminalDirectoryA directory of a project's current Juicebox terminal to receive payments in.

configure

Configures the next eligible funding cycle for the specified project.

Only a project's current terminal can configure its funding cycles.

_properties.target: The amount that the project wants to receive in each funding cycle. 18 decimals.

_properties.currency: The currency of the _target. Send 0 for ETH or 1 for USD.

  • _properties.duration: The duration of the funding cycle for which the _target amount is needed. Measured in days. Set to 0 for no expiry and to be able to reconfigure anytime.

_cycleLimit: The number of cycles that this configuration should last for before going back to the last permanent. This does nothing for a project's first funding cycle.

  • _properties.discountRate: A number from 0-200 indicating how valuable a contribution to this funding cycle is compared to previous funding cycles. If it's 0, each funding cycle will have equal weight. If the number is 100, a contribution to the next funding cycle will only give you 90% of tickets given to a contribution of the same amount during the current funding cycle. If the number is 200, a contribution to the next funding cycle will only give you 80% of tickets given to a contribution of the same amoutn during the current funding cycle. If the number is 201, an non-recurring funding cycle will get made.

_ballot: The new ballot that will be used to approve subsequent reconfigurations.

function configure(
uint256 _projectId,
FundingCycleProperties calldata _properties,
uint256 _metadata,
uint256 _fee,
bool _configureActiveFundingCycle
) external override onlyTerminal(_projectId) returns (FundingCycle memory fundingCycle);

Parameters

NameTypeDescription
_projectIduint256The ID of the project being reconfigured.
_propertiesFundingCyclePropertiesThe funding cycle configuration.
_metadatauint256Data to associate with this funding cycle configuration.
_feeuint256The fee that this configuration will incure when tapping.
_configureActiveFundingCycleboolIf a funding cycle that has already started should be configurable.

Returns

NameTypeDescription
fundingCycleFundingCycleThe funding cycle that the configuration will take effect during.

tap

Tap funds from a project's currently tappable funding cycle.

Only a project's current terminal can tap funds for its funding cycles.

function tap(uint256 _projectId, uint256 _amount)
external
override
onlyTerminal(_projectId)
returns (FundingCycle memory fundingCycle);

Parameters

NameTypeDescription
_projectIduint256The ID of the project being tapped.
_amountuint256The amount being tapped.

Returns

NameTypeDescription
fundingCycleFundingCycleThe tapped funding cycle.

_configurable

Returns the configurable funding cycle for this project if it exists, otherwise creates one.

function _configurable(uint256 _projectId, uint256 _configured, bool _configureActiveFundingCycle)
private
returns (uint256 fundingCycleId);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to find a configurable funding cycle for.
_configureduint256The time at which the configuration is occuring.
_configureActiveFundingCycleboolIf the active funding cycle should be configurable. Otherwise the next funding cycle will be used.

Returns

NameTypeDescription
fundingCycleIduint256The ID of the configurable funding cycle.

_tappable

Returns the funding cycle that can be tapped at the time of the call.

function _tappable(uint256 _projectId) private returns (uint256 fundingCycleId);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to find a configurable funding cycle for.

Returns

NameTypeDescription
fundingCycleIduint256The ID of the tappable funding cycle.

_init

Initializes a funding cycle with the appropriate properties.

function _init(uint256 _projectId, FundingCycle memory _baseFundingCycle, uint256 _mustStartOnOrAfter, bool _copy)
private
returns (uint256 newFundingCycleId);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to which the funding cycle being initialized belongs.
_baseFundingCycleFundingCycleThe funding cycle to base the initialized one on.
_mustStartOnOrAfteruint256The time before which the initialized funding cycle can't start.
_copyboolIf non-intrinsic properties should be copied from the base funding cycle.

Returns

NameTypeDescription
newFundingCycleIduint256The ID of the initialized funding cycle.

_standby

The project's funding cycle that hasn't yet started, if one exists.

function _standby(uint256 _projectId) private view returns (uint256 fundingCycleId);

Parameters

NameTypeDescription
_projectIduint256The ID of project to look through.

Returns

NameTypeDescription
fundingCycleIduint256The ID of the standby funding cycle.

_eligible

The project's funding cycle that has started and hasn't yet expired.

function _eligible(uint256 _projectId) private view returns (uint256 fundingCycleId);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to look through.

Returns

NameTypeDescription
fundingCycleIduint256The ID of the active funding cycle.

_mockFundingCycleBasedOn

A view of the funding cycle that would be created based on the provided one if the project doesn't make a reconfiguration.

function _mockFundingCycleBasedOn(FundingCycle memory _baseFundingCycle, bool _allowMidCycle)
internal
view
returns (FundingCycle memory);

Parameters

NameTypeDescription
_baseFundingCycleFundingCycleThe funding cycle to make the calculation for.
_allowMidCycleboolAllow the mocked funding cycle to already be mid cycle.

Returns

NameTypeDescription
<none>FundingCycleThe next funding cycle, with an ID set to 0.

_updateFundingCycle

Updates intrinsic properties for a funding cycle given a base cycle.

function _updateFundingCycle(
uint256 _fundingCycleId,
FundingCycle memory _baseFundingCycle,
uint256 _mustStartOnOrAfter,
bool _copy
) private;

Parameters

NameTypeDescription
_fundingCycleIduint256The ID of the funding cycle to make sure is update.
_baseFundingCycleFundingCycleThe cycle that the one being updated is based on.
_mustStartOnOrAfteruint256The time before which the initialized funding cycle can't start.
_copyboolIf non-intrinsic properties should be copied from the base funding cycle.

_packAndStoreIntrinsicProperties

Efficiently stores a funding cycle's provided intrinsic properties.

function _packAndStoreIntrinsicProperties(
uint256 _fundingCycleId,
uint256 _projectId,
uint256 _weight,
uint256 _number,
uint256 _basedOn,
uint256 _start
) private;

Parameters

NameTypeDescription
_fundingCycleIduint256The ID of the funding cycle to pack and store.
_projectIduint256The ID of the project to which the funding cycle belongs.
_weightuint256The weight of the funding cycle.
_numberuint256The number of the funding cycle.
_basedOnuint256The ID of the based funding cycle.
_startuint256The start time of this funding cycle.

_packAndStoreConfigurationProperties

Efficiently stores a funding cycles provided configuration properties.

function _packAndStoreConfigurationProperties(
uint256 _fundingCycleId,
uint256 _configured,
uint256 _cycleLimit,
IFundingCycleBallot _ballot,
uint256 _duration,
uint256 _currency,
uint256 _fee,
uint256 _discountRate
) private;

Parameters

NameTypeDescription
_fundingCycleIduint256The ID of the funding cycle to pack and store.
_configureduint256The timestamp of the configuration.
_cycleLimituint256The number of cycles that this configuration should last for before going back to the last permanent.
_ballotIFundingCycleBallotThe ballot to use for future reconfiguration approvals.
_durationuint256The duration of the funding cycle.
_currencyuint256The currency of the funding cycle.
_feeuint256The fee of the funding cycle.
_discountRateuint256The discount rate of the based funding cycle.

_getStruct

Unpack a funding cycle's packed stored values into an easy-to-work-with funding cycle struct.

function _getStruct(uint256 _id) private view returns (FundingCycle memory _fundingCycle);

Parameters

NameTypeDescription
_iduint256The ID of the funding cycle to get a struct of.

Returns

NameTypeDescription
_fundingCycleFundingCycleThe funding cycle struct.

_deriveStart

The date that is the nearest multiple of the specified funding cycle's duration from its end.

function _deriveStart(
FundingCycle memory _baseFundingCycle,
FundingCycle memory _latestPermanentFundingCycle,
uint256 _mustStartOnOrAfter
) internal pure returns (uint256 start);

Parameters

NameTypeDescription
_baseFundingCycleFundingCycleThe funding cycle to make the calculation for.
_latestPermanentFundingCycleFundingCycleThe latest funding cycle in the same project as _baseFundingCycle to not have a limit.
_mustStartOnOrAfteruint256A date that the derived start must be on or come after.

Returns

NameTypeDescription
startuint256The next start time.

_deriveWeight

The accumulated weight change since the specified funding cycle.

function _deriveWeight(
FundingCycle memory _baseFundingCycle,
FundingCycle memory _latestPermanentFundingCycle,
uint256 _start
) internal pure returns (uint256 weight);

Parameters

NameTypeDescription
_baseFundingCycleFundingCycleThe funding cycle to make the calculation with.
_latestPermanentFundingCycleFundingCycleThe latest funding cycle in the same project as _fundingCycle to not have a limit.
_startuint256The start time to derive a weight for.

Returns

NameTypeDescription
weightuint256The next weight.

_deriveNumber

The number of the next funding cycle given the specified funding cycle.

function _deriveNumber(
FundingCycle memory _baseFundingCycle,
FundingCycle memory _latestPermanentFundingCycle,
uint256 _start
) internal pure returns (uint256 number);

Parameters

NameTypeDescription
_baseFundingCycleFundingCycleThe funding cycle to make the calculation with.
_latestPermanentFundingCycleFundingCycleThe latest funding cycle in the same project as _fundingCycle to not have a limit.
_startuint256The start time to derive a number for.

Returns

NameTypeDescription
numberuint256The next number.

_deriveCycleLimit

The limited number of times a funding cycle configuration can be active given the specified funding cycle.

function _deriveCycleLimit(FundingCycle memory _fundingCycle, uint256 _start) internal pure returns (uint256);

Parameters

NameTypeDescription
_fundingCycleFundingCycleThe funding cycle to make the calculation with.
_startuint256The start time to derive cycles remaining for.

Returns

NameTypeDescription
<none>uint256start The inclusive nunmber of cycles remaining.

_isIdApproved

Checks to see if the funding cycle of the provided ID is approved according to the correct ballot.

function _isIdApproved(uint256 _fundingCycleId) private view returns (bool);

Parameters

NameTypeDescription
_fundingCycleIduint256The ID of the funding cycle to get an approval flag for.

Returns

NameTypeDescription
<none>boolThe approval flag.

_isApproved

Checks to see if the provided funding cycle is approved according to the correct ballot.

function _isApproved(FundingCycle memory _fundingCycle) private view returns (bool);

Parameters

NameTypeDescription
_fundingCycleFundingCycleThe ID of the funding cycle to get an approval flag for.

Returns

NameTypeDescription
<none>boolThe approval flag.

_ballotState

A funding cycle configuration's currency status.

function _ballotState(uint256 _id, uint256 _configuration, uint256 _ballotFundingCycleId)
private
view
returns (BallotState);

Parameters

NameTypeDescription
_iduint256The ID of the funding cycle configuration to check the status of.
_configurationuint256The timestamp of when the configuration took place.
_ballotFundingCycleIduint256The ID of the funding cycle which is configured with the ballot that should be used.

Returns

NameTypeDescription
<none>BallotStateThe funding cycle's configuration status.

_latestPermanentCycleBefore

Finds the last funding cycle that was permanent in relation to the specified funding cycle.

Determined what the latest funding cycle with a cycleLimit of 0 is, or isn't based on any previous funding cycle.

function _latestPermanentCycleBefore(FundingCycle memory _fundingCycle)
private
view
returns (FundingCycle memory fundingCycle);

Parameters

NameTypeDescription
_fundingCycleFundingCycleThe funding cycle to find the most recent permanent cycle compared to.

Returns

NameTypeDescription
fundingCycleFundingCycleThe most recent permanent funding cycle.

_getTimeAfterBallot

The time after the ballot of the provided funding cycle has expired.

If the ballot ends in the past, the current block timestamp will be returned.

function _getTimeAfterBallot(FundingCycle memory _fundingCycle, uint256 _from) private view returns (uint256);

Parameters

NameTypeDescription
_fundingCycleFundingCycleThe ID funding cycle to make the caluclation the ballot of.
_fromuint256The time from which the ballot duration should be calculated.

Returns

NameTypeDescription
<none>uint256The time when the ballot duration ends.