# iExchange Protocol

### P2P Order lifecycle Overview

This document outlines the life cycle of buy and sell orders iExchange. It integrates off-chain messaging, cross-chain validation, and smart contract interactions to ensure a secure, transparent, and efficient trading process.

### Definitions

| Component          | Description                                                              |
| ------------------ | ------------------------------------------------------------------------ |
| Off-Chain Messages | Signed intent, cancellation, and dispute messages.                       |
| Taker Chain        | Handles taker escrow, payments, and fund releases.                       |
| Maker Chain        | Handles maker escrow, payments, and fund releases.                       |
| Cross-Chain Bridge | Facilitates communication and validation between taker and maker chains. |
| Smart Contracts    | Enforce escrow rules, cancellations, payments, and dispute resolutions.  |
| Maker              | A participant who places ads (intent to buy or sell).                    |
| Taker              | A participant who chooses an ad and initiates a transaction.             |
| Arbiter            | Resolves disputes and submits decisions to the smart contract.           |

\


### General Rules

1. **Ad Creation:**

* Makers place ads (intent to buy or sell) by signing off-chain messages.
* These ads include essential details (e.g., order terms, price, and expiration).

2. **Cross-Chain Communication:**

* Escrow management, payment confirmation, and fund release may require cross-chain messages.

3. **Cancellations:**

* Either party can cancel an order before payment or if the other party fails to act within a set time limit.

4. **Dispute Resolution:**

* Disputes can be raised after an order is marked as paid.
* Manual arbitration decisions require signed dispute messages to execute resolutions on the smart contract.

If the maker cancels multiple orders, their ad is automatically de-listed to present misuse. If a maker's ads get de-listed multiple times, they are banned from placing ads for a period.

### Buy Order Flow

#### 1. Order Creation

* (Off-Chain):
  * Taker chooses an ad and signs a message indicating an order to buy.
  * An expiration time is included to ensure order has to be submitted to the smart contract before the deadline.
* Notification:
  * The maker is notified of the taker’s intent.

#### 2. Maker Acceptance

* (Off-Chain):
  * Maker accepts the order by signing an agreement signature
    * This signature includes approval of the tokens to be transferred to the contract.
    * Using permits
    * Or approval flow
  * Up to this point they don't have access to the taker's signature
* (On Maker Chain):
  * Anyone with a maker and taker's signature can submit the two signatures to the contract.
  * In iExchange's flow, this is done by the maker.
* Smart Contract Validation:
  * Ensures the time limit for acceptance has not expired.

#### 3. Maker Rejection

* (Off-Chain):
  * Maker can simply reject the notification if not interested

#### 4. Taker Payment or Cancellation

**Taker Pays**

* Taker pays for the order and submits a transaction to mark the order as paid.

**Taker Cancels**

* (Off-Chain):
  * Taker can cancel by signing a cancellation message.
* Smart Contract Submission:
  * This signed message can be submitted by anyone to the smart contract. The options are;
  * Taker submits the message themselves. This is how it will be done if the destination chain is the same as the taker chain.
  * Submitted by the maker.
  * Submitted by iExchange.
  * Smart contract releases maker tokens back to them

#### 5. Maker Release

* After verifying payment, the maker sends a message to release the escrowed funds to the taker.
* If the taker is on a different chain, the token transfer is done using a cross-chain transaction.
* Smart Contract Validation:
  * Confirm the payment status before releasing funds.

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXfrWjsZ-bsA4_6B-sNIhbiOVGoS2iXbUXZu8ueuDNbIvVyN3WbdDzKWveAlZrIt5Xl77wG371b_4L3f9s18dwxXmWAL00iQoxLSJvRdSUc_W7B2tYiKzLunpjT4-Ve5Dy-bhfMDXQ?key=438w3DiA4nM75tX3u0u4EqIR" alt=""><figcaption><p>Process flow diagram for Buy</p></figcaption></figure>

### Sell Order Flow

#### 1. Order Creation

* (On Taker Chain):
  * Taker chooses an ad and interacts with the smart contract to escrow their funds.
* Notification:
  * The maker is notified of the order.

#### 2. Maker Payment or Rejection

**Maker Cancels**

* Sign cancellation message
* Smart Contract Submission:
  * This signed message can be submitted by anyone to the smart contract. The options are;
    * Maker submits the message themselves. This is how it will be done if the destination chain is the same as the maker chain.
    * Submitted by the taker. The UX will show as claiming funds.

**Maker Pays**

* Maker submits a transaction indicating that they have paid.
* Smart Contract Submission:
  * This signed message can be submitted by anyone to the smart contract. The options are;
    * Maker submits the message themselves. This is how it will be done if the destination chain is the same as the taker chain.
    * Submitted by the taker.
    * Submitted by iExchange. This is how it will be done if the destination chain is different from the taker's chain.

#### 3. Taker Release

* Taker verifies the payment and sends a message to release the escrowed funds to the maker.
* If the maker is on a different chain, the token transfer is done using a cross-chain transaction.
* Smart Contract Validation:
  * Confirms the maker's payment before releasing funds.

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXe8w8yivz7fZNvaAStjtXqTpbITfiE8pVIC8K7NZQMoHF6UZFzCq6BJnHBKlY8D-DFxKWHVpxk5iM241RCizqujTXgE4DEj4QcFgujrLirQD8Ac6BPRhkEHPOMEE8Bta_LY4JY6ZQ?key=438w3DiA4nM75tX3u0u4EqIR" alt=""><figcaption></figcaption></figure>

### Dispute Resolution Flow

* Conditions:
  * Either party can raise a dispute after the maker marks the order as paid.
*   Process:

    Dispute is raised by signing a dispute message off-chain.

    * Manual arbitration begins.
* Arbitration Execution:
  * Arbiter submits the dispute decision (signed message) to the smart contract.
  * Smart contract validates the signed message and executes the resolution to release escrowed funds accordingly.

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXcdtz26ADrdg6hQm-sAE75pWhV5Uai-A2-lJQ4vyFoCCBT01sglo7WByGRppYyPFOVATcD7oEhO-iJREHk7Qj_nsZnDhsJep-7dwyI_PImFO4gPcPxSzb2BmKAEQUU1NFaIp4HP?key=438w3DiA4nM75tX3u0u4EqIR" alt=""><figcaption></figcaption></figure>

### Time-Limit Enforcement for Non-Payment

Time limits will be enforced in the following scenarios;

1. Taker waiting for maker acceptance
2. Taker waiting for maker payment
3. Maker waiting for taker payment

#### Taker waiting for maker acceptance

* This scenario happens in the buy flow where the taker sends a buy intent to the maker.
* In order to ensure time limits, the taker includes an expiry time in their signature.
* If the order is submitted to the contract after this expiry time, it will be reverted.

#### Taker waiting for maker payment

* This also happens in the sell flow where the order has been accepted by maker
* There should be a global min and max time limit on fiat payment in the protocol.
* This is the minPaymentTimeLimit
* After this period passes, the taker should be able to cancel the transaction without any consent from the maker or dispute process.

#### Maker waiting for taker payment

* This also happens in the buy flow where the order has been accepted
* There should be a global min and max time limit on fiat payment in the protocol.
* This is the minPaymentTimeLimit
* After this period passes the maker should be able to cancel the transaction without any consent from the taker or dispute process.

## Account Management

\
iExchange offers users flexible options for account management, ensuring both accessibility and security. Users can choose between two primary authentication methods: social login via Alchemy Account Kit or traditional wallet connections.

#### Social Login with Alchemy Account Kit

For users who prefer a seamless onboarding experience, iExchange integrates Alchemy Account Kit, allowing authentication via social logins such as Google, GitHub, and other OAuth providers. When a user signs in through social login:

* They are assigned a non-custodial signer, managed by Alchemy. This signer enables them to interact with the blockchain without needing to manage private keys directly.
* The private keys are securely generated and stored within Turnkey’s secure enclaves. Neither iExchange nor Alchemy has access to these keys.
* Users authenticate their sessions with iExchange by signing a message using their assigned signer after verifying their identity with the social provider.
* Alchemy Account Kit ensures a high level of security while maintaining a user-friendly authentication process.
* Additionally, users have the option to export their private keys, ensuring they retain full control over their accounts if needed.

For more details on how Alchemy Account Kit works, visit [Alchemy's documentation](https://www.alchemy.com/docs/wallets).

#### Traditional Wallet Authentication

Users who prefer to maintain full control over their private keys can connect their own wallets, such as MetaMask or WalletConnect-compatible wallets. In this case:

* The user manages their private key and is responsible for signing transactions.
* Upon connecting their wallet, the user must sign a message to authenticate themselves with the iExchange backend. This step ensures that the wallet owner is in control and prevents unauthorized access.
* Unlike social login users, these users handle their own key security and recovery.

#### Authentication Flow

Regardless of the authentication method used, iExchange follows a consistent process for backend verification:

1. Social Login Users: Authenticate with their social provider → Signer signs a message → The signed message is sent to iExchange’s backend for verification.
2. Traditional Wallet Users: Connect their wallet → Sign a message using their wallet → The signed message is sent to iExchange’s backend for verification.

This approach ensures a seamless yet secure user experience, balancing ease of use with decentralised ownership principles.

#### Wallet Linking

Users may choose to link multiple wallets to a single iExchange account, allowing seamless access across different devices and login methods. Wallet linking ensures that users can sign in using either a wallet or social login while maintaining the same account.

**Linking a Wallet to an Existing Account**

1. The user signs in using their existing account.
2. In the account settings, they select "Link Another Wallet."
3. The user connects their new wallet and signs a verification message.
4. The backend verifies the wallet and associates it with the user's existing account.
5. The user can now sign in with either their wallet and have access to the same account.
