User Guide

Welcome to BlockStar Cypher - your decentralized, end-to-end encrypted messaging app powered by Web3 and NFT domain identity.

Getting Started

Connecting Your Wallet

  1. Open BlockStar Cypher in your browser or mobile app
  2. Click "Connect Wallet"
  3. Select your wallet provider (MetaMask, WalletConnect, etc.)
  4. Approve the connection request in your wallet
  5. Sign the authentication message to verify ownership

Linking Your BlockStar NFT Domain

If you own a BlockStar NFT domain (e.g., @yourname):

  1. After connecting your wallet, you'll be prompted to select your domain
  2. Choose your preferred domain from the list
  3. Your @name will now be displayed instead of your wallet address
💡 Tip

Don't have a BlockStar domain? Visit domains.blockstar.site to mint one!

Your Profile & Identity

Viewing Your Profile

  1. Tap the Settings icon (gear) in the sidebar
  2. Your profile shows your @name, avatar, and wallet address

Updating Your Profile

Your profile information (avatar, banner, bio) is stored on the blockchain via your NFT domain:

  1. Go to Settings → "Edit Profile on BlockStar Domains"
  2. This opens the BlockStar Domains resolver page
  3. Update your profile picture, banner, or bio
  4. Save changes (requires a transaction)
  5. Return to Cypher and refresh to see updates

Profile Picture Not Showing?

  • Profile images are stored on IPFS and linked to your NFT domain
  • Make sure you've set a profile image on BlockStar Domains
  • Try refreshing the app or clearing cache

Contacts

Adding a Contact

By @name (Recommended)

  1. Tap the Add Contact button (+ icon)
  2. Enter their @name (e.g., @david or david)
  3. Optionally add a nickname
  4. Tap "Add Contact"

By Wallet Address

  1. Tap the Add Contact button
  2. Enter their full wallet address (0x...)
  3. Add a nickname to help identify them
  4. Tap "Add Contact"
⚠️ Important

Adding contacts by @name is recommended because it ensures their profile information persists even after clearing your cache.

Managing Contacts

  • Favorite: Tap the star icon to add to favorites
  • Edit: Tap the pencil icon to change their nickname
  • Message: Tap the message icon to start a chat
  • Remove: Tap the trash icon to remove the contact

Searching Contacts

Use the search bar to find contacts by:

  • @name
  • Nickname
  • Wallet address

Messaging

Starting a Conversation

  1. From the Contacts section, tap a contact
  2. Click "Send Message" or the message icon
  3. Type your message and press Enter or tap Send

Message Features

  • End-to-End Encryption: All messages are encrypted - only you and the recipient can read them
  • Read Receipts: See when your message has been delivered and read
  • Timestamps: Messages show when they were sent

Sending Files & Images

  1. Tap the attachment icon (📎) in the message input
  2. Select a file or image from your device
  3. The file will be encrypted and sent

Voice & Video Calls

Making a Call

  1. Open a conversation with a contact
  2. Tap the Phone icon for voice call or Video icon for video call
  3. Wait for them to answer

Receiving a Call

When someone calls you:

  1. An incoming call screen appears with their @name and avatar
  2. Tap Accept to answer or Decline to reject
  3. For video calls, your camera activates automatically

During a Call

  • Mute: Tap the microphone icon to mute/unmute
  • Speaker: Tap the speaker icon to switch between earpiece and speakerphone
  • Video: Tap the camera icon to turn video on/off
  • End Call: Tap the red phone icon to hang up

Call Audio Options

  • Earpiece Mode: Audio plays through your phone's earpiece (like a regular phone call)
  • Speaker Mode: Audio plays through your phone's speaker (for hands-free)

Mesh Network & Bluetooth

BlockStar Cypher includes mesh networking capabilities, allowing you to communicate even when traditional internet connectivity is unavailable - perfect for events, conferences, remote areas, or emergency situations.

📶

No Internet Needed

Communicate when WiFi and cellular are unavailable

🔗

Device-to-Device

Connect directly via Bluetooth or WiFi Direct

🌐

Multi-Hop Routing

Messages relay through nearby devices

🔒

Still Encrypted

End-to-end encryption maintained

How Mesh Networking Works

When you're at a crowded event, festival, or location without internet access, BlockStar Cypher can create a local mesh network using:

  • Bluetooth Low Energy (BLE): Short-range connections up to ~30 meters
  • WiFi Direct: Medium-range connections up to ~200 meters
  • Peer-to-Peer WiFi: Connect to other devices without a router

Enabling Mesh Mode

  1. Go to Settings → "Network"
  2. Toggle "Enable Mesh Networking" on
  3. Grant Bluetooth and Location permissions when prompted
  4. The app will automatically discover nearby BlockStar Cypher users
📍 Location Permission

Android requires location permission for Bluetooth scanning. This is an OS requirement - BlockStar Cypher does not track or store your location.

