Verify external flows
Verify the external-flow details in an HTLC settlement before sender approvals, secret reveal, and expiry recovery.
External flows are references to the matching leg of an HTLC settlement on another EVM chain. The settlement record stores the external asset address, sender, recipient, amount, and chain ID so operators can compare both sides of the exchange before approval or secret reveal.
Use this how-to when you are reviewing an existing cross-chain HTLC settlement. It also helps when counterparties ask you to confirm the external leg before local senders approve. It does not replace the external chain's own settlement checks. Each chain still needs its own settlement, approvals, cutoff timing, and secret-reveal path.
What to verify
| Check | Why it matters |
|---|---|
| Local flow | Confirms what the current settlement can execute on this chain |
| External flow | Confirms the matching asset movement expected on the other EVM chain |
| Hashlock | Links both settlements to the same secret without exposing the secret before reveal |
| Cutoff dates | Gives the party who learns the revealed secret enough time to reuse it on the other chain |
| Approval state | Shows whether every local sender has locked the assets needed for this chain's settlement |
| Secret reveal | Shows whether the secret is public and can still be used before the matching settlement expires |
Before you start
You need:
- The settlement detail page or settlement read response for the local chain
- The matching settlement details from the other EVM chain
- The expected asset addresses, sender wallets, recipient wallets, amounts, and chain IDs for both legs
- The shared hashlock used by the matching settlements
- The cutoff date for each settlement
External flows are not local execution
An external flow does not transfer assets from the local settlement contract. It is the record you use to verify the matching leg on another chain. Approve only after you have checked the external chain's own settlement details.
Verify an external-flow settlement
Confirm there is at least one local flow
Open the settlement detail and check the flow list. A valid XvP settlement includes at least one local flow. Local flows are the transfers this settlement can execute on the current chain.
If every flow points to another chain, stop and ask for the correct settlement record. The local settlement cannot execute a purely external record.
Match the external-flow fields
For each external flow, compare the values against the settlement or evidence from the other EVM chain.
| Field | Match against |
|---|---|
| Asset address | Token contract address expected for the external leg |
| Sender | Wallet expected to send the external asset |
| Recipient | Wallet expected to receive the external asset |
| Amount | Base-unit amount recorded for the external leg |
| Chain ID | The EVM chain where the external leg is expected |
Do not approve based only on a token symbol or a human-readable asset name. Use the address, amount, and chain ID because symbols can collide across chains.
Check the shared hashlock
Compare the hashlock on both settlements. The value should be the same 32-byte hash.
If one party generated the raw secret in the settlement workflow, the local record stores whether it has an encrypted secret available. The raw secret should stay private until the intended reveal step. If a counterparty supplied a precomputed hashlock, verify that the same hashlock appears on every matching settlement before approvals proceed.
Check cutoff timing
Compare the cutoff date on each settlement. The settlement where the secret is revealed first should leave enough time for the counterparty to find the revealed secret and use it on the matching chain.
If the external chain is congested or operationally slower, use a wider gap between cutoffs. Do not reveal a secret close to the matching settlement's cutoff unless the counterparty can still submit and confirm the reveal in time.
Confirm approval state before reveal
Check that every local sender has approved before treating the settlement as armed. External-flow references do not create local approvals. Only local senders lock assets into this settlement.
When all local senders have approved, the settlement waits for the secret reveal. If the settlement is not fully approved, coordinate approvals before asking anyone to reveal the secret.
Verify the secret reveal before execution or recovery
After a secret is revealed on one chain, compare it against the shared hashlock and use it on the matching settlement before that settlement expires.
If the cutoff date passes before reveal, use the expiry recovery path for the affected settlement. If the parties decide to stop before secret reveal, use the cancellation path that matches the settlement state. After secret reveal, continue to execution or expiry recovery instead of cancellation.
Troubleshoot delayed settlement visibility
After a transaction confirms on an EVM chain, the settlement detail page or read response can lag while indexed state catches up. Check the transaction hash and block confirmation on the affected chain first, then refresh the settlement detail or read response before changing approvals, revealing the secret, or starting recovery.
If one chain shows the expected transaction and the other settlement still shows the old state, keep the flow in the current operational state until both settlement records agree. Do not use stale indexed state as proof that the matching transfer, approval, or secret reveal failed.
Verification summary
Before approving or revealing, you should be able to answer yes to each question:
- Does this settlement contain at least one local flow that can execute on the current chain?
- Does each external flow match the other chain's asset address, sender, recipient, amount, and chain ID?
- Do the matching settlements use the same hashlock?
- Are cutoff dates staggered enough for the revealed secret to be reused safely?
- Have all local senders approved before anyone reveals the secret?
- Have both settlement records caught up after any confirmed transaction?
- Is there a clear cancellation or expiry recovery path if the exchange stops?
Related
Walkthrough
Follow a complete multi-party cross-chain settlement where a Builder sells tokenized real estate to two Buyers, with a Notary receiving fees across Ethereum and Polygon.
Cancel or recover a settlement
Choose the correct XvP cancellation or expiry recovery path for local and HTLC settlement modes.