gor-deploy/CLAUDE.md

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

# 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_*)

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

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:

// 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