# {{projectName}}

SBC + Turnkey fullstack example with embedded wallets and gasless transactions.

## Features

- ✅ **Backend Architecture**: Express server handling Turnkey sub-org creation
- ✅ **Passkey Authentication**: Users create wallets with biometric auth (Face ID/Touch ID)
- ✅ **Wallet Authentication**: Connect with MetaMask/Coinbase Wallet as alternative to passkeys
- ✅ **Embedded Wallets**: Non-custodial wallets managed by Turnkey
- ✅ **Smart Accounts**: ERC-4337 account abstraction with SBC paymaster
- ✅ **Gasless Transactions**: All gas fees sponsored by SBC
- ✅ **Account History**: Never lose access to accounts - all accounts saved and switchable

## Prerequisites

Before you begin, you need:

1. **SBC API Key**: Get from https://dashboard.stablecoin.xyz
2. **Turnkey Organization + API Keys**: Get from https://app.turnkey.com

### Getting Turnkey API Keys

1. Go to https://app.turnkey.com and sign up
2. Create a new organization (or use existing)
3. Navigate to **Settings** → **API Keys**
4. Click **"Create API Key"**
5. **Save both keys securely**:
   - Copy the **API Public Key**
   - Copy the **API Private Key** (shown only once!)
6. Copy your **Organization ID** from Settings

## Quick Start

### 1. Install Dependencies

```bash
npm install
# or
pnpm install
```

### 2. Configure Environment Variables

Edit the `.env` file that was created for you:

```bash
# SBC Configuration
VITE_SBC_API_KEY=your_sbc_api_key_here

# Turnkey Frontend (Public - safe for browser)
VITE_TURNKEY_API_BASE_URL=https://api.turnkey.com
VITE_TURNKEY_RPID=localhost

# Turnkey Backend (Secret - never expose to frontend!)
TURNKEY_API_BASE_URL=https://api.turnkey.com
TURNKEY_ORGANIZATION_ID=your_turnkey_org_id_here
TURNKEY_API_PUBLIC_KEY=your_turnkey_public_key_here
TURNKEY_API_PRIVATE_KEY=your_turnkey_private_key_here

# Backend Server
PORT=3001
VITE_BACKEND_URL=http://localhost:3001
```

### 3. Run the Application

**Option A: Run both frontend and backend together (recommended)**

```bash
npm run dev:fullstack
```

This starts:
- Backend server on `http://localhost:3001`
- Frontend on `http://localhost:5173`

**Option B: Run separately**

```bash
# Terminal 1 - Backend
npm run dev:backend

# Terminal 2 - Frontend
npm run dev
```

## How It Works

### Authentication Flows

#### Passkey Flow (Biometric)
1. User clicks "Continue with Passkey"
2. Browser creates passkey via WebAuthn (Face ID/Touch ID)
3. Frontend → Backend: `POST /api/create-sub-org` with attestation
4. Backend → Turnkey: Creates sub-org + Turnkey-managed wallet
5. User signs transactions with biometric auth

#### Wallet Flow (MetaMask/Coinbase)
1. User clicks "Connect Wallet"
2. MetaMask prompts for connection + signature
3. Frontend derives public key from signature
4. Frontend → Backend: `POST /api/create-sub-org-with-wallet` with public key
5. Backend → Turnkey: Creates sub-org (uses user's wallet as owner)
6. User signs transactions with their connected wallet

### Transaction Flow

1. User initiates transaction (e.g., "Send 1 SBC")
2. Frontend builds transaction via SBC App Kit
3. User signs transaction:
   - **Passkey**: Biometric prompt (Face ID/Touch ID)
   - **Wallet**: MetaMask/Coinbase popup
4. SBC paymaster sponsors all gas fees
5. Transaction executes on-chain via ERC-4337

## Project Structure

```
{{projectName}}/
├── server/           # Backend Express server
│   └── index.ts      # Turnkey API endpoints
├── src/              # Frontend React app
│   ├── App.tsx       # Main app component
│   ├── main.tsx      # Entry point
│   └── index.css     # Styles
├── public/           # Static assets
├── .env              # Environment variables (do not commit!)
└── package.json      # Dependencies and scripts
```

## Available Scripts

- `npm run dev` - Start frontend development server
- `npm run dev:backend` - Start backend server with hot reload
- `npm run dev:fullstack` - Run both frontend and backend concurrently
- `npm run build` - Build for production
- `npm run preview` - Preview production build

## Security Notes

⚠️ **IMPORTANT**: Never expose Turnkey API keys to the frontend!

- API keys stay on the backend only
- Frontend uses passkeys for user authentication
- Each user gets their own isolated sub-organization

## Production Deployment

### Backend Deployment
Deploy the Express server to:
- Railway, Render, Fly.io (Node.js)
- Vercel, Netlify (Serverless functions)
- AWS Lambda, Google Cloud Functions

### Frontend Deployment
Deploy the Vite app to:
- Vercel, Netlify, CloudFlare Pages
- Any static hosting service

### Environment Variables

**Frontend (.env):**
```bash
VITE_SBC_API_KEY=prod_key_here
VITE_TURNKEY_API_BASE_URL=https://api.turnkey.com
VITE_TURNKEY_RPID=yourdomain.com  # Your production domain
VITE_BACKEND_URL=https://your-backend.com
```

**Backend (.env):**
```bash
TURNKEY_API_BASE_URL=https://api.turnkey.com
TURNKEY_ORGANIZATION_ID=prod_org_id
TURNKEY_API_PUBLIC_KEY=prod_public_key
TURNKEY_API_PRIVATE_KEY=prod_private_key
PORT=3001
```

## Troubleshooting

### "Failed to create sub-org"
- Check backend logs for detailed error
- Verify `TURNKEY_API_PUBLIC_KEY` and `TURNKEY_API_PRIVATE_KEY` are correct
- Ensure `TURNKEY_ORGANIZATION_ID` matches your Turnkey org

### "Network Error" when signing up
- Make sure backend is running (`npm run dev:backend`)
- Check `VITE_BACKEND_URL` points to correct backend URL
- Verify CORS is configured (backend allows frontend origin)

### Passkey creation fails
- Use HTTPS in production (passkeys require secure context)
- For localhost: use `http://localhost` (not `127.0.0.1`)
- Check `VITE_TURNKEY_RPID` matches your domain

## Resources

- [Turnkey Documentation](https://docs.turnkey.com)
- [Turnkey Dashboard](https://app.turnkey.com)
- [SBC App Kit Docs](https://docs.stablecoin.xyz)
- [Turnkey SDK GitHub](https://github.com/tkhq/sdk)

## License

MIT