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

## What HTLC adds to XvP [#what-htlc-adds-to-xvp]

An XvP settlement can contain local flows and external flows.

| 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 | A secret or precomputed hashlock is required    |

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:

```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. The secret is sensitive until the party that owns it 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 can execute when the hashlock condition is satisfied. After the cutoff date, the settlement can be withdrawn instead of staying locked.

For external XvP flows, cutoff dates must leave enough time for the receiving party to use the secret on the other leg. If a party claims assets after seeing a secret revealed elsewhere, the receiving leg must still be open.

<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 secret is accepted |

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. When auto-execute is disabled, revealing the secret makes the settlement ready for execution, but execution is a separate action.

## Failure modes [#failure-modes]

| Scenario                                       | Local settlement outcome                                    | Operator action                                                                              |
| ---------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| The secret is never revealed                   | 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 |
| The secret is revealed 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                                   |
| The wrong secret is submitted                  | The hashlock check fails                                    | Use the original preimage that produced the stored hashlock                                  |

## How to use the concept safely [#how-to-use-the-concept-safely]

* Treat the secret as a settlement credential until it is meant to be public.
* Use the same hashlock on every linked leg.
* Check that each receiving leg stays open after the secret can become visible.
* Keep enough operational time for network confirmation, wallet approval, and incident response.
* Use the external-flow verification checklist before relying 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)