# @cowprotocol/sdk-flash-loans 中文文档

规范地址：https://npmcn.com/package/%40cowprotocol/sdk-flash-loans/

版本：4\.1\.3
npm 元数据更新时间：2026-11-04T11:33:13.311Z
中文译文更新时间：2026-11-10T22:21:36.644Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cowprotocol/sdk-flash-loans
原文对照：https://npmcn.com/package/%40cowprotocol/sdk-flash-loans/?lang=original
源码仓库：https://github.com/cowprotocol/cow-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：125 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2025-10-24T11:19:22.746Z
- 最新版本发布：2026-11-04T11:33:12.934Z
- 近 30 天下载量：2587（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：84（近 12 个月 76 个）

## 中文简介

COW 协议的闪存贷款

## 安装

```sh
npm install @cowprotocol/sdk-flash-loans
```

也可以使用：`pnpm add @cowprotocol/sdk-flash-loans`、`yarn add @cowprotocol/sdk-flash-loans`、`bun add @cowprotocol/sdk-flash-loans`

## README

![](https://github.com/cowprotocol/cow-sdk/raw/main/docs/images/CoW.png)

# 闪存贷款 SDK

## 测试覆盖率

| 发言 | 分支 | 职能 | 行数 |
| --- | --- | --- | --- |
| ![Statements](https://img.shields.io/badge/statements-47.9%25-red.svg?style=flat) | ![Branches](https://img.shields.io/badge/branches-63.93%25-red.svg?style=flat) | ![Functions](https://img.shields.io/badge/functions-64.28%25-red.svg?style=flat) | ![Lines](https://img.shields.io/badge/lines-47.9%25-red.svg?style=flat) |

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

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

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

## 如何运作

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

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

## 为什么用闪存贷款?

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

## 安装

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

你还需要交易SDK:

```bash
npm install @cowprotocol/sdk-trading
```

## 设置

你需要的就是: 爱丽丝

-   `chainId` - 支持链式ID(见 [SDK 配置](https://docs.cow.fi/cow-protocol/reference/sdks/core-utilities/sdk-config)(中文(简体) )
-   `appCode` - 跟踪命令的专用应用程序标识符
-   `signer` - 私人钥匙、醚签字器或 `Eip1193` 提供者
-   `TradingSdk` 例如 -- -- 获得报价和张贴命令

## 使用量

### 基本担保交换

```typescript
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)
```

### 带引文评论的高级使用

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

```typescript
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` 参数

**示例**

```typescript
// 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),即:

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

### 关于克诺斯链的普通指针

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

### 用法示例

```typescript
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()` 必要时自动检查和批准担保品:

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

### 手动核准并获得担保担保

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

```typescript
// 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的标志,您可以使用许可证进行无气批准:

```typescript
// 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` 在贸易参数中:

```typescript
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 时设定自定义默认 :

```typescript
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自动配置并估算出气体.

## 处理错误

常见错误和解决方案:

**短期贷款数额不足**

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

**滑过紧**

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

**命令已过期**

```typescript
// 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%)
-   受《化学武器议定书》限制
-   需要部署网络专用合同

## 安全考虑

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

## 资源

-   [Aave 闪存贷款文档](https://docs.aave.com/developers/guides/flash-loans)
-   [COW 协议文档](https://docs.cow.fi/)
-   [COW 协议钩](https://docs.cow.fi/cow-protocol/reference/core/intents/hooks)
-   [EIP-1271 规格](https://eips.ethereum.org/EIPS/eip-1271)

## 常见问题

### @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 和提交记录判断。