GlobalForce Wallet Plugin

A TypeScript/JavaScript wallet plugin for WharfKit that enables dApps to connect to GlobalForce Wallet through a Socket.IO-based wallet-connect-server. This plugin provides seamless integration with EOSIO blockchain networks and supports both mobile and desktop wallet interactions.

Features

• EOSIO Blockchain Support: Native integration with EOSIO-based networks
• Socket.IO Communication: Real-time bidirectional communication with wallet
• Mobile Deep Linking: Launch GlobalForce Wallet app directly from dApps
• QR Code Support: Easy wallet connection via QR codes on desktop
• Transaction Signing: Secure transaction signing with user approval flow
• WharfKit Integration: Built for the WharfKit session management framework

Installation

npm install @your-org/globalforce-wallet-plugin

Usage

Basic Setup

import { GlobalForceWalletPlugin } from '@your-org/globalforce-wallet-plugin';

const walletPlugin = new GlobalForceWalletPlugin({
  serverUrl: 'https://your-wallet-connect-server.com',
  timeout: 30000, // optional, defaults to 30000ms
  defaultChainId: '8a34ec7df1b8cd06ff4a8abbaa7cc50300823350cadc59ab296cb00d104d2b8f' // optional
});

Integration with WharfKit Session

import { Session } from '@wharfkit/session';
import { GlobalForceWalletPlugin } from '@your-org/globalforce-wallet-plugin';

const session = new Session({
  chain: 'eos', // or your EOSIO chain
  walletPlugin: new GlobalForceWalletPlugin({
    serverUrl: 'https://your-wallet-connect-server.com',
    timeout: 30000
  })
});

// Login with GlobalForce Wallet
const loginResult = await session.login();
console.log('Logged in as:', loginResult.actor);

Transaction Signing

// Using WharfKit Session
const action = {
  account: 'eosio.token',
  name: 'transfer',
  authorization: [{
    actor: 'youraccount',
    permission: 'active'
  }],
  data: {
    from: 'youraccount',
    to: 'recipient',
    quantity: '1.0000 EOS',
    memo: 'Transfer via GlobalForce Wallet'
  }
};

try {
  const result = await session.transact({ actions: [action] });
  console.log('Transaction successful:', result.transactionId);
} catch (error) {
  console.error('Transaction failed:', error.message);
}

Mobile Deep Linking

The plugin supports deep linking to launch the GlobalForce Wallet mobile app directly:

// Get the deep link URL for manual use
const deepLink = walletPlugin.getConnectionLink();
console.log('Deep link:', deepLink);
// Output: globalforcewallet://globalforce.io/app/wcs2?client_id=your-client-id

// The plugin automatically handles deep linking during login
// Users can tap "Launch Wallet" button or scan QR code

Advanced Configuration

const walletPlugin = new GlobalForceWalletPlugin({
  serverUrl: 'https://your-wallet-connect-server.com',
  clientId: 'custom-client-id', // optional, auto-generated if not provided
  timeout: 30000, // connection timeout in milliseconds
  defaultChainId: '8a34ec7df1b8cd06ff4a8abbaa7cc50300823350cadc59ab296cb00d104d2b8f' // EOS mainnet
});

Session Management

// Login establishes connection and retrieves user's account
const loginResponse = await session.login();
console.log('Account:', loginResponse.permissionLevel.actor);

// Logout and cleanup
await session.logout();

API Reference

GlobalForceWalletPlugin

Methods

• login(context: LoginContext): Promise<WalletPluginLoginResponse> - Authenticate user and establish wallet connection
• logout(): Promise<void> - Disconnect from wallet and cleanup session
• sign(resolved: ResolvedSigningRequest, context: TransactContext): Promise<WalletPluginSignResponse> - Sign transaction or other blockchain data
• connect(): Promise<void> - Establish Socket.IO connection to wallet-connect-server
• disconnect(): Promise<void> - Close Socket.IO connection
• getConnectionLink(): string - Generate deep link for mobile wallet app
• serialize(): any - Serialize plugin state for persistence

