Arlink Backend

Deploy static sites to Arweave with ARNS naming. A Vercel-like deployment platform for the permaweb — with pay-as-you-go billing, a full CLI, and on-chain USDC/USDT payment verification.

Quick Start

# Install
pnpm install

# Configure
cp .env.example .env
# Fill in: WEBHOOK_SECRET, ANT_PROCESS, GITHUB keys, ALCHEMY_API_KEY, JWT_SECRET

# Start
pnpm start          # production
pnpm dev            # development (auto-reload)

Server: http://localhost:3050

CLI Quick Start

cd cli && pnpm install && pnpm link --global

arlink login --wallet ./wallet.json
arlink deploy --repo https://github.com/user/repo --follow
arlink balance

Architecture

                                 ┌──────────────────┐
                                 │   Arlink CLI      │
                                 │  (cli/bin/arlink) │
                                 └────────┬─────────┘
                                          │
┌──────────┐    POST /deploy    ┌─────────▼─────────┐
│  GitHub   │──── webhook ────→ │    Express API     │
│  Push     │                   │   (port 3050)      │
└──────────┘                    └─────────┬─────────┘
                                          │
                                ┌─────────▼─────────┐
                                │   Billing Gate     │
                                │ (balance, tier,    │
                                │  rate limit check) │
                                └─────────┬─────────┘
                                          │
                                ┌─────────▼─────────┐
                                │   p-queue          │
                                │ (concurrency: 2)   │
                                └─────────┬─────────┘
                                          │
                                ┌─────────▼─────────┐
                                │  Worker Thread     │
                                │ (nix-shell build)  │
                                └─────────┬─────────┘
                                          │
                            ┌─────────────┼─────────────┐
                            │             │             │
                   ┌────────▼──┐  ┌───────▼────┐  ┌────▼───────┐
                   │  Billing  │  │   Turbo    │  │   ARNS     │
                   │  Charge   │  │  Upload    │  │ Undername  │
                   │  ($0.10)  │  │ (Arweave)  │  │  Setup     │
                   └───────────┘  └────────────┘  └────────────┘

Features

• Deploy any static site to Arweave (permanent hosting)
• GitHub webhook auto-deployment on push
• Branch preview deployments (Load Network)
• Environment variable management (encrypted, Web3 auth)
• Pay-as-you-go billing with on-chain USDC/USDT verification
• Full CLI for developers and AI agents
• Web3 authentication (Arweave JWK wallets)
• ARNS name service integration
• Admin dashboard
• Build queue with concurrency control
• SQLite database (WAL mode, zero-config)
• Structured logging (Pino)
• Input validation on all endpoints (Zod)

Documentation

Guide	Description
CLI Reference	All CLI commands, auth, deploy, billing
Billing Guide	Pricing, tiers, USDC top-ups, on-chain verification
API Reference	All 46 HTTP endpoints
Quick Start	Deploy in 30 seconds
Deployment Workflow	CI/CD, webhooks, branch previews
Web3 Auth	Arweave wallet signature auth
Environment Variables	Env var management
Admin Dashboard	Dashboard setup

Project Structure

src/
├── config/          # env.js, constants.js (billing tiers, limits)
├── db/              # schema.sql, connection.js (SQLite + migrations)
├── errors/          # AppError, InsufficientBalanceError, etc.
├── middleware/       # web3Auth.js, validate.js, requestLogger.js
├── routes/          # HTTP route handlers
│   ├── billing.routes.js     # /billing/* (balance, topup, history)
│   ├── deploy.routes.js      # /deploy, /deployments/*
│   ├── project.routes.js     # /config/*, /env-vars/*
│   ├── branchPreview.routes.js
│   ├── session.routes.js     # /session/* (JWT auth)
│   ├── github.routes.js      # webhooks, OAuth
│   ├── arns.routes.js
│   ├── admin.routes.js
│   └── health.routes.js
├── schemas/         # Zod validation schemas
├── services/        # Business logic
│   ├── BillingService.js     # Accounts, charges, refunds, top-ups
│   ├── ChainVerifyService.js # On-chain USDC/USDT verification (Alchemy)
│   ├── BuildService.js       # Deploy pipeline orchestrator
│   ├── DeployService.js      # Arweave upload via Turbo SDK
│   ├── ArnsService.js        # ARNS undername management
│   ├── ProjectService.js     # Project CRUD
│   ├── AuthService.js        # JWT sessions
│   └── Web3AuthService.js    # Arweave signature verification
├── workers/         # Build worker threads (nix-shell)
├── utils/           # Logger, git utils, path sanitizer, size check
├── app.js           # Express app setup
└── server.js        # Entry point

