{"id":47483078,"url":"https://github.com/diorwave/ChainBridge-Swap","last_synced_at":"2026-04-09T15:01:07.121Z","repository":{"id":338663661,"uuid":"1157421732","full_name":"diorwave/ChainBridge-Swap","owner":"diorwave","description":"A web-based atomic swap platform enabling trustless cross-chain trading between Bitcoin and Liquid Network tokens using HTLC contracts. Provides wallet integration, swap offers, real-time status tracking, and a backend API for managing secure decentralized exchanges.","archived":false,"fork":false,"pushed_at":"2026-02-15T19:22:04.000Z","size":79,"stargazers_count":2,"open_issues_count":14,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-16T00:44:41.263Z","etag":null,"topics":["atomic-swap","bitcoin","blockchain","corss-chain","cryptocurrency","defi","fastapi","htlc","liquid-network","react"],"latest_commit_sha":null,"homepage":"https://github.com/diorwave/ChainBridge-Swap","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/diorwave.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T19:55:10.000Z","updated_at":"2026-02-15T21:02:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/diorwave/ChainBridge-Swap","commit_stats":null,"previous_names":["diorwave/chainbridge-swap"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/diorwave/ChainBridge-Swap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diorwave%2FChainBridge-Swap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diorwave%2FChainBridge-Swap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diorwave%2FChainBridge-Swap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diorwave%2FChainBridge-Swap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/diorwave","download_url":"https://codeload.github.com/diorwave/ChainBridge-Swap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diorwave%2FChainBridge-Swap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31559925,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atomic-swap","bitcoin","blockchain","corss-chain","cryptocurrency","defi","fastapi","htlc","liquid-network","react"],"created_at":"2026-03-26T03:00:48.759Z","updated_at":"2026-04-09T15:01:07.116Z","avatar_url":"https://github.com/diorwave.png","language":"TypeScript","funding_links":[],"categories":["Development Tools"],"sub_categories":[],"readme":"# Depix ↔ Bitcoin Atomic Swap PoC\n\nProof-of-concept for trustless atomic swaps between Depix tokens (Liquid Network) and Bitcoin using Hash Time-Locked Contracts (HTLC).\n\n## Features\n\n- Trustless cross-chain swaps between Bitcoin testnet and Liquid Network\n- HTLC-based atomic swap protocol (both succeed or both fail)\n- Web interface for creating and managing swap offers\n- Support for Electrum (Bitcoin) and Elements (Liquid) wallets\n- Real-time swap status tracking\n\n## Project Structure\n\n```\n├── backend/\n│   ├── wallets/          # Wallet integration (elementsd, Electrum)\n│   │   ├── bitcoin.py    # Bitcoin wallet via Electrum\n│   │   └── depix.py      # Depix wallet via Elements RPC\n│   ├── htlc/             # HTLC logic and swap engine\n│   ├── api/              # FastAPI REST endpoints\n│   └── db/               # SQLite for swap state\n├── frontend/             # React + TypeScript web interface\n└── tests/                # Test scenarios\n```\n\n## Prerequisites\n\n- Python 3.9+\n- Node.js 18+ and npm\n- **elementsd** (Liquid Network daemon) - [Install Guide](https://github.com/ElementsProject/elements)\n- **Electrum** (Bitcoin wallet) - [Download](https://electrum.org/)\n\n## Installation\n\n### 1. Clone and Install Dependencies\n\n```bash\n# Install Python dependencies\npip install -r requirements.txt\n\n# Install frontend dependencies\ncd frontend\nnpm install\ncd ..\n```\n\n### 2. Setup Wallets\n\n#### Bitcoin Wallet (Electrum)\n\n```bash\n# Create testnet wallet\nelectrum --testnet create\n\n# Get testnet coins from faucet\n# Use: https://testnet-faucet.mempool.co/\nelectrum --testnet getunusedaddress\n```\n\n#### Depix Wallet (Elements/Liquid)\n\n```bash\n# Start elementsd (Liquid testnet)\nelementsd -chain=liquidtestnet -daemon\n\n# Create wallet\nelements-cli -chain=liquidtestnet createwallet \"new wallet\"\n\n# Load wallet\nelements-cli -chain=liquidtestnet loadwallet \"wallet name\"\n\n# Get new address for receiving Depix tokens\nelements-cli -chain=liquidtestnet getnewaddress\n```\n\n### 3. Configuration\n\nCopy `.env.example` to `.env` and configure:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` with your settings:\n\n```env\n# Elementd (Liquid Network) Configuration\nELEMENTD_RPC_USER=depixrpc\nELEMENTD_RPC_PASSWORD=your_password_here\nELEMENTD_RPC_HOST=127.0.0.1\nELEMENTD_RPC_PORT=7041\nELEMENTD_WALLET=depixswap\n\n# Depix Asset ID (custom asset on Liquid)\nDEPIX_ASSET_ID=02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189\n\n# Electrum Configuration\nELECTRUM_WALLET_PATH=wallet path\nELECTRUM_TESTNET=true\n\n# API Configuration\nAPI_HOST=0.0.0.0\nAPI_PORT=8000\nAPI_SECRET_KEY=change-this-in-production\n\n# HTLC Configuration\nHTLC_TIMELOCK_HOURS=24\n```\n\nAlso configure frontend:\n\n```bash\ncd frontend\ncp .env.example .env\n# Edit frontend/.env if needed (default: http://localhost:8000)\n```\n\n## Running\n\n### Start Backend\n\n```bash\n# Make sure elementsd is running\nelementsd -chain=liquidtestnet -daemon\n\n# Load wallet\nelements-cli -chain=liquidtestnet loadwallet \"wallet name\"\n\n# Start FastAPI backend\ncd backend\npython main.py\n```\n\nBackend will run on `http://localhost:8000`\n\n### Start Frontend\n\n```bash\ncd frontend\nnpm run dev\n```\n\nFrontend will run on `http://localhost:3000`\n\n## Usage\n\n### Creating a Swap Offer\n\n1. Open the web interface at `http://localhost:3000`\n2. Check your wallet balances\n3. Click \"Create Offer\"\n4. Specify:\n   - What you're offering (BTC or Depix)\n   - Amount\n   - What you want in return\n5. Submit the offer\n\n### Accepting a Swap\n\n1. Browse available offers\n2. Click \"Accept\" on an offer\n3. The HTLC contracts are created on both chains\n4. Complete the swap by revealing the secret\n\n### Swap States\n\n- `pending` - Offer created, waiting for counterparty\n- `accepted` - Both parties agreed, HTLCs being created\n- `locked` - Funds locked in HTLCs on both chains\n- `completed` - Swap successful, funds exchanged\n- `refunded` - Timelock expired, funds returned\n\n## Wallet Management\n\n### Electrum Commands\n\n```bash\n# Check balance\nelectrum --testnet getbalance\n\n# Get receiving address\nelectrum --testnet getunusedaddress\n\n# List addresses\nelectrum --testnet listaddresses\n```\n\n### Elements Commands\n\n```bash\n# Check balance\nelements-cli -chain=liquidtestnet getbalance\n\n# Get new address\nelements-cli -chain=liquidtestnet getnewaddress\n\n# Check Depix asset balance\nelements-cli -chain=liquidtestnet getbalance \"*\" 1 false \"02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189\"\n```\n\n## API Endpoints\n\n### Health \u0026 Balance\n\n#### `GET /health`\nHealth check endpoint.\n\n**Response:**\n```json\n{\n  \"status\": \"healthy\",\n  \"timestamp\": 1234567890\n}\n```\n\n#### `GET /balances`\nGet current wallet balances for both Bitcoin and Depix.\n\n**Response:**\n```json\n{\n  \"btc_balance\": 0.00195291,\n  \"depix_balance\": 100.0\n}\n```\n\n---\n\n### Atomic Swap Endpoints (Recommended)\n\nThese endpoints implement the full atomic swap protocol with proper HTLC sequencing.\n\n#### `POST /atomic/offers`\n**Step 1:** Create a new swap offer (Initiator/Alice).\n\n**Request:**\n```json\n{\n  \"initiator_asset\": \"btc\",\n  \"initiator_amount\": 0.001,\n  \"acceptor_asset\": \"depix\",\n  \"acceptor_amount\": 50.0,\n  \"initiator_address\": \"tb1q...\"\n}\n```\n\n**Response:**\n```json\n{\n  \"swap_id\": \"uuid\",\n  \"status\": \"offered\",\n  \"initiator_asset\": \"btc\",\n  \"initiator_amount\": 0.001,\n  \"acceptor_asset\": \"depix\",\n  \"acceptor_amount\": 50.0,\n  \"initiator_address\": \"tb1q...\",\n  \"hashlock\": \"hash...\",\n  \"initiator_timelock\": 1234567890,\n  \"acceptor_timelock\": 1234567890,\n  \"created_at\": 1234567890\n}\n```\n\n#### `GET /atomic/offers`\nList all swap offers. Optional query parameter: `?status=offered`\n\n**Response:**\n```json\n[\n  {\n    \"swap_id\": \"uuid\",\n    \"status\": \"offered\",\n    \"initiator_asset\": \"btc\",\n    \"initiator_amount\": 0.001,\n    ...\n  }\n]\n```\n\n#### `GET /atomic/offers/open`\nList only open offers that can be accepted (status = \"offered\").\n\n#### `GET /atomic/offers/{swap_id}`\nGet details of a specific swap offer.\n\n#### `POST /atomic/offers/{swap_id}/accept`\n**Step 2:** Accept a swap offer (Acceptor/Bob).\n\n**Request:**\n```json\n{\n  \"acceptor_address\": \"VTpz...\"\n}\n```\n\n**Response:**\n```json\n{\n  \"swap_id\": \"uuid\",\n  \"status\": \"accepted\",\n  \"acceptor_address\": \"VTpz...\",\n  \"accepted_at\": 1234567890,\n  ...\n}\n```\n\n#### `POST /atomic/offers/{swap_id}/lock-initiator`\n**Step 3:** Initiator (Alice) locks their funds in HTLC.\n\nCreates HTLC transaction on the initiator's blockchain (BTC or Depix).\n\n**Response:**\n```json\n{\n  \"swap_id\": \"uuid\",\n  \"status\": \"initiator_locked\",\n  \"initiator_txid\": \"abc123...\",\n  ...\n}\n```\n\n#### `POST /atomic/offers/{swap_id}/lock-acceptor`\n**Step 4:** Acceptor (Bob) locks their funds in HTLC.\n\nCreates HTLC transaction on the acceptor's blockchain. Can only be called after initiator has locked.\n\n**Response:**\n```json\n{\n  \"swap_id\": \"uuid\",\n  \"status\": \"acceptor_locked\",\n  \"acceptor_txid\": \"def456...\",\n  ...\n}\n```\n\n#### `POST /atomic/offers/{swap_id}/claim-initiator`\n**Step 5:** Initiator (Alice) claims acceptor's funds using the secret.\n\nThis reveals the secret on the blockchain, allowing Bob to claim Alice's funds.\n\n**Response:**\n```json\n{\n  \"status\": \"claimed\",\n  \"message\": \"Initiator claimed funds. Secret is now public!\",\n  \"secret\": \"abc123...\",\n  \"swap_id\": \"uuid\"\n}\n```\n\n#### `POST /atomic/offers/{swap_id}/claim-acceptor`\n**Step 6:** Acceptor (Bob) claims initiator's funds using the revealed secret.\n\nCompletes the atomic swap.\n\n**Response:**\n```json\n{\n  \"status\": \"completed\",\n  \"message\": \"Swap completed successfully!\",\n  \"swap_id\": \"uuid\"\n}\n```\n\n---\n\n### Legacy Swap Endpoints\n\nThese endpoints provide a simplified swap interface (for backward compatibility).\n\n#### `POST /swaps`\nCreate a new atomic swap (simplified version).\n\n**Request:**\n```json\n{\n  \"depix_amount\": 50.0,\n  \"btc_amount\": 0.001,\n  \"btc_recipient\": \"tb1q...\",\n  \"depix_recipient\": \"VTpz...\"\n}\n```\n\n**Response:**\n```json\n{\n  \"swap_id\": \"uuid\",\n  \"depix_amount\": 50.0,\n  \"btc_amount\": 0.001,\n  \"hashlock\": \"hash...\",\n  \"timelock\": 1234567890,\n  \"status\": \"locked\",\n  \"depix_txid\": \"abc123...\",\n  \"btc_txid\": \"def456...\",\n  \"created_at\": 1234567890\n}\n```\n\n#### `GET /swaps`\nList all swaps.\n\n#### `GET /swaps/{swap_id}`\nGet specific swap details.\n\n#### `POST /swaps/{swap_id}/redeem`\nRedeem swap with secret.\n\n**Request:**\n```json\n{\n  \"swap_id\": \"uuid\",\n  \"secret\": \"abc123...\"\n}\n```\n\n#### `POST /swaps/{swap_id}/refund`\nRefund swap after timelock expires.\n\n---\n\n### Swap Status Flow\n\n```\noffered → accepted → initiator_locked → acceptor_locked → \ninitiator_claimed → completed\n\nOR\n\noffered → cancelled\nlocked → refunded (if timelock expires)\n```\n\n### Status Descriptions\n\n- `offered` - Swap offer created, waiting for acceptor\n- `accepted` - Acceptor agreed to swap terms\n- `initiator_locked` - Initiator's funds locked in HTLC\n- `acceptor_locked` - Acceptor's funds locked in HTLC\n- `initiator_claimed` - Initiator claimed funds (secret revealed)\n- `completed` - Both parties claimed funds, swap successful\n- `refunded` - Timelock expired, funds returned\n- `cancelled` - Swap cancelled before completion\n\n## Troubleshooting\n\n### Electrum wallet not showing balance\n\n```bash\n# Check if wallet is synced\nelectrum --testnet getinfo\n\n# Restart daemon\nelectrum --testnet daemon stop\nelectrum --testnet daemon start\n```\n\n### Elements wallet not loaded\n\n```bash\n# List available wallets\nelements-cli -chain=liquidtestnet listwalletdir\n\n# Load wallet\nelements-cli -chain=liquidtestnet loadwallet \"depixswap\"\n```\n\n### Disk space issues\n\nIf running full nodes, blockchain data can be large:\n- Bitcoin testnet: ~30GB\n- Liquid testnet: ~10GB\n\nConsider using pruned mode or SPV wallets like Electrum.\n\n## Security Notes\n\n- This is a PoC for testing only\n- Use testnet coins only\n- Change default passwords in production\n- Verify HTLC scripts before deploying to mainnet\n- Ensure proper timelock values for mainnet\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiorwave%2FChainBridge-Swap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdiorwave%2FChainBridge-Swap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiorwave%2FChainBridge-Swap/lists"}