Introduction

​

Key Features

​

How OAuth Wallets Work

1. User authenticates with Google, Apple, or Magic Link
2. Provider issues JWT token with user identity (sub claim)
3. Wallet address derived deterministically: addressSeed = Poseidon(sub, salt) → contract address
4. Ephemeral session key generated for transaction signing (~24 hour lifetime)
5. Nonce computed: Poseidon(eph_pubkey_lo, eph_pubkey_hi, max_block, randomness) — embedded in JWT
6. First transaction deploys account + registers session key via on-chain JWT verification
7. All transactions signed automatically with session key — no prompts needed

[!NOTE] Your wallet address is computed from your OAuth identity. There are no private keys to manage — your Google or Apple account IS your wallet.

​

Choose Your Platform

​

Authentication Methods

• Google OAuth: Login with Google account
• Apple OAuth: Login with Apple ID
• Magic Link: Passwordless email login

​

Quick Example

import { CavosProvider, useCavos } from '@cavos/react';

function App() {
  return (
    <CavosProvider 
      config={{ 
        appId: 'your-app-id',
        session: {
          defaultPolicy: {
            allowedContracts: ['0x049d...'],
            spendingLimits: [{ token: '0x049d...', limit: 10n * 10n**18n }],
            maxCallsPerTx: 10
          }
        }
      }}
    >
      <WalletDemo />
    </CavosProvider>
  );
}

function WalletDemo() {
  const { login, sendMagicLink, address, execute, isAuthenticated } = useCavos();

  if (!isAuthenticated || !address) {
    return (
      <div>
        <button onClick={() => login('google')}>Login with Google</button>
        <button onClick={() => login('apple')}>Login with Apple</button>
        <button onClick={() => sendMagicLink('user@example.com')}>
          Send Magic Link
        </button>
      </div>
    );
  }

  // Transactions are signed automatically with session key
  const handleTransfer = async () => {
    const txHash = await execute({
      contractAddress: '0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7',
      entrypoint: 'transfer',
      calldata: ['0x...recipient', '1000000000000000000', '0'],
    });
    console.log('Transaction hash:', txHash);
  };

  return (
    <div>
      <p>Connected: {address}</p>
      <button onClick={handleTransfer}>Send Transfer (Gasless)</button>
    </div>
  );
}

​

How It Works Under the Hood

1. SDK generates session key and computes nonce (Poseidon of pubkey + max_block + randomness)
2. After OAuth, JWT contains that nonce in its nonce claim
3. SDK submits calldata including the JWT bytes and Garaga RSA-2048 hint (≈864 felt252 values)
4. Account contract deploys itself via AVNU Paymaster (gasless)
5. Contract fetches the RSA public key from the on-chain JWKS registry (managed by Argus)
6. Garaga’s is_valid_rsa2048_sha256_signature verifies the JWT RSA-2048 signature (~11.8M gas)
7. Session key is registered; transaction executes

1. SDK signs with session key (lightweight signature)
2. No JWT needed - key already registered
3. Much cheaper gas cost
4. Ephemeral keys auto-renew when they expire

​

Key Benefits