Skip to main content

JBController3_0_1

Stitches together funding cycles and project tokens, making sure all activity is accounted for and correct.

Git Source

Mainnet: 0xA139D37275d1fF7275e6F33821898934Bc8Cb7B6

Goerli: 0x696f8175E114C5C89248Fb254185Df3Df4cD03f3

Inherits: JBOperatable, ERC165, IJBController, IJBController3_0_1, IJBMigratable

This Controller manages a project's reserved tokens explicitly instead of through a passive tracker property.

It is backwards compatible with the original IJBController, and exposes convenience view methods as part of IJBController3_1 for clearer queries.

Adheres to:

  • IJBController3_0_1: General interface for the generic controller methods in this contract that interacts with funding cycles and tokens according to the protocol's rules.
  • IJBMigratable: Allows migrating to this contract, with a hook called to prepare for the migration.

Inherits from:

  • JBOperatable: Several functions in this contract can only be accessed by a project owner, or an address that has been preconfifigured to be an operator of the project.
  • ERC165: Introspection on interface adherance.

State Variables

_packedDistributionLimitDataOf

Data regarding the distribution limit of a project during a configuration.

bits 0-231: The amount of token that a project can distribute per funding cycle.

bits 232-255: The currency of amount that a project can distribute.

  • _projectId The ID of the project to get the packed distribution limit data of.
  • _configuration The configuration during which the packed distribution limit data applies.
  • _terminal The terminal from which distributions are being limited.
  • _token The token for which distributions are being limited.
mapping(uint256 => mapping(uint256 => mapping(IJBPaymentTerminal => mapping(address => uint256)))) internal
_packedDistributionLimitDataOf;

_packedOverflowAllowanceDataOf

Data regarding the overflow allowance of a project during a configuration.

bits 0-231: The amount of overflow that a project is allowed to tap into on-demand throughout the configuration.

bits 232-255: The currency of the amount of overflow that a project is allowed to tap.

  • _projectId The ID of the project to get the packed overflow allowance data of.
  • _configuration The configuration during which the packed overflow allowance data applies.
  • _terminal The terminal managing the overflow.
  • _token The token for which overflow is being allowed.
mapping(uint256 => mapping(uint256 => mapping(IJBPaymentTerminal => mapping(address => uint256)))) internal
_packedOverflowAllowanceDataOf;

_reservedTokenBalanceOf

The current undistributed reserved token balance of.

  • _projectId The ID of the project to get a reserved token balance of.
mapping(uint256 => uint256) internal _reservedTokenBalanceOf;

projects

Mints ERC-721's that represent project ownership.

IJBProjects public immutable override projects;

fundingCycleStore

The contract storing all funding cycle configurations.

IJBFundingCycleStore public immutable override fundingCycleStore;

tokenStore

The contract that manages token minting and burning.

IJBTokenStore public immutable override tokenStore;

splitsStore

The contract that stores splits for each project.

IJBSplitsStore public immutable override splitsStore;

directory

The directory of terminals and controllers for projects.

IJBDirectory public immutable override directory;

Functions

distributionLimitOf

The amount of token that a project can distribute per funding cycle, and the currency it's in terms of.

The number of decimals in the returned fixed point amount is the same as that of the specified terminal.

function distributionLimitOf(uint256 _projectId, uint256 _configuration, IJBPaymentTerminal _terminal, address _token)
external
view
override
returns (uint256, uint256);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to get the distribution limit of.
_configurationuint256The configuration during which the distribution limit applies.
_terminalIJBPaymentTerminalThe terminal from which distributions are being limited.
_tokenaddressThe token for which the distribution limit applies.

Returns

NameTypeDescription
<none>uint256The distribution limit, as a fixed point number with the same number of decimals as the provided terminal.
<none>uint256The currency of the distribution limit.

overflowAllowanceOf

The amount of overflow that a project is allowed to tap into on-demand throughout a configuration, and the currency it's in terms of.

The number of decimals in the returned fixed point amount is the same as that of the specified terminal.

function overflowAllowanceOf(uint256 _projectId, uint256 _configuration, IJBPaymentTerminal _terminal, address _token)
external
view
override
returns (uint256, uint256);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to get the overflow allowance of.
_configurationuint256The configuration of the during which the allowance applies.
_terminalIJBPaymentTerminalThe terminal managing the overflow.
_tokenaddressThe token for which the overflow allowance applies.

