Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

11 Commits

Folders and files

Repository files navigation

WikiGems

Every article is a card. There is only one.

Status: not currently deployed. A Turso database named wikigems is available for development; the previous Cloudflare deployment has been removed. WikiGems is a fan-made, browser-based trading card game built from Wikipedia. Open a pack and you get five real Wikipedia articles, each rendered as a unique card. There are no reprints and no duplicate supplies: one article equals one card, globally.

Cards can be collected, used in quiz duels, and traded through the in-game exchange. Any unminted card can also be minted as a Metaplex Core NFT on Solana, at which point the 1-of-1 lives in the player's own wallet rather than the game database.

The project is a Solana-native reimagining of the WikiGems loop: packs, album, duels, exchange, and a rarity and stats system derived from the real Wikipedia page.

Monorepo foundations

The existing frontend and worker remain at the root. New private workspaces hold apps/server (TypeScript and Effect v4), packages/contracts (server contracts), and programs/wikigems (Rust Solana program). The new server runs separately with bun run dev:server; it is a foundation, not a replacement for the existing API. See architecture and local checks for boundaries, implementation status, and Solana build instructions.

Current web app

The Solid frontend provides passkey login, account/profile management and Wikipedia article search. Collection, marketplace, action and wallet routes currently display labeled previews. Pack, trade, duel and mint components remain in the codebase; the current routes do not expose the complete game loop described below.

Run bun run test:e2e for the isolated account, route, search and component browser checks. These checks use disposable data and a virtual passkey. The older test:mint and test:trade scripts target the earlier pack-based UI and require updating before they can verify the current app or a live provider.

The game

  • Packs — five unique articles per pack, one free pack every ten minutes, ten packs max.
  • Album — every card is a 1-of-1 claim. The archive refuses to issue an article twice.
  • Rarity — Common → Uncommon → Rare → Epic → Legendary → Mythic, based on real yearly pageviews.
  • Stats — attack is driven by readership; defense is driven by the depth of the article.
  • Duels — three questions generated from the descriptions of the cards in play.
  • Exchange — list unminted cards and swap them with other collectors. Ownership moves instantly.
  • Mint — connect Phantom, Solflare, or Backpack and mint an unminted card to your Solana wallet.

Solana ownership model

A card starts as an in-game 1-of-1 claim. Minting is optional and non-custodial:

  1. The player connects a Solana wallet and signs a message. The Worker verifies the Ed25519 signature and links the wallet address to the passkey account.
  2. The browser builds a Metaplex Core create transaction with the card's metadata URI. The player's wallet signs and pays the devnet fee.
  3. The browser sends the confirmed transaction signature to the Worker.
  4. The Worker verifies the transaction through the Solana RPC, checks the asset address appears in the transaction, and records the mint address in Turso.
  5. The card is marked On-chain and links to Solana Explorer.

The live build targets Solana Devnet. Minting requires a small amount of devnet SOL. If the wallet has none, the UI links to the official faucet. In-game swaps remain available for unminted cards, so the complete game is playable without a wallet.

Stack

Layer Choice
Runtime / package manager Bun 1.4.2 (pinned by Flox)
UI Solid 2 + DaisyUI 5 + TanStack Router (Solid) + Effect
Build Vite 8 + Solid plugin + Tailwind CSS 4
Domain / API composition Effect 4.0
Auth Better Auth 1.7 + @better-auth/passkey
Solana @solana/web3.js, Umi, Metaplex Core
Database Turso / libSQL through Kysely
Hosting Cloudflare Workers + Workers Static Assets
Toolchain pinning Flox

The domain layer uses Effect Schema for every client/server contract. API handlers are composed with Effect.gen, and the Solana verifier and Turso operations are wrapped in typed Effects.

Profile picture storage

Profile pictures are stored in the private R2 bucket wikigems-avatars, bound to the Worker as AVATARS. Turso stores the object key and the profile image URL. Image bytes and content type live in R2. The Worker checks the session before serving a picture.

Development uses the remote R2 bucket because the configured development database is hosted in Turso. Run bunx wrangler login if Cloudflare authentication is missing. The account tests use disposable SQLite and a local R2 emulator with remote bindings explicitly disabled. Run bun run test:account for storage tests and the passkey browser flow.

Uploads use immutable keys. A pending cleanup record is written before the R2 upload; the profile reference is published only after the object is stored. Replacements and account deletion queue old objects in the same database transaction. Cleanup runs after changes and through a Worker cron every 15 minutes. Failed deletions retain their records for retry; interrupted uploads become eligible after one hour. R2 and Turso are separate systems. A failed request can leave cleanup pending, and a lost SQL commit response can leave an update committed. Reload the Account page to read the current profile state after an error.

Migration 003_r2_avatars.sql clears existing profile pictures and removes the old base64, MIME, and version columns. Usernames and X.com links are preserved. The earlier migration is retained as history, and there is no fallback to database image storage.

