@cowprotocol/sdk-flash-loans

中文文档

4.1.3发布于 2026/11/04MITTypeScriptESM + CJS构建来源已验证近 30 天下载 2587

COW 协议的闪存贷款

文档目录31 节

测试覆盖率
如何运作
为什么用闪存贷款?
安装
设置
使用量
基本担保交换
带引文评论的高级使用
闪存贷款费
边形托肯参数
什么是"托肯斯"吗?
关于克诺斯链的普通指针
用法示例
担保托肯核准
自动批准
手动核准并获得担保担保
EIP-2612许可的无气批准
自定义钩气限制
默认气体限制
自定义气体限制
虎克怎样工作
预览
后图
处理错误
高级主题
EIP-1271 签署
气体优化
适配合同
限制
安全考虑
资源

闪存贷款 SDK

测试覆盖率

发言	分支	职能	行数

使用与COW协议结合的Aave Protocol V3执行以闪存出贷为基础的抵押交换,以优化交易执行.

此 SDK 方便复杂的闪存贷款操作, 您可以:

通过Aave期初贷款借款资产
利用CoW议定书的意向交易交换担保品
通过优化执行自动偿还闪存贷款
使用 CoW 协议钩子管理整个流量

如何运作

通过Aave 闪存贷款的借款令牌
将 CoW 协议交换给想要的抵押品
使用 CoW 钩子来部署适配器合同并管理互换
* 自动以手续费偿还闪存贷款

该订单使用EIP-1271签署,以决定性生成的智能合同地址为签名站.

为什么用闪存贷款?

资本效率 - 没有交换抵押品所需的前期资本
原子能 - 整个操作在解剖学上成功或恢复
气体优化 - 用于复杂多步骤业务的单一交易
协助融合 - 利用Aave V3的闪存贷款基础设施
COW 协议福利 - MEV保护和通过分批拍卖进行最佳执行

安装

npm install @cowprotocol/sdk-flash-loans
# or
pnpm add @cowprotocol/sdk-flash-loans
# or
yarn add @cowprotocol/sdk-flash-loans

你还需要交易SDK:

npm install @cowprotocol/sdk-trading

设置

你需要的就是: 爱丽丝

