Skip to main content

Farcaster Mini App Launch Checklist

Scope​

This checklist covers production launch readiness for Vartovii Farcaster Mini App and deep-link funnel integration with vartovii.com.

1. Production Environment Configuration​

Apply these environment variables on the production backend service:

FARCASTER_DOMAIN=vartovii.com
FARCASTER_HOME_URL=https://vartovii.com/api/farcaster/frame
FARCASTER_CAST_SHARE_URL=https://vartovii.com/api/farcaster/frame?source=cast_share
FARCASTER_URL_VERSION=20260726-1
FARCASTER_APP_NAME=Vartovii Contract Signals
FARCASTER_APP_SUBTITLE=Base contract risk signals
FARCASTER_APP_TAGLINE=Review signals before you act
FARCASTER_APP_DESCRIPTION=Review contract, ownership, and available activity evidence for Base contracts.
FARCASTER_BUTTON_TITLE=Scan contract
FARCASTER_PRIMARY_CATEGORY=developer-tools
FARCASTER_TAGS=base,contracts,risk,devtools,web3
FARCASTER_ICON_URL=https://vartovii.com/app/public/farcaster_icon_v2.png
FARCASTER_SPLASH_IMAGE_URL=https://vartovii.com/app/public/farcaster_splash_v2.png
FARCASTER_IMAGE_URL=https://vartovii.com/app/public/farcaster_embed_v2.png
FARCASTER_HERO_IMAGE_URL=https://vartovii.com/app/public/farcaster_embed_v2.png
FARCASTER_OG_TITLE=Vartovii Contract Signals
FARCASTER_OG_DESCRIPTION=Review Base contract risk signals based on available data.
FARCASTER_OG_IMAGE_URL=https://vartovii.com/app/public/farcaster_embed_v2.png
FARCASTER_SCREENSHOT_URLS=https://vartovii.com/app/public/farcaster_screenshot_scan_v2.png,https://vartovii.com/app/public/farcaster_screenshot_result_v2.png,https://vartovii.com/app/public/farcaster_screenshot_error_v2.png
FARCASTER_SAMPLE_CONTRACT=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
FARCASTER_NOINDEX=false
FARCASTER_ANALYSIS_VERSION=farcaster-hybrid-v2
FARCASTER_MARKET_TIMEOUT_SECONDS=2.0
FARCASTER_MARKET_CACHE_TTL_SECONDS=60
FORENSIC_CACHE_TTL_SECONDS=3600
FORENSIC_AI_TIMEOUT_SECONDS=5.0
FORENSIC_CHAIN_TIMEOUT_SECONDS=4.0
BASE_RPC_TIMEOUT_SECONDS=4.0
FORENSIC_PREWARM_ADDRESSES=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913,0x4200000000000000000000000000000000000006

Identity images use new immutable filenames for every visual revision because Farcaster clients may cache an image URL for a long period. Keep the previous files available during the rollback window; changing their contents is not a reliable way to refresh an installed app.

Manifest field guardrails (must pass):

  • subtitle length <= 30
  • tagline length <= 30
  • iconUrl: 1024 x 1024 PNG without alpha
  • splashImageUrl: 200 x 200
  • screenshotUrls: portrait 1284 x 2778, maximum 3
  • heroImageUrl and ogImageUrl: 1200 x 630 PNG

2. Pre-Deploy Local Validation​

pytest -q -m integration tests/test_farcaster.py
npm -C dashboard_app run lint -- src/router.jsx src/pages/forensics/ForensicsPage.jsx
npm -C dashboard_app run build

Expected: all commands pass.

3. Deploy Sequence​

  1. Commit and push to your integration branch.
  2. Open PR and merge into master.
  3. Verify CI workflow success.
  4. Confirm Cloud Build / Cloud Run deployment finished.
  5. In Farcaster Developer Dashboard, click Refresh for manifest.

Publishing has four separate operations:

OperationPurposeCurrent release
Code pushDeploy reviewed application and manifest changesRequired
Manifest refreshAsk Farcaster to refetch production metadataRequired after deploy
Launch castCreate opens and adds through an embedded castManual approval
Push notificationRe-engage opted-in users through tokensNot implemented

Push notifications are not another name for publishing. They require an approved webhook plus a consent-safe notification-token lifecycle, so the manifest intentionally omits webhookUrl.

