All pages
Powered by GitBook
1 of 4

Staking

StakingProxy is proxy, and its implementation is StakingPackage.

The Staking Package is designed for creating and managing staking streams, handling user stakes with the ability to lock and unlock tokens, and calculating rewards. The contract allows for the addition of new staking streams, each with unique parameters like reward schedules and lock periods. It also enforces rules around the early withdrawal of stakes, calculating penalties, and distributing rewards, ensuring a robust and flexible staking environment.

State Variables

mainStreamInitialized:

  • Type: bool

  • Description: Indicates whether the main stream has been initialized.

MAIN_STREAM:

  • Type: uint256

  • Description: The constant identifier for the main staking stream.

streams:

  • Type: Stream[]

  • Description: Dynamic array storing all streams available for staking.

locks:

  • Type: mapping(address => LockedBalance[])

  • Description: Maps user addresses to their respective locked balances.

users:

  • Type: mapping(address => User)

  • Description: Maps user addresses to their staking-related data.

streamTotalUserPendings:

  • Type: mapping(uint256 => uint256)

  • Description: Maps stream IDs to total pending tokens for users.

prohibitedEarlyWithdraw:

  • Type: mapping(address => mapping(uint256 => bool))

  • Description: Tracks locks that cannot be unlocked early.

totalAmountOfStakedToken, totalStreamShares, totalAmountOfVoteToken:

  • Type: uint256

  • Description: Track the total amounts of staked tokens, stream shares, and vote tokens across all users.

totalPenaltyBalance:

  • Type: uint256

  • Description: Sum of all penalties collected from early withdrawals.

vault, treasury, rewardsCalculator, mainToken, voteToken:

  • Type: address

  • Description: Addresses of contracts for the vault, treasury, rewards calculation, main token, and voting token.

minLockPeriod, maxLockPeriod:

  • Type: uint256

  • Description: The minimum and maximum lock periods for staking tokens.

maxLockPositions:

  • Type: uint256

  • Description: Maximum number of lock positions a user can have.

Structs

Schedule:

  • time: An array of timestamps indicating the start of each reward distribution interval. The last timestamp marks the stream's end.

  • reward: An array parallel to time, specifying the amount of rewards at the start of each interval. The final entry is always zero, marking the end of rewards.

User:

  • voteTokenBalance: Represents the total balance of voting tokens a user possesses.

  • pendings: A mapping from a stream ID to the amount of tokens pending release for the user.

  • releaseTime: A mapping from a stream ID to the timestamp when tokens are scheduled for release.

  • rpsDuringLastClaimForLock: Nested mappings from stream ID and lock ID to the reward-per-share value noted at the last claim.

Weight:

  • maxWeightShares, minWeightShares: Used to calculate the share weight over time from maximum to minimum.

  • maxWeightPenalty, minWeightPenalty, penaltyWeightMultiplier: Parameters for calculating early withdrawal penalties.

VoteCoefficient:

  • voteShareCoef, voteLockCoef: Coefficients influencing the voting power derived from token shares and lock duration, respectively.

LockedBalance:

  • amountOfToken, positionStreamShares: Tokens locked and shares of the position within a stream, respectively.

  • end: The expiration of the lock.

  • owner: The owner of the lock.

  • amountOfVoteToken: Amount of vote tokens reflecting the voting power from this lock.

Stream:

  • Contains properties such as the owner, the manager, reward token type, status, financial thresholds, schedule data, and others. Status is managed through an enum (StreamStatus), which tracks if a stream is active, proposed, or inactive.

CreateLockParams:

  • Details required to create a lock: amount of tokens, lockPeriod, and the account the lock is associated with.

Set Functions

createLock

  • Arguments:

    • uint256 amount: The amount of tokens to be locked.

    • uint256 lockPeriod: The period for which the tokens are locked.

  • Returns:

    • No return value. This function processes the locking of tokens and interacts with the internal state.

unlock

  • Arguments:

    • uint256 lockId: The identifier of the lock to be unlocked.

  • Returns:

    • No return value. This function processes the unlocking of tokens, updating the internal state to reflect the change.

unlockPartially

  • Arguments:

    • uint256 lockId: The identifier of the lock to be partially unlocked.

    • uint256 amount: The amount of tokens to unlock from the specified lock.

  • Returns:

    • No return value. This function allows partial unlocking of locked tokens and modifies the internal state accordingly.

