gor-deploy/README.md

# GOR Deploy - Laconic Registry

A simple Next.js frontend that allows users to pay in GOR tokens (configurable Solana SPL tokens) using Solana wallets and paste a URL. The transaction hash and URL are used to create records in the Laconic Registry.

## Features

- Solana wallet integration (Phantom & Solflare) for GOR token payments
- Configurable Solana SPL token support (defaults to GOR)
- URL validation and submission
- Solana transaction verification with replay protection
- Laconic Registry record creation using official `@cerc-io/registry-sdk`
- LNT token transfer integration for registry payments
- Automatic salt addition to DNS names to prevent collisions
- Error handling and validation throughout the application flow

## Prerequisites

- Node.js 18.x or later
- npm or yarn
- Solana wallet browser extension (Phantom or Solflare)
- Access to a Laconic Registry node

## Deploy to production

Follow [these steps](./deploy/README.md) to deploy this app to production

## Installation

```bash
npm install
```

## Development

Copy the `.env.example` file to `.env.local` and fill in the required variables:

```bash
cp .env.example .env.local
```

Required environment variables:

Client-side (must be prefixed with NEXT_PUBLIC_):
- `NEXT_PUBLIC_SOLANA_RPC_URL` - The RPC URL for the Solana blockchain (SPL token transactions)
- `NEXT_PUBLIC_SOLANA_WS_URL` - The WS URL for the Solana blockchain (SPL token transactions)
- `NEXT_PUBLIC_SOLANA_TOKEN_MINT_ADDRESS` - The mint address of the SPL token to accept
- `NEXT_PUBLIC_SOLANA_TOKEN_SYMBOL` - The token symbol to display (e.g., "GOR")
- `NEXT_PUBLIC_GORBAGANA_RPC_URL` - The RPC URL for the Gorbagana blockchain (native GOR transactions)
- `NEXT_PUBLIC_ENABLE_NATIVE_GOR_TRANSFER` - Enable native GOR token transfers (true/false)
- `NEXT_PUBLIC_SOLANA_TOKEN_RECIPIENT_ADDRESS` - The Solana address that will receive token payments
- `NEXT_PUBLIC_EXAMPLE_URL` - Example URL to pre-fill in the URL form
- `NEXT_PUBLIC_REGISTRY_CHAIN_ID` - The laconicd chain ID for the Laconic Registry
- `NEXT_PUBLIC_REGISTRY_RPC_ENDPOINT` - The laconicd RPC endpoint for the Laconic Registry
- `NEXT_PUBLIC_REGISTRY_GQL_ENDPOINT` - The laconicd GraphQL endpoint for the Laconic Registry
- `NEXT_PUBLIC_ALNT_COST_LRN` - LRN for ALNT token pricing
- `NEXT_PUBLIC_DEPLOYMENT_COST_LRN` - LRN for deployment cost pricing
- `NEXT_PUBLIC_DOMAIN_SUFFIX` - Optional suffix to append to DNS names in the UI (e.g. ".example.com")

Server-side:
- `REGISTRY_BOND_ID` - The bond ID to use for Laconic Registry records
- `REGISTRY_AUTHORITY` - The authority for Laconic Registry LRNs
- `REGISTRY_USER_KEY` - The private key for Laconic Registry transactions (also used for LNT transfers)
- `DEPLOYER_LRN` - The LRN of the deployer

```bash
npm run dev
```

Visit http://localhost:3000 to see the application.

## Build for Production

```bash
npm run build
```

## Start Production Server

```bash
npm start
```

## How It Works

1. User connects their Solana wallet (Phantom or Solflare) to the application
2. User enters a URL they want to deploy to the Laconic Registry
3. User completes payment in GOR tokens (or configured SPL token) to a specified Solana address
4. The application verifies the Solana transaction with replay protection
5. After payment verification, the server transfers LNT tokens from a prefilled account to the service provider
6. The application calls a server-side API route which creates records in the Laconic Registry using the LNT transfer hash
7. The server generates a unique DNS name by adding a random salt to prevent name collisions
8. Two records are created in the Laconic Registry:
   - An ApplicationRecord containing metadata about the URL
   - An ApplicationDeploymentRequest linking the URL, DNS, and payment details with external_payment metadata

### Architecture

This application uses a hybrid client/server approach:

- Client-side: Handles the user interface, Solana wallet integration, and transaction verification
- Server-side: Next.js API route handles LNT transfers and communication with the Laconic Registry

This architecture allows us to keep sensitive keys secure on the server side while providing a responsive user experience. The dual-payment system (Solana → LNT → Registry) enables cross-chain payment acceptance.

### Resource Name Formats

#### DNS Name Format

The DNS names are generated with the following format:
```
{sanitized-url-name}-{short-commit-hash}-{random-salt}{domain-suffix}
```

For example:
- Basic DNS: `github-abc123-xyz789`
- With domain suffix: `github-abc123-xyz789.example.com`

The random salt ensures that each deployment request has a unique DNS name, even if the same URL is deployed multiple times or by different users. The optional domain suffix allows the application to display a full domain name to users.

#### Laconic Resource Name (LRN) Format

The Laconic Resource Names (LRNs) are generated with the following format:
```
lrn://{authority}/applications/{app-name}-{short-commit-hash}-{random-salt}
```

For example: `lrn://gor/applications/github-abc123-xyz789`

Including the commit hash and salt in the LRN ensures that each application record has a unique identifier, consistently matching the DNS naming pattern.

## Reference Files

This application was built with reference to:
- `snowballtools-base/packages/backend/src/registry.ts`
- Original `hosted-frontends/deploy-atom.sh` (adapted for Solana/GOR)

## Known Issues

- You may see a deprecated Buffer() warning during build. This comes from dependencies in the registry-sdk. This doesn't affect functionality.
- Ensure that your Solana RPC endpoint supports CORS for client-side requests.
- Solana wallet integrations require HTTPS in production environments.

## Troubleshooting

### Solana Wallet Issues

- **Wallet not detecting**: Install the Phantom or Solflare browser extension and refresh the page.
- **Connection issues**: Ensure the wallet is unlocked and try refreshing the page.
- **Transaction failures**: Check that you have sufficient SOL for transaction fees and enough tokens for the payment.

### Laconic Registry Issues

- **Failed to create record**: Check that your REGISTRY_USER_KEY and REGISTRY_BOND_ID are correctly set.
- **LNT transfer errors**: Ensure your REGISTRY_USER_KEY has sufficient LNT balance.
- **Transaction verification errors**: Ensure your SOLANA_RPC_URL is accessible and returns correct transaction data.