# @1inch/aqua-sdk 中文文档

规范地址：https://npmcn.com/package/%401inch/aqua-sdk/

版本：0\.4\.0
npm 元数据更新时间：2026-11-05T09:56:40.278Z
中文译文更新时间：2026-11-06T08:22:28.243Z
软件包许可：LicenseRef-Degensoft-Aqua-Source-1\.1

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

原始 npm 页面：https://www.npmjs.com/package/%401inch/aqua-sdk
原文对照：https://npmcn.com/package/%401inch/aqua-sdk/?lang=original
项目主页：https://github.com/1inch/sdks#readme
源码仓库：https://github.com/1inch/sdks

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

- 包体积（解压后）：329 kB，43 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2025-11-17T11:28:41.472Z
- 最新版本发布：2026-11-05T09:56:39.843Z
- 近 30 天下载量：3881（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

1英寸水协议SDK

## 安装

```sh
npm install @1inch/aqua-sdk
```

也可以使用：`pnpm add @1inch/aqua-sdk`、`yarn add @1inch/aqua-sdk`、`bun add @1inch/aqua-sdk`

## README

# @ 1英寸/ aqua- sdk - 1英寸水协议的 SDK 类型

一个TypeScript SDK,用于编码,解码,并与一英寸水协议智能合同互动. 这个SDK为水议定书核心业务的建筑交易和剖析活动提供公用事业.

## 概览

《水议定书》是流动资金管理的分权议定书。 这种SDK通过提供:

-   **编码/解码**: 构建打入的呼叫数据 `ship`, (中文(简体) ), `dock` 业务
-   **事件分析**: 解码和解析 `Pushed`, (中文(简体) ), `Pulled`, (中文(简体) ), `Shipped`,以及 `Docked` 事件
-   **多钱支持**: 10+区块链网络的预配置地址

