# @augustdigital/sdk 中文文档

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

版本：9\.16\.0
npm 元数据更新时间：2026-10-28T14:18:54.960Z
中文译文更新时间：2026-11-07T04:47:03.707Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40augustdigital/sdk
原文对照：https://npmcn.com/package/%40augustdigital/sdk/?lang=original

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

- 包体积（解压后）：5.6 MB，346 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：13 个
- peer 依赖：viem ^2\.0\.0
- 首次发布：2024-06-27T21:00:54.633Z
- 最新版本发布：2026-10-28T14:18:54.688Z
- 近 30 天下载量：34708（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：534（近 12 个月 172 个）

## 中文简介

JS SDK为8月数字生态系统提供动力.

## 安装

```sh
npm install @augustdigital/sdk
```

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

## README

# 8月 数字 SDK

TypeScript SDK用于与August Digital金库交互,跨越EVM,索拉纳,斯特拉尔和Sui链.

## 安装

```bash
npm install @augustdigital/sdk ethers
# or
pnpm add @augustdigital/sdk ethers
# or
yarn add @augustdigital/sdk ethers
```

### 瓦格米/维姆支助

SDK既支持醚又支持wagmi/viem符号. 如果你在反应应用中使用wagmi, 也安装viem:

```bash
npm install viem
```

SDK 自动转换viem `WalletClient` 与醚兼容的符号.

## 快速启动

```typescript
import AugustSDK from '@augustdigital/sdk';

const sdk = new AugustSDK({
  // Required: stable kebab-case slug identifying your application.
  appName: 'acme-trader',
  providers: {
    1: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
    42161: 'https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY',
    -1: 'https://api.mainnet-beta.solana.com', // Solana
  },
  keys: {
    august: 'YOUR_API_KEY', // Optional: vault reads, allocations and vault-linked sub-account reads work without it
  },
  monitoring: {
    env: 'DEV', // Optional: 'DEV' enables console logging (defaults to 'PROD')
  },
});

// Fetch all vaults
const vaults = await sdk.getVaults();

// Fetch a specific vault with loans and allocations
const vault = await sdk.getVault({
  vault: '0x...',
  options: { loans: true, allocations: true },
});

// Get user positions
const positions = await sdk.getVaultPositions({
  wallet: '0x...',
  showAllVaults: true,
});
```

### 应用程序名称

`appName` 需要每个 `AugustSDK` 建筑师呼叫。 通过一个稳定的kebab- case 弹片 识别您的申请(例如). `'acme-trader'`, (中文(简体) ), `'my-defi-app'`:

-   **何等为用.** 8月 数字标记分析事件 `app.name = <yourSlug>` 改为 属性错误标记和优先排序错误修正 .
-   **事实并非如此.** 不是秘密 不是执照钥匙 不是显示标签 选一发子弹 并在部署中重复使用.
-   **制约因素.** 3-64个字符,仅限 `[a-zA-Z0-9._-]`。SDK同步从 如果数值缺失或无效,则该构建器.

```typescript
// Will throw — appName is required.
new AugustSDK({ providers: { /* ... */ } } as any);

// Will throw — spaces not allowed. Use 'acme-trader'.
new AugustSDK({ appName: 'Acme Trader', providers: { /* ... */ } });

// Correct.
new AugustSDK({ appName: 'acme-trader', providers: { /* ... */ } });
```

### 起源- 代码归属( SwapRouter)

在交换室上注册的拥有原产地(参考/费用分享)代码的集成商将它安装在 SDK实例。 通过SDK实现的存款然后在链上携带:

```typescript
const sdk = new AugustSDK({
  appName: 'acme-trader',
  providers: { 1: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY' },
  attribution: {
    originCode: '0x…', // bytes32 registered on the SwapRouter with addOrigin
    strictOrigin: false, // optional: true throws instead of falling back
  },
});

// Check the code before you ship it.
const { registered, originFeeBps, collector } = await sdk.getOriginInfo({
  chainId: 1,
  originCode: '0x…',
});
```

