create-sbc-app 0.3.0 → 0.4.0

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"
+  }
+}

package/templates/react-turnkey/server/index.ts.template

@@ -0,0 +1,271 @@
+import 'dotenv/config';
+import express from 'express';
+import cors from 'cors';
+import { Turnkey } from '@turnkey/sdk-server';
+
+const app = express();
+const port = process.env.PORT || 3001;
+
+app.use(cors());
+app.use(express.json());
+
+// Log environment variables BEFORE initialization
+console.log('\n🔍 Environment Variables:');
+console.log('  TURNKEY_ORGANIZATION_ID:', process.env.TURNKEY_ORGANIZATION_ID);
+console.log('  TURNKEY_API_BASE_URL:', process.env.TURNKEY_API_BASE_URL);
+console.log('  TURNKEY_API_PUBLIC_KEY:', process.env.TURNKEY_API_PUBLIC_KEY?.substring(0, 20) + '...');
+console.log('  TURNKEY_API_PRIVATE_KEY:', process.env.TURNKEY_API_PRIVATE_KEY ? '[SET]' : '[NOT SET]');
+
+// Initialize Turnkey SDK
+const turnkey = new Turnkey({
+  defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID!,
+  apiBaseUrl: process.env.TURNKEY_API_BASE_URL || 'https://api.turnkey.com',
+  apiPrivateKey: process.env.TURNKEY_API_PRIVATE_KEY!,
+  apiPublicKey: process.env.TURNKEY_API_PUBLIC_KEY!,
+});
+
+// Create API client for signing requests
+const turnkeyClient = turnkey.apiClient();
+
+console.log('\n✓ Turnkey SDK initialized');
+console.log('  Using Organization ID:', process.env.TURNKEY_ORGANIZATION_ID);
+console.log('  API Base URL:', process.env.TURNKEY_API_BASE_URL);
+
+/**
+ * Create sub-organization with passkey authentication
+ *
+ * Creates a new Turnkey sub-organization for a user using WebAuthn passkey authentication.
+ * This is the primary flow for biometric authentication (Face ID/Touch ID).
+ * Also creates a Turnkey-managed wallet for the user.
+ *
+ * @route POST /api/create-sub-org
+ * @param {string} req.body.userName - User's display name
+ * @param {string} req.body.userEmail - User's email address
+ * @param {string} req.body.attestation - WebAuthn attestation object from passkey creation
+ * @param {string} req.body.challenge - WebAuthn challenge used for passkey creation
+ * @returns {object} Response object
+ * @returns {string} response.subOrganizationId - ID of the created sub-organization
+ * @returns {string[]} response.addresses - Array of wallet addresses (Turnkey-managed wallet)
+ * @throws {500} If sub-organization creation fails
+ */
+app.post('/api/create-sub-org', async (req, res) => {
+  console.log('\n🚀 [BACKEND] POST /api/create-sub-org - Request received');
+
+  try {
+    const { userName, userEmail, attestation, challenge } = req.body;
+    console.log('📝 [BACKEND] Request data:', {
+      userName,
+      userEmail,
+      hasAttestation: !!attestation,
+      hasChallenge: !!challenge,
+      attestationLength: attestation?.length,
+    });
+
+    // Step 1: Create sub-organization
+    console.log('🏢 [BACKEND] Step 1: Creating sub-organization...');
+    console.log('🔑 [BACKEND] Forcing organization ID:', process.env.TURNKEY_ORGANIZATION_ID);
+
+    const subOrgResponse = await turnkeyClient.createSubOrganization({
+      organizationId: process.env.TURNKEY_ORGANIZATION_ID!,
+      subOrganizationName: `${userName}'s Organization`,
+      rootUsers: [{
+        userName,
+        userEmail,
+        apiKeys: [],
+        authenticators: [{
+          authenticatorName: `${userName}'s Passkey`,
+          challenge,
+          attestation,
+        }],
+        oauthProviders: [],
+      }],
+      rootQuorumThreshold: 1,
+      wallet: {
+        walletName: `${userName}'s Wallet`,
+        accounts: [{
+          curve: 'CURVE_SECP256K1',
+          pathFormat: 'PATH_FORMAT_BIP32',
+          path: "m/44'/60'/0'/0/0",
+          addressFormat: 'ADDRESS_FORMAT_ETHEREUM',
+        }],
+      },
+    });
+    console.log('✅ [BACKEND] Sub-org created successfully!', {
+      subOrgId: subOrgResponse.subOrganizationId,
+      wallet: subOrgResponse.wallet,
+    });
+
+    const subOrgId = subOrgResponse.subOrganizationId;
+    const walletAddresses = subOrgResponse.wallet?.addresses || [];
+
+    const responseData = {
+      subOrganizationId: subOrgId,
+      addresses: walletAddresses,
+    };
+    console.log('📤 [BACKEND] Sending success response:', responseData);
+    res.json(responseData);
+  } catch (error: any) {
+    console.error('❌ [BACKEND] Error creating sub-org:', error);
+    console.error('❌ [BACKEND] Error message:', error.message);
+    console.error('❌ [BACKEND] Error stack:', error.stack);
+    res.status(500).json({ error: error.message });
+  }
+});
+
+/**
+ * Create sub-organization with wallet authentication
+ *
+ * Creates a new Turnkey sub-organization for a user using external wallet authentication
+ * (MetaMask, Coinbase Wallet, etc.). The user's wallet becomes the smart account owner.
+ * Does NOT create a Turnkey-managed wallet - uses user's existing wallet instead.
+ *
+ * @route POST /api/create-sub-org-with-wallet
+ * @param {string} req.body.userName - User's display name
+ * @param {string} req.body.userEmail - User's email address
+ * @param {string} req.body.publicKey - Compressed secp256k1 public key derived from wallet signature
+ * @param {string} req.body.walletAddress - User's wallet address (0x...)
+ * @returns {object} Response object
+ * @returns {string} response.subOrganizationId - ID of the created sub-organization
+ * @returns {string[]} response.addresses - Array containing the user's wallet address
+ * @throws {400} If required parameters are missing
+ * @throws {500} If sub-organization creation fails
+ */
+app.post('/api/create-sub-org-with-wallet', async (req, res) => {
+  console.log('\n🚀 [BACKEND] POST /api/create-sub-org-with-wallet - Request received');
+
+  try {
+    const { userName, userEmail, publicKey, walletAddress } = req.body;
+    console.log('📝 [BACKEND] Request data:', {
+      userName,
+      userEmail,
+      publicKey,
+      walletAddress,
+    });
+
+    if (!userName || !userEmail || !publicKey || !walletAddress) {
+      return res.status(400).json({ error: 'userName, userEmail, publicKey, and walletAddress are required' });
+    }
+
+    // Compressed public keys from secp256k1 start with 0x02 or 0x03 (33 bytes / 66 hex chars)
+    console.log('📝 [BACKEND] Using public key:', publicKey);
+    const formattedPublicKey = publicKey;
+
+    // Create sub-organization with wallet-based API key (NO Turnkey wallet creation)
+    console.log('🏢 [BACKEND] Creating sub-organization with wallet authentication...');
+    console.log('🔑 [BACKEND] User will use their MetaMask wallet as owner:', walletAddress);
+
+    const subOrgResponse = await turnkeyClient.createSubOrganization({
+      organizationId: process.env.TURNKEY_ORGANIZATION_ID!,
+      subOrganizationName: `${userName}'s Organization`,
+      rootUsers: [{
+        userName,
+        userEmail,
+        apiKeys: [{
+          apiKeyName: `${userName}'s Wallet Key`,
+          publicKey: formattedPublicKey,
+          curveType: 'API_KEY_CURVE_SECP256K1',
+        }],
+        authenticators: [], // No passkey authenticators for wallet-based auth
+        oauthProviders: [],
+      }],
+      rootQuorumThreshold: 1,
+      // NO wallet creation - user's MetaMask wallet will be the owner
+    });
+
+    console.log('✅ [BACKEND] Sub-org created with wallet auth!', {
+      subOrgId: subOrgResponse.subOrganizationId,
+      userWalletAddress: walletAddress,
+    });
+
+    const subOrgId = subOrgResponse.subOrganizationId;
+
+    // Return the user's MetaMask wallet address, not a Turnkey wallet
+    const responseData = {
+      subOrganizationId: subOrgId,
+      addresses: [walletAddress], // User's MetaMask wallet is the owner
+    };
+    console.log('📤 [BACKEND] Sending success response:', responseData);
+    res.json(responseData);
+  } catch (error: any) {
+    console.error('❌ [BACKEND] Error creating sub-org with wallet:', error);
+    console.error('❌ [BACKEND] Error message:', error.message);
+    console.error('❌ [BACKEND] Error stack:', error.stack);
+    res.status(500).json({ error: error.message });
+  }
+});
+
+/**
+ * Get sub-organization by wallet public key
+ *
+ * Looks up a sub-organization ID using the wallet's public key.
+ * Used to check if a wallet user already has an existing sub-organization.
+ * Also fetches wallet addresses associated with the sub-organization.
+ *
+ * @route POST /api/get-sub-org-by-wallet
+ * @param {string} req.body.publicKey - Compressed secp256k1 public key to search for
+ * @returns {object} Response object
+ * @returns {string|null} response.subOrganizationId - ID of the found sub-organization, or null if not found
+ * @returns {string[]} response.addresses - Array of wallet addresses (empty if not found)
+ * @throws {400} If publicKey is missing or invalid
+ * @throws {500} If sub-organization lookup fails
+ */
+app.post('/api/get-sub-org-by-wallet', async (req, res) => {
+  console.log('\n🔍 [BACKEND] POST /api/get-sub-org-by-wallet - Request received');
+
+  try {
+    const { publicKey } = req.body;
+    console.log('📝 [BACKEND] Public key:', publicKey);
+
+    if (!publicKey || typeof publicKey !== 'string') {
+      return res.status(400).json({ error: 'publicKey is required' });
+    }
+
+    console.log('🔎 [BACKEND] Searching for sub-org with public key...');
+    const result = await turnkeyClient.getSubOrgIds({
+      organizationId: process.env.TURNKEY_ORGANIZATION_ID!,
+      filterType: 'PUBLIC_KEY',
+      filterValue: publicKey,
+    });
+
+    console.log('✅ [BACKEND] Sub-org IDs found:', result.organizationIds);
+
+    const subOrgId = result.organizationIds?.[0] ?? null;
+
+    if (subOrgId) {
+      // Fetch wallet info for this sub-org
+      console.log('💼 [BACKEND] Fetching wallet for sub-org:', subOrgId);
+      const walletsResponse = await turnkeyClient.getWallets({
+        organizationId: subOrgId,
+      });
+
+      const addresses: string[] = [];
+      if (walletsResponse.wallets && walletsResponse.wallets.length > 0) {
+        const wallet = walletsResponse.wallets[0];
+        const accountsResponse = await turnkeyClient.getWalletAccounts({
+          organizationId: subOrgId,
+          walletId: wallet.walletId,
+        });
+        if (accountsResponse.accounts) {
+          addresses.push(...accountsResponse.accounts.map(acc => acc.address));
+        }
+      }
+
+      res.json({
+        subOrganizationId: subOrgId,
+        addresses,
+      });
+    } else {
+      res.json({
+        subOrganizationId: null,
+        addresses: [],
+      });
+    }
+  } catch (error: any) {
+    console.error('❌ [BACKEND] Error fetching sub-org:', error);
+    res.status(500).json({ error: error.message });
+  }
+});
+
+app.listen(port, () => {
+  console.log(`Turnkey backend server running on http://localhost:${port}`);
+});