🚀 BTCGather - Premium Bitcoin L1 Group Payments Platform

Trustless Group Payments & Escrow on Bitcoin L1 via OP_NET

Pool BTC with friends, teams, or DAOs for shared goals. Funds are locked in a Bitcoin L1 smart contract — only released when conditions are met. No custodian, no bridge, no EVM.

✨ Premium Features

• 🎨 Elite Design - Glass morphism UI with custom branding
• 📊 Real-time BTC Price - Live price widget with 24h changes
• 🎵 Background Music - Auto-play with premium audio
• 🏦 Trustless Escrow - Bitcoin L1 smart contract security
• 🗳️ Democratic Voting - Group fund release decisions
• 📱 Mobile Responsive - Works seamlessly on all devices

---

📸 Features

• Create Group Funds — Trip, Gift, Rent, DAO, Business, Emergency, Custom
• Invite Code System — Share a short code for anyone to join
• Progress Tracking — Real-time funding bar with participant count
• 3 Payout Rules:
  • ⚡ Auto — Funds release automatically when target reached
  • 🗳️ Vote — Majority threshold (configurable 51–100%)
  • 🔒 Unanimous — All participants must approve
• Deadline + Auto-Refund — If target not reached by deadline, full refund
• OP_NET Wallet — Connect your Bitcoin wallet for on-chain transactions
• Demo Mode — Works fully without deployed contracts (local simulation)

---

🏗️ Architecture

BTCGather/
├── src/                         ← React + Vite + Tailwind frontend
│   ├── main.jsx
│   ├── App.jsx                  ← Root: state, routing, demo simulation
│   ├── index.css                ← Dark BTC theme + custom components
│   ├── data/mockData.js         ← Mock groups, states, templates
│   ├── hooks/
│   │   ├── useOPNetWallet.js    ← Wallet connect/disconnect/refresh
│   │   └── useGroupContract.js  ← Contract method bindings
│   ├── services/
│   │   ├── opnetWallet.js       ← OP_NET wallet extension API
│   │   └── contractService.js   ← SDK + ABI + RPC layer
│   └── components/
│       ├── Header.jsx           ← Logo, wallet, nav
│       ├── StatsBar.jsx         ← Protocol stats
│       ├── GroupList.jsx        ← Grid + search + filters
│       ├── GroupCard.jsx        ← Individual group card
│       ├── GroupDetail.jsx      ← Full group view + actions
│       ├── ParticipantsPanel.jsx← Contributor list
│       ├── VotingPanel.jsx      ← Vote release/refund
│       ├── CreateGroupModal.jsx ← 3-step wizard
│       ├── JoinGroupModal.jsx   ← Invite code + browse
│       └── Footer.jsx
│
├── contracts/                   ← AssemblyScript OP_NET smart contracts
│   ├── src/
│   │   ├── escrow/EscrowContract.ts     ← Core escrow + state machine
│   │   ├── factory/GroupFactoryContract.ts ← Global group registry
│   │   ├── voting/VotingContract.ts     ← Standalone vote module
│   │   └── registry/RegistryContract.ts ← Contribution tracker
│   ├── asconfig-{escrow,factory,voting,registry}.json
│   ├── deploy.ts                ← Universal deployment script
│   ├── package.json
│   └── .env.example
│
├── index.html                   ← Contract address placeholders
├── package.json
├── vite.config.js
└── tailwind.config.js

---

🚀 Quick Start (Frontend Only)

cd BTCGather
npm install
npm run dev
# → http://localhost:3000

Works in demo mode (mock data, local simulation) without deployed contracts.

---

🔗 Smart Contract Deployment

1. Setup

cd BTCGather/contracts
cp .env.example .env
# Edit .env — add your MNEMONIC and RPC_URL
npm install

2. Build All Contracts

npm run build:all

This produces 4 WASM files in build/:

• BTCGatherEscrow.wasm
• BTCGatherFactory.wasm
• BTCGatherVoting.wasm
• BTCGatherRegistry.wasm

3. Deploy Contracts

