docs: 明确交易 webhook 事件关系

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": "智能合约调用示例",

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        | <ul><li>**[Custodial Wallets]** [Transaction history](/v1/api-references/custody-wallet/transaction_history)</li><li>**[MPC Wallets]** [Get Transactions List](/v1/api-references/mpc-wallet/mpc_list_transactions)</li></ul> | <ul><li>[List all transactions](/v2/api-references/transactions/list-all-transactions)</li><li>[Get transaction information](/v2/api-references/transactions/get-transaction-information)</li></ul>|
 
+<Warning>
+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`.
+</Warning>
+
 ## Upgrade to 2.0
 
 This section introduces the detailed steps to upgrade from WaaS 1.0 to 2.0.

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:

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.

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';
+
+<WaasSkillReminder />
+
+## 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)

v2/guides/transactions/sources-and-destinations.mdx

@@ -16,6 +16,8 @@ Refer to the following table for the source and destination types corresponding
 
 <Note>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.</Note>
 
+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         |

v2/guides/transactions/status.mdx

@@ -274,6 +274,20 @@ The table below provides an overview of transaction statuses and sub-statuses re
   </tr>
 </table>
 
+## Status details
+
+<Note>
+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.
+</Note>
+
+<Warning>
+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.
+</Warning>
+
+<Note>
+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.
+</Note>
+
 ## 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).

v2/guides/transactions/transaction-process-mpc.mdx

@@ -33,4 +33,8 @@ The following diagram illustrates how a withdrawal is processed. Colors are used
 <img src="/v2/images/guides/mpc-withdrawal-en.png" className="diagram" alt="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.
+- 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.
+
+<Warning>
+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.
+</Warning>

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';
+
+<WaasSkillReminder />
+
+## 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)

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
     <tr>
       <td><code>wallets.transaction.updated</code></td>
       <td><code>Transaction</code></td>
-      <td>There are changes to a transaction's status or confirmation numbers.<Note>The <code>wallets.transaction.updated</code> 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.</Note></td>
+      <td>There are changes to a transaction's status or confirmation numbers, including when the transaction reaches a terminal outcome.<Note>See <a href="#how-transaction-events-relate-to-each-other">How transaction events relate to each other</a> below for how this event relates to <code>wallets.transaction.succeeded</code> and <code>wallets.transaction.failed</code>.</Note></td>
     </tr>
     <tr>
       <td><code>wallets.transaction.succeeded</code></td>
       <td><code>Transaction</code></td>
-      <td>A transaction has been successfully completed.</td>
+      <td>A transaction has been successfully completed.<Note>Always accompanied by a <code>wallets.transaction.updated</code> event for the same transition. See <a href="#how-transaction-events-relate-to-each-other">How transaction events relate to each other</a>.</Note></td>
     </tr>
     <tr>
       <td><code>wallets.transaction.failed</code></td>
       <td><code>Transaction</code></td>
-      <td>A transaction failed.</td>
+      <td>A transaction failed.<Note>Always accompanied by a <code>wallets.transaction.updated</code> event for the same transition. See <a href="#how-transaction-events-relate-to-each-other">How transaction events relate to each other</a>.</Note></td>
     </tr>
     <tr>
       <td><code>token.suspended.deposit</code></td>
@@ -63,6 +63,21 @@ For payment webhook events, please refer to [Order Status and Events](/v2/paymen
   </tbody>
 </table>
 
+#### 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
 
 <table class="table-three-cols">
@@ -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**.
+Additionally, you can view all webhook events in your organization on **Cobo Portal** > **Developer**> **Webhook Events**.