guide.mdf

# Futarchy Technical Documentation & Sushiswap Integration Guide

## Table of Contents
1. [System Overview](#system-overview)
2. [Smart Contracts](#smart-contracts)
   - [Contract Addresses](#contract-addresses)
   - [Contract ABIs](#contract-abis)
3. [Token Standards](#token-standards)
4. [Core Operations](#core-operations)
   - [Adding Collateral (Split & Wrap)](#adding-collateral-split-wrap)
   - [Position Merging](#position-merging)
5. [Contract Interactions](#contract-interactions)
6. [Sushiswap Integration and Swap Process](#sushiswap-integration-and-swap-process)
   - [Fetching Swap Route Data](#fetching-swap-route-data)
   - [Executing the Swap](#executing-the-swap)
   - [Route Data Structure](#route-data-structure)
7. [Integration Example](#integration-example)
8. [Error Handling](#error-handling)
9. [Best Practices and Security](#best-practices-and-security)

---

## 1. System Overview

The Futarchy system is a prediction market platform built on the Gnosis Chain. It enables users to trade on outcomes using a combination of ERC1155 and ERC20 tokens. The system employs advanced mechanisms such as splitting positions into YES/NO tokens and wrapping these positions to make them fungible, allowing trading via decentralized exchanges such as SushiSwap.

## 2. Smart Contracts

### Contract Addresses
- **Conditional Tokens Contract:** `0xCeAfDD6bc0bEF976fdCd1112955828E00543c0Ce`
- **Wrapper Service Contract:** `0xc14f5d2B9d6945EF1BA93f8dB20294b90FA5b5b1`
- **Futarchy Router Contract:** `0x7495a583ba85875d59407781b4958ED6e0E1228f`
- **SushiSwap V2 Router:** `0xf2614A233c7C3e7f08b1F887Ba133a13f1eb2c55`
- **Base Currency Token (sDAI):** `0xaf204776c7245bF4147c2612BF6e5972Ee483701`
- **Base Company Token (GNO):** `0x9C58BAcC331c9aa871AFD802DB6379a98e80CEdb`

### Contract ABIs

#### Conditional Tokens ABI
```javascript
[
  'function splitPosition(address collateralToken, bytes32 parentCollectionId, bytes32 conditionId, uint[] partition, uint amount) external',
  'function mergePositions(address collateralToken, bytes32 parentCollectionId, bytes32 conditionId, uint[] partition, uint amount) external',
  'function isApprovedForAll(address owner, address operator) external view returns (bool)',
  'function setApprovalForAll(address operator, bool approved) external',
  'function safeTransferFrom(address from, address to, uint256 id, uint256 amount, bytes data) external'
]
```

#### Wrapper Service ABI
```javascript
[
  'function wrap(address multiToken, uint256 tokenId, uint256 amount, address recipient, bytes data) external',
  'function unwrap(address multiToken, uint256 tokenId, uint256 amount, address recipient, bytes data) external'
]
```

#### Futarchy Router ABI
```javascript
[
  'function splitPosition(address proposal, address collateralToken, uint256 amount) external',
  'function mergePositions(address proposal, address collateralToken, uint256 amount) external'
]
```

#### ERC20 ABI
```javascript
[
  'function approve(address spender, uint256 amount) external returns (bool)',
  'function allowance(address owner, address spender) external view returns (uint256)',
  'function balanceOf(address account) external view returns (uint256)',
  'function transfer(address recipient, uint256 amount) external returns (bool)',
  'function transferFrom(address sender, address recipient, uint256 amount) external returns (bool)'
]
```

#### ERC1155 ABI
```javascript
[
  'function balanceOf(address account, uint256 id) external view returns (uint256)',
  'function safeTransferFrom(address from, address to, uint256 id, uint256 amount, bytes data) external'
]
```

---

## 3. Token Standards

- **ERC1155:** Used for representing the raw YES/NO positions in the system. These tokens allow batch operations and represent non-fungible position IDs.
- **ERC20:** Wrapped tokens generated from splitting positions. They are fungible and can be traded on decentralized exchanges.

---

## 4. Core Operations

### Adding Collateral (Split & Wrap)

The new version simplifies the process by combining position splitting and wrapping into a single operation. When you add collateral, it automatically splits your base token (e.g., sDAI or GNO) into YES and NO positions and wraps them into tradeable ERC20 tokens in one transaction.

```javascript
// Example: Adding collateral (splits and wraps in one step)
async function addCollateral(amount) {
  const amountWei = ethers.utils.parseEther(amount);
  // Approve base token for Futarchy Router
  await baseToken.approve(FUTARCHY_ROUTER_ADDRESS, amountWei);
  // Execute split and wrap via Futarchy Router
  await futarchyRouter.splitPosition(MARKET_ADDRESS, baseTokenAddress, amountWei);
}
```

### Position Merging (Collateral Removal)

Merging combines YES and NO positions back into the original base token in a single transaction.

```javascript
// Example: Merging YES/NO positions
async function mergePositions(amount) {
  const amountWei = ethers.utils.parseEther(amount);
  // Approve wrapped YES and NO tokens
  await yesToken.approve(FUTARCHY_ROUTER_ADDRESS, amountWei);
  await noToken.approve(FUTARCHY_ROUTER_ADDRESS, amountWei);
  // Merge positions via Futarchy Router
  await futarchyRouter.mergePositions(MARKET_ADDRESS, baseTokenAddress, amountWei);
}
```

---

## 5. Contract Interactions

### Approval Flow

Before interacting with the contracts, it is essential to ensure that the user has approved the appropriate token allowances.

```javascript
async function handleTokenApproval(tokenAddress, spenderAddress, amount) {
  const tokenContract = new ethers.Contract(tokenAddress, ERC20_ABI, signer);
  const currentAllowance = await tokenContract.allowance(userAddress, spenderAddress);
  if (currentAllowance.lt(amount)) {
    await tokenContract.approve(spenderAddress, ethers.constants.MaxUint256);
  }
}
```

### Balance Checking

It is important to check both ERC20 and ERC1155 balances before performing operations.

```javascript
async function checkBalances(userAddress) {
  // ERC1155: Get balance for positions
  const positionIds = [yesPositionId, noPositionId];
  const balances = await conditionalTokens.balanceOfBatch(Array(2).fill(userAddress), positionIds);
  // ERC20: Get wrapped token balances
  const wrappedYesBalance = await yesToken.balanceOf(userAddress);
  const wrappedNoBalance = await noToken.balanceOf(userAddress);
}
```

---

## 6. Sushiswap Integration and Swap Process

Sushiswap is used for swapping between the different position tokens within the Futarchy system. This integration is handled using two core functions:

### Fetching Swap Route Data

The `fetchSushiSwapRoute` function fetches optimal route data from the Sushiswap V5 API.

```javascript
const fetchSushiSwapRoute = async ({
  tokenIn,
  tokenOut,
  amount,
  userAddress,
  feeReceiver,
  options = { maxSlippage: '0.005', gasPrice: '1000000008', fee: '0.0025' }
}) => {
  // Constructs API URL and fetches swap route data
  // Returns an object containing:
  //   transferValueTo, amountValueTransfer, tokenIn, amountIn, tokenOut, amountOutMin, to, and route (encoded route bytes)
};
```

### Executing the Swap

Once the route data is obtained, the `executeSushiSwapRoute` function performs the swap execution using the Sushiswap V5 router.

```javascript
const executeSushiSwapRoute = async ({
  signer,
  routerAddress,
  routeData,
  options = { gasLimit: 400000, gasPrice: ethers.utils.parseUnits('0.97', 'gwei') }
}) => {
  // Executes the swap by calling processRouteWithTransferValueOutput on the Sushiswap V2 router
  // Returns a transaction receipt after waiting for confirmation
};
```

### Route Data Structure

The route data returned from the API has the following structure:

```javascript
interface RouteData {
  transferValueTo: string,      // Fee receiver address
  amountValueTransfer: BigNumber, // Fee amount
  tokenIn: string,             // Input token address
  amountIn: BigNumber,         // Input amount
  tokenOut: string,            // Output token address
  amountOutMin: BigNumber,     // Minimum output amount
  to: string,                  // Recipient address
  route: string                // Encoded route bytes
}
```

The encoded route bytes contain detailed information about the swap path, including the number of hops, token addresses, pool types, fees, and protocol identifiers.

---

## 7. Integration Example

```javascript
async function swapPositionTokens(tokenIn, tokenOut, amount, userAddress) {
  try {
    // 1. Fetch the optimal swap route
    const routeData = await fetchSushiSwapRoute({
        tokenIn,
        tokenOut,
        amount: ethers.utils.parseEther(amount),
        userAddress,
        feeReceiver: FEE_RECEIVER_ADDRESS
    });

    // 2. Approve the router to spend the input token if necessary
    await handleTokenApproval(routeData.tokenIn, SUSHISWAP_V2_ROUTER, routeData.amountIn);

    // 3. Execute the swap
    const tx = await executeSushiSwapRoute({
      signer,
      routerAddress: SUSHISWAP_V2_ROUTER,
      routeData
    });

    await tx.wait();
    return tx;
  } catch (error) {
    handleSwapError(error);
  }
}
```

---

## 8. Error Handling

Proper error handling is crucial to ensure a robust integration.

```javascript
function handleSwapError(error) {
  if (error.message.includes('INSUFFICIENT_OUTPUT_AMOUNT')) {
    throw new Error('Slippage too high, try increasing slippage tolerance');
  }
  if (error.message.includes('EXCESSIVE_INPUT_AMOUNT')) {
    throw new Error('Trade size too large for available liquidity');
  }
  if (error.message.includes('user rejected')) {
    throw new Error('Transaction rejected by user');
  }
  console.error('Swap failed:', error);
  throw new Error('Swap failed: ' + error.message);
}
```

---

## 9. Best Practices and Security

### Best Practices
- **Balance Checks:** Always verify token balances before initiating any operation.
- **Approval Management:** Check existing allowances and only request approval if necessary.
- **Gas Optimization:** Set appropriate gas limits and monitor gas prices for efficient transactions.
- **Slippage Protection:** Use reasonable slippage tolerances, e.g., 0.5% to 1%.
- **Modular Functions:** Implement modular and reusable functions like `handleTokenApproval` for consistency.

### Security Considerations
- **Input Validation:** Ensure that all user inputs are validated (e.g., amount is positive and within allowed limits).
- **Allowance Revocation:** Revoke token allowances if they are no longer needed to reduce risk exposure.
- **Transaction Monitoring:** Wait for transaction confirmations and handle failures gracefully using try-catch blocks.
- **Audit:** Regularly audit smart contract interactions and approval logic.

---

This document provides a comprehensive guide on the technical aspects of the Futarchy system and its integration with Sushiswap. Refer to the source code for further implementation details and testing scenarios.