Have ideas to improve npm?Join in the discussion! »


2.0.0 • Public • Published

CI Coverage Status Discord npm version

This repo contains all contracts and tests relevant to the core mStable protocol. mStable is a protocol built to make stablecoins easy, robust and profitable.

mStable Assets (mAssets) are tokens that allow minting and redemption for underlying Basket Assets (bAssets) of the same peg (i.e. USD, BTC, Gold). The InvariantValidator applies both min and max weights to these bAssets, and enforces penalties and bonuses when minting with these assets to provide low slippage swaps. This Invariant applies progressive penalties and bonuses on either end of the weight scale - having the result of having a large area of low slippage. bAssets are integrated with lending protocols (initially Aave, Compound) to generate interest which is accrued in mAsset terms. mAssets can be deposited to earn native interest through their respective Savings Contract, just like you would with a savings account. bAssets within an mAsset can also be swapped with low slippage (provided they remain within their validator limits), with a swapFee credited additionally to Savers.

Core mAsset contracts utilise OpenZeppelin's InitializableAdminUpgradeabilityProxy to facilitate future upgrades, fixes or feature additions. The upgrades are proposed by the mStable Governors (with current governor address stored in the Nexus - the system kernel) and executed via the DelayedProxyAdmin. Both changes to the governor, and contract upgrades have a one week delay built in to execution. This allows mStable users a one week opt out window if they do not agree with the given change.

mStable rewards those who contribute to its utility and growth - for more information see MTA.

🏠 https://mstable.org
📀 https://app.mstable.org
📄 https://docs.mstable.org

Bug bounty

Found a bug? Claim a reward from our open Bug Bounty by reporting it to mStable (following the responsible disclosure policy)


  • master contains complete, tested and audited contract code, generally on mainnet
  • beta is for the pre-release code, generally on ropsten


We publish the contract artifacts to an npm package called @mstable/protocol. You can browse them via unpkg.com.

Dev notes


Installing dependencies

$ yarn


Tests are written with Hardhat, Ethers, Waffle & Typescript, using Typechain to generate typings for all contracts. Tests are executed using hardhat in hardhats evm.

$ yarn test


mStable-contracts test suite is built to support execution on a mainnet fork of ganache. This allows tests to be ran using all mainnet dependencies (bAssets, lending protocols). To do this, certain mainnet accounts need to be unlocked to allows tx to be sent from that origin.

NB: The following commands assume you have a full Ethereum node running and exposed on local port 1234

$ ganache-cli -f http://localhost:1234 -p 7545 -l 100000000 --allowUnlimitedContractSize --unlock "0x6cC5F688a315f3dC28A7781717a9A798a59fDA7b" --unlock "0x3f5CE5FBFe3E9af3971dD833D26bA9b5C936f0bE" --unlock "0x3dfd23a6c5e8bbcfc9581d2e864a68feb6a076d3"
$ yarn compile
$ truffle test ./test/xxx.spec.tx --network fork


Key folders:

  • /contracts/z_mocks: All mocks used throughout the test suite
  • /security: Scripts used to run static analysis tools like Slither and Securify
  • /test: Unit tests in folders corresponding to contracts/xx
  • /test-utils: Core util files used throughout the test framework
    • /machines: Mock contract machines for creating configurable instances of the contracts
  • /types: TS Types used throughout the suite
    • /generated: Output from Typechain; strongly-typed, Ethers-flavoured contract interfaces


Solidity-coverage is used to run coverage analysis on test suite.

This produces reports that are visible in the /coverage folder, and navigatable/uploadable. Ultimately they are used as a reference that there is some sort of adequate cover, although they will not be a source of truth for a robust test framework. Reports publically available on coveralls.

NB: solidity-coverage runs with solc optimizer=false (see discussion)


Codebase rules are enforced through a passing CI (visible in .circleci/config.yml). These rules are:

  • Linting of both the contracts (through Solium) and TS files (ESLint)
  • Passing test suite
  • Maintaining high unit testing coverage

Code formatting

  • Solidity imports deconstructed as import { xxx } from "../xxx.sol"
  • Solidity commented as per NatSpec format
  • Internal function ordering from high > low order




npm i @mstable/protocol

DownloadsWeekly Downloads






Unpacked Size

4.1 MB

Total Files


Last publish


  • avatar
  • avatar
  • avatar