TypeScript icon, indicating that this package has built-in type declarations

    0.4.2 • Public • Published

    Build Status Coverage Status

    Gnosis Protocol - Smart Contracts

    The Gnosis Protocol Exchange is a fully decentralized trading protocol which facilitates ring trades via discrete auction between several ERC20 token pairs.

    It uses a batch auction for arbitrage-free exchanges while maximizing trader surplus to facilitate the development of a fairer Web3 ecosystem for everyone.


    Checkout the Smart Contract Documentation.

    Audit report

    The audit report can be found here.

    CLI Examples

    Checkout wiki

    Deployment Process

    For the deployment of the contracts into an official network, follow this steps:

    1. Make sure that all depended contracts and libraries - e.g. BytesLib - has been deployed to the intended network and that their network information is available in the npm modules

    2. Run the following commands

    yarn install                        # This installs all dependencies 
    npx truffle build                   # This builds the contracts 
    npx truffle migrate --network $NETWORKNAME --reset
    yarn run networks-extract           # extracts deployed addresses to networks.json 

    If you are building for a local development network, ganache has to be running locally. For this you can e.g. in a separate shell run

    yarn run ganache # start a development network (blocking) 

    If you want to deploy the contracts with an already existing fee token (tokenId 0), you can set the env variable

    export FEE_TOKEN_ADDRESS=...

    before running the migration script.

    1. Verify the contracts for some cool Etherscan.io goodies (see below for more help)
    npx truffle run verify BatchExchange --network $NETWORKNAME
    1. List some default tokens on the StableX exchange
    npx truffle exec scripts/add_token_list.js --network $NETWORKNAME

    Verifying Contracts

    In order to verify a contract on Etherscan.io, you need to first create an account and an API key

    1. Navigate to https://etherscan.io/myapikey
    2. Login or create an account
    3. Generate a new API key
    4. Add export MY_ETHERSCAN_API_KEY="..." to your ~/.zshrc, ~/.bash_profile, or similar

    Note, if you have a specific contract address in mind (i.e. one which is not specified in networks.json) it may be referred to by address as

    npx truffle run verify $CONTRACT_NAME@$CONTRACT_ADDRESS --network $NETWORKNAME

    Retrieving previous deployments

    In order to use the previously deployed contracts, which are documented in the network.json file, the following steps are necessary:

    1. Build the contracts:
    npx truffle compile
    1. Inject address from network.json into the builds:
    yarn run networks-inject

    Deploying a simple market maker scenario to Rinkeby:

    The following script deploys a simple market maker order and a necessary owl order, to enable trading:

    # Get token ID of DAI 
    npx truffle exec scripts/invokeViewFunction.js 'tokenAddressToIdMap' '0x5592EC0cfb4dbc12D3aB100b257153436a1f0FEa' --network rinkeby
    # Export the resulting token ID 
    export TOKEN_ID_DAI=[Result from last call]
    # Get token ID of TrueUSD 
    npx truffle exec scripts/invokeViewFunction.js 'tokenAddressToIdMap' '0x0000000000085d4780B73119b644AE5ecd22b376' --network rinkeby
    # Export the resulting token ID 
    export TOKEN_ID_TUSD=[Result from last call]
    # Make sure that the users have deposited sufficient funds into the exchange 
    # Please be aware that the specified amounts are multiples of 10**18 
    npx truffle exec scripts/deposit.js --accountId=0 --tokenId=0 --amount=30 --network rinkeby&& \
    npx truffle exec scripts/deposit.js --accountId=0 --tokenId=$TOKEN_ID_TUSD --amount=100 --network rinkeby
    # Place  market-maker order in current auction 
    # This simulates a strategy expected from market makers: trading stable coins against each other 
    # with a spread of 0.02 percent 
    npx truffle exec scripts/place_order.js --accountId=0 --buyToken=$TOKEN_ID_DAI --sellToken=$TOKEN_ID_TUSD --minBuy=1000 --maxSell=998 --validFor=20 --network rinkeby
    # Place owl token order for the fee mechanism 
    npx truffle exec scripts/place_order.js --accountId=0 --buyToken=$TOKEN_ID_DAI --sellToken=0 --minBuy=1000 --maxSell=1000 --validFor=20 --network rinkeby

    Then, the market order can be place, after switching to another account. Usually, this is expected to happen via the UI. If it will be done via the console, following commands can be used:

    # Deposit funds into exchange: 
    npx truffle exec scripts/deposit.js --accountId=0 --tokenId=$TOKEN_ID_DAI --amount=100 --network rinkeby
    # Place market order with 1/2 limit-price 
    npx truffle exec scripts/place_order.js --accountId=1 --buyToken=$TOKEN_ID_TUSD --sellToken=$TOKEN_ID_DAI --minBuy=500 --maxSell=1000 --validFor=5 --network rinkeby

    Now, the market can be inspected by:

    # view the market status: 
    npx truffle exec scripts/get_auction_elements.js --network rinkeby

    And the output should look like this:

    { user: '0x740a98f8f4fae0986fb3264fe4aacf94ac1ee96f',
        sellTokenBalance: 100000000000000000000,
        buyToken: 7,
        sellToken: 3,
        validFrom: 5247563,
        validUntil: 5247583,
        priceNumerator: 1e+21,
        priceDenominator: 998000000000000000000,
        remainingAmount: 998000000000000000000 },
      { user: '0x740a98f8f4fae0986fb3264fe4aacf94ac1ee96f',
        sellTokenBalance: 30000000000000000000,
        buyToken: 7,
        sellToken: 0,
        validFrom: 5247563,
        validUntil: 5247583,
        priceNumerator: 1e+21,
        priceDenominator: 1e+21,
        remainingAmount: 1e+21 },
      { user: 'account',
        sellTokenBalance: 100000000000000000000,
        buyToken: 3,
        sellToken: 7,
        validFrom: 5247750,
        validUntil: 5247755,
        priceNumerator: 500000000000000000000,
        priceDenominator: 1e+21,
        remainingAmount: 1e+21 } ]

    Building on top of BatchExchange

    The integration of the Gnosis Protocol contracts into your own truffle project are demonstrated here: https://github.com/gnosis/dex-contracts-integration-example. This repository contains a minimal truffle project allowing to build on top of contracts. Please consult its readme for further information.


    The continuous integration is running several linters which must pass in order to make a contribution to this repo. For your convenience there is a pre-commit hook file contained in the project's root directory. You can make your life easier by executing the following command after cloning this project (it will ensure your changes pass linting before allowing commits).

    cp pre-commit .git/hooks/
    chmod +x .git/hooks/pre-commit

    For any other questions, comments or concerns please feel free to contact any of the project admins:


    npm i @fleupold/dex-contracts

    DownloadsWeekly Downloads






    Unpacked Size

    20.7 MB

    Total Files


    Last publish


    • fleupold