Party

A Party is the core unit of the protocol. The Party smart contract implements governance logic to allow its members to coordinate. This contract also holds the ETH, NFTs, and token balances of the Party and is simultaneously the token contract for Party Cards (implemented as ERC721s) held by its members.

Code

Party.sol

Roles

Members

Users who have voting power in the Party, either through holding a membership NFT or through receiving delegated votes.

Hosts

A special role in the Party. Trusted addresses with the ability to unilaterally veto proposals in the Party and configure Rage Quit. Each Host may or may not be a member.

Authorities

Addresses with the ability to perform sensitive operations like minting and burning new memberships in a Party and updating the voting power of members. Authorities are almost always trusted smart contracts, but may be a highly trusted user in some cases.

Fee Recipient

An optional address that will receive a percentage of all distributions created by the Party. The fee recipient will also receive a percentage of all tokens withdrawn from the Party through Rage Quit.

States

Governance

Inactive

Governance has not begun, and the Party's total voting power has not been set yet. This will be the state of Party governance while the initial crowdfund is still ongoing and not yet been finalized.

Active

Governance has begun and members may create and vote on proposals.

Proposals

Voting

The proposal has been created is within its voting window. Members can vote on the proposal and Hosts can veto the proposal.

Defeated

The proposal has either exceeded its voting window without gathering enough votes or was vetoed by a host.

Passed

The proposal has gathered enough votes to pass but is still waiting through the execution delay before it can be executed. Members can continue to vote on the proposal to reach unanimous consensus, which will bypass the execution delay. Hosts can still veto at this time.

Ready

The proposal has passed and waited through the execution delay, and is now ready to be executed. Any member may execute the proposal until the proposal deadline.

In Progress

The proposal has been executed but has further steps to complete. It will need to be executed again until all steps are complete. No other proposals may be executed while a proposal is “In Progress.” No voting or vetoing of the proposal is allowed during this time. However, the proposal may be forcibly cancelled if enough time has passed since it was first executed.

Complete

The proposal was executed and completed all its steps. No voting or vetoing can occur at this stage, and it cannot be executed again.

Cancelled

The proposal was executed at least once, but it did not complete before the cancel delay passed. Therefore, the proposal was forcibly cancelled.

Functions

propose

Create a proposal for members to vote on, and cast a vote to accept it as well.

Only an active member (has voting power, either intrinsically or delegated to them) can call this. Afterwards, members can vote to support it with accept() or a Party Host can unilaterally reject the proposal with veto().

function propose(Proposal memory proposal, uint256 latestSnapIndex)
    external
    onlyActiveMember
    returns (uint256 proposalId);

Parameters

Name	Type	Description
proposal	Proposal	The details of the proposal.
latestSnapIndex	uint256	The index of the caller's most recent voting power snapshot before the proposal was created. Should be retrieved off-chain and passed in.

accept

Vote to support a proposal.

The voting power cast will be the effective voting power of the caller just before propose() was called (see getVotingPowerAt()). If the proposal reaches passThresholdBps acceptance ratio then the proposal will be in the Passed state and will be executable after the executionDelay has passed, putting it in the Ready state.

function accept(uint256 proposalId, uint256 snapIndex) public returns (uint256 totalVotes);

Parameters

Name	Type	Description
proposalId	uint256	The ID of the proposal to accept.
snapIndex	uint256	The index of the caller's last voting power snapshot before the proposal was created. Should be retrieved off-chain and passed in.

Returns

Name	Type	Description
totalVotes	uint256	The total votes cast on the proposal.

execute

Executes a proposal that has passed governance.

The proposal must be in the Ready or InProgress status. If the proposal only has one step, it will execute and move to the completed state. If the proposal has extra steps to carry out (must be executed again), a ProposalExecuted event will be emitted with a non-empty nextProgressData, in which case nextProgressData should be passed into the next execute() call. The ProposalExecutionEngine enforces that only one InProgress proposal is active at a time, so that proposal must be completed or cancelled via cancel() in order to execute a different proposal. extraData is optional, off-chain data a proposal might need to execute a step.

function execute(
    uint256 proposalId,
    Proposal memory proposal,
    IERC721[] memory preciousTokens,
    uint256[] memory preciousTokenIds,
    bytes calldata progressData,
    bytes calldata extraData
) external payable onlyActiveMember onlyWhenNotGloballyDisabled onlyDelegateCall;

Parameters

Name	Type	Description
proposalId	uint256	The ID of the proposal to execute.
proposal	Proposal	The details of the proposal.
preciousTokens	IERC721[]	The tokens that the Party considers precious.
preciousTokenIds	uint256[]	The token IDs associated with each precious token.
progressData	bytes	The data returned from the last execute() call, if any.
extraData	bytes	Off-chain data a proposal might need to execute a step.

veto

As a Party Host, veto a proposal, moving it to the Defeated state.

The proposal will never be executable and cannot be voted on anymore. A proposal that has been already executed at least once (in the InProgress status) cannot be vetoed.

function veto(uint256 proposalId) external onlyHost;

Parameters

