Skip to main content

Phantom dApp Keys - Deployment Checklist

Pre-Deployment (Do Once)​

  • Generate keypair

    cd ../smartbets-protocol
    node scripts/generate-phantomkeypair.js

    Copy output values

  • Update environment files

    • .env - add DEVNET keys
    • .env.mainnet - add MAINNET keys (different from devnet!)
    • .env.devnet (if exists) - add devnet keys

  • Verify code changes

    • src/lib/phantomDeeplink.ts loads keys from ENV
    • No localStorage fallback key generation
    • Validation errors are clear

Pre-Build​

  • Verify environment variables are set

    echo $VITE_PUBLIC_PHANTOM_DAPP_PUBLIC_KEY
    echo $PHANTOM_DAPP_SECRET_KEY

  • Check for hardcoded keys

    • No keys in git history
    • No keys in comments/docs (except template)

Build​

  • Clean build

    rm -rf dist node_modules/.vite
    npm run build:mainnet

  • Check build output

    # Public key should be embedded (VITE_ prefix)
    grep "VITE_PUBLIC_PHANTOM_DAPP_PUBLIC_KEY" dist/assets/*.js
    # Secret should NOT be in build output
    ! grep "PHANTOM_DAPP_SECRET_KEY" dist/assets/*.js

Post-Build / Pre-Deploy​

  • Test locally

    npm run preview:mainnet
    # Visit http://localhost:4173
    # Open browser console, check for errors

  • Verify error handling

    • If keys missing: Clear error message in console
    • If keys invalid: Descriptive base58 decode error
    • No silent fallbacks

Deployment​

For Vercel/Netlify:​

  • Add environment secrets

    • Project Settings → Environment Variables
    • Add: VITE_PUBLIC_PHANTOM_DAPP_PUBLIC_KEY=<public>
    • Add: PHANTOM_DAPP_SECRET_KEY=<secret>

  • Trigger rebuild

    git push  # Redeploy with env vars

  • Check build logs

    • No "Missing VITE_PUBLIC_PHANTOM_DAPP_PUBLIC_KEY" errors
    • Build succeeds

For Self-Hosted:​

  • Set environment variables

    export VITE_PUBLIC_PHANTOM_DAPP_PUBLIC_KEY=<public>
    export PHANTOM_DAPP_SECRET_KEY=<secret>
    npm run build:mainnet

  • Deploy dist folder

Post-Deployment Testing​

  • Test Phantom connection

    1. Open https://your-app.com on mobile
    2. Click "Connect Wallet"
    3. Phantom opens
    4. Approve in Phantom
    5. Redirect back to app
    6. Check browser console: No errors

  • Test signing

    1. Connect wallet (if not already)
    2. Click "Sign Message"
    3. Phantom opens
    4. Approve signature
    5. Redirect back: No error screen
    6. Console: handleSignMessageCallback success: true

  • Test session persistence

    1. Sign a message
    2. Refresh page
    3. Session still valid (no re-connect needed)

Rollback Plan​

If something breaks:

  • Check error logs

    # Browser console: Check for base58 decode errors
    # Network: Check for 401/403 from Phantom

  • Clear Phantom session (user side)

    1. Phantom → Settings → Trusted Apps
    2. Remove app
    3. Try again

  • Regenerate keys (if keys compromised)

    node scripts/generate-phantomkeypair.js
    # Update environment variables
    # Redeploy
    # Users: Remove app from Phantom Trusted Apps

  • Revert to previous deployment If keys are correct but something else broke, revert without changing keys

Maintenance​

  • Monthly check: Verify keys still in environment
  • After mainnet launch: Document keys in secure vault (1Password, etc.)
  • Key rotation: Only if absolutely necessary; expensive operation

Environment Variable Safety​

⚠️ NEVER:

  • Commit secret keys to git
  • Log secret keys to console
  • Share keys in Slack/Discord
  • Use same keys across multiple dApps

✅ DO:

  • Use CI/CD secrets (GitHub Secrets, Vercel Env, etc.)
  • Rotate keys if accidentally exposed
  • Generate separate keys per environment
  • Store secret key in secure vault

Questions?​

See PHANTOM_SETUP.md for detailed explanation and troubleshooting.