Skip to content
BranchesTags

Repository files navigation

Release

iOS Web3 Wallet Framework — Comprehensive Swift Web3 Toolkit for Secure DeFi

Hero Image

  • 🧭 A complete Web3 wallet integration framework for iOS
  • 💠 Built with Swift for deep iOS native experience
  • 🔒 Biometric authentication, secure storage, and hardware-wallet support
  • 🔗 Modular design with DeFi adapters for popular protocols
  • 🚀 Multi-chain support: Ethereum, Polygon, Arbitrum, Optimism, Avalanche, BSC, and more
  • 🧩 Extensible architecture for custom integrations and future chains

Welcome to the iOS Web3 Wallet Framework. This project provides a cohesive, production-grade toolkit that helps developers add wallet functionality, blockchain connectivity, and DeFi features to Swift-based iOS apps. The framework emphasizes security, speed, and a smooth developer experience. It offers ready-made building blocks for wallet creation, key management, transaction signing, on-device secure storage, biometric authentication, and DeFi protocol adapters.

This README explains how to use the framework, what you get out of the box, and how to extend it for real-world apps. The content is organized to help you go from a quick start to a production-ready integration, with best practices for security, performance, and reliability. If you are exploring Web3 wallet features for iOS, this guide aims to be your dependable companion.

Table of Contents

  • Overview and philosophy
  • Features and capabilities
  • Supported networks and protocols
  • Architecture and design
  • Getting started: prerequisites and installation
  • Quick start: create and connect a wallet
  • Core APIs and usage patterns
  • DeFi adapters: Aave, Compound, Uniswap, and more
  • Transaction signing and message signing
  • Biometrics, device security, and secure storage
  • Hardware wallet integration
  • Network interactions and providers
  • Security model and data protection
  • Testing strategy
  • CI/CD and quality gates
  • Customization and extension hooks
  • Code samples and guides
  • Release strategy and how to upgrade
  • Troubleshooting and common pitfalls
  • Roadmap and future directions
  • Community contribution guidelines
  • Licensing and attribution
  • Releases and downloads

Overview and philosophy The iOS Web3 Wallet Framework is designed with a pragmatic philosophy. It aims to be pragmatic and predictable, not flashy. The goal is to provide stable, well-documented building blocks that you can assemble into a strong wallet experience without wrestling with low-level cryptography or fragmented integration points across multiple DeFi protocols.

Key ideas:

  • Simplicity with depth: Use clear APIs for common tasks, while exposing hooks for advanced use cases.
  • Security by design: Make secure storage, key management, and signing operations a core, not an afterthought.
  • Interoperability: A consistent surface for multiple blockchains and DeFi protocols.
  • Extensibility: A plugin-like architecture to add new chains and adapters without rewriting existing code.
  • Developer experience: Rich samples, descriptive errors, and tests that reflect real-world usage.

Features and capabilities

  • Wallet lifecycle
    • Create or restore wallets with secure local storage
    • Manage keys with secure storage backends and biometric protections
    • Support for hardware wallets and secure off-device signing options
  • Key management and security
    • Encrypted key vaults with armor for offline and remote backups
    • Biometric authentication (Face ID / Touch ID) for key access
    • Fine-grained permission policies and session lifetimes
  • Signing and transactions
    • Signing transactions for multiple chains and EVM-compatible networks
    • Support for EIP-712 typed data signing, message signing, and raw transaction signing
    • Nonce and gas estimation integration, with safe-guarded signing flows
  • DeFi adapters and protocol integrations
    • Adapter templates for popular DeFi protocols
    • Ready-to-use adapters for Aave, Compound, Uniswap, and others
    • DeFi workflow patterns like lending, swapping, and yield farming
  • Multi-chain support
    • Ethereum, Polygon, Arbitrum, Optimism, Avalanche, Binance Smart Chain (BSC), and more
    • Chain-aware provider configuration and network switching
    • Cross-chain transaction flows and multi-network session management
  • Wallet integration and UX
    • Seamless onboarding and wallet connection flows
    • In-app wallet rendering and transparency for users
    • Transaction previews with estimated gas and slippage
  • Biometric and secure storage
    • Built-in biometric prompts for sensitive actions
    • Secure storage with hardware-backed keystore where available
    • Clear recovery and backup options with recommended practices
  • Hardware wallet support
    • Integration patterns for popular hardware wallets
    • Secure transport and signing flows for hardware devices
  • Developer ergonomics
    • Swift Package Manager ready
    • Clean, well-documented APIs
    • Extensible architecture with protocol-oriented design
  • Testing and reliability
    • Test harness with mocks and stubs for network and signing
    • CI-ready test suites and reproducible builds
    • Documentation-driven test examples to validate integration paths

