docs: 完善 Webhook 事件与 Transaction 字段文档

docs.json

@@ -46,13 +46,16 @@
                 "pages": [
                   "v2/guides/webhooks-callbacks/introduction",
                   "v2/guides/webhooks-callbacks/set-up-endpoint",
-                  "v2/guides/webhooks-callbacks/webhook-event-type"
+                  "v2/guides/webhooks-callbacks/webhook-event-type",
+                  "v2/guides/webhooks-callbacks/transaction-webhook-events",
+                  "v2/guides/webhooks-callbacks/mpc-tss-request-webhook-events"
                 ]
               },
               {
                 "group": "Transactions",
                 "pages": [
                   "v2/guides/transactions/sources-and-destinations",
+                  "v2/guides/transactions/transaction-fields",
                   "v2/guides/transactions/transfer-routing",
                   "v2/guides/transactions/estimate-fees",
                   "v2/guides/transactions/solana-token-account-rent",
@@ -858,13 +861,16 @@
                 "pages": [
                   "v2_cn/guides/webhooks-callbacks/introduction",
                   "v2_cn/guides/webhooks-callbacks/set-up-endpoint",
-                  "v2_cn/guides/webhooks-callbacks/webhook-event-type"
+                  "v2_cn/guides/webhooks-callbacks/webhook-event-type",
+                  "v2_cn/guides/webhooks-callbacks/transaction-webhook-events",
+                  "v2_cn/guides/webhooks-callbacks/mpc-tss-request-webhook-events"
                 ]
               },
               {
                 "group": "交易",
                 "pages": [
                   "v2_cn/guides/transactions/sources-and-destinations",
+                  "v2_cn/guides/transactions/transaction-fields",
                   "v2_cn/guides/transactions/transfer-routing",
                   "v2_cn/guides/transactions/estimate-fees",
                   "v2_cn/guides/transactions/solana-token-account-rent",
@@ -1598,4 +1604,4 @@
       "destination": "https://www.cobo.com/payments/cn/guides/overview"
     }
   ]
-}
+}

v2/guides/transactions/transaction-fields.mdx

