# Reveal secret

Source: https://docs.settlemint.com/docs/user-guides/system-addons/xvp-settlement/actions/reveal-secret
Learn how to reveal the HTLC secret to trigger execution of a cross-chain settlement.
Once revealed, the secret becomes public and can be used on all linked chains.




For HTLC (cross-chain) settlements, revealing the secret triggers execution of the settlement. The secret proves knowledge of the original value that was used to create the hashlock.

## When to reveal the secret [#when-to-reveal-the-secret]

Reveal the secret when:

* The settlement is in **Armed** state (all local senders have approved)
* You are ready to complete the exchange
* You want to claim the assets locked in this settlement

<Callout type="info" title="Who reveals the secret?">
  Typically, the party who generated the secret reveals it first on the chain where they receive assets. Once revealed,
  the secret is public and anyone can use it on other chains.
</Callout>

## Prerequisites [#prerequisites]

* The settlement is in Armed state
* You have the secret that matches the settlement's hashlock
* You're ready to complete the settlement (no going back after reveal)

## Steps [#steps]

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

    Navigate to **Settlements** and find the HTLC settlement in Armed state.

    Verify:

    * All local senders have approved
    * The settlement shows "Waiting for secret"
    * The cutoff date has not passed
  </Step>

  <Step>
    ### Reveal the secret [#reveal-the-secret]

    Click **Reveal Secret** on the settlement detail page.

    Enter the secret value (the original value before hashing).

    Optionally, enter email addresses to share the secret with. Once the secret is revealed on-chain, these recipients will receive it via email. This is typically used to notify your counterparty on the external chain so they can complete their side of the settlement.
  </Step>

  <Step>
    ### Confirm execution [#confirm-execution]

    Review the confirmation dialog showing:

    * The secret being revealed
    * The flows that will execute
    * The assets you'll receive

    Click **Confirm** and authenticate with your PIN or OTP.
  </Step>

  <Step>
    ### Verify execution [#verify-execution]

    After the transaction confirms:

    * The settlement enters **Executed** state
    * All local flows complete atomically
    * Recipients receive their assets
    * The secret is now visible on-chain
  </Step>
</Steps>

## What happens after reveal [#what-happens-after-reveal]

Once you reveal the secret:

1. **This chain:** The settlement executes immediately (if auto-execute is on)
2. **Other chains:** Anyone can see the secret on-chain and use it
3. **Secret becomes public:** There's no security risk since the settlement is complete

## Sharing the secret [#sharing-the-secret]

After revealing, you can share the secret with counterparties on other chains:

* **Option A:** They find it on-chain (in the transaction that revealed it)
* **Option B:** You send it via email or messaging (it's already public)

Sharing via email is convenient because counterparties don't need to monitor the blockchain.

## Timing considerations [#timing-considerations]

Reveal the secret with enough time buffer before timelocks expire:

| Action                | Recommendation                                   |
| --------------------- | ------------------------------------------------ |
| Reveal on first chain | At least 24 hours before second chain's timelock |
| Monitor confirmation  | Ensure transaction confirms before moving on     |

## Troubleshooting [#troubleshooting]

| Issue                  | Solution                                                                  |
| ---------------------- | ------------------------------------------------------------------------- |
| "Invalid secret" error | The secret doesn't match the hashlock - verify you have the correct value |
| "Settlement not armed" | All senders must approve before the secret can be revealed                |
| "Settlement expired"   | The cutoff date passed - withdraw your assets instead                     |
| Transaction reverts    | Check gas limits and network conditions                                   |

## Next steps [#next-steps]

<Cards>
  <Card title="Withdraw expired" href="/docs/user-guides/system-addons/xvp-settlement/actions/withdraw-expired">
    How to recover assets if the settlement expires.
  </Card>

  <Card title="HTLC explained" href="/docs/user-guides/system-addons/xvp-settlement/htlc/htlc-explained">
    Understand how the hashlock and secret mechanism works.
  </Card>
</Cards>

## Related [#related]

* [XvP settlement overview](/docs/user-guides/system-addons/xvp-settlement/overview)
* [HTLC walkthrough](/docs/user-guides/system-addons/xvp-settlement/htlc/walkthrough)