关于详细的礼宾文件,请参看 [水议定书文件](https://github.com/1inch/aqua#table-of-contents)。 。 。 .

## 安装

```bash
pnpm add @1inch/aqua-sdk
```

## 快速启动

```typescript
import {
  AquaProtocolContract,
  AQUA_CONTRACT_ADDRESSES,
  Address,
  HexString,
  NetworkEnum
} from '@1inch/aqua-sdk'

// Initialize the contract
const contractAddress = AQUA_CONTRACT_ADDRESSES[NetworkEnum.ETHEREUM]
const aqua = new AquaProtocolContract(contractAddress)

// Build a ship transaction
const shipTx = aqua.ship({
  app: new Address('0x...'),
  strategy: new HexString('0x...'),
  amountsAndTokens: [
    {
      token: new Address('0x...'),
      amount: 1000000000000000000n, // 1 token with 18 decimals
    },
  ],
})

// Use the transaction data
console.log(shipTx) // { to: '0x...', data: '0x...', value: 0n }
```

## 核心业务

### 船舶

启动流动性战略,为此设定虚拟代号余额.

```typescript
const shipTx = aqua.ship({
  app: new Address('0x...'),
  strategy: new HexString('0x...'),
  amountsAndTokens: [
    {
      token: new Address('0x...'),
      amount: 1000000000000000000n,
    },
  ],
})
```

**参数:**

-   `app` - 申请合同地址
-   `strategy` - 包含执行逻辑的战略字节
-   `amountsAndTokens` - 象征性地址和金额

**回返情况:** `CallInfo` 带有编码交易数据的对象

### 锁定

完成流动性策略,从中去除虚拟符号余额.

```typescript
const strategyHash = AquaProtocolContract.calculateStrategyHash(strategy)

const dockTx = aqua.dock({
  app: new Address('0x...'),
  strategyHash: strategyHash,
  tokens: [
    new Address('0x...'),
    new Address('0x...'),
  ],
})
```

**参数:**

-   `app` - 申请合同地址
-   `strategyHash` - 战略字节的克恰克256散列
-   `tokens` - 战略所有象征性地址的组合,其虚拟余额被设定为零

**回返情况:** `CallInfo` 带有编码交易数据的对象

## 事件分析

### 推动事件

将资金投入战略/Wallet时予以发放.

```typescript
import { PushedEvent } from '@1inch/aqua-sdk'

const log = { data: '0x...', topics: ['0x...'] }
const event = PushedEvent.fromLog(log)

console.log(event.maker)        // Address
console.log(event.app)          // Address
console.log(event.strategyHash) // HexString
console.log(event.token)        // Address
console.log(event.amount)       // bigint
```

### 拉动事件

在从战略/Wallet中提取资金时发放.

```typescript
import { PulledEvent } from '@1inch/aqua-sdk'

const event = PulledEvent.fromLog(log)
```

### 运输事件

在启动流动资金战略时予以释放.

```typescript
import { ShippedEvent } from '@1inch/aqua-sdk'

const event = ShippedEvent.fromLog(log)
```

### 锁定事件

当流动性战略结束时,即予释放.

```typescript
import { DockedEvent } from '@1inch/aqua-sdk'

const event = DockedEvent.fromLog(log)
```

## 工具函数

### 计算策略散列

将策略字节转换为它们的克恰克256散列.

```typescript
import { AquaProtocolContract } from '@1inch/aqua-sdk'
import { HexString } from '@1inch/sdk-core'

const strategy = new HexString('0x...')
const hash = AquaProtocolContract.calculateStrategyHash(strategy)
```

### 编码调用数据

需要时手动编码函数调用数据 .

```typescript
import { AquaProtocolContract } from '@1inch/aqua-sdk'

const encodedShip = AquaProtocolContract.encodeShipCallData({
  app: new Address('0x...'),
  strategy: new HexString('0x...'),
  amountsAndTokens: [ /* ... */ ],
})

const encodedDock = AquaProtocolContract.encodeDockCallData({
  app: new Address('0x...'),
  strategyHash: new HexString('0x...'),
  tokens: [ /* ... */ ],
})
```

## 支持的网络

SDK包括以下网络的预配置合同地址:

| 网络 | 链式标识 | 地址 |
| --- | --- | --- |
| 以利亚 | 1个 | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://etherscan.io/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| BNB 链条 | 页:1 | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://bscscan.com/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| 多边形 | 137国 | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://polygonscan.com/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| 坐标 | 42161 (韩语) | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://arbiscan.io/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| 雪崩 | 第43114号 | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](http://snowscan.xyz/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| 肠道 | 100个 | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://gnosisscan.io/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| 基地 | 8453 (英语) | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://basescan.org/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| 乐观主义 | 10个 | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://optimistic.etherscan.io/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| zk同步时代 | 324国道 | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://era.zksync.network/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| 线性a | 第59144号 | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://lineascan.build/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| 单链 | 130个 | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://uniscan.xyz/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| 音响 | 146 (中文(简体) ) | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://sonicscan.org/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| 罗宾链 | 第4663条 | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://robinhoodchain.blockscout.com/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| 修道院 | 143国 | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://monadscan.com/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| 克罗诺斯 | 第25条 | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://explorer.cronos.com/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| 超高频 | 999号 | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://hyperevmscan.io/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |
| 弧形 | 5042 (简体中文) | [0x1111113ccf1426a8e30e2bff5e005d929bf6a90a (中文(简体) )](https://explorer.arc.io/address/0x1111113ccf1426a8e30e2bff5e005d929bf6a90a) |

访问地址使用 :

```typescript
import { AQUA_CONTRACT_ADDRESSES } from '@1inch/aqua-sdk'
import { NetworkEnum } from '@1inch/sdk-core'

const ethereumAddress = AQUA_CONTRACT_ADDRESSES[NetworkEnum.ETHEREUM]
const arbitrumAddress = AQUA_CONTRACT_ADDRESSES[NetworkEnum.ARBITRUM]
```

## API 参考

### 出口

SDK出口:

-   **[`AquaProtocolContract`](https://npmcn.com/package/%401inch/aqua-sdk/src/aqua-protocol-contract/aqua-protocol-contract.ts)** - 编码、解码和建筑物交易的主要合同类别
-   **[`AQUA_CONTRACT_ADDRESSES`](https://npmcn.com/package/%401inch/aqua-sdk/src/aqua-protocol-contract/constants.ts)** - 按网络预配置的合同地址
-   **[`ABI`](https://npmcn.com/package/%401inch/aqua-sdk/src/abi/)** - ABI合同出口
-   **[类型](https://npmcn.com/package/%401inch/aqua-sdk/src/aqua-protocol-contract/types.ts)**数字 :
    -   `ShipArgs`
    -   `DockArgs`
    -   `AmountsAndTokens`
    -   `EventAction`
-   **[活动类别](https://npmcn.com/package/%401inch/aqua-sdk/src/aqua-protocol-contract/events/)**数字 :
    -   `PushedEvent`
    -   `PulledEvent`
    -   `ShippedEvent`
    -   `DockedEvent`

## 现实生活实例

### 实例1:船舶流动性 [XYCWAP.sol (英语)](https://github.com/1inch/aqua/blob/0637013a51cd56851f7b143a1f4500fdc93726cc/src/apps/XYCSwap.sol) aqua 应用

启动流动性战略,在Aqua设定其虚拟余额. `ship` 不转移指使符:它们留在制作人的钱包里,水叮当用它拉出 `transferFrom` 当交换执行时,所以制作者必须持有符文并批准水上公司合同,以花费每个符文.

```typescript
import { AquaProtocolContract, Address, HexString, AQUA_CONTRACT_ADDRESSES, NetworkEnum } from '@1inch/aqua-sdk'
import { encodeAbiParameters, parseUnits, http, createWalletClient, isHex, erc20Abi, maxUint256 } from 'viem'
import { privateKeyToAccount, privateKeyToAddress } from 'viem/accounts'
import { mainnet } from 'viem/chains'
import assert from 'assert'
import 'dotenv/config'

const makerPrivateKey = process.env.MAKER_PRIVATE_KEY

assert(isHex(makerPrivateKey))
const maker = privateKeyToAddress(makerPrivateKey)
const app = '0xTODO_REPLACE'
const WETH = '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'
const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'

// Define strategy based on the smart contract app structure. Each Aqua app can have it's own strategy schema
const strategyData = {
  maker,
  token0: WETH,
  token1: USDC,
  feeBps: 0n,
  salt: '0x0000000000000000000000000000000000000000000000000000000000000001'
} as const

// Encode strategy as bytes
const strategy = encodeAbiParameters(
  [
    {
      name: 'strategy',
      type: 'tuple',
      components: [
        { name: 'maker', type: 'address' },
        { name: 'token0', type: 'address' },
        { name: 'token1', type: 'address' },
        { name: 'feeBps', type: 'uint256' },
        { name: 'salt', type: 'bytes32' }
      ]
    }
  ],
  [strategyData]
)

console.log('Encoded strategy:', strategy)

// Initialize Aqua contract
const aqua = new AquaProtocolContract(AQUA_CONTRACT_ADDRESSES[NetworkEnum.ETHEREUM])

// Create ship transaction
const shipTx = aqua.ship({
  app: new Address(app),
  strategy: new HexString(strategy),
  amountsAndTokens: [
    {
      token: new Address(USDC),
      amount: parseUnits('4000', 6)
    },
    {
      token: new Address(WETH),
      amount: parseUnits('1', 18)
    }
  ]
})

const wallet = createWalletClient({
  chain: mainnet,
  transport: http(),
  account: privateKeyToAccount(makerPrivateKey)
})

// Aqua pulls the tokens from the maker's wallet when swaps execute, so it needs an allowance
for (const token of [USDC, WETH] as const) {
  await wallet.writeContract({
    address: token,
    abi: erc20Abi,
    functionName: 'approve',
    args: [aqua.address.toString(), maxUint256]
  })
}

// Send transaction
await wallet.sendTransaction(shipTx)
```

**完整测试示例 :** [试验/aqua. spec.ts -- -- 应发货](https://github.com/1inch/sdks/blob/master/typescript/aqua/tests/aqua.spec.ts#L27)

### 例2:通过交换执行 [XYCWAP.sol (英语)](https://github.com/1inch/aqua/blob/0637013a51cd56851f7b143a1f4500fdc93726cc/src/apps/XYCSwap.sol) aqua 应用

与水口公司提供的流动性进行互换. [测试器. sol](https://github.com/1inch/sdks/blob/0a276af00b91b287cc4c4f04402c44e02afffa44/contracts/src/aqua/TestTrader.sol#L7) 帮助者合同被用作批准持有人和路由器.

```typescript
import {
  parseUnits,
  http,
  createWalletClient,
  isHex,
  encodeFunctionData,
  decodeAbiParameters,
  publicActions
} from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'
import assert from 'assert'
import 'dotenv/config'

const takerPrivateKey = process.env.TAKER_PRIVATE_KEY

assert(isHex(takerPrivateKey))
const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
const app = '0xTODOReplace'
const routerAddress = '0xTestTraderAddress'

const strategy = '0x' // parsed from ship events or fetched from api

// Send transaction
const wallet = createWalletClient({
  chain: mainnet,
  transport: http(),
  account: privateKeyToAccount(takerPrivateKey)
}).extend(publicActions)

// decode data based on specified by app format
const [strategyData] = decodeAbiParameters(
  [
    {
      type: 'tuple',
      components: [
        { name: 'maker', type: 'address' },
        { name: 'token0', type: 'address' },
        { name: 'token1', type: 'address' },
        { name: 'feeBps', type: 'uint256' },
        { name: 'salt', type: 'bytes32' }
      ]
    }
  ],
  strategy
)

// Define swap parameters
const srcAmount = parseUnits('10', 6) // 10 USDC
const srcToken = USDC
const isZeroForOne = strategyData.token0 === srcToken

// Encode the swap call to helper Router contract
const swapData = encodeFunctionData({
  abi: [
    {
      type: 'function',
      name: 'swap',
      inputs: [
        {
          name: 'app',
          type: 'address'
        },
        {
          name: 'strategy',
          type: 'tuple',
          components: [
            { name: 'maker', type: 'address' },
            { name: 'token0', type: 'address' },
            { name: 'token1', type: 'address' },
            { name: 'feeBps', type: 'uint256' },
            { name: 'salt', type: 'bytes32' }
          ]
        },
        { name: 'zeroForOne', type: 'bool' },
        { name: 'amountIn', type: 'uint256' }
      ],
      outputs: [{ name: 'amountOut', type: 'uint256' }],
      stateMutability: 'nonpayable'
    }
  ],
  functionName: 'swap',
  args: [app, strategyData, isZeroForOne, srcAmount]
})

// give erc20 approve to routerAddress
await wallet.writeContract({
  abi: [
    {
      type: 'function',
      name: 'approve',
      inputs: [
        { name: 'spender', type: 'address', internalType: 'address' },
        { name: 'value', type: 'uint256', internalType: 'uint256' }
      ],
      outputs: [{ name: '', type: 'bool', internalType: 'bool' }],
      stateMutability: 'nonpayable'
    }
  ],
  address: srcToken,
  account: wallet.account,
  functionName: 'approve',
  chain: wallet.chain,
  args: [routerAddress, srcAmount]
})

// Execute swap
const swapTx = await wallet.sendTransaction({
  to: routerAddress,
  data: swapData
})

await wallet.waitForTransactionReceipt({ hash: swapTx })
```

**完整测试示例 :** [测试/aqua. spec.ts - 应互换](https://github.com/1inch/sdks/blob/master/typescript/aqua/tests/aqua.spec.ts#L142)

### 例3:码头流动性

关闭策略, 将其虚拟余额设置为 0 . `dock` 不传输令牌:它们已经在制作者的钱包中.

```typescript
import { AquaProtocolContract, Address, HexString, AQUA_CONTRACT_ADDRESSES, NetworkEnum } from '@1inch/aqua-sdk'
import { http, createWalletClient, isHex } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { mainnet } from 'viem/chains'
import assert from 'assert'
import 'dotenv/config'

const makerPrivateKey = process.env.MAKER_PRIVATE_KEY

assert(isHex(makerPrivateKey))
const app = '0xTODO_REPLACE'
const WETH = '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'
const USDC = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'

const strategy = '0x' // parsed from ship events or fetched from api

// Initialize Aqua contract
const aqua = new AquaProtocolContract(AQUA_CONTRACT_ADDRESSES[NetworkEnum.ETHEREUM])

// Create dock transaction
const dockTx = aqua.dock({
  app: new Address(app),
  strategyHash: AquaProtocolContract.calculateStrategyHash(new HexString(strategy)),
  tokens: [new Address(USDC), new Address(WETH)]
})

// Send transaction
const wallet = createWalletClient({
  chain: mainnet,
  transport: http(),
  account: privateKeyToAccount(makerPrivateKey)
})

await wallet.sendTransaction(dockTx)

// After the transaction is confirmed, the strategy's virtual balances are zero
// and the strategy is closed
```

**完整测试示例 :** [试验/aqua. spec.ts - 应停靠](https://github.com/1inch/sdks/blob/master/typescript/aqua/tests/aqua.spec.ts#L320)

## 许可证

该SDK是根据下列条款提供的: [自由主义](https://npmcn.com/package/%401inch/aqua-sdk/LICENSE) 财务报告和审定财务报表 [第三层( P)](https://npmcn.com/package/%401inch/aqua-sdk/THIRD_PARTY_NOTICES)。 。 。 .

任何许可证发放问题或申请,请联系:

-   [许可证@ degensoft.com](mailto:license@degensoft.com)
-   [法律@ degensoft.com](mailto:legal@degensoft.com)

## 常见问题

### @1inch/aqua-sdk 是什么？

1英寸水协议SDK

### 如何安装 @1inch/aqua-sdk？

在项目目录运行 npm install @1inch/aqua-sdk，或使用 pnpm add / yarn add / bun add。

### @1inch/aqua-sdk 支持 TypeScript 吗？

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

### @1inch/aqua-sdk 支持 ESM 还是 CommonJS？

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

### @1inch/aqua-sdk 可以商用吗？

@1inch/aqua-sdk 使用 LicenseRef-Degensoft-Aqua-Source-1\.1 许可。声明的许可为 LicenseRef-Degensoft-Aqua-Source-1\.1，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @1inch/aqua-sdk 的下载量有多少？

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

### @1inch/aqua-sdk 还在维护吗？

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