Supported networks and protocols The framework targets a broad set of environments. It keeps a consistent signing and interaction model while allowing protocol-specific hooks for advanced behaviors.

  • Ethereum mainnet and testnets
  • Polygon (Matic)
  • Arbitrum One
  • Optimism
  • Avalanche C-Chain
  • Binance Smart Chain (BNB Smart Chain)
  • Other EVM-compatible networks
  • Aave, Compound lending protocols
  • Uniswap and other major DEXs
  • Broad DeFi toolchain support through adapters

This mix supports typical DeFi workflows: swap, lending, borrowing, liquidity provision, yield optimization, and more. The adapters are designed to be easily extended for new protocols as the ecosystem evolves.

Architecture and design The framework follows a modular, layered approach. Each layer has a clear responsibility, small surface area, and well-defined interfaces. This makes it easier to test, maintain, and extend.

  • Core layer
    • Wallet and key management
    • Secure vaults and storage abstractions
    • Biometric authentication plumbing
    • Network provider abstraction and network switching
  • Signer layer
    • Transaction signing engines
    • Message signing with EIP-712 support
    • Nonce and gas estimation strategies
  • DeFi adapters
    • Protocol adapters that implement a common interface
    • Protocol-specific logic isolated to adapters
    • Reusable components for approvals, allowances, and swaps
  • Provider and network layer
    • Abstracted provider that can talk to JSON-RPC endpoints
    • Caching and retry policies
    • Configurable network timeouts and backoff
  • Security layer
    • Encrypted storage, keychain usage, and data protection
    • Biometric prompts and session guards
  • Platform integration layer
    • iOS-specific UI scaffolding
    • App lifecycle integration and background task handling
    • Secure enclave considerations and device capabilities detection
  • Testing and mocks
    • Test doubles for networks and adapters
    • End-to-end test patterns and deterministic outcomes
  • Extension points
    • Protocols for adding new networks, wallets, and adapters
    • Hooks for custom UI workflows and user prompts
    • Plugins for alternate signing flows or external services

Getting started: prerequisites and installation Prerequisites

  • macOS with Xcode (recommended 14.x or newer for modern Swift tooling)
  • Swift 5.5+ compatible project
  • Basic knowledge of iOS app structure and Swift concurrency
  • Access to a development account if you plan to test on a real device
  • Understanding of Ethereum-based networks and gas concepts is helpful but not required for initial exploration

Installation The framework is designed for Swift Package Manager (SPM). This makes integration straightforward in Xcode projects.

Quick start: create and connect a wallet Note: The following steps illustrate a typical path to initialize the framework, enable biometric access, connect a wallet, and present a signing flow. The actual API names may vary slightly in your project, but the concepts remain consistent.

Core API surface and usage patterns The framework presents a clean, opinionated API surface with well-documented types. Here is a high-level map of typical APIs you will interact with.

  • WalletConfig
    • networks: [Network]
    • useBiometrics: Bool
    • storagePolicy: StoragePolicy
    • debugMode: Bool
  • Web3WalletManager
    • init(config: WalletConfig)
    • func connect(completion: @escaping (Result<Address, WalletError>) -> Void)
    • func disconnect()
    • func signTransaction(_ draft: TransactionDraft, completion: @escaping (Result<SignedTransaction, WalletError>) -> Void)
    • func broadcast(_ signedTx: SignedTransaction, completion: @escaping (Result<String, WalletError>) -> Void)
    • func signMessage(_ message: SignableMessage, completion: @escaping (Result<SignedMessage, WalletError>) -> Void)
    • func enrollBiometrics(completion: @escaping (Bool, WalletError?) -> Void)
  • Adapter protocol
    • protocol ProtocolAdapter
    • func prepare() -> AdapterPreparation
    • func performOperation(_ operation: ProtocolOperation, completion: @escaping (Result<AdapterResult, WalletError>) -> Void)
  • DeFi adapters
    • AaveAdapter, CompoundAdapter, UniswapAdapter
    • Each adapter supports common operations: approve, borrow/lend, swap, etc.
  • Security and storage
    • SecureStorage protocol with methods to save, read, and wipe secrets
    • Key management helpers and keystore abstraction
  • Network providers
    • NetworkProvider protocol with fetchBalance, estimateGas, getNonce, etc.
    • Network configuration and endpoints management

