This package contains the Solidity implementation of Mangrove as well as deployment scripts and example Solidity offer logics.
If you are looking for the Mangrove developer documentation, the site to go to is docs.mangrove.exchange.
Just forge install mangrovedao/mangrove-core
.
mangrove-core/=lib/mangrove-core/src/
(because forge's remapping generation heuristic sees the preprocessing/lib/
directory and decides to remap to the parent dir). Instead, you will get:
mgv_src/=lib/mangrove-core/src/
mgv_lib/=lib/mangrove-core/lib/
mgv_test/=lib/mangrove-core/test/
mgv_script/=lib/mangrove-core/script/
First, clone the repo and install the prerequisites for the monorepo described in the root README.md.
Next, run the following commands:
$ yarn install # Sets up Mangrove monorepo and install dependencies
$ yarn build # Compiles Mangrove and offer logics
After the initial installation, it is sufficient to run yarn build
after updating the clone - this will also run yarn install
.
This package relies heavily on the Foundry development framework for Ethereum. It includes an EVM interpreter with special hooks for
- interpreting
console.log
-type statements - displaying Solidity stack traces on reverts.
For example, you can use console.log
in contracts for debugging; those logs survive transaction revert. More in Foundry's. Example:
string memory s = "Hello";
uint n = 31;
console.log("Message %s number %d",s,d);
To run all tests in the package, just run yarn test
.
This package contains a comprehensive test suite for Mangrove, implemented in Solidity using foundry.
The tests are located in ./test.
Refer to the documentation of foundry for details on how tests are structured and options for running it.
Mangrove uses forge script
forge script <scriptName>
executes an arbitrary smart contract function locally. Then, any CALLs executed therein and preceded by the cheatcode vm.broadcast()
can be broadcast to a remote node by reading a forge-generated run-*.json
field.
The log of transactions generated by forge script
gets written to broadcast/<scriptName>/<chainId>/run-latest.json
. It is an array of low-level transactions info with some additions like newly created contract names.
Mangrove needs to:
- Name its contract (multiple instances of the same contract may be deployed)
- Ignore script names (different scripts are used for different networks)
- Have all its deployed contracts in one place
To do the above, Mangrove adds a layer to forge script
deployment.
- Deployment scripts should inherit the
Deployer
contract. - You should call
outputDeployment()
at the end of your scripts.- When
outputDeployment()
gets called, a file with all known deployed contracts are written toaddresses/deployed.backup/<network>-latest.json
- When
- You should set
WRITE_DEPLOY=true
when running scripts that you want to broadcast.- When
WRITE_DEPLOY=true
, the contract set is also written toaddresses/deployed/<network>.json
.
- When
(Note that for mumbai, network=maticmum
)
We use foundry's [rpc_endpoints]
and [etherscan]
config sections. If the same key exists in both, you can drop the --etherscan-api-key
from the commandline arguments. For instance if mumbai
is defined in both sections, you can say forge script --fork-url mumbai ... --verify
and any deployed contracts will get verified through etherscan using the mumbai
API key of the [etherscan]
section.
(Note: in this context, etherscan can mean "polygonscan" or any block explorer)
The vm.broadcast()
cheatcode implicitly selects a sender for the broadcast transactions: either the default sender, or the address associated to the --private-key
given in the CLI, or to --mnemonic
information, etc.
It is tiring to always add --private-key 0x..
to scripts, especially since the key may be different for each network. The Deployer
contract has a broadcast()
function that reads the <NAME>_PRIVATE_KEY
var off the environment, where NAME
is the name of the chain you're talking to.
- You should have vars such as
MUMBAI_PRIVATE_KEY
,POLYGON_PRIVATE_KEY
in your.env
file. You can use .env.example as a template. - You should use
broadcast()
instead ofvm.broadcast()
in scripts. The deployer contract will look for the correct private key, and fallback to the CLI-provided key if none was found.
(Note that for Mumbai, name=”mumbai”
)
The Mangrove Solidity files contain documentation that can be extracted to a nicely formatted and navigable HTML file by running yarn doc
which will generate a doc/MgvDoc.html
.
This package uses hierarchical configurations via node-config. The main configuration is in ./config/default.js and the other .js files in the same directory specify environment/stage specific overrides. Please refer to the documentation for node-config for details on how the configuration hierarchy is resolved.
It is possible to override parts of the configuration with environment variables. This is controlled by ./config/custom-environment-variables.json. The structure of this file mirrors the configuration structure but with names of environment variables in the places where these can override a part of the configuration.
For more information, please refer to the node-config's documentation of this feature: https://github.com/lorenwest/node-config/wiki/Environment-Variables#custom-environment-variables .