augur-lite v1.0.1

Welcome to AugurLite! AugurLite is a decentralized prediction market protocol, built on Ethereum. The protocol is a fork of Augur v1, whose code is available here. AugurLite shares much of the same functionality as Augur but is designed to be more modular—supporting multiple denomination tokens and oracle systems.

Introduction

AugurLite is a protocol for creating and resolving prediction market contracts on Ethereum. Each prediction market is a smart contract with a chosen denomination token, such as Dai. Denomination tokens can be escrowed in a market in exchange for a set of outcome tokens, each of which is an ERC-20 token. The outcome tokens can be traded or exchanged on platforms like Veil, and ultimately redeemed for a portion of the escrowed denomination tokens once the chosen oracle resolves the market.

Overview

To explain AugurLite concepts, we will discuss each smart contract that makes up the protocol. Here is the breakdown.

AugurLite Go to code

This is the protocol's master contract. It is responsible for logging protocol-wide events, controlling transfers of denomination tokens, and creating the genesis universe using the UniverseFactory. This contract is a fork of Augur's main contract.

Universe Go to code

Conceptually, a universe is a container for markets that use the same denomination token. Each universe is created by the AugurLite contract. New markets (scalar, yesno, categorical) are created by calling this contract that in turn uses MarketFactory contracts. The Universe contract stores the denomination token that is used for all markets created in the universe. Unlike Augur's equivalent, this contract doesn't have any concept of forking, fee windows, reporting fees, open interest, or REP, because AugurLite does not come with an oracle out-of-the-box.

Market Go to code

A market is effectively a question about the future. Examples might be "Will Kamala Harris win the 2020 Democratic presidential nomination?" or "What will be the price of Bitcoin (BTC) in USD at 5pm PDT on Friday, May 17, 2019?" Markets come in three types: yes/no, categorical, and scalar.

AugurLite markets have an oracle field which specifies which Ethereum address can resolve the market, meaning specify how much each outcome is actually worth on expiration. All markets in Augur by default use the Augur oracle for resolution, and therefore users are required to deposit ETH and REP when creating a market. AugurLite is oracle-agnostic, so markets could be resolved by referencing the result of an Augur market or some other piece of Ethereum state. Therefore, users do not have to pay additional ETH, REP, or any other currency when creating markets.

This contract shares many of the same fields as Augur's Market contract. It's worth noting that the initial reporter and reporting participants concepts have been removed because they relate to the Augur oracle, which is irrelevant here. Markets are resolved by calling one resolve method. There is no finalization process as there is on Augur.

Upon market creation, a market creator mailbox is created through the MailboxFactory, and share tokens are created through the ShareTokenFactory. We'll talk more about those in their own sections below. Markets also have a market creator fee that is charged when shares are redeemed.

ShareToken Go to code

These are mintable, burnable ERC-20 tokens that represent outcomes in markets. They are created by ShareTokenFactory. A share token should be valued between 0 and 1 of the relevant denomination token. For instance, if you own a "YES" share token in a market denominated in Dai about an event that ends up happening, that share token will be worth 1 DAI upon resolution. Similarly, the "NO" share token in that market will be worth 0 DAI. There is an equivalent ShareToken contract in Augur.

CompleteSets Go to code

A complete set is a basket of all share tokens in a market. For instance, 1 complete set in a yes/no market would be 1 "YES" share token and 1 "NO" share token. Complete sets have the property of always being worth denomination token, because regardless of the outcome of the market, the sum of the values of the share tokens will be 1. This contract lets uesrs buy and sell complete sets in a given market. A user can buy a complete set by escrowing 1 denomination token in the market in exchange for 1 complete set. And a user can sell a complete set by exchanging the set for 1 denomination token (minus the market creator fee) that had been escrowed in the market. There is an equivalent CompleteSets contract in Augur.

ClaimTradingProceeds Go to code

This contract lets users exchange their share tokens for denomination tokens once a market resolves. It is equivalent to the ClaimTradingProceeds contract in Augur.

You will notice that all other trading-related contracts from Augur do not exist in AugurLite. That is because AugurLite defers trading to other off-chain exchange protocols (like 0x or Hydro) and encourages users to trade through off-chain relayers (like Veil, BlitzPredict, or Flux) for better performance.

Mailbox Go to code

This contract is deployed per market and is owned by the market creator. It collects the market creator fees, and it's ownership can be transferred. There is an equivalent Mailbox contract in Augur.

Factory Contracts Go to code

