# CLAUDE.md - GOR Deploy Development Guide

## Project Overview

**GOR Deploy** is a Next.js application that bridges Solana blockchain token payments with Laconic Registry deployments. Users pay with native GOR tokens or GOR SPL tokens and the app creates deployment records in the Laconic Registry for frontend applications.

## Quick Commands

```bash
# Development
npm run dev            # Start development server (http://localhost:3000)
npm run build          # Build for production
npm start              # Start production server
npm run lint           # Run ESLint

# Testing
# No test framework configured - check README for testing approach
```

## Project Architecture

### Tech Stack
- **Frontend**: Next.js 15.3.1 with React 19
- **Styling**: TailwindCSS 4
- **Blockchain**:
  - Solana Web3.js for payments
  - @cerc-io/registry-sdk for Laconic Registry
  - CosmJS for Cosmos blockchain interactions
- **Wallet Integration**: Phantom, Solflare & Backpack with context-based filtering
- **Language**: TypeScript

### Key Dependencies
- `@solana/web3.js` - Solana blockchain interactions
- `@solana/spl-token` - SPL token handling
- `@solana/wallet-adapter-react` - Unified wallet adapter integration
- `@solana/wallet-adapter-phantom` - Phantom wallet adapter
- `@solana/wallet-adapter-solflare` - Solflare wallet adapter
- `@solana/wallet-adapter-backpack` - Backpack wallet adapter
- `@cerc-io/registry-sdk` - Laconic Registry operations
- `@cosmjs/stargate` - Cosmos blockchain operations
- `axios` - HTTP requests for GitHub API
- `bn.js` - Big number arithmetic
- `big.js` - Decimal arithmetic

## Application Flow

1. **Payment Method Selection**: User chooses between native GOR or SPL token payment
2. **Wallet Connection**: Compatible wallets are filtered based on payment method
3. **URL Input**: User enters repository URL to deploy (enabled after wallet connection)
4. **Payment**: Fixed amount payment in native GOR or GOR SPL tokens to configured recipient
5. **Verification**: Server verifies Solana transaction (5-minute window)
6. **LNT Transfer**: Server transfers LNT tokens for registry fees
7. **Registry Records**: Creates ApplicationRecord and ApplicationDeploymentRequest
8. **Name Mapping**: Sets LRN mappings in Laconic Registry

## Payment Method & Wallet Compatibility

### Native GOR Payments (`nat-gor`)
- **Amount**: 0.01 GOR (10,000,000 lamports)
- **Compatible Wallets**: Backpack only
- **RPC Endpoint**: Uses `NEXT_PUBLIC_GORBAGANA_RPC_URL` for native transactions

### SPL Token Payments (`spl-token`)
- **Amount**: $5 USD worth of GOR SPL tokens (dynamic pricing via Jupiter)
- **Compatible Wallets**: Phantom, Solflare (Backpack excluded)
- **RPC Endpoint**: Uses `NEXT_PUBLIC_SOLANA_RPC_URL` for token transactions

## Key Files and Components

### Frontend Components
- `src/app/page.tsx` - Main application page with 4-step flow (Payment Method → Wallet → URL → Status)
- `src/components/PaymentModal.tsx` - Solana payment interface with pre-selected payment method
- `src/components/WalletProviders.tsx` - Context-aware wallet provider with filtering
- `src/components/URLForm.tsx` - URL input form
- `src/components/StatusDisplay.tsx` - Deployment status display

### Context & State Management
- `src/contexts/PaymentMethodContext.tsx` - Global payment method state management
- Uses React Context for payment method selection
- Wallet filtering based on payment method context

### Services and Utils
- `src/services/solana.ts` - Unified wallet adapter integration for payments
- `src/services/registry.ts` - Client-side registry service wrapper
- `src/services/laconic-transfer.ts` - LNT token transfer logic
- `src/utils/solana-verify.ts` - Payment verification with replay protection
- `src/config/index.ts` - Registry configuration management
- `src/constants/payments.ts` - Payment method types and configuration

