Skip to content

Commit d0a7eed

Browse files
GundamDweebralph-pichler
GundamDweeb
authored and
ralph-pichler
committed
Upload Contracts
0 parents  commit d0a7eed

33 files changed

+7292
-0
lines changed

‎.env.example‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Deployer EOA private key (insecure)
2+
DEPLOYER_PRIVATE_KEY_LOCAL=
3+
DEPLOYER_PRIVATE_KEY_RINKEBY=
4+
DEPLOYER_PRIVATE_KEY_GOERLI=
5+
DEPLOYER_PRIVATE_KEY_MAINNET=
6+
7+
# Infura key (rinkeby + mainnet)
8+
INFURA_API_KEY=
9+
10+
# BZZ bonding curve set up variables
11+
BZZ_DEPLOYED_MAINNET=
12+
ROUTER_ADDRESS_GOERLI=
13+
DAI_ADDRESS_MAINNET=0x6b175474e89094c44da98b954eedeac495271d0f
14+
OWNER_ADDRESS=
15+
16+
# Deployment settings
17+
# Main 12000000 | Local 10000000 | Rinkeby 10000000 | Goerli 8000000
18+
GAS_LIMIT=100000
19+
# Mainnet will be over riden.
20+
GAS_PRICE=2500000000
21+
22+
# TESTING SET UP
23+
# Mock DAI (for testing) set up
24+
COLLATERAL_TOKEN_NAME=
25+
COLLATERAL_TOKEN_SYMBOL=
26+
COLLATERAL_TOKEN_DECIMAL=18
27+
28+
# BZZ token set up variables
29+
TOKEN_NAME=
30+
TOKEN_SYMBOL=
31+
# BZZ token has 16 decimals. DO NOT CHANGE THIS! This will break the bonding curve
32+
TOKEN_DECIMAL=16
33+
# BZZ needs this limit for the curve. DO NOT CHANGE THIS! This will break the bonding curve
34+
TOKEN_CAP=1250000000000000000000000
35+
36+
# Testing address (NB: GETS THE BZZ ON TESTNET DEPLOYMENT)
37+
ADDRESS_OF_TESTER=
38+

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
node_modules/
2+
.env
3+
.DS_Store
4+
.outputParameter