-   **只有伊特鲁姆主网.** 实例代码发送于链 1 (`ORIGIN_ATTRIBUTION_CHAINS`没有其他 链,即使配置了交换路器.
    
-   **适用之处.** `vaultDeposit` 发送保证金通过 `SwapRouter.deposit` 密码 `sdk.evm.getDepositRoute()` 返回时 `via: 'router'`:金库在路由器上注册,金库接受 资产原地(其参考资产,或Tokenized Vault V2 白上市资产——从未互换),路由器 白列资产,路由器不被暂停,押金不是许可,本地或适配器押金, 并注册了密码. `swapRouterDeposit`, (中文(简体) ), `swapAndDeposit`, (中文(简体) ), `depositViaSwapRouter` 财务报告和审定财务报表 `depositNativeViaSwapRouter` 也发去.
    
-   **先入正觉.** 一个 `originCode` 传递到路由器方法,然后是实例代码,然后是全零 sentinel(无来源费). 传出零哨,选择一个呼叫.
    
-   **倒倒倒地来.** 当代码无法应用时——它没有注册,链条不是主网,路由器 暂停( e)`router-paused`,用15秒缓存检查)或不将资产白化,金库会 不接受,或未在路由器上注册,或是一种许可、本地托存或适配存款—— `vaultDeposit` 使用金库的本地路径和日志 `vaultDeposit:attribution-skipped` 带有原因( 哨兵标记) `sdk.attribution.origin=skipped`) (中文(简体) ). 路由器 方法发送未注册实例代码和日志的0 sentinel `<method>:attribution-skipped`。 。 。 . 与 `strictOrigin: true` 未注册实例代码抛出 `AugustValidationError` 任何批准之前 相反;一个被暂停的路由器甚至会回到原生地. 一个 `originCode` 传递到路由器方法,即 未注册总是丢 `AugustValidationError` 在任何批准之前。 当路由器被暂停时 路由器方法抛出 `AugustSDKError` (单位:千美元)`context.reason: 'router-paused'`任何批准之前.
    
-   **核准 `route.spender`不是金库.** 换接器提取了路由押金. `vaultDeposit` 财务报告和审定财务报表 `approve` 操作此选项; 如果您自己发送批准文件, 请先读到支出者 :
    
    ```typescript
    const route = await sdk.evm.getDepositRoute({ target: vault, depositAsset: usdc });
    // route.spender is the SwapRouter when route.via === 'router', else the vault (or adapter wrapper)
    ```
    
-   **气来.** 在主网叉上测量(将1,000美元存款汇入核心USDC):直接存款102,067个气体; 路由器为0%,编码为161.744 (+59.7k);路由器为1%,编码为173,135 (+71.1k). 路由存款还需要一个 一次性批准路由器每令牌.
    
-   **零费码.** 以 0 bps 收费注册的代码仅对归属有效,但路由器发出否 `OriginFeeApplied` 活动。 其存款仅来自交易 calldata和SDK 遥测.
    
-   **进程-全球.** `attribution` 是进程- 全球: 最后一个 `AugustSDK` 构造胜出,一个 建造无 `attribution` 释出. 每个进程运行一个归属配置.
    

## 建筑

```
src.ts/
├── main.ts              # Main SDK class (AugustSDK)
├── core/                # Base utilities
│   ├── base.class.ts    # Base SDK functionality
│   ├── fetcher.ts       # API client with retry logic
│   └── web3.helpers.ts  # Blockchain utilities
├── adapters/            # Chain-specific implementations
│   ├── evm/             # EVM adapter (approve, deposit, redeem, read helpers)
│   ├── solana/          # Solana program adapters
│   ├── stellar/         # Stellar vault adapters
│   └── sui/             # Sui (Ember) vault adapters
├── evm/                 # EVM cross-chain (LayerZero OVault)
├── modules/             # Feature modules
│   ├── vaults/          # Vault read operations
│   ├── sub-accounts/    # Sub-account queries
│   └── api/             # August backend API integration
├── services/            # External service integrations
│   ├── debank/          # DeFi allocation data
│   ├── coingecko/       # Token pricing
│   └── subgraph/        # Historical transaction data
└── types/               # TypeScript interfaces
```

## 关键概念

### 多钱支持

-   **EVM 链**:伊特鲁姆,阿比特鲁姆, Base, BSC, Avalanche, 以及更多—— `wagmi/viem` 财务报告和审定财务报表 `ethers` 支持的签名符
-   **索拉纳**: 具有完整金库功能的原生索拉纳程序支持
-   **斯特拉尔**: Stellar 保险库存款、赎回和职位查询
-   **苏**: Ember 金库读取操作
-   跨越所有链条的统一接口

### 默认版本

-   `evm-0/evm-1`: 遗产金库合同
-   `evm-2`: 当前 EVM 金库架构( 单独的收件符)
-   `sol-0`: 索拉纳程序金库
-   `stellar-0`: 以 Starr 为主的金库

### 数据浓缩

所有金库查询都支持可选浓缩 :

-   `loans`: 包含主动贷款数据
-   `allocations`: DeFi/CeFi/OTC位置细分
-   `wallet`: 用户特定位置数据

## API 参考

### 断层查询

