feat(rounds): gate voting by delegated Gnars votes at a fixed snapshot (#294)

* Gate round voting by delegated Gnars votes

* feat(rounds): gate voting by delegated Gnars votes at a fixed snapshot

Builds on xSatori's #115 (all UI/route/service structure is theirs):
rounds voting requires delegated Gnars voting power, enforced server-
side at vote submission.

One change on top: the power is read with getPastVotes at the round's
voting-open instant instead of live getVotes. Live votes let the same
Gnars vote once per re-delegation hop (A delegates to B, B votes, A
re-delegates to C, C votes — usage is tracked per wallet, so every hop
arrives fresh; on fixed_per_wallet each hop gets the FULL per-wallet
allotment). The checkpoint at votingStartsAt is immutable, so those
Gnars sat in exactly one wallet at that instant — the same snapshot
model the onchain governor uses, and the policy that comes with it:
delegating transfers the vote.

The Gnars token runs timestamp clock mode (ERC-6372), so the timepoint
is the round's votingStartsAt directly — no block derivation. A future
timepoint returns 0 without touching the chain (ERC-5805 would revert,
and an unopened round has no snapshot).

Co-authored-by: xSatori <99294685+xSatori@users.noreply.github.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: xSatori <99294685+xSatori@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

src/app/api/rounds/[slug]/voting-power/route.test.ts

@@ -0,0 +1,64 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getAddress } from "viem";
+import type { RoundWithSubmissions } from "@/features/rounds/types";
+
+vi.mock("@/services/rounds", () => ({
+  getPublicRoundBySlug: vi.fn(),
+  getRoundVoteUsage: vi.fn(),
+  getRoundVotingPower: vi.fn(),
+}));
+
+import { getPublicRoundBySlug, getRoundVoteUsage, getRoundVotingPower } from "@/services/rounds";
+import { GET } from "./route";
+
+const walletAddress = "0x39a7b6fa1597bb6657fe84e64e3b836c37d6f75d";
+
+const round: RoundWithSubmissions = {
+  id: "round-1",
+  slug: "clip-round",
+  title: "Clip Round",
+  description: "Round description",
+  content: "Round content",
+  image: "",
+  startsAt: "2026-06-01T00:00:00.000Z",
+  submissionsOpenAt: "2026-06-02T00:00:00.000Z",
+  votingStartsAt: "2026-06-03T00:00:00.000Z",
+  votingEndsAt: "2026-06-04T00:00:00.000Z",
+  endsAt: "2026-06-04T00:00:00.000Z",
+  active: true,
+  featured: false,
+  status: "published",
+  votingStrategy: "fixed_per_wallet",
+  votesPerWallet: 5,
+  winnerCount: 1,
+  maxSubmissionsPerWallet: 1,
+  createdAt: "2026-06-01T00:00:00.000Z",
+  updatedAt: "2026-06-01T00:00:00.000Z",
+  deletedAt: null,
+  submissions: [],
+  voteActivity: [],
+};
+
+describe("GET /api/rounds/[slug]/voting-power", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns votingPower, usedVotes, and remainingVotes", async () => {
+    vi.mocked(getPublicRoundBySlug).mockResolvedValueOnce(round);
+    vi.mocked(getRoundVotingPower).mockResolvedValueOnce(5);
+    vi.mocked(getRoundVoteUsage).mockResolvedValueOnce(2);
+
+    const response = await GET(
+      new Request(`https://gnars.com/api/rounds/clip-round/voting-power?wallet=${walletAddress}`),
+      { params: Promise.resolve({ slug: "clip-round" }) },
+    );
+
+    await expect(response.json()).resolves.toEqual({
+      walletAddress: getAddress(walletAddress),
+      votingPower: 5,
+      usedVotes: 2,
+      remainingVotes: 3,
+    });
+  });
+});

src/app/api/rounds/[slug]/voting-power/route.ts