cli/
├── bin/arlink.js    # CLI entry point
├── lib/
│   ├── auth.js      # JWK wallet auth
│   ├── client.js    # HTTP client with auto-auth
│   ├── config.js    # ~/.arlink/config.json
│   ├── format.js    # Table, color, spinner output
│   └── commands/    # login, deploy, balance, topup, etc.
└── package.json

docs/                # Documentation
data/                # SQLite database (gitignored)
builds/              # Build artifacts (gitignored)

Database Tables

Table	Purpose
projects	Project config (owner, repo, build commands, ARNS)
deployments	Deployment records (status, tx_id, logs)
deployment_logs	Build log content
branch_preview_settings	Branch preview config per project
branch_deployments	Branch preview deployment records
accounts	Billing accounts (github_username, wallet, balance, tier)
top_ups	USDC/USDT payment ledger (tx_hash, amount, status)
billing_events	Per-deploy charge/refund log

API Endpoints (Summary)

Deployment

• POST /deploy — Deploy a project (202, non-blocking, billing gated)
• GET /deployments/:id — Poll deployment status
• GET /deployments/:id/log — Read build log
• GET /projects/:owner/:repo/history — Paginated deployment history

Billing

• GET /billing/balance — Account balance + tier (session auth)
• POST /billing/topup — Verify on-chain USDC/USDT transfer (session auth)
• GET /billing/chains — Supported chains + payment wallet (public)
• GET /billing/history — Billing event log (session auth)
• GET /billing/usage — Monthly usage summary (session auth)

Projects

• POST /createconfig — Create project config
• GET /config/:owner/:repo — Get project config
• PATCH /config/:owner/:repo — Update build settings (web3 auth)
• DELETE /deleteproject/:owner/:repo — Delete project

Auth

• POST /session/create — Create JWT session (wallet signature)
• GET /session/verify — Verify session token
• POST /session/refresh — Refresh session

Full API Reference

Environment Variables

# Required
WEBHOOK_SECRET=              # GitHub webhook secret
ANT_PROCESS=                 # ARNS ANT process ID
NEXT_PUBLIC_GITHUB_CLIENT_ID=
NEXT_PUBLIC_GITHUB_CLIENT_SECRET=
JWT_SECRET=                  # Generate: openssl rand -hex 32
ALCHEMY_API_KEY=             # Alchemy API key for on-chain verification

# Optional
PORT=3050
NODE_ENV=development         # 'production' for mainnet chains
DB_PATH=./data/arlink.db
PAYMENT_WALLET=0x173496ee2EFB79bb59b339557a9e5D73AdD98472
QUEUE_CONCURRENCY=2
BUILD_TIMEOUT_MS=720000

See .env.example for all options.

Tech Stack

• Runtime: Node.js 18+ (ES modules)
• Framework: Express.js
• Database: SQLite (better-sqlite3, WAL mode)
• Queue: p-queue
• Validation: Zod
• Logging: Pino
• Build: Nix shell
• Blockchain: ethers.js, Alchemy RPC
• Arweave: Turbo SDK, ao-connect, ARNS
• Auth: JWT, Arweave signatures (arweave.js)
• CLI: Commander, Chalk, Ora, Inquirer

Production Deployment

# PM2
pm2 start ecosystem.config.mjs
pm2 save && pm2 startup

# Or directly
NODE_ENV=production node src/server.js

Testing

pnpm test                    # All tests
pnpm test:project            # Project CRUD + config updates
pnpm test:deploy             # Deployment workflow
pnpm test:validation         # Input validation
pnpm test:security           # Security tests
pnpm test:flow               # Full lifecycle (create → patch → deploy → history)
node tests/e2e/billing-security.test.js  # Billing security (10 attack vectors)

License

MIT