Returns

NameTypeDescription
<none>uint256The overflow allowance, as a fixed point number with the same number of decimals as the provided terminal.
<none>uint256The currency of the overflow allowance.

getFundingCycleOf

A project's funding cycle for the specified configuration along with its metadata.

function getFundingCycleOf(uint256 _projectId, uint256 _configuration)
external
view
override
returns (JBFundingCycle memory fundingCycle, JBFundingCycleMetadata memory metadata);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to which the funding cycle belongs.
_configurationuint256

Returns

NameTypeDescription
fundingCycleJBFundingCycleThe funding cycle.
metadataJBFundingCycleMetadataThe funding cycle's metadata.

latestConfiguredFundingCycleOf

A project's latest configured funding cycle along with its metadata and the ballot state of the configuration.

function latestConfiguredFundingCycleOf(uint256 _projectId)
external
view
override
returns (JBFundingCycle memory fundingCycle, JBFundingCycleMetadata memory metadata, JBBallotState ballotState);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to which the funding cycle belongs.

Returns

NameTypeDescription
fundingCycleJBFundingCycleThe latest configured funding cycle.
metadataJBFundingCycleMetadataThe latest configured funding cycle's metadata.
ballotStateJBBallotStateThe state of the configuration.

currentFundingCycleOf

A project's current funding cycle along with its metadata.

function currentFundingCycleOf(uint256 _projectId)
external
view
override
returns (JBFundingCycle memory fundingCycle, JBFundingCycleMetadata memory metadata);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to which the funding cycle belongs.

Returns

NameTypeDescription
fundingCycleJBFundingCycleThe current funding cycle.
metadataJBFundingCycleMetadataThe current funding cycle's metadata.

queuedFundingCycleOf

A project's queued funding cycle along with its metadata.

function queuedFundingCycleOf(uint256 _projectId)
external
view
override
returns (JBFundingCycle memory fundingCycle, JBFundingCycleMetadata memory metadata);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to which the funding cycle belongs.

Returns

NameTypeDescription
fundingCycleJBFundingCycleThe queued funding cycle.
metadataJBFundingCycleMetadataThe queued funding cycle's metadata.

reservedTokenBalanceOf

Gets the amount of reserved tokens that a project has available to distribute.

function reservedTokenBalanceOf(uint256 _projectId) external view override returns (uint256);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to get a reserved token balance of.

Returns

NameTypeDescription
<none>uint256The current amount of reserved tokens.

reservedTokenBalanceOf

Gets the amount of reserved tokens that a project has available to distribute.

This is just for IJBController backwards compatibility.

function reservedTokenBalanceOf(uint256 _projectId, uint256 _reservedRate) external view override returns (uint256);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to get a reserved token balance of.
_reservedRateuint256The reserved rate to use when making the calculation.

Returns

NameTypeDescription
<none>uint256The current amount of reserved tokens.

totalOutstandingTokensOf

Gets the current total amount of outstanding tokens for a project, given a reserved rate.

This is just for IJBController backwards compatibility.

function totalOutstandingTokensOf(uint256 _projectId, uint256 _reservedRate) external view override returns (uint256);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to get total outstanding tokens of.
_reservedRateuint256The reserved rate to use when making the calculation.

Returns

NameTypeDescription
<none>uint256The current total amount of outstanding tokens for the project.

totalOutstandingTokensOf

Gets the current total amount of outstanding tokens for a project.

function totalOutstandingTokensOf(uint256 _projectId) public view override returns (uint256);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to get total outstanding tokens of.

Returns

NameTypeDescription
<none>uint256The current total amount of outstanding tokens for the project.

supportsInterface

Indicates if this contract adheres to the specified interface.

See IERC165-supportsInterface.

function supportsInterface(bytes4 _interfaceId) public view virtual override(ERC165, IERC165) returns (bool);

Parameters

NameTypeDescription
_interfaceIdbytes4The ID of the interface to check for adherance to.

constructor

constructor(
IJBOperatorStore _operatorStore,
IJBProjects _projects,
IJBDirectory _directory,
IJBFundingCycleStore _fundingCycleStore,
IJBTokenStore _tokenStore,
IJBSplitsStore _splitsStore
) JBOperatable(_operatorStore);

Parameters