@@ -0,0 +1,126 @@
+---
+title: "Transaction fields"
+lang: "en"
+description: "Reference the Transaction object returned by transaction API operations and delivered in transaction webhook events and callback messages."
+sidebarTitle: "Transaction fields"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx';
+
+<WaasSkillReminder />
+
+## Overview
+
+The `Transaction` object represents a transaction throughout its lifecycle. Transaction API operations, transaction webhook events, and callback messages use this object.
+
+<table class="table-three-cols">
+  <thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead>
+  <tbody>
+    <tr><td><code>transaction_id</code></td><td>string</td><td>Cobo's unique identifier for the transaction.</td></tr>
+    <tr><td><code>cobo_id</code></td><td>string</td><td>The Cobo ID that you can use to track the transaction.</td></tr>
+    <tr><td><code>request_id</code></td><td>string</td><td>Your unique identifier for the API request that initiated the transaction. It is absent when no corresponding request exists, such as for a deposit.</td></tr>
+    <tr><td><code>wallet_id</code></td><td>string</td><td>The unique identifier of the wallet associated with the transaction.</td></tr>
+    <tr><td><code>type</code></td><td>string</td><td>The transaction type, such as <code>Deposit</code>, <code>Withdrawal</code>, <code>ContractCall</code>, or <code>MessageSign</code>.</td></tr>
+    <tr><td><code>status</code></td><td>string</td><td>The transaction's lifecycle stage.</td></tr>
+    <tr><td><code>sub_status</code></td><td>string</td><td>A more specific reason or stage within <code>status</code>.</td></tr>
+    <tr><td><code>failed_reason</code></td><td>string</td><td>Additional detail about why the transaction failed.</td></tr>
+    <tr><td><code>chain_id</code></td><td>string</td><td>The unique identifier of the blockchain on which the transaction occurs.</td></tr>
+    <tr><td><code>token_id</code></td><td>string</td><td>The WaaS token catalog identifier for Custodial Wallet, Web3 Wallet, and MPC Wallet transactions.</td></tr>
+    <tr><td><code>asset_id</code></td><td>string</td><td>The asset identifier in your linked exchange account. It applies only to Exchange Wallet transactions.</td></tr>
+    <tr><td><code>source</code></td><td>object</td><td>The transaction origin. Its shape is selected by <code>source_type</code>.</td></tr>
+    <tr><td><code>destination</code></td><td>object</td><td>The transaction target or signing input. Its shape is selected by <code>destination_type</code>.</td></tr>
+    <tr><td><code>result</code></td><td>object</td><td>The signing result for a <code>MessageSign</code> transaction. It is absent for every other transaction type.</td></tr>
+    <tr><td><code>fee</code></td><td>object</td><td>The network fee details, discriminated by <code>fee_type</code>. It is populated after broadcast and absent while signature or broadcast is pending.</td></tr>
+    <tr><td><code>initiator</code></td><td>string</td><td>The name or identifier of the transaction initiator.</td></tr>
+    <tr><td><code>initiator_type</code></td><td>string</td><td>The channel through which the transaction was initiated.</td></tr>
+    <tr><td><code>confirmed_num</code></td><td>integer</td><td>The number of confirmations received.</td></tr>
+    <tr><td><code>confirming_threshold</code></td><td>integer</td><td>The minimum confirmation count required by Cobo.</td></tr>
+    <tr><td><code>transaction_hash</code></td><td>string</td><td>The on-chain transaction identifier, also called the transaction hash or <code>txid</code>. It is populated only after broadcast.</td></tr>
+    <tr><td><code>block_info</code></td><td>object</td><td>The number, timestamp, and hash of the confirmed block. It is absent before on-chain confirmation and for <code>MessageSign</code> transactions.</td></tr>
+    <tr><td><code>raw_tx_info</code></td><td>object</td><td>The constructed transaction data and any nonce or UTXO details. It is populated after assembly for broadcast and is absent before that stage and for <code>MessageSign</code> transactions.</td></tr>
+    <tr><td><code>replacement</code></td><td>object</td><td>Forward or backward links between an original transaction and its replacement. It appears only when a replacement operation exists.</td></tr>
+    <tr><td><code>category</code></td><td>array of strings</td><td>Your custom categories for organizing transactions.</td></tr>
+    <tr><td><code>description</code></td><td>string</td><td>Your description of the transaction.</td></tr>
+    <tr><td><code>is_loop</code></td><td>boolean</td><td>Whether the transaction was executed as a Cobo Loop transfer.</td></tr>
+    <tr><td><code>cobo_category</code></td><td>array of strings</td><td>System-assigned categories that identify Cobo workflows associated with the transaction.</td></tr>
+    <tr><td><code>extra</code></td><td>array of strings</td><td>JSON-encoded, business-specific information; each item identifies its shape with <code>extra_type</code>.</td></tr>
+    <tr><td><code>fueling_info</code></td><td>object</td><td>Fee Station fueling details associated with the transaction.</td></tr>
+    <tr><td><code>created_timestamp</code></td><td>integer</td><td>The creation time as a Unix timestamp in milliseconds.</td></tr>
+    <tr><td><code>updated_timestamp</code></td><td>integer</td><td>The most recent update time as a Unix timestamp in milliseconds.</td></tr>
+  </tbody>
+</table>
+
+For the complete status and sub-status values, see [Transaction statuses and sub-statuses](/v2/guides/transactions/status).
+
+## `token_id` and `asset_id`
+
+`token_id` is the token's identifier in the WaaS token catalog, such as `ETH`, `ETH_USDT`, or `BTC`. Use [List enabled tokens](/v2/api-references/wallets/list-enabled-tokens) to retrieve the identifiers available to your organization.
+
+`token_id` is populated for Custodial Wallet, Web3 Wallet, and MPC Wallet transactions. `asset_id` is the asset identifier in your linked exchange account and is populated only for Exchange Wallet transactions. A transaction has one field or the other based on its wallet type, not both. The fields are not interchangeable.
+
+## `request_id`
+
+`request_id` is present only for transactions that you initiated through an API request, such as a transaction-creation operation. Use it to correlate the transaction with your original request. It is absent for deposits and other transactions that Cobo created without a corresponding request from you.
+
+## `replacement` and RBF links
+
+The `replacement` object links transactions involved in replacement operations:
+
+| Field | Description |
+|-------|-------------|
+| `replaced_by_type` | The replacement operation applied to the original transaction: `Drop`, `Resend`, or `SpeedUp`. |
+| `replaced_by_transaction_id` | The Cobo transaction ID of the transaction that replaced this transaction. |
+| `replaced_by_transaction_hash` | The on-chain hash of the transaction that replaced this transaction. |
+| `replaced_type` | The replacement operation through which this transaction replaced another transaction. |
+| `replaced_transaction_id` | The Cobo transaction ID of the transaction replaced by this transaction. |
+| `replaced_transaction_hash` | The on-chain hash of the transaction replaced by this transaction. |
+
+See [RBF (Replace-By-Fee) transaction lifecycle](/v2/guides/transactions/rbf-transaction-lifecycle) for replacement operations and status changes.
+
+`replaced_by_transaction_hash` is populated only after the replacing transaction from a `Drop`, `Resend`, or `SpeedUp` operation has broadcast. Use it together with `replaced_by_transaction_id` to look up the replacing transaction.
+
+## `cobo_category`
+
+`cobo_category` is assigned by Cobo and is distinct from your `category` and `description` values. Examples include `AutoFueling`, `BillPayment`, and `AutoSweep`. See [Cobo-defined categories](/v2/guides/transactions/manage-transactions#cobo-defined-categories) for the categorized value list.
+
+## Structured and conditional fields
+
+### `fee`
+
+`fee` is populated after the transaction broadcasts. It is absent while signature or broadcast is pending.
+
+The `fee_type` discriminator selects the fee shape for the chain's fee model: `EVM_EIP_1559`, `EVM_Legacy`, `UTXO`, `Fixed`, `SOL`, or `FIL`. Fee shapes can include the fee token in `token_id`, the charged amount in `fee_used`, and the estimate in `estimated_fee_used`. Chain-specific shapes add fields such as gas prices and gas usage, UTXO fee rates, Solana compute units, or Filecoin gas parameters. See [Estimate transaction fees](/v2/guides/transactions/estimate-fees) for fee models.
+
+### `block_info`
+
+`block_info` is populated after the transaction broadcasts and receives on-chain confirmation. It is absent for pending transactions and for `MessageSign` transactions.
+
+`block_info` contains:
+
+| Field | Description |
+|-------|-------------|
+| `block_number` | The number of the block containing the transaction. |
+| `block_timestamp` | The block creation time as a Unix timestamp in milliseconds. |
+| `block_hash` | The block's hash. |
+
+### `raw_tx_info`
+
+`raw_tx_info` is populated after the transaction has been assembled for broadcast. It is absent before that stage and for `MessageSign` transactions.
+
+`raw_tx_info` contains constructed transaction data:
+
+| Field | Description |
+|-------|-------------|
+| `used_nonce` | The nonce used by the transaction. |
+| `selected_utxos` | The inputs selected for a UTXO transaction. Each item can include `tx_hash`, `vout_n`, `token_id`, `address`, and `value`, plus script or object-chain details when applicable. |
+| `raw_tx` | The serialized raw transaction. |
+| `unsigned_raw_tx` | The serialized transaction before signing. |
+| `utxo_changes` | UTXO change outputs. Each item contains `address`, `value`, and `token_id`. |
+
+### `result`
+
+`result` is present only for `MessageSign` transactions. For a message-signing result, `result_type` is `Signature` and `signature` contains the raw signature data.
+
+## Sources and destinations
+
+`source` and `destination` are discriminated objects. `source_type` identifies the wallet or deposit origin, while `destination_type` identifies an address, wallet, contract call, deposit target, or message-signing format. See [Transaction sources and destinations](/v2/guides/transactions/sources-and-destinations) for the complete fields supported by each transaction type.

v2/guides/webhooks-callbacks/mpc-tss-request-webhook-events.mdx

@@ -0,0 +1,94 @@
+---
+title: "MPC TSS request webhook events"
+lang: "en"
+description: "Understand the payload and lifecycle signals for wallets.mpc.tss_request.* webhook events."
+sidebarTitle: "MPC TSS request webhook events"
+---
+
+import WaasSkillReminder from '/snippets/waas_skill_reminder.mdx';
+
+<WaasSkillReminder />
+
+## Overview
+
+The `wallets.mpc.tss_request.*` webhook events report Cobo Portal key-generation and reshare operations for MPC Wallets. `KeyGen` creates the organization's first Main Group. `KeyGenFromKeyGroup` derives a new Signing Group or Recovery Group from an existing Main Group. `Recovery` replaces a holder's key share within the Main Group.
+
+## Event lifecycle
+
+<table class="table-three-cols">
+  <thead><tr><th>Event</th><th>Data type</th><th>When it occurs</th></tr></thead>
+  <tbody>
+    <tr><td><code>wallets.mpc.tss_request.created</code></td><td><code>TSSRequest</code></td><td>Fires once when the request is created, before any key-holder interaction.</td></tr>
+    <tr><td><code>wallets.mpc.tss_request.updated</code></td><td><code>TSSRequest</code></td><td>Fires for each subsequent intermediate status change, including key-holder confirmation, key generation, and MPC processing states.</td></tr>
+    <tr><td><code>wallets.mpc.tss_request.succeeded</code></td><td><code>TSSRequest</code></td><td>Fires once when the request reaches the terminal <code>Success</code> status.</td></tr>
+    <tr><td><code>wallets.mpc.tss_request.failed</code></td><td><code>TSSRequest</code></td><td>Fires once when the request reaches a terminal failure state and cannot proceed.</td></tr>
+  </tbody>
+</table>
+
+Intermediate statuses such as `PendingKeyHolderConfirmation`, `KeyHolderConfirmationFailed`, `KeyGenerating`, and `MPCProcessing` are delivered through `updated`, not through terminal events. The initial request state is delivered through `created`; terminal outcomes are delivered through `succeeded` or `failed`.
+
+## Payload reference
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tss_request_id` | string | The unique identifier of the TSS request. |
+| `source_key_share_holder_group` | object | The existing source group. It is populated for `KeyGenFromKeyGroup` and `Recovery` and absent for `KeyGen`, which has no prior group. |
+| `target_key_share_holder_group_id` | string | The target group for every request type: the new Main Group for `KeyGen`, the derived Signing or Recovery Group for `KeyGenFromKeyGroup`, or the Main Group whose member key share is replaced for `Recovery`. |
+| `type` | string | The request type: `KeyGen`, `KeyGenFromKeyGroup`, or `Recovery`. |
+| `status` | string | The current TSS request lifecycle status. |
+| `description` | string | The description supplied for the TSS request. |
+| `created_timestamp` | integer | The request creation time as a Unix timestamp in milliseconds. |
+
+When provided, `source_key_share_holder_group` contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `key_share_holder_group_id` | string | The identifier of the source key share holder group. |
+| `tss_node_ids` | array of strings | The TSS Node IDs participating in creation of the new key share holder group. |
+
+The following examples show all four outcomes. Each object includes every field populated for the represented request.
+
+### Created
+
+```json
+{
+  "event_id": "8f2e919a-6a7b-4a9b-8c1a-4c0b3f5b8b1f",
+  "url": "https://example.com/webhook",
+  "created_timestamp": 1701396866000,
+  "type": "wallets.mpc.tss_request.created",
+  "data": {
+    "data_type": "TSSRequest",
+    "tss_request_id": "20240711114129000132315000003970",
+    "target_key_share_holder_group_id": "fd9519ae-507b-4605-b108-04d4e5ffcdd3",
+    "type": "KeyGen",
+    "status": "PendingKeyHolderConfirmation",
+    "description": "Create the first Main Group",
+    "created_timestamp": 1701396866000
+  },
+  "status": "Delivered"
+}
+```
+
+### Updated
+
+```json
+{"event_id":"event-tss-updated","url":"https://example.com/webhook","created_timestamp":1701396966000,"type":"wallets.mpc.tss_request.updated","data":{"data_type":"TSSRequest","tss_request_id":"20240711114129000132315000003971","source_key_share_holder_group":{"key_share_holder_group_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","tss_node_ids":["cobo5yb7BNEBwwp5XXedbhnzQfvQtp132W4dH4Jz4x4eDp4KA"]},"target_key_share_holder_group_id":"fd9519ae-507b-4605-b108-04d4e5ffcdd3","type":"KeyGenFromKeyGroup","status":"MPCProcessing","description":"Create a Signing Group","created_timestamp":1701396866000},"status":"Delivered"}
+```
+
+### Succeeded
+
+```json
+{"event_id":"event-tss-succeeded","url":"https://example.com/webhook","created_timestamp":1701397066000,"type":"wallets.mpc.tss_request.succeeded","data":{"data_type":"TSSRequest","tss_request_id":"20240711114129000132315000003971","source_key_share_holder_group":{"key_share_holder_group_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","tss_node_ids":["cobo5yb7BNEBwwp5XXedbhnzQfvQtp132W4dH4Jz4x4eDp4KA"]},"target_key_share_holder_group_id":"fd9519ae-507b-4605-b108-04d4e5ffcdd3","type":"KeyGenFromKeyGroup","status":"Success","description":"Create a Signing Group","created_timestamp":1701396866000},"status":"Delivered"}
+```
+
+### Failed
+
+```json
+{"event_id":"event-tss-failed","url":"https://example.com/webhook","created_timestamp":1701397166000,"type":"wallets.mpc.tss_request.failed","data":{"data_type":"TSSRequest","tss_request_id":"20240711114129000132315000003972","target_key_share_holder_group_id":"fd9519ae-507b-4605-b108-04d4e5ffcdd4","type":"KeyGen","status":"KeyGeneratingFailed","description":"Create the first Main Group","created_timestamp":1701396866000},"status":"Delivered"}
+```
+
+See [Set up a callback or webhook endpoint](/v2/guides/webhooks-callbacks/set-up-endpoint) for delivery and retry behavior.
+
+## Related guides
+
+- [Webhook event types and data types](/v2/guides/webhooks-callbacks/webhook-event-type)