Quartz 4

guild-token-design

13 min read

GUILD Token Design

SPL token backing the Guild cooperative loyalty network. Ticker: GUILD. User-facing name: Guild Points (GP).

Core concept

GP is the universal currency of the indie shop cooperative network. Earn at any guild, spend at any guild. The analogy is Gil from Final Fantasy — works in every shop in every town. Also maps to credit card loyalty points transferable across partners (Amex → airline miles → hotel points).

Crypto is infrastructure, not interface. Members see a points balance. Shops see automatic settlement. Neither needs to know it’s Solana.

Token mechanics

Minting (earning GP)

GP is minted when a member earns points. Sources:

  • Purchase — 1 cent = 1 GP base, scaled by tier earn multiplier
  • Check-in — flat 100 GP (configurable per guild)
  • Event attendance — configurable per event
  • Promotion/bonus — manual award by guild staff

Only registered guilds can mint. Each mint instruction includes a source enum and a nonce (derived from Payload transaction ID) for idempotency.

Burning (spending GP)

GP is burned on redemption:

  • Store credit — redemption rate set per-shop (TBD). Tier multiplier makes it cheaper for subscribed members.
  • Experiences — guild-specific GP pricing
  • Merch — guild-specific GP pricing
  • Digital perks — guild-specific GP pricing

Any guild can burn from a member’s account. The burn is the settlement — no invoicing needed.

Not a speculative asset

GP is a loyalty currency, not a cryptocurrency in the speculative sense. There is no floating exchange rate or DEX listing. The earn rate is fixed by protocol (1 cent = 1 GP). The redemption rate is set per-shop as a business decision. The value is backed by the goods and services the network offers.

Multiplier economics: mint universal, redeem local

The principle

Minting is universal. Every shop in the network mints at the same rate: 1 cent spent = 1 GP. No exceptions, no multipliers. This is the network agreement — GP supply is directly proportional to real commerce. No shop can inflate it.

Redemption is local. Each shop sets its own redemption rates for its own tier members. The tier multiplier applies at the point of spending, not earning. The shop that collects membership fees is the shop that offers the better rate. The cost is borne by the shop that benefits from the subscription revenue.

Example: Dungeon Books tiers

Base redemption rate TBD (e.g., R GP = $1). Tier multiplier makes GP go further:

TierMonthly feeEffective rate$1 store credit costs
Non-member$0R GP = $1R GP
Bronze$10R/1.5 GP = $167% of base
Silver$25R/2 GP = $150% of base
Gold$50R/2.5 GP = $140% of base
Mithril$100R/3 GP = $133% of base

A different shop sets its own base rate and tier multipliers. Each shop controls its own economics.

Cross-guild scenario

A Gold member at Dungeon Books earns 2,000 GP from a $20 purchase. They walk into a game store in Brooklyn where they have no membership.

  • At Dungeon Books (Gold): 2,000 GP stretches 2.5x (tier multiplier on redemption)
  • At the game store (non-member): 2,000 GP redeems at that shop’s base rate
  • If they sign up for Bronze at the game store: 2,000 GP stretches 1.5x at that shop

Exact dollar values depend on each shop’s base redemption rate.

No cross-guild subsidy. The game store never honors inflated GP it didn’t benefit from. The member’s GP is portable at base rate everywhere, and premium at their home guilds.

Incentive structure

  • Members: be a member where you shop most — that’s where your GP stretches furthest
  • Shops: offer compelling tiers to lock in local loyalty — the membership fee funds your better redemption rates
  • Network: grows because portability is free (base rate) and every shop benefits from foot traffic driven by GP earned elsewhere

This mirrors credit card loyalty: you earn United miles on any purchase, but they’re worth more when you fly United. The earn rate is universal. The value depends on where you redeem.

On-chain vs off-chain

  • On-chain: GP balance (SPL token). Mint and burn only. The chain knows how much GP a member has.
  • Off-chain (Postgres): Tier membership, redemption rate calculation, the actual store credit issuance. The shop’s tier system is its own business logic, not a protocol concern.

The Anchor program doesn’t need to know about tiers at all. It mints GP (flat rate) and burns GP (any amount the shop requests). The redemption math happens in the shop’s server before calling burn_gp.

Redemption types

Two modes:

  1. Store credit (GP → dollars) — tier multiplier applies. Gold member at their home shop gets 2.5x the purchasing power of a non-member. The shop subsidizes the better rate from membership revenue.
  2. Everything else (GP → item) — flat GP price set by the shop. Discord roles, digital goods, experiences, merch. No multiplier. Near-zero marginal cost to the shop, so no subsidy concern. Shops can let members burn GP on digital perks without it costing real money.

Coexistence with existing points

