AtomX is an open-source reference implementation of a trustless, peer-to-peer Bitcoin ↔ Litecoin atomic swap using Hash Time-Locked Contracts (HTLCs) on native Segwit (P2WSH) outputs. It ships three pieces:
| Piece | Role |
|---|---|
@atomx/core |
HTLC script construction (bitcoinjs-lib), witness stacks, PSBT finalization helpers, dual-chain and single-chain in-memory “regtest” simulators, and cross-chain parameter planning (BTC vs LTC CLTV ordering). |
atomx-cli |
simulate — full BTC + LTC simulated atomic swap (four transactions: two locks, then LTC redeem revealing preimage, then BTC redeem). walk — step-by-step narrative for initiators and followers (interactive on a TTY). relay — WebSocket hub for the GUI or manual JSON coordination. |
@atomx/gui |
Static Vite app that connects to the relay—two parties share a session ID and exchange HTLC metadata (addresses, optional lock txid, notes). No private keys in the browser. |
There is no custodial bridge and no wrapped asset: funds move only when valid HTLC witnesses hit chain within the agreed timelocks.
| Goal | Where it lives |
|---|---|
HTLC core (bitcoinjs-lib; Litecoin-compatible scripts — specs sometimes cite “litecoinjs-lib”) |
packages/core — see Tech stack |
| CLI: step-by-step initiate / participate / redeem | npm run walk → packages/cli/src/walk.ts; npm run simulate for full scripted demo |
| Web GUI + WebSocket coordination | npm run relay + npm run gui:dev → packages/gui, relay in packages/cli/src/relay.ts |
| Simulated Bitcoin + Litecoin “regtest” (safe local experiment) | demoDualChainAtomicSwap + tests in packages/core (in-memory ledgers, not bitcoind) |
Workspace path (this environment): /root/Projects/project-structures/AtomX
Cross-chain interoperability is expanding beyond custodial bridges: ecosystem activity around trust-minimized swaps (including Bitcoin paired with other major L1s—often discussed alongside Cardano-class experiments—and ongoing HTLC / adaptor-signature research) reflects demand to move liquidity without centralized exchanges or wrapped synthetic tokens. AtomX stays intentionally narrow—BTC ↔ LTC—because Litecoin shares Bitcoin’s UTXO script model, making it the standard teaching and integration-test analogue next to Bitcoin itself.
Educational specs sometimes cite litecoinjs-lib alongside bitcoinjs-lib. There is no widely maintained npm package named litecoinjs-lib. Litecoin HTLCs use the same Script VM as Bitcoin for this pattern; AtomX implements Litecoin outputs by combining bitcoinjs-lib with an explicit litecoinRegtest Network (version bytes / bech32 prefix). Older standalone packages such as litecoinjs exist on npm but are unmaintained—this repo does not depend on them.
The locking redeem script follows the standard branch layout:
- IF path:
SHA256(preimage) == hashand redeemer signature (counterparty reveals secret). - ELSE path:
CHECKLOCKTIMEVERIFYat refund height/time and funder signature.
Witness ordering for P2WSH is handled in core (witnessStackForRedeem / witnessStackForRefund) and wired through PSBT finalization (finalizeHtlcRedeemInput).
For Alice swapping BTC for Bob’s LTC (Alice locks BTC first in the canonical story), Litecoin’s refund CLTV must unlock strictly before Bitcoin’s refund CLTV. Otherwise Bob could stall until Alice’s patience expires on one chain while extracting value on the other. planBtcLtcSwap enforces ltcRefund < btcRefund.
The simulator does not connect to bitcoind/litecoind. It maintains separate in-memory ledgers (ChainSimulator), mints synthetic UTXOs, builds real bitcoinjs-lib transactions and witnesses, and runs a full dual-chain story: BTC lock → LTC lock → LTC redeem (preimage revealed) → BTC redeem. An additional single-chain smoke test exercises one isolated Bitcoin ledger. Connecting to real regtest daemons is left as an operational extension.
- Node.js ≥ 20
cd AtomX
npm install
npm run buildnpm run simulate
# or
node packages/cli/dist/index.js simulatePrints four main-net-style tx ids (BTC lock, LTC lock, LTC redeem, BTC redeem), secret hash, HTLC addresses, CLTV heights, plus an extra single-chain HTLC demo on a fresh simulator.
Explains the swap phases (lock ordering, preimage handling, claim order). On a TTY, prompts once then runs the same dual-chain simulation and prints tx ids. In CI/non-interactive environments, prints the script and exits without hanging.
npm run walknpm run relay
# default bind: ws://127.0.0.1:8765Environment overrides:
ATOMX_RELAY_HOST(default127.0.0.1)ATOMX_RELAY_PORT(default8765)
Custom port:
node packages/cli/dist/index.js relay --port 9000npm run gui:devOpen two tabs/windows, use the same session ID, choose complementary roles, connect both to the relay, then exchange HTLC metadata. Never paste private keys or mnemonics.
Production assets:
npm run gui:build
# static output: packages/gui/distServe packages/gui/dist with any static file server over HTTPS in production; use wss:// for the relay.
npm testBuilds core → cli → gui, then runs Node’s test runner (via tsx) for @atomx/core and @atomx/cli (including CLI subprocess smoke tests).
AtomX/
packages/
core/ # HTLC + simulators + redeem helpers
cli/ # atomx-cli binary
gui/ # Vite static client
- Reference/educational software—audit before any mainnet use.
- Simulator ≠ production: no fee markets, no mempool policy, no P2P relay—only script/transaction validity exercises on synthetic UTXOs.
- GUI relay is not authenticated: run locally or behind TLS + auth for real deployments.
- Keys: simulation keys are ephemeral; the GUI never handles mainnet wallets.
MIT (project-wide; verify individual dependencies at install time).
Telegram: @AuraTerminal