@lykhoyda/gelato-wallet-ui/LIMITATIONS.md

Production-ready React Smart components for Web3 wallet interfaces with Gelato SDK integration

# Known Limitations & Workarounds

This document outlines the current limitations of the `@lykhoyda/gelato-wallet-ui` library and provides workarounds where possible.

## Table of Contents

- [Authentication Constraints](#authentication-constraints)
- [Chain Support](#chain-support)
- [React Version Requirements](#react-version-requirements)
- [Bundle Size Considerations](#bundle-size-considerations)
- [SDK-Specific Limitations](#sdk-specific-limitations)

## Authentication Constraints

### ❌ Cannot Programmatically Open Wallet Modal

**Issue:** The Gelato Smart Wallet SDK does not expose methods to programmatically trigger the authentication modal. This is a security feature built into the underlying Dynamic.xyz integration.

**Impact:**

- Cannot create fully custom connect buttons
- Cannot trigger connection from other UI events
- Cannot implement auto-connect flows

**Required Pattern:**

```tsx
// ✅ CORRECT: Must use SDK's button wrapper
import { GelatoSmartWalletConnectButton } from '@lykhoyda/gelato-wallet-ui';

<GelatoSmartWalletConnectButton>
  <button>Connect</button>
</GelatoSmartWalletConnectButton>;

// ❌ WRONG: This will not open the modal
const { connect } = useGelatoWallet();
<button onClick={connect}>Connect</button>; // Won't work!
```

**Workarounds:**

1. **Style the inner button:** You can fully customize the button element inside `GelatoSmartWalletConnectButton`
2. **Use conditional rendering:** Show different UI based on connection state
3. **Wrap in your own component:** Create a wrapper that adds your logic around the SDK button

```tsx
// Workaround Example: Custom styled button
function CustomConnectButton() {
  const { isConnected } = useGelatoWallet();

  return (
    <GelatoSmartWalletConnectButton>
      <button className="your-custom-styles">
        {isConnected ? 'Disconnect' : 'Connect Wallet'}
      </button>
    </GelatoSmartWalletConnectButton>
  );
}
```

## Chain Support

### Network Support

**Default:** Ink Sepolia (Chain ID: 763373)

**Optional:** Add more networks via the `chains` prop (for example, Base Sepolia 84532, Sepolia 11155111). Gas sponsorship must be configured per chain.

**Setup Requirements:**

1. Obtain test tokens from faucets
2. Configure sponsorship on [Gelato Dashboard](https://app.gelato.network)
3. Optionally pass supported chains to the provider

```tsx
import { inkSepolia, baseSepolia, sepolia } from 'viem/chains';

<GelatoProvider
  config={{ sponsorApiKey, dynamicEnvironmentId }}
  chains={[inkSepolia, baseSepolia, sepolia]}
>
```

## React Version Requirements

### Requires React 19+

**Issue:** This library is built for React 19 and uses features not available in React 18.

**Not Compatible With:**

- React 18.x
- Next.js versions using React 18
- Create React App (until updated)

**Migration Path:**

```json
// package.json
{
  "dependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}
```

**If you cannot upgrade:**
Consider using the raw Gelato SDK directly with your own components.

## Bundle Size Considerations

### Large Dependencies

The library includes several large dependencies:

- Gelato Smart Wallet SDK (~200kb)
- Dynamic.xyz SDK (~150kb)
- Viem (~100kb)

**Total Bundle Impact:** ~500kb minified

**Optimization Strategies:**

1. **Tree shaking:** Import only needed components
2. **Code splitting:** Lazy load wallet features
3. **Dynamic imports:** Load SDK only when needed

```tsx
// Optimize with lazy loading
const WalletCard = lazy(() =>
  import('@lykhoyda/gelato-wallet-ui').then((module) => ({ default: module.WalletCard })),
);
```

## SDK-Specific Limitations

### 1. Manual Client Creation Fallback

**Issue:** When the SDK client isn't available, we attempt to create a manual client. This has limitations:

- No automatic provider updates
- May miss some SDK events
- Requires manual refresh for state changes

**Detection:**
Console warnings will appear when using fallback mode:

```
[GelatoWallet] Using manual client fallback - some features may be limited
```

### 2. Rate Limiting on Sponsored Transactions

**Issue:** Sponsored transactions are rate-limited per API key.

**Limits:**

- 10 transactions per minute per user
- 100 transactions per hour per API key

**Workaround:**
Implement ERC-20 payment fallback:

```tsx
const { mintSponsored, mintWithERC20 } = useMintToken();

try {
  await mintSponsored();
} catch (error) {
  if (error.message.includes('rate limit')) {
    // Fallback to ERC-20 payment
    await mintWithERC20('USDC');
  }
}
```

### 3. Account Resolution Timing

**Issue:** Account information may not be immediately available after connection.

**Symptoms:**

- `account` is null briefly after connection
- Balance queries fail initially

**Solution:**

```tsx
// Add retry logic
const { account } = useGelatoWallet();

useEffect(() => {
  if (!account) return;

  // Wait for account to be fully resolved
  const timer = setTimeout(() => {
    fetchBalances(account);
  }, 500);

  return () => clearTimeout(timer);
}, [account]);
```

### 4. Transaction Status Updates

**Issue:** Transaction status updates may be delayed or missed.

**Impact:**

- UI shows "pending" longer than expected
- Success status may not update

**Workaround:**
Implement polling for transaction status:

```tsx
const pollTransaction = async (hash: string, client: any) => {
  const maxAttempts = 30;
  for (let i = 0; i < maxAttempts; i++) {
    const receipt = await client.getTransactionReceipt({ hash });
    if (receipt) return receipt;
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
  throw new Error('Transaction timeout');
};
```

## Error Handling

### Common Errors and Solutions

| Error                                        | Cause               | Solution                                |
| -------------------------------------------- | ------------------- | --------------------------------------- |
| "Cannot read property 'client' of undefined" | SDK not initialized | Ensure GelatoProvider wraps your app    |
| "Sponsored function requires API key"        | Missing API key     | Pass `sponsorApiKey` to provider config |
| "User rejected the request"                  | User cancelled      | Handle gracefully in UI                 |
| "Insufficient funds"                         | No gas tokens       | Direct user to faucet                   |
| "Invalid chain ID"                           | Wrong network       | Switch to supported chain               |

## Debugging Tips

### Enable Debug Mode

Set environment variable to see detailed logs:

```bash
NEXT_PUBLIC_DEBUG_GELATO=true
```

### Check SDK State

```tsx
// Debug helper component
function DebugSDK() {
  const context = useGelatoSmartWalletProviderContext();

  useEffect(() => {
    console.log('SDK State:', {
      hasClient: !!context?.gelato?.client,
      account: context?.gelato?.client?.account,
      wagmi: context?.wagmi,
    });
  }, [context]);

  return null;
}
```

## Future Improvements

We're actively working on:

1. Mainnet support
2. Additional chain support
3. Reduced bundle size
4. Better error messages
5. Automatic retry logic
6. Enhanced TypeScript types

## Getting Help

If you encounter issues not covered here:

1. Check the [GitHub Issues](https://github.com/gelato-network/gelato-wallet-ui/issues)
2. Review the [Gelato Documentation](https://docs.gelato.network)
3. Join the [Gelato Discord](https://discord.gg/gelato)
4. Contact support at support@gelato.network

## Contributing

Found a workaround for a limitation? Please contribute:

1. Fork the repository
2. Add your solution to this document
3. Submit a pull request

---

_Last updated: January 2025_
_Library version: 2.x_