# @chironbuilder/ootle-sdk 中文文档

规范地址：https://npmcn.com/package/%40chironbuilder/ootle-sdk/

版本：0\.4\.1
npm 元数据更新时间：2026-11-08T15:01:29.246Z
中文译文更新时间：2026-11-09T14:13:51.886Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：2 MB，71 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- 首次发布：2026-09-12T10:09:37.191Z
- 最新版本发布：2026-11-08T15:01:29.088Z
- 近 30 天下载量：2478（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：37（近 12 个月 37 个）

## 中文简介

Tari Ootle(L2)的共享TypeScript客户端:账户衍生,余额,交易,HTLCs,以及隐秘/机密转移——Sapient背后的账户核心和Tari L1网络钱包的Ootle支持.

## 安装

```sh
npm install @chironbuilder/ootle-sdk
```

也可以使用：`pnpm add @chironbuilder/ootle-sdk`、`yarn add @chironbuilder/ootle-sdk`、`bun add @chironbuilder/ootle-sdk`

## README

# @chironbuilder/boltle-sdk (英语)

共享类型脚本客户端 [塔里乌托](https://github.com/tari-project/tari-ootle) (L2):账户 衍生、余额、自动输入解析的交易结构/提交、高通量交易和 秘密/机密转移.

这是从两个独立设计的钱包中提取的账户核心 (大多数) 同一个代码用手—— [稳健](https://github.com/chironbuilds/tari-wallet),一个克罗姆 扩展,以及 [Tari L1 网络钱包](https://universe.tari.mw/)'Ootle L2支持——在每一个都得到了之后 捡起它自己的修补品 另一个不见了 这个软件包存在, 以便停止发生: 一 钱包核心,由两者使用,并带有特定平台关切(存储,此处为存储) 比硬码.

**状况:早.** 取出并核对为一通;尚未接回其中任何一条 上面的钱包(它们目前仍然携带自己的本地副本)。 处理 `0.x` 就是这样.

## 安装

```bash
npm install @chironbuilder/ootle-sdk
```

这个套件卖出两个小的,仍然没有出现的补丁: `@tari-project/ootle` 联合国 `covenant_claims` 序列化间隙 `StealthTransferStatement.toCompactJson()`每一次转移SDK都是无害的 今日建造,但尚未上游固定)和 `@tari-project/ootle-wasm` (增加数) `createConfidentialWithdrawProofLiteral`,需要保密-断层提取,而不是在 已出版 `0.39.x` 建楼). 见 `vendor/*/README.md` 每一个。 两人都被跟踪一次 上游船只的真正固定装置——在假定还需要任何固定装置之前到那里检查.

## 存储

SDK从不直接接触混凝土存储 API. 它读和写 通过一个小 `KeyValueStore` 接口 – 一次配置一个适配器,然后再调用其它设备 :

```ts
import { configureOotleStorage } from "@chironbuilder/ootle-sdk";
import { chromeStorageAdapter } from "@chironbuilder/ootle-sdk/adapters";
// or: localStorageAdapter, inMemoryAdapter (tests)

configureOotleStorage(chromeStorageAdapter());
```

给其他主机写自己的适配器——这是三种方法(`get`编号 :`set`编号 :`remove`) (中文(简体) ).

这只包括账户核心本身需要的(屏蔽产出、待处理的盾牌、 私人付费扫描光标,已知的子态版本缓存). 地址簿,连接网站 权限、守护进程连接和完整的交易历史 UI 是应用程序的担忧 每个主机的形状非常不同——将那些保存在自己的应用存储层.

## 使用量

```ts
import { OotleAccount, toOotleNetwork } from "@chironbuilder/ootle-sdk";

const account = OotleAccount.fromSeed(entropy, /* index */ 0, "esmeralda");

const balances = await account.getBalances();
await account.send(recipientWalletAddress, resourceAddress, amount);
```

见 `src/wallet.ts`完整的文件注释 `OotleAccount` 水面- `send`, (中文(简体) ), `sendPrivately`, (中文(简体) ), `shield`编号 :`unshield`, (中文(简体) ), `htlcFund`编号 :`htlcClaim`编号 :`htlcRefund`, (中文(简体) ), `claimTestnetXtr`, (中文(简体) ), `execute` (总则 指令-建造者逃出舱口,自动发现出漏入和锁定保留重试).

