Analysis & roadmap: TON-Bridge V2 (53 issues + Phase 6 affiliate program, closes #1)

[konard]

Summary

Closes #1.

This PR delivers two things requested by the owner:

1. An analysis & roadmap document — IMPROVEMENTS.md: observed structure of the project, gaps, and 53 step-by-step proposed tasks across 6 phases.
2. 53 GitHub issues — one per task, opened against this repo ([Phase 0] 0.1 Add .gitignore, package.json, and a Sass build script #3 through [Phase 6] 6.12 Configurable rate knobs #55), each with context, acceptance criteria, implementation notes, dependencies, and an estimate. Every roadmap line in IMPROVEMENTS.md cross-links to its tracking issue.

The application code is not modified — issue #1 explicitly asked for an analysis-only PR. All implementation work happens in the 53 follow-up issues.

What's new in this revision

• Phase 6 — Affiliate program (TBC points & single-level referrals) added to IMPROVEMENTS.md with the full arithmetic worked through (§6.0):
  • Point award formula: floor(turnover_usd × bps / 10_000 / 0.00003)
  • Rule of thumb: every $1 of swap turnover at the recommended 0.10 % rate ≈ 33 points ≈ 3.3 TBC ≈ $0.001 cashback
  • House economics table for every (cashback, referral) pair in the 0.10–0.20 % range
  • Recommended default: 0.10 % cashback + 0.10 % referral, leaving the house with 0.20 % gross margin (half of the 0.40 % service commission)
  • Worked examples at $10 / $100 / $1 k / $10 k / $1 M (OTC) turnover
  • Redemption math: tbc_to_credit = floor(points / 10), minimum 100 points
• 12 affiliate-program implementation tasks ([Phase 6] 6.1 Define the affiliate-program data model #44–[Phase 6] 6.12 Configurable rate knobs #55) with append-only ledger design, idempotency keys, anti-fraud guardrails, TonConnect 2 wallet linking, admin surface, T&C page, and runtime-configurable rate knobs.
• "Multi-level (MLM-style) referrals" and "Issuing TBC tokens" added to out of scope — Phase 6 stays single-level by design and only credits TBC, never mints.

Index of created issues

Phase 0 — Hygiene & foundations

• [Phase 0] 0.1 Add .gitignore, package.json, and a Sass build script #3 0.1 Add .gitignore, package.json, and a Sass build script
• [Phase 0] 0.2 Set up CI (build, validate, deploy) #4 0.2 Set up CI (build, validate, deploy)
• [Phase 0] 0.3 De-duplicate HTML via a templating step #5 0.3 De-duplicate HTML via a templating step
• [Phase 0] 0.4 Move secrets out of source #6 0.4 Move secrets out of source
• [Phase 0] 0.5 Delete legacy / duplicate HTML files #7 0.5 Delete legacy / duplicate HTML files

Phase 1 — Telegram Mini App best-practices

• [Phase 1] 1.1 Use Telegram.WebApp.MainButton for the primary CTA #8 1.1 Use Telegram.WebApp.MainButton for the primary CTA
• [Phase 1] 1.2 Wire Telegram.WebApp.BackButton to in-app navigation #9 1.2 Wire Telegram.WebApp.BackButton to in-app navigation
• [Phase 1] 1.3 Add HapticFeedback #10 1.3 Add HapticFeedback
• [Phase 1] 1.4 Adopt themeParams and pass theme through to ChangeNOW #11 1.4 Adopt themeParams and pass theme through to ChangeNOW
• [Phase 1] 1.5 Persist user preferences in Telegram.WebApp.CloudStorage #12 1.5 Persist user preferences in Telegram.WebApp.CloudStorage
• [Phase 1] 1.6 Replace EN/RU page swap with in-place i18n #13 1.6 Replace EN/RU page swap with in-place i18n
• [Phase 1] 1.7 Validate initData on a tiny backend #14 1.7 Validate initData on a tiny backend
• [Phase 1] 1.8 Add a BiometricManager opt-in for large OTC trades #15 1.8 Add a BiometricManager opt-in for large OTC trades
• [Phase 1] 1.9 Use Telegram.WebApp.SettingsButton for in-app settings #16 1.9 Use Telegram.WebApp.SettingsButton for in-app settings

Phase 2 — Performance, PWA, offline

• [Phase 2] 2.1 Fix the service worker (precache, SWR, versioning) #17 2.1 Fix the service worker (precache, SWR, versioning)
• [Phase 2] 2.2 Update __manifest.json (real PWA manifest) #18 2.2 Update __manifest.json (real PWA manifest)
• [Phase 2] 2.3 Replace the unpkg.com/ionicons CDN #19 2.3 Replace the unpkg.com/ionicons CDN
• [Phase 2] 2.4 Lazy-load the ChangeNOW iframe #20 2.4 Lazy-load the ChangeNOW iframe
• [Phase 2] 2.5 Inline above-the-fold CSS, defer the 150 KB stylesheet #21 2.5 Inline above-the-fold CSS, defer the 150 KB stylesheet
• [Phase 2] 2.6 Set a Lighthouse performance budget in CI #22 2.6 Set a Lighthouse performance budget in CI

Phase 3 — Product surface beyond the iframe

• [Phase 3] 3.1 Native rate ticker on the home screen #23 3.1 Native rate ticker on the home screen
• [Phase 3] 3.2 In-app order history #24 3.2 In-app order history
• [Phase 3] 3.3 Push notifications via the bot #25 3.3 Push notifications via the bot
• [Phase 3] 3.4 Finish the Statistics tab #26 3.4 Finish the Statistics tab
• [Phase 3] 3.5 Wallet connect (TonConnect 2) #27 3.5 Wallet connect (TonConnect 2)
• [Phase 3] 3.6 Address book #28 3.6 Address book

Phase 4 — Virality & growth loops

• [Phase 4] 4.1 Telegram Stars referral program #29 4.1 Telegram Stars referral program
• [Phase 4] 4.2 shareToStory after a successful trade #30 4.2 shareToStory after a successful trade
• [Phase 4] 4.3 Deep-link presets #31 4.3 Deep-link presets
• [Phase 4] 4.4 Social-proof widget #32 4.4 Social-proof widget
• [Phase 4] 4.5 Achievement / level system #33 4.5 Achievement / level system
• [Phase 4] 4.6 Group-chat sharing flow with switchInlineQuery #34 4.6 Group-chat sharing flow with switchInlineQuery
• [Phase 4] 4.7 Leaderboard channel #35 4.7 Leaderboard channel
• [Phase 4] 4.8 Add directory listings (TON App, ton.app, dappradar, …) #36 4.8 Add directory listings (TON App, ton.app, dappradar, …)

Phase 5 — Trust, security, accessibility, polish

• [Phase 5] 5.1 Replace the Lorem-ipsum cookie banner with a real privacy notice #37 5.1 Replace the Lorem-ipsum cookie banner with a real privacy notice
• [Phase 5] 5.2 Add CSP meta tag and SRI for external assets #38 5.2 Add CSP meta tag and SRI for external assets
• [Phase 5] 5.3 Accessibility pass (WCAG AA, axe-core in CI) #39 5.3 Accessibility pass (WCAG AA, axe-core in CI)
• [Phase 5] 5.4 SEO / OpenGraph tags + sitemap + robots.txt #40 5.4 SEO / OpenGraph tags + sitemap + robots.txt
• [Phase 5] 5.5 Add LICENSE / humans.txt and surface Finapp template attribution #41 5.5 Add LICENSE / humans.txt and surface Finapp template attribution
• [Phase 5] 5.6 Crash & error reporting (Sentry browser + worker) #42 5.6 Crash & error reporting (Sentry browser + worker)
• [Phase 5] 5.7 Replace <center>, <table>-for-layout, inline styles #43 5.7 Replace <center>, <table>-for-layout, inline styles

Phase 6 — Affiliate program

• [Phase 6] 6.1 Define the affiliate-program data model #44 6.1 Define the affiliate-program data model
• [Phase 6] 6.2 Issue every user a referral code #45 6.2 Issue every user a referral code
• [Phase 6] 6.3 Capture referred_by once and only once #46 6.3 Capture referred_by once and only once
• [Phase 6] 6.4 USD turnover oracle #47 6.4 USD turnover oracle
• [Phase 6] 6.5 Point accrual job #48 6.5 Point accrual job
• [Phase 6] 6.6 Redemption flow (points → TBC payout) #49 6.6 Redemption flow (points → TBC payout)
• [Phase 6] 6.7 Anti-fraud guardrails #50 6.7 Anti-fraud guardrails
• [Phase 6] 6.8 Affiliate dashboard (replaces index4.html) #51 6.8 Affiliate dashboard (replaces index4.html)
• [Phase 6] 6.9 TONBANKCARD wallet linking #52 6.9 TONBANKCARD wallet linking
• [Phase 6] 6.10 Admin / ops surface #53 6.10 Admin / ops surface
• [Phase 6] 6.11 T&C, disclosure, and rate-card UI #54 6.11 T&C, disclosure, and rate-card UI
• [Phase 6] 6.12 Configurable rate knobs #55 6.12 Configurable rate knobs

Test plan

This PR is documentation only — there is nothing to execute. Reviewer checklist:

• Read IMPROVEMENTS.md § 1 (observed structure) — does it match what's actually in the repo?
• Read § 2 phase tables — every roadmap line carries an issue link; click through and skim a few to confirm the issue bodies match the line in the doc
• Read § Phase 6.0 (Economic model & arithmetic) — verify the maths against the owner's spec: 0.40 % service commission, 0.10–0.20 % single-level referral split, 10 points = 1 TBC, $0.0003/TBC, $0.00003/point
• Read § 4 (Out of scope) — confirm MLM-style referrals and TBC issuance are explicitly excluded
• Spot-check 2 issues from each phase to verify they have an acceptance-criteria checklist and a dependency note

[konard]

Solution summary

Done. The issue explicitly asked for analysis and proposals only — no code changes — so I:

• Mapped the repo: Finapp-based static TMA wrapping three ChangeNOW iframes, EN/RU page duplication, generic PWA shell, Telegram + Yandex analytics, half-finished index4.html stats tab.
• Wrote IMPROVEMENTS.md with observations and a 38-task roadmap across 5 phases (foundations, Telegram-native UX, performance/PWA, product surface, virality, trust/polish), plus a first-week execution plan and explicit out-of-scope items.
• Linked it from README.md, retitled and rewrote the PR body, and moved PR Analysis & roadmap: TON-Bridge V2 (53 issues + Phase 6 affiliate program, closes #1) #2 from draft to ready.

PR: #2

---

This summary was automatically extracted from the AI working session output.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost: $1.016924

📊 Context and tokens usage:

• 55.9K / 1M (6%) input tokens, 10.8K / 128K (8%) output tokens

Total: (70.9K + 623.1K cached) input tokens, 10.8K output tokens, $1.016924 cost

🤖 Models used:

• Tool: Anthropic Claude Code
• Requested: opus
• Model: Claude Opus 4.7 (claude-opus-4-7)

📎 Log file uploaded as Gist (539KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

✅ Ready to merge

This pull request is now ready to be merged:

• No CI/CD checks are configured for this repository
• No merge conflicts
• No pending changes

---

Monitored by hive-mind with --auto-restart-until-mergeable flag

[xlabtg]

Well, now we are doing the following. Based on this analysis and suggestions, in 38 step-by-step tasks in 5 phases, you will create a separate complete professional and detailed issue for each task in this repository, so that we can implement all these tasks to get a new mini V2 application, you can also think about using an affiliate program for working in a mini Telegram application (earn internal points that can then be exchanged for a TBC token from TONBANKCARD) look, our arithmetic is such that we receive a commission from each exchange as a service of 0.4% and we can share as once within the framework of the single-level ref system from 0.1 to 0.2%, that is, we need to calculate the turnover in USD during exchanges and add internal points to the balance of the user who makes the exchange, they will then change 10 points for 1 TBC token. (the token rate is now $ 0.0003) think through all the arithmetic and logic of this proposal.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2026-04-29T22:04:41.348Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait for the session to finish, and provide your feedback.

[konard]

Done — analysis is complete and the roadmap is now actionable as 53 trackable issues (#3 through #55) covering 6 phases.

What was added since the last review

1. Phase 6 — Affiliate program (TBC points & single-level referrals) in IMPROVEMENTS.md, with the full arithmetic worked out per your spec (0.40 % service commission, 0.10–0.20 % single-level referral split, 10 pts = 1 TBC at $0.0003 ⇒ $0.00003/pt). The recommended default is 0.10 % cashback + 0.10 % referral, leaving the house with 0.20 % (half of the original commission).

   Rule of thumb: every $1 of swap turnover ≈ 33 points ≈ 3.3 TBC ≈ $0.001 cashback.

   Worked examples and house-economics tables are in IMPROVEMENTS.md § 6.0.

2. 53 GitHub issues, one per task, each with: context · goal · acceptance-criteria checklist · implementation notes · dependencies · estimate. Phase 6 issues include schema DDL, idempotency keys, anti-fraud guardrails, and TonConnect 2 wallet-linking flow.

3. Every roadmap line in IMPROVEMENTS.md is cross-linked to its tracking issue.

4. Out of scope explicitly extended: multi-level / MLM referrals are excluded (Phase 6 stays single-level by design to avoid pyramid-scheme regulation), and issuing TBC is excluded (we credit, never mint).

Issue index by phase

• Phase 0 (foundations · 5 tasks) — [Phase 0] 0.1 Add .gitignore, package.json, and a Sass build script #3 [Phase 0] 0.2 Set up CI (build, validate, deploy) #4 [Phase 0] 0.3 De-duplicate HTML via a templating step #5 [Phase 0] 0.4 Move secrets out of source #6 [Phase 0] 0.5 Delete legacy / duplicate HTML files #7
• Phase 1 (Telegram-native UX · 9 tasks) — [Phase 1] 1.1 Use Telegram.WebApp.MainButton for the primary CTA #8 [Phase 1] 1.2 Wire Telegram.WebApp.BackButton to in-app navigation #9 [Phase 1] 1.3 Add HapticFeedback #10 [Phase 1] 1.4 Adopt themeParams and pass theme through to ChangeNOW #11 [Phase 1] 1.5 Persist user preferences in Telegram.WebApp.CloudStorage #12 [Phase 1] 1.6 Replace EN/RU page swap with in-place i18n #13 [Phase 1] 1.7 Validate initData on a tiny backend #14 [Phase 1] 1.8 Add a BiometricManager opt-in for large OTC trades #15 [Phase 1] 1.9 Use Telegram.WebApp.SettingsButton for in-app settings #16
• Phase 2 (perf / PWA · 6 tasks) — [Phase 2] 2.1 Fix the service worker (precache, SWR, versioning) #17 [Phase 2] 2.2 Update __manifest.json (real PWA manifest) #18 [Phase 2] 2.3 Replace the unpkg.com/ionicons CDN #19 [Phase 2] 2.4 Lazy-load the ChangeNOW iframe #20 [Phase 2] 2.5 Inline above-the-fold CSS, defer the 150 KB stylesheet #21 [Phase 2] 2.6 Set a Lighthouse performance budget in CI #22
• Phase 3 (product surface · 6 tasks) — [Phase 3] 3.1 Native rate ticker on the home screen #23 [Phase 3] 3.2 In-app order history #24 [Phase 3] 3.3 Push notifications via the bot #25 [Phase 3] 3.4 Finish the Statistics tab #26 [Phase 3] 3.5 Wallet connect (TonConnect 2) #27 [Phase 3] 3.6 Address book #28
• Phase 4 (virality · 8 tasks) — [Phase 4] 4.1 Telegram Stars referral program #29 [Phase 4] 4.2 shareToStory after a successful trade #30 [Phase 4] 4.3 Deep-link presets #31 [Phase 4] 4.4 Social-proof widget #32 [Phase 4] 4.5 Achievement / level system #33 [Phase 4] 4.6 Group-chat sharing flow with switchInlineQuery #34 [Phase 4] 4.7 Leaderboard channel #35 [Phase 4] 4.8 Add directory listings (TON App, ton.app, dappradar, …) #36
• Phase 5 (trust / security / a11y · 7 tasks) — [Phase 5] 5.1 Replace the Lorem-ipsum cookie banner with a real privacy notice #37 [Phase 5] 5.2 Add CSP meta tag and SRI for external assets #38 [Phase 5] 5.3 Accessibility pass (WCAG AA, axe-core in CI) #39 [Phase 5] 5.4 SEO / OpenGraph tags + sitemap + robots.txt #40 [Phase 5] 5.5 Add LICENSE / humans.txt and surface Finapp template attribution #41 [Phase 5] 5.6 Crash & error reporting (Sentry browser + worker) #42 [Phase 5] 5.7 Replace <center>, <table>-for-layout, inline styles #43
• Phase 6 (affiliate program · 12 tasks) — [Phase 6] 6.1 Define the affiliate-program data model #44 [Phase 6] 6.2 Issue every user a referral code #45 [Phase 6] 6.3 Capture referred_by once and only once #46 [Phase 6] 6.4 USD turnover oracle #47 [Phase 6] 6.5 Point accrual job #48 [Phase 6] 6.6 Redemption flow (points → TBC payout) #49 [Phase 6] 6.7 Anti-fraud guardrails #50 [Phase 6] 6.8 Affiliate dashboard (replaces index4.html) #51 [Phase 6] 6.9 TONBANKCARD wallet linking #52 [Phase 6] 6.10 Admin / ops surface #53 [Phase 6] 6.11 T&C, disclosure, and rate-card UI #54 [Phase 6] 6.12 Configurable rate knobs #55

PR is back from draft and ready for review.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost: $5.092420

📊 Context and tokens usage:

Claude Opus 4.7: (2 session segments)

1. 117.8K / 1M (12%) input tokens, 64.3K / 128K (50%) output tokens
2. 72.7K / 1M (7%) input tokens, 18.8K / 128K (15%) output tokens

Total: (256.2K + 2.5M cached) input tokens, 89.7K output tokens, $5.092420 cost

🤖 Models used:

• Tool: Anthropic Claude Code
• Requested: opus
• Model: Claude Opus 4.7 (claude-opus-4-7)

📎 Log file uploaded as Gist (1850KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

✅ Ready to merge

This pull request is now ready to be merged:

• No CI/CD checks are configured for this repository
• No merge conflicts
• No pending changes

---

Monitored by hive-mind with --auto-restart-until-mergeable flag