htlc-decoder

Decode COMIT / Liquality atomic-swap HTLC contracts straight from their EVM bytecode.

These ~200-byte hand-written hash-time-locked contracts powered Liquality's cross-chain swaps (BTC ↔ ETH / ERC-20). When Liquality wound down its wallet in 2024, many were left on-chain with funds still locked. This tool decodes any instance into its four hardcoded fields and, optionally, checks its live on-chain state. Read-only — no keys, no transactions.

What it extracts

Field	Meaning
secretHash	the sha256 image the claimer must reveal
expiration	unix timestamp; after it, refund is allowed
buyer	receives funds on claim (secret revealed)
seller	receives funds on refund (after the timeout)

It handles both gas-stipend sub-variants (the SHA-256 precompile gas is 0x48 or 0xffff).

How the HTLC works

The contract has two exits, both ending in SELFDESTRUCT:

• claim — call with the 32-byte secret; if sha256(secret) == secretHash, the balance goes to buyer.
• refund — call with empty calldata after expiration, the balance goes to seller.

The refund recipient is hardcoded in the bytecode and the refund is permissionless: anyone can trigger it, but the funds can only ever go to the original seller. (Decoding a contract is not the same as refunding it — that's a separate, deliberate action, and it only ever pays the hardcoded owner.)

Usage

# decode raw runtime bytecode
python htlc_decoder.py 0x6020806000803760218160008060026048f1...

# decode a deployed contract + show live state (balance, expired, refundable)
RPC_URL=https://ethereum-rpc.publicnode.com \
  python htlc_decoder.py 0x597f71dB673813AD3A88414b1c16CDB42815f27E

Example output:

{
  "secret_hash": "0x5b8266fdc091460ad7fbb81cacb58962b8690684750c0c1578e63eec8e508b79",
  "expiration": 1625584597,
  "buyer": "0xe0ab7c77f6ecc7d629a5ef2d7d23585c0da65988",
  "seller": "0x3a712cc47aeb0f20a7c9de157c05d74b11f172f5",
  "address": "0x597f71dB673813AD3A88414b1c16CDB42815f27E",
  "balance_eth": 0.0,
  "expired": true,
  "refundable": false,
  "expiration_utc": "2021-07-06T15:16:37+00:00"
}

Requirements

Python 3.8+. No third-party dependencies (standard library only).

Background

Built while reverse-engineering and recovering stuck Liquality/COMIT swaps and returning the funds to their original owners. Decoder only — the recovery logic is intentionally not included here.

License

MIT — see LICENSE.