# Intent-Based Trading System

## **Intent States**

| State               | Description                                                    |
| ------------------- | -------------------------------------------------------------- |
| **PENDING**         | Initial state when intent is created by Party A                |
| **LOCKED**          | Intent reserved by a Party B                                   |
| **FILLED**          | Intent executed and trade created                              |
| **EXPIRED**         | Intent passed expiration time                                  |
| **CANCELLED**       | Intent cancelled by Party A before filling                     |
| **CANCEL\_PENDING** | Party A cancelled locked intent, awaiting Party B confirmation |

## **Trading Lifecycle**

<figure><img src="https://1257875949-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYQhBmTCs9MwhhuPQrV5v%2Fuploads%2Fvm1TaUpuyO9ya9JTzzFF%2Fimage.png?alt=media&#x26;token=714a211f-6b1b-461d-8a41-ef12ad7e1eb3" alt=""><figcaption></figcaption></figure>

### **Step 1: Send Open Intent**

Party A initiates an open intent by calling:

```solidity
function sendOpenIntent(
    address[] calldata partyBsWhiteList,
    uint256 symbolId,
    uint256 price,
    uint256 quantity,
    uint256 strikePrice,
    uint256 expirationTimestamp,
    uint256 mm,
    TradeSide tradeSide,
    MarginType marginType,
    ExerciseFee memory exerciseFee,
    uint256 deadline,
    address feeToken,
    address affiliate,
    bytes memory userData
) external returns (uint256 intentId)
```

* **Fees**: Party A pays three fees : protocol fee + affiliate fee + solver fee.
* **Fund locking**:

**BUY options:**

* Party A locks the option premium: `premium = option_price × quantity`.
* The premium will be transferred to Party B when the trade is settled.

**SELL options**

* Party A locks the required maintenance margin.

The intent is stored with **PENDING** status and becomes visible to eligible Party B accounts.

## **Step 2: Lock Open Intent**

**Eligibility requirements for Party B**

* The intent is **PENDING** and has not expired.
* Party B’s address is included in `partyBsWhiteList`.
* Party B has a sufficient balance to meet its obligations.
* Party B accepts the terms.

```solidity
function lockOpenIntent(uint256 intentId) external onlyPartyB
```

* The intent status changes from **PENDING** to **LOCKED** and is reserved for the locking Party B.

## **Step 3: Fill Open Intent**

```solidity
function fillOpenIntent(uint256 intentId, uint256 quantity, uint256 price) external
```

**BUY options :**

* The locked premium is debited from Party A and credited to Party B. It will be paid to Party B after settlement.

**SELL options :**

* The locked maintenance margin is added to Party A’s total maintenance margin balance for solvency checks.
* Party B pays the premium to Party A.
* A new trade is created with **OPENED** status.
* The intent status changes from **LOCKED** to **FILLED**.

### **Step 4: Close Position**

#### **4.1 Early Close (before expiration)**

Party A may close a position early by sending a close intent:

```solidity
function sendCloseIntent(
    uint256 tradeId,
    uint256 quantity,
    uint256 price,
    uint256 deadline
) external
```

**BUY positions:**

* The premium is paid to Party B.
* Party A sells the option back to Party B.
* Party B pays Party A the PnL:

  `PnL = (closePrice − openPrice) × quantity`.

  If **PnL < 0**, Party A pays the loss to Party B.

**SELL positions**

* The corresponding maintenance margin is released to Party A.
* Party A pays Party B the PnL (same formula as above).

  If **PnL < 0**, Party B pays the loss to Party A.

#### **4.2 Settlement at Expiration**

```solidity
function executeTrade(
    uint256 tradeId,
    SettlementPriceSig memory settlementPriceSig
) external
```

* Party B keeps the premium already received (for trades where Party A was the buyer).

**In‑the‑Money (ITM)**

* Settlement price is obtained from the oracle.
* `PnL = (settlementPrice − strikePrice) × quantity`.
* The seller pays the positive P\&L to the buyer (or vice versa if negative).

**Out‑of‑the‑Money (OTM)**

* The option expires worthless.
* Any maintenance margin locked by the Party A seller is released.