| 方法 | 说明 |
| --- | --- |
| `getVaults(options?)` | 跨链取出所有金库 |
| `getVault({ vault, chainId?, options? })` | 获取单个金库细节 |
| `getVaultLoans({ vault, chainId? })` | 获取活动贷款 |
| `getVaultAllocations({ vault, chainId? })` | 获取分配细目 |
| `getVaultHistoricalTimeseries({ vault, chainId? })` | 历史上的APY和TVL时间序列 |
| `getVaultApy({ vault, historical? })` | **@ 已过期** ——使用 `getVaultHistoricalTimeseries` |
| `getVaultTvl({ vault, historical? })` | 目前/历史 TVL |
| `getVaultAnnualizedApy({ vault })` | 将APY用作保险库 |
| `getVaultSummary({ vault })` | 汇总金库摘要 |
| `getVaultPnl({ vault, chainId? })` | 默认级别 PnL |
| `getVaultUnrealizedPnlHistory({ vault, chainId?, ... })` | 未实现的 PnL 时间序列 |
| `getLatestUnrealizedPnl()` | 所有金库的最新未实现的PnL快照 |
| `getYieldLastRealizedOn({ vault, chainId? })` | 最后产量实现的时间戳 |
| `getTotalDeposited(options?)` | 整个保险库的存款总额 |

### 用户位置

| 方法 | 说明 |
| --- | --- |
| `getVaultPositions({ wallet?, vault?, chainId? })` | 用户金库位置 |
| `getVaultAvailableRedemptions({ vault, wallet?, chainId, verbose? })` | 索赔的赎回 |
| `getVaultRedemptionHistory({ vault, wallet?, chainId? })` | 历史的救赎 |
| `getVaultUserHistory({ wallet, vault?, chainId? })` | 交易历史 |
| `getVaultUserTransfers({ wallet, vault?, chainId? })` | 传输历史 |
| `getVaultUserLifetimePnl({ wallet, vault?, chainId? })` | 钱包终身 PnL |
| `getVaultStakingPositions({ wallet, chainId })` | 担任职务 |
| `getVaultBorrowerHealthFactor(props?)` | 借款人健康因素 |
| `getVaultWithdrawals({ vault, chainId? })` | 待提取 |

### 点

| 方法 | 说明 |
| --- | --- |
| `getUserPoints(userAddress)` | 钱包的分数平衡 |
| `registerUserForPoints({ wallet, referral? })` | 为分数程序注册钱包 |
| `fetchPointsLeaderboard(params?)` | 点头板 |

### 写操作( 顶级)

| 方法 | 说明 |
| --- | --- |
| `vaultDeposit(signer, options)` | 存入金库 |
| `previewRedemption(props)` | 广播前预览还原输出 |

### 横琴 (LayerZero)

| 方法 | 说明 |
| --- | --- |
| `getLayerZeroDeposits({ wallet?, chainId? })` | 图层Zero储量历史 |
| `getLayerZeroRedeems(props?)` | 图层Zero救赎历史 |

### 公用事业

| 方法 | 说明 |
| --- | --- |
| `getPrice(symbol)` | 汇兑价格(美元) |
| `switchNetwork(chainId)` | 更改活动链 |
| `updateWallet(address)` | 设置正在运行的跟踪钱包 |

### 分账户`sdk.subAccountsModule`(中文(简体) )

| 方法 | 说明 |
| --- | --- |
| `getSubaccountHealthFactor(address)` | 一个分账户的健康因素 |
| `getSubaccountLoans(address)` | 用于子账户的积极贷款 |
| `getSubaccountCefiPositions(address)` | CeFi 职位 |
| `getSubaccountOtcPositions(address)` | OTC职位 |
| `getSubaccountSummary(address)` | 合计分账户汇总 |

### EVM 适应器`sdk.evm`(中文(简体) )

在调用写法前设置一个签名符 :

```typescript
// ethers
import { JsonRpcProvider, Wallet } from 'ethers';
const wallet = new Wallet(process.env.PRIVATE_KEY!, new JsonRpcProvider(rpcUrl));
sdk.evm.setSigner(wallet);

// wagmi/viem (browser)
import { useWalletClient } from 'wagmi';
const { data: walletClient } = useWalletClient();
if (walletClient) sdk.evm.setSigner(walletClient);
```

**写入方法 :**

| 方法 | 说明 |
| --- | --- |
| `vaultApprove(options)` | 批准为金库支付代币 |
| `approve(options)` | 一般性ERC-20核准 |
| `vaultDeposit(options)` | 将资产存入金库 |
| `vaultRequestRedeem(options)` | 请求撤回/撤销 |
| `vaultRedeem(signer, options)` | 要求可获得的补偿 |
| `depositNative(options)` | 保存本地地物(ETH等) |
| `swapAndDeposit(options)` | 换一换一换 |
| `depositViaSwapRouter(options)` | 通过互换路由器存款 |
| `depositNativeViaSwapRouter(options)` | 通过互换路由器交存本地 |

