Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.train.tech/llms.txt

Use this file to discover all available pages before exploring further.

The Wallet HTLC approach is TRAIN’s solution for practical atomic swaps with recoverable secret generation. Instead of requiring users to manually manage secrets or complete multiple transactions per swap, secrets are derived from the user’s wallet signature. This enables N+1 interactions for N swaps — after an initial sign-in, users can perform unlimited swaps without additional signing steps.

​
The Challenge

Traditional HTLC implementations face a key tradeoff: User-generated secrets. Private key/secret management burden on users; if the browser clears cache or the user loses access, the transaction cannot be recovered Wallet HTLC solves this by making secret derivation reproducible and recoverable from on-chain data, while delegating the management entirely to the dApp.

​
Sign In

1

User Sign

The users signs the message I am using Train.
2

Cache Key

The dapp calls a HKDF to derive an initial key from the signature, and keeps the key in the cache.

​
Wallet HTLC Flow

1

Derive Secret

The dApp derives a secret from the user’s cached initial key, source chain, destination chain, and the timelock of the swap using HKDF.
2

User Locks Funds

User locks funds on the source chain using the hash of the derived secret as the hashlock.
3

Solver Locks Funds

Solver observes the source lock and creates a matching HTLC on the destination chain with the same hashlock.
4

User Transmits Signed Secret

The dApp signs a message containing the actual derived secret and transmits this signed secret to the Solver (or broadcasts it to any available actor).
5

Solver Releases Funds

The Solver reveals the secret on the destination chain to unlock the user’s funds (earning a designated reward for this action) and on the source chain to claim their primary fee. The Solver is economically incentivized to execute the destination redemption promptly—if they delay, any other actor can step in and claim the reward instead. Both user and Solver complete the swap.
This way we keep all the advantages of HTLC, but delegate the secret management to the dapp. As long as the user does not clear the cache the dapp can crete newer and newer secrets. And if the cache is cleared than the user can sign the message again and get the initial key, after that the secret can be recovered as the other parameters used to derive the key are publicly stored in the blockchain.

​
Passkey-Based Implementation

For enhanced security and UX, the secret generation can also be derived from passkeys (WebAuthn credentials) instead of wallet signatures. This allows for fully passwordless authentication while maintaining the same recoverable secret generation properties. Implementation details: See the auth package in the TRAIN app repository for the passkey-based implementation using HKDF key derivation.