NameTypeDescription
_operatorStoreIJBOperatorStoreA contract storing operator assignments.
_projectsIJBProjectsA contract which mints ERC-721's that represent project ownership and transfers.
_directoryIJBDirectoryA contract storing directories of terminals and controllers for each project.
_fundingCycleStoreIJBFundingCycleStoreA contract storing all funding cycle configurations.
_tokenStoreIJBTokenStoreA contract that manages token minting and burning.
_splitsStoreIJBSplitsStoreA contract that stores splits for each project.

launchProjectFor

Creates a project. This will mint an ERC-721 into the specified owner's account, configure a first funding cycle, and set up any splits.

Each operation within this transaction can be done in sequence separately.

Anyone can deploy a project on an owner's behalf.

function launchProjectFor(
address _owner,
JBProjectMetadata calldata _projectMetadata,
JBFundingCycleData calldata _data,
JBFundingCycleMetadata calldata _metadata,
uint256 _mustStartAtOrAfter,
JBGroupedSplits[] calldata _groupedSplits,
JBFundAccessConstraints[] calldata _fundAccessConstraints,
IJBPaymentTerminal[] memory _terminals,
string memory _memo
) external virtual override returns (uint256 projectId);

Parameters

NameTypeDescription
_owneraddressThe address to set as the owner of the project. The project ERC-721 will be owned by this address.
_projectMetadataJBProjectMetadataMetadata to associate with the project within a particular domain. This can be updated any time by the owner of the project.
_dataJBFundingCycleDataData that defines the project's first funding cycle. These properties will remain fixed for the duration of the funding cycle.
_metadataJBFundingCycleMetadataMetadata specifying the controller specific params that a funding cycle can have. These properties will remain fixed for the duration of the funding cycle.
_mustStartAtOrAfteruint256The time before which the configured funding cycle cannot start.
_groupedSplitsJBGroupedSplits[]An array of splits to set for any number of groups.
_fundAccessConstraintsJBFundAccessConstraints[]An array containing amounts that a project can use from its treasury for each payment terminal. Amounts are fixed point numbers using the same number of decimals as the accompanying terminal. The _distributionLimit and _overflowAllowance parameters must fit in a uint232.
_terminalsIJBPaymentTerminal[]Payment terminals to add for the project.
_memostringA memo to pass along to the emitted event.

Returns

NameTypeDescription
projectIduint256The ID of the project.

launchFundingCyclesFor

Creates a funding cycle for an already existing project ERC-721.

Each operation within this transaction can be done in sequence separately.

Only a project owner or operator can launch its funding cycles.

function launchFundingCyclesFor(
uint256 _projectId,
JBFundingCycleData calldata _data,
JBFundingCycleMetadata calldata _metadata,
uint256 _mustStartAtOrAfter,
JBGroupedSplits[] calldata _groupedSplits,
JBFundAccessConstraints[] memory _fundAccessConstraints,
IJBPaymentTerminal[] memory _terminals,
string memory _memo
)
external
virtual
override
requirePermission(projects.ownerOf(_projectId), _projectId, JBOperations.RECONFIGURE)
returns (uint256 configuration);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to launch funding cycles for.
_dataJBFundingCycleDataData that defines the project's first funding cycle. These properties will remain fixed for the duration of the funding cycle.
_metadataJBFundingCycleMetadataMetadata specifying the controller specific params that a funding cycle can have. These properties will remain fixed for the duration of the funding cycle.
_mustStartAtOrAfteruint256The time before which the configured funding cycle cannot start.
_groupedSplitsJBGroupedSplits[]An array of splits to set for any number of groups.
_fundAccessConstraintsJBFundAccessConstraints[]An array containing amounts that a project can use from its treasury for each payment terminal. Amounts are fixed point numbers using the same number of decimals as the accompanying terminal. The _distributionLimit and _overflowAllowance parameters must fit in a uint232.
_terminalsIJBPaymentTerminal[]Payment terminals to add for the project.
_memostringA memo to pass along to the emitted event.

Returns

NameTypeDescription
configurationuint256The configuration of the funding cycle that was successfully created.

reconfigureFundingCyclesOf

Proposes a configuration of a subsequent funding cycle that will take effect once the current one expires if it is approved by the current funding cycle's ballot.

Only a project's owner or a designated operator can configure its funding cycles.