### API Routes
- `src/app/api/registry/route.ts` - Main server-side registry operations with dual payment support

## Environment Configuration

### Client-side Variables (NEXT_PUBLIC_*)
```bash
NEXT_PUBLIC_SOLANA_RPC_URL=https://skilled-prettiest-seed.solana-mainnet.quiknode.pro/eeecfebd04e345f69f1900cc3483cbbfea02a158
NEXT_PUBLIC_GORBAGANA_RPC_URL=https://rpc.gorbagana.wtf
NEXT_PUBLIC_SOLANA_TOKEN_MINT_ADDRESS=<SPL_TOKEN_MINT>
NEXT_PUBLIC_SOLANA_TOKEN_RECIPIENT_ADDRESS=<RECIPIENT_WALLET>
NEXT_PUBLIC_SOLANA_TOKEN_SYMBOL=GOR
NEXT_PUBLIC_SOLANA_PAYMENT_AMOUNT_USD=5
NEXT_PUBLIC_DOMAIN_SUFFIX=.example.com
NEXT_PUBLIC_EXAMPLE_URL=https://git.vdb.to/cerc-io/test-progressive-web-app
```

### Server-side Variables
```bash
REGISTRY_CHAIN_ID=laconic-mainnet
REGISTRY_GQL_ENDPOINT=https://laconicd-mainnet-1.laconic.com/api
REGISTRY_RPC_ENDPOINT=https://laconicd-mainnet-1.laconic.com
REGISTRY_BOND_ID=<BOND_ID>
REGISTRY_AUTHORITY=<AUTHORITY_NAME>
REGISTRY_USER_KEY=<PRIVATE_KEY>
APP_NAME=gor-deploy
DEPLOYER_LRN=<DEPLOYER_LRN>
```

## Code Patterns and Conventions

### State Management
- Uses React Context (`PaymentMethodContext`) for global payment method state
- React `useState` for component-level state
- Dynamic imports to avoid SSR issues with browser APIs
- Context-driven wallet filtering

### Payment Architecture
- Unified wallet adapter pattern for all three wallets
- Payment method determines wallet availability
- Separate RPC endpoints for native vs SPL token transactions
- Dynamic pricing via Jupiter API for SPL tokens

### Error Handling
- Comprehensive try-catch blocks in all async operations
- User-friendly error messages in UI
- Server-side error logging with detailed context
- Wallet compatibility validation with clear feedback

### Security Best Practices
- Environment variables for sensitive data
- Transaction verification with replay protection
- Proper SPL token account creation and validation
- Private key never exposed to client-side
- Wallet signature verification via adapters

## Development Workflow

### Adding New Features
1. **Client Components**: Add to `src/components/`
2. **Services**: Add to `src/services/`
3. **API Routes**: Add to `src/app/api/`
4. **Types**: Update `src/types/index.ts`
5. **Payment Methods**: Update `src/constants/payments.ts`

### Payment Integration
- All payment logic unified in `src/services/solana.ts`
- Verification logic in `src/utils/solana-verify.ts`
- Transaction signing via wallet adapters
- Payment method context drives wallet selection

### Wallet Integration
- Add new wallet adapters to `src/components/WalletProviders.tsx`
- Update wallet filtering logic based on payment method compatibility
- Use `@solana/wallet-adapter-*` packages for consistent integration

### Registry Integration
- Registry operations in `src/app/api/registry/route.ts`
- Configuration in `src/config/index.ts`
- LRN format: `lrn://{authority}/applications/{app-name}-{commit-hash}`

## DNS and Resource Naming

### DNS Name Generation
Format: `{sanitized-repo-name}-{7-char-commit-hash}`
- Sanitized to be DNS-compatible (alphanumeric + dashes)
- Max 63 characters per DNS label
- Always lowercase
- Random salt removed (commit hash provides uniqueness)

