# @centrifuge/sdk 中文文档

规范地址：https://npmcn.com/package/%40centrifuge/sdk/

版本：2\.10\.0
npm 元数据更新时间：2026-11-05T16:14:00.552Z
中文译文更新时间：2026-11-09T12:26:17.708Z
软件包许可：LGPL-3\.0-only

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

原始 npm 页面：https://www.npmjs.com/package/%40centrifuge/sdk
原文对照：https://npmcn.com/package/%40centrifuge/sdk/?lang=original
项目主页：https://github.com/centrifuge/sdk/tree/main#readme
源码仓库：https://github.com/centrifuge/sdk

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

- 包体积（解压后）：4.2 MB，623 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.18
- 运行依赖：6 个
- 首次发布：2024-12-03T11:40:29.958Z
- 最新版本发布：2026-11-05T16:14:00.229Z
- 近 30 天下载量：2755（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：254（近 12 个月 148 个）

## 中文简介

一个完全输入的 JavaScript 客户端可以与该客户端交互 [离心器](https://centrifuge.io/) 生态系统。 用它来管理集合,投资,赎回,财务报告等等.

## 安装

```sh
npm install @centrifuge/sdk
```

也可以使用：`pnpm add @centrifuge/sdk`、`yarn add @centrifuge/sdk`、`bun add @centrifuge/sdk`

## README

# 离心式 SDK [![Codecov](https://codecov.io/gh/centrifuge/sdk/graph/badge.svg?token=Q2yU8QfefP)](https://codecov.io/gh/centrifuge/sdk) [![Build CI status](https://github.com/centrifuge/sdk/actions/workflows/build-test-report.yml/badge.svg)](https://github.com/centrifuge/sdk/actions/workflows/build-test-report.yml) [![Latest Release](https://img.shields.io/github/v/release/centrifuge/sdk?sort=semver)](https://github.com/centrifuge/sdk/releases/latest)

一个完全输入的 JavaScript 客户端可以与该客户端交互 [离心器](https://centrifuge.io/) 生态系统。 用它来管理集合,投资,赎回,财务报告等等.

* * *

## 目录

1.  [特征](https://npmcn.com/package/%40centrifuge/sdk/#readme-features)
2.  [安装](https://npmcn.com/package/%40centrifuge/sdk/#readme-installation)
3.  [开始](https://npmcn.com/package/%40centrifuge/sdk/#readme-getting-started)
    -   [初始化配置( C)](https://npmcn.com/package/%40centrifuge/sdk/#readme-initialization--configuration)
    -   [查询](https://npmcn.com/package/%40centrifuge/sdk/#readme-queries)
    -   [交易](https://npmcn.com/package/%40centrifuge/sdk/#readme-transactions)
    -   [投资](https://npmcn.com/package/%40centrifuge/sdk/#readme-investments)
    -   [报告](https://npmcn.com/package/%40centrifuge/sdk/#readme-reports)
4.  [开发者指南](https://npmcn.com/package/%40centrifuge/sdk/#readme-developer-guide)
    -   [发展模式](https://npmcn.com/package/%40centrifuge/sdk/#readme-development-mode)
    -   [大楼](https://npmcn.com/package/%40centrifuge/sdk/#readme-building)
    -   [测试](https://npmcn.com/package/%40centrifuge/sdk/#readme-testing)
    -   [调试](https://npmcn.com/package/%40centrifuge/sdk/#readme-debugging)
5.  [捐款](https://npmcn.com/package/%40centrifuge/sdk/#readme-contributing)
    -   [文档](https://npmcn.com/package/%40centrifuge/sdk/#readme-docs)
    -   [PR 公约和版本](https://npmcn.com/package/%40centrifuge/sdk/#readme-pr-naming-convention--versioning)
6.  [许可证](https://npmcn.com/package/%40centrifuge/sdk/#readme-license)

* * *

## 特征

-   已键入 JavaScript/ TypeScript 客户端
-   支持主网和测试网环境
-   完整查询接口( 只读) + 订阅支持
-   交易支持(等待或可观察更新)
-   处理股票类、金库和ERC-7540象征性金库
-   报表:资产负债表、损益、现金流量

* * *

## 安装

```bash
npm install @centrifuge/sdk
```

## 开始

### 初始化配置( C)

```typescript
import Centrifuge from '@centrifuge/sdk'

const centrifuge = new Centrifuge({
  environment: 'mainnet' | 'testnet',         // optional, defaults to 'mainnet'
  rpcUrls?: { [chainId: number]: string },     // optional RPC endpoints
  indexerUrl?: string,                         // optional indexer API URL
  ipfsUrl?: string                             // optional IPFS gateway, default: https://centrifuge-files.mypinata.cloud
})
```

### 查询

查询返回可观测值(rxjs),可以是:

-   等待(一个值),或
-   已订阅( 当链上数据变化时接收更新)

```typescript
const pools = await centrifuge.pools()

// Or subscribe
const subscription = centrifuge.pools().subscribe(
  (pools) => console.log(pools),
  (error) => console.error(error)
)

// Later, to stop updates:
subscription.unsubscribe()
```

### 交易

-   在调用交易方法之前,在离心机实例上设置一个签名符.
-   签名者可以是:
    -   EIP-1193兼容供应商
    -   Viem 本地账户
-   交易和查询一样,支持等待完成或签署状态更新.

```typescript
centrifuge.setSigner(signer)
const poolId = PoolId.from(1, 1)
const pool = await centrifuge.pool(poolId)
const tx = await pool.updatePoolManagers([
  {
    address: '0xAddress',
    canManage: true,
  },
])
console.log(tx.hash)

// or, subscribe to transaction lifecycle:
const sub = pool.pool
  .updatePoolManagers([
    {
      address: '0xAddress',
      canManage: true,
    },
  ])
  .subscribe(
    (status) => console.log(status),
    (error) => console.error(error),
    () => console.log('Done')
  )
```

### 投资

SDK 支持 [ERC-7540 (中文(简体) )](https://eips.ethereum.org/EIPS/eip-7540) 象征性的金库。 每股分级,连锁,和货币,都会产生空档.

```typescript
const pool = await centrifuge.pool(poolId)
const scId = ShareClassId.from(poolId, 1)
const assetId = AssetId.from(centId, 1)
// Get a vault
const vault = await pool.vault(11155111, scId, assetId)
```

#### 默认类型

根据池的配置, 跳槽行为会有所不同 :

-   同步存款金库 这些金库采用ERC-4626和ERC-7540两种混合模型. 存款使用 ERC-4626 行为立即执行,允许用户立即接收股票. 然而,救赎通过ERC-7540同步处理,使用Hub来排队和管理取还请求.
    
-   同步金库 同步金库完全基于请求,并遵循ERC-7540标准. 它们允许通过同步工作流程处理存款和赎回行动,利用离心枢纽管理请求.
    

您可以查询个人投资者的状态:

```typescript
const inv = await vault.investment('0xInvestorAddress')

// Example returned fields include:
//   isAllowedToInvest
//   investmentCurrency, investmentCurrencyBalance, investmentCurrencyAllowance
//   shareCurrency, shareBalance
//   claimableInvestShares, claimableInvestCurrencyEquivalent
//   claimableRedeemCurrency, claimableRedeemSharesEquivalent
//   pendingInvestCurrency, pendingRedeemShares
//   hasPendingCancelInvestRequest, hasPendingCancelRedeemRequest
```

投资:

```typescript
const { investmentCurrency } = await vault.details()
const amount = Balance.fromFloat(1000, investmentCurrency.decimals)
const tx = await vault.increaseInvestOrder(amount)
console.log(result.hash)
```

任何可索赔的股票或货币一经处理,即可索赔:

```typescript
const claimResult = await vault.claim()
```

### 报告

您可以基于链式+API数据为集合生成财务报告.

可用报告类型 :

-   价 价 额

支持过滤 :

```typescript
type ReportFilter = {
  from?: string // e.g. '2024-01-01'
  to?: string // e.g. '2024-01-31'
  groupBy?: 'day' | 'month' | 'quarter' | 'year'
}

const fromNum = toUTCEpoch(filters.from, unit)
const toNum = toUTCEpoch(filters.to, unit)

const report = await pool.reports.sharePrices({
  from: fromNum,
  to: toNum,
  groupBy: 'day',
})
```

### 开发者指南

#### 发展模式

```bash
pnpm dev
```

#### 大楼

```bash
pnpm build
```

#### 测试

```bash
pnpm test                # full test suite
pnpm test:single <file>  # test specific file
pnpm test:simple:single <file>
# (runs faster excluding setup files)
```

#### 调试

该项目为在本地运行Indexer(api-v3)和Anvil叉(Foundry)提供了完全多克化的环境. 为准备您的测试环境进行链上调试, 首先设置调试脚本 :

`./src/debugIssues.mjs`

```javascript
// @ts-check

import { catchError, combineLatest, lastValueFrom, map, of, switchMap, tap } from 'rxjs'
import { parseAbiItem } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { AssetId, Balance, Centrifuge, PoolId, Price, ShareClass, ShareClassId } from './dist/index.js'

const abiItem = parseAbiItem('function balanceOf(address owner) view returns (uint256)')

const chainId = 1

const cent = new Centrifuge({
  environment: 'mainnet',
  pinJson: async () => 'test',
  rpcUrls: {
    1: 'http://127.0.0.1:8545',
  },
  inexerPollingInterval: 2000,
  indexerUrl: 'http://localhost:8000',
})

const account = privateKeyToAccount('0xPrivateKey')

cent.setSigner(account)

async function main() {
  const client = cent.getClient(centrifugeId)

  const pool = await cent.pool(new PoolId('PoolId'))
  const scId = new ShareClassId('0x00010000000000010000000000000001')
  const shareClass = new ShareClass(cent, pool, scId)
  const assetId = new AssetId('AssetId')

  const result = await shareClass.approveDepositsAndIssueShares([
    {
      assetId,
      approveAssetAmount: Balance.fromFloat(10, 6),
      issuePricePerShare: Price.fromFloat(1.0),
    },
  ])
}

main()
```

\* 警告 在运行调试脚本之前, 请评论您想要测试的交易, 如果您不想执行 . 记住在本地运行此脚本将执行与测试网或主网相同的交易逻辑. \* :

然后,建造和启动 Docker 容器:

```bash
docker compose up -d
```

完成后,将环境拆卸并删除相关量:

```bash
docker compose down -v
```

### 捐款

#### 文档

页:1 [文件存储库](https://github.com/centrifuge/documentation/tree/main/docs/developer/centrifuge-sdk)。 。 。 .

#### PR 命名公约和版本

公关标题和承诺应当遵循常规承诺风格.

使用语义化的版本:标记/放出应该是主要,次要,补丁之一.

如果不需要释放,则标为不释放.

### 许可证

该项目根据LGPL-3.0获得许可. 见 [自由主义](https://npmcn.com/package/%40centrifuge/sdk/LICENSE) 详细文件.

## 常见问题

### @centrifuge/sdk 是什么？

一个完全输入的 JavaScript 客户端可以与该客户端交互 离心器 生态系统。 用它来管理集合,投资,赎回,财务报告等等\.

### 如何安装 @centrifuge/sdk？

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

### @centrifuge/sdk 支持 TypeScript 吗？

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

### @centrifuge/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @centrifuge/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @centrifuge/sdk 可以商用吗？

@centrifuge/sdk 使用 LGPL-3\.0-only 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。

### @centrifuge/sdk 的下载量有多少？

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

### @centrifuge/sdk 还在维护吗？

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