4. Manifest Verification (Production)​

curl -s https://vartovii.com/.well-known/farcaster.json | jq '.miniapp'

Confirm non-empty values for:

  • primaryCategory
  • tags
  • screenshotUrls (>= 3)
  • subtitle
  • tagline
  • ogTitle
  • ogDescription
  • ogImageUrl
  • castShareUrl
  • noindex is false

Compatibility target:

  • miniapp contains the current manifest fields.
  • frame remains present with the same value for older clients.
  • webhookUrl is absent until a real Farcaster notification handler exists.
  • The signed account-association payload decodes to vartovii.com.
  • The client pins @farcaster/miniapp-sdk@0.3.0.

If users still see stale Mini App UI after deploy, bump URL version:

FARCASTER_URL_VERSION=20260228-3

Then refresh the Mini App manifest in Farcaster dashboard.

5. User-Side Testing Plan​

Use two accounts:

  • Account A: app owner/admin
  • Account B: independent user (non-owner)

Scenario A — Discoverability​

  1. Login with Account B.
  2. Open Farcaster Mini Apps search.
  3. Search using: Vartovii, Contract Signals, and creator handle.
  4. Verify app appears and opens.

Metadata improves eligibility and comprehension but does not guarantee search placement. Search also depends on recent opens, adds, engagement, quality signals, and Farcaster's indexing cadence. Record non-owner discovery as unverified when a second authenticated account is unavailable.

Scenario B — Scanner Flow​

  1. Open Mini App.

  2. Click Try a sample Base contract, or enter: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

  3. Verify response includes:

    • token or contract identity
    • bounded contract-control signal
    • exact Base contract match status
    • market snapshot, or a bounded unavailable explanation
    • contract profile
    • separated control risks and supporting signals
    • reader-facing coverage limits

  4. Run the production FLUID verification with: 0x61e030a56d33e8260fdd81f03b162a79fe3449cd.

  5. Confirm the result identifies Fluid / FLUID, reports an exact Base contract match when the provider is available, and shows the same bounded market status in the full forensic report.

Market data is descriptive context and never affects the contract-control signal.

Scenario C — Invalid Input​

  1. Enter 0x123.
  2. Verify deterministic error behavior (no hallucinated success payload).

Scenario D — Cache Behavior​

  1. Repeat scan on same address.
  2. Verify second response is faster and indicates cached branch.

Scenario E — Share + Deep Link​

  1. Click Share Result.
  2. Verify the native Farcaster composeCast action opens with the Mini App embed link.
  3. Click View Full Report.
  4. Verify redirect to: /app/forensics/:address?source=farcaster...

6. Growth Event Checks​

Validate event ingestion logs for:

  • miniapp_open
  • scan_started
  • scan_succeeded
  • scan_failed
  • result_shared
  • new_scan_started
  • deep_link_open

Legacy events remain accepted temporarily for cached clients. New clients must not record contract addresses, raw exceptions, or upstream payloads.

7. Share Copy Variants (A/B)​

Current Mini App share variants:

  1. Vartovii contract control signal: {control concern} · {score}/100.
  2. {shortAddress} · bounded Base contract checks.

Both variants include Mini App embed URL from FARCASTER_CAST_SHARE_URL.

8. Release Gate​

Launch only when all are true:

  • Test suite green (tests/test_farcaster.py)
  • Manifest fields complete in production
  • Non-owner discoverability test passed
  • Share and deep-link flow passed
  • FLUID exact-contract identity and market-context path verified, or the provider returned a bounded unavailable reason
  • No critical latency regressions on warm path

9. Post-Deploy Smoke Check (Automation)​

GitHub Actions workflow:

  • .github/workflows/post-deploy-smoke.yml

Local equivalent command:

python scripts/post_deploy_smoke.py \
  --base-url https://vartovii.com \
  --address 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  --retries 3 \
  --delay 20

This smoke check validates:

  • current miniapp plus matching legacy frame manifest schemas
  • signed association domain equality with the production host
  • absence of a notification webhook until notification handling exists
  • immutable versioned identity image URLs
  • Mini App frame markers (Know the signals before you interact., Scan contract)
  • invalid input returns a bounded error without a score
  • contract endpoint payload contract, including bounded market_context
  • deployed Forensics bundle markers (Contract control signal, Market snapshot, Contract Profile, Open in Crypto Module)