📗Aggregator

Aggregator Contract API Documentation

Overview

The Aggregator contract is a smart contract that handles token swaps, cross-chain bridging, and batch transfers. It implements an upgradeable pattern and includes the following security features:

• Pausable functionality (emergency stop)

• Reentrancy protection

• Access control through ownership

Core Methods

executeSwap

Function: Execute token swap

Parameters:

struct SwapRequest {
    address inputToken;    // Input token address
    address outputToken;   // Output token address
    uint256 inputAmount;   // Input amount
    uint256 minOutputAmount; // Minimum output amount
    uint256 feeAmount;     // Fee amount
    address feeRecipient;  // Fee recipient address
    address recipient;     // Recipient address
    bool unwrapped;        // Whether to unwrap WETH
    bytes extData;        // Extended data
}

struct Call {
    address target;        // Target contract address
    bytes callData;       // Call data
    uint256 value;        // Transfer amount
}

Example:

// Swap ETH to USDC
Aggregator.executeSwap(
    SwapRequest({
        inputToken: address(0),
        outputToken: USDC_ADDRESS,
        inputAmount: 1 ether,
        minOutputAmount: 1900 * 1e6, // 1900 USDC
        feeAmount: 0.01 ether,
        feeRecipient: FEE_RECIPIENT,
        recipient: USER_ADDRESS,
        unwrapped: false,
        extData: ""
    }),
    [Call({
        target: DEX_ADAPTER,
        callData: abi.encodeWithSelector(...),
        value: 0
    })]
){value: 1 ether};

Notes:

1. Input amount must be greater than 0

2. Fee amount cannot exceed input amount

3. For ETH swaps, msg.value must equal inputAmount

4. Output amount must be greater than minOutputAmount

5. feeAmount can be set to 0 to indicate no fee, in which case feeRecipient must also be set to the 0 address

6. When real-time commission is needed, feeAmount and feeRecipient parameters can be passed

executeBridge

Function: Execute cross-chain bridge

Parameters:

struct BridgeRequest {
    address inputToken;    // Input token address
    uint256 inputAmount;   // Input amount
    uint256 feeAmount;     // Fee amount
    address feeRecipient;  // Fee recipient address
    address recipient;     // Recipient address
    bool unwrapped;        // Whether to unwrap WETH
    bytes extData;        // Extended data
}

Example:

// Bridge ETH
Aggregator.executeBridge(
    BridgeRequest({
        inputToken: address(0),
        inputAmount: 1 ether,
        feeAmount: 0.01 ether,
        feeRecipient: FEE_RECIPIENT,
        recipient: USER_ADDRESS,
        unwrapped: false,
        extData: ""
    })
){value: 1 ether};

Notes:

1. Input amount must be greater than 0

2. Fee amount cannot exceed input amount

3. For ETH bridges, msg.value must equal inputAmount

4. Recipient address cannot be 0

5. feeAmount can be set to 0 to indicate no fee, in which case feeRecipient must also be set to the 0 address

6. When real-time commission is needed, feeAmount and feeRecipient parameters can be passed

extData Generation Instructions

The extData field is used to pass extended data, formatted as a hexadecimal representation of URL-encoded parameters.

Field Mapping:

// Field abbreviation to full name mapping
const ContractExtDataField = {
  's': 'slippage', // Slippage
  'app': 'app', // Application/channel (if using 0x00..00, EVM wallet address can be connected to withdraw commission)
  't': 'targetRecipient', // Target recipient
  'c': 'targetChain', // Target chain
  'tt': 'targetToken', // Target token
  'o': 'targetTokenSymbol', // Target token symbol
  'r': 'rebateRate', // Rebate rate
  'e': 'expectValue', // Expected value
  'm': 'minExpectedValue', // Minimum expected value
  'h': 'hash', // Hash
  'ot': 'originToken', // Origin token
  'os': 'originTokenSymbol', // Origin token symbol
  'ov': 'originValue' // Origin value
}

Generation Example:

// Generate extData
function buildExtData(data: Partial<Record<keyof typeof ContractExtDataField, string>>): string {
  const params = new URLSearchParams();

  for (const [key, value] of Object.entries(data)) {
    if (value !== undefined) {
      params.append(key, String(value));
    }
  }

  return Buffer.from(params.toString()).toString('hex');
}

// Usage example
const extData = buildExtData({
  t: '0x123', // Target recipient address
  s: '0.5' // 0.5% slippage
});

Notes:

1. All values will be converted to string type

2. Empty or undefined fields will be ignored

3. The final result is a hexadecimal string of URL-encoded parameters