# Walkthrough

Source: https://docs.settlemint.com/docs/user-guides/system-addons/xvp-settlement/htlc/walkthrough
Follow a complete multi-party cross-chain settlement where a Builder sells tokenized
real estate to two Buyers, with a Notary receiving fees across Ethereum and Polygon.




This walkthrough demonstrates a complex multi-party HTLC settlement involving four parties across two blockchains. You'll see how XvP coordinates cross-chain exchanges and handles multiple flows.

<Callout type="info" title="Prerequisites">
  This walkthrough assumes you understand how HTLC works. If you're new to HTLCs, we recommend reading the [HTLC
  explanation](/docs/user-guides/system-addons/xvp-settlement/htlc/htlc-explained) first to learn about hashlocks,
  timelocks, and why the mechanism is cryptographically secure.
</Callout>

## Scenario: Tokenized real estate sale [#scenario-tokenized-real-estate-sale]

### The parties [#the-parties]

| Party       | Role                                 | Chain    |
| ----------- | ------------------------------------ | -------- |
| **Builder** | Sells property tokens                | Ethereum |
| **Buyer 1** | Purchases 50% ownership              | Polygon  |
| **Buyer 2** | Purchases 50% ownership              | Polygon  |
| **Notary**  | Handles legal transfer, receives fee | Polygon  |

### The deal [#the-deal]

* Builder sells an apartment tokenized as 100 APT-101 tokens on Ethereum
* Buyer 1 and Buyer 2 each purchase 50% (50 tokens each)
* Total price: 500,000 USDC + 5,000 USDC notary fee

| Item            | Amount                          |
| --------------- | ------------------------------- |
| Property price  | 500,000 USDC                    |
| Buyer 1's share | 250,000 USDC + 2,500 notary fee |
| Buyer 2's share | 250,000 USDC + 2,500 notary fee |
| Notary fee      | 5,000 USDC total                |

## Settlement structures [#settlement-structures]

### Ethereum settlement (created by Builder) [#ethereum-settlement-created-by-builder]

| Field                              | Value                                        |
| ---------------------------------- | -------------------------------------------- |
| **Local flows**                    |                                              |
| Flow 1                             | Builder → Buyer 1: 50 APT-101                |
| Flow 2                             | Builder → Buyer 2: 50 APT-101                |
| **External flows** (informational) |                                              |
| Flow 3                             | Buyer 1 → Builder: 250,000 USDC (on Polygon) |
| Flow 4                             | Buyer 2 → Builder: 250,000 USDC (on Polygon) |
| Flow 5                             | Buyer 1 → Notary: 2,500 USDC (on Polygon)    |
| Flow 6                             | Buyer 2 → Notary: 2,500 USDC (on Polygon)    |
| **Hashlock**                       | `0xdef456...`                                |
| **Timelock**                       | January 20, 2025 at 5:00 PM                  |
| **Auto-execute**                   | Enabled                                      |

### Polygon settlement (created by Buyer 1) [#polygon-settlement-created-by-buyer-1]

| Field                              | Value                                                  |
| ---------------------------------- | ------------------------------------------------------ |
| **Local flows**                    |                                                        |
| Flow 1                             | Buyer 1 → Builder: 250,000 USDC                        |
| Flow 2                             | Buyer 2 → Builder: 250,000 USDC                        |
| Flow 3                             | Buyer 1 → Notary: 2,500 USDC                           |
| Flow 4                             | Buyer 2 → Notary: 2,500 USDC                           |
| **External flows** (informational) |                                                        |
| Flow 5                             | Builder → Buyer 1: 50 APT-101 (on Ethereum)            |
| Flow 6                             | Builder → Buyer 2: 50 APT-101 (on Ethereum)            |
| **Hashlock**                       | `0xdef456...` (same as Ethereum)                       |
| **Timelock**                       | January 19, 2025 at 5:00 PM (24 hours before Ethereum) |
| **Auto-execute**                   | Enabled                                                |

<Callout type="info" title="Only senders approve">
  On Ethereum, only the Builder approves (sending tokens). On Polygon, only Buyer 1 and Buyer 2 approve (sending USDC).
  Recipients don't take action.
</Callout>

## Balance tracking [#balance-tracking]

### Ethereum chain [#ethereum-chain]

| Step    | Action                       | Builder     | Buyer 1    | Buyer 2    | XvP Contract |
| ------- | ---------------------------- | ----------- | ---------- | ---------- | ------------ |
| Initial | -                            | 100 APT-101 | 0          | 0          | 0            |
| Create  | Builder creates settlement   | 100 APT-101 | 0          | 0          | 0            |
| Approve | Builder approves → **Armed** | 0           | 0          | 0          | 100 APT-101  |
| Execute | Secret revealed              | 0           | 50 APT-101 | 50 APT-101 | 0            |

### Polygon chain [#polygon-chain]

| Step      | Action                       | Builder      | Notary     | Buyer 1      | Buyer 2      | XvP Contract |
| --------- | ---------------------------- | ------------ | ---------- | ------------ | ------------ | ------------ |
| Initial   | -                            | 0            | 0          | 252,500 USDC | 252,500 USDC | 0            |
| Create    | Buyer 1 creates settlement   | 0            | 0          | 252,500 USDC | 252,500 USDC | 0            |
| Approve 1 | Buyer 1 approves             | 0            | 0          | 0            | 252,500 USDC | 252,500 USDC |
| Approve 2 | Buyer 2 approves → **Armed** | 0            | 0          | 0            | 0            | 505,000 USDC |
| Execute   | Secret revealed              | 500,000 USDC | 5,000 USDC | 0            | 0            | 0            |

