# HTLC explained

Source: https://docs.settlemint.com/docs/operators/system-addons/xvp-settlement/htlc/htlc-explained
Understand how Hash Time-Locked Contracts coordinate XvP settlement legs with a shared secret and cutoff dates.




Hash Time-Locked Contracts (HTLCs) coordinate settlement legs with a shared secret and a deadline. In DALP XvP, an HTLC hashlock links the local settlement leg to an external leg, while the cutoff date prevents assets from staying locked forever.

## HTLC requirements by flow type [#htlc-requirements-by-flow-type]

An XvP settlement can contain local flows, external flows, or a mix of both. The HTLC requirement differs by type.

| Flow type     | What DALP records                                                                                        | HTLC requirement                                         |
| ------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| Local flow    | The on-chain asset, sender, recipient, and amount managed by the DALP settlement contract                | A hashlock is optional when every flow is local          |
| External flow | The asset, sender, recipient, amount, external chain ID, and external asset decimals for the outside leg | The settlement requires a secret or precomputed hashlock |

The hashlock does not move assets by itself. The hashlock makes one secret usable across linked settlement legs. DALP validates the secret against the hashlock on the local settlement contract. The other chain or external system must use the same secret and safe timing for the exchange to complete.

## The two controls [#the-two-controls]

### Hashlock [#hashlock]

A hashlock is a 32-byte `keccak256` hash of a secret value. It lets parties commit to a shared secret without revealing the preimage:

```text
hashlock = keccak256(secret)
```

The settlement can store the hashlock before the secret is public. When a party later reveals the secret, the contract hashes it and checks that it matches the stored hashlock. The public hashlock lets parties coordinate without sharing the secret early, because the preimage stays private until the owner is ready for the linked leg to execute.

### Cutoff date [#cutoff-date]

The cutoff date is the settlement deadline. Before the cutoff date, an approved settlement executes once the hashlock condition clears. After the cutoff date passes, the contract no longer accepts secret reveals, and any escrowed assets can be withdrawn instead of staying locked indefinitely.

For external XvP flows, cutoff dates must leave enough time for the receiving party to use the secret on the other leg. The staggering rule is directional: the settlement where the secret is revealed first should carry a later cutoff. If a party claims assets on the first chain after seeing the secret, the receiving settlement on the second chain must still accept reveals before its own cutoff expires.

<Callout type="warn" title="Cutoff dates are part of the safety model">
  DALP enforces the cutoff date on the local settlement. DALP does not validate that an external chain or off-platform
  flow uses a safe matching deadline. Operators must coordinate the timing across every leg of the exchange.
</Callout>

## Example exchange [#example-exchange]

A bank sells tokenised bonds for stablecoins across two EVM networks:

| Leg            | Asset movement              | Chain context           | Timing role                                                  |
| -------------- | --------------------------- | ----------------------- | ------------------------------------------------------------ |
| Bond leg       | Bank sends BOND to Investor | DALP local settlement   | Must remain open after the stablecoin leg reveals the secret |
| Stablecoin leg | Investor sends USDC to Bank | External settlement leg | Reveals the secret first                                     |

The bank generates a secret and shares only the hashlock with the investor. Both settlement legs use the same hashlock.

<Mermaid
  chart="`
flowchart TD
  A[Bank creates a secret] --> B[Bank shares the hashlock]
  B --> C[Bond leg is created in DALP]
  B --> D[Stablecoin leg is created externally]
  C --> E[Local senders approve]
  D --> F[Secret is revealed on the stablecoin leg]
  F --> G[Bank receives stablecoins]
  F --> H[Investor can use the revealed secret on the bond leg]
  H --> I[Investor receives bonds]

  style A fill:#6ba4d4,stroke:#4a7ba8,stroke-width:2px,color:#fff
  style B fill:#6ba4d4,stroke:#4a7ba8,stroke-width:2px,color:#fff
  style C fill:#2f4f6f,stroke:#1f354d,stroke-width:2px,color:#fff
  style D fill:#2f4f6f,stroke:#1f354d,stroke-width:2px,color:#fff
  style E fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style F fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style G fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style H fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style I fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff

`"
/>

The sequence works because the bond leg remains open after the stablecoin leg reveals the secret. If the bond leg expired first, the bank could withdraw the bonds and still use the secret on the stablecoin leg. That timing would leave the investor exposed.

## What happens when the secret is revealed [#what-happens-when-the-secret-is-revealed]

When you reveal a secret for a DALP XvP settlement, the platform checks the local settlement state before execution.

| Check           | Required condition                                                        |
| --------------- | ------------------------------------------------------------------------- |
| Secret match    | The provided secret hashes to the settlement hashlock                     |
| Sender approval | All local senders have approved the flows they send                       |
| Cutoff date     | The settlement is still before its cutoff date                            |
| Auto-execute    | If enabled, the settlement executes after the platform accepts the secret |

The XvP create API accepts either a raw secret or a precomputed hashlock for cross-chain flows. The hashlock must be a `0x`-prefixed 32-byte hex string. Local-only settlements do not require a hashlock.

`autoExecute` defaults to `false` in the API schema. With auto-execute off, revealing the secret makes the settlement ready for execution, but a caller must trigger execution separately.

## Failure modes [#failure-modes]

| Scenario                                           | Local settlement outcome                                    | What to do                                                                                   |
| -------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| No party reveals the secret                        | The settlement remains locked until the cutoff date         | Withdraw after expiry                                                                        |
| A local sender does not approve                    | The settlement cannot execute                               | Collect the missing approval or cancel the settlement where the workflow allows cancellation |
| A party reveals the secret too late on another leg | The receiving party may not have enough time to act locally | Use safer cutoff-date buffers before creating the exchange                                   |
| A party submits the wrong secret                   | The hashlock check fails                                    | Use the original preimage that produced the stored hashlock                                  |

## How to coordinate safely [#how-to-coordinate-safely]

Before you create or approve an HTLC settlement:

* Treat the secret as a settlement credential until you are ready to reveal it.
* Use the same hashlock on every linked leg.
* Confirm that each receiving leg stays open after the secret becomes visible.
* Keep enough operational time for network confirmation, wallet approval, and incident response.
* Run the external-flow verification checklist before you rely on an off-platform leg.

## Related [#related]

* [HTLC overview](/docs/operators/system-addons/xvp-settlement/htlc/overview)
* [HTLC walkthrough](/docs/operators/system-addons/xvp-settlement/htlc/walkthrough)
* [Reveal an HTLC secret](/docs/operators/system-addons/xvp-settlement/actions/reveal-secret)
* [Verify external XvP flows](/docs/operators/system-addons/xvp-settlement/htlc/verify-external-flows)