@astrolabs/swapper

Swapper

by Astrolab

Swapper is Astrolab's liquidity meta-aggregator, powering all of its monochain and cross-chain swaps. It blends liquidity and bridge aggregators. The DEX meta-aggregation was inspired by LlamaSwap's work available here, supercharged with cross-chain capacity.

⚠️ Disclaimer

Astrolab DAO and its core team members will not be held accountable for losses related to the deployment and use of this repository's codebase. As per the licence states, the code is provided as-is and is under active development. The codebase, documentation, and other aspects of the project may be subject to changes and improvements over time.

Supported Aggregators

Don't hesitate to reach out or submit pull requests with missing aggregators adapters.

Bridges+Liquidity

• Li.Fi stable tested
• Squid Router stable tested
• Socket stable tested

Liquidity

• 1inch stable tested
• 0x stable tested
• KyberSwap stable tested
• ParaSwap untested

To be implemented

• CowSwap
• OpenOcean
• DeBridge's DLN

Features

Swapper SDK

The Swapper SDK facilitates TransactionRequests and raw CallData construction for every aggregator, in a unified way. The querying uses a generic ISwapperParams object as seen here.

The SDK can be used off-chain via ethers or viem, the generated callData can be used with any provider implementation or directly on-chain by passing the callData to the Swapper.sol contract on the desired chain.

ethers examples

import { AggregatorId, ISwapperParams } from "@astrolab/swapper/types";
import { getCallData, getTransactionRequest, swapperParamsToString } from "@astrolab/swapper";
import { TransactionRequest } from "ethers";

const _1inchSwap: ISwapperParams = {
  aggregatorId: AggregatorId.ONE_INCH,
  inputChainId: 250, // fantom->fantom
  input: addresses[250].tokens.LZUSDC,
  output: addresses[250].tokens.AXLUSDC,
  amountWei: 100 * 1e6, // $100
  payer: `0xPaYeR`
};

const lifiSwap: ISwapperParams = {
  aggregatorId: AggregatorId.LIFI,
  inputChainId: 250, // from fantom
  input: addresses[250].tokens.LZUSDC, // USDC-e
  outputChainId: 10 // to optimism
  output: addresses[42161].tokens.LZUSDC, // USDC-e
  amountWei: 100 * 1e6, // $100
  payer: `0xPaYeR`
};

// fetch the transaction request object from both aggregators
// NB: this transaction request object can then be used with ethers.sendTransaction
// eg. ethers.sendTransaction(tr)
async function getTransactionRequests(): TransactionRequest[] {
  return await Promise.all([_1inchSwap, lifiSwap]
    .map(s => getTransactionRequest(s)));
}

// fetch only the callData from both aggregators
// NB: this callData should be passed to the smart contract .call() directly
// this assumes that the caller already knows the aggregator contract (available in tr.to)
async function getTransactionRequests(): TransactionRequest[] {
  return await Promise.all([_1inchSwap, lifiSwap]
    .map(s => getCallData(s)));
}

Aggregator Clients

• Li.Fi
• Squid Router
• Socket
• 1inch
• 0x
• KyberSwap
• ParaSwap

Swapper Contract

The Swapper contract is a proxy that allows generic callData to be executed on the requested aggregator's contract, available from transactionRequest.to. It adds a layer of security between the client who swap and the target aggregation router. A Swapper instance can:

• whitelist callers
• whitelist input tokens
• whitelist output tokens
• whitelist router

It also enforces slippage/price impact protection, making the use of external callData inherently safer.

Usage

To start using Swapper, you can clone the repository and install the necessary dependencies.

git clone https://github.com/AstrolabFinance/swapper
cd swapper

Installation

yarn install

Unit Testing (client only)

This only tests the client functions (typescript SDK).

yarn test-unit

Integration Testing

This tests the client functions (typescript SDK) + the contract execution by forking with hardhat and deploying Swapper.sol locally, then passing callData to it.

yarn test-integration

Pruning

Cleans hardhat and typescript compilation caches, artifacts and dist folders.

yarn clean

Contributing

Contributions are welcome! Feel free to open an issue or create a pull request if you have any improvements or suggestions.