TwinLock

Problem Statement

TwinLock: Cross-Chain Atomic Swap Protocol TwinLock is a smart contract-based atomic swap system that enables secure, trustless exchange of tokens between two incompatible blockchain networks: Ethereum (Sepolia) and Tron (Nile). The protocol is built using Hashed Timelock Contracts (HTLCs), which enforce cryptographic guarantees to ensure both users receive what they expect—or both walk away with their original assets.Why This Project? Most cross-chain token transfers today rely on centralized bridges, oracles, or liquidity networks, which introduce risks such as hacks, slashing, and counterparty trust. TwinLock removes all intermediaries and replaces them with a purely cryptographic protocol.It demonstrates a fully trustless way for two people to swap tokens across incompatible chains by agreeing on:A shared secret hash (hashlock)A timeout period (timelock)The amount to swap on each sideThis is especially relevant as the multi-chain ecosystem grows, and there's a need for safer alternatives to risky bridges.What Does TwinLock Include? Two fully deployed HTLC smart contracts:One on Ethereum Sepolia (Solidity)One on Tron Nile (Tron Solidity / TVM)Swap logic for:lock (initiate swap)claim (redeem with secret)autoRefund (reclaim funds after timeout)CLI scripts using Node.js to:Deploy contractsLock tokens on both chainsClaim tokens using the shared secretRefund if no claim is made in timeClear logging and events for each actionHow a Swap Happens: Initiator (e.g., Alice) generates a random secret and locks tokens on Ethereum using the hash of that secret.Counterparty (e.g., Bob) uses the same hash to lock tokens on Tron.Alice claims Bob's tokens on Tron, revealing the secret.Bob uses that revealed secret to claim Alice’s tokens on Ethereum.This atomic flow ensures that either both sides complete or nothing happens at all.Key Features: Bi-directional atomic swap between Ethereum and TronNo bridge, no oracle, no validator — only smart contracts and hashlocksAutomatic refunds after timelock expiryAll swap data visible on-chain (transparent)Testnet-safe — deployable and runnable on Sepolia and NileEducational and extensible — ideal for devs learning about HTLCsUse Cases: Developers learning cross-chain swap mechanicsResearch prototypes for decentralized exchange infrastructureSafe peer-to-peer trading of assets on different chainsFoundation for future cross-chain dApps or multi-chain protocolsStatus: TwinLock is a working proof-of-concept. All smart contracts are deployed, and CLI tools are functional. The design is simple and lightweight, with emphasis on security and extensibility for future upgrades.This is not meant for production usage or mainnet deployment. It is an educational and research-focused implementation for testnets only

Solution

How It's Made TwinLock was built as a proof-of-concept implementation of a cross-chain atomic swap protocol between Ethereum (Sepolia testnet) and Tron (Nile testnet) using Hashed Timelock Contracts (HTLCs). The main challenge was ensuring synchronization and compatibility between EVM and TVM environments, which are very different under the hood.Core Technologies Used Component Tech Stack Ethereum Contract Solidity, OpenZeppelin Tron Contract Solidity (TVM-compatible), TronWeb Scripting/CLI Node.js, TronWeb, Ethers.js Testing + Deployment Sepolia testnet (Ethereum), Nile testnet (Tron) Version Control Git + GitHub Interaction Scripts Pure JavaScript with .env secretsArchitecture Breakdown HTLC Contracts (Ethereum & Tron):Deployed custom HTLC contracts to Sepolia and Nile networks.Each contract has lock(), claim(), and autoRefund() functions.They use the same logic: only allow the other party to claim funds by revealing the correct preimage of a hash.Shared Swap Parameters:We generate a random secret using Node.js.Then we use keccak256(secret) as the hashlock on both chains.The same hashlock and timelock are used on both contracts for consistency.Cross-Chain Claiming:Once one party claims tokens (e.g., on Tron), the revealed secret is publicly visible on-chain.The counterparty can then pick it up from logs or transaction details and use it to claim on the other chain.No oracle, no off-chain coordinator is needed.CLI Automation Scripts:Written in Node.js with ethers.js for Ethereum and TronWeb for Tron.Scripts include:lockEth.js, lockTron.jsclaimEth.js, claimTron.jsrefundEth.js, refundTron.jsAll of them read parameters from .env and config files, so they're easy to customize.Notable Challenges / Hacky Parts TVM vs EVM Compatibility: Tron uses a forked version of Solidity and has a slightly different runtime, especially around msg.sender and contract addresses. Had to adjust contract logic to work on both chains without breaking the atomicity guarantee.ABI Handling: Since Tron doesn’t offer ABI access as easily as Etherscan does, we manually kept ABI files and wrote wrapper scripts to simulate Etherscan-like interactions for Tron.Lack of Bridges: This project intentionally does not use any cross-chain bridges, relayers, or 3rd-party services. It relies entirely on cryptographic guarantees (hashlocks + timelocks) and uses public mempool / on-chain state to coordinate between two parties.Auto-Refund Logic: Handling expired swaps gracefully was a challenge, as both chains needed to have similar refund mechanisms that automatically give funds back after a timeout—without letting users double-claim.Why This Stack? We chose Ethereum Sepolia and Tron Nile because they:Have free testnet faucetsRepresent two very different blockchain architectures (EVM vs TVM)Allow developers to simulate real-world, multi-chain dApp scenariosThe decision to use TronWeb and Ethers.js instead of frameworks like Hardhat or Foundry was intentional, so the CLI scripts could run independently, without needing a local dev blockchain.