RaidGuild Accounting

Wallet-gated accounting dashboard for RaidGuild treasury reporting.

Product Scope

RaidGuild Accounting links treasury holdings, manually entered accounting activity, DAO proposal data, RIPs, and imported reporting data into member-facing quarterly and annual financial reports.

The app uses cash-basis accounting: money counts when it moves. Taxable raid revenue is gross client revenue, with spoils tracked as 10% of gross raid revenue and subcontractor payouts tracked as expenses for P&L and raid accounting.

Treasury portfolio views are read-only and focus on current holdings, asset allocation, account breakdowns, sync freshness, and stablecoin rebalancing guidance. Stablecoin allocation targets 25% stables and 75% other assets, with a 5 percentage point tolerance.

Architecture

• Next.js App Router renders the wallet-gated dashboard.
• Drizzle ORM models accounting records, treasury accounts, balance snapshots, quarter workflow state, audit records, and entity/address book records.
• Treasury balance snapshots are synced from environment-configured accounts and cached for member-visible reads.
• Published quarter reports and exports are member-visible. Draft, ready-for-review, reopened, and administrative accounting workflows remain restricted to the appropriate roles.
• Sensitive configuration and real financial data are environment-driven. The public repo must not hardcode treasury addresses, DAO addresses, RPC URLs, API keys, bank data, or classified accounting records.

Permissions

• Member access is wallet-gated through SIWE and current RaidGuild DAO shares.
• Admin/write access is derived from Angry Dwarf Hat ownership.
• Cleric access is database-managed by admins and is limited to raid-oriented accounting workflows.
• Portfolio and published report views are read-only for authorized users.

Getting Started

Install dependencies:

pnpm install

Copy local environment placeholders:

cp .env.example .env.local

Run the development server:

pnpm dev

Open http://localhost:3000 with your browser to see the result.

For a local HTTPS proxy or remote development tunnel, set the public app URL and allowed dev origins in your ignored local environment file:

NEXT_PUBLIC_APP_URL=https://your-dev-origin.example
NEXT_ALLOWED_DEV_ORIGINS=your-dev-origin.example

Then run the proxy-friendly dev server:

pnpm dev:proxy

Point your local proxy at http://127.0.0.1:3001. Keep machine-specific proxy hostnames and URLs out of committed source.

Scripts

• pnpm dev: start the local Next.js dev server.
• pnpm dev:proxy: start the local Next.js dev server on 127.0.0.1:3001 for a local HTTPS proxy or remote development tunnel.
• pnpm build: create a production build.
• pnpm start: run the production build.
• pnpm lint: run ESLint.
• pnpm test:e2e: run Playwright responsive smoke tests.
• pnpm test:e2e:install: install the Playwright Chromium browser.
• pnpm db:generate: generate Drizzle SQL migrations from the schema.
• pnpm db:migrate: apply Drizzle migrations to DATABASE_URL.
• pnpm db:reset:local: drop and recreate the local public schema, then run migrations.
• pnpm db:studio: open Drizzle Studio for local database inspection.

End-to-End QA

The Playwright suite checks public and gated dashboard routes across mobile, tablet, and desktop viewports. It uses the local database state that is already present. Detail-page checks skip with a clear message when the local database does not contain a matching quarter or report.

On a fresh Ubuntu server, install browser system dependencies once:

pnpm exec playwright install-deps chromium

Then install the Chromium browser bundle:

pnpm test:e2e:install

Run the suite:

pnpm test:e2e

The tests start the Next.js dev server with E2E_AUTH_ENABLED=true and use a local-only mock session endpoint for member, cleric, and admin route coverage. That endpoint returns 404 unless E2E_AUTH_ENABLED=true and the app is not running in production.

Stack

• Next.js App Router.
• TypeScript.
• Tailwind CSS.
• shadcn/ui.
• Neon Postgres.
• Drizzle ORM.
• RaidGuild brand color tokens.

Security Notes

The repo is public. Do not commit real treasury addresses, DAO addresses, RPC URLs, API keys, bank data, or classified accounting records.

Use .env.local for local secrets. .env.example should contain only placeholder keys. Drizzle CLI commands also load .env, with .env.local overriding it when present. The app targets Neon in production. At runtime it uses Neon HTTP for Neon URLs and the standard pg driver for localhost database URLs, so local Postgres works in both the app and migrations. pnpm db:reset:local refuses non-localhost database URLs and protected database names, but it is still destructive for the selected local database.

RaidGuild member access is checked with DAO_SHARE_TOKEN_ADDRESS, the DAOhaus/Baal ERC-20 shares token. DAO_SHARE_THRESHOLD is written as a human share amount such as 100. HATS_CONTRACT_ADDRESS is the Hats Protocol contract address used for hats-based permissions, formatted as a 0x-prefixed EVM address. Use the deployed Hats contract for the target network, or a local test contract address for local chain testing. ANGRY_DWARF_HAT_ID can be provided as a decimal or hex string and requires HATS_CONTRACT_ADDRESS to function.

ENCRYPTION_KEY must be a base64-encoded 32-byte key. Multiple-key rotation requires stable key-id:base64-key entries. To generate a local development key:

openssl rand -base64 32

SESSION_SECRET must be at least 32 characters. To generate a local development value:

openssl rand -base64 32

Database Deployment

The Database GitHub Actions workflow checks generated migrations on pull requests and applies committed migrations on pushes to main.

Production migrations require a GitHub Actions production environment secret named DATABASE_URL.

If Vercel is deployed through the Git integration, its production build may start at the same time as the migration workflow. For strict migration-before-deploy ordering, deploy Vercel from GitHub Actions after the migration job instead of using Vercel's automatic Git deployment.

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.