Reveal an HTLC settlement secret for an external flow

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

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.

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.

Reveal from the settlement page

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.

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.

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.

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.

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.

{
  "settlementAddress": "0x8a4f0f2f3c9e7b7a7b2a1c7c1d5e3f4a5b6c7d8e",
  "secret": "northwind-redemption-secret-2026",
  "emailRecipients": ["[email protected]"],
  "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:

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

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

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

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.

Withdraw expired: recover assets after an HTLC settlement expires.
Create an XvP settlement: start the settlement before approval, reveal, execution, or recovery.
HTLC settlement overview: review the external-flow lifecycle before coordinating counterparties.
HTLC walkthrough: follow the full hashlock flow in order.
HTLC explained: understand how the hashlock and secret mechanism works.

Reveal secret