AugurLite uses the UniverseFactory contract to create universes, including the genesis universe. Universe contracts uses MarketFactory to create new markets. Upon deployment, market contracts use MailboxFactory to create mailboxes for the market creators and ShareTokenFactory to create outcome tokens (i.e. share tokens).

Comparison

Here is a table that highlights the main differences between Augur and AugurLite.

If you're looking for a more in-depth list of changes, please review the CHANGELOG file.

Current addresses of relevant contracts

Installation

You need system-wide installations of Python 3.7.3, Node.js 10.12, and Solidity 0.4.26. On MacOS, you also need to use venv for package management.

Setting up a specific solc version could get tricky. We recommend using Homebrew, and following this guide to help install the latest 0.4.xx version of Solidity.

To setup venv:

python3 -m venv venv # Creates venv directory to install Python packages
source venv/bin/activate # Activates the virtual environment

You can switch away from your environment with:

deactivate

Once your Python setup is complete, install JS dependencies with yarn:

yarn add npx
yarn

Deployment

To deploy the contracts, you need to create an .env in the base directory. The specification for the .env file will depend on which Ethereum network you are deploying to. Review the NetworkConfiguration file to see all options. Or copy one of the examples below for common networks.

Sample .env file for Kovan:

KOVAN_ETHEREUM_HTTP=https://eth-kovan.alchemyapi.io/jsonrpc/<INSERT API KEY>
KOVAN_PRIVATE_KEY=<INSERT PRIVATE KEY OF ADDRESS DEPLOYING CONTRACTS>

Sample .env file for Mainnet:

MAINNET_ETHEREUM_HTTP=https://eth-mainnet.alchemyapi.io/jsonrpc/<INSERT API KEY>
MAINNET_PRIVATE_KEY=<INSERT PRIVATE KEY OF ADDRESS DEPLOYING CONTRACTS>

Now you should be able to compile contracts, build contract interfaces, and deploy contracts.

yarn run build              # Compiles contracts and builds contract interfaces
yarn run deploy:kovan       # Deploys contracts to Kovan
yarn run deploy:mainnet     # Deploys contracts to Mainnet

You can see a full list of helper functions to run with yarn in package.json.

Solidity contract deployment is handled by ContractDeployer.ts and the wrapper programs located in source/deployment. This deployment framework allows for incremental deploys of contracts to a given controller (specified via a configuration option). This allows us to deploy new contracts without touching the controller, effectively upgrading the deployed system in-place.

Main Code

• source/libraries/ContractCompiler.ts - All logic for compiling contracts, generating ABI
• source/libraries/ContractDeployer.ts - All logic for uploading, initializing, and whitelisting contracts, generating addresses and block number outputs.

Configuration

• source/libraries/CompilerConfiguration.ts
• source/libraries/DeployerConfiguration.ts
• source/libraries/NetworkConfiguration.ts

Smart contract organization

Solidity smart contracts reside in source/contracts. There are two additional folders:

• source/contracts/factories: Constructors for universes, markets, share tokens etc.
• source/contracts/libraries: Libraries (like SafeMath) or utility contracts (like MarketValidator) used elsewhere in the source code.

Oracles and custom resolvers

By design, AugurLite does not come packaged with an oracle system. An oracle is some sort of mechanism for bringing information from the real-world onto a blockchain, enabling smart contracts to respond to it. Here are some popular oracle systems:

• Augur
• Chainlink
• Verity
• Witnet
• Polaris

One goal of AugurLite is to decouple markets from their oracles. Not every market needs to be reviewed by the Augur reporting community. And an oracle for data feeds should be designed differently from an oracle for one-off events. Therefore, markets in AugurLite simply designate an Ethereum address that has the power to resolve them. That oracle address could be a trusted third-party, a smart contract that can observe state from an oracle and pass it along to AugurLite, or something else entirely.

Example: OracleBridge

As an example, Veil uses a smart contract called OracleBridge to observe the result of Augur markets and resolve AugurLite markets accordingly. The OracleBridge address is set as the oracle for Veil's 2020 US Presidential Election markets in order to abstract away various oracle systems. Read more in Veil's smart contracts repository.

Additional resources

Here is a short collection of resources and guides to better understand the Augur ecosystem:

• Augur.Guide
• A guide to Augur market economics
• Off-chain trading with Augur and 0x

Questions and support

If you have questions, comments, or ideas, we recommend pursuing one of these channels:

• Open an issue or pull request in this repository
• Reach out to @veil on Twitter
• Send an email to hello@veil.co
• Join Veil's discord and reach out to a Veil team member

License

AugurLite is released under the GNU General Public License v3.0. See License.