Add swarm leaderboard backend with DB

Makefile

@@ -39,8 +39,11 @@ BACKEND_ONLY_PKGS := packages/txm,apps/randomness,apps/faucet
 # packages needed to build the backend services
 BACKEND_PKGS := support/common,$(BACKEND_ONLY_PKGS)
 
+# all the swarm leaderboard packages
+LEADERBOARD_PKGS := apps/leaderboard-backend
+
 # all typescript packages, excluding docs
-TS_PKGS := $(ACCOUNT_PKGS),$(DEMOS_PKGS),${BACKEND_ONLY_PKGS}
+TS_PKGS := $(ACCOUNT_PKGS),$(DEMOS_PKGS),${BACKEND_ONLY_PKGS},apps/leaderboard-backend
 
 # all packages that have a package.json
 NPM_PKGS := $(TS_PKGS),apps/docs,contracts,support/configs
@@ -169,6 +172,20 @@ submitter.prod: submitter.build
 	cd apps/submitter && make prod;
 .PHONY: submitter.prod
 
+leaderboard-backend.dev: setup.ts shared.dev
+	cd apps/leaderboard-backend && make migrate;
+	cd apps/leaderboard-backend && make dev;
+.PHONY: leaderboard-backend.dev
+
+leaderboard-backend.build: shared.build
+	cd apps/leaderboard-backend && make build;
+.PHONY: leaderboard-backend.build
+
+leaderboard-backend.prod: leaderboard-backend.build
+	cd apps/leaderboard-backend && make migrate;
+	cd apps/leaderboard-backend && make prod;
+.PHONY: leaderboard-backend.prod
+
 iframe.dev: shared.dev sdk.dev ## Serves the wallet iframe at http://localhost:5160
 	cd apps/iframe && make dev
 .PHONY: iframe.dev

apps/leaderboard-backend/.env.example

@@ -0,0 +1,3 @@
+PORT=4545
+LEADERBOARD_DB_URL="leaderboard-backend.sqlite"
+DATABASE_MIGRATE_DIR="migrations"

apps/leaderboard-backend/Makefile

@@ -0,0 +1,34 @@
+include ../../makefiles/lib.mk
+include ../../makefiles/bundling.mk
+include ../../makefiles/formatting.mk
+include ../../makefiles/help.mk
+
+# include .env file and export its env vars
+# (-include to ignore error if it does not exist)
+-include .env
+
+dev: node_modules reset-dev
+	@NODE_ENV=development bun --bun --hot src/index.ts;
+.PHONY: dev
+
+prod: build ## Start the local dev server for development
+	@NODE_ENV=production bun --bun run build/index.es.js;
+.PHONY: prod
+
+# Migration targets for leaderboard-backend (using Bun)
+
+migrate: ## Runs latest migrations
+	@echo "Running latest migrations..."
+	@bun run src/db/migrate.ts
+.PHONY: migrate
+
+migrate-fresh: ## Deletes database and starts fresh
+	@if [ -f ${LEADERBOARD_DB_URL} ]; then rm ${LEADERBOARD_DB_URL}; fi;
+	@echo "Running latest migrations on fresh DB..."
+	@bun run src/db/migrate.ts
+.PHONY: migrate-fresh
+
+# NOTE: migrate-rollback is not implemented in migrate.ts; add support if needed
+migrate-rollback: ## Rollsback latest migrations (not implemented)
+	@echo "Rollback not implemented in migrate.ts. Implement if needed."
+.PHONY: migrate-rollback

apps/leaderboard-backend/README.md

@@ -0,0 +1,11 @@
+# leaderboard-backend
+
+## Quickstart
+
+- `make setup` — Install dependencies
+- `make dev` — Start the dev server with hot reload
+- `make build` — Build the service for production
+- `make prod` — Run the built app in production mode
+- `make migrate` — Run database migrations (customize as needed)
+- `make migrate-fresh` — Reset and re-run migrations
+- `make migrate-rollback` — Roll back the last migration