Dungeon Books already has a production points system with tier earn multipliers (Gold = 2.5x). Existing members have multiplied points balances. No migration needed.

Points and GP coexist as separate systems:

  • Points (Postgres) — shop-local legacy currency. Earned with tier multiplier. Redeemed at 100 pts = $1 at that shop only. Existing behavior, unchanged.
  • GP (on-chain) — network currency. Minted at base rate (1 cent = 1 GP, no multiplier). Redeemable at any guild with redeem-side tier multiplier.

Dual-write in awardPoints(): write multiplied points to Postgres (existing), mint base-rate GP to Solana (new, additive). No breaking changes.

Backfill: Mint each existing member’s total historical GP as a single lump sum (sum of totalMoney across all purchases). No per-transaction replay — Solana transactions carry the block timestamp, not a backdated one. Postgres is the historical record. On-chain GP starts from deployment day, with balances seeded from history.

Over time, points may sunset in favor of GP-only with redeem-side multiplier. Post-hackathon decision.

Anchor program

Program: guild_protocol

Accounts:
  Network          PDA["network"]                    — admin, global config, mint authority
  Guild            PDA["guild", authority_pubkey]     — registered shop, name, element, mint cap
  MemberAccount    Associated Token Account           — standard SPL token account per member

Instructions:
  initialize_network()                — one-time setup, creates mint
  register_guild(name, element)       — shop joins network, gets constrained mint authority
  mint_gp(member, amount, source, nonce) — guild mints GP to member (purchase/checkin/event)
  burn_gp(member, amount, redemption_type) — guild burns GP on redemption

Key constraints

  • Mint authority: Only the Network PDA holds true mint authority. Guilds call mint_gp which the program validates — registered guild, within rate limits, valid source.
  • Rate limiting: Optional per-guild daily/weekly mint cap to prevent abuse. Configurable by network admin.
  • Idempotency: nonce field prevents double-minting from retries. PDA[“receipt”, guild, nonce] tracks processed mints.
  • No member wallets required. Server manages associated token accounts. Members can optionally link a wallet later to self-custody.

Integration with existing codebase

Dual-write flow (purchase)

Square webhook → payment.updated
  → Create Purchase in Postgres
  → Award points in Postgres (with tier multiplier): 5,000 pts
  → Award XP in Postgres (with buff multiplier): 10,000 XP
  → Mint GP on Solana (base rate only): 2,000 GP  [fire-and-forget]
  → Sync to Square custom attributes

Dual-write flow (check-in)

NFC tap → kiosk server action
  → Create CheckIn in Postgres
  → Award XP in Postgres: 100 XP
  → Mint GP on Solana: 100 GP  [fire-and-forget]
  → Discord notification

Redemption flow

Member redeems in portal
  → Deduct points in Postgres: -5,000 pts
  → Burn GP on Solana: matching amount  [fire-and-forget]
  → Create Square store credit (if store_credit type)

Failure handling

Solana writes are fire-and-forget. If the Solana write fails, Postgres is still authoritative. A reconciliation job can replay missed writes from the Postgres ledger. The on-chain state is eventually consistent with Postgres, not the other way around.

File structure (planned)

programs/guild-protocol/
  Anchor.toml
  Cargo.toml
  src/
    lib.rs              — program entrypoint
    instructions/
      initialize.rs     — network setup
      register_guild.rs — guild registration
      mint_gp.rs        — minting with validation
      burn_gp.rs        — redemption burning
    state/
      network.rs        — Network account
      guild.rs          — Guild account
      receipt.rs        — Mint receipt (idempotency)
    error.rs            — custom errors

src/lib/solana/
  client.ts             — Connection, program ID, keypair loading
  instructions.ts       — Typed wrappers for Anchor instructions
  dual-write.ts         — Fire-and-forget helpers for loyalty.ts and check-in.ts
  reconcile.ts          — Replay missed writes from Postgres ledger

What this is NOT

  • Not a speculative token. No DEX listing. No liquidity pools. No yield farming.
  • Not a stablecoin. It’s backed by the goods/services of the network, not by collateral.
  • Not requiring member wallets. Server-managed until a member chooses to self-custody.
  • Not replacing Postgres. The game layer (XP, levels, classes) stays off-chain. GP is the only on-chain primitive.

Open questions

