Skip to content

docs: 补充 MPC 钱包余额可用性模型、资金锁定与 BTC/UTXO 说明并优化 12007/30010 错误码指引 #369

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rcsh1 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: 补充 MPC 钱包余额可用性模型、资金锁定与 BTC/UTXO 说明并优化 12007/30010 错误码指引 #369

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions snippets/error-codes-cn.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
| 1003, 2003 | 请求中缺少一个或多个必填参数。 | 提供所有必填参数。 |
| 1006, 2006 | 一个或多个参数格式无效或包含不支持的值。 | 以预期格式提供有效参数。 |
| 12002 | Cobo 不支持指定的代币。 | 选择支持的代币。调用 [List supported tokens](/v2/api-references/wallets/list-supported-tokens) 接口获取完整的支持代币列表。 |
| 12007, 30012 | 余额不足，无法执行请求的操作。 | 确保源地址有足够的余额支付转账金额。 |
| 12007, 30012 | 余额不足，无法执行请求的操作。 | 确保源地址有足够的可用余额来支付提币金额加上交易费用。当资金处于待处理、锁定、合规筛查中或被冻结时，可用余额可能低于当前余额。有关详情，请参见 [MPC 钱包的余额和交易金额](/v2_cn/guides/mpc-wallets/balance-amounts)。如果金额非常小，它可能会以错误 30010（低于尘埃阈值）被拒绝。 |
| 12009, 30001 | 重复的请求 ID。 | 使用唯一的请求 ID。 |
| 12025 | 在 `included_utxos` 或 `excluded_utxos` 中指定的 UTXO 无效。 | 验证 `included_utxos` 或 `excluded_utxos` 中指定的 UTXO。 |
| 2000 | 处理过程中发生内部错误。 | 请稍后重试。 |
Expand All @@ -24,7 +24,7 @@
| 2051 | 当前套餐已过期。 | 续订您的套餐以继续使用服务。更多信息，请参见[账单和付款介绍](https://manuals.cobo.com/cn/portal/bills-and-payments/introduction)。 |
| 30007 | 金额无效。该值不是有效数字或不符合所需格式或范围。 | 提供符合预期格式和范围的有效金额。 |
| 30008 | 绝对金额无效。金额的绝对值太小、太大，或在需要非零值时为零。 | 确保金额的绝对值满足所需条件。 |
| 30010 | 提供的金额低于尘埃阈值。金额太小，无法处理或转账。 | 增加金额以超过尘埃阈值。 |
| 30010 | 提供的金额低于尘埃阈值。金额太小，无法处理或转账。 | 增加金额以超过该代币的尘埃阈值。尘埃阈值按代币配置。此错误表示金额太小无法转账，与错误 12007（余额不足）不同。 |
| 30011 | 提供的金额低于最低充币阈值。 | 增加充币金额以满足最低阈值。 |
| 30013 | 余额不足以支付所需的交易费用。 | 确保源地址有足够的余额支付交易费用。 |
| 30014 | 目标地址无效。 | 提供有效的目标地址。 |
Expand Down
4 changes: 2 additions & 2 deletions snippets/error-codes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ This article explains the common error codes and HTTP status codes you may encou
| 1003, 2003 | One or more required parameters are missing in the request. | Provide all required parameters. |
| 1006, 2006 | One or more parameters are in an invalid format or contain unsupported values. | Provide valid parameters in the expected format. |
| 12002 | The specified token is not supported by Cobo. | Choose a supported token. Call the [List supported tokens](/v2/api-references/wallets/list-supported-tokens) operation to get the full list of supported tokens. |
| 12007, 30012 | Insufficient balance to perform the requested operation. | Ensure the source address has sufficient balance to cover the transferred amount. |
| 12007, 30012 | Insufficient balance to perform the requested operation. | Ensure the source address has enough available balance to cover the withdrawal amount plus the transaction fee. The available balance can be lower than the current balance when funds are pending, locked, held for compliance screening, or frozen. For details, see [Balances and transaction amounts for MPC Wallets](/v2/guides/mpc-wallets/balance-amounts). If the amount is very small, it may instead be rejected with error 30010 (below the dust threshold). |
| 12009, 30001 | Duplicate request ID. | Use a unique request ID. |
| 12025 | The UTXOs specified in `included_utxos` or `excluded_utxos` are invalid. | Verify the UTXOs specified in `included_utxos` or `excluded_utxos`. |
| 2000 | Internal error occurred during processing. | Please try again later. |
Expand All @@ -22,7 +22,7 @@ This article explains the common error codes and HTTP status codes you may encou
| 2051 | The current pricing plan has expired. | Renew your pricing plan to continue using the service. For more information, see [Introduction to Bills & Payments](https://manuals.cobo.com/en/portal/bills-and-payments/introduction). |
| 30007 | Invalid amount. The value is not a valid number or does not meet the required format or range. | Provide a valid amount that meets the expected format and range. |
| 30008 | Invalid absolute amount. The absolute value of the amount is either too small, too large, or zero when a non-zero value is required. | Ensure the absolute value of the amount meets the required conditions. |
| 30010 | The provided amount is below the dust threshold. It is too small to be processed or transferred. | Increase the amount to exceed the dust threshold. |
| 30010 | The provided amount is below the dust threshold. It is too small to be processed or transferred. | Increase the amount to exceed the token's dust threshold. The dust threshold is configured per token. This error means the amount is too small to transfer and is distinct from error 12007 (insufficient balance). |
| 30011 | The provided amount is below the minimum deposit threshold. | Increase the deposit amount to meet the minimum threshold. |
| 30013 | Insufficient balance to cover the required transaction fee. | Ensure the source address has enough balance to cover transaction fees. |
| 30014 | The destination address is invalid. | Provide a valid destination address. |
Expand Down
60 changes: 59 additions & 1 deletion v2/guides/mpc-wallets/balance-amounts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,22 @@ This diagram illustrates the relationship between these values:

<img src="/v2/images/guides/balances_amount.svg" className="diagram" alt="Definitions of several types of balances and amounts"></img>

## Balance availability model

The values in [Definitions](#definitions) are the public fields returned by the [List token balances by address](/v2/api-references/wallets/list-token-balances-by-address) operation. When a withdrawal is rejected for insufficient balance, the error response may report internal field names. The following table maps those internal field names to the public balance fields.

| Error response field | Public balance field | Meaning |
| -------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------- |
| `using_amount` | `data.balance.pending` | Amount reserved by in-flight transactions (withdrawal amount plus transaction fee). |
| `locked_amount` | `data.balance.locked` | Value of funds locked for in-flight transactions; for UTXO chains, the combined value of selected UTXOs. |
| `spendable` | `data.balance.available` | Amount ready to be spent. |

The available balance is derived as follows:

`spendable = on-chain balance - using_amount - amount pending compliance screening - net frozen amount`

The available balance can be lower than the current balance even when there is no obvious pending withdrawal, for example when funds are held for compliance screening or are frozen.

## Update time

These values are updated at different times during a deposit and withdrawal transaction.
Expand Down Expand Up @@ -61,6 +77,15 @@ These values are updated at different times during a deposit and withdrawal tran
- Locked amount: Equal to 0
- Available balance: Equal to the current balance

## Fund locking

Funds are locked when you create and sign a withdrawal or other outgoing transaction. Locking happens in two stages:

1. When the transaction is created and signed, the required amount moves from available to locked. This is why the available balance drops as soon as a withdrawal is submitted, before on-chain confirmation. For the corresponding balance changes, see the `PendingSignature` step in [Update time](#withdrawals).
2. Locked funds are released only when the transaction succeeds, or when a failure is confirmed on-chain. A confirmed failure means the network has finalized that the transaction will not be included (for example, the transaction is reverted or dropped), at which point the funds return to available.

For UTXO chains such as Bitcoin, a single withdrawal can lock UTXOs across multiple addresses at once when coin selection spans more than one address. All selected UTXOs are locked together, scoped to that transaction, and released together when the transaction settles or fails.

## Replace-By-Fee (RBF) transactions

If you speed up a transaction with an RBF transaction, the RBF transaction will be used in calculating the pending amount and locked amount.
Expand All @@ -73,4 +98,37 @@ The maximum amount you can withdraw is affected by the transaction fee, availabl

- (Withdrawal amount + transaction fee) > Available balance: The withdrawal request cannot be submitted.
- (Withdrawal amount + transaction fee) ≤ (Current balance - locked amount): Your withdrawal request will be handled immediately.
- (Current balance - locked amount) < (Withdrawal amount + transaction fee) ≤ Available balance: You can successfully submit your withdrawal request, but your transaction will be queued.
- (Current balance - locked amount) < (Withdrawal amount + transaction fee) ≤ Available balance: You can successfully submit your withdrawal request, but your transaction will be queued.

## Bitcoin and UTXO considerations

### Available balance after a deposit

For Bitcoin and other UTXO-based chains, the available balance is derived from indexed on-chain UTXO data. After a deposit, the current balance can already reflect the deposit while the available balance still reads 0 until the new UTXOs finish indexing. Wait for indexing to complete before withdrawing the deposited funds.

### Minimum transfer amount (dust threshold)

Each token has a configurable dust threshold. A withdrawal whose amount is below that token's dust threshold is rejected with error `30010` (amount below the dust threshold), not error `12007` (insufficient balance). To proceed, increase the amount above the threshold. The dust threshold is configured per token.

### Consolidating UTXOs

A withdrawal that spends many small UTXOs produces a larger transaction and higher network fees. Consolidate small UTXOs ahead of large withdrawals to reduce transaction size and fees.

## Payment balances

Payment balances follow a different model from MPC Wallet balances. The following concepts apply to payment accounts:

- **Total balance**: The available balance plus the frozen amount.
- **Available balance**: The balance that can be withdrawn.
- **Frozen amount**: The portion held for in-flight payouts.

For full details on payments, see the [Payments documentation](https://www.cobo.com/payments/en/guides/overview).

## Troubleshooting insufficient balance

When a withdrawal is rejected with error `12007` (insufficient balance), work through the following checks:

1. **Genuine shortfall**: Compare the withdrawal amount plus the transaction fee against `data.balance.available`. If it exceeds the available balance, the address lacks spendable funds. Deposit more funds or reduce the amount.
2. **Locked, pending, screening, or frozen funds**: If `data.balance.available` is lower than `data.balance.total`, funds are reserved in `data.balance.pending`, held in `data.balance.locked` by in-flight transactions, or held for compliance screening or frozen. Wait for them to settle or be released. For details, see [Balance availability model](#balance-availability-model) and [Fund locking](#fund-locking).
3. **Un-indexed UTXOs**: On Bitcoin and other UTXO chains, if the available balance reads 0 shortly after a deposit, the new UTXOs may still be indexing. Wait and recheck. For details, see [Bitcoin and UTXO considerations](#bitcoin-and-utxo-considerations).
4. **Dust**: If the amount is very small, it may instead be rejected with error `30010` (below the dust threshold) rather than `12007`. Increase the amount above the token's dust threshold.
Loading