At Events & Conferences

Mesh networking is ideal for situations where many people are in one area but internet is congested or unavailable:

  • Music Festivals: Stay connected when cell towers are overloaded
  • Conferences: Message other attendees without relying on venue WiFi
  • Outdoor Events: Communicate in areas with no signal
  • Emergency Situations: Coordinate when infrastructure is down

Mesh Network Features

  • Automatic Discovery: Finds nearby BlockStar Cypher users automatically
  • Message Relay: Your message can hop through multiple devices to reach the recipient
  • Store & Forward: Messages queue and deliver when the recipient comes in range
  • Hybrid Mode: Seamlessly switches between internet and mesh as available

Mesh Network Indicators

  • Mesh icon (🔗) in header: Mesh networking is active
  • Peer count: Shows number of nearby devices connected
  • Message status: Shows if message sent via mesh vs internet
💡 Pro Tip

For best mesh coverage at an event, encourage others to use BlockStar Cypher too! More devices = stronger mesh network with greater range.

Battery Considerations

Mesh networking uses Bluetooth and WiFi scanning, which can increase battery usage. To optimize:

  • Only enable mesh mode when needed (no internet available)
  • Disable mesh mode when you have reliable internet
  • Keep your phone charged, especially at long events

Groups

Creating a Group

  1. In the sidebar, tap "New Group"
  2. Enter a group name
  3. Search and add members by @name or wallet address
  4. Tap "Create Group"

Group Features

  • Add Members: Group admins can add new members
  • Remove Members: Group admins can remove members
  • Leave Group: Any member can leave at any time
  • Group Calls: Start voice/video calls with all group members

Settings

Sounds & Ringtones

Customize your notification sounds:

  1. Go to Settings → "Sounds & Ringtones"
  2. Choose from:
    • Incoming Call Ringtone: Sound when someone calls you
    • Outgoing Call Tone: Sound while waiting for someone to answer
    • Message Sound: Notification for new messages
  3. Adjust volume sliders for calls and messages
  4. Tap the play button to preview sounds

Network Settings

  • Enable Mesh Networking: Allow device-to-device communication
  • Auto-switch Mode: Automatically use mesh when internet unavailable
  • Bluetooth Discovery: Allow other devices to find you

Notifications

  • Enable/disable push notifications
  • Customize notification preferences per conversation

Privacy

  • View your encryption keys
  • Manage blocked users
  • Control mesh network visibility

Troubleshooting

Profile & Identity Issues

"My contacts show wallet addresses instead of @names"

Cause: This happens when contacts were added by wallet address, or after clearing your browser cache.

Solutions:
  1. Re-add by @name: Remove the contact and add them again using their @name instead of wallet address
  2. Ask them to log in: If they log into BlockStar Cypher themselves, their @name will be stored in the system
  3. Refresh: Tap the refresh button in the Contacts section

"My profile picture isn't showing"

Solutions:
  1. Make sure you've set a profile picture on BlockStar Domains
  2. Go to Settings and tap "Edit Profile on BlockStar Domains" to verify
  3. Clear cache and refresh the app
  4. Wait a few minutes - IPFS images may take time to load

"Someone else's profile picture isn't showing"

Cause: They may not have set a profile picture, or it's still loading from IPFS.

Solutions:
  1. Tap the refresh button to reload profiles
  2. Wait a few moments for IPFS content to load
  3. Check if they have a profile picture set (ask them)

Connection Issues

"I can't connect my wallet"

Solutions:
  1. Make sure your wallet extension is installed and unlocked
  2. Try refreshing the page
  3. Check that you're on the correct network (BlockStar Mainnet)
  4. Try a different browser or clear browser cache
  5. Disable other wallet extensions that might conflict

"I'm getting disconnected frequently"

Solutions:
  1. Check your internet connection
  2. Try switching between WiFi and mobile data
  3. Close other apps using significant bandwidth
  4. Refresh the app
  5. Enable mesh networking as a backup connection method

"Messages aren't sending"

Solutions:
  1. Check your internet connection
  2. Make sure you're still logged in (wallet connected)
  3. Try refreshing the page
  4. Check if the recipient is a valid address
  5. Try enabling mesh networking if recipient is nearby

Call Issues

"The other person can't hear me"

Solutions:
  1. Check that your microphone isn't muted (mic icon should not be crossed out)
  2. Make sure you granted microphone permissions when prompted
  3. On mobile: Check your phone's app permissions for microphone access
  4. Try switching between speaker and earpiece mode
  5. Close and reopen the call

"I can't hear the other person"

Solutions:
  1. Check your volume settings
  2. Try switching between speaker and earpiece mode
  3. On mobile: Make sure Do Not Disturb is off
  4. Check if your phone is connected to Bluetooth (audio may route there)

"Video call shows black screen"