Run locally

1. Activate the pinned environment

flox activate
bun install

Flox pins Bun, Node, Turso CLI, Wrangler, Solana CLI, Rust/Cargo, rustfmt, Clippy, SOPS, and age through the manifest and lockfile. Application dependencies are locked in bun.lock. Flox works on macOS and Linux; no separate Nix installation or system rebuild is needed for the development workflow.

2. Put your local settings in Keychain

On macOS, install envchain once:

brew install envchain

If you have the existing plaintext .env, import it without printing its contents:

bun run secrets:import
bun run secrets:check

The import leaves .env untouched. You can delete that file yourself after checking the app. For manual setup, changing a secret, and where the values live, follow the envchain tutorial.

3. Start the game

bun run dev

This command loads settings from the wikigems-dev-bundle Keychain namespace, uses the configured database, applies migrations, starts Wrangler on :8787, and starts Vite on :5173 with /api proxied to the Worker. With the local database URL http://127.0.0.1:8080, it also starts a local Turso server on :8080.

Open http://localhost:5173.

Use localhost, not 127.0.0.1: the default local passkey RP ID is localhost.

The game is fully testable without a wallet. The first account is created passkey-first. A virtual authenticator works in Chrome DevTools → WebAuthn, or via the included Playwright tests.

4. Optional: local Solana validator for minting

The mint flow can be tested end-to-end on a local validator with the Metaplex Core program cloned from mainnet. Flox installs solana-test-validator.

solana-test-validator \
  --reset \
  --ledger .solana-ledger \
  --rpc-port 8899 \
  --clone-upgradeable-program CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d \
  --url https://api.mainnet-beta.solana.com

The dev server already proxies /solana-rpc to 127.0.0.1:8899 and .env.development points the client at that proxy. Production builds ignore .env.development and use https://api.devnet.solana.com.

The local mint test uses a temporary signing bridge and a generated, locally funded wallet:

bun run test:mint

It performs signup, pack opening, album selection, wallet linking, a real Metaplex Core mint, and the Worker's transaction verification. A second test exercises the complete two-user exchange:

bun run test:trade

Useful commands

bun run dev            # configured Turso (or local server) + Wrangler + Vite
bun run dev:db         # local Turso only
bun run dev:worker     # Worker only
bun run dev:web        # Vite only
bun run db:migrate     # load Keychain settings and apply migrations
bun run db:generate    # emit a fresh Better Auth schema migration for review
bun run secrets:import # copy existing .env settings into Keychain, leaving the file alone
bun run secrets:check  # check Keychain settings without printing values
bun run secrets:set TURSO_AUTH_TOKEN # change one setting with hidden input
bun run typecheck
bun run build
bun run test:e2e       # passkey + pack + album smoke test

Install as an app

Production builds include a web app manifest, 192/512px icons (including a maskable icon), Apple touch metadata, and a service worker. An install offer appears on arrival. When the browser exposes its installation API, Install app opens the native dialog from your tap. The site also leaves the browser's automatic install promotion enabled.

Browsers control when that native dialog is available: HTTPS and installability criteria are required, and Chrome also applies engagement rules. A site cannot force the native dialog on first load or skip the user's confirmation. How to install provides browser-specific instructions while the native option is unavailable, including Share → Add to Home Screen on iPhone/iPad and File → Add to Dock in Safari on Mac. Account keeps an installation action available after the arrival offer is dismissed. Dismissal lasts for the current tab session; installed app windows hide the offer. A local installation hint is cleared when the browser reports a new install opportunity after uninstalling.

The installed app launches /play: signed-in users enter the game, and signed-out users go to /login. Signed-in visits to / and /login also open /play.

After the first online visit, the app shell can load offline. Signing in, syncing cards, trading, and minting require a connection. Authentication, game data, and wallet requests are never stored in the service worker cache. New versions activate after existing app windows close.

The service worker and installation UI are enabled in production builds. Vite development stays free of cached bundles. For local testing, run bun run build then bun run preview; localhost is a secure-context exception. Public hosting must use HTTPS and serve sw.js, manifest.webmanifest, and the icon files from this origin. Cloudflare's existing asset configuration serves those files and the security/cache headers in public/_headers.

Run bun run test:pwa for a disposable, non-incognito Chrome profile checking real browser installability diagnostics, the active worker, offline shell and cache boundaries. Install button choices are simulated at the browser API boundary; the checks do not install an OS application or prove browser promotion timing on a deployed domain.

Configuration

Local server settings share one password-protected Keychain item in the wikigems-dev-bundle envchain namespace. A launch reads that item once, so macOS asks once for the whole service. Development and database commands load them from Keychain and stop if required values are missing. They do not decrypt, create, or update .env. The launcher discards inherited project settings before asking envchain for them, so an old .env cannot supply missing credentials.