earlyUnlock

  • Arguments:

    • uint256 lockId: The identifier of the lock to be unlocked early.

  • Returns:

    • No return value. It handles the early unlocking process, adjusting the user's locked tokens and any applicable penalties.

claimAllStreamRewardsForLock

  • Arguments:

    • uint256 lockId: The identifier of the lock for which all stream rewards are claimed.

  • Returns:

    • No return value. This function processes the claiming of all rewards associated with a particular lock.

claimAllLockRewardsForStream

  • Arguments:

    • uint256 streamId: The identifier of the stream for which all rewards for all locks are claimed.

  • Returns:

    • No return value. It handles the claiming of rewards for all locks associated with a specific stream.

withdrawStream

  • Arguments:

    • uint256 streamId: The identifier of the stream from which to withdraw rewards.

  • Returns:

    • No return value. This function processes the withdrawal of rewards from a specific stream.

withdrawAllStreams

  • Arguments:

    • None.

  • Returns:

    • No return value. This function facilitates the withdrawal of rewards from all streams associated with the caller.

Events

Staked

  • Emitted when: A new lock is created and tokens are staked.

  • Parameters:

    • address indexed account: The account that staked tokens.

    • uint256 amount: The amount of tokens staked.

    • uint256 streamShares: Shares received in the stream due to staking.

    • uint256 nVoteToken: Number of voting tokens allocated.

    • uint256 indexed lockId: The identifier of the lock.

    • uint256 end: When the lock will end.

StreamProposed

  • Emitted when: A new stream is proposed.

  • Parameters:

    • uint256 indexed streamId: Identifier of the proposed stream.

    • address indexed streamOwner: The owner of the stream.

    • address indexed rewardToken: The token used for rewards in the stream.

    • uint256 maxDepositAmount: The maximum amount that can be deposited in the stream.

Released

  • Emitted when: Tokens are released from a stream.

  • Parameters:

    • uint256 indexed streamId: The stream from which tokens are released.

    • address indexed user: The user receiving the released tokens.

    • uint256 pendingAmount: The amount of tokens released.

StreamProposalCancelled

  • Emitted when: A proposed stream is cancelled.

  • Parameters:

    • uint256 indexed streamId: The stream that was cancelled.

    • address indexed owner: Owner of the stream.

    • address indexed token: The reward token associated with the cancelled stream.

StreamCreated

  • Emitted when: A stream is created and becomes active.

  • Parameters:

    • uint256 indexed streamId: The identifier of the created stream.

    • address indexed owner: The owner of the stream.

    • address indexed token: The reward token of the stream.

    • uint256 tau: The pending time prior reward release for the stream.

StreamRemoved

  • Emitted when: A stream is removed.

  • Parameters:

    • uint256 indexed streamId: The identifier of the removed stream.

    • address indexed owner: The owner of the stream.

    • address indexed token: The reward token of the removed stream.

Unstaked

  • Emitted when: A full unlock is performed on a lock.

  • Parameters:

    • address indexed account: The account that unstaked tokens.

    • uint256 amount: The amount of tokens unstaked.

    • uint256 indexed lockId: The identifier of the lock from which tokens were unstaked.

PartialUnstaked

  • Emitted when: A partial unlock is performed on a lock.

  • Parameters:

    • address indexed account: The account that partially unstaked tokens.

    • uint256 amount: The amount of tokens unstaked.

    • uint256 indexed lockId: The identifier of the lock from which tokens were partially unstaked.

Pending

  • Emitted when: Rewards are moved to pending for a user in a stream.

  • Parameters:

    • uint256 indexed streamId: The stream where rewards are pending.

    • address indexed account: The user for whom rewards are pending.

    • uint256 pendings: Amount of tokens that are pending.

Vault

https://github.com/Into-the-Fathom/fathom-dao-smart-contracts/blob/master/contracts/dao/staking/vault/packages/VaultPackage.sol

VaultProxy is proxy, and its implementation is VaultPackage.

The VaultPackage contract manages the operations and state related to supported tokens and their deposits within the vault. It handles the addition and removal of tokens, depositing of tokens for rewards, and managing migration of tokens to a new vault package.

State Variables:

deposited (mapping(address => uint256))

  • Description: Tracks the total amount of each token that has been deposited into the vault.

  • Key: Token address.

  • Value: Amount deposited.

isSupportedToken (mapping(address => bool))

  • Description: Indicates whether a token is supported by the vault.

  • Key: Token address.

  • Value: Boolean indicating support.

listOfSupportedTokens (address[])

  • Description: An array of token addresses that are currently supported by the vault.

