[EPIC] PlotLink Buy-Back Sprint v5 — Airdrop Campaign

[realproject7]

Spec: docs/PLOTLINK-diamond-hand-airdrop-5.md · Design: z-design/plotlink-airdrop-final.html

Campaign in one paragraph

Users activate by signing into PlotLink (SIWE) + confirming an X handle (via twitterapi.io) + clicking Follow on @plotlinkxyz, with an optional Farcaster follow that adds a multiplier bonus. Once activated, every PLOT spent on storyline tokens during the 3-month campaign contributes to share of the released pool. Bringing friends multiplies the share (up to 3×). At month 3, the milestone reached by PLOT's FDV determines what fraction of the 200K pool gets released — the rest burns forever.

Three phases

• Phase A — Activate (one-time, ~3 min): SIWE + X handle + X follow (+ optional FC follow)
• Phase B — Mine (3 months): PLOT spent on storyline tokens, tracked by existing v1 cron
• Phase C — Settle (T+3 months): 7-day TWAP → tier → released_pool, Merkle distribution, burn unclaimed

Pool

• 200,000 PLOT (20% supply) locked via Mint Club Locker on Base for 3 months
• Sourcing: Project7 ~11% + 9% buyback on bonding curve over 7-day TWAP pre-launch

Milestone tiers (per §4.3)

Tier	FDV	Released	Burned
🥉 Bronze	$100K	10% (20K)	90% (180K)
🥈 Silver	$1M	30% (60K)	70% (140K)
🥇 Gold	$5M	50% (100K)	50% (100K)
💎 Diamond	$10M	100% (200K)	0%

Sub-Bronze (FDV < $100K): 0% released, 100% burned.

Phases + tickets

Phase 0 — Operator setup (~0.6d)

• [T0.1] Confirm v1 deployment + approve campaign config + provision API keys #1230 T0.1 [op] Confirm v1 deployment + approve config + provision API keys (includes T2.4b + T1.1 decisions)
• [T0.2] Apply pl_activations DB schema migration #1231 T0.2 [op] Apply DB schema migration (pl_activations + is_blacklisted)

Phase 1 — v1 reset + cron fix (~0.8d)

• [T1.1] Fix airdrop-points cron handler (GET wrapper, no vercel.json edit) #1232 T1.1 [code] Fix airdrop-points cron handler (GET wrapper, no vercel.json edit)
• [T1.2] Production-DB smoke test + wallet-scoped v1 cleanup #1233 T1.2 [op] Production-DB smoke + wallet-scoped v1 cleanup (merged T1.2+T1.3 — single op session; single-DB env)
• [T1.4] Production cron registration (deferred to T5.2 launch pre-flight) #1235 T1.4 [op] Production cron registration (deferred to T5.2 launch pre-flight)

Phase 2 — Backend (~5.8d)

• [T2.1] Update lib/airdrop/config.ts (PROD + TEST configs) #1236 T2.1 [code] Update lib/airdrop/config.ts (PROD + TEST)
• [T2.2] v1 code cleanup (points, award, cron, checkin) #1237 T2.2 [code] v1 code cleanup (points, award, cron, checkin)
• [T2.3] Build lib/airdrop/twitterapi.ts (lookupXUser) #1238 T2.3 [code] Build lib/airdrop/twitterapi.ts
• [T2.4] Build lib/airdrop/activation-verify.ts (verifyFc) #1239 T2.4 [code] Build lib/airdrop/activation-verify.ts
• [T2.4a] Build lib/airdrop/siwe-verify.ts (full EIP-4361 validation) #1240 T2.4a [code] Build lib/airdrop/siwe-verify.ts
• [T2.4b] Shared SQL helper v_weighted_spend (config-source decision required) #1241 T2.4b [code] Shared SQL helper v_weighted_spend (config-source decision required)
• [T2.5a] X handle + follow endpoints (verify-x-handle, confirm-x-handle, x-follow-click) #1242 T2.5a [code] X handle + follow endpoints
• [T2.5b] /verify-fc endpoint (single endpoint, 2 Neynar calls) #1243 T2.5b [code] /verify-fc endpoint
• [T2.5c] /activation-status endpoint (public read) #1244 T2.5c [code] /activation-status endpoint
• [T2.5d] /projection endpoint (canonical v5 contribution API) #1245 T2.5d [code] /projection endpoint
• [T2.5e] Auth migration on referral endpoints (register-referral, referral-code) #1246 T2.5e [code] Auth migration on referral endpoints
• [T2.5f] v1 endpoint rewrites (status, leaderboard, points deprecation) #1247 T2.5f [code] v1 endpoint rewrites (status, leaderboard, points deprecation)
• [T2.6] Rewrite scripts/airdrop-finalize.ts per §5.2 SQL #1248 T2.6 [code] Rewrite scripts/airdrop-finalize.ts
• [T2.7] Add claim deadline + sweepUnclaimed to MerkleClaim contract (T6.5 prerequisite) #1267 T2.7 [code] MerkleClaim contract: claim deadline + sweepUnclaimed + rename 🚨 (BLOCKS T6.2/T6.5)