Wrangler receives only the declared secret names and configured variables from the process environment. The dev commands pass an empty env file to ignore both .env and .dev.vars. Vite still reads public VITE_ settings, including the checked-in .env.development. Never give a secret the VITE_ prefix. See the envchain tutorial.

The previous SOPS ciphertext, recipient configuration, and Nix modules remain as a recovery snapshot. Local startup no longer uses them. Changing Keychain values does not update that snapshot. Production secrets still need to be configured in Cloudflare.

Variable Purpose
TURSO_DATABASE_URL http://127.0.0.1:8080 locally, libsql://… in production
TURSO_AUTH_TOKEN Turso token; empty locally
BETTER_AUTH_SECRET Session/HMAC secret; at least 32 random bytes in production
BETTER_AUTH_URL Optional auth base URL; derived from the request when omitted
PASSKEY_RP_ID Optional WebAuthn RP ID; derived from the request host when omitted
PASSKEY_ORIGIN Optional pinned WebAuthn origin
SOLANA_RPC_URL Worker-side RPC used to verify mint transactions
SOLANA_CLUSTER devnet, localnet, or mainnet-beta, used for explorer links

Client-side configuration:

VITE_SOLANA_RPC_URL=/solana-rpc     # dev only; defaults to devnet in production
VITE_SOLANA_CLUSTER=localnet        # dev only; defaults to devnet in production

Database

The migrations are plain SQL and tracked exactly once in a private migration ledger table:

  • migrations/000_better_auth.sql — user, session, account, verification, passkey
  • migrations/001_game.sql — profiles, packs, cards, trades

Important invariants:

  • cards.articleId is UNIQUE. This is the database-level guarantee that one Wikipedia article is only ever one card.
  • Minted cards are locked from in-game trading; their ownership is now a wallet concern.
  • Pack stock and refill timing live on the user profile and are updated transactionally with a pack.
  • Trade settlement swaps both cards.ownerUserId values in one transaction.

Provision production Turso

turso auth login
turso db create wikigems

TURSO_URL="$(turso db show wikigems --url)"
TURSO_TOKEN="$(turso db tokens create wikigems)"

# Use the raw script for an explicitly supplied production environment;
# db:migrate deliberately reloads the Keychain development credentials.
TURSO_DATABASE_URL="$TURSO_URL" TURSO_AUTH_TOKEN="$TURSO_TOKEN" bun run scripts/migrate.ts

Deployment notes (for future releases)

flox activate
wrangler login

wrangler secret put TURSO_DATABASE_URL --name wikigems
wrangler secret put TURSO_AUTH_TOKEN --name wikigems
wrangler secret put BETTER_AUTH_SECRET --name wikigems

bun run deploy

wrangler.jsonc sets the devnet RPC and cluster as public Worker variables. The Worker serves dist/client, routes /api/* first, and falls back to the SPA for client routes. Auth origin and RP ID are derived from the incoming request, so passkeys work immediately on the generated workers.dev hostname. Set BETTER_AUTH_URL and PASSKEY_RP_ID explicitly for a custom domain.

The Content Security Policy allows Wikimedia images and the Solana devnet RPC while keeping scripts, fonts, and API calls same-origin.

Card generation

shared/featured.ts contains 40 hand-picked Wikipedia articles with real yearly pageview counts, fetched from the Wikipedia REST and pageview APIs. Packs draw mostly from this set plus random live Wikipedia articles. shared/card-engine.ts derives rarity, attack, defense, and category.

Regenerate the featured set with:

bun run scripts/fetch-featured.ts

Article text is available under CC BY-SA 4.0. Card images come from Wikimedia Commons. WikiGems is an independent fan project and is not affiliated with the Wikimedia Foundation.

Project map

src/pages/Landing.tsx        marketing page and card showcase
src/pages/Play.tsx           Wikipedia search and preview mint controls
src/components/GameCard.tsx  the card component
src/components/CardModal.tsx card detail + mint flow
src/components/PackOpening.tsx
src/components/DuelGame.tsx
src/lib/solana.ts            Phantom/Solflare/Backpack adapter, Umi mint, HTTP confirmation
src/lib/wallet.ts            browser wallet state and connection
worker/api.ts                Effect-composed game API
worker/wiki.ts               Wikipedia article + pageview ingestion
worker/solana.ts             server-side mint transaction verification
shared/card-engine.ts        rarity, stats, categories
shared/domain.ts             Effect schemas
migrations/                  Better Auth + game schema
scripts/                     dev orchestrator, migrations, e2e tests

Frontend architecture

The Solid web app shares domain rules and its validated, Effect-based API client with any future native app. Read the architecture and native integration guide for package ownership, usage and validation. Run bun run check:architecture to check these boundaries.

Component credits

Monetary displays use the Animated counter from Rare UI, by Swami Malode. Its license and attribution terms are preserved in third-party/rare-ui/LICENSE.

Optional email verification uses the OTP input from Rare UI, under the same credited license.

Action notifications use the Toast component from Rare UI, under the same credited license.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages