# Using CarbonVortex

The `CarbonVortex` is a contract designed to auction off fees collected within a Carbon DeFi ecosystem. It incentivizes arbitrageurs and public callers to interact with it and facilitates token trading through an auction mechanism. 

This guide explains how to deploy and interact with the contract effectively.

***

### **1. Deploying the `CarbonVortex` Contract**

#### **Steps to Deploy:**

1. **Obtain the Source Code**\
   Download the verified `CarbonVortex.sol` from the official [Bancor GitHub](https://github.com/bancorprotocol/carbon-contracts/tree/dev/contracts/vortex) repository.
2. **Configure Deployment Parameters**
   * **Token Address:** Define the token for which fees will be auctioned.\
     `CarbonVortex` supports 2 dimentional auction for increased flexibility:
     * `targetToken` : This token will be the destination to which all fees collected in multiple different and unique tokens (stables such as USDC and USDT, popular such as wETH, wBTC, or meme such as PEPE, SHIB) will be auctions for. The result is that all tokens collected would be auctioned and traded for this `targetToken` eventually.
     * `finalTargetToken`: This 2nd destination token allows the deployer to define another token in which the `targetToken` will be auctions for. This structure enables a secondary auction that can work for less liquid tokens yet allow consolidation. Deployer can decide to leave this address blank and avoid this step altogether.
   * **Auction Parameters:** Allow flexibility in auction flow and speed as well as the process in which the auction price reacts to trades and restart the auction price as a result.
   * **Caller Incentive:** Define the public incentive to encourage community engagement and interaction with the contract and auctions. 
3. **Deploy the Contract**

   Ensure deployment is on the intended blockchain network (e.g., Ethereum, Polygon).
4. **Verify Deployment**
   * Check the deployed contract address.
   * Verify the deployment on a block explorer to ensure all constructor arguments are set correctly.

***

### **2. Caller Incentive: When and Why to Trigger `execute()`**

The `execute()` function plays a central role in the lifecycle of the `CarbonVortex`:

1. **Transfers Collected Fees**: Aggregates fees from the protocol into the CarbonVortex contract.
2. **Initiates an Auction**: Starts an auction to consolidate various tokens into the `targetToken`.
3. **Provides Caller Incentives**: Rewards the caller of the function to encourage execution.

#### **Caller Incentive:**

* **Caller Rewards:** Callers are rewarded with a portion of the auction proceeds as defined in the contract.
* **Profit Opportunity:** Callers may profit by executing when they can acquire tokens below market value.

#### **Steps to Identify Profitability and Use `execute()`**

1. **Evaluate Tokens Collected by the Contract**
   * Before calling `execute()`, assess the amount of tokens currently held by the `CarbonVortex` contract. These tokens represent fees accumulated by the system.
2. **Identify the Collected Tokens:**

   The contract incentivizes execution by offering rewards to the caller. This incentive is derived from the collected tokens that will be transferred and auctions when calling the `execute()` function.

   * Use `availableTokens()` to identify the available balance of the token at hand.
   * Calculate caller incentives by multiplying this value by the returned value from `rewardsPPM()` .
3. **Trigger `execute()`**\
   Once the incentive is profitable, call the `execute()` function.

#### **What Happens After `execute()` is Called?**

1. **Auction Initialization:**
   * The contract sets up a new auction or restart an existing one, with parameters such as:
     * Starting price.
     * Auction duration.
     * Token amount for auction.
   * Auction details are typically emitted as an event for external tracking.
2. **Caller Reward:**
   * The caller receives their incentive, as calculated earlier, immediately upon execution.

***

### **3. Identifying Auction Prices and Trading Tokens**

#### **Fetching Auction Data**

This process requires retrieving some information from the contract

1. Call the `amountAvailableForTrading()` to identify the amount of tokens that are currently being auctions. This call requires passing the token address.
2. Call the `tokenPrice()` to know the current price for the token
3. Call `tradingEnabled()` and `pairDisabled()` to verify the token auction is enabled
4. Call `expectedTradeReturn()` or `expectedTradeInput()` to confirm the required amount for the trade (this can also help in defining the minReturn correctly to avoid loses)
5. Execute `trade()` to trade against the active auction in the contract

Alternatively, once can calculate the prices off-chain by analyzing the price dynamics:

* Auctions have a decaying price model half life (Dutch auction).
* As time progresses, prices decrease, incentivizing early bids.

#### **Executing a Trade**

Use the `trade()` function to buy tokens:

* Specify the amount you wish to trade.
* Ensure sufficient token allowance or ETH (if applicable).
* Specify the maxInput (commonly known as minReturn) to avoid loses as a result of MEV activity.

***

### **Conclusion**

The `CarbonVortex` contract is a powerful tool for decentralized fee auctions. By understanding its mechanisms and incentives, teams can effectively deploy, maintain, and interact with it to maximize utility and ensure a seamless auction process.