# @defindex/sdk 中文文档

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

版本：0\.3\.0
npm 元数据更新时间：2026-09-09T12:28:18.406Z
中文译文更新时间：2026-11-11T20:57:47.910Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40defindex/sdk
原文对照：https://npmcn.com/package/%40defindex/sdk/?lang=original
项目主页：https://defindex.io/
源码仓库：https://github.com/paltalabs/defindex-sdk

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

- 包体积（解压后）：108 kB，42 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16\.0\.0
- 运行依赖：1 个
- 首次发布：2025-07-29T21:25:11.566Z
- 最新版本发布：2026-04-08T18:31:46.895Z
- 近 30 天下载量：3709（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 6 个）

## 中文简介

DeFindex API 的官方类型SDK脚本

## 安装

```sh
npm install @defindex/sdk
```

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

## README

# DeFindex SDK 数据存储器

[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/defindex/sdk) [![npm version](https://img.shields.io/npm/v/@defindex/sdk)](https://www.npmjs.com/package/@defindex/sdk) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

正式类型SDK [数据索引](https://defindex.io/) - 利用索罗班智能合同在斯特拉尔上建立的分散式金库管理系统.

## \* 特性

-   **API 密钥认证**: 安全 API 有 Bearer 令牌的密钥认证( 建议)
-   **\*** : 创建、保存、提取和管理分散式金库
-   **工厂业务**: 使用自定义配置的新金库
-   **管理操作**:紧急救援,金库操作员战略管理
-   **实时数据**:缺损余额、APY跟踪和综合金库信息
-   **QQ 服务器焦点**:安全处理全权证书和敏感业务
-   **QQ 类型脚本支持**: 具有全面接口的完整类型安全
-   **轻型**: 简单认证和全面处理错误
-   **QQ 测试良好**: 综合单位和综合测试覆盖率
-   **完整实例**: 功能类型脚本示例和综合文档

## \* 安装

```bash
pnpm install @defindex/sdk
```

## QQ 快速启动

```typescript
import { DefindexSDK, SupportedNetworks } from '@defindex/sdk';

// Initialize with API key
const sdk = new DefindexSDK({
  apiKey: 'sk_your_api_key_here',
  baseUrl: 'https://api.defindex.io'
});

// Check API health
const health = await sdk.healthCheck();
console.log('API Status:', health.status.reachable);

// Get factory address
const factory = await sdk.getFactoryAddress(SupportedNetworks.TESTNET);
console.log('Factory Address:', factory.address);

// Get vault information
const vaultAddress = 'CVAULT_CONTRACT_ADDRESS...';
const vaultInfo = await sdk.getVaultInfo(vaultAddress, SupportedNetworks.TESTNET);
console.log(`Vault: ${vaultInfo.name} (${vaultInfo.symbol})`);

// Deposit to vault
const depositResponse = await sdk.depositToVault(vaultAddress, {
  amounts: [1000000], // Amount for each asset (considering decimals)
  caller: 'GUSER_ADDRESS...',
  invest: true,
  slippageBps: 100 // 1% slippage tolerance
}, SupportedNetworks.TESTNET);

// Sign the XDR with your wallet and submit
const signedXdr = await yourWallet.sign(depositResponse.xdr);
const result = await sdk.sendTransaction(signedXdr, SupportedNetworks.TESTNET);
```

## QQ 运行示例

SDK包括一个全面的功能实例:

```bash
# Install dependencies
pnpm install

# Copy environment configuration
cp .env.example .env

# Edit .env with your credentials
# DEFINDEX_API_KEY=sk_your_api_key_here

# Run the example
pnpm run example
```

该实例表明:

-   SDK 初始化和认证
-   API 健康检查
-   工厂业务
-   地产、存款和提款
-   行政金库管理
-   处理错误和最佳做法

## QQ 配置

### SDK 配置选项

```typescript
interface DefindexSDKConfig {
  apiKey?: string;         // API key for authentication (recommended)
  baseUrl?: string;        // Custom API base URL (defaults to 'https://api.defindex.io')
  timeout?: number;        // Request timeout in ms (defaults to 30000)
}
```

### 环境变量

为了更好的安全,使用环境变量:

```typescript
// Using API key (recommended)
const sdk = new DefindexSDK({
  apiKey: process.env.DEFINDEX_API_KEY,
  baseUrl: process.env.DEFINDEX_API_URL || 'https://api.defindex.io'
});
```

## 现状

**大新闻!** DeFindex API现已在测试网全面运行:

-   ✅ **健康检查**: 工作正确
-   ✅ **SDK 认证**: 已执行 API 密钥认证
-   ✅ **工厂业务**: 安装测试网的工厂
-   ✅ **默认创建**: 创建自定义配置的金库
-   ✅ **默认操作**:全额存款、提取和结余业务
-   ✅ **断层管理**行政业务(暂停/不暂停战略、紧急救援)
-   ✅ **交易大楼**: 所有操作返回签名的 XDR 钱包集成
-   ⚠️ **PY 计算**: 正在工作, 但有些字段可能无法定义新金库

### 最近更新

1.  ✅ **已部署工厂**: 工厂合同现已通过测试网提供
2.  ✅ **完整默认操作**: 创建、管理和与金库互动
3.  ✅ **完整示例**运行 `pnpm run example` 查看所有功能
4.  ✅ **准备生产**: 所有核心功能已开始运作

## API 参考

### 系统操作

#### 健康检查

```typescript
const health = await sdk.healthCheck();
if (health.status.reachable) {
  console.log('API is healthy');
}
```

### 工厂业务

#### 获取工厂地址

```typescript
const factory = await sdk.getFactoryAddress(SupportedNetworks.TESTNET);
console.log('Factory address:', factory.address);
```

#### 创建默认

```typescript
const vaultConfig: CreateVaultParams = {
  roles: {
    emergencyManager: "GEMERGENCY_MANAGER_ADDRESS...",
    feeReceiver: "GFEE_RECEIVER_ADDRESS...",
    manager: "GVAULT_MANAGER_ADDRESS...",
    rebalanceManager: "GREBALANCE_MANAGER_ADDRESS..."
  },
  vaultFeeBps: 100, // 1% fee
  assets: [{
    address: "CXLM_CONTRACT_ADDRESS...",
    strategies: [{
      address: "GSTRATEGY_CONTRACT_ADDRESS...",
      name: "XLM Strategy",
      paused: false
    }]
  }],
  name: "My DeFi Vault",
  symbol: "MDV",
  upgradable: true,
  caller: "GCREATOR_ADDRESS..."
};

const response = await sdk.createVault(vaultConfig, SupportedNetworks.TESTNET);
console.log('Vault XDR:', response.xdr);
```

### 默认操作

#### 获取默认信息

```typescript
const vaultInfo = await sdk.getVaultInfo(vaultAddress, SupportedNetworks.TESTNET);
console.log(`Total Assets: ${vaultInfo.totalAssets}`);
console.log(`Vault Fee: ${vaultInfo.feesBps.vaultFee / 100}%`);
```

#### 获取默认余额

```typescript
const balance = await sdk.getVaultBalance(
  vaultAddress, 
  userAddress, 
  SupportedNetworks.TESTNET
);
console.log(`Vault Shares: ${balance.dfTokens}`);
```

#### 存到地窖

```typescript
const depositResponse = await sdk.depositToVault(vaultAddress, {
  amounts: [1000000, 2000000],
  caller: 'GUSER_ADDRESS...',
  invest: true,
  slippageBps: 100
}, SupportedNetworks.TESTNET);
```

#### 从地窖撤回

```typescript
// Withdraw specific amounts
const withdrawResponse = await sdk.withdrawFromVault(vaultAddress, {
  amounts: [500000, 1000000],
  caller: 'GUSER_ADDRESS...',
  slippageBps: 100
}, SupportedNetworks.TESTNET);

// Withdraw by shares
const shareResponse = await sdk.withdrawShares(vaultAddress, {
  shares: 1000000,
  caller: 'GUSER_ADDRESS...',
  slippageBps: 100
}, SupportedNetworks.TESTNET);
```

#### 获取 Vault APY

```typescript
const apy = await sdk.getVaultAPY(vaultAddress, SupportedNetworks.TESTNET);
console.log(`Current APY: ${apy.apyPercent}%`);
```

### 地壳管理(阿明业务)

#### 紧急救援

```typescript
// Requires Emergency Manager role
const response = await sdk.emergencyRescue(vaultAddress, {
  strategy_address: 'GSTRATEGY_TO_RESCUE...',
  caller: 'GEMERGENCY_MANAGER_ADDRESS...'
}, SupportedNetworks.TESTNET);
```

#### 暂停/不暂停战略

```typescript
// Requires Strategy Manager role
await sdk.pauseStrategy(vaultAddress, {
  strategy_address: 'GSTRATEGY_TO_PAUSE...',
  caller: 'GSTRATEGY_MANAGER_ADDRESS...'
}, SupportedNetworks.TESTNET);

await sdk.unpauseStrategy(vaultAddress, {
  strategy_address: 'GSTRATEGY_TO_UNPAUSE...',
  caller: 'GSTRATEGY_MANAGER_ADDRESS...'
}, SupportedNetworks.TESTNET);
```

### 交易管理

#### 发送交易

```typescript
// Submit signed transaction to the Stellar network
const response = await sdk.sendTransaction(
  signedXDR,
  SupportedNetworks.TESTNET
);
```

### 系统操作

#### 健康检查

```typescript
const health = await sdk.healthCheck();
if (health.status.reachable) {
  console.log('API is healthy');
}
```

## 安保最佳做法

1.  **环境变量**: 在环境变量中而不是在代码中存储证书
2.  **仅服务器**: 此 SDK 仅供服务器侧使用
3.  **证书安全**: 保证证书安全, 绝不将其投入版本控制
4.  **处理错误**: 总是将 API 调用在尝试捕获块中
5.  **托肯管理**: 对长期运行的应用程序使用刷新符号

```typescript
try {
  const vaultInfo = await sdk.getVaultInfo(vaultAddress, network);
  // Handle success
} catch (error) {
  console.error('Operation failed:', error.message);
  // Handle error appropriately
}
```

## 空洞管理角色

SDK支持不同的操作角色:

-   **故障管理员**: 可以创建和配置金库
-   **应急管理人员**: 可以执行紧急救援
-   **战略管理员**: 能够暂停/停止个别战略
-   **普通用户**: 可以保存、提取和查看金库信息

## 发展

### 大楼

```bash
pnpm run build
```

### 测试

#### 单位测试( 混合)

```bash
# Run unit tests
pnpm test

# Run with coverage
pnpm run test:coverage

# Watch mode
pnpm run test:watch

# Run integration tests
pnpm run test:integration

# Run all tests
pnpm run test:all
```

### 代码质量

```bash
pnpm run lint
pnpm run lint:fix
```

## 定义类型

SDK 输出全面的类型脚本类型 :

```typescript
import {
  DefindexSDK,
  DefindexSDKConfig,
  SupportedNetworks,
  CreateVaultParams,
  DepositParams,
  WithdrawParams,
  WithdrawSharesParams,
  VaultInfo,
  VaultBalance,
  VaultAPY,
  // ... and many more
} from '@defindex/sdk';
```

## 前端整合

在服务器侧重心的同时,您可以创建安全的前端集成:

```typescript
// Backend API endpoint using API key
app.post('/api/vault-info', async (req, res) => {
  try {
    const sdk = new DefindexSDK({
      apiKey: process.env.DEFINDEX_API_KEY
    });
    
    const vaultInfo = await sdk.getVaultInfo(req.body.vaultAddress, req.body.network);
    res.json(vaultInfo);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});
```

## 页:1

综合实例和详细的API文件见:

-   [实例/基本实例](https://npmcn.com/package/%40defindex/sdk/examples/basic-example.ts) - 完整的功能实例
-   [缩略语.md](https://npmcn.com/package/%40defindex/sdk/EXAMPLES.md) - 综合使用实例
-   [文件/索引文件](https://npmcn.com/package/%40defindex/sdk/docs/defindex-sdk-docs.md) - 完成SDK文档
-   [克劳德·姆德](https://npmcn.com/package/%40defindex/sdk/CLAUDE.md) - 发展指导和结构说明
-   [API 文档](https://api.defindex.io/) - 完整的API参考文献

## 链接

-   [数据索引](https://defindex.io/)
-   [GitHub 仓库](https://github.com/paltalabs/defindex-sdk)

* * *

由帕尔塔拉布斯队与QQ共同建造.

## 常见问题

### @defindex/sdk 是什么？

DeFindex API 的官方类型SDK脚本

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

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

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

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

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

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

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

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

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

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

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

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

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

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