TokenizeRWATemplate/projects/TokenizeRWATemplate-frontend/WEB3AUTH_INTEGRATION.md

Web3Auth Integration Guide

Overview

Web3Auth has been successfully integrated into your Algorand tokenization dApp. This allows users to sign in with Google (or other social logins) and automatically get an Algorand wallet generated from their Web3Auth credentials.

Installation

1. Install Dependencies

Run the following command in your TokenizeRWATemplate-frontend directory:

npm install @web3auth/modal @web3auth/base @web3auth/openlogin-adapter

2. Get Web3Auth Client ID

1. Go to Web3Auth Dashboard
2. Create a new application or use an existing one
3. Copy your Client ID
4. Add it to your .env file:

VITE_WEB3AUTH_CLIENT_ID=your_client_id_here

File Structure Created

src/
├── utils/
│   └── web3auth/
│       ├── web3authConfig.ts          # Web3Auth initialization and config
│       ├── algorandAdapter.ts         # Convert Web3Auth keys to Algorand format
│       └── web3authIntegration.ts     # Integration helpers for AlgorandClient
├── components/
│   ├── Web3AuthProvider.tsx           # React Context Provider
│   └── Web3AuthButton.tsx             # Connect/Disconnect button component
└── hooks/
    └── (useWeb3Auth exported from Web3AuthProvider)

Files Created

1. src/utils/web3auth/web3authConfig.ts

Initializes Web3Auth with:

• Google OAuth via OpenLogin adapter
• Algorand TestNet configuration (chainNamespace: OTHER)
• Sapphire DevNet for development
• Functions: initWeb3Auth(), getWeb3AuthProvider(), isWeb3AuthConnected(), etc.

2. src/utils/web3auth/algorandAdapter.ts

Converts Web3Auth keys to Algorand format:

• getAlgorandAccount(provider) - Extracts private key and converts to Algorand account
• createAlgorandSigner(secretKey) - Creates a signer for transactions
• Helper functions for validation and key derivation

3. src/utils/web3auth/web3authIntegration.ts

Integration utilities for AlgorandClient:

• createWeb3AuthSigner(account) - Drop-in signer for AlgorandClient
• Amount formatting and parsing utilities
• Transaction verification and analysis helpers
• Balance checking utilities

4. src/components/Web3AuthProvider.tsx

React Context Provider with:

• State management for Web3Auth and Algorand account
• login() / logout() functions
• useWeb3Auth() custom hook
• Automatic user info fetching from OAuth provider

5. src/components/Web3AuthButton.tsx

UI Component with:

• "Sign in with Google" button when disconnected
• Address display with dropdown menu when connected
• Profile picture, name, and email display
• Copy address and disconnect buttons
• Loading and error states

Updated Files

src/App.tsx

Wrapped the app with <Web3AuthProvider> to provide Web3Auth context throughout the application:

<Web3AuthProvider>
  <WalletProvider manager={walletManager}>{/* your routes */}</WalletProvider>
</Web3AuthProvider>

.env.template

Added:

VITE_WEB3AUTH_CLIENT_ID=""

Usage Examples

Basic Usage in Components

import { useWeb3Auth } from './components/Web3AuthProvider'

export function MyComponent() {
  const { isConnected, algorandAccount, login, logout } = useWeb3Auth()

  if (!isConnected) {
    return <button onClick={login}>Sign in with Google</button>
  }

  return (
    <div>
      <p>Connected: {algorandAccount?.address}</p>
      <button onClick={logout}>Disconnect</button>
    </div>
  )
}

Using with AlgorandClient

import { AlgorandClient } from '@algorandfoundation/algokit-utils'
import { createWeb3AuthSigner } from './utils/web3auth/web3authIntegration'
import { useWeb3Auth } from './components/Web3AuthProvider'

export function TokenizeAsset() {
  const { algorandAccount } = useWeb3Auth()

  if (!algorandAccount) {
    return <Web3AuthButton />
  }

  // Create signer from Web3Auth account
  const signer = createWeb3AuthSigner(algorandAccount)

  const algodConfig = getAlgodConfigFromViteEnvironment()
  const algorand = AlgorandClient.fromConfig({ algodConfig })

  const handleCreateAsset = async () => {
    try {
      const result = await algorand.send.assetCreate({
        sender: algorandAccount.address,
        signer: signer,
        total: BigInt(1000000),
        decimals: 6,
        assetName: 'My Token',
        unitName: 'MYT',
      })

      console.log('Asset created:', result.confirmation?.assetIndex)
    } catch (error) {
      console.error('Failed to create asset:', error)
    }
  }

  return <button onClick={handleCreateAsset}>Create Asset</button>
}

Add Web3AuthButton to Your UI

import Web3AuthButton from './components/Web3AuthButton'

export function Header() {
  return (
    <header>
      <h1>My Tokenization App</h1>
      <Web3AuthButton /> {/* Shows login/account dropdown */}
    </header>
  )
}

Access User Information