function reconfigureFundingCyclesOf(
uint256 _projectId,
JBFundingCycleData calldata _data,
JBFundingCycleMetadata calldata _metadata,
uint256 _mustStartAtOrAfter,
JBGroupedSplits[] calldata _groupedSplits,
JBFundAccessConstraints[] calldata _fundAccessConstraints,
string calldata _memo
)
external
virtual
override
requirePermission(projects.ownerOf(_projectId), _projectId, JBOperations.RECONFIGURE)
returns (uint256 configuration);

Parameters

NameTypeDescription
_projectIduint256The ID of the project whose funding cycles are being reconfigured.
_dataJBFundingCycleDataData that defines the funding cycle. These properties will remain fixed for the duration of the funding cycle.
_metadataJBFundingCycleMetadataMetadata specifying the controller specific params that a funding cycle can have. These properties will remain fixed for the duration of the funding cycle.
_mustStartAtOrAfteruint256The time before which the configured funding cycle cannot start.
_groupedSplitsJBGroupedSplits[]An array of splits to set for any number of groups.
_fundAccessConstraintsJBFundAccessConstraints[]An array containing amounts that a project can use from its treasury for each payment terminal. Amounts are fixed point numbers using the same number of decimals as the accompanying terminal. The _distributionLimit and _overflowAllowance parameters must fit in a uint232.
_memostringA memo to pass along to the emitted event.

Returns

NameTypeDescription
configurationuint256The configuration of the funding cycle that was successfully reconfigured.

mintTokensOf

Mint new token supply into an account, and optionally reserve a supply to be distributed according to the project's current funding cycle configuration.

Only a project's owner, a designated operator, one of its terminals, or the current data source can mint its tokens.

function mintTokensOf(
uint256 _projectId,
uint256 _tokenCount,
address _beneficiary,
string calldata _memo,
bool _preferClaimedTokens,
bool _useReservedRate
) external virtual override returns (uint256 beneficiaryTokenCount);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to which the tokens being minted belong.
_tokenCountuint256The amount of tokens to mint in total, counting however many should be reserved.
_beneficiaryaddressThe account that the tokens are being minted for.
_memostringA memo to pass along to the emitted event.
_preferClaimedTokensboolA flag indicating whether a project's attached token contract should be minted if they have been issued.
_useReservedRateboolWhether to use the current funding cycle's reserved rate in the mint calculation.

Returns

NameTypeDescription
beneficiaryTokenCountuint256The amount of tokens minted for the beneficiary.

burnTokensOf

Burns a token holder's supply.

Only a token's holder, a designated operator, or a project's terminal can burn it.

function burnTokensOf(
address _holder,
uint256 _projectId,
uint256 _tokenCount,
string calldata _memo,
bool _preferClaimedTokens
)
external
virtual
override
requirePermissionAllowingOverride(
_holder,
_projectId,
JBOperations.BURN,
directory.isTerminalOf(_projectId, IJBPaymentTerminal(msg.sender))
);

Parameters

NameTypeDescription
_holderaddressThe account that is having its tokens burned.
_projectIduint256The ID of the project to which the tokens being burned belong.
_tokenCountuint256The number of tokens to burn.
_memostringA memo to pass along to the emitted event.
_preferClaimedTokensboolA flag indicating whether a project's attached token contract should be burned first if they have been issued.

distributeReservedTokensOf

Distributes all outstanding reserved tokens for a project.

function distributeReservedTokensOf(uint256 _projectId, string calldata _memo)
external
virtual
override
returns (uint256);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to which the reserved tokens belong.
_memostringA memo to pass along to the emitted event.

Returns

NameTypeDescription
<none>uint256The amount of minted reserved tokens.

prepForMigrationOf

Allows other controllers to signal to this one that a migration is expected for the specified project.

This controller should not yet be the project's controller.

function prepForMigrationOf(uint256 _projectId, address _from) external virtual override;

Parameters

NameTypeDescription
_projectIduint256The ID of the project that will be migrated to this controller.
_fromaddressThe controller being migrated from.

migrate

Allows a project to migrate from this controller to another.

Only a project's owner or a designated operator can migrate it.

function migrate(uint256 _projectId, IJBMigratable _to)
external
virtual
override
requirePermission(projects.ownerOf(_projectId), _projectId, JBOperations.MIGRATE_CONTROLLER);

Parameters

NameTypeDescription
_projectIduint256The ID of the project that will be migrated from this controller.
_toIJBMigratableThe controller to which the project is migrating.

