TerminalV1

Git Source

Mainnet: 0xd569D3CCE55b71a8a3f3C418c329A66e5f714431

Inherits: Operatable, ITerminalV1, ITerminal, ReentrancyGuard

This contract manages the Juicebox ecosystem, serves as a payment terminal, and custodies all funds.

A project can transfer its funds, along with the power to reconfigure and mint/burn their Tickets, from this contract to another allowed terminal contract at any time.

State Variables

_processedTicketTrackerOf

mapping(uint256 => int256) private _processedTicketTrackerOf;

_preconfigureTicketCountOf

mapping(uint256 => uint256) private _preconfigureTicketCountOf;

projects

The Projects contract which mints ERC-721's that represent project ownership and transfers.

IProjects public immutable override projects;

fundingCycles

The contract storing all funding cycle configurations.

IFundingCycles public immutable override fundingCycles;

ticketBooth

The contract that manages Ticket printing and redeeming.

ITicketBooth public immutable override ticketBooth;

modStore

The contract that stores mods for each project.

IModStore public immutable override modStore;

prices

The prices feeds.

IPrices public immutable override prices;

terminalDirectory

The directory of terminals.

ITerminalDirectory public immutable override terminalDirectory;

balanceOf

The amount of ETH that each project is responsible for.

mapping(uint256 => uint256) public override balanceOf;

fee

The percent fee the Juicebox project takes from tapped amounts. Out of 200.

uint256 public override fee = 10;

governance

The governance of the contract who makes fees and can allow new TerminalV1 contracts to be migrated to by project owners.

address payable public override governance;

pendingGovernance

The governance of the contract who makes fees and can allow new TerminalV1 contracts to be migrated to by project owners.

address payable public override pendingGovernance;

migrationIsAllowed

mapping(ITerminal => bool) public override migrationIsAllowed;

Functions

onlyGov

modifier onlyGov();

currentOverflowOf

Gets the current overflowed amount for a specified project.

function currentOverflowOf(uint256 _projectId) external view override returns (uint256 overflow);

Parameters

Name	Type	Description
_projectId	uint256	The ID of the project to get overflow for.

Returns

Name	Type	Description
overflow	uint256	The current overflow of funds for the project.

reservedTicketBalanceOf

Gets the amount of reserved tickets that a project has.

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

Parameters

Name	Type	Description
_projectId	uint256	The ID of the project to get overflow for.
_reservedRate	uint256	The reserved rate to use to make the calculation.

Returns

Name	Type	Description
<none>	uint256	amount overflow The current overflow of funds for the project.

claimableOverflowOf

The amount of tokens that can be claimed by the given address.

The _account must have at least _count tickets for the specified project.

If there is a funding cycle reconfiguration ballot open for the project, the project's current bonding curve is bypassed.

function claimableOverflowOf(address _account, uint256 _projectId, uint256 _count)
    public
    view
    override
    returns (uint256);

Parameters

Name	Type	Description
_account	address	The address to get an amount for.
_projectId	uint256	The ID of the project to get a claimable amount for.
_count	uint256	The number of Tickets that would be redeemed to get the resulting amount.

Returns

Name	Type	Description
<none>	uint256	amount The amount of tokens that can be claimed.

canPrintPreminedTickets

Whether or not a project can still print premined tickets.

function canPrintPreminedTickets(uint256 _projectId) public view override returns (bool);

Parameters

Name	Type	Description
_projectId	uint256	The ID of the project to get the status of.

Returns

Name	Type	Description
<none>	bool	Boolean flag.

constructor

constructor(
    IProjects _projects,
    IFundingCycles _fundingCycles,
    ITicketBooth _ticketBooth,
    IOperatorStore _operatorStore,
    IModStore _modStore,
    IPrices _prices,
    ITerminalDirectory _terminalDirectory,
    address payable _governance
) Operatable(_operatorStore);

Parameters

Name	Type	Description
_projects	IProjects	A Projects contract which mints ERC-721's that represent project ownership and transfers.
_fundingCycles	IFundingCycles	A funding cycle configuration store.
_ticketBooth	ITicketBooth	A contract that manages Ticket printing and redeeming.
_operatorStore	IOperatorStore	A contract storing operator assignments.
_modStore	IModStore	A storage for a project's mods.
_prices	IPrices	A price feed contract to use.
_terminalDirectory	ITerminalDirectory	A directory of a project's current Juicebox terminal to receive payments in.
_governance	address payable