Phase 3 — Frontend (~6.7-7.2d) — all reference z-design/plotlink-airdrop-final.html

• [T3.0] Verify wallet-connect UI integration for /airdrop #1249 T3.0 [code] Verify wallet-connect UI integration
• [T3.1] 3-state machine in src/app/airdrop/page.tsx #1250 T3.1 [code] 3-state machine in airdrop/page.tsx
• [T3.2] Build ActivationFlow.tsx (3-step UI with refresh-resume) #1251 T3.2 [code] Build ActivationFlow.tsx
• [T3.3] Build ContributionPanel.tsx (reads from /projection) #1252 T3.3 [code] Build ContributionPanel.tsx
• [T3.4] Implement MilestoneClimb.tsx (port SVG from v4 backup) #1253 T3.4 [code] Implement MilestoneClimb.tsx (deps: T2.5d + T2.5f)
• [T3.5] Implement ReferralCTA.tsx (link + copy + share) #1254 T3.5 [code] Implement ReferralCTA.tsx (deps: T2.5e)
• [T3.6] Refactor ClaimPanel.tsx → ClaimCard.tsx (v5 breakdown copy) #1255 T3.6 [code] Refactor ClaimPanel.tsx → ClaimCard.tsx (deps: T2.6 + T2.7)
• [T3.7] Delete StreakCard, WeeklySnapshots; reduce CampaignHero #1256 T3.7 [code] Delete v1-only components
• [T3.8] Storyline page integration (banner + ref preservation) #1257 T3.8 [code] Storyline page integration

Phase 4 — Deploy gates + Reusable test framework (~2.5d)

• [T4.0] Deploy gate automation scripts (T2.x, T3.x, Pre-T4.1) #1268 T4.0 [code] Deploy gate automation — CLOSED per RE1 r35 (deferred — manual T4.1 sufficient for v5 one-shot launch; saves ~1.5d DEV)
• [T4.1] Manual full-cycle launch readiness test (operator click-through) #1258 T4.1 [op] Manual full-cycle launch readiness test (RE1 r35: simplified from orchestrator → manual click-through, ~1-1.5h per run, 2 consecutive PASS) — operator manually runs browser click-through sessions multiple times before launch; remains open as confidence tracker until 2 consecutive PASS runs + within 7d of T5.2