@@ -0,0 +1,41 @@
+import { NextResponse } from "next/server";
+import { getAddress, isAddress } from "viem";
+import { getPublicRoundBySlug, getRoundVoteUsage, getRoundVotingPower } from "@/services/rounds";
+
+export async function GET(request: Request, { params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const wallet = new URL(request.url).searchParams.get("wallet");
+
+  try {
+    if (!isValidRoundSlug(slug)) {
+      return NextResponse.json({ error: "Use a valid round slug." }, { status: 400 });
+    }
+
+    if (!wallet || !isAddress(wallet)) {
+      return NextResponse.json({ error: "Use a valid wallet address." }, { status: 400 });
+    }
+
+    const walletAddress = getAddress(wallet);
+    const round = await getPublicRoundBySlug(slug);
+    if (!round) return NextResponse.json({ error: "Round not found." }, { status: 404 });
+
+    const [votingPower, usedVotes] = await Promise.all([
+      getRoundVotingPower(round, walletAddress),
+      getRoundVoteUsage(round.id, walletAddress),
+    ]);
+
+    return NextResponse.json({
+      walletAddress,
+      votingPower,
+      usedVotes,
+      remainingVotes: Math.max(votingPower - usedVotes, 0),
+    });
+  } catch (error) {
+    console.error("[rounds] voting power lookup failed", error);
+    return NextResponse.json({ error: "Unable to load voting power." }, { status: 500 });
+  }
+}
+
+function isValidRoundSlug(slug: string) {
+  return /^[a-z0-9-]+$/.test(slug);
+}

src/components/rounds/RoundDetailView.test.tsx

@@ -0,0 +1,22 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("thirdweb/react", () => ({
+  useActiveAccount: () => null,
+}));
+
+vi.mock("@/hooks/use-user-address", () => ({
+  useUserAddress: () => ({ address: undefined, isConnected: false }),
+}));
+
+vi.mock("@/i18n/navigation", () => ({
+  Link: "a",
+  useRouter: () => ({ refresh: vi.fn() }),
+}));
+
+import { canShowRoundVotingControls } from "./RoundDetailView";
+
+describe("RoundDetailView voting controls", () => {
+  it("does not enable voting controls when votingPower is 0", () => {
+    expect(canShowRoundVotingControls({ state: "voting_open", votingPower: 0 })).toBe(false);
+  });
+});

src/components/rounds/RoundDetailView.tsx

@@ -1,18 +1,25 @@
 "use client";
 
-import { useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import { ArrowLeft, ExternalLink, Minus, Plus } from "lucide-react";
 import { useActiveAccount } from "thirdweb/react";
 import { Button } from "@/components/ui/button";
 import { createRoundActionMessage } from "@/features/rounds/signature";
 import { getRoundState, getRoundStateLabel } from "@/features/rounds/state";
-import type { RoundSubmission, RoundWithSubmissions } from "@/features/rounds/types";
+import type { RoundState, RoundSubmission, RoundWithSubmissions } from "@/features/rounds/types";
 import { useUserAddress } from "@/hooks/use-user-address";
-import { Link } from "@/i18n/navigation";
+import { Link, useRouter } from "@/i18n/navigation";
 import { cn } from "@/lib/utils";
 import { RoundStatusPill } from "./RoundStatusPill";
 import { RoundTimeline } from "./RoundTimeline";
 
+type RoundVotingPower = {
+  walletAddress: string;
+  votingPower: number;
+  usedVotes: number;
+  remainingVotes: number;
+};
+
 export function RoundDetailView({
   round,
   databaseConfigured,
@@ -23,16 +30,70 @@ export function RoundDetailView({
   const state = getRoundState(round);
   const { address, isConnected } = useUserAddress();
   const account = useActiveAccount();
+  const router = useRouter();
   const [allocations, setAllocations] = useState<Record<string, number>>({});
   const [message, setMessage] = useState("");
   const [isVoting, setIsVoting] = useState(false);
-  const votingPower = state === "voting_open" && isConnected ? round.votesPerWallet : 0;
+  const [votingPowerStatus, setVotingPowerStatus] = useState<RoundVotingPower | null>(null);
+  const [isLoadingVotingPower, setIsLoadingVotingPower] = useState(false);
+  const [votingPowerError, setVotingPowerError] = useState("");
+  const votingPower = state === "voting_open" && isConnected ? votingPowerStatus?.votingPower || 0 : 0;
+  const remainingVotes =
+    state === "voting_open" && isConnected ? votingPowerStatus?.remainingVotes || 0 : 0;
   const allocatedVotes = useMemo(
     () => Object.values(allocations).reduce((total, count) => total + count, 0),
     [allocations],
   );
+  const availableVotes = Math.max(remainingVotes - allocatedVotes, 0);
+  const showVotingControls = canShowRoundVotingControls({ state, votingPower });
+  const votingStatusMessage = getVotingStatusMessage({
+    isConnected,
+    isLoadingVotingPower,
+    votingPowerError,
+    votingPower,
+    availableVotes,
+    remainingVotes,
+  });
   const winners = state === "ended" ? round.submissions.slice(0, round.winnerCount) : [];
 
+  const fetchVotingPower = useCallback(async () => {
+    if (state !== "voting_open" || !isConnected || !address) {
+      setVotingPowerStatus(null);
+      setVotingPowerError("");
+      return;
+    }
+
+    setIsLoadingVotingPower(true);
+    setVotingPowerError("");
+
+    try {
+      const response = await fetch(
+        `/api/rounds/${round.slug}/voting-power?wallet=${encodeURIComponent(address)}`,
+      );
+      const result = await response.json();
+      if (!response.ok) throw new Error(result.error || "Unable to load voting power.");
+
+      setVotingPowerStatus(result as RoundVotingPower);
+    } catch (error) {
+      setVotingPowerStatus(null);
+      setVotingPowerError(error instanceof Error ? error.message : "Unable to load voting power.");
+    } finally {
+      setIsLoadingVotingPower(false);
+    }
+  }, [
+    address,
+    isConnected,
+    round.slug,
+    setIsLoadingVotingPower,
+    setVotingPowerError,
+    setVotingPowerStatus,
+    state,
+  ]);
+
+  useEffect(() => {
+    void fetchVotingPower();
+  }, [fetchVotingPower]);
+
   const updateAllocation = (submissionId: string, delta: number) => {
     setMessage("");
     setAllocations((current) => {
@@ -44,13 +105,13 @@ export function RoundDetailView({
       );
       return {
         ...current,
-        [submissionId]: Math.min(next, Math.max(votingPower - totalWithoutCurrent, 0)),
+        [submissionId]: Math.min(next, Math.max(remainingVotes - totalWithoutCurrent, 0)),
       };
     });
   };
 
   const submitVotes = async () => {
-    if (!address || !account || allocatedVotes <= 0) return;
+    if (!address || !account || allocatedVotes <= 0 || allocatedVotes > remainingVotes) return;
 
     setIsVoting(true);
     setMessage("");
@@ -83,7 +144,9 @@ export function RoundDetailView({
       if (!response.ok) throw new Error(result.error || "Unable to submit votes.");
 
       setAllocations({});
-      setMessage("Votes submitted. Refreshing will show the updated totals.");
+      setMessage("Votes submitted.");
+      await fetchVotingPower();
+      router.refresh();
     } catch (error) {
       setMessage(error instanceof Error ? error.message : "Unable to submit votes.");
     } finally {
@@ -190,15 +253,19 @@ export function RoundDetailView({
             <div className="flex flex-col gap-3 md:flex-row md:items-center md:justify-between">
               <div>
                 <h2 className="text-xl font-semibold tracking-tight">Voting</h2>
-                <p className="mt-1 text-sm text-muted-foreground">
-                  {isConnected
-                    ? `${Math.max(votingPower - allocatedVotes, 0)} of ${votingPower} votes remaining`
-                    : "Connect your wallet to vote."}
-                </p>
+                <p className="mt-1 text-sm text-muted-foreground">{votingStatusMessage}</p>
               </div>
               <Button
                 onClick={submitVotes}
-                disabled={!databaseConfigured || !isConnected || allocatedVotes <= 0 || isVoting}
+                disabled={
+                  !databaseConfigured ||
+                  !isConnected ||
+                  !showVotingControls ||
+                  allocatedVotes <= 0 ||
+                  allocatedVotes > remainingVotes ||
+                  isVoting ||
+                  isLoadingVotingPower
+                }
               >
                 {isVoting ? "Submitting..." : "Submit votes"}
               </Button>
@@ -221,10 +288,11 @@ export function RoundDetailView({
                   key={submission.id}
                   submission={submission}
                   rank={index + 1}
-                  showVoting={state === "voting_open" && votingPower > 0}
+                  showVoting={showVotingControls}
                   allocation={allocations[submission.id] || 0}
                   onMinus={() => updateAllocation(submission.id, -1)}
                   onPlus={() => updateAllocation(submission.id, 1)}
+                  disablePlus={availableVotes <= 0}
                 />
               ))}
             </div>
@@ -285,13 +353,15 @@ function SubmissionCard({
   allocation,
   onMinus,
   onPlus,
+  disablePlus,
 }: {
   submission: RoundSubmission;
   rank: number;
   showVoting: boolean;
   allocation: number;
   onMinus: () => void;
   onPlus: () => void;
+  disablePlus?: boolean;
 }) {
   return (
     <article
@@ -357,7 +427,7 @@ function SubmissionCard({
               <span className="w-6 text-center text-sm font-semibold tabular-nums">
                 {allocation}
               </span>
-              <Button size="icon-sm" variant="outline" onClick={onPlus}>
+              <Button size="icon-sm" variant="outline" onClick={onPlus} disabled={disablePlus}>
                 <Plus className="size-3.5" />
               </Button>
             </div>
@@ -373,3 +443,38 @@ function getVotingStrategyLabel(round: RoundWithSubmissions) {
   if (round.votingStrategy === "one_per_nft") return "1 vote per Gnars NFT";
   return `${round.votesPerWallet} votes per wallet`;
 }
+
+export function canShowRoundVotingControls({
+  state,
+  votingPower,
+}: {
+  state: RoundState;
+  votingPower: number;
+}) {
+  return state === "voting_open" && votingPower > 0;
+}
+
+function getVotingStatusMessage({
+  isConnected,
+  isLoadingVotingPower,
+  votingPowerError,
+  votingPower,
+  availableVotes,
+  remainingVotes,
+}: {
+  isConnected: boolean;
+  isLoadingVotingPower: boolean;
+  votingPowerError: string;
+  votingPower: number;
+  availableVotes: number;
+  remainingVotes: number;
+}) {
+  if (!isConnected) return "Connect your wallet to vote.";
+  if (isLoadingVotingPower) return "Checking delegated Gnars voting power...";
+  if (votingPowerError) return votingPowerError;
+  if (votingPower <= 0) {
+    return "This wallet needs at least 1 delegated Gnars DAO vote to vote in this round.";
+  }
+
+  return `${availableVotes} of ${remainingVotes} votes remaining`;
+}