Code samples and usage patterns

DeFi adapters: patterns and extension points Adapters provide a consistent interface to interact with DeFi protocols. They isolate protocol-specific logic, offering a stable experience to your app while still allowing protocol-specific optimizations.

  • Common interface
    • prepare, approve, swap, borrow, lend, repay
    • fetchUserPosition, fetchRates, and governance hooks
  • How to extend
    • Create a new adapter by conforming to ProtocolAdapter
    • Implement prepare() to check preconditions
    • Implement operation methods for protocol actions
    • Provide demo flows and test data to verify integration
  • Example extension concept
    • Add a new protocol adapter for a lending protocol not yet covered
    • Provide a minimal test harness to verify key interactions
    • Document usage with common scenarios like supply, borrow, repay, and liquidations where applicable

Transaction signing and message signing in depth

  • Signers are designed to support both transaction signing and message signing
  • EIP-712 typed data signing is supported for structured data
  • Nonce and gas handling
    • The framework can fetch the current nonce and gas estimates automatically
    • It supports manual override when needed, with sane defaults
  • Signing flows
    • In-app signing with biometric protection
    • External signer flows via hardware wallets
    • Secure signing with ephemeral sessions to reduce exposure
  • Verification and replay protection
    • Nonce tracking and re-try safeguards
    • Replay-protected signing to reduce risk of double spends
  • Testing signing
    • Test vectors for common signing scenarios
    • Mock signer to simulate network responses

Biometric authentication and secure storage

  • Biometric prompts integrated into signing and sensitive actions
  • Secure storage backed by the device’s secure enclave or keychain
  • Key management policies
    • Keys are never exposed in plaintext
    • Access controls control read/write permissions
  • Recovery considerations
    • Guidance on backup and recovery of wallets
    • Safe import/export mechanisms that preserve security properties
  • User experience
    • Clear prompts for biometric enrollment
    • Optional passcode fallback for devices without biometrics

Hardware wallet integration

  • Safe integration patterns
    • Abstracted transport layer for USB or BLE connections
    • Device discovery and pairing flows
    • Signing on hardware devices with user prompts
  • Security considerations
    • Ensure user confirmation on the device for sensitive actions
    • Validate signatures on-device and on-server where applicable
  • UX considerations
    • Provide progress indicators during hardware signing
    • Show a clear transaction summary before signing

Network interactions and providers

  • Provider abstraction
    • Unified interface for balance, signing, and broadcast flows
    • Pluggable endpoints for different networks or test environments
  • Core provider capabilities
    • Balance inquiry, gas estimation, nonce retrieval
    • Transaction send and receipt handling
    • Event listening for contract events (where relevant)
  • Caching and synchronization
    • Local caches for balances and token metadata
    • Expiration policies to keep data fresh without excessive network pressure

Security model and data protection

  • Data at rest
    • Encrypted vaults for keys and secrets
    • Access controls for sensitive data
  • Data in transit
    • Secure channels for signing operations
    • Validation of signatures before broadcast
  • Threat modeling
    • Focus on reducing exposure during signing
    • Minimize the amount of sensitive data kept in memory
  • Best practices
    • Avoid long-lived sessions for signing
    • Implement revocation and account recovery processes

Testing strategy

  • Unit tests
    • Coverage for core APIs, adapters, and storage
    • Mock providers to simulate network conditions
  • Integration tests
    • End-to-end flows for wallet creation, signing, and broadcast
    • Real network tests in staging environments
  • Property-based tests
    • Validate invariants for signing and nonce management
  • Performance tests
    • Measure signing latency and network round-trips
    • Optimize for low memory footprints on devices with limited resources
  • Test data and fixtures
    • Use deterministic fixtures for predictable results
    • Isolate tests from real network dependencies where possible

CI/CD and quality gates

  • GitHub Actions workflows
    • Build and test on macOS runners
    • Linting, formatting, and static analysis
    • Snapshot tests and unit test coverage metrics
  • Versioning and releases
    • Semantic versioning with clear upgrade notes
    • Changelogs in releases to guide migration
  • Code quality
    • Enforce strict build settings and disable warnings-as-errors unless necessary
    • Documented API deprecation strategy with migration guides

Customization and extension points

  • How to customize
    • Override adapter behavior at runtime
    • Provide custom UI prompts for signing or approvals
    • Swap storage backends for different environments (debug vs production)
  • Extension hooks
    • Pre-signing hooks to validate inputs
    • Post-signing hooks to log actions securely
    • Hooks to integrate with other iOS frameworks (e.g., analytics or crash reporting) without coupling

Code samples and guides

  • Quick snippets
    • Wallet setup
    • Sign and broadcast flow
    • DeFi adapter usage for common cases
  • Full walkthrough projects
    • Sample iOS app showing wallet creation, connection, and a DeFi dex swap
    • Step-by-step instructions for testing on a local testnet
  • Troubleshooting
    • Common errors during connection and signing
    • How to inspect and resolve
    • Best practices to reduce flaky tests

Release notes and upgrade guidance

  • Release notes outline changes by version
    • Fixed issues, new adapters, performance improvements
    • Breaking changes and migration tips
  • Upgrade steps
    • How to upgrade the SPM dependency
    • How to migrate apps using older APIs to newer ones
    • Deprecation timelines and recommended alternatives

Releases and downloads

  • Access to the latest builds
  • How to use release assets
    • If you download a prebuilt framework, integrate it into your Xcode project as a binary
    • If you download a sample app, run it on a simulator to explore flows
    • For advanced teams, use the source as a reference to implement your own modules
  • Keeping up to date
    • Subscribe to releases to get notified about updates
    • Review release notes to learn about breaking changes, new adapters, and security improvements
    • Validate your app against new networks and protocol updates

Downloads and installation details

  • Retrieve and review assets
    • The Releases page contains assets for various platforms and use cases
    • Look for a packaged framework suitable for iOS apps
    • Read accompanying README or CHANGELOG included with the release for specifics
  • Installation steps
    • Add the framework via Swift Package Manager or as a binary artifact
    • Ensure your Xcode project sets the correct deployment target and Swift version
    • Link necessary system frameworks for networking, crypto, and security
  • Post-install validation
    • Build and run a small test app to verify wallet creation, connection, and signing
    • Validate that biometrics prompts are working as expected on device
    • Confirm DeFi adapters initialize correctly and can perform simulated operations

Topics and ecosystem tags

  • aave
  • arbitrum
  • avalanche
  • binance-smart-chain
  • biometric-authentication
  • blockchain
  • compound
  • cryptocurrency
  • defi
  • ethereum
  • hardware-wallet
  • ios
  • optimism
  • polygon
  • secure-storage
  • swift
  • transaction-signing
  • uniswap
  • wallet-integration
  • web3

Design philosophy and maintainability notes

  • Clean API design
    • Intentional naming and explicit types to reduce ambiguity
    • Documentation that stays close to the code to minimize drift
  • Reliability
    • Defensive programming patterns to reduce crashes
    • Clear error types and actionable messages
  • Performance
    • Efficient memory usage, especially for long-lived wallet sessions
    • Non-blocking network calls and concurrent operations where safe
  • Accessibility
    • Focus on accessible UI prompts and clear error feedback
    • Ensure that biometric prompts are screen-reader friendly and informative
  • Internationalization
    • Labels and messages can be localized without changing internal APIs
    • Strategy for adding translations that align with the app’s localization plan

Contributing and collaboration

  • How to contribute
    • Fork the repository and open a feature branch
    • Start with a small, well-scoped change that includes tests
    • Write tests for new features and edge cases
    • Update documentation to reflect API changes and usage patterns
  • Coding standards
    • Follow the project’s Swift coding conventions
    • Write clear, concise comments and doc blocks for public APIs
    • Keep functions small and responsibilities focused
  • Review process
    • Pull requests undergo code reviews focusing on correctness, API design, and test coverage
    • Be open to feedback and ready to provide clarifications or alternatives

Changelog and historical context

  • A historical log of changes, bug fixes, and new features
  • Useful for developers who need to migrate between versions
  • Includes migration notes where breaking changes exist
  • Helps teams plan integration work around releases and deprecations

