From fdfc5dcef5c15a178f8d8442e80716cb7e99418f 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/8] 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 | 10 +------ v2/guides/transactions/estimate-fees.mdx | 8 +----- .../rbf-transaction-lifecycle.mdx | 2 +- v2/guides/transactions/status.mdx | 2 +- .../transactions/transaction-process-mpc.mdx | 2 +- v2/guides/transactions/transfer-routing.mdx | 24 +++++++++------- v2_cn/guides/overview/upgrade-guide.mdx | 4 +++ v2_cn/guides/transactions/estimate-fees.mdx | 8 +----- .../transactions/manage-transactions.mdx | 28 ++++--------------- .../rbf-transaction-lifecycle.mdx | 14 +++++----- v2_cn/guides/transactions/status.mdx | 4 +-- .../transactions/transaction-process-mpc.mdx | 8 +++--- .../guides/transactions/transfer-routing.mdx | 28 +++++++++++-------- 13 files changed, 58 insertions(+), 84 deletions(-) diff --git a/docs.json b/docs.json index 1a46808e..3f4d8538 100644 --- a/docs.json +++ b/docs.json @@ -55,7 +55,6 @@ "v2/guides/transactions/sources-and-destinations", "v2/guides/transactions/transfer-routing", "v2/guides/transactions/estimate-fees", - "v2/guides/transactions/solana-token-account-rent", { "group": "Transaction statuses", "pages": [ @@ -66,7 +65,6 @@ }, "v2/guides/transactions/manage-transactions", "v2/guides/transactions/rbf-transaction-lifecycle", - "v2/guides/transactions/validate-addresses", { "group": "Smart contract call samples", "pages": [ @@ -119,7 +117,6 @@ ] }, "v2/guides/mpc-wallets/server-co-signer/key-share-verify", - "v2/guides/mpc-wallets/server-co-signer/troubleshooting", "v2/guides/mpc-wallets/server-co-signer/appendix" ] }, @@ -348,7 +345,7 @@ "v2/api-references/autosweep/create-auto-sweep-task", "v2/api-references/autosweep/list-auto-sweep-tasks", "v2/api-references/autosweep/get-auto-sweep-task-details", - "v2/api-references/autosweep/cancel-auto-sweep-task" + "v2/api-references/autosweep/cancel-auto-sweep-task-by-id" ] }, { @@ -865,9 +862,7 @@ "group": "交易", "pages": [ "v2_cn/guides/transactions/sources-and-destinations", - "v2_cn/guides/transactions/transfer-routing", "v2_cn/guides/transactions/estimate-fees", - "v2_cn/guides/transactions/solana-token-account-rent", { "group": "交易状态", "pages": [ @@ -877,8 +872,6 @@ ] }, "v2_cn/guides/transactions/manage-transactions", - "v2_cn/guides/transactions/rbf-transaction-lifecycle", - "v2_cn/guides/transactions/validate-addresses", { "group": "智能合约调用示例", "pages": [ @@ -931,7 +924,6 @@ ] }, "v2_cn/guides/mpc-wallets/server-co-signer/key-share-verify", - "v2_cn/guides/mpc-wallets/server-co-signer/troubleshooting", "v2_cn/guides/mpc-wallets/server-co-signer/appendix" ] }, diff --git a/v2/guides/transactions/estimate-fees.mdx b/v2/guides/transactions/estimate-fees.mdx index dd4f6872..b58dada1 100644 --- a/v2/guides/transactions/estimate-fees.mdx +++ b/v2/guides/transactions/estimate-fees.mdx @@ -109,7 +109,6 @@ On Solana, you can use either the native model or the Legacy model. In the nativ | Base fee | A fixed fee charged per signature (default 5,000 lamports per signature). | | CU price | The price paid per CU (compute unit) to increase transaction priority, in lamports. | | CU limit | The maximum number of compute units your transaction is allowed to consume. A higher limit may increase priority but also increases the fee. | -| Rent | A one-time fee required to activate a Solana token sub-address (Associated Token Account, or ATA) before that token can be used. It is not included in the base fee or compute unit fee and is paid by the source address. | You can customize the following values: - CU price @@ -117,8 +116,6 @@ You can customize the following values: Refer to the response of the [Estimate transaction fee](/v2/api-references/transactions/estimate-transaction-fee) operation for details. -Activating a Solana token sub-address (Associated Token Account) incurs a one-time rent paid by the source address, separate from the network transaction fee. For details, see [Solana token account rent](/v2/guides/transactions/solana-token-account-rent). - Solana and Filecoin both support two fee models: their native model and the Legacy model. When calling transaction API operations, you can choose which model to use. However, for Replace-By-Fee (RBF) transactions, you must use the same fee model as the original transaction. ### Filecoin @@ -179,10 +176,7 @@ 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. 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). +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 diff --git a/v2/guides/transactions/rbf-transaction-lifecycle.mdx b/v2/guides/transactions/rbf-transaction-lifecycle.mdx index 51b8b8ff..8df9ebd5 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. 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). +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 diff --git a/v2/guides/transactions/status.mdx b/v2/guides/transactions/status.mdx index 97757df1..363ab4e0 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 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. +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. diff --git a/v2/guides/transactions/transaction-process-mpc.mdx b/v2/guides/transactions/transaction-process-mpc.mdx index f003d4f0..3041a8c8 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). 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. +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 index 5f3b2044..95f897d4 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 processed as Cobo Loop transfers or on-chain transfers, and how to control that behavior with request parameters." +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'; @@ -10,23 +10,27 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx'; ## Overview -Every token transfer is processed in one of the following ways: +Every token transfer is routed either internally or externally: -- **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. +- **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 whether the transfer uses Cobo Loop or is sent on-chain: `force_internal` and `force_external`. +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 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). | +| `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. | -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. +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 diff --git a/v2_cn/guides/overview/upgrade-guide.mdx b/v2_cn/guides/overview/upgrade-guide.mdx index ba462ce0..091e5339 100644 --- a/v2_cn/guides/overview/upgrade-guide.mdx +++ b/v2_cn/guides/overview/upgrade-guide.mdx @@ -76,6 +76,10 @@ WaaS 2.0 相较于 WaaS 1.0 进行了重大升级，面向支付、代币化、 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 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 0060b391..8571f0e9 100644 --- a/v2_cn/guides/transactions/estimate-fees.mdx +++ b/v2_cn/guides/transactions/estimate-fees.mdx @@ -111,7 +111,6 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; | Base Fee | 每个签名固定收取的费用（默认每个签名 5,000 Lamports）。 | | CU Price | 每个 CU（Compute Unit，计算单元）的费用，用于提升交易优先级。单位为 Lamports。 | | CU Limit | 交易允许消耗的最大CU数量。值越高优先级越高，但费用也越高。 | -| Rent | 激活 Solana 代币子地址（Associated Token Account，简称 ATA）所需的一次性费用，代币在使用前必须先激活该地址。该费用不包含在 Base Fee 或计算单元费用中，由交易来源地址支付。 | 你可以自定义以下参数的值： - CU Price @@ -119,8 +118,6 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 请参考[估算交易费用](/v2/api-references/transactions/estimate-transaction-fee) 操作的响应结果获取详细字段信息。 -激活 Solana 代币子地址（Associated Token Account）会产生一次性租金，由交易来源地址支付，与网络交易手续费相互独立。详情请参阅 [Solana 代币账户租金](/v2_cn/guides/transactions/solana-token-account-rent)。 - Solana 和 Filecoin 均支持两种费用模型：其原生模型和 Legacy 模型。调用交易相关 API 时，你可以自行选择使用哪种模型。但对于 Replace-By-Fee（RBF）交易，必须使用与原始交易相同的费用模型。 ### Filecoin 链 @@ -181,10 +178,7 @@ Replace-By-Fee (RBF) 是一种允许您用新版本替换未确认交易的功 ## Layer 2 链上的费用 -在 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)。 +在 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 2f9077bd..7ceb13f5 100644 --- a/v2_cn/guides/transactions/manage-transactions.mdx +++ b/v2_cn/guides/transactions/manage-transactions.mdx @@ -10,24 +10,6 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 本指南概述了取消、加速和放弃交易的过程。掌握这些技术可以确保您的交易得到及时准确的处理。 -## 对交易列表分页 - -[List all transactions](/v2/api-references/transactions/list-all-transactions) 操作每次返回一页结果。分页由两个独立的游标参数 `before` 和 `after` 控制，它们分别向相反的方向移动分页窗口。`direction` 参数与分页无关，仅控制排序顺序。 - -- `after`：向前翻到下一页。传入上一个响应的 `pagination` 对象中返回的 `after` 值。 -- `before`：向后翻到上一页。传入上一个响应的 `pagination` 对象中返回的 `before` 值。 - -首次请求时，请勿包含 `before` 或 `after`。Cobo 会返回第一页，并附带一个 `pagination` 对象，其中包含用于翻页的 `before` 和 `after` 游标值。使用 `limit` 参数设置每页的记录数。 - -`direction` 参数是独立的排序控制，不会移动分页窗口。它接受 `ASC`（升序，默认值）或 `DESC`（降序），仅决定记录返回的顺序。向前和向后翻页始终由 `after` 和 `before` 控制。 - -### 分页操作步骤 - -1. 发送首次请求，不带 `before` 和 `after` 参数。响应会返回第一页以及包含 `before`、`after` 和 `total_count` 的 `pagination` 对象。 -2. 要向前翻到下一页，请发送另一个请求，并将 `after` 设置为上一个响应中的 `after` 值。 -3. 要向后翻到上一页，请发送另一个请求，并将 `before` 设置为上一个响应中的 `before` 值。 -4. 当响应返回的 `after` 值为空时，表示您已到达结果的末尾。当响应返回的 `before` 值为空时，表示您已到达结果的开头。 - ## 取消交易 取消交易是在交易仍处于待处理状态时停止它。 @@ -42,7 +24,7 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; - `PendingAuthorization` - `PendingSignature`（仅当子状态为 `Queue`, `InsufficientBalance`, `InsufficientBalanceFundLocked`, `PendingSignerApproval`, `PendingSystemProcessing`, 或 `Built` 时） -要通过 WaaS 2.0 API 取消交易，请使用 [Cancel transaction](/v2/api-references/transactions/cancel-transaction) 操作。这需要您希望取消的交易的交易 ID。 +要通过 WaaS 2.0 API 取消交易，请使用 [取消交易](/v2/api-references/transactions/cancel-transaction) 操作。这需要您希望取消的交易的交易 ID。 ## Replace-By-Fee (RBF) 交易 @@ -54,7 +36,7 @@ Replace-By-Fee (RBF) 是一种允许您用新版本替换未确认交易的功 RBF 的两个最常见用例是加速和放弃交易。 -有关被替换交易的状态变化及其触发的事件，请参阅 [RBF (Replace-By-Fee) 交易生命周期](/v2_cn/guides/transactions/rbf-transaction-lifecycle)。 +有关被替换交易的状态变化及其触发的事件，请参阅 [RBF (Replace-By-Fee) transaction lifecycle](/v2_cn/guides/transactions/rbf-transaction-lifecycle)。 ### 加速交易 @@ -66,7 +48,7 @@ RBF 的两个最常见用例是加速和放弃交易。 只有当交易状态为 `Broadcasting` 时，才能加速交易。 -要加速交易，请使用 [Speed up transaction](/v2/api-references/transactions/speed-up-transaction) 操作。这需要您希望加速的交易的交易 ID。 +要加速交易，请使用 [加速交易](/v2/api-references/transactions/speed-up-transaction) 操作。这需要您希望加速的交易的交易 ID。 如果您加速智能合约钱包的交易，将触发两个 RBF 交易：一个用于智能合约钱包的交易，另一个用于委托人的交易。 @@ -82,7 +64,7 @@ RBF 的两个最常见用例是加速和放弃交易。 只有当交易状态为 `Broadcasting` 时，才能放弃交易。 -要放弃交易，请使用 [Drop transaction](/v2/api-references/transactions/drop-transaction) 操作。这需要您希望放弃的交易的交易 ID。 +要放弃交易，请使用 [放弃交易](/v2/api-references/transactions/drop-transaction) 操作。这需要您希望放弃的交易的交易 ID。 当交易被放弃时，任何后续的放弃或加速操作仍将应用于原始交易。例如，如果用户创建交易 A，然后对交易 A 执行放弃操作使用交易 B，接着对交易 B 执行加速操作使用交易 C，加速操作仍将应用于交易 A，而不是交易 B。 @@ -151,4 +133,4 @@ RBF 的两个最常见用例是加速和放弃交易。 | SafeTxMessage | 由 MPC 钱包发起的消息签名交易，用于授权智能合约钱包（Safe{Wallet}）的操作。 | | StellarChangeTrust | 在 Stellar 网络上建立 trustline 的交易。 | | NonceAccountSign | 使用 Solana nonce account 进行签名的交易，支持确定性且防重放的执行模式。 | -| FeePayerSign | 由 Solana 指定 fee payer 账户代付交易费用的交易，该账户与主签名账户相互独立。 | +| FeePayerSign | 由 Solana 指定 fee payer 账户代付交易费用的交易，该账户与主签名账户相互独立。 | \ No newline at end of file diff --git a/v2_cn/guides/transactions/rbf-transaction-lifecycle.mdx b/v2_cn/guides/transactions/rbf-transaction-lifecycle.mdx index 6d1a5593..98fc9c20 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 替换的完整生命周期：您可以执行的替换操作、原交易的状态如何变化，以及您会收到哪些事件。 -有关分步操作，请参阅 [管理交易](/v2_cn/guides/transactions/manage-transactions)。有关适用于 RBF 交易的费用规则，请参阅 [估算交易费用](/v2_cn/guides/transactions/estimate-fees#replace-by-fee-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)。 ## 替换操作 @@ -25,7 +25,7 @@ WaaS 2.0 支持以下 RBF 操作： ## 替换后原交易的状态 -当替换交易生效时，原交易将转入 `Failed` 状态，子状态为 `ReplacedByNewTransaction`。有关状态和子状态的完整列表，请参阅 [交易状态和子状态](/v2_cn/guides/transactions/status)。 +当替换交易生效时，原交易将转入 `Failed` 状态，子状态为 `ReplacedByNewTransaction`。有关状态和子状态的完整列表，请参阅 [Transaction statuses and sub-statuses](/v2_cn/guides/transactions/status)。 ## 链式替换 @@ -33,11 +33,11 @@ WaaS 2.0 支持以下 RBF 操作： ## 事件 -RBF 的状态变化通过 WaaS 2.0 交易 Webhook 事件呈现。请订阅 `wallets.transaction.updated` 事件，该事件覆盖交易的完整生命周期（包括失败）。有关详细信息，请参阅 [Webhook 事件类型和数据类型](/v2_cn/guides/webhooks-callbacks/webhook-event-type)。 +RBF 的状态变化通过 WaaS 2.0 交易 Webhook 事件呈现。如需了解您会收到哪些事件，请参阅 [Webhook event types](/v2_cn/guides/webhooks-callbacks/webhook-event-type)。 ## 相关指南 -- [管理交易](/v2_cn/guides/transactions/manage-transactions) -- [估算交易费用](/v2_cn/guides/transactions/estimate-fees) -- [交易状态和子状态](/v2_cn/guides/transactions/status) -- [交易来源和目的地](/v2_cn/guides/transactions/sources-and-destinations) +- [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/status.mdx b/v2_cn/guides/transactions/status.mdx index 2657ac36..50217d03 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)，合约调用使用 [Call smart contract](/v2/api-references/transactions/call-smart-contract)，消息签名使用 [Sign message](/v2/api-references/transactions/sign-message)。 +交易经审批通过后会进入 `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`，请重新发起该交易。 @@ -300,6 +300,6 @@ WaaS 2.0 定义了各种交易状态和子状态，以反映不同的处理阶 - 如果交易状态是 `Failed`，您可以重发交易。 - 如果交易状态是 `Broadcasting`，您可以加速或放弃交易。 -有关被替换交易的状态如何变化的详细信息，请参阅 [RBF (Replace-By-Fee) 交易生命周期](/v2_cn/guides/transactions/rbf-transaction-lifecycle)。 +有关被替换交易的状态如何变化的详细信息，请参阅 [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 e6017335..1cad22ea 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 保留拒绝该交易的权利。 -- 如果交易金额低于最低充币门槛，交易将不会被处理，也不会创建任何记录。您可以调用 [Get token information](/v2/api-references/wallets/get-token-information) 操作来检索每种代币类型的最低充币金额。 +- 如果交易金额低于最低充币门槛，交易将不会被处理，也不会创建任何记录。您可以调用 [获取代币信息](/v2/api-references/wallets/get-token-information) 操作来检索每种代币类型的最低充币金额。 ## 提币流程 @@ -34,8 +34,8 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 提币流程 - 如果提币被拒绝或不成功，代币将返回到您的钱包，您的余额将保持不变。 -- 如果您的提币金额小于最低提币门槛，提币请求将收到错误。您可以调用 [Get token information](/v2/api-references/wallets/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) 操作发起一笔新转账。 - +提币交易经审批通过后会进入 `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 index 940670d3..d5c4a184 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,25 +10,29 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; ## 概述 -每笔代币转账都会以下列方式之一处理： +每笔代币转账都会通过内部或外部路由： -- **Cobo Loop 转账**：当目的地支持时，通过 Cobo Loop 转账网络在 Cobo Portal 账户之间以链下方式结算。 -- **链上转账**：将交易广播到区块链上。 +- **内部路由**：当目的地支持时，通过 Cobo Loop 转账网络在 Cobo Portal 账户之间以链下方式结算。 +- **外部路由**：将交易广播到区块链上。 ## 使用请求参数控制路由 -[Transfer token](/v2/api-references/transactions/transfer-token) 操作提供两个布尔参数，用于控制转账是使用 Cobo Loop 还是发送到链上：`force_internal` 和 `force_external`。 +[Transfer token](/v2/api-references/transactions/transfer-token) 操作提供两个布尔参数来控制路由：`force_internal` 和 `force_external`。 | 设置 | 路由行为 | |---------|------------------| -| `force_internal` = `true` | 强制转账使用 Cobo Loop（链下）。 | -| `force_external` = `true` | 强制转账发送到链上。 | -| 两者均为 `false`（默认） | 如果目的地支持，则使用 Cobo Loop；否则发送到链上。 | -| 两者均为 `true` | 请求将被拒绝，返回 HTTP 400 错误（错误码 `2006`，参数无效）。 | +| `force_internal` = `true` | 强制通过 Cobo Loop 进行内部路由（链下）。 | +| `force_external` = `true` | 强制进行链上外部路由。 | +| 两者均为 `false`（默认） | 如果目的地支持，则通过 Cobo Loop 路由；否则进行链上路由。 | +| 两者均为 `true` | 请求将被拒绝。 | -这些参数仅适用于目的地为地址的转账。有关支持的目的地类型，请参阅 [Transfer token](/v2/api-references/transactions/transfer-token) 操作。 +部分目的地不支持这些参数。 + +## 对生成交易的影响 + +内部路由生成链下的 Cobo Loop 转账。外部路由生成链上交易。 ## 相关指南 -- [交易来源和目的地](/v2_cn/guides/transactions/sources-and-destinations) -- [Cobo Loop](https://manuals.cobo.com/cn/portal/custodial-wallets/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 33a171078f4a4ced55eab9761b2841cf40710dde 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/8] 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 360989a1ba7996c6310dac9d216528ed94455369 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/8] 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 a7e5658fd5c4e45730547858ba0e106f6224b40f 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/8] 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 | 4 -- v2_cn/guides/transactions/status.mdx | 2 +- .../guides/transactions/transfer-routing.mdx | 38 +++++++++++++++++++ 5 files changed, 78 insertions(+), 6 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 091e5339..ba462ce0 100644 --- a/v2_cn/guides/overview/upgrade-guide.mdx +++ b/v2_cn/guides/overview/upgrade-guide.mdx @@ -76,10 +76,6 @@ WaaS 2.0 相较于 WaaS 1.0 进行了重大升级，面向支付、代币化、 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 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/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 4e80c33d301af76d7fc64ba3483a1c492763cf8f 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/8] 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 f126b4b742f0194579d863ff95e42363c8d8d555 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/8] 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 70f19ef934b68fe719a3ea549a13fe21ff700249 Mon Sep 17 00:00:00 2001 From: rcsh <163504257+rcsh1@users.noreply.github.com> Date: Tue, 21 Jul 2026 11:52:58 +0800 Subject: [PATCH 7/8] =?UTF-8?q?docs:=20=E6=BE=84=E6=B8=85=E8=87=AA?= =?UTF-8?q?=E5=8A=A8=E5=BD=92=E9=9B=86=E4=BB=BB=E5=8A=A1=E4=B8=8E=E9=92=B1?= =?UTF-8?q?=E5=8C=85=E9=85=8D=E7=BD=AE=E8=AF=AD=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- v2/cobo_waas2_openapi_spec/dev_openapi.yaml | 83 +++++++++++++++---- .../get-started-asset-wallets.mdx | 18 ++-- v2/guides/overview/changelog.mdx | 4 +- .../get-started-asset-wallets.mdx | 18 ++-- v2_cn/guides/overview/changelog.mdx | 4 +- 5 files changed, 97 insertions(+), 30 deletions(-) diff --git a/v2/cobo_waas2_openapi_spec/dev_openapi.yaml b/v2/cobo_waas2_openapi_spec/dev_openapi.yaml index 46128aeb..0b8e0a4a 100644 --- a/v2/cobo_waas2_openapi_spec/dev_openapi.yaml +++ b/v2/cobo_waas2_openapi_spec/dev_openapi.yaml @@ -6150,11 +6150,11 @@ paths: operationId: create_auto_sweep_task summary: Create auto-sweep task description: | - This operation creates an auto-sweep task for the specified wallet and token. The task triggers transactions to sweep the full balance of the specified token to the configured sweep-to address. + This operation creates an on-demand sweep task for the specified token. Unlike automatic sweeping, this task does not wait for the wallet's automatic policy trigger conditions. It is accepted for processing immediately. - A sweep requires native chain coin to pay for gas. The gas must be available either in the source (deposit) address, or supplied by a configured Fee Station or Auto-Fuel. Reaching the deposit threshold alone does not trigger a sweep. If no gas is available, the sweep is blocked (for example, with an insufficient-balance error) or the Fee Station quota check fails. When a sweep is blocked, the reason is reported in the `failed_reasons` array of the auto-sweep task. + During execution, Cobo evaluates the request's `min_balance_threshold` and other eligibility constraints for each address, including available gas, reserved balances and fees, and any pending transaction on the address. As a result, execution may create no transaction if no address is eligible. - This operation is asynchronous. When the task is created, it is returned with `status` set to `Submitted` and an empty `transaction_ids` array; this is expected and does not indicate a failure. The `transaction_ids` array is populated only after `status` becomes `TransactionCreated`. To retrieve the transaction IDs, poll [Get auto-sweep task details](https://www.cobo.com/developers/v2/api-references/autosweep/get-auto-sweep-task-details) using the returned `task_id` until the status changes. + A `Submitted` status means the task has been accepted for asynchronous processing. It does not guarantee that a sweep transaction will be created. Poll [Get auto-sweep task details](https://www.cobo.com/developers/v2/api-references/autosweep/get-auto-sweep-task-details) and check `status`, `transaction_ids`, and `failed_reasons` together to determine the task's current state. Once `transaction_ids` contains an ID, call [Get transaction information](https://www.cobo.com/developers/v2/api-references/transactions/get-transaction-information) to determine that transaction's outcome. security: - CoboAuth: [] - OAuth2: @@ -6989,7 +6989,16 @@ components: example: f47ac10b-58cc-4372-a567-0e02b2c3d479 enable_auto_sweep: type: boolean - description: Enable the auto sweep feature for the wallet + description: | + Whether the auto-sweep capability has been enabled for this wallet. + - `true`: Auto-sweep has been enabled for this wallet. + - `false`: Auto-sweep has not been enabled for this wallet. + + This field reports whether the capability itself has been enabled. It does not indicate whether automatic sweep triggers are currently paused. Pausing and resuming automatic triggers is managed separately in Cobo Portal and does not change this field's value. + + + Once enabled, deposit addresses in this wallet cannot initiate public token transfers or contract calls by default. Use the deposit-address transaction setting in Cobo Portal to restore permitted activity for specific addresses. + MPCWalletInfo: title: MPC Wallets allOf: @@ -7228,7 +7237,14 @@ components: $ref: '#/components/schemas/WalletSubtype' enable_auto_sweep: type: boolean - description: Enable the auto-sweep feature for the wallet. This parameter only applies to MPC Wallets and Custodial Wallets (Web3 Wallets). + description: | + Whether to enable the auto-sweep capability for this wallet. + - `true`: Enables auto-sweep for the wallet. + - `false`: Does not enable auto-sweep for the wallet. + + + Enabling auto-sweep is irreversible. After enablement, deposit addresses in this wallet can no longer initiate public token transfers or contract calls by default. You can restore permitted activity for specific deposit addresses using the deposit-address transaction setting in Cobo Portal. + CreateMpcWalletParams: title: MPC Wallets allOf: @@ -7373,7 +7389,18 @@ components: description: The wallet name. enable_auto_sweep: type: boolean - description: Enable the auto sweep feature for the wallet + description: | + Whether to enable the auto-sweep capability for this wallet. + - `true`: Enables auto-sweep for the wallet. + - `false`: Does not disable auto-sweep for a wallet that already has it enabled. This field is a one-way enable control. + + + To stop future automatic sweep triggers for a wallet, use the pause control in Cobo Portal instead of setting this field to `false`. Pausing automatic triggers does not undo enablement. This field continues to report `true` for a wallet that was enabled and later paused. + + + + Enabling auto-sweep is irreversible. After enablement, deposit addresses in this wallet can no longer initiate public token transfers or contract calls by default. Use the deposit-address transaction setting in Cobo Portal to restore permitted activity for specific addresses. + UpdateMpcWalletParams: type: object title: MPC Wallets @@ -7389,7 +7416,18 @@ components: description: The wallet name. enable_auto_sweep: type: boolean - description: Enable the auto sweep feature for the wallet + description: | + Whether to enable the auto-sweep capability for this wallet. + - `true`: Enables auto-sweep for the wallet. + - `false`: Does not disable auto-sweep for a wallet that already has it enabled. This field is a one-way enable control. + + + To stop future automatic sweep triggers for a wallet, use the pause control in Cobo Portal instead of setting this field to `false`. Pausing automatic triggers does not undo enablement. This field continues to report `true` for a wallet that was enabled and later paused. + + + + Enabling auto-sweep is irreversible. After enablement, deposit addresses in this wallet can no longer initiate public token transfers or contract calls by default. Use the deposit-address transaction setting in Cobo Portal to restore permitted activity for specific addresses. + UpdateSmartContractWalletParams: type: object title: Smart Contract Wallets @@ -21454,13 +21492,24 @@ components: type: string example: 0011039d-27fb-49ba-b172-6e0aa80e37ec description: | - IDs of the transactions triggered by the task. This array is empty while the task `status` is `Submitted`, and is populated only after the status becomes `TransactionCreated`. Poll [Get auto-sweep task details](https://www.cobo.com/developers/v2/api-references/autosweep/get-auto-sweep-task-details) until the transaction IDs are available. + The IDs of the sweep transactions created for this task. + + An empty array means that no sweep transaction has been created for this task yet. It does not mean that submission failed or that funds have already been swept. Check this field together with `failed_reasons` and `status` to determine the task's current state. Poll [Get auto-sweep task details](https://www.cobo.com/developers/v2/api-references/autosweep/get-auto-sweep-task-details) to retrieve the latest task information. failed_reasons: type: array items: type: string - example: exist pending transaction - description: Reasons why the task creation failed. + example: Insufficient balance to cover network fees. + description: | + A list of human-readable diagnostic messages explaining why this task did not create a sweep transaction for one or more addresses. Each message is free-text, and its exact wording may change. Do not parse it for exact text, transaction IDs, or exception strings. Instead, classify messages using the following general categories: + - Insufficient balance to cover the sweep after transaction fees are reserved. + - Insufficient gas balance to fund the sweep transaction. + - The transaction fee would exceed a configured fee cap. + - Another transaction from the same address is already pending. + - The address balance does not meet the configured minimum-balance threshold. + - Chain-specific fee-handling requirements were not met, for example, on TRON. + - Fee Station declined to fund the transaction. + - The sweep transaction could not be created. created_timestamp: type: integer format: int64 @@ -21478,9 +21527,11 @@ components: - TransactionCreated example: Submitted description: | - Auto-sweep task status: - - `Submitted`: The auto-sweep task has been submitted. - - `TransactionCreated`: The auto-sweep task triggered one or more token sweeping transactions. + The status of the auto-sweep task. Possible values: + - `Submitted`: The task has been accepted and is still awaiting transaction creation. Check `failed_reasons` and `transaction_ids` for the latest task details. + - `TransactionCreated`: Task processing created, or completed its attempt to create, a sweep transaction. Check `transaction_ids` for the resulting transaction IDs and `failed_reasons` for any diagnostic messages. + + Task-level failure is not represented by a dedicated `Failed` status. If a task cannot proceed, the reason is recorded in `failed_reasons`. Once `transaction_ids` contains an ID, retrieve that transaction separately to determine its own success or failure. This status does not reflect downstream transaction outcomes. CreateAutoSweepTask: type: object description: Wallet and token information required to create an auto-sweep task. @@ -21499,7 +21550,11 @@ components: min_balance_threshold: type: string description: | - The minimum token balance threshold for auto sweep. If the token balance of an address is less than this threshold, the address will not be swept. + The per-request minimum balance threshold used to filter addresses when this task executes. During execution, any address whose balance is below this threshold is skipped for this task. + + This field only filters which addresses are considered for this task. It does not override other execution checks such as gas requirements, reserved balances, transaction fees, or an existing pending transaction on the same address. If you omit this field, address selection still passes through those other checks. + + It applies only to this manual task. example: '0.01' parameters: sortByParam: diff --git a/v2/guides/custodial-wallets/get-started-asset-wallets.mdx b/v2/guides/custodial-wallets/get-started-asset-wallets.mdx index f7e0a38d..e47c346a 100644 --- a/v2/guides/custodial-wallets/get-started-asset-wallets.mdx +++ b/v2/guides/custodial-wallets/get-started-asset-wallets.mdx @@ -703,24 +703,30 @@ public class ListTokenBalancesExample { ## 6. Sweep funds automatically (auto-sweep) -Auto-sweep automatically consolidates tokens from your deposit addresses into a designated sweep-to address, so that you do not need to move funds out of each deposit address manually. To create an auto-sweep task, call the [Create auto-sweep task](/v2/api-references/autosweep/create-auto-sweep-task) operation and specify the following: +Auto-sweep automatically consolidates tokens from your deposit addresses into a designated sweep-to address, so that you do not need to move funds out of each deposit address manually. To create an on-demand sweep task for a specific token, call the [Create auto-sweep task](/v2/api-references/autosweep/create-auto-sweep-task) operation and specify the following: - `wallet_id`: The ID of the wallet you created. - `token_id`: The ID of the token to sweep. -- `min_balance_threshold`: (Optional) The minimum token balance an address must hold to be swept. Addresses holding less than this value are skipped, which lets you filter out dust. There is no per-address blocklist; use `min_balance_threshold` to control the minimum sweep amount. +- `min_balance_threshold`: (Optional) The minimum balance an address must hold to be eligible for this sweep request. Addresses holding less than this value are skipped. This threshold only filters which address balances are considered for the request; it does not override other execution checks such as available gas, required fees, reserved balances, or an existing pending transaction on the address. -A sweep moves tokens out of a deposit address, which requires native chain coin to pay for gas. Make sure that gas is available either in the source deposit address or through a configured Fee Station or Auto Fueling. Reaching the deposit threshold alone does not complete a sweep: if no gas is available, the sweep cannot be broadcast. When a sweep cannot proceed, the reason is reported in the `failed_reasons` array returned by the task details. +Meeting `min_balance_threshold` does not by itself guarantee a sweep transaction is created. A sweep moves tokens out of a deposit address, which requires native chain coin to pay for gas, so make sure that gas is available either in the source deposit address or through a configured Fee Station or Auto Fueling. Cobo also checks required fees, reserved balances, and whether the address already has a pending transaction before creating a sweep transaction. When any of these checks prevents a sweep, the reason is reported in the `failed_reasons` array returned by the task details. ### Retrieve the swept transactions -The Create auto-sweep task operation returns immediately with a `task_id`. At this point the task `status` is `Submitted` and the `transaction_ids` array is empty. This is expected and does not indicate a failure. +The Create auto-sweep task operation returns immediately with a `task_id`, accepting your request for asynchronous processing. This does not guarantee that a sweep transaction will ultimately be created for the request. -The task transitions to `TransactionCreated` once it triggers one or more sweep transactions, at which point `transaction_ids` is populated. To retrieve the transaction IDs, poll the [Get auto-sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details) operation with your `task_id` until `status` becomes `TransactionCreated`. +Poll the [Get auto-sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details) operation with your `task_id`, and check `status`, `transaction_ids`, and `failed_reasons` together rather than relying on any single field: + +- `status` of `Submitted` means the task is accepted and still awaiting its transaction-creation attempt. `TransactionCreated` means that attempt has completed. +- `transaction_ids` stays empty while the task is `Submitted`. An empty array under `TransactionCreated` means the attempt completed without creating a transaction, for example because no address balance remained eligible after gas, fee, reserve, or pending-transaction checks — not that a sweep was submitted and failed, and not that funds were already swept. +- `failed_reasons` explains why a sweep could not be created for one or more addresses. Treat these as diagnostic text and do not parse the exact wording. + +Once `transaction_ids` is populated, those sweep transactions still need to confirm on-chain. Poll [Get transaction information](/v2/api-references/transactions/get-transaction-information) with each transaction ID to track its final outcome, the same way you would for any other transaction created through the WaaS 2.0 API. ### Timing and lifecycle -Auto-sweep is poll-based rather than instant. A sweep is initiated shortly after its trigger condition is met, so a short delay between the deposit and the sweep transaction is normal. Tasks that cannot proceed do not stay pending indefinitely: a task that remains without gas or without a signature is automatically cancelled after a timeout, and the affected funds remain in the source address so that you can sweep them again later. +Auto-sweep task processing is asynchronous rather than instant, so expect a short delay between submitting the Create auto-sweep task request and `status` reaching `TransactionCreated`. There is no fixed schedule that guarantees when, or whether, a given task leaves `Submitted`; rely on polling `status`, `transaction_ids`, and `failed_reasons` to determine the outcome. If a sweep cannot proceed, for example because gas is unavailable, the affected funds remain in the source address and you can submit a new sweep task for that address later. For EVM-compatible chains (such as Ethereum and BNB Smart Chain), the same address is used across all EVM chains. As a result, when you list sweep-to addresses with [List sweep-to addresses](/v2/api-references/autosweep/list-sweep-to-addresses), only one address entry (shown under Ethereum) is returned for all EVM-compatible chains. Do not expect a separate entry for each EVM chain. \ No newline at end of file diff --git a/v2/guides/overview/changelog.mdx b/v2/guides/overview/changelog.mdx index edf53ba9..97316e7a 100644 --- a/v2/guides/overview/changelog.mdx +++ b/v2/guides/overview/changelog.mdx @@ -30,7 +30,7 @@ This version was released on July 9, 2026. - Deprecated `Raw_Message_Signature` in the [Sign message](/v2/api-references/transactions/sign-message) operation due to security concerns. It is no longer allowed and must not be used. It may be removed in a future version. - Clarified wallet name constraints in the [Create wallet](/v2/api-references/wallets/create-wallet) operation: the `name` field is required and cannot be empty; special characters such as `@` are not accepted and will return `400 Bad Request`. - Clarified that fee estimates from [Estimate transaction fee](/v2/api-references/transactions/estimate-transaction-fee) are point-in-time and short-lived. Re-estimate immediately before submitting a withdrawal to avoid rejection due to insufficient fees. -- Clarified async behavior of [Create auto sweep task](/v2/api-references/autosweep/create-auto-sweep-task): returned tasks have `status` set to `Submitted` with an empty `transaction_ids` array; poll [Get auto sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details) until `status` becomes `TransactionCreated`. Sweeps require native chain coin for gas from the deposit address, Fee Station, or Auto-Fuel. +- Clarified async behavior of [Create auto-sweep task](/v2/api-references/autosweep/create-auto-sweep-task): the task is accepted for asynchronous processing and returns with `status` set to `Submitted` and an empty `transaction_ids` array. Poll [Get auto-sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details) and check `status`, `transaction_ids`, and `failed_reasons` together; not every task is guaranteed to leave `Submitted`. Sweeps require native chain coin for gas from the deposit address, Fee Station, or Auto-Fuel. - Clarified that `transaction_hash` in [Get transaction information](/v2/api-references/transactions/get-transaction-information) and [List all transactions](/v2/api-references/transactions/list-all-transactions) responses may be `null` or absent before on-chain broadcast. - Clarified Solana transaction fee fields: `fee_used` covers on-chain network fees only and excludes ATA activation rent. `rent_amount` in fee estimate responses is reserved for future ATA activation rent and is currently not populated. @@ -829,4 +829,4 @@ This release includes support for [Custodial Wallets](https://manuals.cobo.com/e - [General wallet operations](/v2/api-references/wallets/list-supported-chains) - [MPC Wallets-specific operations](/v2/api-references/wallets--mpc-wallets/list-all-cobo-key-share-holders) - [Transactions operations](/v2/api-references/transactions/estimate-transaction-fee) -- [Webhook operations](/v2/api-references/developers--webhooks/list-webhook-endpoints) \ No newline at end of file +- [Webhook operations](/v2/api-references/developers--webhooks/list-webhook-endpoints) diff --git a/v2_cn/guides/custodial-wallets/get-started-asset-wallets.mdx b/v2_cn/guides/custodial-wallets/get-started-asset-wallets.mdx index 4ce598a6..d4b96e44 100644 --- a/v2_cn/guides/custodial-wallets/get-started-asset-wallets.mdx +++ b/v2_cn/guides/custodial-wallets/get-started-asset-wallets.mdx @@ -708,24 +708,30 @@ public class ListTokenBalancesExample { ## 6. 自动归集资金（auto-sweep） -自动归集（auto-sweep）会自动将充币地址中的代币归集到指定的归集目标地址，您无需手动从每个充币地址转出资金。要创建自动归集任务，请调用 [Create auto-sweep task](/v2/api-references/autosweep/create-auto-sweep-task)，并指定以下参数： +自动归集（auto-sweep）会自动将充币地址中的代币归集到指定的归集目标地址，您无需手动从每个充币地址转出资金。要为指定代币创建一次按需归集任务，请调用 [Create auto-sweep task](/v2/api-references/autosweep/create-auto-sweep-task)，并指定以下参数： - `wallet_id`：您创建的钱包 ID。 - `token_id`：要归集的代币 ID。 -- `min_balance_threshold`：（可选）地址被归集所需的最低代币余额。余额低于此值的地址将被跳过，可用于过滤粉尘（dust）。系统不提供按地址设置的黑名单；请使用 `min_balance_threshold` 控制最低归集金额。 +- `min_balance_threshold`：（可选）本次归集请求中，地址需达到的最低余额。余额低于此值的地址会被跳过。该阈值仅用于筛选本次请求中纳入考虑的地址余额，不会影响其他执行检查，例如可用 gas、所需手续费、保留余额，或该地址是否已有一笔待处理交易。 -归集会将代币从充币地址转出，因此需要链上原生代币支付 gas 费。请确保源充币地址中有足够的原生代币，或已配置 Fee Station 或自动加油（Auto Fueling）来提供 gas。仅达到充币阈值并不会完成归集：如果没有可用的 gas，归集交易将无法广播。当归集无法进行时，原因会显示在任务详情返回的 `failed_reasons` 数组中。 +满足 `min_balance_threshold` 并不能保证一定会创建归集交易。归集会将代币从充币地址转出，因此需要链上原生代币支付 gas 费，请确保源充币地址中有足够的原生代币，或已配置 Fee Station 或自动加油（Auto Fueling）来提供 gas。在创建归集交易之前，Cobo 还会检查所需手续费、保留余额，以及该地址是否已存在待处理交易。当以上任一检查未通过时，原因会显示在任务详情返回的 `failed_reasons` 数组中。 ### 获取归集交易 -Create auto-sweep task 会立即返回 `task_id`。此时任务 `status` 为 `Submitted`，`transaction_ids` 数组为空。这是预期行为，并不表示失败。 +Create auto-sweep task 会立即返回 `task_id`，表示请求已被接受并进入异步处理，但这并不保证最终一定会为该请求创建归集交易。 -当任务触发一个或多个归集交易后，其状态会变为 `TransactionCreated`，此时 `transaction_ids` 会被填充。要获取交易 ID，请使用 `task_id` 轮询 [Get auto-sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details)，直到 `status` 变为 `TransactionCreated`。 +请使用 `task_id` 轮询 [Get auto-sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details)，并同时查看 `status`、`transaction_ids` 和 `failed_reasons`，而不要只依赖其中一个字段： + +- `status` 为 `Submitted` 表示任务已被接受，仍在等待交易创建的处理结果；为 `TransactionCreated` 表示该处理已经完成。 +- 当任务处于 `Submitted` 时，`transaction_ids` 为空。当状态变为 `TransactionCreated` 后，`transaction_ids` 仍为空，则表示处理完成但未创建交易，例如在经过 gas、手续费、保留余额或待处理交易等检查后，没有余额符合归集条件——这并不代表已提交但归集失败，也不代表资金已被归集。 +- `failed_reasons` 说明了为何某个地址未能创建归集交易。请将其视为诊断性文本，不要解析具体措辞。 + +`transaction_ids` 被填充后，这些归集交易仍需在链上得到确认。请使用每个交易 ID 轮询 [Get transaction information](/v2/api-references/transactions/get-transaction-information)，跟踪其最终结果，方式与您跟踪 WaaS 2.0 API 创建的其他交易相同。 ### 时间与生命周期 -自动归集基于轮询机制，并非即时执行。归集会在满足触发条件后不久发起，因此充币与归集交易之间存在短暂延迟属于正常现象。无法继续的任务不会一直处于等待状态：长时间缺少 gas 或未完成签名的任务会在超时后自动取消，相关资金会保留在源地址中，您可以稍后重新归集。 +自动归集任务的处理是异步的，并非即时完成，因此从提交 Create auto-sweep task 请求到 `status` 变为 `TransactionCreated` 之间存在短暂延迟属于正常现象。系统并不保证某个任务会在固定时间内、或最终一定会脱离 `Submitted` 状态；请通过轮询 `status`、`transaction_ids` 和 `failed_reasons` 来判断结果。如果归集因故无法进行（例如 gas 不足），相关资金会保留在源地址中，您可以之后为该地址重新提交归集任务。 对于 EVM 兼容链（如 Ethereum 和 BNB Smart Chain），所有 EVM 链共用同一个地址。因此，当您使用 [List sweep-to addresses](/v2/api-references/autosweep/list-sweep-to-addresses) 列出归集目标地址时，所有 EVM 兼容链只会返回一个地址条目（显示在 Ethereum 下）。请勿期望每条 EVM 链都有单独的地址条目。 \ No newline at end of file diff --git a/v2_cn/guides/overview/changelog.mdx b/v2_cn/guides/overview/changelog.mdx index a88e37bf..664bc255 100644 --- a/v2_cn/guides/overview/changelog.mdx +++ b/v2_cn/guides/overview/changelog.mdx @@ -30,7 +30,7 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; - 出于安全考虑，[签署消息](/v2/api-references/transactions/sign-message) 接口中的 `Raw_Message_Signature` 已废弃，不再允许使用，未来版本可能移除。 - 澄清 [创建钱包](/v2/api-references/wallets/create-wallet) 接口的钱包名称约束：`name` 为必填且不能为空；不支持 `@` 等特殊字符，否则返回 `400 Bad Request`。 - 澄清 [估算交易费用](/v2/api-references/transactions/estimate-transaction-fee) 接口返回的手续费预估为瞬时数据、时效较短。提交提现前应重新估算，避免因手续费不足导致交易被拒绝。 -- 澄清 [创建自动归集任务](/v2/api-references/autosweep/create-auto-sweep-task) 接口的异步行为：任务创建后 `status` 为 `Submitted` 且 `transaction_ids` 为空属正常；请轮询 [获取自动归集任务详情](/v2/api-references/autosweep/get-auto-sweep-task-details) 直至 `status` 变为 `TransactionCreated`。归集需要原生链币支付 gas，可从充币地址、Fee Station 或 Auto-Fuel 获取。 +- 澄清 [Create auto-sweep task](/v2/api-references/autosweep/create-auto-sweep-task) 接口的异步行为：请求会被异步接受处理，返回时 `status` 为 `Submitted` 且 `transaction_ids` 为空属正常。请轮询 [Get auto-sweep task details](/v2/api-references/autosweep/get-auto-sweep-task-details)，并结合 `status`、`transaction_ids` 与 `failed_reasons` 共同判断任务状态；并非每个任务都保证会脱离 `Submitted` 状态。归集需要原生链币支付 gas，可从充币地址、Fee Station 或 Auto-Fuel 获取。 - 澄清 [查询交易详情](/v2/api-references/transactions/get-transaction-information) 和 [查询交易列表](/v2/api-references/transactions/list-all-transactions) 响应中的 `transaction_hash` 仅在链上广播后才有值，广播前可能为 `null` 或缺失。 - 澄清 Solana 交易费用字段：`fee_used` 仅包含链上网络手续费，不含 ATA 激活租金；费用预估响应中的 `rent_amount` 为 ATA 激活租金预留字段，当前不返回。 @@ -818,4 +818,4 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; - [通用钱包操作](/v2/api-references/wallets/list-supported-chains) - [MPC 钱包特定操作](/v2/api-references/wallets--mpc-wallets/list-all-cobo-key-share-holders) - [交易操作](/v2/api-references/transactions/estimate-transaction-fee) -- [Webhook 操作](/v2/api-references/developers--webhooks/list-webhook-endpoints) \ No newline at end of file +- [Webhook 操作](/v2/api-references/developers--webhooks/list-webhook-endpoints) From 7307c32e8877d9c555a74262f7b00853584421ca Mon Sep 17 00:00:00 2001 From: rcsh <163504257+rcsh1@users.noreply.github.com> Date: Fri, 24 Jul 2026 14:53:14 +0800 Subject: [PATCH 8/8] docs: address review feedback --- v2/cobo_waas2_openapi_spec/dev_openapi.yaml | 18 +++++++++++------- .../transactions/manage-transactions.mdx | 6 +++--- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/v2/cobo_waas2_openapi_spec/dev_openapi.yaml b/v2/cobo_waas2_openapi_spec/dev_openapi.yaml index 0b8e0a4a..61de0a4f 100644 --- a/v2/cobo_waas2_openapi_spec/dev_openapi.yaml +++ b/v2/cobo_waas2_openapi_spec/dev_openapi.yaml @@ -6994,10 +6994,14 @@ components: - `true`: Auto-sweep has been enabled for this wallet. - `false`: Auto-sweep has not been enabled for this wallet. - This field reports whether the capability itself has been enabled. It does not indicate whether automatic sweep triggers are currently paused. Pausing and resuming automatic triggers is managed separately in Cobo Portal and does not change this field's value. + This field reports whether the capability itself has been enabled. It does not indicate whether automatic sweep triggers are currently paused. To pause or resume automatic triggers in Cobo Portal: + - For a Custodial Web3 Wallet, go to **Wallets > Custodial Wallets > Web3 Wallets**, select the wallet, click **Auto-Sweep Settings**, and then click **Pause Auto-Sweep** or **Resume Auto-Sweep**. + - For an Organization-Controlled MPC Wallet, go to **Wallets > MPC Wallets > Organization-Controlled Wallets**, select the vault and wallet, click **Auto-Sweep Settings**, and then click **Pause Auto-Sweep** or **Resume Auto-Sweep**. + + Pausing or resuming automatic triggers does not change this field's value. - Once enabled, deposit addresses in this wallet cannot initiate public token transfers or contract calls by default. Use the deposit-address transaction setting in Cobo Portal to restore permitted activity for specific addresses. + Once enabled, deposit addresses in this wallet cannot initiate public token transfers or contract calls by default. To restore deposit-address transactions in Cobo Portal, follow the applicable wallet path above, click **Auto-Sweep Settings > Sweep Security**, turn on **Deposit Address Transactions**, and click **Confirm**. This setting applies to the wallet's deposit addresses. MPCWalletInfo: title: MPC Wallets @@ -7243,7 +7247,7 @@ components: - `false`: Does not enable auto-sweep for the wallet. - Enabling auto-sweep is irreversible. After enablement, deposit addresses in this wallet can no longer initiate public token transfers or contract calls by default. You can restore permitted activity for specific deposit addresses using the deposit-address transaction setting in Cobo Portal. + Enabling auto-sweep is irreversible. After enablement, deposit addresses in this wallet can no longer initiate public token transfers or contract calls by default. To restore deposit-address transactions in Cobo Portal, go to **Wallets > Custodial Wallets > Web3 Wallets**, select the wallet, click **Auto-Sweep Settings > Sweep Security**, turn on **Deposit Address Transactions**, and click **Confirm**. This setting applies to the wallet's deposit addresses. CreateMpcWalletParams: title: MPC Wallets @@ -7395,11 +7399,11 @@ components: - `false`: Does not disable auto-sweep for a wallet that already has it enabled. This field is a one-way enable control. - To stop future automatic sweep triggers for a wallet, use the pause control in Cobo Portal instead of setting this field to `false`. Pausing automatic triggers does not undo enablement. This field continues to report `true` for a wallet that was enabled and later paused. + To stop future automatic sweep triggers in Cobo Portal, go to **Wallets > Custodial Wallets > Web3 Wallets**, select the wallet, click **Auto-Sweep Settings**, and then click **Pause Auto-Sweep**. Use **Resume Auto-Sweep** to resume automatic triggers. Pausing automatic triggers does not undo enablement. This field continues to report `true` for a wallet that was enabled and later paused. - Enabling auto-sweep is irreversible. After enablement, deposit addresses in this wallet can no longer initiate public token transfers or contract calls by default. Use the deposit-address transaction setting in Cobo Portal to restore permitted activity for specific addresses. + Enabling auto-sweep is irreversible. After enablement, deposit addresses in this wallet can no longer initiate public token transfers or contract calls by default. To restore deposit-address transactions in Cobo Portal, go to **Wallets > Custodial Wallets > Web3 Wallets**, select the wallet, click **Auto-Sweep Settings > Sweep Security**, turn on **Deposit Address Transactions**, and click **Confirm**. This setting applies to the wallet's deposit addresses. UpdateMpcWalletParams: type: object @@ -7422,11 +7426,11 @@ components: - `false`: Does not disable auto-sweep for a wallet that already has it enabled. This field is a one-way enable control. - To stop future automatic sweep triggers for a wallet, use the pause control in Cobo Portal instead of setting this field to `false`. Pausing automatic triggers does not undo enablement. This field continues to report `true` for a wallet that was enabled and later paused. + To stop future automatic sweep triggers in Cobo Portal, go to **Wallets > MPC Wallets > Organization-Controlled Wallets**, select the vault and wallet, click **Auto-Sweep Settings**, and then click **Pause Auto-Sweep**. Use **Resume Auto-Sweep** to resume automatic triggers. Pausing automatic triggers does not undo enablement. This field continues to report `true` for a wallet that was enabled and later paused. - Enabling auto-sweep is irreversible. After enablement, deposit addresses in this wallet can no longer initiate public token transfers or contract calls by default. Use the deposit-address transaction setting in Cobo Portal to restore permitted activity for specific addresses. + Enabling auto-sweep is irreversible. After enablement, deposit addresses in this wallet can no longer initiate public token transfers or contract calls by default. To restore deposit-address transactions in Cobo Portal, go to **Wallets > MPC Wallets > Organization-Controlled Wallets**, select the vault and wallet, click **Auto-Sweep Settings > Sweep Security**, turn on **Deposit Address Transactions**, and click **Confirm**. This setting applies to the wallet's deposit addresses. UpdateSmartContractWalletParams: type: object diff --git a/v2_cn/guides/transactions/manage-transactions.mdx b/v2_cn/guides/transactions/manage-transactions.mdx index 780d8d46..24f9f2f1 100644 --- a/v2_cn/guides/transactions/manage-transactions.mdx +++ b/v2_cn/guides/transactions/manage-transactions.mdx @@ -24,7 +24,7 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; - `PendingAuthorization` - `PendingSignature`（仅当子状态为 `Queue`, `InsufficientBalance`, `InsufficientBalanceFundLocked`, `PendingSignerApproval`, `PendingSystemProcessing`, 或 `Built` 时） -要通过 WaaS 2.0 API 取消交易，请使用 [取消交易](/v2/api-references/transactions/cancel-transaction) 操作。这需要您希望取消的交易的交易 ID。 +要通过 WaaS 2.0 API 取消交易，请使用 [Cancel transaction](/v2/api-references/transactions/cancel-transaction) 操作。这需要您希望取消的交易的交易 ID。 ## Replace-By-Fee (RBF) 交易 @@ -48,7 +48,7 @@ RBF 的两个最常见用例是加速和放弃交易。 只有当交易状态为 `Broadcasting` 时，才能加速交易。 -要加速交易，请使用 [加速交易](/v2/api-references/transactions/speed-up-transaction) 操作。这需要您希望加速的交易的交易 ID。 +要加速交易，请使用 [Speed up transaction](/v2/api-references/transactions/speed-up-transaction) 操作。这需要您希望加速的交易的交易 ID。 如果您加速智能合约钱包的交易，将触发两个 RBF 交易：一个用于智能合约钱包的交易，另一个用于委托人的交易。 @@ -64,7 +64,7 @@ RBF 的两个最常见用例是加速和放弃交易。 只有当交易状态为 `Broadcasting` 时，才能放弃交易。 -要放弃交易，请使用 [放弃交易](/v2/api-references/transactions/drop-transaction) 操作。这需要您希望放弃的交易的交易 ID。 +要放弃交易，请使用 [Drop transaction](/v2/api-references/transactions/drop-transaction) 操作。这需要您希望放弃的交易的交易 ID。 当交易被放弃时，任何后续的放弃或加速操作仍将应用于原始交易。例如，如果用户创建交易 A，然后对交易 A 执行放弃操作使用交易 B，接着对交易 B 执行加速操作使用交易 C，加速操作仍将应用于交易 A，而不是交易 B。