Protocol design

  • Who controls register_guild? Self-register (permissionless) or network approval (permissioned)?

    • Lean permissioned for now. A rogue shop minting GP is printing money the network honors. At early stage you’re onboarding shops personally anyway — the manifesto’s canvassing plan is hand-to-hand. Permissionless is the endgame vision but premature when 5 shops are on the network and one bad actor can tank trust. Start with admin-approved registration, add permissionless later when there’s enough volume that rate limits and reputation systems can do the policing instead of you.

  • What happens when a shop leaves the network or goes under?

    • Nothing should change for members — GP they hold is GP they hold. The guild’s mint authority gets revoked (no new GP from that shop) but existing tokens stay valid. This is a feature of on-chain: the tokens exist independently of the minting guild. If you did this in Postgres, a shop leaving would orphan all the points they issued. On-chain, the tokens just… are. This is actually a good slide in the pitch.

  • Mint rate limits?

    • Lean toward soft limits with alerts rather than hard caps. A hard cap at $10K/day punishes a shop that runs a big event weekend. Better: flag anomalies (shop minting 10x their rolling average) for network admin review. The real protection is that registration is permissioned — you know the shops, you can revoke. Hard caps are for the permissionless future when you don’t know every shop personally.

Economics

  • Net-negative shops (redeem more GP than they mint — members earned elsewhere, spend here).

    • This is the “popular destination” problem. A shop that’s great at attracting visitors but low on purchase volume becomes a GP sink. Two takes: (a) that shop is getting foot traffic it wouldn’t otherwise have, and foot traffic converts to purchases — the GP redemption is a customer acquisition cost. (b) If it doesn’t convert, the shop can raise its base redemption rate (make GP worth less per dollar) to make cross-guild redemption less attractive. The shop controls its own rates. If being a GP redemption destination isn’t working for them, they adjust. Market forces, not protocol rules.

  • Can shops buy GP to fund promotions?

    • Yes, and this should be a first-class feature. “Double GP weekend” means the shop mints extra GP funded by its own marketing budget. This is how credit card issuers fund bonus categories — Chase pays for 5x on groceries, not the grocery store. The mint instruction already takes an amount and source — add a promotion source type. The shop pays the network (in dollars or SOL) for the right to mint promotional GP. This is also a revenue line for the platform.

  • Does the network take a cut?

    • Lean toward a cut on burns (redemption), not mints. Taxing mints penalizes earning and feels punitive to members. Taxing burns is a transaction fee on the settlement — the shop is converting GP to real-dollar store credit, and the network takes a small percentage for providing the infrastructure. This is the Visa interchange model: the merchant pays the fee, not the cardholder. Keep it small (1-2%) so shops don’t route around the network.

Member experience

  • Source of truth for GP balance — Postgres or on-chain read?

    • Postgres, synced from chain events. Direct on-chain reads add latency to every page load and create a hard dependency on Solana RPC availability. Write to chain, listen for confirmation, update Postgres. The portal reads Postgres. If the chain is down, the portal still works — members see their last-known balance. Reconciliation job catches drift. Same pattern as the existing Square sync: Square is the source of truth for purchases, but Guild reads from its own DB.

  • When would a member want to self-custody?

    • Honestly, most won’t. The bookstore’s customers are not crypto natives. Self-custody is for the edge case: a member who leaves the network entirely and wants to prove their GP balance to a new network, or a power user who wants to interact with GP in a DeFi context (unlikely but possible). Build it as a “link wallet” option in settings, don’t push it. The real audience for self-custody is the hackathon judges — it demonstrates that the system can be trustless even if most users choose convenience.

  • How to show “your GP is worth more here” without “worth less everywhere else”?

    • Frame it as a perk, not a comparison. “Gold members: your GP goes 2.5x further here.” Don’t show the base rate next to it. The member portal at Dungeon Books shows “50 here but only 20 store credit available — become a member for more.” Positive framing per-shop, never cross-shop comparison.

Hackathon-specific

  • Second guild for demo?

    • Fictional, seeded on devnet. A real partner shop would be better but you don’t have one onboarded yet and you can’t wait. A game store makes the most sense — Fire/Warrior element, “Dragon’s Hoard Games” or similar. Seed it with a handful of fictional members and GP transactions. The demo flow: show a member earning GP at Dungeon Books, then redeeming at Dragon’s Hoard, settlement visible on-chain. Two guilds is enough to prove the network concept.

  • Open-source scope?

    • Open-source the Anchor program and a TypeScript SDK for interacting with it. Keep the Next.js app private — it has PII handling, Stripe/Square integration, business logic that’s your competitive advantage. The Anchor program + SDK is what composes with the Solana ecosystem (other devs can build on the GUILD protocol). The judges care about composability of the on-chain primitive, not your admin panel.

  • Solo or team?

    • Solo is fine given the timeline. Bringing someone in means onboarding them on Guild’s architecture, the RPG design, the token model — that’s a week of context transfer. The strongest version of this submission is depth of vision from one person who built the whole thing, not breadth from a team that assembled for a hackathon. If you know a Rust/Anchor dev who can pair on the program without needing context on the business, that’s the one exception worth considering.

Graph View

Backlinks