GuildPass Mobile

Secure, on-the-go access control and guild management.

Key Features • Getting Started • Architecture • Testing • Roadmap • Contributing

---

Part of the Adamantine-Guild project — a Web3 membership and token-gated community platform built for the open-source ecosystem.

📱 Experience the Protocol

GuildPass Mobile is the official gateway to the GuildPass ecosystem for iOS and Android. It empowers users to manage their digital memberships, verify on-chain roles, and unlock token-gated experiences directly from their mobile devices. Built with performance and security at its core, it leverages modern Web3 standards to provide a seamless user experience.

✨ Key Features

• 🛡️ Universal Membership: View all your active guild memberships and assigned roles in a unified dashboard.
• 📷 QR Access Check: Scan GuildPass access QR codes to instantly verify token-gated resource permissions.
• 🔍 Instant Verification: Execute real-time protocol checks for token-gated resources with zero friction.
• 🌐 Cross-Chain Support: Explore guild configurations and role requirements across supported EVM networks.
• ⚡ High Performance: Native-speed interactions powered by React Native and efficient server-state management.
• 🎨 Fluid Design: A beautiful, accessible UI built with NativeWind, optimized for both light and dark environments.

🚀 Getting Started

Prerequisites

• Node.js: 18.0 or higher
• Package Manager: pnpm (recommended) or npm
• Mobile Environment: Expo Go installed on your device, or configured iOS/Android simulators.

Installation

# Clone the repository
git clone https://github.com/Adamantine-Guild/guildpass-mobile.git
cd guildpass-mobile

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env
# Edit .env with your API URL and chain ID

Development

# Start the development server
pnpm start

# Launch on specific platforms
pnpm ios
pnpm android

🏗️ Architecture

The application is built on a robust, feature-driven foundation designed for long-term maintainability:

• Routing: Expo Router for type-safe, file-based navigation.
• State: Zustand for client state and TanStack Query for server synchronization.
• Styling: NativeWind for high-performance Tailwind CSS utility styling.
• SDK: Seamless integration with the core @guildpass/sdk.

Project structure

Path	Purpose
app/	Expo Router file-based pages and layouts
app/access-scanner.tsx	QR code scanner screen using expo-camera
src/features/access/	Access check hooks and QR payload validation
src/	Feature modules, hooks, stores, and services
docs/	Architecture and integration guides
tests/	Vitest unit tests

🧪 Testing

Unit & Integration Tests

# Run all tests (watch mode)
pnpm test

# Run tests once (CI mode)
pnpm test:run

# Type checking
pnpm typecheck

# Lint
pnpm lint

# Format
pnpm format

End-to-End Tests

GuildPass Mobile uses Maestro for E2E testing. Maestro provides deterministic, device-level testing for Expo apps.

Install Maestro:

# macOS/Linux
curl -Ls "https://get.maestro.mobile.dev" | bash

# Windows (using WSL)
wsl
curl -Ls "https://get.maestro.mobile.dev" | bash

Run E2E Tests:

# 1. Build the app for your platform
npx expo run:ios    # or npx expo run:android

# 2. Start development server (in separate terminal)
pnpm start

# 3. Run all E2E tests
maestro test .maestro/

# 4. Run specific test
maestro test .maestro/01-onboarding-to-profile.yaml

# 5. Interactive debugging
maestro studio

E2E Test Coverage:

• ✅ Onboarding to profile navigation
• ✅ Manual wallet entry
• ✅ Guild list and guild detail navigation
• ✅ Access check success and failure paths
• ✅ Reset app state

See .maestro/README.md for detailed E2E testing documentation, troubleshooting, and best practices.

🚀 Build & Release

GuildPass Mobile uses EAS Build with three distinct profiles:

Profile	Distribution	Channel	Use Case
development	Internal	development	Local dev & debug builds
preview	Internal	preview	QA / TestFlight / Beta
production	Store	production	App Store & Play Store

# Development build (APK / debug)
eas build --profile development --platform all

# Preview build (AAB / release for testers)
eas build --profile preview --platform all

# Production build (AAB / release for stores)
eas build --profile production --platform all

# Submit to stores
eas submit --profile production --platform ios
eas submit --profile production --platform android

See docs/release.md for the full release guide, environment matrix, and preflight checklist.

Environment Variables

Copy .env.example to .env and fill in your values. Environment variables prefixed with EXPO_PUBLIC_ are available at runtime. Sensitive values must be stored as EAS Secrets.

QR access check payload

QR access checks use a JSON payload encoded directly in the QR code:

{
  "type": "guildpass.access-check",
  "version": 1,
  "guildId": "guild_abc",
  "resourceId": "vip-door",
  "walletAddress": "0x1234567890123456789012345678901234567890",
  "expiresAt": "2026-06-23T12:05:00.000Z"
}

type, version, guildId, and resourceId are required. walletAddress and expiresAt are optional. Unsupported types or versions, malformed JSON, missing required fields, invalid wallet addresses, and expired payloads are rejected before the access check is submitted.

� Deep Linking

GuildPass Mobile supports deep linking, allowing external links to open specific screens within the app.

Supported Link Formats

Guild Detail

• Custom Scheme: guildpass://guild/{guildId}
• Universal Link: https://guildpass.xyz/guild/{guildId}
• Example: guildpass://guild/alpha-guild

Access Check

• Custom Scheme: guildpass://access-check?guildId={id}&resourceId={id}&walletAddress={address}
• Universal Link: https://guildpass.xyz/access-check?guildId={id}&resourceId={id}&walletAddress={address}
• Example: guildpass://access-check?guildId=alpha-guild&resourceId=secret-channel&walletAddress=0x1234...

Parameter Validation

• Guild detail links require a valid guildId
• Access check links require both guildId and resourceId parameters
• walletAddress is optional for access check; if not provided, the app uses the connected wallet
• Invalid or malformed links redirect to a user-friendly error screen

Cold Start Support

Deep links work when the app is cold-started (not already running). The app will launch and navigate to the appropriate screen.

🗺️ Roadmap

• Native Wallet Integration: Support for WalletConnect, MetaMask, and Coinbase Wallet.
• Smart Onboarding: Social login and embedded wallets for non-crypto native users.
• Push Notifications: Real-time alerts for role updates and access grants.
• QR Access Verification: Scan GuildPass QR codes to verify token-gated resource access from the mobile app.
• Offline Resilience: Advanced caching layer for viewing memberships without connectivity.

🤝 Contributing

We welcome contributions from the community! See CONTRIBUTING.md for the full guide.

1. Browse open issues tagged good first issue or help wanted.
2. Comment on the GitHub issue you'd like to work on.
3. Fork the repo, create a feature branch, implement your change, open a PR.

Maintainer contact

• Contact: cerealboxx123@gmail.com

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

Crafted with precision by the GuildPass team

guildpass.xyz