migrated (bool)

  • Description: A boolean flag indicating if the vault has been migrated to a new package.

Set Functions:

deposit(address _token, uint256 _amount)

  • Deposits a specified amount of a supported token into the vault.

  • Parameters:

    • _token (address): The token's address.

    • _amount (uint256): Amount of the token to deposit.

  • Returns: None.

payRewards(address _user, address _token, uint256 _amount)

  • Pays out rewards to a user from the deposited tokens.

  • Parameters:

    • _user (address): The user's address.

    • _token (address): The token's address.

    • _amount (uint256): Amount of the token to pay out.

  • Returns: None.

addSupportedToken(address _token)

  • Adds a token to the list of supported tokens.

  • Parameters:

    • _token (address): The token's address.

  • Returns: None.

removeSupportedToken(address _token)

  • Removes a token from the list of supported tokens.

  • Parameters:

    • _token (address): The token's address.

  • Returns: None.

migrate(address newVaultPackage)

  • Migrates the vault to a new package.

  • Parameters:

    • newVaultPackage (address): The new vault package's address.

  • Returns: None.

withdrawExtraSupportedTokens(address _withdrawTo)

  • Withdraws excess balances of supported tokens.

  • Parameters:

    • _withdrawTo (address): Address to which the tokens will be withdrawn.

  • Returns: None.

withdrawExtraUnsupportedToken(address _token, address _withdrawTo)

  • Withdraws all balances of an unsupported token.

  • Parameters:

    • _token (address): The token's address.

    • _withdrawTo (address): Address to which the tokens will be withdrawn.

  • Returns: None.

Events:

TokenAdded

  • Emitted when a token is added to the list of supported tokens.

  • Parameters:

    • tokenAddress (address indexed): Address of the token added.

    • addedBy (address indexed): Address of the user who added the token.

    • timestamp (uint256): Time at which the token was added.

TokenRemoved

  • Emitted when a token is removed from the list of supported tokens.

  • Parameters:

    • tokenAddress (address indexed): Address of the token removed.

    • removedBy (address indexed): Address of the user who removed the token.

    • timestamp (uint256): Time at which the token was removed.

RewardsCalculator

https://github.com/Into-the-Fathom/fathom-dao-smart-contracts/tree/master/contracts/dao/staking/packages

The RewardsCalculator contract, a component of the Fathom DAO Staking, is designed to handle and calculate rewards distribution for staking activities. It leverages a detailed schedule system to determine rewards over different time frames, ensuring flexibility and accuracy in reward calculations. It also includes functionality to handle errors related to inputs and state conditions rigorously, thus maintaining the integrity and robustness of the rewards distribution mechanism.

Storage Variables

MAXIMUM_PERCENT_TO_TREASURY

  • Type: uint256

  • Visibility: public constant

  • Description: Represents the maximum allowable percentage of rewards that can be allocated to the treasury, set at 10,000 to represent 100% using a base-10000 system for precision.

Read Functions

validateStreamParameters

  • Arguments:

    • address streamOwner - The owner of the reward stream.

    • address rewardToken - The token used for rewards.

    • uint256 percentToTreasury - The percentage of rewards directed to the treasury.

    • uint256 maxDepositAmount - The maximum deposit amount allowed.

    • uint256 minDepositAmount - The minimum deposit amount required.

    • uint256[] scheduleTimes - An array of times defining the reward schedule.

    • uint256[] scheduleRewards - Corresponding rewards for each scheduled time.

    • uint256 tau - A specific parameter used in reward calculations.

  • Return Values: None. Reverts on validation failure with specific errors.

getRewardsAmount

  • Arguments:

    • Schedule calldata schedule - The reward schedule details.

    • uint256 lastUpdate - The last update time for calculating incremental rewards.

  • Return Values:

    • uint256 - The amount of rewards calculated based on the schedule and time updates.

vFTHM

https://github.com/Into-the-Fathom/fathom-dao-smart-contracts/blob/master/contracts/dao/tokens/VMainToken.sol

vFTHM is a specialized governance token designed for the Fathom protocol. It incorporates features from several OpenZeppelin libraries, providing advanced functionality such as role-based access control, pausing capabilities, and permit-based approvals. The token is non-transferable unless the sender is on an allowlist, ensuring security and control over token transfers. The token's minting and burning capabilities are restricted to accounts with the minter role, which can be dynamically granted or revoked by an admin. This setup ensures that only authorized accounts can manage the token supply while maintaining strict control over token operations.