apps/leaderboard-backend/biome.jsonc

@@ -0,0 +1,4 @@
+{
+    "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
+    "extends": ["../../support/configs/biome.jsonc"]
+}

apps/leaderboard-backend/build.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "@happy.tech/happybuild"
+
+export default defineConfig({
+    bunConfig: {
+        target: "bun",
+        minify: false,
+    },
+})

apps/leaderboard-backend/package.json

@@ -0,0 +1,36 @@
+{
+    "version": "0.1.0",
+    "name": "@happy.tech/leaderboard-backend",
+    "private": true,
+    "main": "./dist/index.es.js",
+    "module": "./dist/index.es.js",
+    "type": "module",
+    "types": "./dist/index.es.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.es.d.ts",
+            "default": "./dist/index.es.js"
+        }
+    },
+    "devDependencies": {
+        "@happy.tech/common": "workspace:0.1.0",
+        "@happy.tech/configs": "workspace:0.1.0",
+        "@happy.tech/happybuild": "workspace:0.1.1",
+        "@types/bun": "latest"
+    },
+    "peerDependencies": {
+        "typescript": "^5.0.0"
+    },
+    "dependencies": {
+        "@hono/zod-openapi": "^0.19.6",
+        "@hono/zod-validator": "^0.4.3",
+        "@scalar/hono-api-reference": "^0.8.8",
+        "hono": "^4.7.2",
+        "hono-openapi": "^0.4.4",
+        "kysely": "^0.27.5",
+        "kysely-bun-sqlite": "^0.3.2",
+        "viem": "^2.21.53",
+        "zod": "^3.23.8",
+        "zod-openapi": "^4.2.3"
+    }
+}

apps/leaderboard-backend/src/db/driver.ts

@@ -0,0 +1,13 @@
+import { Database as BunDatabase } from "bun:sqlite"
+import { Kysely } from "kysely"
+import { BunSqliteDialect } from "kysely-bun-sqlite"
+import type { Database } from "./types"
+
+import { env } from "../env"
+
+const dbPath = env.LEADERBOARD_DB_URL || ":memory:"
+
+export const db = new Kysely<Database>({
+    dialect: new BunSqliteDialect({ database: new BunDatabase(dbPath) }),
+    // Add plugins here if needed
+})

apps/leaderboard-backend/src/db/migrate.ts

@@ -0,0 +1,37 @@
+import { type Migration, type MigrationProvider, Migrator } from "kysely"
+import { db } from "./driver"
+import { migrations } from "./migrations"
+
+class ObjectMigrationProvider implements MigrationProvider {
+    constructor(private migrations: Record<string, Migration>) {}
+    async getMigrations(): Promise<Record<string, Migration>> {
+        return this.migrations
+    }
+}
+
+const migrator = new Migrator({
+    db,
+    provider: new ObjectMigrationProvider(migrations),
+})
+
+async function migrateToLatest() {
+    const { error, results } = await migrator.migrateToLatest()
+
+    results?.forEach((it) => {
+        if (it.status === "Success") {
+            console.log(`migration "${it.migrationName}" was executed successfully`)
+        } else if (it.status === "Error") {
+            console.error(`failed to execute migration "${it.migrationName}"`)
+        }
+    })
+
+    if (error) {
+        console.error("failed to migrate")
+        console.error(error)
+        process.exit(1)
+    }
+
+    await db.destroy()
+}
+
+migrateToLatest()

apps/leaderboard-backend/src/db/migrations/1745907000000_create_all_tables.ts

