# Reveal secret

Source: https://docs.settlemint.com/docs/operators/system-addons/xvp-settlement/actions/reveal-secret
Reveal the hashlock preimage for an external-flow HTLC settlement, queue the on-chain reveal transaction, and optionally notify counterparties by email.




Reveal the secret when the receiving party is ready to publish the hashlock preimage for an external-flow HTLC settlement. DALP queues a `revealSecret` transaction for the settlement contract. For local-only settlements, there is no chain-side secret reveal to perform.

## Before you reveal [#before-you-reveal]

Check these conditions before using the reveal flow:

* The settlement is an HTLC settlement with an external flow.
* The settlement is ready for the secret reveal. Local senders have approved where sender approval applies.
* You have the original secret value that matches the settlement hashlock.
* The cutoff date has not passed.
* You are ready for the secret to become public.

<Callout type="warning" title="The secret becomes public">
  Revealing the secret publishes the preimage on-chain. Chain observers can reuse the preimage to complete linked HTLC
  settlement steps before their timelocks expire.
</Callout>

## Reveal from the settlement page [#reveal-from-the-settlement-page]

<Steps>
  <Step>
    ### Open the armed HTLC settlement [#open-the-armed-htlc-settlement]

    Go to **Settlements**, open the HTLC settlement, and confirm that the settlement is waiting for the secret. Do not use this control for a local settlement. Local settlements use the normal execute flow.
  </Step>

  <Step>
    ### Enter the secret [#enter-the-secret]

    Click **Reveal Secret** and enter the original secret value. DALP accepts a hex value or a plain string value. The platform converts a plain string to hex before encoding the contract call.
  </Step>

  <Step>
    ### Add email recipients when needed [#add-email-recipients-when-needed]

    If email is configured, add up to 10 valid recipients. DALP includes notification results when the reveal completes synchronously and email sending is attempted. Async reveals return a status URL first, so email is a convenience for counterparties, not the source of truth for the reveal.
  </Step>

  <Step>
    ### Confirm with wallet verification [#confirm-with-wallet-verification]

    Review the confirmation sheet, then approve the reveal with the required wallet verification. DALP queues the reveal transaction against the settlement contract. Synchronous completion returns a transaction hash; asynchronous processing returns a status URL to poll.
  </Step>
</Steps>

## Reveal through the API or CLI [#reveal-through-the-api-or-cli]

The API input contains the settlement address, the secret, and optional email recipients. Session-based wallet-signing flows also include wallet verification. A synchronous response includes the reveal transaction hash and, when email sending is attempted, one result per recipient. An asynchronous request returns a transaction ID, status, and status URL for polling.

```json
{
  "settlementAddress": "0x8a4f0f2f3c9e7b7a7b2a1c7c1d5e3f4a5b6c7d8e",
  "secret": "northwind-redemption-secret-2026",
  "emailRecipients": ["operations@example.com"],
  "settlementName": "Northwind EUR treasury swap",
  "walletVerification": {
    "secretVerificationCode": "123456",
    "verificationType": "PINCODE"
  }
}
```

You can also reveal from the CLI when you already know the settlement address and secret:

```bash
dalp xvp-settlements reveal-secret \
  --address 0x8a4f0f2f3c9e7b7a7b2a1c7c1d5e3f4a5b6c7d8e \
  --secret northwind-redemption-secret-2026
```

## What DALP does [#what-dalp-does]

| Step                  | Platform behaviour                                                                                   |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| Validate input        | Checks the settlement address, secret format, optional recipient addresses, and wallet verification. |
| Check settlement type | Rejects local-only settlements because they have no external HTLC flow to reveal.                    |
| Encode transaction    | Encodes `revealSecret(secret)` for the settlement contract.                                          |
| Queue execution       | Sends the contract call through the transaction queue for the selected wallet.                       |
| Notify recipients     | Sends reveal emails only when recipients are supplied and email is configured.                       |

## Operational notes [#operational-notes]

* The reveal is useful only for cross-chain HTLC settlement flows. If the settlement has no external flow, DALP rejects the request because no hashlock reveal is required.
* Email notification failure does not change the on-chain reveal result. Treat the transaction hash as the execution evidence and resend the secret through your agreed counterparty channel if a recipient notification fails.
* Give the other chain enough time to observe the secret and complete before its timelock expires. The exact buffer depends on the external chain, wallet approval process, and operational monitoring.
* If the cutoff date has passed, use the expired-settlement withdrawal flow instead of revealing the secret.

## Troubleshooting [#troubleshooting]

| Issue                 | What to check                                                                                          |
| --------------------- | ------------------------------------------------------------------------------------------------------ |
| Invalid secret        | Confirm that the entered value is the original preimage for the settlement hashlock.                   |
| Reveal not required   | Confirm that the settlement has an external HTLC flow. Local-only settlements do not use this control. |
| Settlement not ready  | Confirm that required approvals are complete and the settlement has not expired.                       |
| Email recipient error | Use a valid email address and keep the recipient list to 10 addresses or fewer.                        |
| Transaction rejected  | Check wallet verification, signer availability, gas, and the current settlement state.                 |

## Related tasks [#related-tasks]

* [Withdraw expired](/docs/operators/system-addons/xvp-settlement/actions/withdraw-expired): recover assets after an HTLC settlement expires.
* [Create an XvP settlement](/docs/operators/system-addons/xvp-settlement/actions/create): start the settlement before approval, reveal, execution, or recovery.
* [HTLC settlement overview](/docs/operators/system-addons/xvp-settlement/htlc/overview): review the external-flow lifecycle before coordinating counterparties.
* [HTLC walkthrough](/docs/operators/system-addons/xvp-settlement/htlc/walkthrough): follow the full hashlock flow in order.
* [HTLC explained](/docs/operators/system-addons/xvp-settlement/htlc/htlc-explained): understand how the hashlock and secret mechanism works.