Matching Scenarios

The CTFExchange supports three different matching scenarios that enable efficient trading and liquidity provision for binary outcome tokens. Each scenario handles different combinations of buy and sell orders.

Asset Notation

Before diving into the scenarios, let’s define the asset types used:

A - ERC1155 outcome token
A' - ERC1155 outcome token, complement of A
C - ERC20 collateral token (e.g., USDC)

Complements assumes 1 outcome token and 1 of its complement can always be merged into 1 unit of collateral and 1 unit of collateral can always be split into 1 outcome token and 1 of its complement (i.e., A + A' = C).Outcome tokens and collateral have the same decimals/base unit.

NORMAL
MINT
MERGE

Scenario 1: NORMAL Matching

The NORMAL scenario matches a buy order against a sell order for the same outcome token. This is a standard exchange where tokens are transferred directly between users.

Example: Buy vs Sell

Maker Order

UserA wants to BUY 100 token A @ $0.50

Order Structure

{
  "maker": "userA",
  "makerAsset": "C",
  "takerAsset": "A",
  "makerAmount": 50,
  "takerAmount": 100
}

UserA is offering 50 USDC to receive 100 token A (price: $0.50 per token)

Taker Order

UserB wants to SELL 50 token A @ $0.50

Order Structure

{
  "maker": "userB",
  "makerAsset": "A",
  "takerAsset": "C",
  "makerAmount": 50,
  "takerAmount": 25
}

UserB is offering 50 token A to receive 25 USDC (price: $0.50 per token)

Match Execution

The exchange calls matchOrders(makerOrder, [takerOrder], 50, [25])Transfer Flow:

Transfer 50 token A from userB into CTFExchange
Transfer 25 C from userA into CTFExchange
Transfer 50 token A from CTFExchange to userA
Transfer 25 C from CTFExchange to userB

Scenario 2: MINT Matching

The MINT scenario matches two buy orders for complementary outcome tokens. Since both users want to buy complementary outcomes, the exchange mints new token sets from the collateral provided by both users.

Example: Buy vs Buy (Complementary)

Maker Order

UserA wants to BUY 100 token A @ $0.50

Order Structure

{
  "maker": "userA",
  "makerAsset": "C",
  "takerAsset": "A",
  "makerAmount": 50,
  "takerAmount": 100
}

Taker Order

UserB wants to BUY 50 token A' @ $0.50

Order Structure

{
  "maker": "userB",
  "makerAsset": "C",
  "takerAsset": "A'",
  "makerAmount": 25,
  "takerAmount": 50
}

Match Execution

The exchange calls matchOrders(makerOrder, [takerOrder], 25, 25)Transfer Flow:

Transfer 25 C from userB into CTFExchange
Transfer 25 C from userA into CTFExchange
Mint 50 token sets (= 50 token A + 50 token A')
Transfer 50 token A from CTFExchange to userA
Transfer 50 token A' from CTFExchange to userB

In MINT scenarios, the combined collateral from both buyers is used to mint complementary token sets, which are then distributed to each buyer.

Scenario 3: MERGE Matching

The MERGE scenario matches two sell orders for complementary outcome tokens. Since both users are selling complementary outcomes, the exchange merges the tokens back into collateral and distributes it to both sellers.

Example: Sell vs Sell (Complementary)

Maker Order

UserA wants to SELL 50 token A @ $0.50

Order Structure

{
  "maker": "userA",
  "makerAsset": "A",
  "takerAsset": "C",
  "makerAmount": 50,
  "takerAmount": 25
}

Taker Order

UserB wants to SELL 100 token A' @ $0.50

Order Structure

{
  "maker": "userB",
  "makerAsset": "A'",
  "takerAsset": "C",
  "makerAmount": 100,
  "takerAmount": 50
}

Match Execution

The exchange calls matchOrders(makerOrder, [takerOrder], 50, 50)Transfer Flow:

Transfer 50 A' from userB into CTFExchange
Transfer 50 A from userA into CTFExchange
Merge 50 token sets into 50 C (50 token A + 50 token A' = 50 C)
Transfer 25 C from CTFExchange to userA
Transfer 25 C from CTFExchange to userB

In MERGE scenarios, complementary tokens from both sellers are merged into collateral, which is then distributed proportionally to each seller.

Match Type Enum

The contract defines a MatchType enum to identify these scenarios:

OrderStructs.sol

enum MatchType {
    // 0: buy vs sell
    COMPLEMENTARY,
    // 1: both buys
    MINT,
    // 2: both sells
    MERGE
}

Key Takeaways

NORMAL

Direct token exchange between a buyer and seller of the same outcome token

MINT

Mints new token sets when two buyers want complementary outcomes

MERGE

Merges complementary tokens into collateral when two sellers have opposite positions

Overview

Core Concepts

Deployment

Security

Matching Scenarios

Asset Notation