> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Polymarket/ctf-exchange/llms.txt
> Use this file to discover all available pages before exploring further.
# Matching Scenarios
> Learn about the three matching scenarios in the CTF Exchange - NORMAL, MINT, and MERGE
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.
## Matching Scenarios
### 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
**UserA** wants to BUY **100** token **`A`** @ **\$0.50**
```json Order Structure theme={null}
{
"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)
**UserB** wants to SELL **50** token **`A`** @ **\$0.50**
```json Order Structure theme={null}
{
"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)
The exchange calls `matchOrders(makerOrder, [takerOrder], 50, [25])`
**Transfer Flow:**
1. Transfer **50** token **`A`** from **userB** into `CTFExchange`
2. Transfer **25** **`C`** from **userA** into `CTFExchange`
3. Transfer **50** token **`A`** from `CTFExchange` to **userA**
4. 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)
**UserA** wants to BUY **100** token **`A`** @ **\$0.50**
```json Order Structure theme={null}
{
"maker": "userA",
"makerAsset": "C",
"takerAsset": "A",
"makerAmount": 50,
"takerAmount": 100
}
```
**UserB** wants to BUY **50** token **`A'`** @ **\$0.50**
```json Order Structure theme={null}
{
"maker": "userB",
"makerAsset": "C",
"takerAsset": "A'",
"makerAmount": 25,
"takerAmount": 50
}
```
The exchange calls `matchOrders(makerOrder, [takerOrder], 25, 25)`
**Transfer Flow:**
1. Transfer **25** **`C`** from **userB** into `CTFExchange`
2. Transfer **25** **`C`** from **userA** into `CTFExchange`
3. **Mint** **50** token sets (= **50** token **`A`** + **50** token **`A'`**)
4. Transfer **50** token **`A`** from `CTFExchange` to **userA**
5. 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)
**UserA** wants to SELL **50** token **`A`** @ **\$0.50**
```json Order Structure theme={null}
{
"maker": "userA",
"makerAsset": "A",
"takerAsset": "C",
"makerAmount": 50,
"takerAmount": 25
}
```
**UserB** wants to SELL **100** token **`A'`** @ **\$0.50**
```json Order Structure theme={null}
{
"maker": "userB",
"makerAsset": "A'",
"takerAsset": "C",
"makerAmount": 100,
"takerAmount": 50
}
```
The exchange calls `matchOrders(makerOrder, [takerOrder], 50, 50)`
**Transfer Flow:**
1. Transfer **50** **`A'`** from **userB** into `CTFExchange`
2. Transfer **50** **`A`** from **userA** into `CTFExchange`
3. **Merge** **50** token sets into **50** **`C`** (**50** token **`A`** + **50** token **`A'`** = **50** **`C`**)
4. Transfer **25** **`C`** from `CTFExchange` to **userA**
5. 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:
```solidity OrderStructs.sol theme={null}
enum MatchType {
// 0: buy vs sell
COMPLEMENTARY,
// 1: both buys
MINT,
// 2: both sells
MERGE
}
```
## Key Takeaways
Direct token exchange between a buyer and seller of the same outcome token
Mints new token sets when two buyers want complementary outcomes
Merges complementary tokens into collateral when two sellers have opposite positions