### 网络

`NetworkName` 实值 `"mainnet" | "esmeralda" | "igor"`主网具有实际价值; `isTestnet(name)` 告诉两个分开 `claimTestnetXtr` 拒绝主网。 同样的种子给出相同的键 每个网络;只有地址前缀不同(`otl_1…` 在主网, `otl_esm_1…` 在《埃斯梅拉达协定》和 每个交易都带有其网络字节,因此一个签入测试网的功能不能被主网重放.

索引来自SDK自己的表格(`indexerUrlFor`主网为: `https://indexer-a.ootle.tari.com` (tari-otle的默认值) Esmeralda保留 `https://ootle-indexer-a.tari.com`伊戈尔没有 指向其它处的网络 `setIndexerUrl(Network.MainNet, url)` 在创建账户之前.

由于密钥相同,所存储的记录被网络分开保存取而代之. 一个账户 屏蔽输出、扫描光标和水印、待取屏蔽、预定和HTLC日记 下级 `account.ledgerId`数字 : `local:N` 在一个测试网上(与先前版本没有变化,因此已有数据) 不需要迁移)和 `mainnet:local:N` 在主网。 读一下 `account.ledgerId`永远 `localAccountId(index)`。子状态版本缓存以相同方式分割,以及 `recoverPendingShields(provider, network)` 只能调和那个网络的 等待盾牌.

### 要求烧掉Minotari(L1)

开往该账户公用钥匙的烧伤`getPublicKey()`索赔方式 `claimBurn`构建 l1 烧伤的索赔材料及其内核内链证明(基点)的证据 `/generate_kernel_merkle_proof`,或读取a `minotari_console_wallet` 证明文件 :

```ts
import { assembleBurnClaimProof, parseConsoleWalletBurnProof } from "@chironbuilder/ootle-sdk";

const proof = assembleBurnClaimProof(l1BurnParts, kernelMerkleProof);
// or: const proof = parseConsoleWalletBurnProof(fileText);
// The fee is measured with a dry run; a stealth-revealed fee is never refunded, so it is not padded.
const { claimedAmount, fee } = await account.claimBurn(proof);
```

索赔资金作为该账户拥有的隐形产出运抵,记入其私人帐户 余额。 校验器只有在其L1区块得到确认后才接受烧伤,所以一个早期的说法是: 拒绝,可以再审.

### HTLCs和原子交换

`htlcFund` 编号 : `htlcClaim` 编号 : `htlcRefund` 为定居点安全而建造,而不仅仅是建造 交易:

```ts
// Lock 5,000 units of a stealth-created asset from exact private outputs. The fee stays in its own
// native-TARI lane (here: private), the asset stays in the main lane, excess comes back as change.
const fund = await account.htlcFund(asset, 5_000n, claimantAddress, hashLockHex, refundEpoch, 50_000n,
  { kind: "private", feeResourceAddress: TARI }, { source: { kind: "stealth", commitments: [myUtxo] } });
// fund.conditions → send to the claimant. fund.outputMask is also journaled (fund.journalId).

// Claimant: nothing is revealed unless the funded output matches the agreed terms.
const check = await account.verifyHtlc(asset, fund.ownCommitment, fund.conditions, { amount: 5_000n, minEpochsBeforeRefund: 3n });
await account.htlcClaim(asset, fund.ownCommitment, fund.conditions, preimageHex, 50_000n, feeType,
  { expected: { amount: 5_000n, refunderPublicKeyHex, minEpochsBeforeRefund: 3n } });

// Funder, once currentEpoch >= refundEpoch:
await account.refundFromJournal(fund.journalId);
```

-   **两道.** 收费(国内TARI、公共或私人UTXO)从未与HTLC共享UTXO 数值. `source: { kind: "stealth" }` 使用这个账户自己的隐形产出资源, 所以不需要公众的平衡.
-   **干跑先发.** 每项基金/索偿/退款在实际提交之前都进行准确交易 (单位:千美元)`preflight: false` 以跳过 —— 权利主张的干线向索引员的干线发送了预想 结束点).
-   **在预想离开设备前验证.** `htlcClaim` (和 `verifyHtlc`检查 金额,索赔的叶子是你的钥匙 退款的叶子 商定的对手 链上条件根等于树根, 预想匹配散列锁 保留足够的时间 `HtlcVerificationError` 否则.
-   **持久日记.** 封口交易、条件树和 HTLC 输出口罩 只有能够退款的事物才能坚持下去 _在此之前_ 提交。 模棱两可的结果 掷出 `HtlcUnknownOutcomeError` ——"待",从未"失败"——和 `reconcileHtlcs()` (已调用) )通过重新提交相同交易并应用其账簿管理来解决. `listHtlcs()` 显示每个操作及其状态.
-   **保留精确输入** 行动期间(以及行动结果 )),所以同时发送/未屏蔽/收费选择不能选择.
-   **Epoch 规则匹配引擎 :** 退款叶子是 `AfterEpoch` (何时打开) `currentEpoch >= refundEpoch`),索赔部分 `BeforeEpoch` 看到了吗 `isHtlcRefundable` 编号 : `isHtlcClaimableByEpoch`。 。 。 .
-   申报和退还的产出被记录入屏蔽分类账中,因此可以同时使用.