Name	Type	Description
proposalId	uint256	The ID of the proposal to veto.

cancel

Cancel a (probably stuck) InProgress proposal.

proposal.cancelDelay seconds must have passed since it was first executed for this to be valid. The currently active proposal will simply be deleted so another proposal can execute. This is intended to be a last resort and can potentially leave the Party in a broken state. Whenever possible, active proposals should be allowed to complete their lifecycle.

function cancel(uint256 proposalId, Proposal calldata proposal) external onlyActiveMember;

Parameters

Name	Type	Description
proposalId	uint256	The ID of the proposal to cancel.
proposal	Proposal	The details of the proposal to cancel.

delegateVotingPower

Delegate your intrinsic voting power to a new address, removing it from the old one (if any).

function delegateVotingPower(address delegate) external;

Parameters

Name	Type	Description
delegate	address	The address to delegating voting power to.

distribute

Create a token distribution by moving the Party's entire balance to the TokenDistributor contract and immediately creating a distribution governed by this Party.

This will be disabled if distributionsRequireVote flag is set in the ProposalExecutionEngine. In such case, distributions can only be created through a distribution proposal.

The feeBps and feeRecipient this Party was created with will be propagated to the distribution. Party members are entitled to a share of the distribution's tokens proportionate to their relative voting power in this Party (less the fee).

Allow this to be called by the Party itself for FractionalizeProposal.

function distribute(uint256 amount, ITokenDistributor.TokenType tokenType, address token, uint256 tokenId)
    external
    onlyWhenNotGloballyDisabled
    returns (ITokenDistributor.DistributionInfo memory distInfo);

Parameters

Name	Type	Description
amount	uint256	The amount to distribute.
tokenType	ITokenDistributor.TokenType	The type of token to distribute.
token	address	The address of the token to distribute.
tokenId	uint256	The ID of the token to distribute. Currently unused but may be used in the future to support other distribution types.

Returns

Name	Type	Description
distInfo	ITokenDistributor.DistributionInfo	The information about the created distribution.

rageQuit

Burn a Party card and withdraw a fair share of fungible tokens from the Party.

function rageQuit(
    uint256[] calldata tokenIds,
    IERC20[] calldata withdrawTokens,
    uint256[] calldata minWithdrawAmounts,
    address receiver
) external;

Parameters

Name	Type	Description
tokenIds	uint256[]	The IDs of the Party Cards to burn.
withdrawTokens	IERC20[]	The fungible tokens to withdraw. Specify the ETH_ADDRESS value to withdraw ETH.
minWithdrawAmounts	uint256[]	The minimum amount of to withdraw for each token.
receiver	address	The address to receive the withdrawn tokens.

mint

Mint a Party Card for owner with votingPower and immediately delegate voting power to delegate. Only callable by an authority.

function mint(address owner, uint256 votingPower, address delegate) external onlyAuthority returns (uint256 tokenId);

Parameters

Name	Type	Description
owner	address	The owner of the NFT.
votingPower	uint256	The voting power of the NFT.
delegate	address	The address to delegate voting power to.

increaseVotingPower

Add voting power to an existing NFT. Only callable by an authority.

function increaseVotingPower(uint256 tokenId, uint256 votingPower) external onlyAuthority;

Parameters

Name	Type	Description
tokenId	uint256	The ID of the NFT to add voting power to.
votingPower	uint256	The amount of voting power to add.

decreaseVotingPower

Remove voting power from an existing NFT. Only callable by an authority.

function decreaseVotingPower(uint256 tokenId, uint96 votingPower) external;

Parameters

Name	Type	Description
tokenId	uint256	The ID of the NFT to remove voting power from.
votingPower	uint96	The amount of voting power to remove.

increaseTotalVotingPower

Update the total voting power of the Party. Only callable by an authority.

function increaseTotalVotingPower(uint96 newVotingPower) external onlyAuthority;

Parameters

Name	Type	Description
newVotingPower	uint96	The new total voting power to add.

decreaseTotalVotingPower

Decrease the total voting power of the party. Only callable by an authority.

function decreaseTotalVotingPower(uint96 votingPower) external;

Parameters

Name	Type	Description
votingPower	uint96	The new total voting power to add.

burn

Burn governance NFTs and remove their voting power. Can only be called by an authority before the party has started.

function burn(uint256[] memory tokenIds) public;

Parameters

Name	Type	Description
tokenIds	uint256[]	The IDs of the governance NFTs to burn.

rageQuit

Burn a governance NFT and withdraw a fair share of fungible tokens from the party.

function rageQuit(
    uint256[] calldata tokenIds,
    IERC20[] calldata withdrawTokens,
    uint256[] calldata minWithdrawAmounts,
    address receiver
) external;

Parameters

Name	Type	Description
tokenIds	uint256[]	The IDs of the governance NFTs to burn.
withdrawTokens	IERC20[]	The fungible tokens to withdraw. Specify the ETH_ADDRESS value to withdraw ETH.
minWithdrawAmounts	uint256[]	The minimum amount of to withdraw for each token.
receiver	address	The address to receive the withdrawn tokens.

setRageQuit

