Zetrix Connect Wallet SDK

A Flutter package for integrating Zetrix blockchain wallet connectivity and operations.

Features

Wallet Connection: Connect to Zetrix wallets via WebSocket
Blockchain Operations: Interact with Zetrix blockchain
QR Code Display: Built-in QR code dialog and custom QR code UI support
- Ready-to-use built-in QR dialog
- Custom branded QR code UI with callback support
Secure Storage: Store session data securely using platform-specific secure storage
Device Detection: Detect device information for platform-specific behavior
Cryptographic Utilities: Hash functions and cryptographic operations
App Linking: Launch external wallet applications

Getting Started

Prerequisites

Requirement	Minimum Version	Recommended Version
Flutter SDK	^3.0.0	^3.16.0
Dart SDK	^3.10.1	^3.10.1+
Android	Android 5.0 (API 21)	Android 12+ (API 31+)
iOS	iOS 11.0+	iOS 13.0+

Platform-Specific Requirements:

Android:

Android SDK 21+
Gradle 7.0+
AndroidX enabled

iOS:

iOS 11.0+
CocoaPods 1.9.0+

Installation

Via Pub.dev (Recommended)

Visit the package on pub.dev for the latest version and additional information.

Add this to your package's pubspec.yaml file:

dependencies:
  zetrix_connect_wallet_sdk: ^1.0.0

Then run:

flutter pub get

Android Configuration

Add the following permissions to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

For secure storage, ensure your app has the correct namespace in android/app/build.gradle:

android {
    namespace "com.example.your_app"
    // ...
}

Usage

Basic Wallet Connection

import 'package:zetrix_connect_wallet_sdk/zetrix_connect_wallet_sdk.dart';

void main() async {
  // Initialize wallet connection
  final walletConnect = ZetrixWalletConnect();
  
  // Connect to wallet
  await walletConnect.connect();
  
  // Get session ID
  final sessionId = await StorageUtils.getSessionId();
  print('Session ID: $sessionId');
}

Blockchain Operations

import 'package:zetrix_connect_wallet_sdk/zetrix_connect_wallet_sdk.dart';

void performTransaction() {
  final chainSdk = ChainSDK();
  
  // Perform blockchain operations
  chainSdk.someOperation();
}

QR Code Display

The SDK supports two QR code display modes:

1. Built-in QR Code UI (Default)

The SDK provides a ready-to-use QR code dialog with a clean, simple design:

import 'package:zetrix_connect_wallet_sdk/zetrix_connect_wallet_sdk.dart';

// Initialize with built-in QR UI
final walletConnect = ZetrixWalletConnect(
  testnet: false,
  qrcode: true,
  appType: 'zetrix',
);

// Connect and authenticate
await walletConnect.connect();
await walletConnect.auth(context);

2. Custom QR Code UI

Create your own branded QR code display with full control over styling and behavior. The SDK provides the QR data via a callback, and you handle the UI:

import 'package:zetrix_connect_wallet_sdk/zetrix_connect_wallet_sdk.dart';
import 'package:qr_flutter/qr_flutter.dart';

class MyApp extends StatefulWidget {
  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  late ZetrixWalletConnect walletConnect;

  @override
  void initState() {
    super.initState();

    // Initialize with custom QR UI
    walletConnect = ZetrixWalletConnect(
      testnet: false,
      qrcode: true,
      appType: 'zetrix',
      isCustomQrUi: true,        // Enable custom QR UI
      qrDataCallback: (qrContent) {
        // Called when QR data is ready
        _showCustomQrDialog(qrContent);
      },
    );
  }

