From 01cb5c585fe138f9bba8463c7f1c4329b3e899b8 Mon Sep 17 00:00:00 2001 From: rcsh <163504257+rcsh1@users.noreply.github.com> Date: Fri, 19 Jun 2026 10:51:22 +0800 Subject: [PATCH 1/7] Recover doc-writing-core run_8d40a6d96746 edits from trace log Reconstructed from ~/.workmate/playbook-traces/run_8d40a6d96746/events.jsonl (25 captured Edit/Write ops replayed). Worktree was deleted on success before the changes were committed; all real doc edits recovered intact. --- docs.json | 2 + v2/guides/overview/upgrade-guide.mdx | 4 ++ v2/guides/transactions/estimate-fees.mdx | 4 ++ .../transactions/manage-transactions.mdx | 2 + .../rbf-transaction-lifecycle.mdx | 43 +++++++++++++++++++ .../transactions/sources-and-destinations.mdx | 2 + v2/guides/transactions/status.mdx | 16 +++++++ .../transactions/transaction-process-mpc.mdx | 6 ++- v2/guides/transactions/transfer-routing.mdx | 38 ++++++++++++++++ v2_cn/guides/overview/upgrade-guide.mdx | 4 ++ v2_cn/guides/transactions/estimate-fees.mdx | 4 ++ .../transactions/manage-transactions.mdx | 2 + .../rbf-transaction-lifecycle.mdx | 43 +++++++++++++++++++ .../transactions/sources-and-destinations.mdx | 2 + v2_cn/guides/transactions/status.mdx | 16 +++++++ .../transactions/transaction-process-mpc.mdx | 6 ++- .../guides/transactions/transfer-routing.mdx | 38 ++++++++++++++++ 17 files changed, 230 insertions(+), 2 deletions(-) create mode 100644 v2/guides/transactions/rbf-transaction-lifecycle.mdx create mode 100644 v2/guides/transactions/transfer-routing.mdx create mode 100644 v2_cn/guides/transactions/rbf-transaction-lifecycle.mdx create mode 100644 v2_cn/guides/transactions/transfer-routing.mdx diff --git a/docs.json b/docs.json index d76c3113..3f4d8538 100644 --- a/docs.json +++ b/docs.json @@ -53,6 +53,7 @@ "group": "Transactions", "pages": [ "v2/guides/transactions/sources-and-destinations", + "v2/guides/transactions/transfer-routing", "v2/guides/transactions/estimate-fees", { "group": "Transaction statuses", @@ -63,6 +64,7 @@ ] }, "v2/guides/transactions/manage-transactions", + "v2/guides/transactions/rbf-transaction-lifecycle", { "group": "Smart contract call samples", "pages": [ diff --git a/v2/guides/overview/upgrade-guide.mdx b/v2/guides/overview/upgrade-guide.mdx index 85df20ed..984af2a6 100644 --- a/v2/guides/overview/upgrade-guide.mdx +++ b/v2/guides/overview/upgrade-guide.mdx @@ -70,6 +70,10 @@ The following table lists the API operations needed for common wallet operations | Sign a message | Not supported | [Sign message](/v2/api-references/transactions/sign-message) | | Query a transaction | | | + +WaaS 2.0 list endpoints, such as [List all transactions](/v2/api-references/transactions/list-all-transactions), return results in pages. By default each page returns 10 records, and the maximum page size is 50, set with the `limit` parameter. This differs from WaaS 1.0, where a single response could return all results. A single WaaS 2.0 page therefore omits later results. To retrieve every record, iterate through all pages using the cursor parameters `before` and `after`. + + ## Upgrade to 2.0 This section introduces the detailed steps to upgrade from WaaS 1.0 to 2.0. diff --git a/v2/guides/transactions/estimate-fees.mdx b/v2/guides/transactions/estimate-fees.mdx index 8a266956..b58dada1 100644 --- a/v2/guides/transactions/estimate-fees.mdx +++ b/v2/guides/transactions/estimate-fees.mdx @@ -174,6 +174,10 @@ The logic for estimating RBF transaction fees is similar to that for normal tran - Fixed: Increase the fee amount. - Filecoin: It is recommended to increase both gas premium and gas fee cap by 25%. +## Fees on Layer 2 chains + +On Layer 2 (L2) chains such as Arbitrum, network fees can change rapidly. If fees rise sharply after you submit a transaction, the transaction can remain in the `PendingSignature` or `Broadcasting` status longer than expected. To unblock such a transaction, use the Replace-By-Fee (RBF) speed-up operation to rebroadcast it with a higher fee. For how RBF works end to end, see [RBF (Replace-By-Fee) transaction lifecycle](/v2/guides/transactions/rbf-transaction-lifecycle). To raise the fee, use the [Speed up transaction](/v2/api-references/transactions/speed-up-transaction) operation. + ## How Cobo estimate the fees Below is how Cobo calculates the fees for each model: diff --git a/v2/guides/transactions/manage-transactions.mdx b/v2/guides/transactions/manage-transactions.mdx index e9792f44..c86a3e1e 100644 --- a/v2/guides/transactions/manage-transactions.mdx +++ b/v2/guides/transactions/manage-transactions.mdx @@ -37,6 +37,8 @@ Replace-By-Fee (RBF) is a feature that allows you to replace an unconfirmed tran The two most common use cases of RBF are speeding up and dropping transactions. +For how a replaced transaction's status changes and the events it emits, see [RBF (Replace-By-Fee) transaction lifecycle](/v2/guides/transactions/rbf-transaction-lifecycle). + ### Speed up a transaction Speeding up a transaction leverages RBF to replace the original transaction with a version with a higher fee, encouraging miners to prioritize it for faster confirmation. diff --git a/v2/guides/transactions/rbf-transaction-lifecycle.mdx b/v2/guides/transactions/rbf-transaction-lifecycle.mdx new file mode 100644 index 00000000..8df9ebd5 --- /dev/null +++ b/v2/guides/transactions/rbf-transaction-lifecycle.mdx @@ -0,0 +1,43 @@ +--- +title: "RBF (Replace-By-Fee) transaction lifecycle" +lang: "en" +description: "Understand how Replace-By-Fee (RBF) replaces an unconfirmed transaction, how the original transaction's status changes, and the events you receive." +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx'; + + + +## Overview + +Replace-By-Fee (RBF) replaces an unconfirmed, already-broadcast transaction with a new version. This guide describes the full lifecycle of an RBF replacement: the replacement operations you can perform, how the original transaction's status changes, and the events you receive. + +For the step-by-step operations, see [Manage transactions](/v2/guides/transactions/manage-transactions). For the fee rules that apply to RBF transactions, see [Estimate transaction fees](/v2/guides/transactions/estimate-fees#replace-by-fee-rbf-transaction-fee). + +## Replacement operations + +WaaS 2.0 supports the following RBF operations: + +- **Speed up**: Replaces the original transaction with a higher-fee version so that it confirms faster. Use the [Speed up transaction](/v2/api-references/transactions/speed-up-transaction) operation. +- **Drop**: Replaces the original transaction with a version that effectively cancels it. Use the [Drop transaction](/v2/api-references/transactions/drop-transaction) operation. + +Both operations apply only when the original transaction is in the `Broadcasting` status. They do not apply to transactions on the following chains: VET, TRON, TVET, SOL, and TON. + +## Original transaction status after replacement + +When a replacement transaction takes effect, the original transaction moves to the `Failed` status with the sub-status `ReplacedByNewTransaction`. For the complete list of statuses and sub-statuses, see [Transaction statuses and sub-statuses](/v2/guides/transactions/status). + +## Chained replacements + +Any subsequent drop or speed-up operations continue to apply to the original transaction. For example, if you create Transaction A, perform a drop operation on Transaction A using Transaction B, and then perform a speed-up operation on Transaction B using Transaction C, the speed-up operation still applies to Transaction A, not Transaction B. + +## Events + +RBF status changes are surfaced through the WaaS 2.0 transaction webhook events. To learn which events you receive, see [Webhook event types](/v2/guides/webhooks-callbacks/webhook-event-type). + +## Related guides + +- [Manage transactions](/v2/guides/transactions/manage-transactions) +- [Estimate transaction fees](/v2/guides/transactions/estimate-fees) +- [Transaction statuses and sub-statuses](/v2/guides/transactions/status) +- [Transaction sources and destinations](/v2/guides/transactions/sources-and-destinations) diff --git a/v2/guides/transactions/sources-and-destinations.mdx b/v2/guides/transactions/sources-and-destinations.mdx index cc7b853b..33e65299 100644 --- a/v2/guides/transactions/sources-and-destinations.mdx +++ b/v2/guides/transactions/sources-and-destinations.mdx @@ -16,6 +16,8 @@ Refer to the following table for the source and destination types corresponding If you transfer tokens between two wallets created on Cobo Portal, two transactions will be recorded: a deposit into the destination wallet and a withdrawal from the source wallet. +To control whether a transfer is routed internally through Cobo Loop or on-chain, see [Transfer routing](/v2/guides/transactions/transfer-routing). + | Transaction type | Source Type | Destination Type | |----------------------------------------------------|-------------------------------------------------------------------------------------------------|--------------------------| | Deposit - [Cobo Loop](https://manuals.cobo.com/en/portal/custodial-wallets/cobo-loop) transfers | DepositFromLoop | DepositToAddress | diff --git a/v2/guides/transactions/status.mdx b/v2/guides/transactions/status.mdx index 7a32ac7a..363ab4e0 100644 --- a/v2/guides/transactions/status.mdx +++ b/v2/guides/transactions/status.mdx @@ -274,6 +274,20 @@ The table below provides an overview of transaction statuses and sub-statuses re +## Status details + + +The `PendingAuthorization` status aggregates both manual approval steps and internal automated checks. Manual steps include `PendingApproverCheck`, `PendingSpenderCheck`, and `PendingDoubleCheck`. Automated checks include `PendingRiskControlCheck` and `PendingCoboCheck`. A transaction in `PendingAuthorization` does not necessarily require a person to act, because it may be undergoing automated risk-control or compliance checks. + + + +After a transaction is approved, it enters the `PendingSignature` status and must be signed by the MPC signer group within a limited signing window. If signing does not complete within this window, the transaction automatically fails and moves to the `Failed` status with the sub-status `FailedSignerTimeout`. To find out why a transaction failed, check the `sub_status` field returned by [List all transactions](/v2/api-references/transactions/list-all-transactions) or [Get transaction information](/v2/api-references/transactions/get-transaction-information). If you encounter `FailedSignerTimeout`, resend the transaction to try again. + + + +A transaction in the `Confirming` status with the sub-status `PendingBlockConfirmations` is waiting for the required number of block confirmations on its chain. This is a normal part of processing and does not mean the transaction is stuck. The required number of confirmations and the expected confirmation time vary by chain. + + ## Available actions You can perform the following actions based on the transaction status: @@ -286,4 +300,6 @@ You can perform the following actions based on the transaction status: - Resend a transaction if its status is `Failed`. - Speed up or drop a transaction if its status is `Broadcasting`. +For details on how a replaced transaction's status changes, see [RBF (Replace-By-Fee) transaction lifecycle](/v2/guides/transactions/rbf-transaction-lifecycle). + For more details, refer to [Manage transactions](/v2/guides/transactions/manage-transactions). \ No newline at end of file diff --git a/v2/guides/transactions/transaction-process-mpc.mdx b/v2/guides/transactions/transaction-process-mpc.mdx index 0d6346a1..3041a8c8 100644 --- a/v2/guides/transactions/transaction-process-mpc.mdx +++ b/v2/guides/transactions/transaction-process-mpc.mdx @@ -33,4 +33,8 @@ The following diagram illustrates how a withdrawal is processed. Colors are used Withdrawal process - If a withdrawal is rejected or unsuccessful, the tokens will be returned to your wallet, and your balance will remain unchanged. -- If your withdrawal amount is smaller than the minimum withdrawal threshold, the withdrawal request will receive an error. You can call the [Get token information](/v2/api-references/wallets/get-token-information) operation to retrieve the minimum withdrawal amount for each token type. \ No newline at end of file +- If your withdrawal amount is smaller than the minimum withdrawal threshold, the withdrawal request will receive an error. You can call the [Get token information](/v2/api-references/wallets/get-token-information) operation to retrieve the minimum withdrawal amount for each token type. + + +After a withdrawal is approved, it enters the `PendingSignature` status and must be signed by the MPC signer group within a limited signing window. If signing does not complete in time, the transaction automatically fails and moves to the `Failed` status with the sub-status `FailedSignerTimeout`. To confirm the reason, check the `sub_status` field returned by [Get transaction information](/v2/api-references/transactions/get-transaction-information), then resend the transaction to try again. + \ No newline at end of file diff --git a/v2/guides/transactions/transfer-routing.mdx b/v2/guides/transactions/transfer-routing.mdx new file mode 100644 index 00000000..95f897d4 --- /dev/null +++ b/v2/guides/transactions/transfer-routing.mdx @@ -0,0 +1,38 @@ +--- +title: "Transfer routing" +lang: "en" +description: "Understand how token transfers are routed internally through Cobo Loop or externally on-chain, and how to control routing with request parameters." +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx'; + + + +## Overview + +Every token transfer is routed either internally or externally: + +- **Internal routing** settles off-chain between accounts on Cobo Portal through the Cobo Loop transfer network, when the destination supports it. +- **External routing** broadcasts the transaction on the blockchain. + +## Control routing with request parameters + +The [Transfer token](/v2/api-references/transactions/transfer-token) operation provides two boolean parameters to control routing: `force_internal` and `force_external`. + +| Setting | Routing behavior | +|---------|------------------| +| `force_internal` = `true` | Forces internal routing through Cobo Loop (off-chain). | +| `force_external` = `true` | Forces external on-chain routing. | +| Both `false` (default) | Routes through Cobo Loop if the destination supports it; otherwise routes on-chain. | +| Both `true` | The request is rejected. | + +Some destinations do not support these parameters. + +## Effect on the resulting transaction + +Internal routing produces an off-chain Cobo Loop transfer. External routing produces an on-chain transaction. + +## Related guides + +- [Transaction sources and destinations](/v2/guides/transactions/sources-and-destinations) +- [Cobo Loop](https://manuals.cobo.com/en/portal/custodial-wallets/cobo-loop) diff --git a/v2_cn/guides/overview/upgrade-guide.mdx b/v2_cn/guides/overview/upgrade-guide.mdx index d729e1f6..c84ab8cd 100644 --- a/v2_cn/guides/overview/upgrade-guide.mdx +++ b/v2_cn/guides/overview/upgrade-guide.mdx @@ -72,6 +72,10 @@ WaaS 2.0 相较于 WaaS 1.0 进行了重大升级，面向支付、代币化、 | 签名消息 | 不支持 | [签名消息](/v2/api-references/transactions/sign-message) | | 查询交易 | | | + +WaaS 2.0 的列表类接口（例如 [List all transactions](/v2/api-references/transactions/list-all-transactions)）会分页返回结果。默认情况下每页返回 10 条记录，最大每页为 50 条，通过 `limit` 参数设置。这与 WaaS 1.0 不同：在 1.0 中单次响应可返回全部结果。因此 WaaS 2.0 的单页会遗漏后续结果。如需获取全部记录，请使用游标参数 `before` 和 `after` 遍历所有页。 + + ## 升级步骤 本节介绍从 WaaS 1.0 升级到 2.0 的详细步骤。 diff --git a/v2_cn/guides/transactions/estimate-fees.mdx b/v2_cn/guides/transactions/estimate-fees.mdx index cc04d624..8571f0e9 100644 --- a/v2_cn/guides/transactions/estimate-fees.mdx +++ b/v2_cn/guides/transactions/estimate-fees.mdx @@ -176,6 +176,10 @@ Replace-By-Fee (RBF) 是一种允许您用新版本替换未确认交易的功 - 固定模型：增加固定金额。 - Filecoin 模型：Gas Premium 和 Gas Fee Cap 建议提升 25%。 +## Layer 2 链上的费用 + +在 Arbitrum 等 Layer 2（L2）链上，网络费用可能快速变化。如果您提交交易后费用大幅上涨，交易可能会比预期更长时间地停留在 `PendingSignature` 或 `Broadcasting` 状态。如需解除此类交易的阻塞，可以使用 Replace-By-Fee（RBF）加速操作，以更高的费用重新广播交易。有关 RBF 的完整流程，请参阅 [RBF (Replace-By-Fee) transaction lifecycle](/v2_cn/guides/transactions/rbf-transaction-lifecycle)。如需提高费用，请使用 [Speed up transaction](/v2/api-references/transactions/speed-up-transaction) 操作。 + ## Cobo 如何估算费用 下列表格展示了不同费用模型下的费用估算方法： diff --git a/v2_cn/guides/transactions/manage-transactions.mdx b/v2_cn/guides/transactions/manage-transactions.mdx index 8582a3a9..7ceb13f5 100644 --- a/v2_cn/guides/transactions/manage-transactions.mdx +++ b/v2_cn/guides/transactions/manage-transactions.mdx @@ -36,6 +36,8 @@ Replace-By-Fee (RBF) 是一种允许您用新版本替换未确认交易的功 RBF 的两个最常见用例是加速和放弃交易。 +有关被替换交易的状态变化及其触发的事件，请参阅 [RBF (Replace-By-Fee) transaction lifecycle](/v2_cn/guides/transactions/rbf-transaction-lifecycle)。 + ### 加速交易 加速交易利用 RBF 用更高费用的版本替换原始交易，鼓励矿工优先处理以更快确认。 diff --git a/v2_cn/guides/transactions/rbf-transaction-lifecycle.mdx b/v2_cn/guides/transactions/rbf-transaction-lifecycle.mdx new file mode 100644 index 00000000..98fc9c20 --- /dev/null +++ b/v2_cn/guides/transactions/rbf-transaction-lifecycle.mdx @@ -0,0 +1,43 @@ +--- +title: "RBF (Replace-By-Fee) 交易生命周期" +lang: "zh-hans" +description: "了解 Replace-By-Fee (RBF) 如何替换未确认交易、原交易的状态如何变化，以及您会收到哪些事件。" +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; + + + +## 概述 + +Replace-By-Fee (RBF) 使用新版本替换已广播但尚未确认的交易。本指南介绍 RBF 替换的完整生命周期：您可以执行的替换操作、原交易的状态如何变化，以及您会收到哪些事件。 + +有关分步操作，请参阅 [Manage transactions](/v2_cn/guides/transactions/manage-transactions)。有关适用于 RBF 交易的费用规则，请参阅 [Estimate transaction fees](/v2_cn/guides/transactions/estimate-fees#replace-by-fee-rbf-transaction-fee)。 + +## 替换操作 + +WaaS 2.0 支持以下 RBF 操作： + +- **Speed up**：用更高费用的版本替换原交易，使其更快确认。请使用 [Speed up transaction](/v2/api-references/transactions/speed-up-transaction) 操作。 +- **Drop**：用可有效取消原交易的版本替换原交易。请使用 [Drop transaction](/v2/api-references/transactions/drop-transaction) 操作。 + +这两种操作仅在原交易处于 `Broadcasting` 状态时适用。它们不适用于以下链上的交易：VET、TRON、TVET、SOL 和 TON。 + +## 替换后原交易的状态 + +当替换交易生效时，原交易将转入 `Failed` 状态，子状态为 `ReplacedByNewTransaction`。有关状态和子状态的完整列表，请参阅 [Transaction statuses and sub-statuses](/v2_cn/guides/transactions/status)。 + +## 链式替换 + +任何后续的放弃或加速操作都将继续应用于原交易。例如，如果您创建交易 A，使用交易 B 对交易 A 执行放弃操作，然后使用交易 C 对交易 B 执行加速操作，则该加速操作仍将应用于交易 A，而不是交易 B。 + +## 事件 + +RBF 的状态变化通过 WaaS 2.0 交易 Webhook 事件呈现。如需了解您会收到哪些事件，请参阅 [Webhook event types](/v2_cn/guides/webhooks-callbacks/webhook-event-type)。 + +## 相关指南 + +- [Manage transactions](/v2_cn/guides/transactions/manage-transactions) +- [Estimate transaction fees](/v2_cn/guides/transactions/estimate-fees) +- [Transaction statuses and sub-statuses](/v2_cn/guides/transactions/status) +- [Transaction sources and destinations](/v2_cn/guides/transactions/sources-and-destinations) diff --git a/v2_cn/guides/transactions/sources-and-destinations.mdx b/v2_cn/guides/transactions/sources-and-destinations.mdx index 03379cfd..29fd3ddf 100644 --- a/v2_cn/guides/transactions/sources-and-destinations.mdx +++ b/v2_cn/guides/transactions/sources-and-destinations.mdx @@ -16,6 +16,8 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 如果您在 Cobo Portal 上的两个钱包之间转移代币，将记录两笔交易：一笔存入目的地钱包，一笔从来源钱包提取。 +如需控制转账是通过 Cobo Loop 内部路由还是链上路由，请参阅 [Transfer routing](/v2_cn/guides/transactions/transfer-routing)。 + | 交易类型 | 交易来源类型 | 交易目的地类型 | |----------------------------------------------------|-------------------------------------------------------------------------------------------------|--------------------------| | Deposit - [Cobo Loop](https://manuals.cobo.com/cn/portal/custodial-wallets/cobo-loop) 转账 | DepositFromLoop | DepositToAddress | diff --git a/v2_cn/guides/transactions/status.mdx b/v2_cn/guides/transactions/status.mdx index b201f1be..50217d03 100644 --- a/v2_cn/guides/transactions/status.mdx +++ b/v2_cn/guides/transactions/status.mdx @@ -274,6 +274,20 @@ WaaS 2.0 定义了各种交易状态和子状态，以反映不同的处理阶 +## 状态详情 + + +`PendingAuthorization` 状态同时涵盖人工审批步骤和内部自动检查。人工步骤包括 `PendingApproverCheck`、`PendingSpenderCheck` 和 `PendingDoubleCheck`。自动检查包括 `PendingRiskControlCheck` 和 `PendingCoboCheck`。处于 `PendingAuthorization` 状态并不一定需要人工操作，因为交易可能正在进行自动风控或合规检查。 + + + +交易经审批通过后会进入 `PendingSignature` 状态，并且必须在有限的签名时间窗口内由 MPC 签名人组完成签名。如果未能在时间窗口内完成签名，交易将自动失败并转入 `Failed` 状态，子状态为 `FailedSignerTimeout`。如需确认交易失败原因，请查看 [List all transactions](/v2/api-references/transactions/list-all-transactions) 或 [Get transaction information](/v2/api-references/transactions/get-transaction-information) 返回的 `sub_status` 字段。如果遇到 `FailedSignerTimeout`，请重新发起该交易。 + + + +处于 `Confirming` 状态且子状态为 `PendingBlockConfirmations` 的交易，正在等待其所在链所需数量的区块确认。这是正常处理过程的一部分，并不表示交易卡住。所需的确认数量和预计确认时间因链而异。 + + ## 可用操作 您可以根据交易状态执行以下操作： @@ -286,4 +300,6 @@ WaaS 2.0 定义了各种交易状态和子状态，以反映不同的处理阶 - 如果交易状态是 `Failed`，您可以重发交易。 - 如果交易状态是 `Broadcasting`，您可以加速或放弃交易。 +有关被替换交易的状态如何变化的详细信息，请参阅 [RBF (Replace-By-Fee) transaction lifecycle](/v2_cn/guides/transactions/rbf-transaction-lifecycle)。 + 有关详细信息，请参阅[管理交易](/v2_cn/guides/transactions/manage-transactions)。 \ No newline at end of file diff --git a/v2_cn/guides/transactions/transaction-process-mpc.mdx b/v2_cn/guides/transactions/transaction-process-mpc.mdx index 9ab338c8..1cad22ea 100644 --- a/v2_cn/guides/transactions/transaction-process-mpc.mdx +++ b/v2_cn/guides/transactions/transaction-process-mpc.mdx @@ -34,4 +34,8 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 提币流程 - 如果提币被拒绝或不成功，代币将返回到您的钱包，您的余额将保持不变。 -- 如果您的提币金额小于最低提币门槛，提币请求将收到错误。您可以调用 [获取代币信息](/v2/api-references/wallets/get-token-information) 操作来检索每种代币类型的最低提币金额。 \ No newline at end of file +- 如果您的提币金额小于最低提币门槛，提币请求将收到错误。您可以调用 [获取代币信息](/v2/api-references/wallets/get-token-information) 操作来检索每种代币类型的最低提币金额。 + + +提币交易经审批通过后会进入 `PendingSignature` 状态，并且必须在有限的签名时间窗口内由 MPC 签名人组完成签名。如果未能在时间窗口内完成签名，交易将自动失败并转入 `Failed` 状态，子状态为 `FailedSignerTimeout`。您可以通过 [Get transaction information](/v2/api-references/transactions/get-transaction-information) 返回的 `sub_status` 字段确认失败原因，然后重新发起该交易。 + \ No newline at end of file diff --git a/v2_cn/guides/transactions/transfer-routing.mdx b/v2_cn/guides/transactions/transfer-routing.mdx new file mode 100644 index 00000000..d5c4a184 --- /dev/null +++ b/v2_cn/guides/transactions/transfer-routing.mdx @@ -0,0 +1,38 @@ +--- +title: "转账路由" +lang: "zh-hans" +description: "了解代币转账如何通过 Cobo Loop 内部路由或链上外部路由，以及如何使用请求参数控制路由。" +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; + + + +## 概述 + +每笔代币转账都会通过内部或外部路由： + +- **内部路由**：当目的地支持时，通过 Cobo Loop 转账网络在 Cobo Portal 账户之间以链下方式结算。 +- **外部路由**：将交易广播到区块链上。 + +## 使用请求参数控制路由 + +[Transfer token](/v2/api-references/transactions/transfer-token) 操作提供两个布尔参数来控制路由：`force_internal` 和 `force_external`。 + +| 设置 | 路由行为 | +|---------|------------------| +| `force_internal` = `true` | 强制通过 Cobo Loop 进行内部路由（链下）。 | +| `force_external` = `true` | 强制进行链上外部路由。 | +| 两者均为 `false`（默认） | 如果目的地支持，则通过 Cobo Loop 路由；否则进行链上路由。 | +| 两者均为 `true` | 请求将被拒绝。 | + +部分目的地不支持这些参数。 + +## 对生成交易的影响 + +内部路由生成链下的 Cobo Loop 转账。外部路由生成链上交易。 + +## 相关指南 + +- [Transaction sources and destinations](/v2_cn/guides/transactions/sources-and-destinations) +- [Cobo Loop](https://manuals.cobo.com/en/portal/custodial-wallets/cobo-loop) From f9d4c4b4bf858d79cfad7de1a519dadc5934be5c Mon Sep 17 00:00:00 2001 From: rcsh <163504257+rcsh1@users.noreply.github.com> Date: Wed, 24 Jun 2026 08:29:39 +0800 Subject: [PATCH 2/7] docs: address review feedback --- docs.json | 2 ++ v2/guides/transactions/estimate-fees.mdx | 5 ++++- .../transactions/rbf-transaction-lifecycle.mdx | 2 +- v2/guides/transactions/status.mdx | 2 +- v2/guides/transactions/transaction-process-mpc.mdx | 2 +- v2/guides/transactions/transfer-routing.mdx | 8 ++------ v2_cn/guides/transactions/estimate-fees.mdx | 5 ++++- v2_cn/guides/transactions/manage-transactions.mdx | 2 +- .../transactions/rbf-transaction-lifecycle.mdx | 14 +++++++------- v2_cn/guides/transactions/status.mdx | 4 ++-- .../transactions/transaction-process-mpc.mdx | 2 +- v2_cn/guides/transactions/transfer-routing.mdx | 12 ++++-------- 12 files changed, 30 insertions(+), 30 deletions(-) diff --git a/docs.json b/docs.json index 3f4d8538..ec53f022 100644 --- a/docs.json +++ b/docs.json @@ -862,6 +862,7 @@ "group": "交易", "pages": [ "v2_cn/guides/transactions/sources-and-destinations", + "v2_cn/guides/transactions/transfer-routing", "v2_cn/guides/transactions/estimate-fees", { "group": "交易状态", @@ -872,6 +873,7 @@ ] }, "v2_cn/guides/transactions/manage-transactions", + "v2_cn/guides/transactions/rbf-transaction-lifecycle", { "group": "智能合约调用示例", "pages": [ diff --git a/v2/guides/transactions/estimate-fees.mdx b/v2/guides/transactions/estimate-fees.mdx index b58dada1..d88beeec 100644 --- a/v2/guides/transactions/estimate-fees.mdx +++ b/v2/guides/transactions/estimate-fees.mdx @@ -176,7 +176,10 @@ The logic for estimating RBF transaction fees is similar to that for normal tran ## Fees on Layer 2 chains -On Layer 2 (L2) chains such as Arbitrum, network fees can change rapidly. If fees rise sharply after you submit a transaction, the transaction can remain in the `PendingSignature` or `Broadcasting` status longer than expected. To unblock such a transaction, use the Replace-By-Fee (RBF) speed-up operation to rebroadcast it with a higher fee. For how RBF works end to end, see [RBF (Replace-By-Fee) transaction lifecycle](/v2/guides/transactions/rbf-transaction-lifecycle). To raise the fee, use the [Speed up transaction](/v2/api-references/transactions/speed-up-transaction) operation. +On Layer 2 (L2) chains such as Arbitrum, network fees can change rapidly. If fees rise sharply after you submit a transaction, the transaction can remain in the `PendingSignature` or `Broadcasting` status longer than expected. How you unblock it depends on the status: + +- `Broadcasting`: The transaction is already broadcast. Use the Replace-By-Fee (RBF) speed-up operation to rebroadcast it with a higher fee. To raise the fee, use the [Speed up transaction](/v2/api-references/transactions/speed-up-transaction) operation. For how RBF works end to end, see [RBF (Replace-By-Fee) transaction lifecycle](/v2/guides/transactions/rbf-transaction-lifecycle). +- `PendingSignature`: The transaction is not yet broadcast, so RBF does not apply. The transaction must be signed within a limited signing window; if signing does not complete in time, it fails with the sub-status `FailedSignerTimeout`. In that case, submit a new transaction to try again. For details, see [Transaction statuses and sub-statuses](/v2/guides/transactions/status). ## How Cobo estimate the fees diff --git a/v2/guides/transactions/rbf-transaction-lifecycle.mdx b/v2/guides/transactions/rbf-transaction-lifecycle.mdx index 8df9ebd5..51b8b8ff 100644 --- a/v2/guides/transactions/rbf-transaction-lifecycle.mdx +++ b/v2/guides/transactions/rbf-transaction-lifecycle.mdx @@ -33,7 +33,7 @@ Any subsequent drop or speed-up operations continue to apply to the original tra ## Events -RBF status changes are surfaced through the WaaS 2.0 transaction webhook events. To learn which events you receive, see [Webhook event types](/v2/guides/webhooks-callbacks/webhook-event-type). +RBF status changes are surfaced through the WaaS 2.0 transaction webhook events. Subscribe to the `wallets.transaction.updated` event, which covers the full transaction lifecycle including failure. For details, see [Webhook event types](/v2/guides/webhooks-callbacks/webhook-event-type). ## Related guides diff --git a/v2/guides/transactions/status.mdx b/v2/guides/transactions/status.mdx index 363ab4e0..04956b30 100644 --- a/v2/guides/transactions/status.mdx +++ b/v2/guides/transactions/status.mdx @@ -281,7 +281,7 @@ The `PendingAuthorization` status aggregates both manual approval steps and inte -After a transaction is approved, it enters the `PendingSignature` status and must be signed by the MPC signer group within a limited signing window. If signing does not complete within this window, the transaction automatically fails and moves to the `Failed` status with the sub-status `FailedSignerTimeout`. To find out why a transaction failed, check the `sub_status` field returned by [List all transactions](/v2/api-references/transactions/list-all-transactions) or [Get transaction information](/v2/api-references/transactions/get-transaction-information). If you encounter `FailedSignerTimeout`, resend the transaction to try again. +After a transaction is approved, it enters the `PendingSignature` status and must be signed by the MPC signer group within a limited signing window. If signing does not complete within this window, the transaction automatically fails and moves to the `Failed` status with the sub-status `FailedSignerTimeout`. To find out why a transaction failed, check the `sub_status` field returned by [List all transactions](/v2/api-references/transactions/list-all-transactions) or [Get transaction information](/v2/api-references/transactions/get-transaction-information). If you encounter `FailedSignerTimeout`, the transaction is in a terminal `Failed` state and cannot be resumed. Submit a new transaction to try again — for example, initiate a new transfer with the [Transfer token](/v2/api-references/transactions/transfer-token) operation. diff --git a/v2/guides/transactions/transaction-process-mpc.mdx b/v2/guides/transactions/transaction-process-mpc.mdx index 3041a8c8..f003d4f0 100644 --- a/v2/guides/transactions/transaction-process-mpc.mdx +++ b/v2/guides/transactions/transaction-process-mpc.mdx @@ -36,5 +36,5 @@ The following diagram illustrates how a withdrawal is processed. Colors are used - If your withdrawal amount is smaller than the minimum withdrawal threshold, the withdrawal request will receive an error. You can call the [Get token information](/v2/api-references/wallets/get-token-information) operation to retrieve the minimum withdrawal amount for each token type. -After a withdrawal is approved, it enters the `PendingSignature` status and must be signed by the MPC signer group within a limited signing window. If signing does not complete in time, the transaction automatically fails and moves to the `Failed` status with the sub-status `FailedSignerTimeout`. To confirm the reason, check the `sub_status` field returned by [Get transaction information](/v2/api-references/transactions/get-transaction-information), then resend the transaction to try again. +After a withdrawal is approved, it enters the `PendingSignature` status and must be signed by the MPC signer group within a limited signing window. If signing does not complete in time, the transaction automatically fails and moves to the `Failed` status with the sub-status `FailedSignerTimeout`. To confirm the reason, check the `sub_status` field returned by [Get transaction information](/v2/api-references/transactions/get-transaction-information). Because `FailedSignerTimeout` is a terminal `Failed` state, submit a new transaction to try again — for example, initiate a new transfer with the [Transfer token](/v2/api-references/transactions/transfer-token) operation. \ No newline at end of file diff --git a/v2/guides/transactions/transfer-routing.mdx b/v2/guides/transactions/transfer-routing.mdx index 95f897d4..0a0c54de 100644 --- a/v2/guides/transactions/transfer-routing.mdx +++ b/v2/guides/transactions/transfer-routing.mdx @@ -24,13 +24,9 @@ The [Transfer token](/v2/api-references/transactions/transfer-token) operation p | `force_internal` = `true` | Forces internal routing through Cobo Loop (off-chain). | | `force_external` = `true` | Forces external on-chain routing. | | Both `false` (default) | Routes through Cobo Loop if the destination supports it; otherwise routes on-chain. | -| Both `true` | The request is rejected. | +| Both `true` | The request is rejected with an HTTP 400 error (error code `2006`, invalid parameter). | -Some destinations do not support these parameters. - -## Effect on the resulting transaction - -Internal routing produces an off-chain Cobo Loop transfer. External routing produces an on-chain transaction. +These parameters are available only for transfers to an address destination. For the supported destination types, see the [Transfer token](/v2/api-references/transactions/transfer-token) operation. ## Related guides diff --git a/v2_cn/guides/transactions/estimate-fees.mdx b/v2_cn/guides/transactions/estimate-fees.mdx index 8571f0e9..1055d6db 100644 --- a/v2_cn/guides/transactions/estimate-fees.mdx +++ b/v2_cn/guides/transactions/estimate-fees.mdx @@ -178,7 +178,10 @@ Replace-By-Fee (RBF) 是一种允许您用新版本替换未确认交易的功 ## Layer 2 链上的费用 -在 Arbitrum 等 Layer 2（L2）链上，网络费用可能快速变化。如果您提交交易后费用大幅上涨，交易可能会比预期更长时间地停留在 `PendingSignature` 或 `Broadcasting` 状态。如需解除此类交易的阻塞，可以使用 Replace-By-Fee（RBF）加速操作，以更高的费用重新广播交易。有关 RBF 的完整流程，请参阅 [RBF (Replace-By-Fee) transaction lifecycle](/v2_cn/guides/transactions/rbf-transaction-lifecycle)。如需提高费用，请使用 [Speed up transaction](/v2/api-references/transactions/speed-up-transaction) 操作。 +在 Arbitrum 等 Layer 2（L2）链上，网络费用可能快速变化。如果您提交交易后费用大幅上涨，交易可能会比预期更长时间地停留在 `PendingSignature` 或 `Broadcasting` 状态。解除阻塞的方式取决于交易状态： + +- `Broadcasting`：交易已广播。可以使用 Replace-By-Fee（RBF）加速操作，以更高的费用重新广播交易。如需提高费用，请使用 [Speed up transaction](/v2/api-references/transactions/speed-up-transaction) 操作。有关 RBF 的完整流程，请参阅 [RBF (Replace-By-Fee) 交易生命周期](/v2_cn/guides/transactions/rbf-transaction-lifecycle)。 +- `PendingSignature`：交易尚未广播，因此 RBF 不适用。交易必须在有限的签名时间窗口内完成签名；如果未能及时完成签名，交易将失败并显示子状态 `FailedSignerTimeout`。此时请重新发起一笔新交易。有关详细信息，请参阅 [交易状态和子状态](/v2_cn/guides/transactions/status)。 ## Cobo 如何估算费用 diff --git a/v2_cn/guides/transactions/manage-transactions.mdx b/v2_cn/guides/transactions/manage-transactions.mdx index 7ceb13f5..780d8d46 100644 --- a/v2_cn/guides/transactions/manage-transactions.mdx +++ b/v2_cn/guides/transactions/manage-transactions.mdx @@ -36,7 +36,7 @@ Replace-By-Fee (RBF) 是一种允许您用新版本替换未确认交易的功 RBF 的两个最常见用例是加速和放弃交易。 -有关被替换交易的状态变化及其触发的事件，请参阅 [RBF (Replace-By-Fee) transaction lifecycle](/v2_cn/guides/transactions/rbf-transaction-lifecycle)。 +有关被替换交易的状态变化及其触发的事件，请参阅 [RBF (Replace-By-Fee) 交易生命周期](/v2_cn/guides/transactions/rbf-transaction-lifecycle)。 ### 加速交易 diff --git a/v2_cn/guides/transactions/rbf-transaction-lifecycle.mdx b/v2_cn/guides/transactions/rbf-transaction-lifecycle.mdx index 98fc9c20..6d1a5593 100644 --- a/v2_cn/guides/transactions/rbf-transaction-lifecycle.mdx +++ b/v2_cn/guides/transactions/rbf-transaction-lifecycle.mdx @@ -12,7 +12,7 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; Replace-By-Fee (RBF) 使用新版本替换已广播但尚未确认的交易。本指南介绍 RBF 替换的完整生命周期：您可以执行的替换操作、原交易的状态如何变化，以及您会收到哪些事件。 -有关分步操作，请参阅 [Manage transactions](/v2_cn/guides/transactions/manage-transactions)。有关适用于 RBF 交易的费用规则，请参阅 [Estimate transaction fees](/v2_cn/guides/transactions/estimate-fees#replace-by-fee-rbf-transaction-fee)。 +有关分步操作，请参阅 [管理交易](/v2_cn/guides/transactions/manage-transactions)。有关适用于 RBF 交易的费用规则，请参阅 [估算交易费用](/v2_cn/guides/transactions/estimate-fees#replace-by-fee-rbf-交易费用)。 ## 替换操作 @@ -25,7 +25,7 @@ WaaS 2.0 支持以下 RBF 操作： ## 替换后原交易的状态 -当替换交易生效时，原交易将转入 `Failed` 状态，子状态为 `ReplacedByNewTransaction`。有关状态和子状态的完整列表，请参阅 [Transaction statuses and sub-statuses](/v2_cn/guides/transactions/status)。 +当替换交易生效时，原交易将转入 `Failed` 状态，子状态为 `ReplacedByNewTransaction`。有关状态和子状态的完整列表，请参阅 [交易状态和子状态](/v2_cn/guides/transactions/status)。 ## 链式替换 @@ -33,11 +33,11 @@ WaaS 2.0 支持以下 RBF 操作： ## 事件 -RBF 的状态变化通过 WaaS 2.0 交易 Webhook 事件呈现。如需了解您会收到哪些事件，请参阅 [Webhook event types](/v2_cn/guides/webhooks-callbacks/webhook-event-type)。 +RBF 的状态变化通过 WaaS 2.0 交易 Webhook 事件呈现。请订阅 `wallets.transaction.updated` 事件，该事件覆盖交易的完整生命周期（包括失败）。有关详细信息，请参阅 [Webhook 事件类型和数据类型](/v2_cn/guides/webhooks-callbacks/webhook-event-type)。 ## 相关指南 -- [Manage transactions](/v2_cn/guides/transactions/manage-transactions) -- [Estimate transaction fees](/v2_cn/guides/transactions/estimate-fees) -- [Transaction statuses and sub-statuses](/v2_cn/guides/transactions/status) -- [Transaction sources and destinations](/v2_cn/guides/transactions/sources-and-destinations) +- [管理交易](/v2_cn/guides/transactions/manage-transactions) +- [估算交易费用](/v2_cn/guides/transactions/estimate-fees) +- [交易状态和子状态](/v2_cn/guides/transactions/status) +- [交易来源和目的地](/v2_cn/guides/transactions/sources-and-destinations) diff --git a/v2_cn/guides/transactions/status.mdx b/v2_cn/guides/transactions/status.mdx index 50217d03..22cd01f9 100644 --- a/v2_cn/guides/transactions/status.mdx +++ b/v2_cn/guides/transactions/status.mdx @@ -281,7 +281,7 @@ WaaS 2.0 定义了各种交易状态和子状态，以反映不同的处理阶 -交易经审批通过后会进入 `PendingSignature` 状态，并且必须在有限的签名时间窗口内由 MPC 签名人组完成签名。如果未能在时间窗口内完成签名，交易将自动失败并转入 `Failed` 状态，子状态为 `FailedSignerTimeout`。如需确认交易失败原因，请查看 [List all transactions](/v2/api-references/transactions/list-all-transactions) 或 [Get transaction information](/v2/api-references/transactions/get-transaction-information) 返回的 `sub_status` 字段。如果遇到 `FailedSignerTimeout`，请重新发起该交易。 +交易经审批通过后会进入 `PendingSignature` 状态，并且必须在有限的签名时间窗口内由 MPC 签名人组完成签名。如果未能在时间窗口内完成签名，交易将自动失败并转入 `Failed` 状态，子状态为 `FailedSignerTimeout`。如需确认交易失败原因，请查看 [List all transactions](/v2/api-references/transactions/list-all-transactions) 或 [Get transaction information](/v2/api-references/transactions/get-transaction-information) 返回的 `sub_status` 字段。如果遇到 `FailedSignerTimeout`，该交易已处于终态 `Failed`，无法恢复。请重新发起一笔新交易以重试，例如通过 [Transfer token](/v2/api-references/transactions/transfer-token) 操作发起一笔新转账。 @@ -300,6 +300,6 @@ WaaS 2.0 定义了各种交易状态和子状态，以反映不同的处理阶 - 如果交易状态是 `Failed`，您可以重发交易。 - 如果交易状态是 `Broadcasting`，您可以加速或放弃交易。 -有关被替换交易的状态如何变化的详细信息，请参阅 [RBF (Replace-By-Fee) transaction lifecycle](/v2_cn/guides/transactions/rbf-transaction-lifecycle)。 +有关被替换交易的状态如何变化的详细信息，请参阅 [RBF (Replace-By-Fee) 交易生命周期](/v2_cn/guides/transactions/rbf-transaction-lifecycle)。 有关详细信息，请参阅[管理交易](/v2_cn/guides/transactions/manage-transactions)。 \ No newline at end of file diff --git a/v2_cn/guides/transactions/transaction-process-mpc.mdx b/v2_cn/guides/transactions/transaction-process-mpc.mdx index 1cad22ea..51ae3dbf 100644 --- a/v2_cn/guides/transactions/transaction-process-mpc.mdx +++ b/v2_cn/guides/transactions/transaction-process-mpc.mdx @@ -37,5 +37,5 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; - 如果您的提币金额小于最低提币门槛，提币请求将收到错误。您可以调用 [获取代币信息](/v2/api-references/wallets/get-token-information) 操作来检索每种代币类型的最低提币金额。 -提币交易经审批通过后会进入 `PendingSignature` 状态，并且必须在有限的签名时间窗口内由 MPC 签名人组完成签名。如果未能在时间窗口内完成签名，交易将自动失败并转入 `Failed` 状态，子状态为 `FailedSignerTimeout`。您可以通过 [Get transaction information](/v2/api-references/transactions/get-transaction-information) 返回的 `sub_status` 字段确认失败原因，然后重新发起该交易。 +提币交易经审批通过后会进入 `PendingSignature` 状态，并且必须在有限的签名时间窗口内由 MPC 签名人组完成签名。如果未能在时间窗口内完成签名，交易将自动失败并转入 `Failed` 状态，子状态为 `FailedSignerTimeout`。您可以通过 [Get transaction information](/v2/api-references/transactions/get-transaction-information) 返回的 `sub_status` 字段确认失败原因。由于 `FailedSignerTimeout` 为终态 `Failed`，请重新发起一笔新交易以重试，例如通过 [Transfer token](/v2/api-references/transactions/transfer-token) 操作发起一笔新转账。 \ No newline at end of file diff --git a/v2_cn/guides/transactions/transfer-routing.mdx b/v2_cn/guides/transactions/transfer-routing.mdx index d5c4a184..956e7b37 100644 --- a/v2_cn/guides/transactions/transfer-routing.mdx +++ b/v2_cn/guides/transactions/transfer-routing.mdx @@ -24,15 +24,11 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; | `force_internal` = `true` | 强制通过 Cobo Loop 进行内部路由（链下）。 | | `force_external` = `true` | 强制进行链上外部路由。 | | 两者均为 `false`（默认） | 如果目的地支持，则通过 Cobo Loop 路由；否则进行链上路由。 | -| 两者均为 `true` | 请求将被拒绝。 | +| 两者均为 `true` | 请求将被拒绝，返回 HTTP 400 错误（错误码 `2006`，参数无效）。 | -部分目的地不支持这些参数。 - -## 对生成交易的影响 - -内部路由生成链下的 Cobo Loop 转账。外部路由生成链上交易。 +这些参数仅适用于目的地为地址的转账。有关支持的目的地类型，请参阅 [Transfer token](/v2/api-references/transactions/transfer-token) 操作。 ## 相关指南 -- [Transaction sources and destinations](/v2_cn/guides/transactions/sources-and-destinations) -- [Cobo Loop](https://manuals.cobo.com/en/portal/custodial-wallets/cobo-loop) +- [交易来源和目的地](/v2_cn/guides/transactions/sources-and-destinations) +- [Cobo Loop](https://manuals.cobo.com/cn/portal/custodial-wallets/cobo-loop) From 25d69579891e6946e4705168ebf4b5ee2352d7f6 Mon Sep 17 00:00:00 2001 From: rcsh <163504257+rcsh1@users.noreply.github.com> Date: Thu, 25 Jun 2026 14:54:33 +0800 Subject: [PATCH 3/7] docs: refine transaction routing wording --- v2/guides/transactions/transfer-routing.mdx | 16 ++++++++-------- .../transactions/transaction-process-mpc.mdx | 6 +++--- v2_cn/guides/transactions/transfer-routing.mdx | 16 ++++++++-------- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/v2/guides/transactions/transfer-routing.mdx b/v2/guides/transactions/transfer-routing.mdx index 0a0c54de..5f3b2044 100644 --- a/v2/guides/transactions/transfer-routing.mdx +++ b/v2/guides/transactions/transfer-routing.mdx @@ -1,7 +1,7 @@ --- title: "Transfer routing" lang: "en" -description: "Understand how token transfers are routed internally through Cobo Loop or externally on-chain, and how to control routing with request parameters." +description: "Understand how token transfers are processed as Cobo Loop transfers or on-chain transfers, and how to control that behavior with request parameters." --- import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx'; @@ -10,20 +10,20 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx'; ## Overview -Every token transfer is routed either internally or externally: +Every token transfer is processed in one of the following ways: -- **Internal routing** settles off-chain between accounts on Cobo Portal through the Cobo Loop transfer network, when the destination supports it. -- **External routing** broadcasts the transaction on the blockchain. +- **Cobo Loop transfer** settles off-chain between accounts on Cobo Portal through the Cobo Loop transfer network, when the destination supports it. +- **On-chain transfer** broadcasts the transaction to the blockchain. ## Control routing with request parameters -The [Transfer token](/v2/api-references/transactions/transfer-token) operation provides two boolean parameters to control routing: `force_internal` and `force_external`. +The [Transfer token](/v2/api-references/transactions/transfer-token) operation provides two boolean parameters to control whether the transfer uses Cobo Loop or is sent on-chain: `force_internal` and `force_external`. | Setting | Routing behavior | |---------|------------------| -| `force_internal` = `true` | Forces internal routing through Cobo Loop (off-chain). | -| `force_external` = `true` | Forces external on-chain routing. | -| Both `false` (default) | Routes through Cobo Loop if the destination supports it; otherwise routes on-chain. | +| `force_internal` = `true` | Forces the transfer to use Cobo Loop (off-chain). | +| `force_external` = `true` | Forces the transfer to be sent on-chain. | +| Both `false` (default) | Uses Cobo Loop if the destination supports it; otherwise sends the transfer on-chain. | | Both `true` | The request is rejected with an HTTP 400 error (error code `2006`, invalid parameter). | These parameters are available only for transfers to an address destination. For the supported destination types, see the [Transfer token](/v2/api-references/transactions/transfer-token) operation. diff --git a/v2_cn/guides/transactions/transaction-process-mpc.mdx b/v2_cn/guides/transactions/transaction-process-mpc.mdx index 51ae3dbf..e6017335 100644 --- a/v2_cn/guides/transactions/transaction-process-mpc.mdx +++ b/v2_cn/guides/transactions/transaction-process-mpc.mdx @@ -17,7 +17,7 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 充币流程 - 如果充币交易违反合规规定，Cobo 保留拒绝该交易的权利。 -- 如果交易金额低于最低充币门槛，交易将不会被处理，也不会创建任何记录。您可以调用 [获取代币信息](/v2/api-references/wallets/get-token-information) 操作来检索每种代币类型的最低充币金额。 +- 如果交易金额低于最低充币门槛，交易将不会被处理，也不会创建任何记录。您可以调用 [Get token information](/v2/api-references/wallets/get-token-information) 操作来检索每种代币类型的最低充币金额。 ## 提币流程 @@ -34,8 +34,8 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 提币流程 - 如果提币被拒绝或不成功，代币将返回到您的钱包，您的余额将保持不变。 -- 如果您的提币金额小于最低提币门槛，提币请求将收到错误。您可以调用 [获取代币信息](/v2/api-references/wallets/get-token-information) 操作来检索每种代币类型的最低提币金额。 +- 如果您的提币金额小于最低提币门槛，提币请求将收到错误。您可以调用 [Get token information](/v2/api-references/wallets/get-token-information) 操作来检索每种代币类型的最低提币金额。 提币交易经审批通过后会进入 `PendingSignature` 状态，并且必须在有限的签名时间窗口内由 MPC 签名人组完成签名。如果未能在时间窗口内完成签名，交易将自动失败并转入 `Failed` 状态，子状态为 `FailedSignerTimeout`。您可以通过 [Get transaction information](/v2/api-references/transactions/get-transaction-information) 返回的 `sub_status` 字段确认失败原因。由于 `FailedSignerTimeout` 为终态 `Failed`，请重新发起一笔新交易以重试，例如通过 [Transfer token](/v2/api-references/transactions/transfer-token) 操作发起一笔新转账。 - \ No newline at end of file + diff --git a/v2_cn/guides/transactions/transfer-routing.mdx b/v2_cn/guides/transactions/transfer-routing.mdx index 956e7b37..940670d3 100644 --- a/v2_cn/guides/transactions/transfer-routing.mdx +++ b/v2_cn/guides/transactions/transfer-routing.mdx @@ -1,7 +1,7 @@ --- title: "转账路由" lang: "zh-hans" -description: "了解代币转账如何通过 Cobo Loop 内部路由或链上外部路由，以及如何使用请求参数控制路由。" +description: "了解代币转账如何通过 Cobo Loop 转账或链上转账处理，以及如何使用请求参数控制该行为。" --- import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; @@ -10,20 +10,20 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; ## 概述 -每笔代币转账都会通过内部或外部路由： +每笔代币转账都会以下列方式之一处理： -- **内部路由**：当目的地支持时，通过 Cobo Loop 转账网络在 Cobo Portal 账户之间以链下方式结算。 -- **外部路由**：将交易广播到区块链上。 +- **Cobo Loop 转账**：当目的地支持时，通过 Cobo Loop 转账网络在 Cobo Portal 账户之间以链下方式结算。 +- **链上转账**：将交易广播到区块链上。 ## 使用请求参数控制路由 -[Transfer token](/v2/api-references/transactions/transfer-token) 操作提供两个布尔参数来控制路由：`force_internal` 和 `force_external`。 +[Transfer token](/v2/api-references/transactions/transfer-token) 操作提供两个布尔参数，用于控制转账是使用 Cobo Loop 还是发送到链上：`force_internal` 和 `force_external`。 | 设置 | 路由行为 | |---------|------------------| -| `force_internal` = `true` | 强制通过 Cobo Loop 进行内部路由（链下）。 | -| `force_external` = `true` | 强制进行链上外部路由。 | -| 两者均为 `false`（默认） | 如果目的地支持，则通过 Cobo Loop 路由；否则进行链上路由。 | +| `force_internal` = `true` | 强制转账使用 Cobo Loop（链下）。 | +| `force_external` = `true` | 强制转账发送到链上。 | +| 两者均为 `false`（默认） | 如果目的地支持，则使用 Cobo Loop；否则发送到链上。 | | 两者均为 `true` | 请求将被拒绝，返回 HTTP 400 错误（错误码 `2006`，参数无效）。 | 这些参数仅适用于目的地为地址的转账。有关支持的目的地类型，请参阅 [Transfer token](/v2/api-references/transactions/transfer-token) 操作。 From 325701c1b5bafb2659e0bdb1854c16bf1326de90 Mon Sep 17 00:00:00 2001 From: rcsh <163504257+rcsh1@users.noreply.github.com> Date: Thu, 2 Jul 2026 10:57:23 +0800 Subject: [PATCH 4/7] docs: address remaining review comments on transaction lifecycle PR - CN upgrade-guide.mdx: restore WaaS 2.0 API operation names to English (Create wallet, Create addresses in wallet, Transfer token, Speed up transaction, Drop transaction, Cancel transaction, Call smart contract, Sign message, List all transactions, Get transaction information) - transfer-routing.mdx EN+CN: add note clarifying force_internal / force_external are mutually exclusive, and add JSON code examples showing force-Cobo-Loop, force-on-chain, and default routing - status.mdx EN+CN: update FailedSignerTimeout remedy to specify retry operation by original transaction type (Transfer token / Call smart contract / Sign message) instead of always pointing to Transfer token Co-Authored-By: Claude Sonnet 4.6 --- v2/guides/transactions/status.mdx | 2 +- v2/guides/transactions/transfer-routing.mdx | 38 +++++++++++++++++++ v2_cn/guides/overview/upgrade-guide.mdx | 18 ++++----- v2_cn/guides/transactions/status.mdx | 2 +- .../guides/transactions/transfer-routing.mdx | 38 +++++++++++++++++++ 5 files changed, 87 insertions(+), 11 deletions(-) diff --git a/v2/guides/transactions/status.mdx b/v2/guides/transactions/status.mdx index 04956b30..97757df1 100644 --- a/v2/guides/transactions/status.mdx +++ b/v2/guides/transactions/status.mdx @@ -281,7 +281,7 @@ The `PendingAuthorization` status aggregates both manual approval steps and inte -After a transaction is approved, it enters the `PendingSignature` status and must be signed by the MPC signer group within a limited signing window. If signing does not complete within this window, the transaction automatically fails and moves to the `Failed` status with the sub-status `FailedSignerTimeout`. To find out why a transaction failed, check the `sub_status` field returned by [List all transactions](/v2/api-references/transactions/list-all-transactions) or [Get transaction information](/v2/api-references/transactions/get-transaction-information). If you encounter `FailedSignerTimeout`, the transaction is in a terminal `Failed` state and cannot be resumed. Submit a new transaction to try again — for example, initiate a new transfer with the [Transfer token](/v2/api-references/transactions/transfer-token) operation. +After a transaction is approved, it enters the `PendingSignature` status and must be signed by the MPC signer group within a limited signing window. If signing does not complete within this window, the transaction automatically fails and moves to the `Failed` status with the sub-status `FailedSignerTimeout`. To find out why a transaction failed, check the `sub_status` field returned by [List all transactions](/v2/api-references/transactions/list-all-transactions) or [Get transaction information](/v2/api-references/transactions/get-transaction-information). If you encounter `FailedSignerTimeout`, the transaction is in a terminal `Failed` state and cannot be resumed. Submit a new transaction of the same type to try again: use [Transfer token](/v2/api-references/transactions/transfer-token) for token transfers, [Call smart contract](/v2/api-references/transactions/call-smart-contract) for contract calls, or [Sign message](/v2/api-references/transactions/sign-message) for message signing. diff --git a/v2/guides/transactions/transfer-routing.mdx b/v2/guides/transactions/transfer-routing.mdx index 5f3b2044..6bd3e295 100644 --- a/v2/guides/transactions/transfer-routing.mdx +++ b/v2/guides/transactions/transfer-routing.mdx @@ -28,6 +28,44 @@ The [Transfer token](/v2/api-references/transactions/transfer-token) operation p These parameters are available only for transfers to an address destination. For the supported destination types, see the [Transfer token](/v2/api-references/transactions/transfer-token) operation. +`force_internal` and `force_external` are mutually exclusive: setting both to `true` in the same request is invalid and returns an HTTP 400 error (error code `2006`). To force a specific routing, set only one to `true` and leave the other as `false` (or omit it). + +The following examples show how to set the routing parameters in a [Transfer token](/v2/api-references/transactions/transfer-token) request body: + +```json Force Cobo Loop transfer +{ + "request_id": "your_unique_request_id", + "source": { ... }, + "destination": { ... }, + "token_id": "ETH_USDT", + "amount": "100", + "force_internal": true, + "force_external": false +} +``` + +```json Force on-chain transfer +{ + "request_id": "your_unique_request_id", + "source": { ... }, + "destination": { ... }, + "token_id": "ETH_USDT", + "amount": "100", + "force_internal": false, + "force_external": true +} +``` + +```json Default routing (Cobo Loop if supported, otherwise on-chain) +{ + "request_id": "your_unique_request_id", + "source": { ... }, + "destination": { ... }, + "token_id": "ETH_USDT", + "amount": "100" +} +``` + ## Related guides - [Transaction sources and destinations](/v2/guides/transactions/sources-and-destinations) diff --git a/v2_cn/guides/overview/upgrade-guide.mdx b/v2_cn/guides/overview/upgrade-guide.mdx index c84ab8cd..ba462ce0 100644 --- a/v2_cn/guides/overview/upgrade-guide.mdx +++ b/v2_cn/guides/overview/upgrade-guide.mdx @@ -62,15 +62,15 @@ WaaS 2.0 相较于 WaaS 1.0 进行了重大升级，面向支付、代币化、 | | WaaS 1.0 | WaaS 2.0 | | -------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -| 创建钱包 | 不支持，因为 API Key 是钱包特定的 | [创建钱包](/v2/api-references/wallets/create-wallet) | -| 创建地址 |
  • **[全托管钱包]** [获取新充币地址](/v1/api-references/custody-wallet/new_address)
  • **[MPC 钱包]** [生成地址](/v1/api-references/mpc-wallet/mpc_generate_addresses) 和 [生成地址备注](/v1/api-references/mpc-wallet/mpc_generate_address_memo)
| [在钱包中创建地址](/v2/api-references/wallets/create-addresses-in-wallet) | -| 提取代币 |
  • **[全托管钱包]** [新建提币请求](/v1/api-references/custody-wallet/new_withdraw_request)
  • **[MPC 钱包]** [创建交易](/v1/api-references/mpc-wallet/mpc_create_transaction)
| [转账代币](/v2/api-references/transactions/transfer-token) | -| RBF 交易（加速） | **[MPC 钱包]** [加速交易](/v1/api-references/mpc-wallet/mpc_speedup_transaction) | [加速交易](/v2/api-references/transactions/speed-up-transaction) | -| RBF 交易（放弃） | **[MPC 钱包]** [放弃交易](/v1/api-references/mpc-wallet/mpc_drop_transaction) | [放弃交易](/v2/api-references/transactions/drop-transaction) | -| 取消交易 | 不支持 | [取消交易](/v2/api-references/transactions/cancel-transaction) | -| 调用合约 | 不支持 | [调用智能合约](/v2/api-references/transactions/call-smart-contract) | -| 签名消息 | 不支持 | [签名消息](/v2/api-references/transactions/sign-message) | -| 查询交易 |
  • **[全托管钱包]** [交易历史](/v1/api-references/custody-wallet/transaction_history)
  • **[MPC 钱包]** [获取交易列表](/v1/api-references/mpc-wallet/mpc_list_transactions)
|
  • [列出所有交易](/v2/api-references/transactions/list-all-transactions)
  • [获取交易信息](/v2/api-references/transactions/get-transaction-information)
| +| 创建钱包 | 不支持，因为 API Key 是钱包特定的 | [Create wallet](/v2/api-references/wallets/create-wallet) | +| 创建地址 |
  • **[全托管钱包]** [获取新充币地址](/v1/api-references/custody-wallet/new_address)
  • **[MPC 钱包]** [生成地址](/v1/api-references/mpc-wallet/mpc_generate_addresses) 和 [生成地址备注](/v1/api-references/mpc-wallet/mpc_generate_address_memo)
| [Create addresses in wallet](/v2/api-references/wallets/create-addresses-in-wallet) | +| 提取代币 |
  • **[全托管钱包]** [新建提币请求](/v1/api-references/custody-wallet/new_withdraw_request)
  • **[MPC 钱包]** [创建交易](/v1/api-references/mpc-wallet/mpc_create_transaction)
| [Transfer token](/v2/api-references/transactions/transfer-token) | +| RBF 交易（加速） | **[MPC 钱包]** [加速交易](/v1/api-references/mpc-wallet/mpc_speedup_transaction) | [Speed up transaction](/v2/api-references/transactions/speed-up-transaction) | +| RBF 交易（放弃） | **[MPC 钱包]** [放弃交易](/v1/api-references/mpc-wallet/mpc_drop_transaction) | [Drop transaction](/v2/api-references/transactions/drop-transaction) | +| 取消交易 | 不支持 | [Cancel transaction](/v2/api-references/transactions/cancel-transaction) | +| 调用合约 | 不支持 | [Call smart contract](/v2/api-references/transactions/call-smart-contract) | +| 签名消息 | 不支持 | [Sign message](/v2/api-references/transactions/sign-message) | +| 查询交易 |
  • **[全托管钱包]** [交易历史](/v1/api-references/custody-wallet/transaction_history)
  • **[MPC 钱包]** [获取交易列表](/v1/api-references/mpc-wallet/mpc_list_transactions)
|
  • [List all transactions](/v2/api-references/transactions/list-all-transactions)
  • [Get transaction information](/v2/api-references/transactions/get-transaction-information)
| WaaS 2.0 的列表类接口（例如 [List all transactions](/v2/api-references/transactions/list-all-transactions)）会分页返回结果。默认情况下每页返回 10 条记录，最大每页为 50 条，通过 `limit` 参数设置。这与 WaaS 1.0 不同：在 1.0 中单次响应可返回全部结果。因此 WaaS 2.0 的单页会遗漏后续结果。如需获取全部记录，请使用游标参数 `before` 和 `after` 遍历所有页。 diff --git a/v2_cn/guides/transactions/status.mdx b/v2_cn/guides/transactions/status.mdx index 22cd01f9..2657ac36 100644 --- a/v2_cn/guides/transactions/status.mdx +++ b/v2_cn/guides/transactions/status.mdx @@ -281,7 +281,7 @@ WaaS 2.0 定义了各种交易状态和子状态，以反映不同的处理阶 -交易经审批通过后会进入 `PendingSignature` 状态，并且必须在有限的签名时间窗口内由 MPC 签名人组完成签名。如果未能在时间窗口内完成签名，交易将自动失败并转入 `Failed` 状态，子状态为 `FailedSignerTimeout`。如需确认交易失败原因，请查看 [List all transactions](/v2/api-references/transactions/list-all-transactions) 或 [Get transaction information](/v2/api-references/transactions/get-transaction-information) 返回的 `sub_status` 字段。如果遇到 `FailedSignerTimeout`，该交易已处于终态 `Failed`，无法恢复。请重新发起一笔新交易以重试，例如通过 [Transfer token](/v2/api-references/transactions/transfer-token) 操作发起一笔新转账。 +交易经审批通过后会进入 `PendingSignature` 状态，并且必须在有限的签名时间窗口内由 MPC 签名人组完成签名。如果未能在时间窗口内完成签名，交易将自动失败并转入 `Failed` 状态，子状态为 `FailedSignerTimeout`。如需确认交易失败原因，请查看 [List all transactions](/v2/api-references/transactions/list-all-transactions) 或 [Get transaction information](/v2/api-references/transactions/get-transaction-information) 返回的 `sub_status` 字段。如果遇到 `FailedSignerTimeout`，该交易已处于终态 `Failed`，无法恢复。请按原交易类型重新发起一笔新交易：代币转账使用 [Transfer token](/v2/api-references/transactions/transfer-token)，合约调用使用 [Call smart contract](/v2/api-references/transactions/call-smart-contract)，消息签名使用 [Sign message](/v2/api-references/transactions/sign-message)。 diff --git a/v2_cn/guides/transactions/transfer-routing.mdx b/v2_cn/guides/transactions/transfer-routing.mdx index 940670d3..86d26c85 100644 --- a/v2_cn/guides/transactions/transfer-routing.mdx +++ b/v2_cn/guides/transactions/transfer-routing.mdx @@ -28,6 +28,44 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 这些参数仅适用于目的地为地址的转账。有关支持的目的地类型，请参阅 [Transfer token](/v2/api-references/transactions/transfer-token) 操作。 +`force_internal` 和 `force_external` 互斥：在同一请求中将两者均设为 `true` 是无效的，将返回 HTTP 400 错误（错误码 `2006`）。若要强制指定路由方式，请只将其中一个设为 `true`，另一个保持 `false`（或省略）。 + +以下示例展示了如何在 [Transfer token](/v2/api-references/transactions/transfer-token) 请求体中设置路由参数： + +```json 强制使用 Cobo Loop 转账 +{ + "request_id": "your_unique_request_id", + "source": { ... }, + "destination": { ... }, + "token_id": "ETH_USDT", + "amount": "100", + "force_internal": true, + "force_external": false +} +``` + +```json 强制使用链上转账 +{ + "request_id": "your_unique_request_id", + "source": { ... }, + "destination": { ... }, + "token_id": "ETH_USDT", + "amount": "100", + "force_internal": false, + "force_external": true +} +``` + +```json 默认路由（优先 Cobo Loop，不支持时发送到链上） +{ + "request_id": "your_unique_request_id", + "source": { ... }, + "destination": { ... }, + "token_id": "ETH_USDT", + "amount": "100" +} +``` + ## 相关指南 - [交易来源和目的地](/v2_cn/guides/transactions/sources-and-destinations) From da5e3c0621522f4f50cef22324f30228e9cefcee Mon Sep 17 00:00:00 2001 From: rcsh <163504257+rcsh1@users.noreply.github.com> Date: Thu, 2 Jul 2026 11:13:19 +0800 Subject: [PATCH 5/7] docs: remove redundant Note on force_internal/force_external mutual exclusivity --- v2/guides/transactions/transfer-routing.mdx | 2 -- v2_cn/guides/transactions/transfer-routing.mdx | 2 -- 2 files changed, 4 deletions(-) diff --git a/v2/guides/transactions/transfer-routing.mdx b/v2/guides/transactions/transfer-routing.mdx index 6bd3e295..b0e0c6f3 100644 --- a/v2/guides/transactions/transfer-routing.mdx +++ b/v2/guides/transactions/transfer-routing.mdx @@ -28,8 +28,6 @@ The [Transfer token](/v2/api-references/transactions/transfer-token) operation p These parameters are available only for transfers to an address destination. For the supported destination types, see the [Transfer token](/v2/api-references/transactions/transfer-token) operation. -`force_internal` and `force_external` are mutually exclusive: setting both to `true` in the same request is invalid and returns an HTTP 400 error (error code `2006`). To force a specific routing, set only one to `true` and leave the other as `false` (or omit it). - The following examples show how to set the routing parameters in a [Transfer token](/v2/api-references/transactions/transfer-token) request body: ```json Force Cobo Loop transfer diff --git a/v2_cn/guides/transactions/transfer-routing.mdx b/v2_cn/guides/transactions/transfer-routing.mdx index 86d26c85..d9ec30fd 100644 --- a/v2_cn/guides/transactions/transfer-routing.mdx +++ b/v2_cn/guides/transactions/transfer-routing.mdx @@ -28,8 +28,6 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 这些参数仅适用于目的地为地址的转账。有关支持的目的地类型，请参阅 [Transfer token](/v2/api-references/transactions/transfer-token) 操作。 -`force_internal` 和 `force_external` 互斥：在同一请求中将两者均设为 `true` 是无效的，将返回 HTTP 400 错误（错误码 `2006`）。若要强制指定路由方式，请只将其中一个设为 `true`，另一个保持 `false`（或省略）。 - 以下示例展示了如何在 [Transfer token](/v2/api-references/transactions/transfer-token) 请求体中设置路由参数： ```json 强制使用 Cobo Loop 转账 From 500724956604d5ad359a14484e9cb7a338a9ebf2 Mon Sep 17 00:00:00 2001 From: rcsh <163504257+rcsh1@users.noreply.github.com> Date: Thu, 2 Jul 2026 11:14:38 +0800 Subject: [PATCH 6/7] docs: remove code examples from transfer-routing pages --- v2/guides/transactions/transfer-routing.mdx | 36 ------------------- .../guides/transactions/transfer-routing.mdx | 36 ------------------- 2 files changed, 72 deletions(-) diff --git a/v2/guides/transactions/transfer-routing.mdx b/v2/guides/transactions/transfer-routing.mdx index b0e0c6f3..5f3b2044 100644 --- a/v2/guides/transactions/transfer-routing.mdx +++ b/v2/guides/transactions/transfer-routing.mdx @@ -28,42 +28,6 @@ The [Transfer token](/v2/api-references/transactions/transfer-token) operation p These parameters are available only for transfers to an address destination. For the supported destination types, see the [Transfer token](/v2/api-references/transactions/transfer-token) operation. -The following examples show how to set the routing parameters in a [Transfer token](/v2/api-references/transactions/transfer-token) request body: - -```json Force Cobo Loop transfer -{ - "request_id": "your_unique_request_id", - "source": { ... }, - "destination": { ... }, - "token_id": "ETH_USDT", - "amount": "100", - "force_internal": true, - "force_external": false -} -``` - -```json Force on-chain transfer -{ - "request_id": "your_unique_request_id", - "source": { ... }, - "destination": { ... }, - "token_id": "ETH_USDT", - "amount": "100", - "force_internal": false, - "force_external": true -} -``` - -```json Default routing (Cobo Loop if supported, otherwise on-chain) -{ - "request_id": "your_unique_request_id", - "source": { ... }, - "destination": { ... }, - "token_id": "ETH_USDT", - "amount": "100" -} -``` - ## Related guides - [Transaction sources and destinations](/v2/guides/transactions/sources-and-destinations) diff --git a/v2_cn/guides/transactions/transfer-routing.mdx b/v2_cn/guides/transactions/transfer-routing.mdx index d9ec30fd..940670d3 100644 --- a/v2_cn/guides/transactions/transfer-routing.mdx +++ b/v2_cn/guides/transactions/transfer-routing.mdx @@ -28,42 +28,6 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 这些参数仅适用于目的地为地址的转账。有关支持的目的地类型，请参阅 [Transfer token](/v2/api-references/transactions/transfer-token) 操作。 -以下示例展示了如何在 [Transfer token](/v2/api-references/transactions/transfer-token) 请求体中设置路由参数： - -```json 强制使用 Cobo Loop 转账 -{ - "request_id": "your_unique_request_id", - "source": { ... }, - "destination": { ... }, - "token_id": "ETH_USDT", - "amount": "100", - "force_internal": true, - "force_external": false -} -``` - -```json 强制使用链上转账 -{ - "request_id": "your_unique_request_id", - "source": { ... }, - "destination": { ... }, - "token_id": "ETH_USDT", - "amount": "100", - "force_internal": false, - "force_external": true -} -``` - -```json 默认路由（优先 Cobo Loop，不支持时发送到链上） -{ - "request_id": "your_unique_request_id", - "source": { ... }, - "destination": { ... }, - "token_id": "ETH_USDT", - "amount": "100" -} -``` - ## 相关指南 - [交易来源和目的地](/v2_cn/guides/transactions/sources-and-destinations) From 5cff55b96c06320f408c51c0b97c2ae025d41c59 Mon Sep 17 00:00:00 2001 From: rcsh <163504257+rcsh1@users.noreply.github.com> Date: Mon, 20 Jul 2026 16:06:28 +0800 Subject: [PATCH 7/7] =?UTF-8?q?docs:=20=E6=98=8E=E7=A1=AE=E4=BA=A4?= =?UTF-8?q?=E6=98=93=20webhook=20=E4=BA=8B=E4=BB=B6=E5=85=B3=E7=B3=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../webhooks-callbacks/webhook-event-type.mdx | 23 +++++++++++++++---- .../webhooks-callbacks/webhook-event-type.mdx | 23 +++++++++++++++---- 2 files changed, 38 insertions(+), 8 deletions(-) diff --git a/v2/guides/webhooks-callbacks/webhook-event-type.mdx b/v2/guides/webhooks-callbacks/webhook-event-type.mdx index 0acafca6..b321addd 100644 --- a/v2/guides/webhooks-callbacks/webhook-event-type.mdx +++ b/v2/guides/webhooks-callbacks/webhook-event-type.mdx @@ -38,17 +38,17 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen wallets.transaction.updated Transaction - There are changes to a transaction's status or confirmation numbers.The wallets.transaction.updated event covers the entire lifecycle of a transaction, including creation, completion, and failure. If you want to track every status change, you need only subscribe to this event. + There are changes to a transaction's status or confirmation numbers, including when the transaction reaches a terminal outcome.See How transaction events relate to each other below for how this event relates to wallets.transaction.succeeded and wallets.transaction.failed. wallets.transaction.succeeded Transaction - A transaction has been successfully completed. + A transaction has been successfully completed.Always accompanied by a wallets.transaction.updated event for the same transition. See How transaction events relate to each other. wallets.transaction.failed Transaction - A transaction failed. + A transaction failed.Always accompanied by a wallets.transaction.updated event for the same transition. See How transaction events relate to each other. token.suspended.deposit @@ -63,6 +63,21 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen +#### How transaction events relate to each other + +| Transaction lifecycle stage | `wallets.transaction.created` | `wallets.transaction.updated` | `wallets.transaction.succeeded` | `wallets.transaction.failed` | +|---|---|---|---|---| +| Transaction first detected on-chain | Emitted | — | — | — | +| A handled status or confirmation-count change (non-terminal) | — | Emitted | — | — | +| Transaction reaches a terminal successful state | — | Emitted | Emitted | — | +| Transaction reaches a terminal failed state | — | Emitted | — | Emitted | + +Every handled transaction transition, terminal or not, produces a `wallets.transaction.updated` event. When the transition is terminal, Cobo additionally emits `wallets.transaction.succeeded` or `wallets.transaction.failed` alongside that `wallets.transaction.updated` event. `wallets.transaction.succeeded` and `wallets.transaction.failed` are never sent on their own. + +Subscribing only to `wallets.transaction.updated` is sufficient to observe every status change in a transaction's lifecycle, including its terminal outcome, so it works well for driving a progress indicator (for example, updating a pending-transaction view as confirmation numbers increase). However, do not treat `wallets.transaction.updated` as an early signal that a transaction has succeeded — it does not by itself confirm the terminal outcome. For actions that depend on the transaction's final result, such as releasing goods or crediting a balance, use the dedicated `wallets.transaction.succeeded` and `wallets.transaction.failed` events. + +Because the terminal event and its accompanying `wallets.transaction.updated` event are delivered as two separate webhook notifications, handle them idempotently: key your processing on the transaction identity (for example, `transaction_id`) together with the event type, and skip any event you have already processed for that transaction. Webhook events are not guaranteed to arrive in generation order and may be delivered more than once — see [Respond to the API request](/v2/guides/webhooks-callbacks/set-up-endpoint#webhook-events) for delivery-order behavior and [Important notes](/v2/guides/webhooks-callbacks/set-up-endpoint#%E2%9A%A0%EF%B8%8F%E2%9A%A0%EF%B8%8F%E2%9A%A0%EF%B8%8Fimportant-notes) for duplicate-delivery handling. + ### Fee Station events @@ -297,4 +312,4 @@ For a complete introduction of the webhook event data and its data structure, re Switch between the event data types to view the data structure of each event data type. -Additionally, you can view all webhook events in your organization on **Cobo Portal** > **Developer**> **Webhook Events**. \ No newline at end of file +Additionally, you can view all webhook events in your organization on **Cobo Portal** > **Developer**> **Webhook Events**. diff --git a/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx b/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx index 4653ec1e..98774a91 100644 --- a/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx +++ b/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx @@ -39,17 +39,17 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; - + - + - + @@ -64,6 +64,21 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx';
wallets.transaction.updated Transaction交易的状态或确认数发生变化。`wallets.transaction.updated` 涵盖交易的整个生命周期，包括创建、完成和失败。如果您想跟踪每个状态变化，订阅此事件即可。交易的状态或确认数发生变化，包括交易达到最终结果时。下方[交易事件之间的关系](#交易事件之间的关系)说明了此事件与 `wallets.transaction.succeeded` 和 `wallets.transaction.failed` 的关系。
wallets.transaction.succeeded Transaction交易已成功完成。交易已成功完成。此事件总是与同一次流转的 `wallets.transaction.updated` 事件一同触发。参阅[交易事件之间的关系](#交易事件之间的关系)。
wallets.transaction.failed Transaction交易失败。交易失败。此事件总是与同一次流转的 `wallets.transaction.updated` 事件一同触发。参阅[交易事件之间的关系](#交易事件之间的关系)。
token.suspended.deposit
+#### 交易事件之间的关系 + +| 交易生命周期阶段 | `wallets.transaction.created` | `wallets.transaction.updated` | `wallets.transaction.succeeded` | `wallets.transaction.failed` | +|---|---|---|---|---| +| 首次在链上检测到交易 | 触发 | — | — | — | +| 已处理的状态或确认数变化（非最终状态） | — | 触发 | — | — | +| 交易达到最终成功状态 | — | 触发 | 触发 | — | +| 交易达到最终失败状态 | — | 触发 | — | 触发 | + +对于每一次已处理的交易状态流转（无论是否为最终状态），Cobo 都会触发一次 `wallets.transaction.updated` 事件。当该次流转是最终状态时，Cobo 还会在同一次流转中额外触发 `wallets.transaction.succeeded` 或 `wallets.transaction.failed` 事件。`wallets.transaction.succeeded` 和 `wallets.transaction.failed` 不会单独触发。 + +仅订阅 `wallets.transaction.updated` 即可观察交易生命周期中的每一次状态变化，包括其最终结果，因此适合用于展示交易进度（例如，随着确认数增加更新待确认交易的展示状态）。但请勿将 `wallets.transaction.updated` 视为交易已成功的早期信号——它本身并不能确认最终结果。对于依赖交易最终结果的操作（例如放行商品或为余额入账），请使用专门的 `wallets.transaction.succeeded` 和 `wallets.transaction.failed` 事件。 + +由于最终事件与同时触发的 `wallets.transaction.updated` 事件是作为两条独立的 webhook 通知投递的，请对它们进行幂等处理：以交易标识（例如 `transaction_id`）结合事件类型作为处理依据，跳过已处理过的同一交易的事件。Webhook 事件不保证按生成顺序到达，也可能重复投递——投递顺序行为请参阅[响应 API 请求](/v2_cn/guides/webhooks-callbacks/set-up-endpoint#webhook-事件)，重复投递的处理方法请参阅[注意事项](/v2_cn/guides/webhooks-callbacks/set-up-endpoint#%E2%9A%A0%EF%B8%8F%E2%9A%A0%EF%B8%8F%E2%9A%A0%EF%B8%8F-%E6%B3%A8%E6%84%8F%E4%BA%8B%E9%A1%B9)。 + ### Fee Station 相关事件 @@ -299,4 +314,4 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 您可以在事件数据类型之间切换来查看每个事件数据类型的数据结构。 -另外，您可以在 **Cobo Portal** > **开发者** > **Webhook 事件** 中查看团队中的所有 webhook 事件。 \ No newline at end of file +另外，您可以在 **Cobo Portal** > **开发者** > **Webhook 事件** 中查看团队中的所有 webhook 事件。