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

## Environment Variables

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

```bash
cp .env.local.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
- `NEXT_PUBLIC_SOLANA_TOKEN_MINT_ADDRESS` - The mint address of the SPL token to accept
- `NEXT_PUBLIC_SOLANA_TOKEN_RECIPIENT_ADDRESS` - The Solana address that will receive token payments
- `NEXT_PUBLIC_SOLANA_TOKEN_SYMBOL` - The token symbol to display (e.g., "GOR")
- `NEXT_PUBLIC_SOLANA_TOKEN_DECIMALS` - The number of decimals for the token (e.g., 6)
- `NEXT_PUBLIC_SOLANA_PAYMENT_AMOUNT` - The fixed payment amount required (e.g., 400)
- `NEXT_PUBLIC_DOMAIN_SUFFIX` - Optional suffix to append to DNS names in the UI (e.g. ".example.com")
- `NEXT_PUBLIC_EXAMPLE_URL` - Example URL to pre-fill in the URL form (e.g. "https://github.com/cerc-io/laconic-registry-cli")

Server-side:
- `REGISTRY_CHAIN_ID` - The chain ID for the Laconic Registry
- `REGISTRY_GQL_ENDPOINT` - The GraphQL endpoint for the Laconic Registry
- `REGISTRY_RPC_ENDPOINT` - The RPC endpoint for the Laconic Registry
- `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)
- `APP_NAME` - The name of the application (used in record creation, defaults to "gor-deploy")
- `DEPLOYER_LRN` - The LRN of the deployer

## Installation

```bash
npm install
```

## Development

```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)

## Deployment to Production

To deploy this application to production, follow these steps:

1. Clone the repository
2. Install dependencies: `npm install`
3. Create a production build: `npm run build`
4. Set up all required environment variables in your production environment
5. Start the production server: `npm start`

For containerized deployments, you can use the following Dockerfile:

```dockerfile
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

EXPOSE 3000

ENV NODE_ENV=production

CMD ["npm", "start"]
```

Build and run the Docker container:

```bash
docker build -t gor-deploy .
docker run -p 3000:3000 --env-file .env.production gor-deploy
```

## 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.

### Token Configuration

- **Wrong token**: Verify the `NEXT_PUBLIC_SOLANA_TOKEN_MINT_ADDRESS` matches your desired SPL token.
- **Incorrect decimals**: Ensure `NEXT_PUBLIC_SOLANA_TOKEN_DECIMALS` matches the token's actual decimal count.
- **Payment amount**: Adjust `NEXT_PUBLIC_SOLANA_PAYMENT_AMOUNT` to the desired payment amount.

### 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.