‎README.md‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
<div align="center">
2+
<img src="./docs/Swarm_Logo_Small.png">
3+
<h1>BZZ Smart Contract Ecosystem</h1>
4+
</div>
5+
6+
---
7+
8+
# Index
9+
10+
#### [Repository Set Up](#repository-set-up)
11+
12+
#### [Testing and Coverage](#testing-and-coverage)
13+
14+
#### [Deployment](#deployment)
15+
16+
- [Testnet Deployment](#testnet-deployment)
17+
- [Mainnet Deployment](#mainnet-deployment)
18+
19+
#### [System Design](#system-design)
20+
21+
### Additional documentation
22+
23+
#### [~ `README`](./README.md)
24+
#### [> Audit Report and Info](./audit/Audit_report_and_info.md)
25+
##### [> Final audit report](./Buzzar_final_audit_report.pdf)
26+
#### [> Admin Permissions and Risks](./docs/admin_permissions_and_risks.md)
27+
#### [> Token Contract](./docs/token_contract.md)
28+
#### [> Curve Contract](./docs/curve_contract.md)
29+
#### [> ETH Broker Contract](./docs/eth_broker_contract.md)
30+
31+
---
32+
33+
# Repository Set Up
34+
35+
To get the blockchain folder into a working state, you will need to install the required packages. To do so, in a terminal open in this directory, run the following:
36+
37+
```
38+
yarn
39+
```
40+
41+
This will install all the needed packages. This may take some time. If your build fails, please check your `node` version, for this repository it is recommended to use `10.21.0`.
42+
43+
Once all the required packages have been installed, build the smart contracts by running:
44+
45+
```
46+
yarn build
47+
```
48+
49+
This will compile the Solidity contracts using the correct version of Solidity.
50+
51+
# Testing and Coverage
52+
53+
To run the tests you will need to run a local instance of the blockchain using Ganache. While Ganache has a GUI, we recommend using the CLI tool instead. In a new terminal in this directory run the following to start a local CLI instance:
54+
55+
```
56+
yarn start
57+
```
58+
59+
Please ensure that you do not have the GUI running as they use the same ports.
60+
61+
Once the Ganache instance is up and running you can run the following command to run the tests:
62+
63+
```
64+
yarn test
65+
```
66+
67+
To run the coverage for the repository, you will need to end your Ganache CLI instance, as the coverage tool runs it's own instance. Once your instance has been safely exited, run the following for the coverage:
68+
69+
```
70+
yarn cover
71+
```
72+
73+
This will take a while to run. Please also note that `Curve.sol` does not have 100% branch coverage directly. The branch coverage is ensured through the `CurveTest.sol` where the curves internal functions are exposed for the final branch coverage. As such the `CurveTest.sol` does not have 100% coverage, but has 100% branch coverage.
74+
75+
# Deployment
76+
77+
The bonding curve has a deployment script for the following networks:
78+
79+
```
80+
local (1337) (Ganache)
81+
Rinkeby (4)
82+
Main (1)
83+
```
84+
85+
Before you are able to deploy to any of these networks, you will need to create an `.env` file in this directory. After you have created your `.env` file, you will need to copy the contents of the `.env.example` file:
86+
87+
```
88+
# Deployer EOA private key (insecure)
89+
DEPLOYER_PRIVATE_KEY_LOCAL=
90+
DEPLOYER_PRIVATE_KEY_RINKEBY=
91+
DEPLOYER_PRIVATE_KEY_MAINNET=
92+
93+
# Infura key (rinkeby + mainnet)
94+
INFURA_API_KEY=
95+
96+
# BZZ bonding curve set up variables
97+
BZZ_DEPLOYED_MAINNET=
98+
DAI_ADDRESS_MAINNET=0x6b175474e89094c44da98b954eedeac495271d0f
99+
OWNER_ADDRESS=
100+
101+
# TESTING SET UP
102+
# Mock DAI (for testing) set up
103+
COLLATERAL_TOKEN_NAME=
104+
COLLATERAL_TOKEN_SYMBOL=
105+
COLLATERAL_TOKEN_DECIMAL=18
106+
107+
# BZZ token set up variables
108+
TOKEN_NAME=
109+
TOKEN_SYMBOL=
110+
# BZZ token has 16 decimals. DO NOT CHANGE THIS! This will break the bonding curve
111+
TOKEN_DECIMAL=16
112+
# BZZ needs this limit for the curve. DO NOT CHANGE THIS! This will break the bonding curve
113+
TOKEN_CAP=1250000000000000000000000
114+
115+
# Testing address
116+
ADDRESS_OF_TESTER=
117+
```
118+
119+
The `.env` file is separated into logical sections to make deployment easier. The first section contains the private keys for deployment on the various networks. Please ensure that the private key that is being used has ETH on the respective network. It is recommended to have at least 0.5 ETH for deployment, more if you intend to deploy multiple times for testing.
120+
121+
**NOTE: Do not change the decimal or token cap of the BZZ token.** These variables are required as is in order for the bonding curve math to work. Changing these variables may result in unexpected behaviors.
122+
123+
The deployment script itself has been split into deployment for testing and deployment for Mainnet. This has been done to reduce friction for testing. Below both deployment scripts shall be explained and walked through.
124+
125+
## Testnet Deployment
126+
127+
The testing portion of the deployment script will run when deploying to local or Rinkeby.
128+
129+
The test deployment script will deploy the BZZ token, Bonding curve as well as a Mock DAI. The script will also mint the test user address some Mock DAI. This speeds up the testing process.
130+
131+
Please ensure that you have filled in all the following values from the `.env.example` before attempting to run the script:
132+
133+
```
134+
# Deployer EOA private key (insecure)
135+
DEPLOYER_PRIVATE_KEY_LOCAL=
136+
DEPLOYER_PRIVATE_KEY_RINKEBY=
137+
138+
# Infura key (rinkeby + mainnet)
139+
INFURA_API_KEY=
140+
141+
# TESTING SET UP
142+
# Mock DAI (for testing) set up
143+
COLLATERAL_TOKEN_NAME=
144+
COLLATERAL_TOKEN_SYMBOL=
145+
COLLATERAL_TOKEN_DECIMAL=18
146+
147+
# BZZ token set up variables
148+
TOKEN_NAME=
149+
TOKEN_SYMBOL=
150+
# BZZ token has 16 decimals. DO NOT CHANGE THIS! This will break the bonding curve
151+
TOKEN_DECIMAL=16
152+
# BZZ needs this limit for the curve. DO NOT CHANGE THIS! This will break the bonding curve
153+
TOKEN_CAP=1250000000000000000000000
154+
155+
# Testing address
156+
ADDRESS_OF_TESTER=
157+
```
158+
159+
Please note that private keys need to start with `0x` and will fail if they have not been prefixed.
160+
161+
When deploying locally please ensure your Ganache CLI is running.
162+
To deploy locally run the following:
163+
164+
```
165+
yarn deploy:local
166+
```
167+
168+
When deploying to Rinkeby please ensure that the private key being used has Rinkeby ETH. [You can get Rinkeby ETH from the facet.](https://faucet.rinkeby.io/) To deploy on Rinkeby run the following:
169+
170+
```
171+
yarn deploy:rinkeby
172+
```
173+
174+
## Mainnet Deployment
175+
176+
The mainnet deployment script will **only deploy the bonding curve**. You will need to enter the address of the deployed BZZ token into the `.env`. Please note that deploying the curve will not initialise it, this will need to be done manually either through [Remix](http://remix.ethereum.org/) or [Etherscan](https://etherscan.io/).
177+
178+
Before running the deployment script, please ensure the following fields have been filled out in the `.env`:
179+
180+
```
181+
# Deployer EOA private key (insecure)
182+
DEPLOYER_PRIVATE_KEY_MAINNET=
183+
184+
# Infura key (rinkeby + mainnet)
185+
INFURA_API_KEY=
186+
187+
# BZZ bonding curve set up variables
188+
BZZ_DEPLOYED_MAINNET=
189+
DAI_ADDRESS_MAINNET=0x6b175474e89094c44da98b954eedeac495271d0f
190+
OWNER_ADDRESS=
191+
```
192+
193+
Ensure the provided private key has sufficient ETH (at least 0.5) before attempting to run the script, and that the address of the deployer is not the same as the address of the owner. The address of DAI on the mainnet has been entered for convenience, but please double check this address before deploying. The address of the owner should preferably be that of a multisig wallet.
194+
195+
Once all the values have been filled in the `.env`, run the following to deploy to mainnet:
196+
197+
```
198+
yarn deploy:mainnet
199+
```
200+
201+
Once deployment is complete you will have the address of the deployed bonding curve. To initialise the curve please follow the below steps (they will also be printed in the terminal during deployment):
202+
203+
1. Add the BZZ Curve as a minter on the BZZ token
204+
2. Pre-minted at least the minimum number of tokens on the BZZ token (62500000 1e16)
205+
3. Ensure the calling address has sufficient collateral to initialise (call `requiredCollateral` on the BZZ curve to get the required collateral amount)
206+
4. Approve the BZZ curve address as a spender of the required collateral amount
207+
5. Call the init function
208+
209+
After these steps have been completed the bonding curve will be operational and able to mint and burn tokens in exchange for DAI. Without following these steps the bonding curve will not function.
210+
211+
# System Design
212+
213+
This smart contract ecosystem has been designed to reduce the security risk and interdependency of the contracts. As such, the BZZ token is separate from the BZZ bonding curve. This allows the curve to be shut down independently from the token should the need arise. The BZZ ETH broker is separate from the BZZ curve and interacts like a normal user with the curve.
214+
215+
<div align="center">
216+
<img src="./docs/Swarm-design.png">
217+
</div>
218+
219+
Should the curve need to be shut down, it will remove itself as minter on the BZZ token. This will leave the BZZ token without a minter, thus capping the supply at the time of shut down at the current supply.
220+
221+
The BZZ broker will check the liveness status of the curve, and will disable minting and burning accordingly.
222+
223+
For more information on each of these contracts please see the specific documentation:
224+
225+
#### [> Token Contract](./docs/token_contract.md)
226+
#### [> Curve Contract](./docs/curve_contract.md)
227+
#### [> ETH Broker Contract](./docs/eth_broker_contract.md)
228+
229+
To understand the risks associated with these elevated permissions see:
230+
231+
#### [> Admin Permissions and Risks](./docs/admin_permissions_and_risks.md)
232+
233+
For the audit, see:
234+
235+
#### [> Audit Report and Info](./audit/Audit_report_and_info.md)
236+
237+
Or jump directly to the final audit report:
238+
239+
#### [> Final audit report](./Buzzar_final_audit_report.pdf)
240+
241+
---

‎audit/Audit_report_and_info.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<div align="center">
2+
<img src="../docs/Swarm_Logo_Small.png">
3+
<h1>BZZ Smart Contract Ecosystem</h1>
4+
<h3>Audit Information</h3>
5+
</div>
6+
7+
---
8+
9+
# Index
10+
11+
#### [Audit Information](#audit-information)
12+
13+
### Additional documentation
14+
15+
#### [< `README`](../README.md)
16+
#### [~ Audit Report and Info](./Audit_report_and_info.md)
17+
#### [> Admin Permissions and Risks](../docs/admin_permissions_and_risks.md)
18+
#### [> Token Contract](../docs/token_contract.md)
19+
#### [> Curve Contract](../docs/curve_contract.md)
20+
#### [> ETH Broker Contract](../docs/eth_broker_contract.md)
21+
22+
23+
# Audit Information
24+
25+
An audit was performed on this repository by [QuantStamp](https://quantstamp.com/).
26+
27+
To read the first (draft) audit, please click below:
28+
29+
#### [> First Audit Report](./Swarm_first_audit_report_draft.pdf)
30+
31+
To see the status of each of the audit issues, please see:
32+
33+
#### [> Audit Findings & Responses](./audit_findings_and_responses.md)
34+
35+
To see the final audit report after the above fixes and acknowledges, check the final audit:
36+
37+
#### [> Final Audit Report](./Buzzar_final_audit_report.pdf)
38+
39+
40+

‎audit/Buzzar_final_audit_report.pdf‎

366 KB
Binary file not shown.

‎audit/Swarm_first_audit_report_draft.pdf‎

363 KB
Binary file not shown.

‎audit/audit_findings_and_responses.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
<div align="center">
2+
<img src="../docs/Swarm_Logo_Small.png">
3+
<h1>BZZ Smart Contract Ecosystem</h1>
4+
<h3>Audit Findings & Responses</h3>
5+
</div>
6+
7+
---
8+
9+
# Audit Findings & Responses
10+
11+
Issue | Status | Project Notes
12+
|:----|:------:|:-------------|
13+
| QSP-1 | Resolved | Additional checks were added to `Eth_broker.sol` to ensure no blank addresses (`0x0`) can be entered.
14+
| QSP-2 | Resolved | Flattered file contained artifacts of older versions of the `Eth_portal.sol` and `Curve.sol` contracts. Files have been removed. `Eth_broker.sol` and `Curve.sol` have reentrancy guards.
15+
| QSP-3 | Acknowledged | `increaseAllowance` and `decreaseAllowance` are available on the `Token.sol` contract. App developers have been informed to use increase and decrease over approve.
16+
| QSP-4 | Acknowledged | Should Ether be forcibly sent to the contract a user on mint or burn may receive more Ether than expected. This does not affect any logic nor UX negatively.
17+
| QSP-5 | Resolved | Checks have been added. See QSP-2.
18+
| QSP-6 | Resolved | Updated visibility of `Curve.sol` `public` functions to `external`.
19+
| QSP-7 | Resolved | Additional `require`'s added for `approve` and `mintTo` calls. `require` not added to Uniswap calls as they handle failure through `revert`.
20+
| QSP-8 | Resolved | Variables mentioned are actually intended on being `constant`. Declaration has been updated to `constant`. `openMarketSupply` has been renamed to make it more clear as `_MARKET_OPENING_SUPPLY`.
21+
| QSP-9 | Resolved | Additional documentation was added to clear up the understanding of the `_helper` function in the `Curve.sol`.
22+
| QSP-10 | Resolved | Changes `Eth_broker.sol` `redeem` function to use `dai_.balanceOf(address(this))` instead of `_minDaiSellValue`.
23+
| QSP-11 | Resolved | Variables where artifacts of outdated math implementation. They have been removed.
24+
| QSP-12 | Resolved | See QSP-2.
25+
| QSP-13 | Resolved | See QSP-2. Additional unused return value of `_mint` in `Curve.sol` has also been removed and tests updated.
26+
| Code Documentation | Resolved | Mentioned documentation has been updated to reflect code functionally.
27+
| Adherence to Best Practices | Resolved | Common functionality in `Curve` `mint` and `mintTo` moved to an internal function `_commonMint`. Same thing for `Eth_broker` `mint` and `mintTo`. Variable naming between the `Curve` and `Broker` have been updated to be more consistent.
28+
29+
### Commit Hash
30+
31+
Phase (Delivery Date, YYYY-MM-DD) | Commit Hash
32+
|:--------------------|:-----------|
33+
| Initial Audit (2021-02-10) | 9a9a0ae71f1294faa76c12642809159361820ea3 |
34+
| Final Audit (2021-02-24) | dc28d883e496759eb2115e05a705fd714ae8473b
35+
36+
### Status Reference
37+
38+
| Status | Definition |
39+
|:-------|:-----------|
40+
| Unresolved | Acknowledged the existence of the risk, and decided to accept it without engaging in special efforts to control it. |
41+
| Acknowledged | The issue remains in the code but is a result of an intentional business or design decision. As such, it is supposed to be addressed outside the programmatic means, such as: 1) comments, documentation, README, FAQ; 2) business processes; 3) analyses showing that the issue shall have no negative consequences in practice (e.g., gas analysis, deployment settings). |
42+
| Resolved | Adjusted program implementation, requirements or constraints to eliminate the risk. |
43+
| Mitigated | Implemented actions to minimize the impact or likelihood of the risk. |
44+

0 commit comments

Comments
 (0)