docs: enhance SDK documentation with earn yield section and update re…

docs/pages/cn/explanation/sdk-overview.mdx

@@ -1,14 +1,14 @@
 ---
 source_path: explanation/sdk-overview.mdx
-source_sha: efcb1b7d8aaf0782573a67c4964ac01904c220ae
+source_sha: de079c165ba2efc991a66b7134e00a6e9b5073f4
 title: "Stable SDK"
-description: "使用类型化的 TypeScript SDK，只需几行代码即可在 Stable 上传输 USDT0、跨链桥接和兑换代币。"
+description: "使用类型化的 TypeScript SDK，只需几行代码即可在 Stable 上转移 USDT0、跨链桥接、兑换代币和赚取金库收益。"
 diataxis: "explanation"
 ---
 
 # Stable SDK
 
-`@stablechain/sdk` 是 Stable 官方的 TypeScript 客户端。它封装了 Viem，提供了一个小巧、类型化的 API，用于处理你最常使用的操作：传输 USDT0、在链之间进行桥接以及在 Stable 上兑换代币。路由、授权、小数位和链切换都已为你处理好。
+`@stablechain/sdk` 是 Stable 的官方 TypeScript 客户端。它将 viem 封装成一个小的、类型化的 API，用于您最常进行的操作：转移 USDT0、跨链桥接、兑换代币以及在 Stable 上赚取收益。路由、批准、小数位数和链切换都为您处理。
 
 ```ts
 import { createStable, Network } from "@stablechain/sdk";
@@ -32,29 +32,32 @@ txHash: 0x8f3a...2d41
 
 ## SDK 功能
 
-- **`transfer`**：发送原生 USDT0 或 Stable 上的任何 ERC-20 代币。Gas 费会自动以 USDT0 支付。
-- **`quoteBridge` / `bridge`**：跨链传输。USDT0 → USDT0 使用 LayerZero，其他所有代币使用 LI.FI。系统会自动为你选择路由。
-- **`quoteSwap` / `swap`**：通过 LI.FI 进行同链代币兑换，ERC-20 授权在内部处理。
+- **`transfer`**：发送原生 USDT0 或 Stable 上的任何 ERC-20。Gas 费会自动以 USDT0 支付。
+- **`quoteBridge` / `bridge`**：通过 LI.FI 进行跨链传输，LI.FI 会为您选择桥接路线。批准和链切换在内部处理。
+- **`quoteSwap` / `swap`**：通过 LI.FI 进行同链代币兑换，ERC-20 批准在内部处理。
+- **`earn`**：将 USDT0 存入 Morpho V2 金库以赚取收益，提现或赎回，并领取 Merkl 激励奖励。批准和适配器解除分配都为您处理。
+- **`createStableReader`**：一个只读客户端，用于获取金库年化收益率 (APY)、您的头寸、收益预测和即时提现可用性检查。无需签名器。
 
-SDK 已发布到 npm，名称为 [`@stablechain/sdk`](https://www.npmjs.com/package/@stablechain/sdk)，并要求 `viem >= 2.0.0` 作为 peer dependency。
+SDK 发布在 npm 上，名称为 [`@stablechain/sdk`](https://www.npmjs.com/package/@stablechain/sdk)，并要求 `viem >= 2.0.0` 作为对等依赖项。
 
-## 何时使用（何时不使用）
+## 何时使用（以及何时不使用）
 
-当你想要一个类型化、规范化的客户端，并隐藏路由和授权样板文件时，请使用 SDK。当你需要直接控制交易构建、自定义 gas 策略或进行 transfer/bridge/swap 之外的合约调用时，请降级到原始的 Viem 或 Ethers。
+当您需要一个类型化、规范化的客户端来隐藏路由和批准样板文件时，请使用 SDK。当您需要直接控制交易构造、自定义 Gas 策略或转账/桥接/兑换之外的合同调用时，请降级到原始 viem 或 ethers。
 
 :::note
-SDK 使用任何兼容 Viem 的签名器进行签名：私钥 `Account`、浏览器 `Transport`（如 `custom(window.ethereum)`）或预构建的 `WalletClient`（例如，wagmi 的 `useWalletClient` 返回的客户端）。
+SDK 使用任何兼容 viem 的签名器进行签名：私钥 `Account`、浏览器 `Transport`（例如 `custom(window.ethereum)`）或预构建的 `WalletClient`（例如，wagmi 的 `useWalletClient` 返回的客户端）。
 :::
 
-## 从这里开始
+## 从此处开始
 
-- [**快速入门**](/cn/tutorial/sdk-quickstart)：安装 SDK 并在测试网上运行你的首次转账、桥接和兑换。
+- [**快速入门**](/cn/tutorial/sdk-quickstart)：安装 SDK 并在测试网上运行您的第一个转账、桥接和兑换。
+- [**使用 SDK 赚取收益**](/cn/how-to/earn-yield)：存款到金库，查看您的 APY 和头寸，提款并领取奖励。
 - [**SDK 参考**](/cn/reference/sdk)：所有方法、配置选项、枚举和错误类。
-- [**与 viem 一起使用**](/cn/how-to/sdk-with-viem)：服务器端账户、浏览器钱包以及自带的 `WalletClient`。
-- [**与 wagmi 一起使用**](/cn/how-to/sdk-with-wagmi)：使用 `useWalletClient` 和 hooks 将 SDK 连接到 React 应用程序。
+- [**与 viem 配合使用**](/cn/how-to/sdk-with-viem)：服务器端账户、浏览器钱包和自带 `WalletClient`。
+- [**与 wagmi 配合使用**](/cn/how-to/sdk-with-wagmi)：使用 `useWalletClient` 和 hooks 将 SDK 连接到 React 应用程序。
 
-## 下一步推荐
+## 下一步建议
 
 - [**从 npm 安装**](https://www.npmjs.com/package/@stablechain/sdk)：在 npmjs.com 上查看软件包并检查最新版本。
 - [**连接到 Stable**](/cn/reference/connect)：主网和测试网的链 ID、RPC 端点和浏览器。
-- [**资助测试网钱包**](/cn/how-to/use-faucet)：在运行快速入门之前，从水龙头获取测试网 USDT0。
+- [**资助测试网钱包**](/cn/how-to/use-faucet)：在运行快速入门之前从水龙头获取测试网 USDT0。

docs/pages/cn/how-to/earn-yield.mdx

@@ -0,0 +1,178 @@
+---
+source_path: how-to/earn-yield.mdx
+source_sha: 03f36a00122cecc73b90075f5f9276cfd84121ee
+title: "用 SDK 赚取收益"
+description: "使用 Stable SDK 将 USDT0 存入 Morpho 资金库，读取年化收益率和头寸，提款，并领取 Merkl 奖励。"
+diataxis: "how-to"
+---
+
+# 用 SDK 赚取收益
+
+在 Stable 主网将 USDT0 存入 Morpho V2 资金库以赚取收益，然后读取您的头寸并提款。 `@stablechain/sdk` 的 `earn` 方法处理 ERC-20 授权、存款和提款时的适配器解除分配，因此您每个操作只需调用一个方法。
+
+涉及两个客户端。`createStable` 为您提供用于存款和提款的签名客户端。`createStableReader` 为您提供只读客户端，用于查询年化收益率、头寸和可提款性，无需签名器。
+
+## 先决条件
+
+- Node.js 20 或更高版本，以及已安装的 `@stablechain/sdk` 和 `viem`。请参阅 [SDK 快速入门](/cn/tutorial/sdk-quickstart)。
+- 具有 Stable 主网 USDT0 的签名器。要转入资金，请使用 [`stable.bridge`](/cn/reference/sdk#bridgeparams) 或其中一个[支持的桥接器](/cn/reference/bridges)。
+- 资金库地址。SDK 将默认主网资金库导出为 `STABLE_VAULT_ADDRESS`。
+
+:::note
+赚取收益的示例在主网上运行。SDK 不提供测试网资金库地址，因此 `Network.Testnet` 仅适用于您自己部署的资金库。
+:::
+
+## 1. 使用资金库创建签名客户端
+
+将 `earn: { vault }` 传递给 `createStable`。如果没有它，存款和提款方法将抛出 `StableValidationError`。
+
+```ts
+import { createStable, Network, STABLE_VAULT_ADDRESS } from "@stablechain/sdk";
+import { privateKeyToAccount } from "viem/accounts";
+
+const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
+
+const stable = createStable({
+  network: Network.Mainnet,
+  account,
+  earn: { vault: STABLE_VAULT_ADDRESS },
+});
+```
+
+```text
+StableClient { transfer, quoteBridge, bridge, quoteSwap, swap, earn }
+```
+
+## 2. 存款前查看年化收益率
+
+创建只读读取器并获取资金库当前的净年化收益率。读取器需要您要读取的地址和资金库，但不需要签名器。
+
+```ts
+import { createStableReader } from "@stablechain/sdk";
+
+const reader = createStableReader({
+  network: Network.Mainnet,
+  address: account.address,
+  earn: { vault: STABLE_VAULT_ADDRESS },
+});
+
+const { apy, native, rewards } = await reader.earn.getYield();
+console.log("净年化收益率:", (apy * 100).toFixed(2) + "%");
+```
+
+```text
+净年化收益率: 5.80%
+```
+
+`apy` 是扣除费用后的总净年化收益率，包括奖励提升。`native` 是底层市场的独立收益率，`rewards` 则分解了每个奖励代币的年化百分比贡献。所有值均为小数，因此 `0.058` 表示 5.8%。
+
+要估算一段时间内的收益，请使用 `preview`：
+
+```ts
+const { projectedYield } = await reader.earn.preview({ amount: 1000, horizonDays: 30 });
+console.log("1000 美元 30 天预测收益:", projectedYield.toFixed(2));
+```
+
+```text
+1000 美元 30 天预测收益: 4.64
+```
+
+## 3. 存款
+
+向资金库提供资产。SDK 发送授权（或钱包支持时的许可签名），然后是存款，并等待收据。
+
+```ts
+const { txHash } = await stable.earn.deposit({ amount: 100 });
+console.log("存款交易哈希:", txHash);
+```
+
+```text
+存款交易哈希: 0x8f3a...2d41
+```
+
+金额是人类可读的。除非您传递 `tokenDecimals`，否则底层资产的小数位将在链上获取。为了限制单次存款消耗的资金库闲置流动性，请传递 `depositBuffer`（例如 `0.8` 表示 80%）；如果金额超过上限，SDK 会在发送前抛出错误。
+
+:::tip
+传递 `idempotencyKey` 可使存款安全重试。如果使用相同键的调用已在进行中，SDK 将返回相同的 Promise，而不是发送第二个交易。
+:::
+
+## 4. 读取您的头寸
+
+获取您的份额余额及其当前资产价值。
+
+```ts
+const position = await reader.earn.position();
+console.log("份额:", position.sharesFormatted, "价值", position.assets);
+```
+
+```text
+份额: 100 价值 100.02
+```
+
+`shares` 是原始余额，`sharesFormatted` 是其人类可读值。`assets` 是这些份额目前以底层单位计的价值。
+
+## 5. 提款或赎回
+
+提取特定数量的底层资产，或赎回一定数量的份额。当资金库的闲置流动性不足时，SDK 会自动从资金库的适配器中解除分配以弥补差额。
+
+```ts
+const { txHash } = await stable.earn.withdraw({ amount: 50 });
+console.log("提款交易哈希:", txHash);
+```
+
+```text
+提款交易哈希: 0xabcd...7890
+```
+
+要按份额数量赎回，请使用 `stable.earn.redeem({ shares: 25 })`。要首先检查某个数量是否可以立即取出，请调用读取器：
+
+```ts
+const { isInstant, availableLiquidity } = await reader.earn.withdrawability({ amount: 50 });
+console.log("即时提款:", isInstant, "可用流动性:", availableLiquidity);
+```
+
+```text
+即时提款: true 可用流动性: 12500.5
+```
+
+当 `isInstant` 为 `false` 时，提款仍然成功；它只是需要适配器解除分配，这由 `withdraw` 和 `redeem` 为您处理。要手动控制从哪些适配器中提取，请使用 [`forceWithdraw` / `forceRedeem`](/cn/reference/sdk#forcewithdrawparams--forceredeemparams)。
+
+## 6. 领取奖励
+
+资金库除了原生收益外，还可以赚取 Merkl 奖励代币。获取待领取奖励，然后领取它们。这些方法需要签名器，但不需要 `earn` 资金库配置。
+
+```ts
+const { rewards } = await stable.earn.incentiveRewards.fetch();
+if (rewards.length > 0) {
+  const { txHash, tokenCount } = await stable.earn.incentiveRewards.claim();
+  console.log("已领取", tokenCount, "个代币:", txHash);
+}
+```
+
+```text
+已领取 1 个代币: 0xabcd...7890
+```
+
+:::note
+Merkl 大约每两小时将奖励提交到其 merkle 树。仍在等待更新的奖励尚不能领取，如果调用 `claim()` 时没有可领取的奖励，则会抛出 `StableValidationError`。对于浏览器，请将 `merklApiBase` 设置为您自己服务器上的代理，以避免 Merkl API 的 CORS 限制。
+:::
+
+## 不在 SDK 中签名？
+
+如果您在其他地方签名交易（一个中继器，一个免 gas 流程，或一个多重签名），构建 calldata 而不发送它：
+
+```ts
+const { steps, chainId } = await stable.earn.prepareDepositCalldata({ amount: 100 });
+```
+
+```text
+{ steps: [ { to: "0x...", data: "0x...", value: 0n } ], chainId: 988 }
+```
+
+`steps` 是一个有序的交易列表，一个可选的授权，然后是存款。`prepareWithdrawCalldata` 和 `prepareRedeemCalldata` 各自返回一个 `{ to, data, value, chainId }` 交易。
+
+## 接下来去哪里
+
+- [**SDK 参考**](/cn/reference/sdk#stableearn)：完整的赚取收益参数、返回类型和读取器方法。
+- [**与 wagmi 一起使用**](/cn/how-to/sdk-with-wagmi)：将 SDK 集成到 React 应用程序中，以便用户从浏览器钱包存款。
+- [**SDK 概述**](/cn/explanation/sdk-overview)：何时使用 SDK 以及签名模式如何工作。

docs/pages/cn/how-to/sdk-with-viem.mdx

@@ -1,6 +1,6 @@
 ---
 source_path: how-to/sdk-with-viem.mdx
-source_sha: 48be50a291feef6843b9074ab105a81c375d5845
+source_sha: 7e53a41e2fc3a48b2ad38135b67d4d980e43e492
 title: "将 SDK 与 viem 结合使用"
 description: "通过三种方式使用 @stablechain/sdk 进行签名：私钥账户、浏览器传输或预构建的 viem WalletClient。"
 diataxis: "how-to"
@@ -10,11 +10,11 @@ diataxis: "how-to"
 
 `@stablechain/sdk` 基于 viem 构建。`createStable` 接受三种签名模式，您可以根据代码运行环境进行选择：在服务器端使用私钥，在浏览器端使用用户钱包，或者使用您已经构建的 `WalletClient`（例如，在 wagmi 应用程序中）。
 
-本指南将演示每种模式的端到端实现。
+本指南将端到端地展示每种模式。
 
 ## 服务器端：私钥 `Account`
 
-使用 viem 中的 `privateKeyToAccount` 函数，通过后端持有的私钥进行签名。
+使用 viem 的 `privateKeyToAccount` 通过您的后端持有的私钥进行签名。
 
 ```ts
 import "dotenv/config";
