Liquidity.spot Tutorial

Meet Alice & Bob – Your Guides to Trustless HNS ↔ BTC Swaps

Alice and Bob Visual Guide

In the world of Handshake, Bob is the friendly, reliable wallet everyone knows — the one that helps you own your names and your coins without middlemen.

Now imagine Alice, a domain owner who wants to trade some of her HNS for BTC privately and securely. She posts her offer on Liquidity.spot.

Along comes Bob — another Handshake user who likes her price and accepts the trade. The platform assigns roles automatically:

  • Alice (the HNS seller) locks her HNS first with a long timelock — giving Bob time to safely lock BTC.
  • Bob then locks BTC with a shorter timelock.
  • Alice claims BTC by revealing her secret → Bob sees the secret on-chain and claims his HNS.

No one can cheat, no funds are ever held by the platform — just like Handshake itself: decentralized, self-sovereign, and powered by trust in math instead of trust in people.

Welcome to Liquidity.spot — where Alice and Bob trade freely in the spirit of Handshake.

Alternative Scenario: Bob Wants to Buy HNS

What if Bob initiates the trade? Let's say Bob has BTC and wants to buy HNS.

  • Bob creates a "Buy HNS" order on the order book.
  • Alice (who has HNS) accepts Bob's order.
  • Even though Bob created the order, Alice is still the HNS Seller.
  • The protocol remains the same: Alice locks HNS first.
  • Bob waits for Alice's lock, then locks his BTC.

Key Takeaway: The person selling HNS always locks first (Alice), regardless of who posted the order.

How it Works Today

Liquidity.spot is currently evolving into a non-custodial P2P coordination platform for Handshake (HNS) and Bitcoin (BTC) trades. The platform helps buyers and sellers find each other, understand their roles, and follow a shared process without taking custody of funds.

Important: We never hold your funds. You retain full custody of your coins throughout the entire process.

The trustless HTLC flow below remains available as an experimental testing feature and should not yet be treated as mainnet-ready.

Two Modes In The App

1. Human P2P Mode

This is the main product path now. Users post P2P offers, match with another user, and coordinate the trade in a shared room with milestones, TXIDs, notes, and dispute handling.

2. Atomic Swaps (Experimental)

This is the original HTLC-based flow. It is still available for testing and learning, but should be treated as experimental until safety, verification, and wallet tooling are stronger.

Step-by-Step Guide

1. Connect Wallet

Log in with your GFAVIP Wallet account. This creates your identity on the platform and syncs your Gems balance (used for staking).

2. Choose A Mode

  • P2P Mode: Go to the P2P page to post or accept a human-to-human offer and use the trade room.
  • Atomic Swaps: Go to the Atomic Swaps page to use the original HTLC testing flow.
Testing Only

3. Experimental Trustless Swap Process (HTLC)

Once matched, the platform automatically assigns you a role based on order sides:

  • Alice: ALWAYS the Seller of HNS (and Buyer of BTC). She locks HNS first.
  • Bob: ALWAYS the Buyer of HNS (and Seller of BTC). He locks BTC second.

Note: Even if you create the order ("Maker"), your role depends on what you are trading. If you create a "Buy HNS" order, you will be Bob.

  1. Initiation: The platform securely generates a random secret key and shows only its hash to both parties.
  2. Lock HNS: Alice locks HNS in her wallet using the hash and a long timelock (48h).
  3. Lock BTC: Bob verifies Alice's lock, then locks BTC in his wallet using the same hash and a shorter timelock (24h).
  4. Claim BTC: Alice uses the secret key to claim the locked BTC. This reveals the secret on the blockchain.
  5. Claim HNS: Bob sees the revealed secret and uses it to claim the locked HNS.

Tools You Need

  • Handshake Wallet: Bob Wallet (recommended) or CLI wallet supporting HTLCs.
  • Bitcoin Wallet: Electrum or Bitcoin Core (must support HTLC/scripting).
  • GFA Gems: Optional reputation stake to boost order visibility and trust. (Future versions will include escrow-like penalties for cancellations.)

How to Test (Testnet)

1. Get Testnet Coins

  • BTC Testnet: Use public Bitcoin Testnet faucets.
  • HNS Testnet: Public faucets are limited. For reliable testing, run a local hsd regtest/simnet node (lightweight mode possible) or coordinate with another tester.

2. Configure Wallets

  • Bob Wallet: Settings > Network → switch to Testnet/Simnet.
  • Electrum: Use --testnet flag or Testnet version.

3. Perform a Swap

Use the Secret Hash, Timelocks, and role instructions generated by the platform to create HTLC transactions manually in your wallets.

Note: Human P2P coordination is becoming the main product path. The trustless HTLC flow should be treated as testing-only for now and used only with testnet or very small experimental amounts.