chainId - 支持链式ID(见 SDK 配置(中文(简体) )
appCode - 跟踪命令的专用应用程序标识符
signer - 私人钥匙、醚签字器或 Eip1193 提供者
TradingSdk 例如 -- -- 获得报价和张贴命令

使用量

基本担保交换

import { AaveCollateralSwapSdk } from '@cowprotocol/sdk-flash-loans'
import { TradingSdk } from '@cowprotocol/sdk-trading'
import { SupportedChainId } from '@cowprotocol/sdk-config'
import { OrderKind } from '@cowprotocol/sdk-order-book'
import { ViemAdapter } from '@cowprotocol/sdk-viem-adapter'
import { createPublicClient, http, privateKeyToAccount } from 'viem'
import { gnosis } from 'viem/chains'

// Set up adapter
const adapter = new ViemAdapter({
  provider: createPublicClient({
    chain: gnosis,
    transport: http('YOUR_RPC_URL')
  }),
  signer: privateKeyToAccount('YOUR_PRIVATE_KEY' as `0x${string}`)
})

// Initialize the Trading SDK
const tradingSdk = new TradingSdk(
  {
    chainId: SupportedChainId.GNOSIS_CHAIN,
    appCode: 'aave-v3-flashloan',
  },
  {},
  adapter
)

// Initialize the Flash Loan SDK
const flashLoanSdk = new AaveCollateralSwapSdk()

// Execute collateral swap
const result = await flashLoanSdk.collateralSwap(
  {
    chainId: SupportedChainId.GNOSIS_CHAIN,
    tradeParameters: {
      sellToken: '0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d', // WXDAI
      sellTokenDecimals: 18,
      buyToken: '0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0', // USDC.e
      buyTokenDecimals: 6,
      amount: '20000000000000000000', // 20 WXDAI
      kind: OrderKind.SELL,
      validFor: 600, // 10 minutes
      slippageBps: 50, // 0.5% slippage
    },
    collateralToken: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533', // aGnoWXDAI (Aave interest-bearing WXDAI)
    flashLoanFeePercent: 0.05, // 0.05% flash loan fee
  },
  tradingSdk
)

console.log('Flash loan order created:', result.orderId)

带引文评论的高级使用

为了最大限度地控制这一过程,包括人工核准管理:

import { AaveCollateralSwapSdk } from '@cowprotocol/sdk-flash-loans'
import { TradingSdk } from '@cowprotocol/sdk-trading'
import { SupportedChainId } from '@cowprotocol/sdk-config'
import { OrderKind } from '@cowprotocol/sdk-order-book'

const flashLoanSdk = new AaveCollateralSwapSdk()

const collateralToken = '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533' // aGnoWXDAI

// Step 1: Prepare quote parameters
const params = {
  chainId: SupportedChainId.GNOSIS_CHAIN,
  tradeParameters: {
    sellToken: '0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d',
    sellTokenDecimals: 18,
    buyToken: '0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0',
    buyTokenDecimals: 6,
    amount: '20000000000000000000',
    kind: OrderKind.SELL,
  },
  collateralToken,
  flashLoanFeePercent: 0.05,
}

const quoteParams = await flashLoanSdk.getSwapQuoteParams(params)

// Step 2: Get quote
const quoteAndPost = await tradingSdk.getQuote(quoteParams)
const { quoteResults } = quoteAndPost

// Step 3: Review the quote
const buyAmount = quoteResults.amountsAndCosts.afterSlippage.buyAmount
console.log(`You will receive at least: ${buyAmount} tokens`)

// Step 4: Generate order settings and get instance address
const { swapSettings, instanceAddress } = await flashLoanSdk.getOrderPostingSettings(
  params,
  quoteParams,
  quoteResults
)

// Step 5: Check collateral allowance
const sellAmount = BigInt(params.tradeParameters.amount)
const allowance = await flashLoanSdk.getCollateralAllowance({
  trader: quoteParams.owner,
  collateralToken,
  amount: sellAmount,
  instanceAddress,
})

console.log(`Current allowance: ${allowance.toString()}`)
console.log(`Required amount: ${sellAmount.toString()}`)

// Step 6: Approve collateral if needed
if (allowance < sellAmount) {
  console.log('Insufficient allowance, approving...')
  const txResponse = await flashLoanSdk.approveCollateral({
    trader: quoteParams.owner,
    collateralToken,
    amount: sellAmount,
    instanceAddress,
  })
  console.log('Approval transaction:', txResponse.hash)
  // Optionally wait for confirmation here
} else {
  console.log('Sufficient allowance already exists')
}

// Step 7: Post the order
const result = await quoteAndPost.postSwapOrderFromQuote(swapSettings)
console.log('Order posted:', result.orderId)

闪存贷款费

临时贷款通常收费(目前大多数资产为0.05%)。这笔费用是:

在得到报价之前从销售额中扣除
确保互换收益既包括预期产出,也包括立即还贷
可配置通过 flashLoanFeePercent 参数

示例

// With 0.05% flash loan fee on 20 WXDAI:
// - Flash loan: 20 WXDAI
// - Fee: 0.01 WXDAI (0.05% of 20)
// - Actual swap amount: 19.99 WXDAI
{
  amount: '20000000000000000000',
  flashLoanFeePercent: 0.05, // 0.05%
}

边形托肯参数

这个 collateralToken 参数指定哪一个Aave有息符(aToken)将作为闪存贷款业务的抵押.

什么是"托肯斯"吗?

当将资产存入Aave时,会收到 aTokens(例如 aWXDAI, aUSDC),即:

代表你的担保品
自动获取利息
可用于闪存贷款抵押交换
闪存贷款适配器支出需要批准

关于克诺斯链的普通指针

const AAVE_TOKENS = {
  aGnoWXDAI: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533', // Aave WXDAI
  aGnoUSDC: '0xc6B7AcA6DE8a6044E0e32d0c841a89244A10D284',  // Aave USDC
  // Add more as needed
}

用法示例

const result = await flashLoanSdk.collateralSwap(
  {
    chainId: SupportedChainId.GNOSIS_CHAIN,
    tradeParameters: {
      sellToken: '0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d', // WXDAI (what we're swapping)
      buyToken: '0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0',  // USDC.e (what we want)
      amount: '20000000000000000000',
      kind: OrderKind.SELL,
    },
    collateralToken: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533', // aGnoWXDAI (our Aave collateral)
    flashLoanFeePercent: 0.05,
  },
  tradingSdk
)

重要注释 :

这个 collateralToken 必须是 Aave aToken 地址
担保物必须有足够的余额
SDK 自动处理此令牌的批准
这不一样 sellToken (这是正在交换的基本资产)

担保托肯核准

在实施抵押品互换之前,闪存贷款适配器需要获得许可才能花出你的抵押品. SDK会自动处理这个,但也提供手动控制的方法.

自动批准

默认, collateralSwap() 必要时自动检查和批准担保品:

// Automatic approval happens here
const result = await flashLoanSdk.collateralSwap(
  {
    chainId: SupportedChainId.GNOSIS_CHAIN,
    tradeParameters: { /* ... */ },
    collateralToken: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533', // aGnoWXDAI
  },
  tradingSdk
)

手动核准并获得担保担保

为加强对批准过程的控制:

// Step 1: Get the adapter instance address
const quoteParams = await flashLoanSdk.getSwapQuoteParams(params)
const quoteAndPost = await tradingSdk.getQuote(quoteParams)
const { swapSettings, instanceAddress } = await flashLoanSdk.getOrderPostingSettings(
  params,
  quoteParams,
  quoteAndPost.quoteResults
)
const sellAmount = BigInt(params.tradeParameters.amount)

// Step 2: Check current allowance
const allowance = await flashLoanSdk.getCollateralAllowance({
  trader: quoteParams.owner,
  collateralToken: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533',
  amount: sellAmount,
  instanceAddress,
})

console.log('Current allowance:', allowance.toString())

// Step 3: Approve if needed
if (allowance < sellAmount) {
  const txResponse = await flashLoanSdk.approveCollateral({
    trader: quoteParams.owner,
    collateralToken: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533',
    amount: sellAmount,
    instanceAddress,
  })
  console.log('Approval transaction:', txResponse.hash)
  // Wait for confirmation...
}

// Step 4: Execute swap with approval prevention
const result = await flashLoanSdk.collateralSwap(
  {
    chainId: SupportedChainId.GNOSIS_CHAIN,
    tradeParameters: { /* ... */ },
    collateralToken: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533',
    settings: {
      preventApproval: true, // Skip automatic approval
    },
  },
  tradingSdk
)

EIP-2612许可的无气批准

对于支持EIP-2612的标志,您可以使用许可证进行无气批准:

// Generate permit signature (implementation varies by wallet)
const collateralPermit = {
  amount: 0,
  deadline: Math.floor(Date.now() / 1000) + 3600, // 1 hour
  v: 27,
  r: '0x...',
  s: '0x...',
}

const result = await flashLoanSdk.collateralSwap(
  {
    chainId: SupportedChainId.GNOSIS_CHAIN,
    tradeParameters: { /* ... */ },
    collateralToken: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533',
    settings: {
      collateralPermit, // Use permit instead of approve
    },
  },
  tradingSdk
)

自定义钩气限制

SDK对执行前钩和执行后钩使用默认的气体限制(分别为30万和60万). 如果需要,您可以自定义每个操作的这些限制 .

默认气体限制

预览:30万瓦斯(部署适配器并设置闪存出借)
后钩: 600 000瓦斯(执行交换并偿还闪存贷款)

自定义气体限制

您可以以两种方式超越气体限制:

1. 管理行动

过 hooksGasLimit 在贸易参数中:

const result = await flashLoanSdk.collateralSwap(
  {
    chainId: SupportedChainId.GNOSIS_CHAIN,
    tradeParameters: {
      sellToken: '0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d',
      sellTokenDecimals: 18,
      buyToken: '0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0',
      buyTokenDecimals: 6,
      amount: '20000000000000000000',
      kind: OrderKind.SELL,
      validFor: 600,
      slippageBps: 50,
    },
    settings: {
      hooksGasLimit: {
        preHookGasLimit: 500000n,  // Custom pre-hook gas limit
        postHookGasLimit: 800000n, // Custom post-hook gas limit
      },
    },
    collateralToken: '0xd0Dd6cEF72143E22cCED4867eb0d5F2328715533',
  },
  tradingSdk
)

2. SDK-Wide 默认覆盖

初始化 SDK 时设定自定义默认 :

const flashLoanSdk = new AaveCollateralSwapSdk({
  hooksGasLimit: {
    pre: 500000n,  // Custom default pre-hook gas limit
    post: 800000n, // Custom default post-hook gas limit
  },
})

// All operations will now use these defaults unless overridden per-operation

虎克怎样工作

SDK使用 CoW 协议钩来协调闪存出借:

预览

确定适用Aave适配器合同
将闪存贷款转让给适配器
设置互换参数

后图

通过适配器执行抵押交换
以手续费偿还Aave闪存贷款
向所有人转让剩余代币

所有钩子由SDK自动配置并估算出气体.

处理错误

常见错误和解决方案:

短期贷款数额不足

// Error: Flash loan amount doesn't cover fee + swap
// Solution: Increase amount or adjust flash loan fee
{
  amount: '20000000000000000000', // Increase this
  flashLoanFeePercent: 0.05,
}

滑过紧

// Error: Slippage tolerance too low for current market conditions
// Solution: Increase slippageBps
{
  slippageBps: 100, // Increase from 50 to 100 (1%)
}

命令已过期

// Error: Order validity period too short
// Solution: Increase validFor
{
  validFor: 1200, // 20 minutes instead of 10
}

高级主题

EIP-1271 签署

闪存出借订单使用EIP-1271签名验证,并带有决定性生成的智能合同地址. 这样可以:

无气令创建
决定合同部署
安全闪存贷款执行

气体优化

SDK自动:

钩子执行气体估计数
如果估计失败,使用回落气体限制
优化钩子呼叫数据编码

适配合同

适应合同有:

使用CREATE2确定部署
多个闪存贷款业务可重复使用
自动由 SDK 管理

限制

只支持 Aave V3 闪存贷款
要求在Aave池中有足够的流动性
适用闪付贷款费(通常为0.05%)
受《化学武器议定书》限制
需要部署网络专用合同

安全考虑

执行前总是审查引用
设置适当的后退容限
验证令牌地址和小数
先用少量测试
监测交易执行
了解闪存贷款收费和费用

资源

版本与发布记录

@cowprotocol/sdk-flash-loans 共发布 84 个版本，首次发布于 2025/10/24；过去 12 个月发布了 76 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`4.1.3`latest	2026/11/04	6 天前
`4.1.2`	2026/11/04	6 天前
`4.1.1`	2026/11/03	7 天前
`4.1.0`	2026/10/26	15 天前
`4.0.1`	2026/10/23	18 天前
`4.0.0`	2026/10/13	28 天前

关于 @cowprotocol/sdk-flash-loans 的常见问题

@cowprotocol/sdk-flash-loans 是什么？

COW 协议的闪存贷款

如何安装 @cowprotocol/sdk-flash-loans？

在项目目录运行 npm install @cowprotocol/sdk-flash-loans，或使用 pnpm add / yarn add / bun add。

@cowprotocol/sdk-flash-loans 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@cowprotocol/sdk-flash-loans 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require() 都可以使用，打包工具会自动选择合适的版本。

@cowprotocol/sdk-flash-loans 可以商用吗？

@cowprotocol/sdk-flash-loans 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@cowprotocol/sdk-flash-loans 的下载量有多少？

根据 npm 官方下载统计，@cowprotocol/sdk-flash-loans 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,587 次，日均约 86 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@cowprotocol/sdk-flash-loans 还在维护吗？

最新版本 4.1.3 发布于 2026/11/04（6 天前）；至今共发布 84 个版本，其中过去 12 个月发布了 76 个；首次发布于 2025/10/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。