Testing a maker contract
Work in progress
This page is currently being updated - thank you for your understanding.
After following the tutorial Post a Smart Offer or some of the guides in this section, you have created a maker contract and are ready to test it. Mangrove offers a helper contract, MangroveTest, that helps setup everything needed for writing a test using the Mangrove core protocol.
We are going to use Foundry as the test runner - and we are going to use some of the features that Foundry provides for testing. Please refer to Set Up Your Local Environment for instructions on how to get and setup Foundry. For this guide, we assume basic knowledge of writing and running tests with Foundry - as can be gained by reading the relevant sections on Foundry -> Tests in the Foundry book.
For this example, we are going to write a simple test for the Amplifier contract that we implemented in the advanced part of Creating a Direct contract.
Creating the test file
When creating the test file, remember to use the naming convention <name>.t.sol, this way Foundry knows what files are tests.
Imports
The first thing to do is to import the relevant contracts. As mentioned, we are going to use the helper contract provided by the Mangrove test library, MangroveTest. This allows us to avoid having to fork an existing chain with Mangrove deployed. We may simply deploy a Mangrove protocol for this specific purpose before running our tests.
The Mangrove test library provides other helpers. We import Polygon - a helper to fork the polygon chain. We do this because we want to use the real addresses for WETH, USDC and DAI. (This is not strictly necessary - we could just create some test tokens and use those instead.)
We also import the Amplifier contract - the contract that we wish to test. The last thing we import is MgvStructs, which contain struct definitions for the offer views, which we shall need in the test.
The console import is not strictly needed - however, it can be very useful, if we want to log something to the console while we are developing the test. Let us import it for now.
Amplifier.t.sol - Imports
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.10;
import {StratTest} from "@mgv-strats/test/lib/StratTest.sol";
import "@mgv/test/lib/forks/Polygon.sol";
import "@mgv-strats/src/toy_strategies/offer_maker/Amplifier.sol";
import {Local} from "@mgv/src/core/MgvLib.sol";
import {MgvReader} from "@mgv/src/periphery/MgvReader.sol";
import {console} from "@mgv/forge-std/console.sol";Test Contract and Setup
We call the test contract AmplifierTest and let it inherit from MangroveTest to be able to use all helper functions. We override the basic setUp() function provided by MangroveTest to setup the actors we shall need in the test. We need 3 tokens, the fork the test should run on, a taker address and the Amplifier contract.
For this test, we are going to use the test contract as the offer maker. Consequentially, it should be able to receive funds (from the taker), so we make sure to define the receive() function.
We do the following in setUp() - refer to the full implementation below:
use the pinned fork of Polygon provided the Mangrove test library
get three tokens from the fork
setup the two relevant markets - DAI/WETH and USDC/WETH (using a helper from
MangroveTest)create an address for the taker, and provide it with native tokens, as well as DAI and USDC for taking the offer(s)
as the taker, we also need to approve Mangrove for taking the funds
In the implementation, we use standard cheatcodes, startPrank(<address>), stopPrank(<address> provided by Foundry for setting up the test (see Foundry -> Cheatcodes).
We also use a helper function $() provided by the Mangrove testing library offering a shorthand for writing address() and casting the contract to its address.
Amplifier.t.sol - Contract and Setup
contract AmplifierTest is StratTest {
IERC20 weth;
IERC20 dai;
IERC20 usdc;
PolygonFork fork;
address payable taker;
Amplifier strat;
OLKey olKeyWethDai;
uint constant GASREQ = 200_000;
receive() external payable virtual {}
function setUp() public override {
// use the pinned Polygon fork
fork = new PinnedPolygonFork(39880000); // use polygon fork to use dai, usdc and weth addresses
fork.setUp();
// use convenience helpers to setup Mangrove
mgv = setupMangrove();
reader = new MgvReader($(mgv));
// setup tokens, markets and approve them
dai = IERC20(fork.get("DAI.e"));
weth = IERC20(fork.get("WETH.e"));
usdc = IERC20(fork.get("USDC.e"));
olKeyWethDai = OLKey($(weth), $(dai), options.defaultTickSpacing);
olKey = OLKey($(usdc), $(weth), options.defaultTickSpacing);
lo = olKey.flipped();
setupMarket(olKeyWethDai);
setupMarket(olKey);
// setup separate taker and give some native token (for gas) + USDC and DAI
taker = freshAddress("taker");
deal(taker, 10_000_000);
deal($(usdc), taker, cash(usdc, 10_000));
deal($(dai), taker, cash(dai, 10_000));
// approve DAI and USDC on Mangrove for taker
vm.startPrank(taker);
dai.approve($(mgv), type(uint).max);
usdc.approve($(mgv), type(uint).max);
vm.stopPrank();
}Testing a Successful Fill
With setUp done, let us write the first test.
We start by testing that we can take the offer fully without any rejections, and that after trade execution both offers are retracted (recall that was how we decided to implement Amplifier). Let us call the test test_success_fill - in line with the naming guidelines of the Foundry test framework.
Breaking the problem down, for this test, we need to
deploy
Amplifieron our local fork,take one of the offers, and verify our conditions
We implement these two steps as separate functions (we need to deploy the contract for other tests, also).
Amplifier.t.sol - Testing a successful fill
function test_success_fill() public {
deployStrat();
execTraderStratWithFillSuccess();
}Now, of course, we need to implement deployStrat() and execTraderStratWithFillSuccess().
Deploying Amplifier on the fork
Amplifier on the forkDeploying a contract on the fork is just calling its constructor of the contract. We give the address of the testing contract($(this)) as the administrator of the Amplifier contract to be able to use that directly as the maker.
After deployment, we use the activate() helper provided by MangroveOffer, which helps setup the correct token approvals for Mangrove for our maker contract.
Before calling activate() we also take the opportunity to demonstrate the related helper, checkList(), which checks whether necessary approvals have been setup, and, if not, reverts (recall that expectRevert(<message>) is a Foundry cheatcode).
Amplifier.t.sol - Deploying on a fork
function deployStrat() public {
strat = new Amplifier({
mgv: IMangrove($(mgv)),
base: weth,
stable1: usdc,
stable2: dai,
tickSpacing1: olKey.tickSpacing,
tickSpacing2: olKeyWethDai.tickSpacing,
admin: $(this) // for ease, set this contract (will be Test runner) as admin for the strat
});
// NOTE:
// For this test, we're locking base, ie WETH, in the vault of the contract
// - so Amplifier is not really used for amplified liquidity, in this example.
// However, to employ actual amplified liquidity it is simply a matter of
// setting up a more refined router.
// check that we actually need to activate for the two 'wants' tokens
IERC20[] memory tokens = new IERC20[](3);
tokens[0] = dai;
tokens[1] = usdc;
tokens[2] = weth;
vm.expectRevert("mgvOffer/LogicMustApproveMangrove");
strat.checkList(tokens);
// and now activate them
strat.activate(tokens);
}With this, we have a function that can deploy a new Amplifier contract on our local chain. Let us turn to writing the actual test.
Breaking down the test-specification further
Let us unfold the specification for the test itself.
For this first test, we want to
post and fund a pair of offers using
Amplifier.newAmplifiedOffers(...),snipe one of the offers, and,
verify these properties
both maker and taker received tokens as expected
after trade execution both offers are retracted
Let us continue our divide-and-conquer strategy and write helper methods for the two first steps, before writing the body of the test. (As we shall see, we can reuse these helper methods, later.)
Post and Fund Offers
Posting offers with Amplifier is simply a call to newAmplifiedOffers, sending along funds for the provision. (And we make a note to ensure in the test body that the testing contract has the funds for the provision.)
Amplifier.t.sol - Post and fund offers
function postAndFundOffers(uint makerGivesAmount, uint makerWantsAmountDAI, uint makerWantsAmountUSDC, uint gasreq)
public
returns (uint offerId1, uint offerId2)
{
(offerId1, offerId2) = strat.newAmplifiedOffers{value: 2 ether}({
gives: makerGivesAmount, // WETH
wants1: makerWantsAmountUSDC, // USDC
wants2: makerWantsAmountDAI, // DAI
gasreq: gasreq
});
}Taking a Single Offer
Mangrove provides snipe exactly for taking a specific offer.
We make sure to impersonate the taker that we setup an address for above. (Recall that Foundry provides vm.prank() for this exact purpose.)
Amplifier.t.sol - Take a single offer
function takeOffer(uint makerWantsAmount, IERC20 makerWantsToken, uint offerId)
public
returns (uint takerGot, uint takerGave, uint bounty)
{
OLKey memory _olKey = OLKey($(weth), $(makerWantsToken), olKey.tickSpacing);
Tick tick = mgv.offers(_olKey, offerId).tick();
// try to take one of the offers (using the separate taker account)
vm.prank(taker);
(takerGot, takerGave, bounty,) =
mgv.marketOrderByTick({olKey: _olKey, maxTick: tick, fillVolume: makerWantsAmount, fillWants: false});
}And Finally, The Test
With these helper methods, the test body amounts to the following steps:
Post and fund offers with
postAndFundOffers().Snipe one offer with
takeOffer().Assert and verify the properties we listed above.
Amplifier.t.sol - Putting it all together
function execTraderStratWithFillSuccess() public {
uint makerGivesAmount = 0.15 ether;
uint makerWantsAmountDAI = cash(dai, 300);
uint makerWantsAmountUSDC = cash(usdc, 300);
weth.approve($(strat.router()), type(uint).max);
deal($(weth), $(this), cash(weth, 10));
(uint offerId1, uint offerId2) =
postAndFundOffers(makerGivesAmount, makerWantsAmountDAI, makerWantsAmountUSDC, GASREQ);
(uint takerGot, uint takerGave,) = takeOffer(makerWantsAmountDAI, dai, offerId1);
// assert that
assertEq(takerGot, reader.minusFee(olKeyWethDai.flipped(), makerGivesAmount), "taker got wrong amount");
assertTrue((makerWantsAmountDAI - takerGave) * 100000 / makerWantsAmountDAI < 10, "taker gave wrong amount");
// assert that neither offer posted by Amplifier are live (= have been retracted)
Offer offer_on_dai = mgv.offers(olKeyWethDai, offerId1);
Offer offer_on_usdc = mgv.offers(olKey, offerId2);
assertTrue(!offer_on_dai.isLive(), "weth->dai offer should have been retracted");
assertTrue(!offer_on_usdc.isLive(), "weth->usdc offer should have been retracted");
}In verifying, we use a few helper functions provided by MangroveTest
cash(token, amount)- that helps us ensure that we use the correct decimals for a specific token,minusFee(address_outbound, address_inbound, price)- that calculates the fee for a given market and price,
and a few view functions provided by Mangrove, offers() and isLive() (see Views on Offers).
Running Tests with Foundry
In Foundry tests are run with the Forge tool, typically invoking something like forge test. Please refer to the Foundry Book -> Tests for updated documentation.
Adding More Tests - Testing Partial Fills
With our helper functions for posting and sniping offers, we we can easily add more tests. For instance, testing that an offer was correctly handled for a partial fill looks like this:
Amplifier.t.sol - Testing partial fill
function test_success_partialFill() public {
deployStrat();
execTraderStratWithPartialFillSuccess();
}See entire file on GitHubAmplifier.t.sol - Helper function
function execTraderStratWithPartialFillSuccess() public {
uint makerGivesAmount = 0.15 ether;
uint makerWantsAmountDAI = cash(dai, 300);
uint makerWantsAmountUSDC = cash(usdc, 300);
weth.approve($(strat.router()), type(uint).max);
deal($(weth), $(this), cash(weth, 5));
// post offers with Amplifier liquidity
(uint offerId1, uint offerId2) =
postAndFundOffers(makerGivesAmount, makerWantsAmountDAI, makerWantsAmountUSDC, GASREQ);
//only take half of the offer
(uint takerGot, uint takerGave,) = takeOffer(makerWantsAmountDAI / 2, dai, offerId1);
// assert that
uint offerGaveMinusFee = reader.minusFee(olKeyWethDai.flipped(), makerGivesAmount / 2);
assertTrue(((takerGot - offerGaveMinusFee) * 10_000) / (makerGivesAmount / 2) < 10, "taker got wrong amount");
assertEq(takerGave, makerWantsAmountDAI / 2, "taker gave wrong amount");
// assert that neither offer posted by Amplifier are live (= have been retracted)
Offer offer_on_dai = mgv.offers(olKeyWethDai, offerId1);
Offer offer_on_usdc = mgv.offers(lo, offerId2);
assertTrue(offer_on_dai.isLive(), "weth->dai offer should not have been retracted");
assertTrue(offer_on_usdc.isLive(), "weth->usdc offer should not have been retracted");
}A full test file for for the Amplifier contract can be found here.
When you have sufficiently tested your maker contract, you may want to deploy your contract to a real chain.rovedao/mangrove-strats/blob/a265abeb96a053e386d346c7c9e431878382749c/test/toy_strategies/Amplifier.t.sol#L72-L76
https://github.com/mangrovedao/mangrove-strats/blob/a265abeb96a053e386d346c7c9e431878382749c/test/toy_strategies/Amplifier.t.sol#L143-L169A full test file for for the Amplifier contract can be found here.
When you have sufficiently tested your %%maker contract|maker-contract%%, you may want to deploy your contract to a real chain.
Last updated