TwinLock

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 side

This 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 contracts

Lock tokens on both chains

Claim tokens using the shared secret

Refund if no claim is made in time

Clear logging and events for each action

How 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 Tron

No bridge, no oracle, no validator — only smart contracts and hashlocks

Automatic refunds after timelock expiry

All swap data visible on-chain (transparent)

Testnet-safe — deployable and runnable on Sepolia and Nile

Educational and extensible — ideal for devs learning about HTLCs

Use Cases: Developers learning cross-chain swap mechanics

Research prototypes for decentralized exchange infrastructure

Safe peer-to-peer trading of assets on different chains

Foundation for future cross-chain dApps or multi-chain protocols

Status: 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

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 secrets

Architecture 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.js

claimEth.js, claimTron.js

refundEth.js, refundTron.js

All 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 faucets

Represent two very different blockchain architectures (EVM vs TVM)

Allow developers to simulate real-world, multi-chain dApp scenarios

The 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.