Configuration

interface GlobalForceWalletConfig extends WalletPluginConfig {
  serverUrl: string;        // URL of wallet-connect-server
  clientId?: string;        // Optional custom client ID (auto-generated if not provided)
  timeout?: number;         // Connection timeout in ms (default: 30000)
  defaultChainId?: string;  // Default EOSIO chain ID
}

Response Types

interface WalletPluginLoginResponse {
  chain: Checksum256;           // EOSIO chain identifier
  permissionLevel: PermissionLevel; // User's account and permission
}

interface WalletPluginSignResponse {
  resolved: ResolvedSigningRequest; // The original signing request with results
  signatures: Signature[];          // Array of transaction signatures
}

Transaction Request/Response (Internal)

interface TrxRequest {
  type: string;         // Always 'transaction_request'
  requestId: string;    // Unique identifier for the request
  actions: Action[];    // Array of EOSIO actions to execute
}

interface TrxResponse {
  type: string;         // Always 'transaction_response'
  error: string;        // Error message if failed
  success: boolean;     // Whether transaction succeeded
  requestId: string;    // Matches the original request ID
  signedTransaction: {
    signatures: string[];     // Transaction signatures
    packedTransaction: string; // Packed transaction hex
  };
}

Server Requirements

This plugin requires a running wallet-connect-server instance. The server should be configured with:

• Socket.IO v4+ support: Real-time bidirectional communication
• Dynamic namespaces: /dapp/{client_id} and /wallet/{client_id} for session isolation
• WebSocket transport: Enabled for optimal performance
• CORS configuration: Properly configured for your dApp domain
• Message handling: Support for wallet_connected and message events

See the wallet-connect-server documentation for detailed setup instructions.

Communication Flow

1. dApp Connection: Plugin connects to /dapp/{client_id} namespace
2. Wallet Discovery: QR code or deep link provides connection details
3. Wallet Connection: Wallet app connects to /wallet/{client_id} namespace
4. Session Establishment: Server facilitates handshake between dApp and wallet
5. Transaction Flow: dApp sends transaction request → wallet signs → response sent back

Examples

React Integration

import { useState } from 'react';
import { Session } from '@wharfkit/session';
import { GlobalForceWalletPlugin } from '@your-org/globalforce-wallet-plugin';

export function useGlobalForceWallet() {
  const [session, setSession] = useState<Session | null>(null);
  
  const login = async () => {
    const newSession = new Session({
      chain: 'eos',
      walletPlugin: new GlobalForceWalletPlugin({
        serverUrl: 'https://wallet-connect-server.example.com'
      })
    });
    
    const loginResult = await newSession.login();
    setSession(newSession);
    return loginResult;
  };

  const transact = async (actions: any[]) => {
    if (!session) throw new Error('Not logged in');
    return await session.transact({ actions });
  };

  const logout = async () => {
    if (session) {
      await session.logout();
      setSession(null);
    }
  };

  return { session, login, transact, logout };
}

Vue.js Composition API

import { ref } from 'vue';
import { Session } from '@wharfkit/session';
import { GlobalForceWalletPlugin } from '@your-org/globalforce-wallet-plugin';

export function useGlobalForceWallet() {
  const session = ref<Session | null>(null);
  const isLoggedIn = ref(false);

  const login = async () => {
    session.value = new Session({
      chain: 'eos',
      walletPlugin: new GlobalForceWalletPlugin({
        serverUrl: process.env.VUE_APP_WALLET_SERVER_URL
      })
    });

    const result = await session.value.login();
    isLoggedIn.value = true;
    return result;
  };

  return { session, isLoggedIn, login };
}

Troubleshooting

Common Issues

• Connection Timeout: Ensure wallet-connect-server is running and accessible
• Deep Link Not Working: Verify GlobalForce Wallet app is installed on mobile device
• Transaction Signing Fails: Check that wallet app is connected and user approved the transaction
• CORS Errors: Configure server to allow requests from your dApp domain

License

MIT