  void _showCustomQrDialog(String qrContent) {
    showDialog(
      context: context,
      barrierDismissible: false,
      builder: (context) => Dialog(
        child: Padding(
          padding: const EdgeInsets.all(24),
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              Text('Scan with Wallet App'),
              SizedBox(height: 20),
              // Display QR code using qr_flutter package
              QrImageView(
                data: qrContent,
                version: QrVersions.auto,
                size: 220.0,
              ),
              SizedBox(height: 20),
              ElevatedButton(
                onPressed: () => Navigator.pop(context),
                child: Text('Cancel'),
              ),
            ],
          ),
        ),
      ),
    );
  }

  Future<void> authenticate() async {
    await walletConnect.connect();
    final result = await walletConnect.auth(context);

    if (result['code'] == 0) {
      // Close custom QR dialog
      Navigator.of(context).pop();
      // Authentication successful
      print('Authenticated: ${result['data']['address']}');
    }
  }
}

QR Data Format:

{rms}&{sessionId}&{type}

Example: abc123token&sess456&H5_BIND

Where:

rms: Server token for QR validation
sessionId: Unique session identifier
type: Operation type (e.g., H5_BIND, H5_BIND_AND_SIGN_MESSAGE)

Key Points:

Set isCustomQrUi: true to enable custom UI mode
Provide qrDataCallback to receive QR data
You control the dialog styling and lifecycle
Close your custom dialog when authentication completes
Works with both auth() and authAndSignMessage()

Live Example:

The example app includes an interactive toggle switch that lets you switch between built-in and custom QR UI modes on the fly. Run the example to see both implementations in action:

cd example
flutter run

Toggle the "Custom QR Code UI" switch to compare both modes.

Secure Storage

import 'package:zetrix_connect_wallet_sdk/zetrix_connect_wallet_sdk.dart';

void storeData() async {
  await StorageUtils.setAuthData('key', 'value');
  final data = await StorageUtils.getAuthData('key');
  print('Stored data: $data');
}

Device Information

import 'package:zetrix_connect_wallet_sdk/zetrix_connect_wallet_sdk.dart';

void getDeviceInfo() async {
  final deviceInfo = await DeviceUtils.getDeviceInfo();
  print('Device: ${deviceInfo['model']}');
}

Logging Configuration

The SDK includes a built-in logging system that can be configured to control log verbosity. Initialize the logger before creating your ZetrixWalletConnect instance:

import 'package:logging/logging.dart';
import 'package:zetrix_connect_wallet_sdk/zetrix_connect_wallet_sdk.dart';

void main() {
  // Initialize logger with desired log level
  ZetrixLogger.initialize(
    level: Level.INFO,       // Control log verbosity
    enableLogging: true,     // Enable/disable all logging
  );

  runApp(MyApp());
}

Available Log Levels (from most to least verbose):

Level.ALL - Show all logs (most verbose)
Level.FINE - Debug level logs
Level.INFO - Informational messages (default)
Level.WARNING - Warning messages only
Level.SEVERE - Error messages only
Level.OFF - Disable all logging

Recommendations:

Development: Use Level.ALL or Level.FINE for detailed debugging
Production: Use Level.WARNING or Level.SEVERE to minimize log noise
Testing: Use Level.INFO for balanced visibility

The SDK logs important events such as:

Wallet connection status
Authentication results
Transaction operations
WebSocket communication
Error conditions

Architecture

This package follows a modular architecture with the following structure:

src/core/: Core wallet connection and WebSocket management
src/blockchain/: Blockchain interaction utilities
src/utils/: Utility functions for crypto, storage, device detection
src/constants/: Application constants
src/ui/: UI components like QR code display
src/navigation/: App linking and navigation utilities

For detailed architecture information, see ARCHITECTURE.md.

Example App

The included example app demonstrates all SDK features with an interactive UI:

Custom QR Toggle: Switch between built-in and custom QR UI modes on the fly
Complete SDK Integration: All wallet operations (connect, auth, sign, transactions)
Custom QR Implementation: Reference implementation for custom branded QR dialogs
Real-time Testing: Test both QR modes without changing code

Run the example:

cd example
flutter run

Documentation & Support

API Reference - Complete API documentation for all classes and methods
Architecture Guide - System architecture and design patterns
Pub.dev Package - Latest version, changelog, and API docs

License

This project is licensed under the MIT License - see the LICENSE file for details.