deploy

Deploys a project. This will mint an ERC-721 into the _owner's account, configure a first funding cycle, and set up any mods.

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

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

_properties.target The amount that the project wants to receive in this funding cycle. Sent as a wad.

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

_properties.duration The duration of the funding stage for which the target amount is needed. Measured in days. Send 0 for a boundless cycle reconfigurable at any time.

_properties.cycleLimit The number of cycles that this configuration should last for before going back to the last permanent. This has no effect for a project's first funding cycle.

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

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

_metadata.reservedRate A number from 0-200 indicating the percentage of each contribution's tickets that will be reserved for the project owner.

• _metadata.bondingCurveRate The rate from 0-200 at which a project's Tickets can be redeemed for surplus. The bonding curve formula is https://www.desmos.com/calculator/sp9ru6zbpk where x is _count, o is _currentOverflow, s is _totalSupply, and r is _bondingCurveRate.

_metadata.reconfigurationBondingCurveRate The bonding curve rate to apply when there is an active ballot.

function deploy(
    address _owner,
    bytes32 _handle,
    string calldata _uri,
    FundingCycleProperties calldata _properties,
    FundingCycleMetadata calldata _metadata,
    PayoutMod[] memory _payoutMods,
    TicketMod[] memory _ticketMods
) external override;

Parameters

Name	Type	Description
_owner	address	The address that will own the project.
_handle	bytes32	The project's unique handle.
_uri	string	A link to information about the project and this funding cycle.
_properties	FundingCycleProperties	The funding cycle configuration.
_metadata	FundingCycleMetadata	A struct specifying the TerminalV1 specific params _bondingCurveRate, and _reservedRate.
_payoutMods	PayoutMod[]	Any payout mods to set.
_ticketMods	TicketMod[]	Any ticket mods to set.

configure

Configures the properties of the current funding cycle if the project hasn't distributed tickets yet, or sets the properties of the proposed 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.

_properties.target The amount that the project wants to receive in this funding stage. Sent as a wad.

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

_properties.duration The duration of the funding stage for which the target amount is needed. Measured in days. Send 0 for a boundless cycle reconfigurable at any time.

_properties.cycleLimit The number of cycles that this configuration should last for before going back to the last permanent. This has no effect for a project's first funding cycle.

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

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

_metadata.reservedRate A number from 0-200 indicating the percentage of each contribution's tickets that will be reserved for the project owner.

• _metadata.bondingCurveRate The rate from 0-200 at which a project's Tickets can be redeemed for surplus. The bonding curve formula is https://www.desmos.com/calculator/sp9ru6zbpk where x is _count, o is _currentOverflow, s is _totalSupply, and r is _bondingCurveRate.

_metadata.reconfigurationBondingCurveRate The bonding curve rate to apply when there is an active ballot.

function configure(
    uint256 _projectId,
    FundingCycleProperties calldata _properties,
    FundingCycleMetadata calldata _metadata,
    PayoutMod[] memory _payoutMods,
    TicketMod[] memory _ticketMods
)
    external
    override
    requirePermission(projects.ownerOf(_projectId), _projectId, Operations.Configure)
    returns (uint256);

Parameters

Name	Type	Description
_projectId	uint256	The ID of the project being reconfigured.
_properties	FundingCycleProperties	The funding cycle configuration.
_metadata	FundingCycleMetadata	A struct specifying the TerminalV1 specific params _bondingCurveRate, and _reservedRate.
_payoutMods	PayoutMod[]
_ticketMods	TicketMod[]

Returns

Name	Type	Description
<none>	uint256	The ID of the funding cycle that was successfully configured.

printPreminedTickets

Allows a project to print tickets for a specified beneficiary before payments have been received.

This can only be done if the project hasn't yet received a payment after configuring a funding cycle.

Only a project's owner or a designated operator can print premined tickets.

