Skip to content
Quantstamp network audit node software, documentation and node operator instructions
Branch: develop
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Version incremented. Version update documented Jun 18, 2019
bin QSP-1205 Remove aws creds from bundle script (#524) Jun 27, 2019
deployment/local QSP-1149 Licenses MIT (#453) May 13, 2019
doc QSP-1235 Update chmod for default.json (#528) Jul 9, 2019
plugins/analyzers QSP-1149 Licenses MIT (#453) May 13, 2019
resources Retiring heartbeat config parameter - no longer needed at this point (#… Jun 7, 2019
src/qsp_protocol_node Check for price floor added. Some tests added Jun 18, 2019
tests Test fixed Jun 18, 2019
.coveragerc Switched to run tests inside container Jun 22, 2018
.dockerignore QSP-1149 Licenses MIT (#453) May 13, 2019
.editorconfig Editorconfig missing value (#141) Aug 16, 2018
.gitignore Qsp 968 audit node restructure (#333) Feb 11, 2019
.travis.yml QSP-1220 install python deps to read version from node config (#521) Jun 25, 2019 Version incremented. Version update documented Jun 18, 2019
Dockerfile QSP-1234 Reduce docker image size (#526) Jul 8, 2019
LICENSE QSP-1149 Licenses MIT (#453) May 13, 2019
Makefile Removing unnecessary mkdir in qsp-protocol-node (#510) Jun 14, 2019 Removing inexistent file reference in (#496) Jun 7, 2019
buildspec.yml QSP-1149 Licenses MIT (#453) May 13, 2019
requirements.txt Qsp 1202 update requirements (#507) Jun 11, 2019


Build Status Coverage Status

Implements the QSP audit node in the Quantstamp network. This guide presents steps on how to perform common development tasks. For Node operators, please refer to the document "How to become a node operator" instead.


  1. Install Docker:

  2. On Linux-based Systems: Make sure your user is a part of the docker group:

    sudo usermod -a -G docker <username>
  3. Ensure node's account has enough funds. At all times, the node must have enough ether to pay for its associated gas fees (e.g., when bidding, submiting a report, etc.). When running the node against testnet (default), one should mint ether.

    Go to a Ropsten faucet and transfer testing ether to the node's target account (default is 0x60463b7ee0c3d33def3a05313597b1300f6de62b).

  4. Replace the contents of default keystore json file in resources/keystore directory with a valid keystore file.

  5. Configure Ethereum node's authentication token. To use Infura as a provider (default), sign up on, create a new project, and then check the associated endpoint, e.g., The last part of the URL (abcdefg) is the authentication token. Set the environment variable QSP_ETH_AUTH_TOKEN to the token:

    export QSP_ETH_AUTH_TOKEN=abcdefg

    To use a different provider, modify eth_node/args/endpoint_uri in config.yaml accordingly.

Running the node

make run

This runs the node against testnet. It relies on default values for QSP_ETH_AUTH_TOKEN and QSP_ETH_PASSPHRASE, two mandatory environment variables used by the node. Specifically:

  • QSP_ETH_AUTH_TOKEN: Ethereum node's authentication token (e.g., one obtained for Infura, a proxy node, etc).

  • QSP_ETH_PASSPHRASE: passphrase of the target Ethereum account. The password must NOT contain quotes (double or single). The safest approach to verify whether your password matches what you have set is to check the value of QSP_ETH_PASSPHRASE in a terminal:


    If the output matches your original password, the latter is correctly set. Otherwise, launching the audit node will fail.

Additionally, the node relies on the configuration settings given in a yaml file (default is resources/config.yaml).

Using custom accounts

To run the node with an account different from the one given as default, create a new account (e.g., using MyEtherWallet).

Record the passphrase and the new Ethereum account address, storing the keystore file in an accessible location. Change the keystore location in the yaml configuration file.

Running tests

make test

Run node's standalone report encoder

  1. To encode an existing json report to a compressed hexstring, create a new container and mount the json report
docker run -v <file-to-mount>:<mount-location> -it <qsp-protocol-node-image> ./bin/codec -e <mount-location>
  1. To decode a compressed hexstring, do (for example)
make interactive
/app # ./bin/codec -d 2003b7f55bc69671c5f4fb295fd5acf1375eb7f1363093176f4bec190c39f95c235b0c00190d001905001d0300190700191a0019150010120018120014
2019-01-30 15:57.56 Decoding report 0
{'audit_state': 4,
 'contract_hash': 'B7F55BC69671C5F4FB295FD5ACF1375EB7F1363093176F4BEC190C39F95C235B',
 'status': 'success',
 'version': '2.0.1',
 'vulnerabilities': [('unprotected_ether_withdrawal', 25, 25),
                     ('call_to_external_contract', 25, 25),
                     ('reentrancy', 29, 29),
                     ('transaction_order_dependency', 25, 25),
                     ('exception_state', 25, 25),
                     ('reentrancy_true_positive', 25, 25),
                     ('missing_input_validation_true_positive', 16, 16),
                     ('missing_input_validation', 24, 24),
                     ('missing_input_validation', 20, 20)]}

Note that there is no 0x prefixing the hexstring.

Run node locally and in an isolated environment

For certain use cases, it is important to run the node in such a way that it doesn't affect any other nodes. Currently, the steps are as follows:

  1. In the audit contract repository, follow the steps to deploy the smart contracts to a separate stage (e.g., "betanet-test-123").

  2. In resources/config.yaml, replace the contract addresses to point to the new stage, e.g., replace:{major-version}-abi.json with{major-version}-abi.json. Do it for all the contract URIs.

  3. Run the node.

Run node locally to produce a report for a given contract

This allows one to produce a non-compressed audit report for a given solidity file.

  1. Copy the solidity file into the project directory (this ensures it will be included in the produced docker image).
  2. Run make interactive.
  3. Within the docker shell, run ./create_report path/to/file.sol

Optional features

The node allows full report uploading to a remote site (e.g., S3), as well as log streaming (e.g., CloudWatch). Currently, this is restricted to AWS services. The configuration steps are as follows:

  1. Set up AWS credentials. If you don't have permissions to create credentials, contact the #dev-protocol Slack channel.

  2. Follow the steps How to configure AWS CLI
    On Mac: double-check that python is in your $PATH and its directory does not start with ~. If it does, replace it with your /Users/<username> (or make won't find aws).

  3. Create an s3 bucket in your AWS account

  4. Specify AWS credentials as environment variables, namely AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Make sure that the AWS role has correct permissions to access the bucket.

  5. Update the following parameters under upload_provider in config.yaml:

    1. bucket_name
    2. contract_bucket_name
  6. Additionally, one can also stream logs to CloudWatch. Once AWS credentials are in place, simply enable logging/streaming in resources/config.yaml, changing the following default parameters (if desired):

    1. log_group
    2. log_stream


  • If you want to build locally just run make build. For instructions on how to contribute to the node's repository, please check the directions in


This section includes situations that a command previously failed and we came up with ways to mitigate it. The following troubleshooting statements are in the form below:

While doing command, on environment, we encountered this message, then did these steps.

(OPTIONAL) Visualize logs :

You can use ELK stack to visualize logs or aggregate results for troubleshooting.

  1. Make sure docker daemon is running
  2. Run make elk
  3. Access kibana dashboard from a browser on port 5601
  4. Create a new index pattern under management matching logstash*. (this can take a couple of minutes while logstash comes online).
  5. For timestamp select @timestamp.
  6. Now visit discover tab to see the logs.

To learn more about ELK please visit

You can’t perform that action at this time.