Set the timestamp until which ragequit is enabled. Can be set to the ENABLE_RAGEQUIT_PERMANENTLY/DISABLE_RAGEQUIT_PERMANENTLY values to enable/disable ragequit permanently. DISABLE_RAGEQUIT_PERMANENTLY can only be set during initialization.

function setRageQuit(uint40 newRageQuitTimestamp) external onlyHost;

Parameters

Name	Type	Description
newRageQuitTimestamp	uint40	The new ragequit timestamp.

abdicateHost

Transfer Party Host status to another address.

function abdicateHost(address newPartyHost) external onlyHost;

Parameters

Name	Type	Description
newPartyHost	address	The address of the new Host.

addAuthority

Add a new authority.

Used in AddAuthorityProposal. Only the party itself can add authorities to prevent it from being used anywhere else.

function addAuthority(address authority) external onlySelf;

abdicateAuthority

Relinquish the authority role.

function abdicateAuthority() external onlyAuthority;

transferFrom

function transferFrom(address owner, address to, uint256 tokenId) public override;

safeTransferFrom

function safeTransferFrom(address owner, address to, uint256 tokenId) public override;

safeTransferFrom

function safeTransferFrom(address owner, address to, uint256 tokenId, bytes calldata data) public override;

ownerOf

function ownerOf(uint256 tokenId) public view override returns (address owner);

tokenURI

function tokenURI(uint256) public view override returns (string memory);

contractURI

Returns a URI for the storefront-level metadata for your contract.

function contractURI() external view returns (string memory);

royaltyInfo

Called with the sale price to determine how much royalty

function royaltyInfo(uint256, uint256) external view returns (address, uint256);

getDistributionShareOf

Return the distribution share amount of a token. Included as an alias for votePowerByTokenId for backwards compatibility with old TokenDistributor implementations.

function getDistributionShareOf(uint256 tokenId) public view returns (uint256);

Parameters

Name	Type	Description
tokenId	uint256	The token ID to query.

Returns

Name	Type	Description
share	uint256	The distribution shares of tokenId.

getVotingPowerShareOf

Return the voting power share of a token. Denominated fractions of 1e18. I.e., 1e18 = 100%.

function getVotingPowerShareOf(uint256 tokenId) public view returns (uint256);

Parameters

Name	Type	Description
tokenId	uint256	The token ID to query.

Returns

Name	Type	Description
share	uint256	The voting power percentage of tokenId.

getProposalExecutionEngine

Get the current ProposalExecutionEngine instance.

function getProposalExecutionEngine() external view returns (IProposalExecutionEngine);

getProposalEngineOpts

Get the current ProposalEngineOpts options.

function getProposalEngineOpts() external view returns (ProposalEngineOpts memory);

getVotingPowerAt

Get the total voting power of voter at a timestamp.

function getVotingPowerAt(address voter, uint40 timestamp) external view returns (uint96 votingPower);

Parameters

Name	Type	Description
voter	address	The address of the voter.
timestamp	uint40	The timestamp at which to to get the voting power.

Returns

Name	Type	Description
votingPower	uint96	The total voting power of voter at timestamp.

getVotingPowerAt

Get the total voting power of voter at a snapshot snapIndex, with checks to make sure it is the latest voting snapshot =< timestamp.

function getVotingPowerAt(address voter, uint40 timestamp, uint256 snapIndex)
    public
    view
    returns (uint96 votingPower);

Parameters

Name	Type	Description
voter	address	The address of the voter.
timestamp	uint40	The timestamp at which to get the voting power.
snapIndex	uint256	The index of the snapshot at which to get the voting power.

Returns

Name	Type	Description
votingPower	uint96	The total voting power of voter at timestamp.

getProposalStateInfo

Get the state of a proposal.

function getProposalStateInfo(uint256 proposalId)
    external
    view
    returns (ProposalStatus status, ProposalStateValues memory values);

Parameters

Name	Type	Description
proposalId	uint256	The ID of the proposal.

Returns

Name	Type	Description
status	ProposalStatus	The status of the proposal.
values	ProposalStateValues	The state of the proposal.

getGovernanceValues

Retrieve fixed governance parameters.

function getGovernanceValues() external view returns (GovernanceValues memory gv);

Returns

Name	Type	Description
gv	GovernanceValues	The governance parameters of this Party.

getProposalHash

Get the hash of a proposal.

Proposal details are not stored on-chain so the hash is used to enforce consistency between calls.

function getProposalHash(Proposal memory proposal) public pure returns (bytes32 proposalHash);

Parameters

Name	Type	Description
proposal	Proposal	The proposal to hash.

Returns

Name	Type	Description
proposalHash	bytes32	The hash of the proposal.

findVotingPowerSnapshotIndex

Get the index of the most recent voting power snapshot <= timestamp.

function findVotingPowerSnapshotIndex(address voter, uint40 timestamp) public view returns (uint256 index);

Parameters

Name	Type	Description
voter	address	The address of the voter.
timestamp	uint40	The timestamp at which to get the snapshot index.

Returns

Name	Type	Description
index	uint256	The index of the snapshot.