function printPreminedTickets(
    uint256 _projectId,
    uint256 _amount,
    uint256 _currency,
    address _beneficiary,
    string memory _memo,
    bool _preferUnstakedTickets
) external override requirePermission(projects.ownerOf(_projectId), _projectId, Operations.PrintPreminedTickets);

Parameters

Name	Type	Description
_projectId	uint256	The ID of the project to premine tickets for.
_amount	uint256	The amount to base the ticket premine off of.
_currency	uint256	The currency of the amount to base the ticket premine off of.
_beneficiary	address	The address to send the printed tickets to.
_memo	string	A memo to leave with the printing.
_preferUnstakedTickets	bool	If there is a preference to unstake the printed tickets.

pay

Contribute ETH to a project.

Print's the project's tickets proportional to the amount of the contribution.

The msg.value is the amount of the contribution in wei.

function pay(uint256 _projectId, address _beneficiary, string calldata _memo, bool _preferUnstakedTickets)
    external
    payable
    override
    returns (uint256);

Parameters

Name	Type	Description
_projectId	uint256	The ID of the project being contribute to.
_beneficiary	address	The address to print Tickets for.
_memo	string	A memo that will be included in the published event.
_preferUnstakedTickets	bool	Whether ERC20's should be unstaked automatically if they have been issued.

Returns

Name	Type	Description
<none>	uint256	The ID of the funding cycle that the payment was made during.

tap

Tap into funds that have been contributed to a project's current funding cycle.

Anyone can tap funds on a project's behalf.

function tap(uint256 _projectId, uint256 _amount, uint256 _currency, uint256 _minReturnedWei)
    external
    override
    nonReentrant
    returns (uint256);

Parameters

Name	Type	Description
_projectId	uint256	The ID of the project to which the funding cycle being tapped belongs.
_amount	uint256	The amount being tapped, in the funding cycle's currency.
_currency	uint256	The expected currency being tapped.
_minReturnedWei	uint256	The minimum number of wei that the amount should be valued at.

Returns

Name	Type	Description
<none>	uint256	The ID of the funding cycle that was tapped.

redeem

Addresses can redeem their Tickets to claim the project's overflowed ETH.

Only a ticket's holder or a designated operator can redeem it.

function redeem(
    address _account,
    uint256 _projectId,
    uint256 _count,
    uint256 _minReturnedWei,
    address payable _beneficiary,
    bool _preferUnstaked
)
    external
    override
    nonReentrant
    requirePermissionAllowingWildcardDomain(_account, _projectId, Operations.Redeem)
    returns (uint256 amount);

Parameters

Name	Type	Description
_account	address	The account to redeem tickets for.
_projectId	uint256	The ID of the project to which the Tickets being redeemed belong.
_count	uint256	The number of Tickets to redeem.
_minReturnedWei	uint256	The minimum amount of Wei expected in return.
_beneficiary	address payable	The address to send the ETH to.
_preferUnstaked	bool	If the preference is to redeem tickets that have been converted to ERC-20s.

Returns

Name	Type	Description
amount	uint256	The amount of ETH that the tickets were redeemed for.

migrate

Allows a project owner to migrate its funds and operations to a new contract.

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

function migrate(uint256 _projectId, ITerminal _to)
    external
    override
    requirePermission(projects.ownerOf(_projectId), _projectId, Operations.Migrate)
    nonReentrant;

Parameters

Name	Type	Description
_projectId	uint256	The ID of the project being migrated.
_to	ITerminal	The contract that will gain the project's funds.

addToBalance

Receives and allocates funds belonging to the specified project.

function addToBalance(uint256 _projectId) external payable override;

Parameters

Name	Type	Description
_projectId	uint256	The ID of the project to which the funds received belong.

allowMigration

Adds to the contract addresses that projects can migrate their Tickets to.

Only governance can add a contract to the migration allow list.

function allowMigration(ITerminal _contract) external override onlyGov;

Parameters

Name	Type	Description
_contract	ITerminal	The contract to allow.

setFee

Allow the admin to change the fee.

*Only funding cycle reconfigurations after the new fee is set will use the new fee. All future funding cycles based on configurations made in the past will use the fee that was set at the time of the configuration.

Only governance can set a new fee.

function setFee(uint256 _fee) external override onlyGov;

Parameters