@@ -43,7 +43,7 @@ console.log(txHash);
 
 ## 浏览器端：来自钱包的 `Transport`
 
-将 `custom(window.ethereum)`（或任何 EIP-1193 provider）作为 `transport` 传递。SDK 会构建 `WalletClient` 并从 provider 读取签名者地址。
+将 `custom(window.ethereum)`（或任何 EIP-1193 provider）作为 `transport` 传入。SDK 会从传输中构建一个 `WalletClient`，并以您传递给 `transfer` 的 `from` 地址进行签名。
 
 ```ts
 import { createStable, Network } from "@stablechain/sdk";
@@ -68,12 +68,16 @@ const { txHash } = await stable.transfer({
 ```
 
 :::warning
-`transfer`、`bridge` 和 `swap` 会调用 `switchChain` 将钱包切换到正确的网络。如果用户拒绝，SDK 会抛出 `StableTransactionError` 并带有 `phase: "switch_chain"` 字段。请捕获此错误并向用户显示重试选项。
+传输模式仅适用于 `transfer`，因为 `transfer` 接受一个显式的 `from` 参数。`swap`、`quoteSwap`、`bridge` 和 `earn` 方法从 `account` 或 `walletClient` 读取签名者地址，当两者都未设置时会抛出 `StableValidationError`。对于这些方法，请从同一个提供者构建一个 `WalletClient`（下一节）。
+:::
+
+:::warning
+`transfer`、`bridge` 和 `swap` 调用 `switchChain` 将钱包切换到正确的网络。如果用户拒绝，SDK 会抛出 `StableTransactionError` 并带有 `phase: "switch_chain"`。捕获它并向用户显示重试选项。
 :::
 
 ## 引入您自己的 `WalletClient`
 
