diff --git a/docs.json b/docs.json index 4092a7a9..5dfe8a8c 100644 --- a/docs.json +++ b/docs.json @@ -53,6 +53,7 @@ "group": "Transactions", "pages": [ "v2/guides/transactions/sources-and-destinations", + "v2/guides/transactions/transfer-routing", "v2/guides/transactions/estimate-fees", "v2/guides/transactions/solana-token-account-rent", { @@ -64,6 +65,7 @@ ] }, "v2/guides/transactions/manage-transactions", + "v2/guides/transactions/rbf-transaction-lifecycle", "v2/guides/transactions/validate-addresses", { "group": "Smart contract call samples", @@ -863,6 +865,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", { @@ -874,6 +877,7 @@ ] }, "v2_cn/guides/transactions/manage-transactions", + "v2_cn/guides/transactions/rbf-transaction-lifecycle", "v2_cn/guides/transactions/validate-addresses", { "group": "智能合约调用示例", diff --git a/v2/guides/overview/upgrade-guide.mdx b/v2/guides/overview/upgrade-guide.mdx index 85df20ed..984af2a6 100644 --- a/v2/guides/overview/upgrade-guide.mdx +++ b/v2/guides/overview/upgrade-guide.mdx @@ -70,6 +70,10 @@ The following table lists the API operations needed for common wallet operations | Sign a message | Not supported | [Sign message](/v2/api-references/transactions/sign-message) | | Query a transaction | | | + +WaaS 2.0 list endpoints, such as [List all transactions](/v2/api-references/transactions/list-all-transactions), return results in pages. By default each page returns 10 records, and the maximum page size is 50, set with the `limit` parameter. This differs from WaaS 1.0, where a single response could return all results. A single WaaS 2.0 page therefore omits later results. To retrieve every record, iterate through all pages using the cursor parameters `before` and `after`. + + ## Upgrade to 2.0 This section introduces the detailed steps to upgrade from WaaS 1.0 to 2.0. diff --git a/v2/guides/transactions/estimate-fees.mdx b/v2/guides/transactions/estimate-fees.mdx index bec71531..dd4f6872 100644 --- a/v2/guides/transactions/estimate-fees.mdx +++ b/v2/guides/transactions/estimate-fees.mdx @@ -177,6 +177,13 @@ The logic for estimating RBF transaction fees is similar to that for normal tran - Fixed: Increase the fee amount. - Filecoin: It is recommended to increase both gas premium and gas fee cap by 25%. +## Fees on Layer 2 chains + +On Layer 2 (L2) chains such as Arbitrum, network fees can change rapidly. If fees rise sharply after you submit a transaction, the transaction can remain in the `PendingSignature` or `Broadcasting` status longer than expected. 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 Below is how Cobo calculates the fees for each model: diff --git a/v2/guides/transactions/manage-transactions.mdx b/v2/guides/transactions/manage-transactions.mdx index e5ce6de3..2c909078 100644 --- a/v2/guides/transactions/manage-transactions.mdx +++ b/v2/guides/transactions/manage-transactions.mdx @@ -55,6 +55,8 @@ Replace-By-Fee (RBF) is a feature that allows you to replace an unconfirmed tran The two most common use cases of RBF are speeding up and dropping transactions. +For how a replaced transaction's status changes and the events it emits, see [RBF (Replace-By-Fee) transaction lifecycle](/v2/guides/transactions/rbf-transaction-lifecycle). + ### Speed up a transaction Speeding up a transaction leverages RBF to replace the original transaction with a version with a higher fee, encouraging miners to prioritize it for faster confirmation. diff --git a/v2/guides/transactions/rbf-transaction-lifecycle.mdx b/v2/guides/transactions/rbf-transaction-lifecycle.mdx new file mode 100644 index 00000000..51b8b8ff --- /dev/null +++ b/v2/guides/transactions/rbf-transaction-lifecycle.mdx @@ -0,0 +1,43 @@ +--- +title: "RBF (Replace-By-Fee) transaction lifecycle" +lang: "en" +description: "Understand how Replace-By-Fee (RBF) replaces an unconfirmed transaction, how the original transaction's status changes, and the events you receive." +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx'; + + + +## Overview + +Replace-By-Fee (RBF) replaces an unconfirmed, already-broadcast transaction with a new version. This guide describes the full lifecycle of an RBF replacement: the replacement operations you can perform, how the original transaction's status changes, and the events you receive. + +For the step-by-step operations, see [Manage transactions](/v2/guides/transactions/manage-transactions). For the fee rules that apply to RBF transactions, see [Estimate transaction fees](/v2/guides/transactions/estimate-fees#replace-by-fee-rbf-transaction-fee). + +## Replacement operations + +WaaS 2.0 supports the following RBF operations: + +- **Speed up**: Replaces the original transaction with a higher-fee version so that it confirms faster. Use the [Speed up transaction](/v2/api-references/transactions/speed-up-transaction) operation. +- **Drop**: Replaces the original transaction with a version that effectively cancels it. Use the [Drop transaction](/v2/api-references/transactions/drop-transaction) operation. + +Both operations apply only when the original transaction is in the `Broadcasting` status. They do not apply to transactions on the following chains: VET, TRON, TVET, SOL, and TON. + +## Original transaction status after replacement + +When a replacement transaction takes effect, the original transaction moves to the `Failed` status with the sub-status `ReplacedByNewTransaction`. For the complete list of statuses and sub-statuses, see [Transaction statuses and sub-statuses](/v2/guides/transactions/status). + +## Chained replacements + +Any subsequent drop or speed-up operations continue to apply to the original transaction. For example, if you create Transaction A, perform a drop operation on Transaction A using Transaction B, and then perform a speed-up operation on Transaction B using Transaction C, the speed-up operation still applies to Transaction A, not Transaction B. + +## Events + +RBF status changes are surfaced through the WaaS 2.0 transaction webhook events. 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 + +- [Manage transactions](/v2/guides/transactions/manage-transactions) +- [Estimate transaction fees](/v2/guides/transactions/estimate-fees) +- [Transaction statuses and sub-statuses](/v2/guides/transactions/status) +- [Transaction sources and destinations](/v2/guides/transactions/sources-and-destinations) diff --git a/v2/guides/transactions/sources-and-destinations.mdx b/v2/guides/transactions/sources-and-destinations.mdx index cc7b853b..33e65299 100644 --- a/v2/guides/transactions/sources-and-destinations.mdx +++ b/v2/guides/transactions/sources-and-destinations.mdx @@ -16,6 +16,8 @@ Refer to the following table for the source and destination types corresponding If you transfer tokens between two wallets created on Cobo Portal, two transactions will be recorded: a deposit into the destination wallet and a withdrawal from the source wallet. +To control whether a transfer is routed internally through Cobo Loop or on-chain, see [Transfer routing](/v2/guides/transactions/transfer-routing). + | Transaction type | Source Type | Destination Type | |----------------------------------------------------|-------------------------------------------------------------------------------------------------|--------------------------| | Deposit - [Cobo Loop](https://manuals.cobo.com/en/portal/custodial-wallets/cobo-loop) transfers | DepositFromLoop | DepositToAddress | diff --git a/v2/guides/transactions/status.mdx b/v2/guides/transactions/status.mdx index 7a32ac7a..97757df1 100644 --- a/v2/guides/transactions/status.mdx +++ b/v2/guides/transactions/status.mdx @@ -274,6 +274,20 @@ The table below provides an overview of transaction statuses and sub-statuses re +## Status details + + +The `PendingAuthorization` status aggregates both manual approval steps and internal automated checks. Manual steps include `PendingApproverCheck`, `PendingSpenderCheck`, and `PendingDoubleCheck`. Automated checks include `PendingRiskControlCheck` and `PendingCoboCheck`. A transaction in `PendingAuthorization` does not necessarily require a person to act, because it may be undergoing automated risk-control or compliance checks. + + + +After a transaction is approved, it enters the `PendingSignature` status and must be signed by the MPC signer group within a limited signing window. If signing does not complete within this window, the transaction automatically fails and moves to the `Failed` status with the sub-status `FailedSignerTimeout`. To find out why a transaction failed, check the `sub_status` field returned by [List all transactions](/v2/api-references/transactions/list-all-transactions) or [Get transaction information](/v2/api-references/transactions/get-transaction-information). If you encounter `FailedSignerTimeout`, 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. + + + +A transaction in the `Confirming` status with the sub-status `PendingBlockConfirmations` is waiting for the required number of block confirmations on its chain. This is a normal part of processing and does not mean the transaction is stuck. The required number of confirmations and the expected confirmation time vary by chain. + + ## Available actions You can perform the following actions based on the transaction status: @@ -286,4 +300,6 @@ You can perform the following actions based on the transaction status: - Resend a transaction if its status is `Failed`. - Speed up or drop a transaction if its status is `Broadcasting`. +For details on how a replaced transaction's status changes, see [RBF (Replace-By-Fee) transaction lifecycle](/v2/guides/transactions/rbf-transaction-lifecycle). + For more details, refer to [Manage transactions](/v2/guides/transactions/manage-transactions). \ No newline at end of file diff --git a/v2/guides/transactions/transaction-process-mpc.mdx b/v2/guides/transactions/transaction-process-mpc.mdx index 0d6346a1..f003d4f0 100644 --- a/v2/guides/transactions/transaction-process-mpc.mdx +++ b/v2/guides/transactions/transaction-process-mpc.mdx @@ -33,4 +33,8 @@ The following diagram illustrates how a withdrawal is processed. Colors are used Withdrawal process - If a withdrawal is rejected or unsuccessful, the tokens will be returned to your wallet, and your balance will remain unchanged. -- If your withdrawal amount is smaller than the minimum withdrawal threshold, the withdrawal request will receive an error. You can call the [Get token information](/v2/api-references/wallets/get-token-information) operation to retrieve the minimum withdrawal amount for each token type. \ No newline at end of file +- If your withdrawal amount is smaller than the minimum withdrawal threshold, the withdrawal request will receive an error. You can call the [Get token information](/v2/api-references/wallets/get-token-information) operation to retrieve the minimum withdrawal amount for each token type. + + +After a withdrawal is approved, it enters the `PendingSignature` status and must be signed by the MPC signer group within a limited signing window. If signing does not complete in time, the transaction automatically fails and moves to the `Failed` status with the sub-status `FailedSignerTimeout`. To confirm the reason, check the `sub_status` field returned by [Get transaction information](/v2/api-references/transactions/get-transaction-information). 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 new file mode 100644 index 00000000..5f3b2044 --- /dev/null +++ b/v2/guides/transactions/transfer-routing.mdx @@ -0,0 +1,34 @@ +--- +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." +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx'; + + + +## Overview + +Every token transfer is processed in one of the following ways: + +- **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 whether the transfer uses Cobo Loop or is sent on-chain: `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). | + +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 + +- [Transaction sources and destinations](/v2/guides/transactions/sources-and-destinations) +- [Cobo Loop](https://manuals.cobo.com/en/portal/custodial-wallets/cobo-loop) diff --git a/v2/guides/webhooks-callbacks/webhook-event-type.mdx b/v2/guides/webhooks-callbacks/webhook-event-type.mdx index 0acafca6..b321addd 100644 --- a/v2/guides/webhooks-callbacks/webhook-event-type.mdx +++ b/v2/guides/webhooks-callbacks/webhook-event-type.mdx @@ -38,17 +38,17 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen wallets.transaction.updated Transaction - There are changes to a transaction's status or confirmation numbers.The wallets.transaction.updated event covers the entire lifecycle of a transaction, including creation, completion, and failure. If you want to track every status change, you need only subscribe to this event. + There are changes to a transaction's status or confirmation numbers, including when the transaction reaches a terminal outcome.See How transaction events relate to each other below for how this event relates to wallets.transaction.succeeded and wallets.transaction.failed. wallets.transaction.succeeded Transaction - A transaction has been successfully completed. + A transaction has been successfully completed.Always accompanied by a wallets.transaction.updated event for the same transition. See How transaction events relate to each other. wallets.transaction.failed Transaction - A transaction failed. + A transaction failed.Always accompanied by a wallets.transaction.updated event for the same transition. See How transaction events relate to each other. token.suspended.deposit @@ -63,6 +63,21 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen +#### How transaction events relate to each other + +| Transaction lifecycle stage | `wallets.transaction.created` | `wallets.transaction.updated` | `wallets.transaction.succeeded` | `wallets.transaction.failed` | +|---|---|---|---|---| +| Transaction first detected on-chain | Emitted | — | — | — | +| A handled status or confirmation-count change (non-terminal) | — | Emitted | — | — | +| Transaction reaches a terminal successful state | — | Emitted | Emitted | — | +| Transaction reaches a terminal failed state | — | Emitted | — | Emitted | + +Every handled transaction transition, terminal or not, produces a `wallets.transaction.updated` event. When the transition is terminal, Cobo additionally emits `wallets.transaction.succeeded` or `wallets.transaction.failed` alongside that `wallets.transaction.updated` event. `wallets.transaction.succeeded` and `wallets.transaction.failed` are never sent on their own. + +Subscribing only to `wallets.transaction.updated` is sufficient to observe every status change in a transaction's lifecycle, including its terminal outcome, so it works well for driving a progress indicator (for example, updating a pending-transaction view as confirmation numbers increase). However, do not treat `wallets.transaction.updated` as an early signal that a transaction has succeeded — it does not by itself confirm the terminal outcome. For actions that depend on the transaction's final result, such as releasing goods or crediting a balance, use the dedicated `wallets.transaction.succeeded` and `wallets.transaction.failed` events. + +Because the terminal event and its accompanying `wallets.transaction.updated` event are delivered as two separate webhook notifications, handle them idempotently: key your processing on the transaction identity (for example, `transaction_id`) together with the event type, and skip any event you have already processed for that transaction. Webhook events are not guaranteed to arrive in generation order and may be delivered more than once — see [Respond to the API request](/v2/guides/webhooks-callbacks/set-up-endpoint#webhook-events) for delivery-order behavior and [Important notes](/v2/guides/webhooks-callbacks/set-up-endpoint#%E2%9A%A0%EF%B8%8F%E2%9A%A0%EF%B8%8F%E2%9A%A0%EF%B8%8Fimportant-notes) for duplicate-delivery handling. + ### Fee Station events @@ -297,4 +312,4 @@ For a complete introduction of the webhook event data and its data structure, re Switch between the event data types to view the data structure of each event data type. -Additionally, you can view all webhook events in your organization on **Cobo Portal** > **Developer**> **Webhook Events**. \ No newline at end of file +Additionally, you can view all webhook events in your organization on **Cobo Portal** > **Developer**> **Webhook Events**. diff --git a/v2_cn/guides/overview/upgrade-guide.mdx b/v2_cn/guides/overview/upgrade-guide.mdx index d729e1f6..ba462ce0 100644 --- a/v2_cn/guides/overview/upgrade-guide.mdx +++ b/v2_cn/guides/overview/upgrade-guide.mdx @@ -62,15 +62,19 @@ WaaS 2.0 相较于 WaaS 1.0 进行了重大升级，面向支付、代币化、 | | WaaS 1.0 | WaaS 2.0 | | -------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -| 创建钱包 | 不支持，因为 API Key 是钱包特定的 | [创建钱包](/v2/api-references/wallets/create-wallet) | -| 创建地址 | | [在钱包中创建地址](/v2/api-references/wallets/create-addresses-in-wallet) | -| 提取代币 | | [转账代币](/v2/api-references/transactions/transfer-token) | -| RBF 交易（加速） | **[MPC 钱包]** [加速交易](/v1/api-references/mpc-wallet/mpc_speedup_transaction) | [加速交易](/v2/api-references/transactions/speed-up-transaction) | -| RBF 交易（放弃） | **[MPC 钱包]** [放弃交易](/v1/api-references/mpc-wallet/mpc_drop_transaction) | [放弃交易](/v2/api-references/transactions/drop-transaction) | -| 取消交易 | 不支持 | [取消交易](/v2/api-references/transactions/cancel-transaction) | -| 调用合约 | 不支持 | [调用智能合约](/v2/api-references/transactions/call-smart-contract) | -| 签名消息 | 不支持 | [签名消息](/v2/api-references/transactions/sign-message) | -| 查询交易 | | | +| 创建钱包 | 不支持，因为 API Key 是钱包特定的 | [Create wallet](/v2/api-references/wallets/create-wallet) | +| 创建地址 | | [Create addresses in wallet](/v2/api-references/wallets/create-addresses-in-wallet) | +| 提取代币 | | [Transfer token](/v2/api-references/transactions/transfer-token) | +| RBF 交易（加速） | **[MPC 钱包]** [加速交易](/v1/api-references/mpc-wallet/mpc_speedup_transaction) | [Speed up transaction](/v2/api-references/transactions/speed-up-transaction) | +| RBF 交易（放弃） | **[MPC 钱包]** [放弃交易](/v1/api-references/mpc-wallet/mpc_drop_transaction) | [Drop transaction](/v2/api-references/transactions/drop-transaction) | +| 取消交易 | 不支持 | [Cancel transaction](/v2/api-references/transactions/cancel-transaction) | +| 调用合约 | 不支持 | [Call smart contract](/v2/api-references/transactions/call-smart-contract) | +| 签名消息 | 不支持 | [Sign message](/v2/api-references/transactions/sign-message) | +| 查询交易 | | | + + +WaaS 2.0 的列表类接口（例如 [List all transactions](/v2/api-references/transactions/list-all-transactions)）会分页返回结果。默认情况下每页返回 10 条记录，最大每页为 50 条，通过 `limit` 参数设置。这与 WaaS 1.0 不同：在 1.0 中单次响应可返回全部结果。因此 WaaS 2.0 的单页会遗漏后续结果。如需获取全部记录，请使用游标参数 `before` 和 `after` 遍历所有页。 + ## 升级步骤 diff --git a/v2_cn/guides/transactions/estimate-fees.mdx b/v2_cn/guides/transactions/estimate-fees.mdx index eb5d3c24..0060b391 100644 --- a/v2_cn/guides/transactions/estimate-fees.mdx +++ b/v2_cn/guides/transactions/estimate-fees.mdx @@ -179,6 +179,13 @@ Replace-By-Fee (RBF) 是一种允许您用新版本替换未确认交易的功 - 固定模型：增加固定金额。 - Filecoin 模型：Gas Premium 和 Gas Fee Cap 建议提升 25%。 +## 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)。 + ## Cobo 如何估算费用 下列表格展示了不同费用模型下的费用估算方法： diff --git a/v2_cn/guides/transactions/manage-transactions.mdx b/v2_cn/guides/transactions/manage-transactions.mdx index 88c1edd4..19432e32 100644 --- a/v2_cn/guides/transactions/manage-transactions.mdx +++ b/v2_cn/guides/transactions/manage-transactions.mdx @@ -54,6 +54,8 @@ Replace-By-Fee (RBF) 是一种允许您用新版本替换未确认交易的功 RBF 的两个最常见用例是加速和放弃交易。 +有关被替换交易的状态变化及其触发的事件，请参阅 [RBF (Replace-By-Fee) 交易生命周期](/v2_cn/guides/transactions/rbf-transaction-lifecycle)。 + ### 加速交易 加速交易利用 RBF 用更高费用的版本替换原始交易，鼓励矿工优先处理以更快确认。 diff --git a/v2_cn/guides/transactions/rbf-transaction-lifecycle.mdx b/v2_cn/guides/transactions/rbf-transaction-lifecycle.mdx new file mode 100644 index 00000000..6d1a5593 --- /dev/null +++ b/v2_cn/guides/transactions/rbf-transaction-lifecycle.mdx @@ -0,0 +1,43 @@ +--- +title: "RBF (Replace-By-Fee) 交易生命周期" +lang: "zh-hans" +description: "了解 Replace-By-Fee (RBF) 如何替换未确认交易、原交易的状态如何变化，以及您会收到哪些事件。" +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; + + + +## 概述 + +Replace-By-Fee (RBF) 使用新版本替换已广播但尚未确认的交易。本指南介绍 RBF 替换的完整生命周期：您可以执行的替换操作、原交易的状态如何变化，以及您会收到哪些事件。 + +有关分步操作，请参阅 [管理交易](/v2_cn/guides/transactions/manage-transactions)。有关适用于 RBF 交易的费用规则，请参阅 [估算交易费用](/v2_cn/guides/transactions/estimate-fees#replace-by-fee-rbf-交易费用)。 + +## 替换操作 + +WaaS 2.0 支持以下 RBF 操作： + +- **Speed up**：用更高费用的版本替换原交易，使其更快确认。请使用 [Speed up transaction](/v2/api-references/transactions/speed-up-transaction) 操作。 +- **Drop**：用可有效取消原交易的版本替换原交易。请使用 [Drop transaction](/v2/api-references/transactions/drop-transaction) 操作。 + +这两种操作仅在原交易处于 `Broadcasting` 状态时适用。它们不适用于以下链上的交易：VET、TRON、TVET、SOL 和 TON。 + +## 替换后原交易的状态 + +当替换交易生效时，原交易将转入 `Failed` 状态，子状态为 `ReplacedByNewTransaction`。有关状态和子状态的完整列表，请参阅 [交易状态和子状态](/v2_cn/guides/transactions/status)。 + +## 链式替换 + +任何后续的放弃或加速操作都将继续应用于原交易。例如，如果您创建交易 A，使用交易 B 对交易 A 执行放弃操作，然后使用交易 C 对交易 B 执行加速操作，则该加速操作仍将应用于交易 A，而不是交易 B。 + +## 事件 + +RBF 的状态变化通过 WaaS 2.0 交易 Webhook 事件呈现。请订阅 `wallets.transaction.updated` 事件，该事件覆盖交易的完整生命周期（包括失败）。有关详细信息，请参阅 [Webhook 事件类型和数据类型](/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) diff --git a/v2_cn/guides/transactions/sources-and-destinations.mdx b/v2_cn/guides/transactions/sources-and-destinations.mdx index 03379cfd..29fd3ddf 100644 --- a/v2_cn/guides/transactions/sources-and-destinations.mdx +++ b/v2_cn/guides/transactions/sources-and-destinations.mdx @@ -16,6 +16,8 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 如果您在 Cobo Portal 上的两个钱包之间转移代币，将记录两笔交易：一笔存入目的地钱包，一笔从来源钱包提取。 +如需控制转账是通过 Cobo Loop 内部路由还是链上路由，请参阅 [Transfer routing](/v2_cn/guides/transactions/transfer-routing)。 + | 交易类型 | 交易来源类型 | 交易目的地类型 | |----------------------------------------------------|-------------------------------------------------------------------------------------------------|--------------------------| | Deposit - [Cobo Loop](https://manuals.cobo.com/cn/portal/custodial-wallets/cobo-loop) 转账 | DepositFromLoop | DepositToAddress | diff --git a/v2_cn/guides/transactions/status.mdx b/v2_cn/guides/transactions/status.mdx index b201f1be..2657ac36 100644 --- a/v2_cn/guides/transactions/status.mdx +++ b/v2_cn/guides/transactions/status.mdx @@ -274,6 +274,20 @@ WaaS 2.0 定义了各种交易状态和子状态，以反映不同的处理阶
+## 状态详情 + + +`PendingAuthorization` 状态同时涵盖人工审批步骤和内部自动检查。人工步骤包括 `PendingApproverCheck`、`PendingSpenderCheck` 和 `PendingDoubleCheck`。自动检查包括 `PendingRiskControlCheck` 和 `PendingCoboCheck`。处于 `PendingAuthorization` 状态并不一定需要人工操作，因为交易可能正在进行自动风控或合规检查。 + + + +交易经审批通过后会进入 `PendingSignature` 状态，并且必须在有限的签名时间窗口内由 MPC 签名人组完成签名。如果未能在时间窗口内完成签名，交易将自动失败并转入 `Failed` 状态，子状态为 `FailedSignerTimeout`。如需确认交易失败原因，请查看 [List all transactions](/v2/api-references/transactions/list-all-transactions) 或 [Get transaction information](/v2/api-references/transactions/get-transaction-information) 返回的 `sub_status` 字段。如果遇到 `FailedSignerTimeout`，该交易已处于终态 `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)。 + + + +处于 `Confirming` 状态且子状态为 `PendingBlockConfirmations` 的交易，正在等待其所在链所需数量的区块确认。这是正常处理过程的一部分，并不表示交易卡住。所需的确认数量和预计确认时间因链而异。 + + ## 可用操作 您可以根据交易状态执行以下操作： @@ -286,4 +300,6 @@ WaaS 2.0 定义了各种交易状态和子状态，以反映不同的处理阶 - 如果交易状态是 `Failed`，您可以重发交易。 - 如果交易状态是 `Broadcasting`，您可以加速或放弃交易。 +有关被替换交易的状态如何变化的详细信息，请参阅 [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 9ab338c8..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,4 +34,8 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 提币流程 - 如果提币被拒绝或不成功，代币将返回到您的钱包，您的余额将保持不变。 -- 如果您的提币金额小于最低提币门槛，提币请求将收到错误。您可以调用 [获取代币信息](/v2/api-references/wallets/get-token-information) 操作来检索每种代币类型的最低提币金额。 \ No newline at end of file +- 如果您的提币金额小于最低提币门槛，提币请求将收到错误。您可以调用 [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) 操作发起一笔新转账。 + diff --git a/v2_cn/guides/transactions/transfer-routing.mdx b/v2_cn/guides/transactions/transfer-routing.mdx new file mode 100644 index 00000000..940670d3 --- /dev/null +++ b/v2_cn/guides/transactions/transfer-routing.mdx @@ -0,0 +1,34 @@ +--- +title: "转账路由" +lang: "zh-hans" +description: "了解代币转账如何通过 Cobo Loop 转账或链上转账处理，以及如何使用请求参数控制该行为。" +--- + +import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; + + + +## 概述 + +每笔代币转账都会以下列方式之一处理： + +- **Cobo Loop 转账**：当目的地支持时，通过 Cobo Loop 转账网络在 Cobo Portal 账户之间以链下方式结算。 +- **链上转账**：将交易广播到区块链上。 + +## 使用请求参数控制路由 + +[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；否则发送到链上。 | +| 两者均为 `true` | 请求将被拒绝，返回 HTTP 400 错误（错误码 `2006`，参数无效）。 | + +这些参数仅适用于目的地为地址的转账。有关支持的目的地类型，请参阅 [Transfer token](/v2/api-references/transactions/transfer-token) 操作。 + +## 相关指南 + +- [交易来源和目的地](/v2_cn/guides/transactions/sources-and-destinations) +- [Cobo Loop](https://manuals.cobo.com/cn/portal/custodial-wallets/cobo-loop) diff --git a/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx b/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx index 4653ec1e..98774a91 100644 --- a/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx +++ b/v2_cn/guides/webhooks-callbacks/webhook-event-type.mdx @@ -39,17 +39,17 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; wallets.transaction.updated Transaction - 交易的状态或确认数发生变化。`wallets.transaction.updated` 涵盖交易的整个生命周期，包括创建、完成和失败。如果您想跟踪每个状态变化，订阅此事件即可。 + 交易的状态或确认数发生变化，包括交易达到最终结果时。下方[交易事件之间的关系](#交易事件之间的关系)说明了此事件与 `wallets.transaction.succeeded` 和 `wallets.transaction.failed` 的关系。 wallets.transaction.succeeded Transaction - 交易已成功完成。 + 交易已成功完成。此事件总是与同一次流转的 `wallets.transaction.updated` 事件一同触发。参阅[交易事件之间的关系](#交易事件之间的关系)。 wallets.transaction.failed Transaction - 交易失败。 + 交易失败。此事件总是与同一次流转的 `wallets.transaction.updated` 事件一同触发。参阅[交易事件之间的关系](#交易事件之间的关系)。 token.suspended.deposit @@ -64,6 +64,21 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; +#### 交易事件之间的关系 + +| 交易生命周期阶段 | `wallets.transaction.created` | `wallets.transaction.updated` | `wallets.transaction.succeeded` | `wallets.transaction.failed` | +|---|---|---|---|---| +| 首次在链上检测到交易 | 触发 | — | — | — | +| 已处理的状态或确认数变化（非最终状态） | — | 触发 | — | — | +| 交易达到最终成功状态 | — | 触发 | 触发 | — | +| 交易达到最终失败状态 | — | 触发 | — | 触发 | + +对于每一次已处理的交易状态流转（无论是否为最终状态），Cobo 都会触发一次 `wallets.transaction.updated` 事件。当该次流转是最终状态时，Cobo 还会在同一次流转中额外触发 `wallets.transaction.succeeded` 或 `wallets.transaction.failed` 事件。`wallets.transaction.succeeded` 和 `wallets.transaction.failed` 不会单独触发。 + +仅订阅 `wallets.transaction.updated` 即可观察交易生命周期中的每一次状态变化，包括其最终结果，因此适合用于展示交易进度（例如，随着确认数增加更新待确认交易的展示状态）。但请勿将 `wallets.transaction.updated` 视为交易已成功的早期信号——它本身并不能确认最终结果。对于依赖交易最终结果的操作（例如放行商品或为余额入账），请使用专门的 `wallets.transaction.succeeded` 和 `wallets.transaction.failed` 事件。 + +由于最终事件与同时触发的 `wallets.transaction.updated` 事件是作为两条独立的 webhook 通知投递的，请对它们进行幂等处理：以交易标识（例如 `transaction_id`）结合事件类型作为处理依据，跳过已处理过的同一交易的事件。Webhook 事件不保证按生成顺序到达，也可能重复投递——投递顺序行为请参阅[响应 API 请求](/v2_cn/guides/webhooks-callbacks/set-up-endpoint#webhook-事件)，重复投递的处理方法请参阅[注意事项](/v2_cn/guides/webhooks-callbacks/set-up-endpoint#%E2%9A%A0%EF%B8%8F%E2%9A%A0%EF%B8%8F%E2%9A%A0%EF%B8%8F-%E6%B3%A8%E6%84%8F%E4%BA%8B%E9%A1%B9)。 + ### Fee Station 相关事件 @@ -299,4 +314,4 @@ import WaasSkillReminder from '/snippets/waas_skill_reminder_cn.mdx'; 您可以在事件数据类型之间切换来查看每个事件数据类型的数据结构。 -另外，您可以在 **Cobo Portal** > **开发者** > **Webhook 事件** 中查看团队中的所有 webhook 事件。 \ No newline at end of file +另外，您可以在 **Cobo Portal** > **开发者** > **Webhook 事件** 中查看团队中的所有 webhook 事件。