Name	Type	Description
_fee	uint256	The new fee percent. Out of 200.

appointGovernance

Allows governance to transfer its privileges to another contract.

Only the currency governance can appoint a new governance.

This address will have to accept the responsibility in a subsequent transaction.

function appointGovernance(address payable _pendingGovernance) external override onlyGov;

Parameters

Name	Type	Description
_pendingGovernance	address payable	The governance to transition power to.

acceptGovernance

Allows contract to accept its appointment as the new governance.

function acceptGovernance() external override;

printReservedTickets

Prints all reserved tickets for a project.

function printReservedTickets(uint256 _projectId) public override returns (uint256 amount);

Parameters

Name	Type	Description
_projectId	uint256	The ID of the project to which the reserved tickets belong.

Returns

Name	Type	Description
amount	uint256	The amount of tickets that are being printed.

_distributeToPayoutMods

Pays out the mods for the specified funding cycle.

function _distributeToPayoutMods(FundingCycle memory _fundingCycle, uint256 _amount, string memory _memo)
    private
    returns (uint256 leftoverAmount);

Parameters

Name	Type	Description
_fundingCycle	FundingCycle	The funding cycle to base the distribution on.
_amount	uint256	The total amount being paid out.
_memo	string	A memo to send along with project payouts.

Returns

Name	Type	Description
leftoverAmount	uint256	If the mod percents dont add up to 100%, the leftover amount is returned.

_distributeToTicketMods

distributed tickets to the mods for the specified funding cycle.

function _distributeToTicketMods(FundingCycle memory _fundingCycle, uint256 _amount)
    private
    returns (uint256 leftoverAmount);

Parameters

Name	Type	Description
_fundingCycle	FundingCycle	The funding cycle to base the ticket distribution on.
_amount	uint256	The total amount of tickets to print.

Returns

Name	Type	Description
leftoverAmount	uint256	If the mod percents dont add up to 100%, the leftover amount is returned.

_pay

See the documentation for 'pay'.

function _pay(
    uint256 _projectId,
    uint256 _amount,
    address _beneficiary,
    string memory _memo,
    bool _preferUnstakedTickets
) private returns (uint256);

_overflowFrom

Gets the amount overflowed in relation to the provided funding cycle.

This amount changes as the price of ETH changes against the funding cycle's currency.

function _overflowFrom(FundingCycle memory _currentFundingCycle) private view returns (uint256);

Parameters

Name	Type	Description
_currentFundingCycle	FundingCycle	The ID of the funding cycle to base the overflow on.

Returns

Name	Type	Description
<none>	uint256	overflow The current overflow of funds.

_reservedTicketAmountFrom

Gets the amount of reserved tickets currently tracked for a project given a reserved rate.

function _reservedTicketAmountFrom(int256 _processedTicketTracker, uint256 _reservedRate, uint256 _totalEligibleTickets)
    private
    pure
    returns (uint256);

Parameters

Name	Type	Description
_processedTicketTracker	int256	The tracker to make the calculation with.
_reservedRate	uint256	The reserved rate to use to make the calculation.
_totalEligibleTickets	uint256	The total amount to make the calculation with.

Returns

Name	Type	Description
<none>	uint256	amount reserved ticket amount.

_validateAndPackFundingCycleMetadata

Validate and pack the funding cycle metadata.

function _validateAndPackFundingCycleMetadata(FundingCycleMetadata memory _metadata)
    private
    pure
    returns (uint256 packed);

Parameters

Name	Type	Description
_metadata	FundingCycleMetadata	The metadata to validate and pack.

Returns

Name	Type	Description
packed	uint256	The packed uint256 of all metadata params. The first 8 bytes specify the version.

_takeFee

Takes a fee into the Governance contract's project.

function _takeFee(uint256 _from, uint256 _percent, address _beneficiary, string memory _memo)
    private
    returns (uint256 feeAmount);

Parameters

Name	Type	Description
_from	uint256	The amount to take a fee from.
_percent	uint256	The percent fee to take. Out of 200.
_beneficiary	address	The address to print governance's tickets for.
_memo	string	A memo to send with the fee.

Returns

Name	Type	Description
feeAmount	uint256	The amount of the fee taken.