@@ -0,0 +1,89 @@
+import type { Kysely } from "kysely"
+import { sql } from "kysely"
+
+// biome-ignore lint/suspicious/noExplicitAny: `any` is required here since migrations should be frozen in time. alternatively, keep a "snapshot" db interface.
+export async function up(db: Kysely<any>): Promise<void> {
+    // Users table
+    await db.schema
+        .createTable("users")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("primary_wallet", "text", (col) => col.notNull().unique())
+        .addColumn("username", "text", (col) => col.notNull().unique())
+        .addColumn("created_at", "text", (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull())
+        .addColumn("updated_at", "text", (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull())
+        .execute()
+
+    // User wallets table (multiple wallets per user)
+    await db.schema
+        .createTable("user_wallets")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("user_id", "integer", (col) => col.notNull())
+        .addColumn("wallet_address", "text", (col) => col.notNull().unique())
+        .addColumn("is_primary", "boolean", (col) => col.notNull().defaultTo(false))
+        .addColumn("created_at", "text", (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull())
+        .addForeignKeyConstraint("user_wallets_user_id_fk", ["user_id"], "users", ["id"])
+        .execute()
+
+    // Guilds table
+    await db.schema
+        .createTable("guilds")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("name", "text", (col) => col.notNull().unique())
+        .addColumn("icon_url", "text", (col) => col)
+        .addColumn("creator_id", "integer", (col) => col.notNull())
+        .addColumn("created_at", "text", (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull())
+        .addColumn("updated_at", "text", (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull())
+        .addForeignKeyConstraint("guilds_creator_id_fk", ["creator_id"], "users", ["id"])
+        .execute()
+
+    // Guild members table (many-to-many users <-> guilds)
+    await db.schema
+        .createTable("guild_members")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("guild_id", "integer", (col) => col.notNull())
+        .addColumn("user_id", "integer", (col) => col.notNull())
+        .addColumn("is_admin", "boolean", (col) => col.notNull().defaultTo(false))
+        .addColumn("joined_at", "text", (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull())
+        .addForeignKeyConstraint("guild_members_guild_id_fk", ["guild_id"], "guilds", ["id"])
+        .addForeignKeyConstraint("guild_members_user_id_fk", ["user_id"], "users", ["id"])
+        .addUniqueConstraint("guild_members_unique", ["guild_id", "user_id"])
+        .execute()
+
+    // Games table
+    await db.schema
+        .createTable("games")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("name", "text", (col) => col.notNull().unique())
+        .addColumn("icon_url", "text", (col) => col)
+        .addColumn("description", "text", (col) => col)
+        .addColumn("admin_id", "integer", (col) => col.notNull())
+        .addColumn("created_at", "text", (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull())
+        .addColumn("updated_at", "text", (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull())
+        .addForeignKeyConstraint("games_admin_id_fk", ["admin_id"], "users", ["id"])
+        .execute()
+
+    // User game scores table
+    await db.schema
+        .createTable("user_game_scores")
+        .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+        .addColumn("user_id", "integer", (col) => col.notNull())
+        .addColumn("game_id", "integer", (col) => col.notNull())
+        .addColumn("score", "integer", (col) => col.notNull())
+        .addColumn("metadata", "text", (col) => col)
+        .addColumn("created_at", "text", (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull())
+        .addColumn("updated_at", "text", (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull())
+        .addForeignKeyConstraint("user_game_scores_user_id_fk", ["user_id"], "users", ["id"])
+        .addForeignKeyConstraint("user_game_scores_game_id_fk", ["game_id"], "games", ["id"])
+        .addUniqueConstraint("user_game_scores_unique", ["user_id", "game_id"])
+        .execute()
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: `any` is required here since migrations should be frozen in time. alternatively, keep a "snapshot" db interface.
+export async function down(db: Kysely<any>): Promise<void> {
+    await db.schema.dropTable("user_game_scores").execute()
+    await db.schema.dropTable("games").execute()
+    await db.schema.dropTable("guild_members").execute()
+    await db.schema.dropTable("guilds").execute()
+    await db.schema.dropTable("user_wallets").execute()
+    await db.schema.dropTable("users").execute()
+}

apps/leaderboard-backend/src/db/migrations/index.ts

@@ -0,0 +1,5 @@
+import * as M_1745907000000_create_all_tables from "./1745907000000_create_all_tables"
+
+export const migrations = {
+    "1745907000000_create_all_tables": M_1745907000000_create_all_tables,
+}