Split, Merge and Redeem

The Router contract is a wrapper around ConditionalTokens contract, allowing users to split, merge and redeems outcome tokens using an ERC20 collateral token. Note that in order to call Router functions, a prediction market (as well as its outcome tokens) must be created beforehand (see Create a market).

Split position

function splitPosition(
    IERC20 collateralToken,
    Market market,
    uint amount
) public

Step-by-step, the function will:

1. Transfer <amount> collateral from the user to Router.

2. Call conditionalTokens.splitPosition to transfer <amount> collateral from Router to ConditionalTokens, while minting corresponding ERC1155 outcome tokens to Router.

3. Transfer outcome tokens from Router to Wrapped1155Factory contract. There is a callback function in Wrapped1155Factory that will wrap the ERC1155 tokens into ERC20 tokens, then transfer the wrapped tokens back to the original user.

Merge positions

function mergePositions(
    IERC20 collateralToken,
    Market market,
    uint amount
) public

Merging positions does precisely the opposite of what splitting a position does. First, it unwraps ERC20 outcome tokens (which will burn these tokens and transfer corresponding ERC1155 outcome tokens to the Router contract). The function will then call conditionalTokens.mergePositions to burn ERC1155 outcome tokens and return collateral to Router. Finally, collateral will be sent to the user.

Redeem positions

function redeemPositions(
    IERC20 collateralToken,
    Market market,
    uint256[] calldata outcomeIndexes,
    uint256[] calldata amounts
) public

A user can only redeem their positions after conditionalTokens.reportPayouts has been called by an oracle. Router will try to redeem based on the provided outcomeIndexes and amounts for collateral (or parent outcome tokens in conditional markets), then transfer back to the user.

Conditional markets

In the case of conditional markets, we will work with parent outcome tokens instead of collateral tokens.

When splitting a position, we will split from a parent position to deeper conditional positions. The opposite is true in the case of merging. For redeeming, you will redeem for parent outcome tokens instead of collateral. There will be an example in the later section.

GnosisRouter and MainnetRouter

GnosisRouter is a Router implementation to use on Gnosis chain, using Savings xDai as its collateral token. Users must have available xDai tokens to call splitFromBase .

function splitFromBase(
    Market market
) external payable

MainnetRouter is similar to GnosisRouter, but is used on Ethereum mainnet. Users must have available Dai tokens to call splitFromDai.