MTProto proxy discovery engine for Android. Fetches, validates, and ranks Telegram proxies across 7 distributed source endpoints. Bypasses IP-level network restrictions using local tg:// intents — no web intermediates, no central server, no manual search.
flowchart LR
A[7 Source Endpoints] -->|Dio GET| B(ProxyFetcherService)
B -->|Parse + Dedup| C{Proxy Cache}
C -->|2s TCP connect × 50 concurrency| D[ProxyTesterService]
D -->|Score + Sort| E[Ranked Proxy List]
E -->|tg:// intent| F[Telegram App]
F -->|Tapped + Failed| G[Failure Feedback]
G -->|−50 penalty| E
Telegram's built-in proxy settings are a configuration sink — you supply a server:port:secret, it attempts to connect. TelePulse is the supply chain: automatic discovery, TCP validation, latency ranking, and failure feedback — all before you ever hit "Connect" in Telegram.
| Feature | Telegram Built-in | TelePulse |
|---|---|---|
| Proxy discovery | Manual entry required | Auto-fetches from 7 endpoints |
| Pre-connection validation | Blind apply | TCP connect (2s timeout, no handshake) |
| Ranking | Chronological | Latency + source trust + failure feedback |
| Aggregation | 5 manual slots | 7 sources + custom URL |
| Favorites | None | SharedPreferences bookmarking |
| Cache strategy | None | Fresh (1h) + stale (24h) tiered cache |
| Network awareness | Manual re-check | Auto re-test on connectivity change |
| Concurrent testing | Sequential | 50 parallel, throttled state updates |
| Failure feedback | None | Per-proxy counter penalizes dead proxies |
| Protocol classification | None | Auto-detect fakeTLS (ee), ddPadding (dd), plain |
git clone https://github.com/krsnaSuraj/TelePulse.git
cd TelePulse
flutter pub get
flutter build apk --release
flutter installFirst launch: fetches all sources in parallel, tests every proxy at 50 concurrency, displays results incrementally. Cached proxies render instantly; fresh results stream in as batches complete.
mindmap
root((TelePulse Sources))
Primary
SoliSpirit[weight=5]
kort0881-all[weight=5]
kort0881-eu[weight=4]
kort0881-ru[weight=4]
Grim1313[weight=5]
Secondary
iwh3n[weight=3]
ALIILAPRO[weight=3]
Fallback
SoliSpirit-mirror[CDN, weight=2]
Grim1313-HTML[HTML parse, weight=2]
Sources auto-disable after 3 consecutive failures with 30-minute recovery window. Fallbacks activate when primary sources yield < 50 proxies.
flowchart TD
subgraph UI ["Presentation"]
H[HomeScreen] --> T[ProxyTile × many]
P[ProxyListScreen] --> T
F[FavoritesScreen] --> T
S[SettingsScreen]
end
subgraph State ["State Management"]
N[ProxyListNotifier<br/>StateNotifier FSM] --> R[Riverpod Provider]
end
subgraph Services ["Service Layer"]
Fetcher[ProxyFetcherService<br/>Dio HTTP]
Tester[ProxyTesterService<br/>Socket.connect]
Ranker[ProxyRankerService<br/>Score function]
Cache[ProxyCacheService<br/>SharedPreferences]
Sources[ProxySourceProvider<br/>Health tracking]
Conn[ConnectivityService<br/>connectivity_plus]
Deep[DeepLinkService<br/>tg:// launch]
Update[UpdateService<br/>GitHub API]
end
UI --> State
State --> Services
Fetcher --> Sources
| Component | Choice | Rationale |
|---|---|---|
| Framework | Flutter 3.44 / Dart 3.12 | Single codebase, native ARM64 |
| State management | Riverpod 2.6 (StateNotifier) | Zero code-gen, fully testable, composable |
| HTTP client | Dio 5.7 | Retry, timeout, interceptor pipeline |
| Proxy validation | dart:io Socket.connect |
TCP-only — protocol handshakes cause false positives |
| Ranking | Composite score function | Latency + source trust + port bonus + failure penalty |
| Persistence | SharedPreferences | Flat JSON; SQLite adds no value here |
| Deep link | url_launcher + tg:// intent |
Direct resolution with t.me fallback |
| Connectivity | connectivity_plus |
Edge-triggered online/offline detection |
Proxies are ranked by a composite score. The formula:
score = aliveBonus(100) + latencyTier + sourceTrust(10)
+ protocolBonus(5-15) + portBonus(8) - failurePenalty(50×n)
flowchart LR
A([Raw Proxy]) --> B{isAlive && failures < 3?}
B -->|Yes| C[+100 base]
B -->|No| D[0 base]
C --> E[+ latency tier]
D --> F[low priority]
E --> G[+ source trust +10]
G --> H[+ protocol bonus 5-15]
H --> I[+ port 443 +8]
I --> J[-50 per failure]
J --> K([Final Score])
| Factor | Value | Condition |
|---|---|---|
| TCP alive | +100 | isAlive == true && connectionFailures < 3 |
| Latency < 100ms | +50 | Best responsiveness |
| Latency 100–299ms | +40 | Good |
| Latency 300–499ms | +25 | Acceptable |
| Latency 500–999ms | +10 | Slow but usable |
| Trusted source | +10 | SoliSpirit, kort0881, Grim1313 |
| FakeTLS secret | +15 | ee prefix — mimics HTTPS |
| Obfuscated secret | +5 | dd prefix — light padding |
| Port 443 | +8 | Common HTTPS port, less throttled |
| Per failure | −50 | User tapped but Telegram couldn't connect |
Proxies with ≥3 failures are excluded from "Fastest Proxies" until they re-test as TCP-alive (which resets the counter). This ensures only proxies the user has actually used successfully stay at the top.
stateDiagram-v2
[*] --> initial
initial --> loading: refreshProxies()
loading --> ready: fetch complete
loading --> error: all sources failed
loading --> noProxies: 0 proxies fetched
ready --> testing: testProxies()
ready --> noInternet: connectivity loss
testing --> ready: all batches complete
error --> loading: retry
noInternet --> loading: connectivity restored
Update checks against the GitHub Releases API. A "Check for Updates" tile in Settings triggers:
- Fetch latest release tag from GitHub (10s timeout)
- Semver comparison against current
PackageInfoversion - Release notes + download dialog if newer
- APK download URL resolved from release assets
- 1-hour result cache + per-version skip persistence
To publish: git tag v1.0.2 && git push --tags, upload APK to a new GitHub Release.
xychart-beta
title "Typical Timing (200 proxies)"
x-axis ["Cold Start", "Cache Load", "Fetch", "Full Test", "Tap → TG"]
y-axis "ms" 0 --> 10000
bar [1000, 50, 8000, 8000, 500]
| Phase | Latency | Notes |
|---|---|---|
| Cache load (tested) | ~50ms | SharedPreferences deserialization |
| Source fetch | 5–10s | Parallel HTTP, 10/15s connect/receive timeout |
| Full test (200 proxies) | ~8s | 2s connect ÷ 50 concurrency |
| Incremental update | ~6s | Merged every 3 batches |
| Cold start → ready | ~1s | Cache-first render, background refresh |
| Tap → Telegram dialog | ~500ms | didTapProxy + TCP test + tg:// intent |
# Debug
flutter build apk --debug
# Release (obfuscated, minified, signed)
flutter build apk --release --obfuscate --split-debug-info=debug-infolib/
main.dart # Entry → ProviderScope + TelePulseApp
app.dart # MainShell: IndexedStack + 4-tab NavigationBar
theme/
app_theme.dart # Amber/"Signal Ops" dark theme
models/
proxy_model.dart # ProxyModel + protocol detection + JSON serde
providers/
proxy_list_provider.dart # Central StateNotifier FSM + merge logic
screens/
home_screen.dart # Dashboard: status orb, top 5, fade-in
proxy_list_screen.dart # Full list: test progress, re-test
favorites_screen.dart # Bookmarks: empty state, retest
settings_screen.dart # Custom URL, source list, stats, about, update
services/
proxy_fetcher_service.dart # Dio-based HTTP fetch + 4 parser strategies
proxy_tester_service.dart # dart:io Socket.connect, 2s t/o, 50 concurrency
proxy_ranker_service.dart # Composite scoring + ranking
proxy_cache_service.dart # SharedPreferences 2-tier cache with TTL
proxy_source_provider.dart # Source health tracking + auto-disable
connectivity_service.dart # connectivity_plus edge-triggered wrapper
deep_link_service.dart # tg:// → t.me → web → clipboard try-fall chain
update_service.dart # GitHub API update check + semver + caching
data/
proxy_sources.dart # 7 source definitions + 2 fallback
widgets/
proxy_tile.dart # Card: tap → didTap + test + connect, long-press → copy
animated_status_orb.dart # CustomPainter: dash-ring + scan arc + pulse
status_badge.dart # Color-coded latency badge with border
glass_card.dart # Semi-transparent surface container
proxy_shimmer.dart # Shimmer loading skeleton
utils/
haptic_utils.dart # HapticFeedback patterns
MIT — see LICENSE.