create-sbc-app 0.3.1 → 0.4.0

package/README.md

@@ -33,7 +33,7 @@ Arguments:
 
 Options:
   -V, --version           output the version number
-  -t, --template <type>   Template to use: react, react-dynamic, or react-para
+  -t, --template <type>   Template to use: react, react-dynamic, react-para, or react-turnkey
   -c, --chain <chain>     Chain to use: baseSepolia, base, or radiusTestnet
   --api-key <apiKey>      Your SBC API key for immediate configuration
   --wallet <wallet>       Wallet integration (not yet implemented)
@@ -44,16 +44,18 @@ Examples:
   $ npx create-sbc-app my-app --template react --chain radiusTestnet
   $ npx create-sbc-app my-app --template react-dynamic --chain base
   $ npx create-sbc-app my-app --template react-para --api-key your-key
+  $ npx create-sbc-app my-app --template react-turnkey --chain base
 
 Available Templates:
   - react           React + Vite template with SBC integration
   - react-dynamic   React + Vite with Dynamic wallet integration
   - react-para      React + Vite with Para wallet integration
+  - react-turnkey   React + Vite + Express backend with Turnkey embedded wallets
 
 Available Chains:
   - baseSepolia     Base Sepolia testnet (default)
   - base            Base mainnet
-  - radiusTestnet   Radius testnet (react template only)
+  - radiusTestnet   Radius testnet (react template only - not supported by Dynamic, Para, or Turnkey)
 ```
 
 ## ✨ Features
@@ -142,6 +144,34 @@ npx create-sbc-app my-app --template react-para
 
 **Additional Requirements:** Para API Key from [Para](https://para.xyz/)
 
+### React + Turnkey Template
+
+**Best for:** Production applications requiring embedded wallets with biometric authentication and backend infrastructure
+
+```bash
+npx create-sbc-app my-app --template react-turnkey
+```
+
+**Supported Chains:** Base Sepolia, Base (Radius Testnet not supported)
+
+**Features:**
+- Turnkey embedded wallet integration with passkey authentication
+- Express backend server for secure Turnkey API operations
+- Two authentication methods: biometric passkeys (Face ID/Touch ID) or wallet connection (MetaMask/Coinbase)
+- Account history and multi-account management
+- Full-stack development with `dev:fullstack` script
+- ERC-4337 smart accounts with gasless transactions
+- All standard SBC features
+
+**Additional Requirements:**
+- Turnkey Organization ID and API Keys from [Turnkey Dashboard](https://app.turnkey.com)
+- Backend deployment for production use (Railway, Render, Vercel, etc.)
+
+**Architecture:**
+- Frontend: React + Vite (port 5173)
+- Backend: Express server (port 3001)
+- Runs both services concurrently with `npm run dev:fullstack`
+
 ## 📝 Configuration
 
 ### Environment Variables

package/bin/cli.js

@@ -10,9 +10,9 @@ const program = new Command();
 program
     .name('create-sbc-app')
     .description('Create a new SBC App Kit project with an opinionated template')
-    .version('0.2.0')
+    .version('0.4.0')
     .argument('[project-directory]', 'Directory to create the new app in')
-    .option('-t, --template <template>', 'Template to use: react, react-dynamic, or react-para')
+    .option('-t, --template <template>', 'Template to use: react, react-dynamic, react-para, or react-turnkey')
     .option('-c, --chain <chain>', 'Chain to use: baseSepolia, base, or radiusTestnet')
     .option('--api-key <apiKey>', 'Your SBC API key for immediate configuration')
     .option('--wallet <wallet>', 'Wallet integration (not yet implemented)')
@@ -26,6 +26,7 @@ Available Templates:
   - react           React + Vite template with SBC integration
   - react-dynamic   React + Vite with Dynamic wallet integration
   - react-para      React + Vite with Para wallet integration
+  - react-turnkey   React + Vite + Express backend with Turnkey embedded wallets
 
 Available Chains:
   - baseSepolia     Base Sepolia testnet (default)
@@ -40,7 +41,8 @@ Available Chains:
     const templateChoices = [
         { title: 'React', value: 'react' },
         { title: 'React (Dynamic wallet)', value: 'react-dynamic' },
-        { title: 'React (Para wallet)', value: 'react-para' }
+        { title: 'React (Para wallet)', value: 'react-para' },
+        { title: 'React (Turnkey embedded wallet + Backend)', value: 'react-turnkey' }
     ];
     const chainChoices = [
         { title: 'Base Sepolia (testnet)', value: 'baseSepolia' },
@@ -62,7 +64,7 @@ Available Chains:
         projectDir = res.dir.trim();
     }
     // Use provided option or prompt for template
-    let template = options.template && ['react', 'react-dynamic', 'react-para'].includes(options.template) ? options.template : '';
+    let template = options.template && ['react', 'react-dynamic', 'react-para', 'react-turnkey'].includes(options.template) ? options.template : '';
     if (!template) {
         const res = await prompts({
             type: 'select',
@@ -75,7 +77,7 @@ Available Chains:
             process.exit(1);
         }
         template = res.template; // The value is already what we want from the choices
-        if (!template || !['react', 'react-dynamic', 'react-para'].includes(template)) {
+        if (!template || !['react', 'react-dynamic', 'react-para', 'react-turnkey'].includes(template)) {
             console.log('Template selection is required.');
             process.exit(1);
         }
@@ -100,6 +102,12 @@ Available Chains:
             process.exit(1);
         }
     }
+    // Validate template + chain compatibility
+    if (['react-dynamic', 'react-para', 'react-turnkey'].includes(template) && chain === 'radiusTestnet') {
+        console.log(`\nError: The ${template} template does not support radiusTestnet.`);
+        console.log('Please use baseSepolia or base chain instead.\n');
+        process.exit(1);
+    }
     // Use provided option or prompt for API key
     let apiKey = options.apiKey && options.apiKey.trim() ? options.apiKey.trim() : '';
     if (!apiKey) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sbc-app",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Scaffold a new SBC App Kit project with one command.",
   "bin": {
     "create-sbc-app": "bin/cli.js"

package/templates/react-turnkey/.env.template

@@ -0,0 +1,26 @@
+# SBC API Key (get from https://dashboard.stablecoin.xyz)
+VITE_SBC_API_KEY={{apiKey}}
+
+# Chain Configuration (baseSepolia or base)
+VITE_CHAIN={{chain}}
+
+# Turnkey Configuration (Frontend - Public, safe to expose)
+VITE_TURNKEY_API_BASE_URL=https://api.turnkey.com
+VITE_TURNKEY_RPID=localhost
+VITE_BACKEND_URL=http://localhost:3001
+
+# Turnkey Backend Configuration (Server - KEEP SECRET!)
+# Get these from https://app.turnkey.com → Settings → API Keys
+TURNKEY_API_BASE_URL=https://api.turnkey.com
+TURNKEY_ORGANIZATION_ID=your_org_id_here
+TURNKEY_API_PUBLIC_KEY=your_public_key_here
+TURNKEY_API_PRIVATE_KEY=your_private_key_here
+
+# Backend Server Port
+PORT=3001
+
+# Optional: Custom RPC URL
+# VITE_RPC_URL=https://base-sepolia.g.alchemy.com/v2/YOUR_KEY
+
+# Note: This example uses passkeyClient approach (official Turnkey pattern)
+# You do NOT need Auth Proxy Config ID or authProxyConfigId

package/templates/react-turnkey/README.md.template

@@ -0,0 +1,206 @@
+# {{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

package/templates/react-turnkey/eslint.config.js.template

@@ -0,0 +1,32 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from '@typescript-eslint/eslint-plugin'
+import tsparser from '@typescript-eslint/parser'
+
+export default [
+  { ignores: ['dist'] },
+  {
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+      parser: tsparser,
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...tseslint.configs.recommended.rules,
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': [
+        'warn',
+        { allowConstantExport: true },
+      ],
+    },
+  },
+] 

package/templates/react-turnkey/index.html.template

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/png" href="/sbc-logo.png" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{projectName}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/react-turnkey/package.json.template

@@ -0,0 +1,45 @@
+{
+  "name": "{{projectName}}",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "dev:backend": "tsx watch server/index.ts",
+    "dev:fullstack": "concurrently \"npm run dev:backend\" \"npm run dev\"",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "lint": "eslint .",
+    "start": "vite"
+  },
+  "dependencies": {
+    "@stablecoin.xyz/core": "latest",
+    "@stablecoin.xyz/react": "latest",
+    "@turnkey/sdk-react": "^5.4.10",
+    "@turnkey/sdk-server": "^4.12.0",
+    "@turnkey/viem": "^0.14.12",
+    "cors": "^2.8.5",
+    "dotenv": "^17.2.3",
+    "express": "^5.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "viem": "^2.33.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.9.0",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.5",
+    "@types/react": "^18.2.66",
+    "@types/react-dom": "^18.2.22",
+    "@vitejs/plugin-react": "^4.0.0",
+    "concurrently": "^9.2.1",
+    "eslint": "^9.9.0",
+    "eslint-plugin-react-hooks": "^5.1.0-rc.0",
+    "eslint-plugin-react-refresh": "^0.4.9",
+    "globals": "^15.9.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.0.1",
+    "vite": "^5.0.0"
+  }
+}