This package contains the Solidity implementation of Mangrove as well as deployment scripts and example Solidity offer logics.

Documentation

If you are looking for the Mangrove developer documentation, the site to go to is docs.mangrove.exchange.

Installation

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.

Foundry and its use in this package

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);

Tests

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.

Deploying on Mangrove

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.

Generating Mangrove address files

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 to addresses/deployed.backup/<network>-latest.json
• You should set WRITE_DEPLOY=true when running scripts that you want to broadcast.
  • When WRITE_DEPLOY=true, the contract set is also written to addresses/deployed/<network>.json.

(Note that for mumbai, network=maticmum)

Foundry keywords for rpc and verification

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)

Chain-dependent broadcast with private keys in .env

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 of vm.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”)

Generate documentation

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.

Configuration

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 .