# HTLC settlements

Source: https://docs.settlemint.com/docs/operators/user-guides/system-addons/xvp-settlement/htlc/overview
Use HTLC settlements to coordinate EVM asset exchanges across chains with a shared hashlock,
local settlement controls, and party-managed secret reveal before each cutoff date.




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

Read this page before you configure or review an HTLC settlement.

DALP enforces local-chain controls. The parties coordinate the cross-chain steps. The lifecycle can move through pending, armed, ready, executed, cancelled, or expired.

DALP controls local approvals, escrowed local flows, secret reveal, execution, cancellation, expiry, and withdrawal on the chain where the settlement exists. The parties that create the matching settlements coordinate the cross-chain parts: choosing the shared hashlock, setting safe timelocks, revealing the secret on the intended chain, and reusing the revealed secret before the matching 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/operators/user-guides/system-addons/xvp-settlement/local/overview) instead. For the protocol mechanics, read [HTLC explained](/docs/operators/user-guides/system-addons/xvp-settlement/htlc/htlc-explained) next. For an end-to-end setup example, read the [HTLC walkthrough](/docs/operators/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 32-byte keccak256 hash that links settlements across chains.
2. **Timelock** - the cutoff timestamp after which that settlement expires.

One party generates a secret and shares only the hashlock with the other participants. The matching settlement on each chain uses the same hashlock. DALP can also derive the hashlock from a supplied secret during creation.

After all local senders approve, any caller with the correct secret can reveal it.

With auto-execute enabled, DALP executes the local flows after reveal. With auto-execute disabled, execution remains a separate step after the settlement is ready.

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

HTLC settlements become armed after every local sender has approved, but before the secret is revealed. At that point, the local settlement is locked behind the hashlock and cutoff date while the parties finish the matching chain.

<Mermaid
  chart="`
flowchart LR
  subgraph Local[Local DALP settlement]
      P[Pending\ncreated, waiting for local approvals]
      A[Armed\nall local senders approved]
      R[Ready\nsecret revealed]
      E[Executed\nlocal flows completed]
      C[Cancelled\nrefund before completion]
      X[Expired\nwithdraw after cutoff]
  end

  subgraph External[Matching settlement on another EVM chain]
      M[Same hashlock]
      S[Secret revealed by a party]
      T[Staggered cutoff]
  end

  P -->|local senders approve| A
  A -->|valid secret revealed| R
  R -->|auto-execute on or execute called| E
  R -->|cutoff passes before execute| X
  P -->|cancel before armed| C
  A -->|unanimous local cancel before reveal| C
  P -->|cutoff passes| X
  A -->|cutoff passes before reveal| X
  M --> A
  S --> R
  T --> X

  style Local fill:#eef7ff,stroke:#4a7ba8,stroke-width:2px,color:#16324f
  style External fill:#f4f1ff,stroke:#654bad,stroke-width:2px,color:#2f235f
  style P fill:#6ba4d4,stroke:#4a7ba8,stroke-width:2px,color:#fff
  style A fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style R fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style E fill:#4aa564,stroke:#2f7d45,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
  style M fill:#fff,stroke:#654bad,stroke-width:1px,color:#2f235f
  style S fill:#fff,stroke:#654bad,stroke-width:1px,color:#2f235f
  style T fill:#fff,stroke:#654bad,stroke-width:1px,color:#2f235f

`"
/>

| State         | Description                                                                |
| ------------- | -------------------------------------------------------------------------- |
| **Pending**   | Settlement created, waiting for local sender approvals                     |
| **Armed**     | All local senders approved, waiting for the matching secret reveal         |
| **Ready**     | Secret revealed, execution conditions satisfied, execution still available |
| **Executed**  | Local flows completed                                                      |
| **Cancelled** | Settlement cancelled before completion                                     |
| **Expired**   | Cutoff date passed before the secret was revealed or execution completed   |

## 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]

Auto-execute is an explicit settlement setting. When auto-execute is enabled, 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.

The API and settlement wizard default this setting to disabled. Enable auto-execute only when the workflow should execute as soon as approval and secret reveal are both complete.

## 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.

Before you approve or reveal a secret, check that both settlements use the same hashlock, that each local flow is on the expected chain, and that the earlier cutoff still leaves enough time to reuse the revealed secret. See [verify external flows](/docs/operators/user-guides/system-addons/xvp-settlement/htlc/verify-external-flows) for the operator checklist.

For a detailed explanation of how hashlocks protect the exchange, see [HTLC explained](/docs/operators/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/operators/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/operators/user-guides/system-addons/xvp-settlement/htlc/walkthrough). For a focused operator check before approval or secret reveal, see [verify external flows](/docs/operators/user-guides/system-addons/xvp-settlement/htlc/verify-external-flows).

## Further reading [#further-reading]

Use the related HTLC pages in this order when you move from concept to operation:

<Cards>
  <Card title="HTLC explained" href="/docs/operators/user-guides/system-addons/xvp-settlement/htlc/htlc-explained">
    Learn the hashlock, secret reveal, timelock, expiry, and refund mechanics behind the overview.
  </Card>

  <Card title="HTLC walkthrough" href="/docs/operators/user-guides/system-addons/xvp-settlement/htlc/walkthrough">
    Configure and execute the multi-party cross-chain example with balance tracking.
  </Card>

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