From 979b306dfb1e69e833a3c000d510fdda0ca6081b Mon Sep 17 00:00:00 2001 From: burns <103551202+burns2854@users.noreply.github.com> Date: Wed, 21 Feb 2024 14:13:26 -0800 Subject: [PATCH 1/3] Update veLaunchpad docs --- .../vote-escrow-launchpad/1_launchpad.md | 9 +- .../vote-escrow-launchpad/2_VotingEscrow.md | 6 +- .../3_RewardDistributor.md | 2 +- .../vote-escrow-launchpad/4_RewardFaucet.md | 2 +- .../5_Troubleshooting.md | 2 +- .../7_SmartWalletWhitelist.md | 2 +- .../vote-escrow-launchpad/8_Risks.md | 25 +++ .../vote-escrow-launchpad/9_FEIntegration | 142 ++++++++++++++++++ docs/tools/core/admin-ve8020.md | 5 +- 9 files changed, 183 insertions(+), 12 deletions(-) create mode 100644 docs/reference/vote-escrow-launchpad/8_Risks.md create mode 100644 docs/reference/vote-escrow-launchpad/9_FEIntegration diff --git a/docs/reference/vote-escrow-launchpad/1_launchpad.md b/docs/reference/vote-escrow-launchpad/1_launchpad.md index e85024a2..9a6b4dd6 100644 --- a/docs/reference/vote-escrow-launchpad/1_launchpad.md +++ b/docs/reference/vote-escrow-launchpad/1_launchpad.md @@ -5,8 +5,10 @@ order: 0 ## Launchpad System Details -The Launchpad system is a set of smart contracts used to lock BPT tokens (representing liquidity providers positions on Balancer) in a vote escrow system in order to gain voting power on a given project, and also being able to vote on rewards distribution to those who are locking their liquidity, incentivising governance and long term participation. -In addition to the BPT token lock, almost any token of any project can be used for locking. This way, users can independently create their own vote escrow systems, with their own reward tokens (incentives). +The Launchpad system is a set of smart contracts used to create veSystems. Each veSystem is used to lock BPT tokens (representing liquidity provider positions on Balancer) in a vote escrow system to gain voting power on a specific project and participate in reward distribution to those who lock their liquidity, incentivizing governance and long-term participation. +In addition to locking BPT tokens, almost any token from any project can be used for locking. Thus, users can independently create their own vote escrow systems with their own reward tokens (incentives). +Reward tokens (incentives) can be any tokens defined by the veSystem creator. +Additionally, veSystem participants may also receive BAL tokens as an extra reward if the locked token is part of the Balancer reward distribution system. Main parts of the system: Launchpad - a contract factory for creating new VotingEscrow and RewardsDistribution contracts. @@ -20,7 +22,7 @@ The Launchpad contract uses the minimal-proxy pattern for deploying new VotingEs ### Code -[Launchpad.vy](../contracts/Launchpad.vy) +[Launchpad.vy](https://github.com/protofire/ve8020-launchpad/blob/main/contracts/Launchpad.vy) ### Deploying new ve-system ```sh @@ -122,4 +124,3 @@ def deploy( return (newVotingEscrow, newRewardDistributor, newRewardFaucet) ``` - diff --git a/docs/reference/vote-escrow-launchpad/2_VotingEscrow.md b/docs/reference/vote-escrow-launchpad/2_VotingEscrow.md index ba932226..eaa74035 100644 --- a/docs/reference/vote-escrow-launchpad/2_VotingEscrow.md +++ b/docs/reference/vote-escrow-launchpad/2_VotingEscrow.md @@ -7,7 +7,7 @@ order: 1 The contract allows locking tokens for a selected period of time and receiving rewards from the RewardsDistribution contract in return. It utilizes the VotingEscrow contract from Curve as its implementation. ## Code -[VotingEscrow.vy](../contracts/VotingEscrow.vy) +[VotingEscrow.vy](https://github.com/protofire/ve8020-launchpad/blob/main/contracts/Launchpad.vy) ## MaxLock Time and Lock Durations @@ -17,7 +17,7 @@ When selecting `MAXTIME`, the VE-System creator should consider the planned rewa ### Interactions with other smart contracts (Smart-Wallets) -By default, the VotingEscrow contract restricts locking for other smart contracts. If you want to configure access for other smart contracts, you need to use the functionality of the third-party `SmartWalletWhitelist` smart contract. With `SmartWalletWhitelist`, you can grant access to all possible smart contracts or only a specific list. [Refer to the instructions](./misc_docs/SmartWalletWhitelist.md) for deploying and configuring access for smart contracts to VotingEscrow. +By default, the VotingEscrow contract restricts locking for other smart contracts. If you want to configure access for other smart contracts, you need to use the functionality of the third-party `SmartWalletWhitelist` smart contract. With `SmartWalletWhitelist`, you can grant access to all possible smart contracts or only a specific list. [Refer to the instructions](./SmartWalletWhitelist.md) for deploying and configuring access for smart contracts to VotingEscrow. ## View functions @@ -150,7 +150,7 @@ functions apply_transfer_ownership() external(); Applies ownership transfer -### [Adding smart wallet checker](./misc_docs/SmartWalletWhitelist.md) +### [Adding smart wallet checker](../7_SmartWalletWhitelist.md) ```sh function commit_smart_wallet_checker(address smartChecker) external; ``` diff --git a/docs/reference/vote-escrow-launchpad/3_RewardDistributor.md b/docs/reference/vote-escrow-launchpad/3_RewardDistributor.md index d4ba7b76..bcde5545 100644 --- a/docs/reference/vote-escrow-launchpad/3_RewardDistributor.md +++ b/docs/reference/vote-escrow-launchpad/3_RewardDistributor.md @@ -12,7 +12,7 @@ The RewardDistributor contract distributes rewards on a weekly basis, requiring ## Code -[RewardDistributor.sol](../contracts/RewardDistributor.sol) +[RewardDistributor.sol](https://github.com/protofire/ve8020-launchpad/blob/main/contracts/RewardDistributor.sol) ## View functions diff --git a/docs/reference/vote-escrow-launchpad/4_RewardFaucet.md b/docs/reference/vote-escrow-launchpad/4_RewardFaucet.md index e005f79c..baf1fb00 100644 --- a/docs/reference/vote-escrow-launchpad/4_RewardFaucet.md +++ b/docs/reference/vote-escrow-launchpad/4_RewardFaucet.md @@ -8,7 +8,7 @@ The contract allows for scheduling reward distributions at specific time interva ## Code -[RewardFaucet.sol](../contracts/RewardFaucet.sol) +[RewardFaucet.sol](https://github.com/protofire/ve8020-launchpad/blob/main/contracts/RewardFaucet.sol) ## View functions diff --git a/docs/reference/vote-escrow-launchpad/5_Troubleshooting.md b/docs/reference/vote-escrow-launchpad/5_Troubleshooting.md index 5d96cfa6..8e4de8ec 100644 --- a/docs/reference/vote-escrow-launchpad/5_Troubleshooting.md +++ b/docs/reference/vote-escrow-launchpad/5_Troubleshooting.md @@ -71,7 +71,7 @@ This error occurs when you want to start reward distribution for the current wee ### Launchpad Contract Verification -To verify Launchpad contract use [contract source code](../contracts/Launchpad.vy) and constructor arguments (ABI-encoded) which you will find after Launchpad deployment. +To verify Launchpad contract use [contract source code](https://github.com/protofire/ve8020-launchpad/blob/main/contracts/Launchpad.vy) and constructor arguments (ABI-encoded) which you will find after Launchpad deployment. If you missed (or have lost) constructor arguments, you can build it manually by inserting addresses of VotingEscrow and RewardDistributor implementations without '0x' into following string: ``` 0000000000000000000000000000000000000000000000000 diff --git a/docs/reference/vote-escrow-launchpad/7_SmartWalletWhitelist.md b/docs/reference/vote-escrow-launchpad/7_SmartWalletWhitelist.md index dd822218..d8927c61 100644 --- a/docs/reference/vote-escrow-launchpad/7_SmartWalletWhitelist.md +++ b/docs/reference/vote-escrow-launchpad/7_SmartWalletWhitelist.md @@ -11,7 +11,7 @@ To deploy `SmartWalletWhitelist`, execute the following command: npx hardhat run ./scripts/utils/deploySmartAllowList.ts --network networkName ``` -Don't forget to specify desired networkName (full list of network names can be found [hardhat.config.ts](../../hardhat.config.ts)) +Don't forget to specify desired networkName (full list of network names can be found [hardhat.config.ts](https://github.com/protofire/ve8020-launchpad/blob/main/hardhat.config.ts)) After deploying the `SmartWalletWhitelist` smart contract, you need to add its address to the VotingEscrow contract. To do this, in the VotingEscrow contract, sequentially call the functions: diff --git a/docs/reference/vote-escrow-launchpad/8_Risks.md b/docs/reference/vote-escrow-launchpad/8_Risks.md new file mode 100644 index 00000000..0d4fbf84 --- /dev/null +++ b/docs/reference/vote-escrow-launchpad/8_Risks.md @@ -0,0 +1,25 @@ +--- +title: "Risks" +order: 7 +--- + +# veLaunchpad Risks + +When deploying or using a vote escrow system through the Launchpad or via the contracts directly, there are several risks that both deployers (developers) and users (participants) should be aware of. This is autonomous software. See also [Balancer Protocol Risks](https://app.balancer.fi/#/risks). + +## Smart Contract Security +While smart contract factories may offer convenience in deploying new instances of vote escrow systems, they also introduce dependencies on the security and reliability of the factory contracts. If the factory contracts contain vulnerabilities or are compromised, it could affect all instances deployed through them. + +[The new contracts](https://github.com/protofire/ve8020-launchpad) are based on the [existing veBAL system](https://medium.com/balancer-protocol/vebal-is-live-aeda1ae13e20) / [VotingEscrow.vy](https://github.com/balancer/balancer-v2-monorepo/blob/master/pkg/liquidity-mining/contracts/VotingEscrow.vy) that Balancer has employed since March 2022 with the addition of factories and updates developed by [Protofire](https://protofire.io/) that include the ability to set early unlock permissions and penalties. Balancer has taken steps to mitigate these risks through reviews by Protofire and conducting an [audit with Certora that can be read here](). Teams can still fork the original VotingEscrow contracts if preferred and the additional features are not required. + +## Configuration Risks +Deployers need to configure the parameters of the vote escrow system according to the specific requirements and objectives of their DAO/project/protocol. This includes setting parameters such as lock-up periods, voting eligibility criteria, quorum thresholds, and voting power weights. Misconfigurations can lead to unintended consequences or vulnerabilities in the governance process. + +## Integration Risks +Deployers may need to integrate the deployed smart contracts with other components of their infrastructure, such as the front-end interface, wallet integrations, or external services. Integration errors or compatibility issues could disrupt the functioning of the vote escrow system and impact user experience. + +## Monitoring and Maintenance +Deployers are responsible for monitoring the performance and health of the deployed smart contracts over time. They should conduct regular audits, security assessments, and upgrades to address any vulnerabilities, bugs, or changes in the operating environment that may affect the integrity or functionality of the vote escrow system. + +## Reliability of Front-End +The front-end interface provided on this docs site may be subject to downtime, bugs, or security vulnerabilities. Deployers and owners should assess the reliability and security of the front-end and consider implementing backup interfaces or contingency plans such as interacting directly with the deployed contracts in case of disruptions. diff --git a/docs/reference/vote-escrow-launchpad/9_FEIntegration b/docs/reference/vote-escrow-launchpad/9_FEIntegration new file mode 100644 index 00000000..1262e9bc --- /dev/null +++ b/docs/reference/vote-escrow-launchpad/9_FEIntegration @@ -0,0 +1,142 @@ +--- +title: "Front End Integration" +order: 8 +--- + +## Frontend integration + +### System creation and management +1) Create system using Launchpad contract. +``` +function deploy( + address tokenBptAddr, + string memory name, + string memory symbol, + uint256 maxLockTime, + uint256 rewardDistributorStartTime +) +``` +**Parameters details and constraints:** +`tokenBptAddr` - token or liquidity-token provided by creator +`name` - any name provided by creator +`symbol` - any symbol provided by creator +`maxLockTime` - time in seconds. **Must be >= `604800` (7 days)** +`rewardDistributorStartTime` - unix timestamp. **Must be >= unix-timestamp of next Thursday 00:00** + +After calling the `deploy()` function, contracts VotingEscrow and RewardDistributor will be created for the caller (admin). The addresses of these contracts can be obtained from the `VESystemCreated(address bptToken, address votingEscrow, address rewardDistributor, address admin)` event of the deploy() function. + +2) After creation admin (creator) must add allowed token for the reward distribution. +To do that use following function of the RewardDistributor constract: +``` +function addAllowedRewardTokens(address[] calldata tokens); +``` + +3) To provide rewards into RewardDistributor constract any user can use one of the following functions: +``` +function depositToken(address token, uint256 amount); +function depositTokens(address[] calldata tokens, uint256[] calldata amounts); +``` +**Parameters details and constraints:** +`token` - token address, that already added to allowed list (see point 2), +`amount` - amount for token +Note: + - tokens can be added to the weekly distribution no earlier than `rewardDistributorStartTime`. + - Every Thursday at 00:00 a new week of reward distributions begins. + +4) The Subgraph can be used to track the history of rewards added each week. +``` +{ + weekRewards(where: {rewardDistributor: ""}) { + rewardDistributor + token + totalWeekAmount + weekStart + } +} +``` + +[Here](https://github.com/protofire/balancer_launchpad_subgraph/blob/main/docs/GraphQueries.md) you can find more subgraph examples that can useful for frontend integration + + + +### Users interaction + +#### VotingEscrow + +1) VotingEscrow metadata: +``` +function name() external view returns (string memory); +function symbol() external view returns (string memory); +function token() external view returns (address); +function decimals() external view returns (uint256); +``` +Returns: +- name of the VotingEscrow contract, +- symbol of the VotingEscrow contract, +- address of the token that can be locked, +- decimals of the token that can be locked, + +2) [Create new lock](./2_VotingEscrow.md/#create_lock) +Creates new lock for a user. + +3) [Increase lock amount](./2_VotingEscrow.md/#increase_amount) +Increases lock amount to increase (voting) power of lock. + +4) [Increase unlock time](./2_VotingEscrow.md/#increase_unlock_time) +Increases lock unlock time to increase (voting) power of lock. + +5) To get information when the user's lock amount and lock deadline: +``` +function locked(address account) external view returns (uint256 amount, uint256 deadline); +``` +Returns: +- `amount` of locked tokens; +- `unix-times` of the lock end. + +5) [Withdraw tokens when lock is finished](./2_VotingEscrow.md/#withdraw) +Withdraws tokens to user. + +6) Each VotingEscrow contract has lock-MaxTime value defined in seconds. To check lock-maxtime: +``` +function MAXTIME() external view returns (uint256); +``` +Returns Maxtime value in seconds for current VotingEscrow contract. + + + + +#### RewardDistributor +1) [Add allowed token for the distribution](./3_RewardDistributor.md/#addallowedrewardtokens) + +2) Get list of allowed tokens for a distribution: +``` +function getAllowedRewardTokens() external view returns (address[] memory) +``` +Returns allowed for reward distribution tokens list. + + +3) [Deposit tokens for the week distribution](./3_RewardDistributor.md/#deposittoken) + +4) Use LensReward contracts to check user's pending rewards: +``` +struct ClaimableRewards { + address token; + uint256 claimableAmount; +} + +LensReward.getUserClaimableRewardsAll( + address rewardDistributor, + address user, + address[] calldata allowedRewardTokenList +) external view returns (ClaimableRewards[] memory) +``` +Parameters: +`rewardDistributor` - The address of the RewardDistributor contract +`user` - The user's address to check pending rewards on +`allowedRewardTokenList` - The array of available reward tokens to check rewards + +Returns an array with objects with ClaimableRewards data. + +5) Rewards claiming +[Claim one token](./3_RewardDistributor.md/#claimtoken) +[Claim multiple tokens](./3_RewardDistributor.md/#claimtokens) \ No newline at end of file diff --git a/docs/tools/core/admin-ve8020.md b/docs/tools/core/admin-ve8020.md index 2ffc50ce..5a1767e8 100644 --- a/docs/tools/core/admin-ve8020.md +++ b/docs/tools/core/admin-ve8020.md @@ -13,4 +13,7 @@ To create a Vote Escrow system, you will need a Balancer Pool Token (BPT) that i Use this Admin panel with the admin wallet to create your VE system. For direct access to contracts, see [this guide](/reference/vote-escrow-launchpad/1_launchpad). ### Step 3 - Add Your Own Reward Program -Use the "Rewards Distribution" tab to set Reward Token and permisssions. For more detailed information see [Reward Distributor Guide](/reference/vote-escrow-launchpad/3_RewardDistributor) and the [Reward Faucet Guide](/reference/vote-escrow-launchpad/4_RewardFaucet) \ No newline at end of file +Use the "Rewards Distribution" tab to set Reward Token and permisssions. For more detailed information see [Reward Distributor Guide](/reference/vote-escrow-launchpad/3_RewardDistributor) and the [Reward Faucet Guide](/reference/vote-escrow-launchpad/4_RewardFaucet) + +#### Risks +Before using this tool, review [Specific Risks](/reference/vote-escrow-launchpad/8_risks) and [Balancer Terms of Use](https://app.balancer.fi/#/terms-of-use) \ No newline at end of file From f4b4f4d07272089b8949b3ca84cf6d120f6ea039 Mon Sep 17 00:00:00 2001 From: burns <103551202+burns2854@users.noreply.github.com> Date: Wed, 21 Feb 2024 14:15:35 -0800 Subject: [PATCH 2/3] Update 8_Risks.md --- docs/reference/vote-escrow-launchpad/8_Risks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/vote-escrow-launchpad/8_Risks.md b/docs/reference/vote-escrow-launchpad/8_Risks.md index 0d4fbf84..1cad5067 100644 --- a/docs/reference/vote-escrow-launchpad/8_Risks.md +++ b/docs/reference/vote-escrow-launchpad/8_Risks.md @@ -10,7 +10,7 @@ When deploying or using a vote escrow system through the Launchpad or via the co ## Smart Contract Security While smart contract factories may offer convenience in deploying new instances of vote escrow systems, they also introduce dependencies on the security and reliability of the factory contracts. If the factory contracts contain vulnerabilities or are compromised, it could affect all instances deployed through them. -[The new contracts](https://github.com/protofire/ve8020-launchpad) are based on the [existing veBAL system](https://medium.com/balancer-protocol/vebal-is-live-aeda1ae13e20) / [VotingEscrow.vy](https://github.com/balancer/balancer-v2-monorepo/blob/master/pkg/liquidity-mining/contracts/VotingEscrow.vy) that Balancer has employed since March 2022 with the addition of factories and updates developed by [Protofire](https://protofire.io/) that include the ability to set early unlock permissions and penalties. Balancer has taken steps to mitigate these risks through reviews by Protofire and conducting an [audit with Certora that can be read here](). Teams can still fork the original VotingEscrow contracts if preferred and the additional features are not required. +[The new contracts](https://github.com/protofire/ve8020-launchpad) are based on the [existing veBAL system](https://medium.com/balancer-protocol/vebal-is-live-aeda1ae13e20) / [VotingEscrow.vy](https://github.com/balancer/balancer-v2-monorepo/blob/master/pkg/liquidity-mining/contracts/VotingEscrow.vy) that Balancer has employed since March 2022 with the addition of factories and updates developed by [Protofire](https://protofire.io/) that include the ability to set early unlock permissions and penalties. Balancer has taken steps to mitigate these risks through reviews by Protofire and conducting an [audit with Certora that can be read here](https://github.com/protofire/ve8020-launchpad/tree/main). Teams can still fork the original VotingEscrow contracts if preferred and the additional features are not required. ## Configuration Risks Deployers need to configure the parameters of the vote escrow system according to the specific requirements and objectives of their DAO/project/protocol. This includes setting parameters such as lock-up periods, voting eligibility criteria, quorum thresholds, and voting power weights. Misconfigurations can lead to unintended consequences or vulnerabilities in the governance process. From b505075eaaa28e874f1da42243c4f797f4b6cf6e Mon Sep 17 00:00:00 2001 From: burns <103551202+burns2854@users.noreply.github.com> Date: Tue, 12 Mar 2024 17:35:04 -0600 Subject: [PATCH 3/3] Recovered --- docs/reference/vote-escrow-launchpad/1_launchpad.md | 4 ++++ docs/tools/core/admin-ve8020.md | 4 +++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/reference/vote-escrow-launchpad/1_launchpad.md b/docs/reference/vote-escrow-launchpad/1_launchpad.md index 9a6b4dd6..ad6c613c 100644 --- a/docs/reference/vote-escrow-launchpad/1_launchpad.md +++ b/docs/reference/vote-escrow-launchpad/1_launchpad.md @@ -5,6 +5,10 @@ order: 0 ## Launchpad System Details +The Launchpad system is a set of smart contracts used to create veSystems. Each veSystem is used to lock BPT tokens (representing liquidity provider positions on Balancer) in a vote escrow system to gain voting power on a specific project and participate in reward distribution to those who lock their liquidity, incentivizing governance and long-term participation. +In addition to locking BPT tokens, almost any token from any project can be used for locking. Thus, users can independently create their own vote escrow systems with their own reward tokens (incentives). +Reward tokens (incentives) can be any tokens defined by the veSystem creator. +Additionally, veSystem participants may also receive BAL tokens as an extra reward if the locked token is part of the Balancer reward distribution system. The Launchpad system is a set of smart contracts used to create veSystems. Each veSystem is used to lock BPT tokens (representing liquidity provider positions on Balancer) in a vote escrow system to gain voting power on a specific project and participate in reward distribution to those who lock their liquidity, incentivizing governance and long-term participation. In addition to locking BPT tokens, almost any token from any project can be used for locking. Thus, users can independently create their own vote escrow systems with their own reward tokens (incentives). Reward tokens (incentives) can be any tokens defined by the veSystem creator. diff --git a/docs/tools/core/admin-ve8020.md b/docs/tools/core/admin-ve8020.md index 5a1767e8..2b0d774e 100644 --- a/docs/tools/core/admin-ve8020.md +++ b/docs/tools/core/admin-ve8020.md @@ -16,4 +16,6 @@ Use this Admin panel with the admin wallet to create your VE system. For direct Use the "Rewards Distribution" tab to set Reward Token and permisssions. For more detailed information see [Reward Distributor Guide](/reference/vote-escrow-launchpad/3_RewardDistributor) and the [Reward Faucet Guide](/reference/vote-escrow-launchpad/4_RewardFaucet) #### Risks -Before using this tool, review [Specific Risks](/reference/vote-escrow-launchpad/8_risks) and [Balancer Terms of Use](https://app.balancer.fi/#/terms-of-use) \ No newline at end of file +Before using this tool, review [Specific Risks](/reference/vote-escrow-launchpad/8_risks) and [Balancer Terms of Use](https://app.balancer.fi/#/terms-of-use) + +Source code can be found at [Protofire's Github Repo](https://github.com/protofire/ve8020-launchpad/tree/main). This code has been audited by Certora - [read the report here](https://www.certora.com/reports/protofire). \ No newline at end of file