Solutions:
  1. Make sure you granted camera permissions
  2. Check that no other app is using your camera
  3. On mobile: Check app permissions for camera access
  4. Try turning video off and on again during the call

"Call quality is poor"

Solutions:
  1. Move to an area with better internet connection
  2. Switch from WiFi to mobile data or vice versa
  3. Close other apps using bandwidth
  4. Try turning off video for audio-only call

"Ringtone doesn't play for incoming calls"

Solutions:
  1. Check that your phone isn't on silent/vibrate mode
  2. Go to Settings → Sounds & Ringtones and verify volume isn't at zero
  3. On mobile: Check that notification permissions are granted
  4. Make sure the app is allowed to play sounds in background

Mesh Network Issues

"Mesh networking won't enable"

Solutions:
  1. Ensure Bluetooth is turned on in your device settings
  2. Grant location permission (required for Bluetooth scanning on Android)
  3. Make sure WiFi is enabled (even if not connected to a network)
  4. Restart the app after granting permissions

"Can't find nearby users"

Solutions:
  1. Make sure other users also have mesh networking enabled
  2. Move closer to other users (Bluetooth range is ~30 meters)
  3. Check that both devices have Bluetooth and WiFi enabled
  4. Try toggling mesh mode off and on
  5. Ensure the app is in foreground (some phones limit background Bluetooth)

"Messages aren't delivering over mesh"

Cause: The recipient may be out of range or their device isn't relaying properly.

Solutions:
  1. Check if the recipient is within mesh range
  2. Messages will queue and deliver when they come in range
  3. Ensure there are enough intermediate devices to relay (more users = better coverage)
  4. Try moving to a more central location at the event

"Battery draining quickly with mesh enabled"

Solutions:
  1. Only enable mesh when you need it (no internet available)
  2. Disable mesh when you have reliable internet connection
  3. Reduce screen brightness to compensate
  4. Bring a portable charger to events

Notification Issues

"I'm not receiving push notifications"

Solutions:
  1. Check your phone's notification settings for BlockStar Cypher
  2. Make sure notifications are enabled in app Settings
  3. On iOS: Check Settings → Notifications → BlockStar Cypher
  4. On Android: Check Settings → Apps → BlockStar Cypher → Notifications
  5. Make sure battery optimization isn't blocking the app

"Notifications are delayed"

Cause: This can happen due to battery optimization or poor connectivity.

Solutions:
  1. Disable battery optimization for BlockStar Cypher
  2. Keep the app open in background
  3. Check your internet connection

Data & Cache Issues

"My conversations disappeared"

Cause: Conversations are stored locally and may be lost if you clear browser data.

Solutions:
  1. Check if you're logged into the same wallet
  2. Old conversations may need to sync from the server
  3. Try refreshing multiple times
  4. Check if you accidentally hid the conversation

"How do I clear my cache?"

If you need to clear cache to resolve issues:

Browser:

  1. Open Developer Tools (F12 or right-click → Inspect)
  2. Go to Application → Storage
  3. Click "Clear site data"
  4. Refresh the page and log in again

Mobile App:

  1. Go to your phone's Settings
  2. Find BlockStar Cypher in Apps
  3. Tap "Clear Cache" (not "Clear Data")
  4. Reopen the app
⚠️ Warning

Clearing data (not cache) may delete local messages that haven't synced.

Mobile-Specific Issues

"The app is slow on my phone"

Solutions:
  1. Close other apps running in background
  2. Restart the app
  3. Make sure you have enough storage space
  4. Update to the latest version of the app

"Keyboard covers the message input"

Solutions:
  1. Scroll down to see the input field
  2. Try rotating your phone to landscape mode
  3. Close the keyboard and tap the input field again

"Touch targets are too small"

Solutions:
  1. Try using the app in landscape mode for larger buttons
  2. Use the main action buttons rather than small icons
  3. Zoom in using accessibility settings if needed

Getting More Help

If you're still experiencing issues:

  1. Check for Updates: Make sure you're using the latest version
  2. Report a Bug: Use the feedback option in Settings
  3. Community Support: Join our community at BlockStar.chat
  4. Contact Support: Email support@blockstar.world

Tips & Best Practices

Security Tips

  • Never share your wallet seed phrase or private key
  • Verify @names before sending sensitive information
  • Log out when using shared devices
  • Keep your wallet software updated

Best Experience

  • Add contacts by @name for reliable profile display
  • Set a profile picture on BlockStar Domains
  • Enable notifications for incoming calls
  • Use WiFi for video calls when possible
  • Keep the app updated for latest features and fixes

For Events & Offline Use

  • Enable mesh networking before losing internet connection
  • Encourage others at the event to use BlockStar Cypher
  • Keep your phone charged - bring a portable charger
  • Add contacts before the event while you have internet
  • Test mesh mode with friends before you need it