Acknowledgments and credits

  • Community contributors who helped shape the framework
  • Tools, libraries, or services that the project relies on
  • Any external projects or inspirations for design patterns and APIs

License and usage terms

  • The framework is licensed under an open-source license suitable for both personal and commercial projects
  • Review the license file in the repository for details
  • Respect attribution requirements and contribution guidelines when using the code

Releases and downloads (revisited)

Gallery and visuals

  • Emojis and icons
  • Hero images from publicly available sources
  • Diagrams illustrating architecture and data flow
  • Screenshots showing common use-case flows such as onboarding, signing, and DeFi interactions

Developer tips and best practices

  • Start with a minimal, working example
  • Validate network connectivity and handle timeouts gracefully
  • Use biometric prompts for the most sensitive actions
  • Validate addresses, nonces, and gas estimates carefully before signing
  • Maintain a clean separation between UI and signing logic
  • Use adapters to decouple protocol-specific logic from core wallet features

Roadmap and future directions

  • Expand protocol adapters with new DeFi and lending platforms
  • Add more cross-chain capabilities and lighter-weight network adapters
  • Improve test coverage for edge cases in signing and approvals
  • Enhance developer tooling around mocks, fixtures, and CI pipelines
  • Integrate more robust analytics and error reporting with respect to user privacy

FAQ (frequently asked questions)

  • Is this framework suitable for production apps? Yes, it is designed to be production-ready with security-conscious defaults, a robust architecture, and test coverage.
  • Which networks are supported out of the box? Ethereum, Polygon, Arbitrum, Optimism, Avalanche, BSC, and other compatible networks.
  • Can I add my own DeFi adapter? Yes. The design supports custom adapters with a well-defined interface.
  • How is user data protected? The framework uses encrypted storage, biometric checks, and secure signing paths to minimize exposure.

Official releases and downloads

Appendix: quick glossary

  • Web3: A set of technologies that enable decentralized apps on the web, powered by blockchain networks
  • Wallet: A digital key store that enables signing transactions and managing assets
  • DeFi: Decentralized finance, a set of protocols that operate without central banks
  • EVM: Ethereum Virtual Machine, the runtime for executing smart contracts

Enduring principles for your project

  • Prioritize security and user trust
  • Build with clear, explicit APIs
  • Embrace modularity and extensibility
  • Document decisions and keep tests comprehensive
  • Validate behavior with real-world usage patterns

Release notes, upgrade guidance, and migration

  • When upgrading, review release notes and ensure compatibility with your app’s Swift version and Xcode settings
  • Migration paths will be documented in the release notes to ease adoption
  • Test all signing and network flows in a staging environment before deploying to production

Accessibility and inclusive design notes

  • Ensure all prompts have accessible labels and descriptions
  • Provide high-contrast visuals for critical actions
  • Localize prompts and error messages where applicable
  • Consider users who rely on assistive technologies when designing the onboarding flow

Privacy and data handling

  • Collect only what is necessary for wallet operation
  • Avoid exposing private keys or seeds in logs or network traces
  • Provide users with transparent controls over what is stored and how it is used

Appendix: troubleshooting quick reference

  • Connection issues
    • Verify network access and correct chain configuration
    • Check that biometric enrollment is complete and available
  • Signing failures
    • Confirm the wallet has permission to sign
    • Ensure the user agrees to the action on the user’s device or hardware wallet
  • Adapter failures
    • Confirm the protocol is supported for the chosen network
    • Validate contract addresses and token symbols
  • Performance concerns
    • Review caching strategies and network retry policies
    • Optimize gas estimation steps and avoid unnecessary re-signing

Community and support

  • Submit issues for bugs and feature requests
  • Join discussions around new adapters and network constraints
  • Share sample apps and implementation notes to help others learn

License and attribution

  • See the LICENSE file for the exact terms
  • Follow attribution guidelines when reusing parts of the code

Releases and downloads (final note)

About

🐙 iOS Web3 Wallet Framework for integrating Ethereum and major networks in Swift apps. Easy wallet connect and onboarding for mobile dApps.

Topics

aavearbitrumavalanchebiometric-authenticationblockchaincompoundcryptocurrencydefiethereumhardware-walletiosoptimismpolygonsecure-storageswifttransaction-signinguniswapweb3

Resources

Readme
MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages