Feat/onchain bounty status

.env.example

@@ -0,0 +1,3 @@
+NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.org
+NEXT_PUBLIC_BOUNTY_CONTRACT_ID=contract_id
+NEXT_PUBLIC_STELLAR_EXPLORER_URL=https://stellar.expert/explorer/testnet

.gitignore

@@ -31,7 +31,7 @@ yarn-error.log*
 .pnpm-debug.log*
 
 # env files (can opt-in for committing if needed)
-.env*
+.env
 
 # vercel
 .vercel

PR_147.md

@@ -0,0 +1,76 @@
+# feat: implement on-chain bounty status sync and event listener (#147)
+
+## Summary
+
+Closes #147. Implements real-time on-chain bounty state syncing by polling Stellar RPC for Soroban contract events, reading contract state directly, and tracking transaction confirmation lifecycle.
+
+---
+
+## Changes
+
+### New files
+
+| File                                         | Purpose                                                                                                           |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `lib/contracts/event-listener.ts`            | Singleton poller that queries Stellar RPC for contract events and dispatches React Query cache invalidations      |
+| `hooks/use-onchain-bounty.ts`                | Per-bounty hook that reads state directly from the contract and compares it with GraphQL data to detect conflicts |
+| `hooks/use-transaction-status.ts`            | Hook that tracks a submitted transaction from `pending` → `confirmed` → `finalized` with Stellar Explorer links   |
+| `components/bounty/onchain-status-badge.tsx` | Badge component that shows verification state and surfaces status conflicts with a tooltip                        |
+
+### Dependencies added
+
+- `@stellar/stellar-sdk` — Soroban RPC client, XDR parsing, `scValToNative`
+
+---
+
+## How it works
+
+### Contract Event Poller (`lib/contracts/event-listener.ts`)
+
+- Polls `NEXT_PUBLIC_STELLAR_RPC_URL` every **6 s** using `rpc.Server.getEvents()`
+- Filters by `NEXT_PUBLIC_BOUNTY_CONTRACT_ID`
+- Parses XDR topics to typed `ParsedContractEvent` objects for all 9 event types
+- Calls `QueryClient` cache invalidations scoped to affected bounty keys
+- Exposes `contractEventPoller.start(queryClient)` / `.stop()` / `.subscribe(cb)`
+
+### On-Chain Bounty Hook (`hooks/use-onchain-bounty.ts`)
+
+- Fetches `BountyStatus` storage entry from contract using `rpc.Server.getContractData()`
+- Subscribes to `contractEventPoller` to receive push updates for the specific bounty
+- Maps GraphQL status → on-chain enum for cross-layer comparison
+- Returns `consistencyState`: `consistent | conflict | unverified | loading`
+
+### Transaction Status Hook (`hooks/use-transaction-status.ts`)
+
+- Call `track(hash)` after sending any Stellar transaction
+- Polls `rpc.Server.getTransaction()` every **3 s** up to 40 attempts (≈ 2 min)
+- Status progression: `idle → pending → confirmed → finalized` (or `failed / not_found`)
+- Returns `explorerUrl` pointing to Stellar Expert
+
+### On-Chain Status Badge (`components/bounty/onchain-status-badge.tsx`)
+
+- Mounts on any bounty detail page: `<OnChainStatusBadge bountyId={id} showConflictDetails />`
+- Renders a shield icon: green ✓ consistent, amber ⚠ conflict, grey – unverified
+- Tooltip shows ledger number, both statuses when conflicting, and links to explorer
+
+---
+
+## Environment variables required
+
+```env
+NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.org
+NEXT_PUBLIC_BOUNTY_CONTRACT_ID=<your_contract_id>
+NEXT_PUBLIC_STELLAR_EXPLORER_URL=https://stellar.expert/explorer/testnet
+```
+
+---
+
+## Proof of build
+
+
+## Acceptance criteria checklist
+
+- [x] Contract events trigger UI updates (via `contractEventPoller` → query invalidation)
+- [x] On-chain status readable for any bounty (`useOnChainBounty`)
+- [x] Transaction confirmation tracked after submission (`useTransactionStatus`)
+- [x] Status conflicts between GraphQL and on-chain detected and surfaced (`OnChainStatusBadge`)

components/bounty/onchain-status-badge.tsx

@@ -0,0 +1,149 @@
+"use client";
+
+import { cn } from "@/lib/utils";
+import {
+  useOnChainBounty,
+  type ConsistencyState,
+  type OnChainStatus,
+} from "@/hooks/use-onchain-bounty";
+import {
+  ExternalLink,
+  ShieldCheck,
+  ShieldAlert,
+  ShieldOff,
+  Loader2,
+} from "lucide-react";
+import { Badge } from "@/components/ui/badge";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+
+interface OnChainStatusBadgeProps {
+  bountyId: string;
+  className?: string;
+  showConflictDetails?: boolean;
+}
+
+const statusLabels: Record<OnChainStatus, string> = {
+  open: "Open",
+  in_progress: "In Progress",
+  submitted: "Submitted",
+  approved: "Approved",
+  claimed: "Claimed",
+  cancelled: "Cancelled",
+  unknown: "Unknown",
+};
+
+const consistencyConfig: Record<
+  ConsistencyState,
+  {
+    icon: React.ReactNode;
+    label: string;
+    badgeClass: string;
+    tooltipText: string;
+  }
+> = {
+  loading: {
+    icon: <Loader2 className="size-3 animate-spin" />,
+    label: "Verifying",
+    badgeClass: "border-muted-foreground/30 text-muted-foreground",
+    tooltipText: "Checking on-chain state…",
+  },
+  consistent: {
+    icon: <ShieldCheck className="size-3" />,
+    label: "Verified on-chain",
+    badgeClass: "border-emerald-500/60 text-emerald-500 bg-emerald-500/10",
+    tooltipText: "On-chain status matches off-chain data.",
+  },
+  conflict: {
+    icon: <ShieldAlert className="size-3" />,
+    label: "Status conflict",
+    badgeClass: "border-amber-500/60 text-amber-500 bg-amber-500/10",
+    tooltipText:
+      "On-chain status differs from the database. On-chain is the source of truth.",
+  },
+  unverified: {
+    icon: <ShieldOff className="size-3" />,
+    label: "Not verified",
+    badgeClass: "border-muted-foreground/30 text-muted-foreground",
+    tooltipText: "On-chain status could not be verified.",
+  },
+};
+
+export function OnChainStatusBadge({
+  bountyId,
+  className,
+  showConflictDetails = false,
+}: OnChainStatusBadgeProps) {
+  const { consistencyState, onChainData, graphqlBounty, explorerUrl } =
+    useOnChainBounty(bountyId);
+
+  const config = consistencyConfig[consistencyState];
+
+  return (
+    <TooltipProvider delayDuration={300}>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <div className={cn("flex items-center gap-1.5", className)}>
+            <Badge
+              variant="outline"
+              className={cn(
+                "flex items-center gap-1 text-xs font-medium px-2 py-0.5 cursor-default select-none",
+                config.badgeClass,
+              )}
+            >
+              {config.icon}
+              <span>{config.label}</span>
+            </Badge>
+
+            {explorerUrl && (
+              <a
+                href={explorerUrl}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="text-muted-foreground hover:text-foreground transition-colors"
+                aria-label="View on Stellar Explorer"
+              >
+                <ExternalLink className="size-3" />
+              </a>
+            )}
+          </div>
+        </TooltipTrigger>
+
+        <TooltipContent className="max-w-xs text-xs" side="bottom">
+          <p>{config.tooltipText}</p>
+
+          {consistencyState === "conflict" && showConflictDetails && (
+            <div className="mt-1.5 space-y-0.5 border-t border-border/50 pt-1.5">
+              {onChainData?.status !== "unknown" && (
+                <p>
+                  <span className="text-muted-foreground">On-chain: </span>
+                  <span className="font-medium text-foreground">
+                    {statusLabels[onChainData!.status]}
+                  </span>
+                </p>
+              )}
+              {graphqlBounty && (
+                <p>
+                  <span className="text-muted-foreground">Database: </span>
+                  <span className="font-medium text-foreground">
+                    {graphqlBounty.status}
+                  </span>
+                </p>
+              )}
+            </div>
+          )}
+
+          {onChainData?.ledger && (
+            <p className="mt-1 text-muted-foreground">
+              Ledger #{onChainData.ledger}
+            </p>
+          )}
+        </TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  );
+}