### LRN (Laconic Resource Name) Format
Format: `lrn://{authority}/applications/{app-name}-{commit-hash}`
- Matches DNS naming for consistency
- Includes both versioned and unversioned mappings

## Transaction Flow Details

### Solana Payment Verification
- 5-minute transaction window
- Amount verification against configured payment
- Recipient address validation (different for native vs SPL)
- Replay attack protection (TODO: implement used transaction tracking)
- Payment method-specific validation logic

### Laconic Registry Operations
1. **ApplicationRecord**: Repository metadata and commit info
2. **Name Mappings**: LRN pointing to application record
3. **ApplicationDeploymentRequest**: Deployment configuration with payment proof

## Common Development Tasks

### Adding New Wallet Support
1. Install wallet adapter package: `npm install @solana/wallet-adapter-{wallet-name}`
2. Add to `src/components/WalletProviders.tsx` wallets array
3. Update wallet filtering logic based on payment method compatibility
4. Test with both payment methods

### Adding New Payment Methods
1. Update `PaymentMethod` type in `src/constants/payments.ts`
2. Add payment method label to `PAYMENT_METHOD_LABELS`
3. Update wallet filtering logic in `WalletProviders.tsx`
4. Add payment processing logic in `src/services/solana.ts`
5. Update verification logic in `src/utils/solana-verify.ts`

### Modifying Payment Verification
- Update logic in `src/utils/solana-verify.ts`
- Consider replay protection requirements
- Test with various transaction types
- Handle both native GOR and SPL token verification

### Registry Schema Changes
- Update record structures in `src/app/api/registry/route.ts`
- Ensure compatibility with Laconic Registry schema
- Test with registry validation

## Payment Method Context Usage

The `PaymentMethodContext` drives wallet filtering:

```typescript
// In components
const { selectedPaymentMethod, setSelectedPaymentMethod } = usePaymentMethod();

// Wallet filtering logic
if (selectedPaymentMethod === 'nat-gor') {
  // Show only Backpack wallet
} else if (selectedPaymentMethod === 'spl-token') {
  // Show only Phantom and Solflare wallets
}
```

## Deployment Considerations

### Production Setup
- All environment variables must be set
- HTTPS required for wallet connections
- Consider rate limiting for API routes
- Monitor gas fees and LNT transfer costs
- Ensure both RPC endpoints are reliable

### Docker Deployment
- Dockerfile provided in project root
- Build optimization for Next.js production
- Environment variables via docker-compose or k8s secrets

## Troubleshooting

### Common Issues
- **Wallet connection fails**: Check HTTPS and wallet extension
- **Wrong wallet shown**: Verify payment method context is set correctly
- **Transaction verification fails**: Check appropriate RPC URL and transaction timing
- **Registry errors**: Verify all REGISTRY_* environment variables
- **LNT transfer fails**: Check private key balance and permissions
- **SPL token price errors**: Verify Jupiter API connectivity

### Debug Tools
- Browser console for client-side debugging
- Server logs for API route debugging
- Solana Explorer for transaction verification
- Registry CLI for direct registry interactions
- Payment method context state in React DevTools

## Testing Strategy

- Manual testing with real wallets and tokens
- Use testnet/devnet for development
- Test transaction verification edge cases
- Verify registry record creation and name mappings
- Test wallet filtering with different payment methods
- Test both native GOR and SPL token payment flows

## Related Projects

This application references:
- `snowballtools-base/packages/backend/src/registry.ts`
- Original `hosted-frontends/deploy-atom.sh`
- Laconic Registry CLI tools

## Security Considerations

- Private keys stored securely server-side only
- Transaction replay protection implemented
- Input validation on all user inputs
- Secure RPC endpoint usage
- Wallet signature verification via adapters
- Payment method validation before processing

## Future Enhancements

- Implement transaction replay protection database
- Add support for custom deployment configurations
- Enhanced error recovery and retry logic
- Monitoring and analytics integration
- Multi-chain payment support
- Additional wallet adapter integrations
- Advanced payment method configurations