## 验证所有权证明

接收网站 `{ walletAddress, publicNonce, signature }` 从 `tari_signWalletOwnershipChallenge` 检查一下 `verifyWalletOwnershipProof` (和产出) 使用 `verifyOwnershipProof`从它已经想到的地址取出钥匙。 这个 字节光谱在 [文件/所有权保护](https://npmcn.com/package/%40chironbuilder/ootle-sdk/docs/ownership-proof.md)· ; `src/fixtures/ownershipProof.vectors.json` 持有 Tari 真实签名器产生的固定向量 (只测试密钥).

## 里面有什么,没有

-   **账户核心** (单位:千美元)`wallet.ts`: `OotleAccount`,余额/计划解决方案帮助者,交易 自动解析回路.
-   **加密/开发**数字 : `derivation.ts`, (中文(简体) ), `domainHash.ts`, (中文(简体) ), `componentAddress.ts`, (中文(简体) ), `vault.ts`, (中文(简体) ), `ownershipProof.ts`, (中文(简体) ), `verifyOwnershipProof.ts`, (中文(简体) ), `confidential.ts`。 。 。 .
-   **HTLC 高氯**数字 : `htlc.ts` (有条件的树木), `htlcSafety.ts` (时代规则,索赔前核实, 每产出口罩,结果分类) + 日记账 `OotleAccount` HTLC方法.
-   **L1燃烧索赔**数字 : `burnClaim.ts` (防组装)+ `OotleAccount.claimBurn`。 。 。 .
-   **存储抽象**数字 : `storage.ts` + 键 `adapters.ts`。 。 。 .
-   **未列入**: UI, dApp 连接、地址簿、守护进程的批准/许可模式 (单位:千美元)`tari_ootle_walletd`中继支持,交易历史的坚持. 这些留在每个 消耗应用.

## 发展中国家

```bash
npm install
npm run typecheck
npm test
npm run build
```

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40chironbuilder/ootle-sdk/LICENSE). (从中取出的两个钱包是单独许可的, 由 PolyForm 非商业性; 此 SDK 刻意更加宽容, 所以其他 Ootle 项目可以 在不受这种限制的情况下,继续发展。 )

## 常见问题

### @chironbuilder/ootle-sdk 是什么？

Tari Ootle\(L2\)的共享TypeScript客户端:账户衍生,余额,交易,HTLCs,以及隐秘/机密转移——Sapient背后的账户核心和Tari L1网络钱包的Ootle支持\.

### 如何安装 @chironbuilder/ootle-sdk？

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

### @chironbuilder/ootle-sdk 支持 TypeScript 吗？

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

### @chironbuilder/ootle-sdk 支持 ESM 还是 CommonJS？

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

### @chironbuilder/ootle-sdk 可以商用吗？

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

### @chironbuilder/ootle-sdk 的下载量有多少？

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

### @chironbuilder/ootle-sdk 还在维护吗？

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