Setter Functions

transfer(address to, uint256 amount)

  • Parameters:

    • to: The address of the recipient.

    • amount: The number of tokens to transfer.

  • Returns:

    • bool: Whether the transfer was successful.

  • Description: Transfers tokens to a specified address.

approve(address spender, uint256 amount)

  • Parameters:

    • spender: The address of the spender.

    • amount: The number of tokens to approve.

  • Returns:

    • bool: Whether the approval was successful.

  • Description: Approves the specified number of tokens for spending by the spender.

transferFrom(address from, address to, uint256 amount)

  • Parameters:

    • from: The address of the sender.

    • to: The address of the recipient.

    • amount: The number of tokens to transfer.

  • Returns:

    • bool: Whether the transfer was successful.

  • Description: Transfers tokens from one specified address to another.

pause()

  • Parameters: None

  • Returns: None

  • Description: Pauses all token transfers and minting functions, putting the contract in a paused state.

unpause()

  • Parameters: None

  • Returns: None

  • Description: Unpauses all token transfers and minting functions, resuming normal contract operations.

Getter Functions

name()

  • Parameters: None

  • Returns:

    • string: The name of the token.

  • Description: Returns the name of the token as set during the contract initialization.

symbol()

  • Parameters: None

  • Returns:

    • string: The symbol of the token.

  • Description: Returns the symbol of the token as set during the contract initialization.

decimals()

  • Parameters: None

  • Returns:

    • uint8: The number of decimal places the token uses.

  • Description: Returns the number of decimal places used to get its user representation.

totalSupply()

  • Parameters: None

  • Returns:

    • uint256: The total supply of the token.

  • Description: Returns the total supply of the token.

balanceOf(address account)

  • Parameters:

    • account: The address of the token holder.

  • Returns:

    • uint256: The balance of the specified address.

  • Description: Returns the token balance of the specified address.

allowance(address owner, address spender)

  • Parameters:

    • owner: The address of the token owner.

    • spender: The address of the spender.

  • Returns:

    • uint256: The remaining number of tokens that the spender is allowed to spend on behalf of the owner.

  • Description: Returns the remaining number of tokens that the spender is allowed to spend on behalf of the owner.

paused()

  • Parameters: None

  • Returns:

    • bool: Whether the contract is paused.

  • Description: Returns whether the contract is in a paused state.

nonces(address owner)

  • Parameters:

    • owner: The address to check.

  • Returns:

    • uint256: The current nonce for the address.

  • Description: Returns the current nonce for an address, used for permit functions.

checkpoints(address account, uint32 pos)

  • Parameters:

    • account: The address to check.

    • pos: The position of the checkpoint.

  • Returns:

    • Checkpoint: The checkpoint data.

  • Description: Returns the checkpoint for an address at a specific position.

numCheckpoints(address account)

  • Parameters:

    • account: The address to check.

  • Returns:

    • uint32: The number of checkpoints for the address.

  • Description: Returns the number of checkpoints for an address.

getVotes(address account)

  • Parameters:

    • account: The address to check.

  • Returns:

    • uint256: The current voting power of the address.

  • Description: Returns the current voting power of an address.

getPastVotes(address account, uint256 blockNumber)

  • Parameters:

    • account: The address to check.

    • blockNumber: The block number to check.

  • Returns:

    • uint256: The voting power of the address at the specified block number.

  • Description: Returns the voting power of an address at a specific block.

getPastTotalSupply(uint256 blockNumber)

  • Parameters:

    • blockNumber: The block number to check.

  • Returns:

    • uint256: The total supply of tokens at the specified block number.

  • Description: Returns the total supply of tokens at a specific block.

delegates(address account)

  • Parameters:

    • account: The address to check.

  • Returns:

    • address: The delegatee of the address.

  • Description: Returns the delegatee of an address.

Events

Transfer

  • Parameters:

    • address indexed from: The address from which tokens are transferred.

    • address indexed to: The address to which tokens are transferred.

    • uint256 value: The number of tokens transferred.

  • Description: Emitted when tokens are transferred from one address to another, including zero value transfers.

Approval

  • Parameters:

    • address indexed owner: The address of the token owner.

    • address indexed spender: The address of the spender.

    • uint256 value: The new allowance granted by the owner.

  • Description: Emitted when the allowance of a spender for an owner is set by a call to approve. This event indicates the amount of tokens the spender is allowed to transfer from the owner’s account.