_distributeReservedTokensOf

Distributes all outstanding reserved tokens for a project.

function _distributeReservedTokensOf(uint256 _projectId, string memory _memo) internal returns (uint256 tokenCount);

Parameters

NameTypeDescription
_projectIduint256The ID of the project to which the reserved tokens belong.
_memostringA memo to pass along to the emitted event.

Returns

NameTypeDescription
tokenCountuint256The amount of minted reserved tokens.

_distributeToReservedTokenSplitsOf

Distribute tokens to the splits according to the specified funding cycle configuration.

function _distributeToReservedTokenSplitsOf(uint256 _projectId, uint256 _domain, uint256 _group, uint256 _amount)
internal
returns (uint256 leftoverAmount);

Parameters

NameTypeDescription
_projectIduint256The ID of the project for which reserved token splits are being distributed.
_domainuint256The domain of the splits to distribute the reserved tokens between.
_groupuint256The group of the splits to distribute the reserved tokens between.
_amountuint256The total amount of tokens to mint.

Returns

NameTypeDescription
leftoverAmountuint256If the splits percents dont add up to 100%, the leftover amount is returned.

_configure

Configures a funding cycle and stores information pertinent to the configuration.

function _configure(
uint256 _projectId,
JBFundingCycleData calldata _data,
JBFundingCycleMetadata calldata _metadata,
uint256 _mustStartAtOrAfter,
JBGroupedSplits[] memory _groupedSplits,
JBFundAccessConstraints[] memory _fundAccessConstraints
) internal returns (uint256);

Parameters

NameTypeDescription
_projectIduint256The ID of the project whose funding cycles are being reconfigured.
_dataJBFundingCycleDataData that defines the funding cycle. These properties will remain fixed for the duration of the funding cycle.
_metadataJBFundingCycleMetadataMetadata specifying the controller specific params that a funding cycle can have. These properties will remain fixed for the duration of the funding cycle.
_mustStartAtOrAfteruint256The time before which the configured funding cycle cannot start.
_groupedSplitsJBGroupedSplits[]An array of splits to set for any number of groups.
_fundAccessConstraintsJBFundAccessConstraints[]An array containing amounts that a project can use from its treasury for each payment terminal. Amounts are fixed point numbers using the same number of decimals as the accompanying terminal.

Returns

NameTypeDescription
<none>uint256configuration The configuration of the funding cycle that was successfully reconfigured.

Errors

BURN_PAUSED_AND_SENDER_NOT_VALID_TERMINAL_DELEGATE

error BURN_PAUSED_AND_SENDER_NOT_VALID_TERMINAL_DELEGATE();

CANT_MIGRATE_TO_CURRENT_CONTROLLER

error CANT_MIGRATE_TO_CURRENT_CONTROLLER();

FUNDING_CYCLE_ALREADY_LAUNCHED

error FUNDING_CYCLE_ALREADY_LAUNCHED();

INVALID_BALLOT_REDEMPTION_RATE

error INVALID_BALLOT_REDEMPTION_RATE();

INVALID_DISTRIBUTION_LIMIT

error INVALID_DISTRIBUTION_LIMIT();

INVALID_DISTRIBUTION_LIMIT_CURRENCY

error INVALID_DISTRIBUTION_LIMIT_CURRENCY();

INVALID_OVERFLOW_ALLOWANCE

error INVALID_OVERFLOW_ALLOWANCE();

INVALID_OVERFLOW_ALLOWANCE_CURRENCY

error INVALID_OVERFLOW_ALLOWANCE_CURRENCY();

INVALID_REDEMPTION_RATE

error INVALID_REDEMPTION_RATE();

INVALID_RESERVED_RATE

error INVALID_RESERVED_RATE();

MIGRATION_NOT_ALLOWED

error MIGRATION_NOT_ALLOWED();

MINT_NOT_ALLOWED_AND_NOT_TERMINAL_DELEGATE

error MINT_NOT_ALLOWED_AND_NOT_TERMINAL_DELEGATE();

NO_BURNABLE_TOKENS

error NO_BURNABLE_TOKENS();

NOT_CURRENT_CONTROLLER

error NOT_CURRENT_CONTROLLER();

OVERFLOW_ALERT

error OVERFLOW_ALERT();

ZERO_TOKENS_TO_MINT

error ZERO_TOKENS_TO_MINT();