import { useWeb3Auth } from './components/Web3AuthProvider'

export function Profile() {
  const { userInfo, algorandAccount } = useWeb3Auth()

  if (!userInfo) return <p>Not logged in</p>

  return (
    <div>
      {userInfo.profileImage && <img src={userInfo.profileImage} alt="Profile" />}
      <p>Name: {userInfo.name}</p>
      <p>Email: {userInfo.email}</p>
      <p>Algorand Address: {algorandAccount?.address}</p>
    </div>
  )
}

Key Features

✅ Multi-Wallet Support

Web3Auth works alongside existing @txnlab/use-wallet-react:

• Users can use traditional wallets (Pera, Defly, etc.)
• OR sign in with Google/social logins
• Both options available simultaneously

✅ Automatic Wallet Generation

When users sign in with Google:

1. Web3Auth generates a secure private key
2. Private key is converted to Algorand mnemonic
3. Algorand account is derived automatically
4. No seed phrases to manage - ties to Google account

✅ TestNet Ready

By default, Web3Auth is configured for:

• Development: Sapphire DevNet
• Algorand Network: TestNet (https://testnet-api.algonode.cloud)
• Switch to SAPPHIRE network for production

✅ Full TypeScript Support

All files include complete TypeScript types:

• AlgorandAccountFromWeb3Auth interface
• Web3AuthContextType for context
• Proper error handling and null checks

✅ Integration with AlgorandClient

Drop-in replacement for transaction signing:

const signer = createWeb3AuthSigner(algorandAccount)

// Works with existing AlgorandClient code
await algorand.send.assetCreate({
  sender: algorandAccount.address,
  signer: signer,
  // ... other params
})

Configuration

Change Network (Development → Production)

In src/utils/web3auth/web3authConfig.ts:

// For development:
web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_DEVNET

// For production:
web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE

Also change in OpenloginAdapter:

network: 'sapphire_devnet' // → 'sapphire'

Add More OAuth Providers

In src/utils/web3auth/web3authConfig.ts, add to loginConfig:

loginConfig: {
  google: { ... },
  github: {
    name: 'GitHub Login',
    verifier: 'web3auth-github-demo',
    typeOfLogin: 'github',
    clientId: clientId,
  },
  // Add more providers...
}

Customize UI

In src/utils/web3auth/web3authConfig.ts, modify uiConfig:

uiConfig: {
  appName: 'Your App Name',
  appLogo: 'https://your-logo-url.png',
  primaryButtonColour: '#FF6B35',
  dark: false,
  theme: 'light',
}

Customize Button Styling

In src/components/Web3AuthButton.tsx, modify Tailwind classes:

// Change button colors, sizes, styles as needed
<button className="btn btn-sm btn-primary gap-2">{/* Your customizations */}</button>

Error Handling

All functions include error handling:

const { error } = useWeb3Auth()

if (error) {
  return <div className="alert alert-error">{error}</div>
}

Common errors:

• VITE_WEB3AUTH_CLIENT_ID is not configured - Add Client ID to .env
• Failed to derive Algorand account - Web3Auth provider issue
• Failed to connect Web3Auth provider - Network or service issue

Testing

Test Web3Auth Login Locally

1. Install dependencies: npm install
2. Add VITE_WEB3AUTH_CLIENT_ID to .env
3. Run dev server: npm run dev
4. Click "Sign in with Google" button
5. Complete Google OAuth flow
6. See Algorand address in dropdown

Test with TestNet

1. Ensure .env has TestNet configuration
2. Get TestNet tokens from Algorand Testnet Dispenser
3. Use Algorand address from Web3Auth
4. Create assets or transactions

Next Steps

1. Install dependencies: Run npm install command above
2. Get Web3Auth Client ID: Register at https://dashboard.web3auth.io
3. Add to .env: Set VITE_WEB3AUTH_CLIENT_ID in your .env file
4. Add to UI: Import and use Web3AuthButton in your header/navbar
5. Use in components: Import useWeb3Auth() to access account and signing capabilities
6. Test: Run npm run dev and test the login flow

Troubleshooting

Web3Auth Modal Not Appearing

• Check that VITE_WEB3AUTH_CLIENT_ID is set in .env
• Ensure Web3AuthProvider wraps your components
• Check browser console for initialization errors

Algorand Account Derivation Fails

• Verify provider is properly connected
• Check that private key extraction works in your environment
• Try logout and login again

Transactions Won't Sign

• Ensure algorandAccount is not null
• Verify signer is created from correct account
• Check transaction format is compatible with algosdk

Network Issues

• For LocalNet: Update RPC target in web3authConfig.ts
• For TestNet: Verify Algonode endpoints are accessible
• Check firewall/CORS settings if making cross-origin requests

Additional Resources

• Web3Auth Documentation
• Web3Auth Dashboard
• Algorand Developer Docs
• AlgoKit Utils
• algosdk.js

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review Web3Auth GitHub Issues
3. Consult Algorand Community Forums
4. Check browser console for detailed error messages