Test modes (per T2.1 #1236 — RE1 round-12)

Mode	Duration	Used by	Who runs
test-fast	5 min	(T4.0 closed per RE1 r35 — no longer used)	n/a
test-full	30 min	T4.1 manual click-through (RE1 r36)	Operator (browser + MetaMask/Coinbase/Rainbow)
prod	3 months	Real campaign	Real users

Phase 7 — Share virality polish (launch-critical)

Story page OG / share preview fixes — directly impacts airdrop referral conversion (?ref= links rely on share-preview quality).

• [T7.1] Fix story page og:url + OG metadata audit #1269 T7.1 [code] Fix story page og:url missing + audit OG metadata + cold-start timing
• [T7.2] Redesign story OG image to match StoryCard thumbnail design #1270 T7.2 [code] Redesign story OG image to match StoryCard thumbnail (port oklch→hex, badges, TVL format)

Both T7.x merge + deploy to production REQUIRED before #1260 T5.2 launch announce. Can run in parallel with Phase 2/3 (independent of activation flow).

Phase 8 — Emergency procedures (added per RE1 r38 operator request)

• [T8.1] Airdrop emergency rollback playbook (3-tier) #1271 T8.1 [op/docs] Airdrop emergency rollback playbook (3-tier: pause / soft / hard). Written by operator after T7.2 merge, before T4.1 starts. ~0.3d. Level 1 validation embedded in T4.1.

Phase 5 — Operational (v5 settlement milestone, calendar-driven)

• [T5.1] Pre-launch buyback (~9% PLOT via TWAP 7 days) #1259 T5.1 [op] Pre-launch buyback (~9% PLOT via TWAP 7 days)
• [T5.2] Launch day (lock 200K + public announcement) #1260 T5.2 [op] Launch day (lock 200K + public announcement) (merged T5.2+T5.3 — same launch-day op session) — pre-flight requires [T7.1] Fix story page og:url + OG metadata audit #1269 + [T7.2] Redesign story OG image to match StoryCard thumbnail design #1270 deployed to prod

Phase 6 — Settlement (T+3 months, v5 settlement milestone)

• [T6.1] Run finalize script + approve distribution (settlement) #1262 T6.1 [op] Run finalize script + approve distribution (NORMAL vs SUB-BRONZE branching)
• [T6.2] Settlement day (deploy contract + fund + announce) #1263 T6.2 [op] Settlement day (deploy contract + fund + announce) (merged T6.2+T6.3+T6.4 — same settlement-day op session with internal 🚦 PAUSE checkpoints)
• [T6.5] At claimDeadline: sweep unclaimed to dead address #1266 T6.5 [op] At claimDeadline: sweep unclaimed to dead address (single contract call)

Count

1 epic (#1229) + 36 child tickets = 37 open issues total. (T8.1 #1271 added per RE1 r38.) RE1 r35: T4.0 (#1268) closed (deferred per round-35). Milestone breakdown: v5 launch-ready = 33 (epic + 32 children, Phase 0-4 + Phase 7 + Phase 8) · v5 settlement = 5 children (Phase 5-6). New: #1268 T4.0.

Operator action map (RE1 round-9 consolidation)

	Before (round-8)	After (round-9)
Operator tickets	14	10
Manual deploy-gate items	17 (3 gates × ~5-7 each)	~5 (T4.0 closed per RE1 r35 — operator handles pre-T4.1 checks manually, ~10 items)
Total operator action points	~17	~12
Net reduction	—	~30% fewer handoffs

Effort estimate

• Total dev: ~14.5-15.5 days (RE1 r35: T4.0 closed, -1.5d). Includes T2.7 contract +0.5d + T2.7 Foundry bootstrap +0.2d. Phase 4 dev = 0 (T4.1 is operator-time only).
• Phase 5-6: calendar-driven, not dev

Risk register

22 risks (R1-R22) documented in §9 of spec. Key items:

• R2 Sybil activations (Medium-High) — mitigated by 3× cap + UNIQUE X handle + is_blacklisted
• R9 New MerkleClaim contract bug (Medium per T2.7 diff) — Foundry tests + testnet deploy required
• R11 Operator misses manual sweep — hard-gated by T2.7 deadline + simplified to one sweepUnclaimed call
• R17 Settlement sell pressure (Medium) — 30-day claim window staggers entry
• R18 SIWE wallet compatibility (Medium) — T4.1 test matrix
• R22 Leaked SIWE signature replay (Low) — bounded scope, 10-min freshness, full EIP-4361 validation

Open questions (resolved at T0.1)

11 open questions in §10. T0.1 also captures: T2.4b config-source (A/B) + T1.1 staging-cron mechanism (A/B/C/D).

Reviews

Spec + tickets passed 39 RE1 review cycles (spec §17-§22 + ticket rounds 6-39). ~120 items applied, 4 pushed back with reasoning. Round-9 consolidated operator workflow (3 ticket merges + deploy gate automation). Round-12 added test-full orchestrator + risk mitigations. Round-13 fixed test timing + cleanup safety guards. Round-14 fixed Supabase project-ref guard + Foundry lib/ collision.

Execution order (RE1 round-32 — partial reorder with operator-gate batching)

T1.4 successfully deferred to launch batch. T1.2 stays at original position because its body explicitly validates pre-T2.2 v1 dirty cron behavior — deferring it would create internal contradiction with T2.2 cleanup. Net: 1 mid-flow operator gate (T1.2) instead of original 2.

Batch A — Operator PREP (front, ~30 min)

• ✅ T0.1 ([T0.1] Confirm v1 deployment + approve campaign config + provision API keys #1230) — locked
• ✅ T0.2 ([T0.2] Apply pl_activations DB schema migration #1231) — applied
• 🟡 Operator: Vercel env vars (add PLOTLINK_FC_FID, review "Needs Attention" items, confirm NEXT_PUBLIC_APP_URL = https://plotlink.xyz)
• 🟡 Operator: generate/fund 3-5 operator-owned test wallets for T4.1 (small PLOT + Base ETH for gas)

Batch B — DEV chain start

1. T1.1 ([T1.1] Fix airdrop-points cron handler (GET wrapper, no vercel.json edit) #1232) — cron GET wrapper, no vercel.json edit

🙋 Mid-flow operator gate (single — ~15 min)

2. T1.2 ([T1.2] Production-DB smoke test + wallet-scoped v1 cleanup #1233) — production-DB smoke + wallet-scoped cleanup, validates v1 cron mechanism before T2.2 cleanup begins. CANNOT be deferred — body tests pre-T2.2 v1 dirty output (streak-boosted points + referral rows).

Batch B continued — DEV chain (uninterrupted, ~16d)

HEAD assigns sequentially after T1.2 completes:
3. T2.1 (#1236) — config 3-mode + Supabase types regen
4. T2.2 (#1237) — v1 code cleanup
5. (parallel) T2.3 (#1238) / T2.4 (#1239) / T2.4a (#1240) / T2.4b (#1241) / T2.7 (#1267)
6. T2.5a-f (#1242-#1247) — sequential or parallel by sub-dep
7. T2.6 (#1248) — finalize script
8. T3.0 (#1249) → T3.1-T3.8 (#1250-#1257) — mostly parallel
9. T4.0 (#1268) — CLOSED per RE1 r35, deferred (manual T4.1 sufficient)
10. (parallel anytime after T2.1) T7.1 (#1269) → T7.2 (#1270) — share virality polish

Batch C — Operator TEST (after DEV chain, ~3-4 weeks across runs)

11. T8.1 ([T8.1] Airdrop emergency rollback playbook (3-tier) #1271) — operator writes docs/airdrop-rollback-playbook.md (~0.3d, after T7.2 merges, before T4.1 starts). Reference document for emergency scenarios.
12. T4.1 ([T4.1] Manual full-cycle launch readiness test (operator click-through) #1258) — manual click-through full-cycle test (~1-1.5h × 2 runs until 2 consecutive PASS within 7 days of T5.2). RE1 r35: no orchestrator, no automated fixture/private-key setup (operator uses local secrets/tools + browser wallets manually), no fixture files — operator clicks via MetaMask/Coinbase/Rainbow + manual Supabase dashboard cleanup.

Batch D — Operator LAUNCH + SETTLEMENT (end, calendar-bound)

13. T5.1 ([T5.1] Pre-launch buyback (~9% PLOT via TWAP 7 days) #1259) — pre-launch buyback (7-day calendar, manual runbook)
14. T5.2 ([T5.2] Launch day (lock 200K + public announcement) #1260) — launch day (lock + announce). T1.4 ([T1.4] Production cron registration (deferred to T5.2 launch pre-flight) #1235) is the first pre-flight item inside T5.2 (~5 min: register prod cron in vercel.json); not a standalone step. Safe because T4.x used manual curl, so the prod cron has been intentionally unregistered until this moment.
15. [3-month campaign window — no dev work, monitor only]
16. T6.1 ([T6.1] Run finalize script + approve distribution (settlement) #1262) — finalize dry-run + branch decision (NORMAL / SUB-BRONZE / ZERO-RECIPIENT)
17. T6.2 ([T6.2] Settlement day (deploy contract + fund + announce) #1263) — settlement day (deploy + fund + announce, branch-specific)
18. T6.5 ([T6.5] At claimDeadline: sweep unclaimed to dead address #1266) — at claimDeadline, sweep unclaimed to dead address

Operator interruption count

• Before any reorder: 2 mid-flow gates (T1.2 after T1.1, T1.4 after T2.2)
• After round-32 partial reorder: 1 mid-flow gate (T1.2 only, ~15 min) — T1.4 successfully deferred via manual-curl pattern in T4.x.
• Total operator touch: prep batch (~30 min) + T1.2 (~15 min) + ~1-2h × 2+ runs + launch+settlement (calendar).