## Step-by-step walkthrough [#step-by-step-walkthrough]

<Steps>
  <Step>
    ### Builder generates the secret [#builder-generates-the-secret]

    Builder opens the settlement wizard on Ethereum and generates a cryptographic secret:

    * **Secret:** `0x7a8b9c...` (Builder saves this securely)
    * **Hashlock:** `keccak256(secret) = 0xdef456...`

    The Builder keeps the secret private and shares only the hashlock with the Buyers.
  </Step>

  <Step>
    ### Builder creates settlement on Ethereum [#builder-creates-settlement-on-ethereum]

    Builder configures the settlement:

    1. Adds two local flows (property tokens to each Buyer)
    2. Adds four external flows (USDC from Buyers on Polygon)
    3. Sets timelock to January 20, 2025 at 5:00 PM
    4. Enables auto-execute
    5. Submits the transaction
  </Step>

  <Step>
    ### Builder shares hashlock with Buyers [#builder-shares-hashlock-with-buyers]

    Builder shares the hashlock `0xdef456...` with Buyer 1 and Buyer 2. The Buyers can verify:

    * The settlement exists on Ethereum
    * It contains the correct flows (they'll receive property tokens)
    * The hashlock matches what they'll use on Polygon

    **Important:** Builder does NOT share the secret yet - only the hashlock.
  </Step>

  <Step>
    ### Buyer 1 creates settlement on Polygon [#buyer-1-creates-settlement-on-polygon]

    Buyer 1 creates the matching settlement on Polygon:

    1. Adds four local flows (USDC from both Buyers to Builder and Notary)
    2. Enters the same hashlock `0xdef456...`
    3. Sets timelock to January 19, 2025 at 5:00 PM (24 hours before Ethereum)
    4. Enables auto-execute
    5. Submits the transaction
  </Step>

  <Step>
    ### Builder approves on Ethereum [#builder-approves-on-ethereum]

    Builder approves the Ethereum settlement:

    1. Opens the settlement detail page
    2. Clicks **Approve**
    3. Confirms the transaction (transfers 100 APT-101 to the XvP contract)

    The Ethereum settlement enters **Armed** state (only one local sender: Builder).
  </Step>

  <Step>
    ### Buyers approve on Polygon [#buyers-approve-on-polygon]

    **Buyer 1 approves:**

    1. Opens the Polygon settlement
    2. Clicks **Approve**
    3. Confirms (transfers 252,500 USDC to XvP contract)

    Settlement shows "1 of 2 approvals."

    **Buyer 2 approves:**

    1. Opens the Polygon settlement
    2. Clicks **Approve**
    3. Confirms (transfers 252,500 USDC to XvP contract)

    The Polygon settlement enters **Armed** state.
  </Step>

  <Step>
    ### Builder reveals secret on Polygon [#builder-reveals-secret-on-polygon]

    Builder reveals the secret to claim the USDC:

    1. Opens the Polygon settlement
    2. Clicks **Reveal Secret**
    3. Enters the secret `0x7a8b9c...`
    4. Confirms the transaction

    **Auto-execute triggers immediately:**

    * Builder receives 500,000 USDC
    * Notary receives 5,000 USDC

    The Polygon settlement is now **Executed**.
  </Step>

  <Step>
    ### Secret is revealed on Ethereum [#secret-is-revealed-on-ethereum]

    Now that the secret is public (visible on Polygon), anyone can use it on Ethereum.

    **Option A:** Buyers find the secret on-chain in the Polygon transaction.

    **Option B:** Builder emails the secret to Buyers (it's already public, no security risk).

    One of the Buyers reveals the secret on Ethereum:

    1. Opens the Ethereum settlement
    2. Clicks **Reveal Secret**
    3. Enters `0x7a8b9c...`
    4. Confirms

    **Auto-execute triggers immediately:**

    * Buyer 1 receives 50 APT-101
    * Buyer 2 receives 50 APT-101

    The Ethereum settlement is now **Executed**.
  </Step>
</Steps>

## What if something goes wrong? [#what-if-something-goes-wrong]

| Scenario                                                      | What happens                                                                                          |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Secret never revealed before January 19                       | Polygon settlement expires. Buyers withdraw their USDC.                                               |
| Secret revealed on Polygon but not Ethereum before January 20 | Buyers have until January 20 to reveal on Ethereum. After that, Builder can withdraw property tokens. |
| One Buyer doesn't approve on Polygon                          | Settlement never reaches Armed state. After timelock, all approved parties can withdraw.              |
| Network congestion on Ethereum                                | Buyers should reveal the secret well before the January 20 deadline to account for delays.            |

## Next steps [#next-steps]

<Cards>
  <Card title="Create a settlement" href="/docs/user-guides/system-addons/xvp-settlement/actions/create">
    Detailed guide to using the settlement wizard.
  </Card>

  <Card title="Reveal secret" href="/docs/user-guides/system-addons/xvp-settlement/actions/reveal-secret">
    How to reveal the HTLC secret to trigger execution.
  </Card>

  <Card title="Withdraw expired" href="/docs/user-guides/system-addons/xvp-settlement/actions/withdraw-expired">
    How to recover assets from expired settlements.
  </Card>
</Cards>