# Deploy EscrowContract (main contract)
npm run deploy:escrow

# Deploy GroupFactoryContract
npm run deploy:factory

# Deploy VotingContract
npm run deploy:voting

# Deploy RegistryContract
npm run deploy:registry

Each deploy prints the contract address. Copy each address into index.html:

<script>
  window.BTCGATHER_ESCROW_CONTRACT    = 'opt1...your_escrow_address';
  window.BTCGATHER_FACTORY_CONTRACT   = 'opt1...your_factory_address';
  window.BTCGATHER_VOTING_CONTRACT    = 'opt1...your_voting_address';
  window.BTCGATHER_REGISTRY_CONTRACT  = 'opt1...your_registry_address';
</script>

4. Restart Frontend

cd ..
npm run dev

The app now switches from demo mode to live OP_NET mode.

---

📜 Contract State Machines

EscrowContract

Open (1) ──[deposits]──▶ Funded (2)
                              │
              ┌───────────────┼────────────────────┐
              ▼               ▼                    ▼
         Auto Rule        Vote Rule           All Rule
              │               │                    │
              ▼               ▼                    ▼
         Released (4)    Voting (3)           Voting (3)
                           │    │               │    │
                        votes  votes          votes  votes
                           │    │               │    │
                           ▼    ▼               ▼    ▼
                       Released Refunded   Released Refunded
                          (4)    (5)          (4)    (5)

Open (1) ──[deadline passed]──▶ Expired (6) ──▶ Refunded (5)

VotingContract

Not Started (0) ──[openVote]──▶ Active (1)
                                    │
                          ┌─────────┴──────────┐
                    [threshold]           [deadline]
                          │                    │
                    ┌─────┴─────┐        Expired (4)
                    ▼           ▼
               Release (2)  Refund (3)

---

🔐 Security Model

• Funds are locked in Bitcoin L1 smart contracts — no custody
• Deadline-based auto-refund prevents permanent fund lockup
• Vote thresholds are configurable per group (51%–100%)
• 0.3% protocol fee only on successful release
• No bridges, no EVM, Bitcoin L1 native only

---

⚙️ Contract Methods

EscrowContract

Method	Type	Description
createGroup(target, deadline, rule, pct)	Write	Initialize a new group escrow
deposit(amount)	Write	Contribute BTC to the fund
castVoteRelease()	Write	Vote to release funds to beneficiary
castVoteRefund()	Write	Vote to refund all contributors
finalizeRelease()	Write	Trigger release if vote threshold passed
claimRefund()	Write	Claim BTC refund
checkExpiry()	Write	Set expired state if deadline passed
getGroupInfo()	View	Full group state + amounts
getVoteInfo()	View	Vote counts + threshold
getProtocolStats()	View	Global protocol stats

GroupFactoryContract

Method	Type	Description
registerGroup(groupId)	Write	Register escrow in global registry
recordRelease(amount)	Write	Track released amount
getGroupCount()	View	Total registered groups
getFactoryStats()	View	Full factory statistics

VotingContract

Method	Type	Description
openVote(duration, pct, total)	Write	Start a vote round
castVote(0|1)	Write	Cast refund(0) or release(1) vote
finalizeVote()	Write	Check + finalize outcome
getVoteInfo()	View	Votes, state, deadline

RegistryContract

Method	Type	Description
recordDeposit(amount)	Write	Log a contribution
closeRegistry()	Write	Close registry to new deposits
getRegistryInfo()	View	Participant count + totals
getAverageDeposit()	View	Average contribution size

---

🌐 Networks

Network	RPC URL
Testnet	https://testnet-rpc.opnet.org
Mainnet	https://rpc.opnet.org

Explorer: https://opscan.org

---

🛣️ Roadmap

• Phase 5 — Integration testing (multiple wallets, edge cases)
• Phase 6 — UX polish (animations, tooltips, loading skeletons)
• Contribution history per wallet address
• Group invitation via URL share
• Multi-group dashboard per wallet
• Mobile PWA support

---

📄 License

MIT — Build freely on Bitcoin L1.