**读取助手( 返回原始) `bigint`:**

| 方法 | 说明 |
| --- | --- |
| `previewDeposit(options)` | 按存款金额计价的股份 |
| `previewRedeem(options)` | 退回的资产,份额 |
| `allowance(options)` | 向金库发放ERC-20津贴 |
| `balanceOf(options)` | ERC-20 任何令牌/所有者的余额 |
| `maxDeposit(options)` | 保险库接受的最大存款 |
| `vaultAllowance(options)` | 特定故障津贴检查 |
| `getDeposited(options)` | 本期存款余额 |
| `getRemainingAllocations(options)` | 剩余分配能力 |
| `isWhitelisted(options)` | 检查白名单状态 |

### 索拉纳适应器`sdk.solana`(中文(简体) )

| 方法 | 说明 |
| --- | --- |
| `getVaultState(...)` | 索拉纳计划中的故障状态 |
| `getVaultStateReadOnly(...)` | 只读金库状态 |
| `getToken(mintAddress)` | SPL 令牌信息 |
| `getTokenSymbol(mintAddress)` | 脚本符号 |
| `fetchUserTokenBalance(publicKey, mint)` | 用户 SPL 符号余额 |
| `fetchUserShareBalance(publicKey, vault)` | 用户共享余额 |
| `fetchUserShareBalanceRaw(publicKey, vault)` | 原始份额余额( 比克特) |

### 斯特拉尔适配器( S)`sdk.stellar`(中文(简体) )

| 方法 | 说明 |
| --- | --- |
| `vaultDeposit(options)` | 存入斯泰拉金库 |
| `vaultRedeem(options)` | 从斯泰拉金库取出 |
| `submitTransaction(signedXdr)` | 提交签名的 XDR 交易 |
| `getUserPosition(options)` | 用户在 Stellar 金库中的位置 |
| `convertToShares(options)` | 将资产金额转换为股份 |

### Sui 适配器( R)`sdk.sui`(中文(简体) )

| 方法 | 说明 |
| --- | --- |
| `getEmberVaults()` | 列出所有 Ember (Sui) 金库 |
| `getEmberTVL(limit?)` | 整个安伯金库锁定的总值 |

## 守则公约

### 命名图案

-   **接口**: 前缀为 `I` (例如, `IVault`, (中文(简体) ), `IVaultLoan`(中文(简体) )
-   **ABIs 函数**: 前缀为 `ABI_` (例如, `ABI_LENDING_POOL_V2`(中文(简体) )
-   **类型**:描述性名称(如:, `IAddress`, (中文(简体) ), `IChainId`(中文(简体) )

### 特殊注释标签

搜索密码库以找到重要区域 :

-   `@todo`: 计划改进或缺失特征
-   `@hardcoded`: 可能需要配置的硬码值
-   `@solana`: 索拉纳语特定逻辑或注释

### 处理错误

每种公用方法都会打出子类错误 `AugustSDKError`数字 :

```typescript
import { AugustValidationError, AugustTimeoutError, AugustSDKError } from '@augustdigital/sdk';

try {
  await sdk.evm.vaultDeposit({ target: '0x...', wallet: owner, amount: '1' });
} catch (err) {
  if (err instanceof AugustValidationError) showFormError(err.message);
  else if (err instanceof AugustTimeoutError) scheduleRetry(err.timeoutMs);
  else if (err instanceof AugustSDKError) reportError(err.code, err.cause);
  else throw err;
}
```

-   网络错误自动重试, 以指数倒置
-   90秒请求超时(可以通过 `REQUEST_TIMEOUT_MS`(中文(简体) )
-   调试出错的关联ID

### 环境配置

```typescript
// Development mode — enables console logging
const sdk = new AugustSDK({ appName: 'my-app', providers: { /* ... */ }, monitoring: { env: 'DEV' } });

// Production mode — default, no console logs
const sdk = new AugustSDK({ appName: 'my-app', providers: { /* ... */ } });
```

## 发展

### 运行测试

```bash
pnpm test
```

### 大楼

```bash
pnpm build
```

## 支助

-   **问题**数字 : [GitHub 问题](https://github.com/fractal-protocol/js-sdk/issues)
-   **文档**数字 : [(原始内容存档于2017-03-21). docs.augustigital.io](https://docs.augustdigital.io/developers/javascript-sdk)
-   **示例应用**数字 : [财务](https://starter.upshift.finance/)

## 常见问题

### @augustdigital/sdk 是什么？

JS SDK为8月数字生态系统提供动力\.

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

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

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

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

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

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

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

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

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

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

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

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