# PEARL HTLC Settlement Model

Black Pearl Market combines EVM escrow for USDC with an HTLC-style PEARL settlement model. The buyer locks USDC in the EVM escrow contract, while the seller prepares a Taproot-based PEARL lock and release flow. This gives each side a clear settlement path without direct buyer-to-seller USDC transfers.

The important point is that PEARL-side settlement is not a hidden bot mechanism. The Telegram Bot and OTC Web App help users build, verify, and follow the lifecycle, but the protocol logic is on-chain and transaction-based.

## Simple Flow

```mermaid
flowchart TD
  A[Buyer takes order] --> B[Buyer locks USDC in EVM escrow]
  B --> C[Seller prepares PEARL Taproot lock]
  C --> D[Taproot release transaction targets known buyer]
  D --> E[Wallet-secured secret coordinates settlement]
  E --> F[Buyer receives PEARL]
  F --> G[Seller claims USDC from escrow]
  E --> H[Timeout or recovery path if needed]
```

1. The buyer creates a wallet-secured secret and the matching hashlock.
2. The buyer locks USDC in the contract-based USDC escrow.
3. The seller locks PEARL with a Taproot lock transaction.
4. The seller prepares a Taproot release transaction for the known buyer.
5. The wallet-secured secret is revealed through the PEARL-side release path.
6. The PEARL-side proof makes the seller eligible to claim USDC during the seller claim window.
7. If the lifecycle cannot complete in time, refund paths apply according to the protocol rules.

## Why The Known Buyer Matters

The release path is built only after the buyer is known. That matters because the seller's pre-signed release is not a blank permission to spend the PEARL lock.

The Taproot release transaction is prepared with the intended buyer output already defined. The seller signs that release transaction after the buyer, amount, lock output, and release data are known. As a result, the buyer receives PEARL only through the intended release transaction.

This makes the pre-signed release safe to use in the settlement lifecycle: it cannot be redirected to an arbitrary buyer without invalidating the seller's signature.

## Taproot Lock And Release

The PEARL-side settlement uses two related transactions:

| Transaction                 | Purpose                                                                                 |
| --------------------------- | --------------------------------------------------------------------------------------- |
| Taproot lock transaction    | Seller locks PEARL into the PEARL-side settlement output.                               |
| Taproot release transaction | Spends that locked PEARL to the known buyer when the wallet-secured secret is revealed. |

The Taproot lock commits to the hashlock-based release condition and the seller refund condition. The release path uses the wallet-secured secret as the coordination point between the PEARL side and the EVM escrow side.

The seller signs the Taproot release transaction using Taproot sighash `0x83`, which corresponds to `SIGHASH_SINGLE | SIGHASH_ANYONECANPAY`. In this model, `0x83` is used so the seller signature is bound to the intended release input and corresponding buyer output, while still allowing the transaction to be completed with appropriate fee handling. Fee inputs and change can be added around the release, but the signed buyer output cannot be changed without invalidating the seller signature.

## Secret And Claim Lifecycle

The wallet-secured secret starts on the buyer side. Pearl Wallet can create the secret and expose only the hashlock until release is needed. The secret is not a general exportable credential for the OTC flow.

When PEARL is released, the secret/proof becomes visible through the PEARL-side settlement transaction. The PRC20 Indexer verifies the settlement proof before marking the swap as USDC-claimable. Verification includes the locked output, revealed secret, hashlock match, known buyer output, expected PEARL amount, and seller `0x83` release signature where applicable.

Once the proof is available, the seller can use the same secret to claim USDC from the EVM escrow within the seller claim window. The EVM escrow and PEARL-side settlement therefore work together as one cross-chain lifecycle:

| Side                  | What It Secures                                                      |
| --------------------- | -------------------------------------------------------------------- |
| EVM escrow            | Buyer USDC, seller claim, buyer refund after timeout.                |
| PEARL-side settlement | Seller PEARL lock, known-buyer release, seller refund after timeout. |

## Refund Paths

Refunds are part of the protocol design, not an exceptional support process.

If PEARL-side settlement does not complete before the PEARL refund time, the seller can use the PEARL refund path according to the Taproot lock rules. If the USDC side remains unclaimed until the EVM refund time, the buyer may refund USDC according to the EVM escrow contract rules.

The PEARL refund window is intentionally earlier than the EVM refund window so the lifecycle has time to reveal, verify, and use the secret before USDC recovery becomes available.

## Component Roles

| Component     | Public Role                                                                                           |
| ------------- | ----------------------------------------------------------------------------------------------------- |
| Pearl Wallet  | Creates wallet-secured secrets, signs PEARL lock/release/refund transactions, and protects user keys. |
| OTC Web App   | Guides users through bid, lock, release, claim, and refund actions.                                   |
| Telegram Bot  | Automates eligible Bot-Assisted Order steps when the user selected that experience.                   |
| PRC20 Indexer | Tracks public PEARL and EVM state, verifies lock/release/refund proofs, and exposes lifecycle status. |
| EVM escrow    | Holds buyer USDC and enforces claim/refund rules on the EVM side.                                     |

## What This Model Does Not Mean

This design reduces reliance on direct counterparty trust, but users should still account for network, wallet, timing, and indexing risk. Pearl and EVM settlement occur on separate networks, indexers and wallets still need to observe and submit transactions correctly, and users must respect the visible claim and refund windows.

The strength of the model is that the critical settlement conditions are expressed through public transactions, Taproot signatures, a wallet-secured secret, and a contract-based USDC escrow rather than through private promises.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blackpearlmarket.com/overview/pearl-htlc-model.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.