# Overview

Source: https://docs.settlemint.com/docs/user-guides/system-addons/xvp-settlement/htlc/overview
HTLC settlements coordinate asset exchanges across EVM networks using
hash time-locked contracts. Learn when to use HTLC and what each DALP settlement controls locally.




HTLC (Hash Time-Locked Contract) settlements coordinate asset exchanges when tokens sit on different EVM networks. Each DALP settlement executes only its local flows. A shared hashlock links the matching settlements so the same secret can unlock each chain's local execution before its cutoff date.

This overview is for operators, integrating developers, and reviewers who need the section boundary before they configure or audit an HTLC settlement. The platform controls local approvals, escrowed local flows, secret reveal, execution, cancellation, expiry, and withdrawal on the chain where that settlement exists. The parties that create the matching settlements own the cross-chain coordination: choosing the shared hashlock, staggering timelocks, revealing the secret on the intended chain, and reusing that revealed secret before the other settlement expires.

HTLC settlement docs do not cover bridge transfers, non-EVM networks, off-chain asset movement, or execution of another chain's settlement from the local contract. For single-chain exchanges, use [local settlements](/docs/user-guides/system-addons/xvp-settlement/local/overview) instead. For the protocol mechanics, read [HTLC explained](/docs/user-guides/system-addons/xvp-settlement/htlc/htlc-explained) next. For an end-to-end setup example, read the [HTLC walkthrough](/docs/user-guides/system-addons/xvp-settlement/htlc/walkthrough).

## When to use HTLC settlements [#when-to-use-htlc-settlements]

Use HTLC settlements when:

* Assets being exchanged exist on different EVM networks
* Each chain needs its own local settlement, but both settlements must share one hashlock
* Participants need the revealed secret to unlock the matching settlement on another chain before expiry

## How HTLC settlements work [#how-htlc-settlements-work]

HTLC settlements use two linked components:

1. **Hashlock** - A cryptographic hash that links settlements across chains
2. **Timelock** - A deadline after which the settlement expires

One party generates a secret and shares only the hash (hashlock) with the other participants. The matching settlement on each chain uses the same hashlock.

After all local senders approve, any caller with the correct secret can reveal it. If auto-execute is enabled, DALP executes that settlement's local flows after the reveal.

### The "Armed" state [#the-armed-state]

HTLC settlements have a unique state called "Armed" that occurs after all local senders approve but before the secret is revealed:

<Mermaid
  chart="`
flowchart TB
  P(Pending) --> |all senders approve| A(Armed)
  A --> |secret revealed| E(Executed)
  A --> |cutoff date passes| X(Expired)
  P --> |cutoff date passes| X
  P --> |cancel| C(Cancelled)

  style P fill:#6ba4d4,stroke:#4a7ba8,stroke-width:2px,color:#fff
  style A fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style E fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style C fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style X fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff

`"
/>

| State         | Description                                             |
| ------------- | ------------------------------------------------------- |
| **Pending**   | Settlement created, waiting for sender approvals        |
| **Armed**     | All senders approved, waiting for secret to be revealed |
| **Executed**  | Secret revealed, all flows completed                    |
| **Cancelled** | Settlement cancelled before armed                       |
| **Expired**   | Cutoff date passed before secret was revealed           |

## External flows [#external-flows]

HTLC settlements include two types of flows:

* **Local flows** - Execute on the current chain when the settlement completes
* **External flows** - Informational references to assets on other chains

External flows do not execute locally. They describe the assets and counterparties expected on the other chain.

Each party still operates its own chain's settlement: create, approve, reveal, execute, cancel, or withdraw there.

<Callout type="info" title="External flow purpose">
  External flows help all parties read the complete transaction structure. They do not transfer assets from the local
  settlement contract.
</Callout>

## Auto-execute behavior [#auto-execute-behavior]

When auto-execute is enabled (the default), a settlement executes after both conditions are true:

1. Every local sender has approved the settlement.
2. The correct secret has been revealed.

If auto-execute is disabled, anyone can call execution after those conditions are true.

## Timelock coordination [#timelock-coordination]

For cross-chain safety, timelocks must be staggered:

* The settlement where the secret is revealed first should have the later cutoff.
* The matching settlement should leave enough time for the other party to reuse the revealed secret before expiry.

For a detailed explanation of how hashlocks ensure security, see [HTLC explained](/docs/user-guides/system-addons/xvp-settlement/htlc/htlc-explained).

## Cancellation rules [#cancellation-rules]

| Situation                        | Cancellation possible?                                                     |
| -------------------------------- | -------------------------------------------------------------------------- |
| Before all local senders approve | Yes. A local participant can cancel while the settlement is still pending. |
| Armed, before secret reveal      | Yes, after every local participant has proposed cancellation.              |
| After secret reveal              | No. Cancellation is no longer allowed.                                     |

<Callout type="info" title="Unanimous cancellation required">
  Once an HTLC settlement is armed, every local participant must send a cancellation vote before the secret is revealed.
  When the last required vote lands, the settlement is cancelled and escrowed assets are refunded. See [how to cancel a
  settlement](/docs/user-guides/system-addons/xvp-settlement/actions/cancel).
</Callout>

## Example scenario [#example-scenario]

**Cross-chain bond purchase:**

* Investor has 100,000 USDC on Polygon.
* Bank has 1,000 BOND tokens on Ethereum.
* They want linked settlements without moving either asset away from its own network.

The bank creates the Ethereum settlement with a hashlock. The investor creates a matching Polygon settlement with the same hashlock. After both settlements are armed, the bank reveals the secret on Polygon to unlock the USDC settlement. The investor then reuses the revealed secret on Ethereum to unlock the bond settlement.

For a complete multi-party example with balance tracking, see the [HTLC walkthrough](/docs/user-guides/system-addons/xvp-settlement/htlc/walkthrough). For a focused operator check before approval or secret reveal, see [verify external flows](/docs/user-guides/system-addons/xvp-settlement/htlc/verify-external-flows).

## Further reading [#further-reading]

<Cards>
  <Card title="HTLC explained" href="/docs/user-guides/system-addons/xvp-settlement/htlc/htlc-explained">
    Explore how hash time-locked contracts ensure security.
  </Card>

  <Card title="HTLC walkthrough" href="/docs/user-guides/system-addons/xvp-settlement/htlc/walkthrough">
    Complete multi-party cross-chain settlement example.
  </Card>

  <Card title="Verify external flows" href="/docs/user-guides/system-addons/xvp-settlement/htlc/verify-external-flows">
    Check external-flow fields, hashlocks, cutoff timing, approvals, and secret reveal before execution.
  </Card>
</Cards>