-当您已经拥有一个 `WalletClient`（例如，来自 wagmi 或自定义签名器）时，可以直接传递它。它会优先于 `account` 和 `transport`。
+当您已经拥有一个 `WalletClient`（例如，来自 wagmi 或自定义签名器）时，直接传递它。它优先于 `account` 和 `transport`。
 
 ```ts
 import { createStable, Network } from "@stablechain/sdk";
@@ -101,14 +105,14 @@ const { txHash } = await stable.transfer({ from, to: "0xRecipient", amount: 5 })
 
 ## 选择一种模式
 
-| **模式** | **何时使用** |
+| **模式** | **使用场景** |
 | :--- | :--- |
-| `account` | 后端服务、脚本、代理，任何您持有私钥的地方。 |
-| `transport` | 浏览器应用程序，用户通过 MetaMask 或无 wagmi 的自定义流程进行签名。 |
-| `walletClient` | 您已经有一个配置好的 `WalletClient` (wagmi、RainbowKit、ConnectKit)。 |
+| `account` | 后端服务、脚本、代理，以及任何您持有密钥的地方。 |
+| `transport` | 仅使用显式 `from` 调用 `transfer` 的浏览器应用程序。 |
+| `walletClient` | 您已经有一个配置好的 `WalletClient` (wagmi, RainbowKit, ConnectKit)。 |
 
 ## 接下来推荐
 
 - [**与 wagmi 结合使用**](/cn/how-to/sdk-with-wagmi)：通过 wagmi 钩子将 SDK 集成到 React 应用程序中。
-- [**SDK 参考**](/cn/reference/sdk)：所有配置字段、方法、枚举和错误类。
+- [**SDK 参考**](/cn/reference/sdk)：每个配置字段、方法、枚举和错误类。
 - [**SDK 快速入门**](/cn/tutorial/sdk-quickstart)：在测试网上运行您的第一个转账、桥接和兑换。