@gatedpath/frontend-kit 0.1.0

package/dist/styles.css

@@ -0,0 +1,100 @@
+/* @gatedpath/frontend-kit default style.
+   Every colour, radius and duration comes from the site's design tokens (site/design/tokens.css,
+   12 September 2026) through var() with that token's light value as the fallback, so the kit
+   looks right on its own and picks up the site's dark theme when tokens.css is loaded. Load this
+   file or don't: the components only carry class names. */
+
+.rb-elig {
+  font-family: var(--sl-font, 'Readex Pro', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif);
+  color: var(--rb-color-text, #283A46);
+  background: var(--rb-color-surface, #EFF3F6);
+  border: 1px solid var(--rb-color-hairline, #DFE7EC);
+  border-left: 4px solid var(--rb-color-hairline-strong, #848B91);
+  border-radius: var(--rb-radius-lg, 10px);
+  padding: var(--rb-space-4, 1rem) var(--rb-space-5, 1.25rem);
+  margin: var(--rb-space-4, 1rem) 0;
+  line-height: var(--sl-line-height, 1.6);
+  transition: border-color var(--rb-duration-base, 250ms) var(--rb-ease-standard, ease);
+}
+.rb-elig-title {
+  margin: 0 0 var(--rb-space-2, 0.5rem);
+  font-weight: var(--rb-weight-strong, 600);
+  color: var(--rb-color-heading, #283A46);
+}
+.rb-elig-body { margin: 0 0 var(--rb-space-2, 0.5rem); }
+.rb-elig-muted, .rb-elig-last-checked, .rb-elig-gas {
+  color: var(--rb-color-text-muted, #4C6B80);
+  font-size: var(--sl-text-sm, 0.875rem);
+  margin: var(--rb-space-2, 0.5rem) 0 0;
+}
+.rb-elig-steps { margin: 0 0 var(--rb-space-2, 0.5rem); padding-left: 1.25rem; }
+.rb-elig-steps li { margin: var(--rb-space-1, 0.25rem) 0; }
+.rb-elig a { color: var(--rb-color-accent, #0F766E); }
+.rb-elig a:hover { color: var(--rb-color-accent-high, #115E59); }
+.rb-elig code {
+  font-family: var(--sl-font-mono, 'JetBrains Mono', ui-monospace, Menlo, monospace);
+  font-size: var(--sl-text-code, 0.875rem);
+  background: var(--rb-color-code-bg, #F4F4F4);
+  color: var(--rb-color-code-text, #283A46);
+  padding: 0 0.3em;
+  border-radius: var(--rb-radius-sm, 3px);
+}
+
+/* One accent per state, all from the token file's status colours. */
+.rb-elig-disconnected { border-left-color: var(--rb-color-hairline-strong, #848B91); }
+.rb-elig-checking { border-left-color: var(--rb-color-hairline-strong, #848B91); opacity: 0.85; }
+.rb-elig-unverified {
+  border-left-color: var(--rb-color-caution-border, #B45309);
+  background: var(--rb-color-caution-bg, #FEF3C7);
+  color: var(--rb-color-caution-text, #78350F);
+}
+.rb-elig-unverified .rb-elig-title, .rb-elig-unverified .rb-elig-muted { color: inherit; }
+.rb-elig-ineligible {
+  border-left-color: var(--rb-color-danger-border, #B91C1C);
+  background: var(--rb-color-danger-bg, #FEE2E2);
+  color: var(--rb-color-danger-text, #991B1B);
+}
+.rb-elig-ineligible .rb-elig-title, .rb-elig-ineligible .rb-elig-muted { color: inherit; }
+.rb-elig-eligible {
+  border-left-color: var(--rb-color-tip-border, #0F766E);
+  background: var(--rb-color-tip-bg, #CCFBF1);
+  color: var(--rb-color-tip-text, #134E4A);
+}
+.rb-elig-eligible .rb-elig-title { color: inherit; }
+.rb-elig-expiring {
+  border-left-color: var(--rb-color-caution-border, #B45309);
+  background: var(--rb-color-caution-bg, #FEF3C7);
+  color: var(--rb-color-caution-text, #78350F);
+}
+.rb-elig-expiring .rb-elig-title { color: inherit; }
+.rb-elig-error {
+  border-left-color: var(--rb-color-danger-border, #B91C1C);
+  background: var(--rb-color-danger-bg, #FEE2E2);
+  color: var(--rb-color-danger-text, #991B1B);
+}
+.rb-elig-error .rb-elig-title { color: inherit; }
+
+.rb-elig-button {
+  font: inherit;
+  font-size: var(--sl-text-sm, 0.875rem);
+  font-weight: var(--rb-weight-button, 600);
+  min-height: var(--rb-target-min, 44px);
+  padding: 0 var(--rb-space-4, 1rem);
+  border-radius: var(--rb-radius-sm, 3px);
+  border: 1px solid var(--rb-color-accent, #0F766E);
+  background: var(--rb-color-accent, #0F766E);
+  color: var(--rb-color-accent-text-on, #FFFFFF);
+  cursor: pointer;
+  transition: background var(--rb-duration-fast, 150ms) var(--rb-ease-standard, ease);
+}
+.rb-elig-button:hover { background: var(--rb-color-accent-high, #115E59); border-color: var(--rb-color-accent-high, #115E59); }
+.rb-elig-button:focus-visible {
+  outline: var(--rb-focus-width, 2px) solid var(--rb-color-focus, #0F766E);
+  outline-offset: var(--rb-focus-offset, 2px);
+}
+.rb-elig-button:disabled { opacity: 0.5; cursor: default; }
+.rb-elig-button-small { min-height: 32px; margin-left: var(--rb-space-2, 0.5rem); padding: 0 var(--rb-space-3, 0.75rem); }
+
+@media (prefers-reduced-motion: reduce) {
+  .rb-elig, .rb-elig-button { transition: none; }
+}

package/dist/urls.d.ts

@@ -0,0 +1,8 @@
+/** Where a wallet gets verified. */
+export declare const ACCESS_URL = "https://access.redbelly.network";
+/** Testnet RBNT, with a Discord login (RESEARCH.md question 12). */
+export declare const FAUCET_URL = "https://redbelly.faucetme.pro/";
+/** Vine's page with the wallet gas warning, quoted in docs/wallet-gas-warning.md. */
+export declare const VINE_INTERACTION_URL = "https://vine.redbelly.network/smart-contracts/interaction/";
+/** Vine's page on how gas is priced in US dollars. */
+export declare const VINE_FEES_URL = "https://vine.redbelly.network/network-fees/";

package/dist/urls.js

@@ -0,0 +1,10 @@
+// Redbelly's own pages. The kit links to them and never restates what they say.
+// Every URL was read on 12 September 2026 (RESEARCH.md source log).
+/** Where a wallet gets verified. */
+export const ACCESS_URL = 'https://access.redbelly.network';
+/** Testnet RBNT, with a Discord login (RESEARCH.md question 12). */
+export const FAUCET_URL = 'https://redbelly.faucetme.pro/';
+/** Vine's page with the wallet gas warning, quoted in docs/wallet-gas-warning.md. */
+export const VINE_INTERACTION_URL = 'https://vine.redbelly.network/smart-contracts/interaction/';
+/** Vine's page on how gas is priced in US dollars. */
+export const VINE_FEES_URL = 'https://vine.redbelly.network/network-fees/';

package/dist/useEligibility.d.ts

@@ -0,0 +1,58 @@
+export type Address = `0x${string}`;
+/** The five UI states, plus the two every real page also has. */
+export type EligibilityState = 'disconnected' | 'checking' | 'unverified' | 'ineligible' | 'eligible' | 'expiring' | 'error';
+export interface UseEligibilityOptions {
+    /** Chain to read on. Defaults to wagmi's current chain. */
+    chainId?: number;
+    /** The network's permission contract. Defaults to the address in @gatedpath/chains for `chainId`. */
+    permission?: Address;
+    /** Refetch floor in milliseconds; the reads also refetch on every new block. Default 30 000. */
+    refreshInterval?: number;
+    /** Watch `eth_blockNumber` and refetch when it changes. Default true. */
+    watchBlocks?: boolean;
+    /**
+     * When the verifier can tell: a function that returns the credential's expiry as a Unix time in
+     * seconds, or null when unknown. `ReceptorMock` can; adapters over real verifiers cannot.
+     * See `receptorMockExpiry`.
+     */
+    expiry?: (args: {
+        address: Address;
+        requestId: bigint;
+    }) => Promise<number | bigint | null>;
+    /** How long before expiry the state turns to `expiring`. Default seven days. */
+    expiringWindowSeconds?: number;
+    /** Turn every read off (for example while a modal is closed). Default true. */
+    enabled?: boolean;
+}
+export interface EligibilityResult {
+    state: EligibilityState;
+    /** `permission.isAllowed(address)`: the wallet has been through access.redbelly.network. */
+    isAllowed: boolean | undefined;
+    /** `verifier.isEligible(address, requestId)`: the wallet passes this action's gate. */
+    isEligible: boolean | undefined;
+    /** Unix seconds when the credential expires, when the verifier can tell. */
+    expiresAt: number | null;
+    /** Seconds until expiry, when known. */
+    secondsToExpiry: number | null;
+    /** When the eligibility read last returned, in milliseconds since the epoch. */
+    lastCheckedAt: number | null;
+    /** The block the last refetch was triggered by, when block watching is on. */
+    blockNumber: bigint | undefined;
+    isFetching: boolean;
+    error: Error | null;
+    /** Read both again now. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Reads the two things a Redbelly UI has to know about a wallet before it offers a button: is
+ * the wallet allowed to transact at all (the network's gate), and does it pass this action's
+ * eligibility check (the dApp's verifier). Both are cached by wagmi's query client and shared by
+ * every component that asks for the same wallet, verifier and request id; they refetch once per
+ * new block, or every `refreshInterval` milliseconds if no block arrives (blocks on Redbelly are
+ * produced on demand, so a quiet chain has no blocks to watch), and on `refresh()`.
+ *
+ * @param address The connected wallet, or undefined when nothing is connected.
+ * @param verifier The dApp's verifier behind `IRedbellyVerifier`.
+ * @param requestId The request id the gated contract is bound to (`Gated.requestId()`).
+ */
+export declare function useEligibility(address: Address | undefined, verifier: Address | undefined, requestId: bigint | number | undefined, options?: UseEligibilityOptions): EligibilityResult;

package/dist/useEligibility.js

@@ -0,0 +1,143 @@
+'use client';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { useBlockNumber, useChainId, useReadContract } from 'wagmi';
+import { chainById } from '@gatedpath/chains';
+import { permissionAbi, verifierAbi } from './abi.js';
+import { onEligibilityChanged } from './events.js';
+const SEVEN_DAYS = 7 * 24 * 60 * 60;
+/**
+ * Reads the two things a Redbelly UI has to know about a wallet before it offers a button: is
+ * the wallet allowed to transact at all (the network's gate), and does it pass this action's
+ * eligibility check (the dApp's verifier). Both are cached by wagmi's query client and shared by
+ * every component that asks for the same wallet, verifier and request id; they refetch once per
+ * new block, or every `refreshInterval` milliseconds if no block arrives (blocks on Redbelly are
+ * produced on demand, so a quiet chain has no blocks to watch), and on `refresh()`.
+ *
+ * @param address The connected wallet, or undefined when nothing is connected.
+ * @param verifier The dApp's verifier behind `IRedbellyVerifier`.
+ * @param requestId The request id the gated contract is bound to (`Gated.requestId()`).
+ */
+export function useEligibility(address, verifier, requestId, options = {}) {
+    const currentChainId = useChainId();
+    const chainId = options.chainId ?? currentChainId;
+    const refreshInterval = options.refreshInterval ?? 30_000;
+    const enabled = (options.enabled ?? true) && Boolean(address);
+    const watchBlocks = options.watchBlocks ?? true;
+    const requestIdBig = requestId === undefined ? undefined : BigInt(requestId);
+    const permission = options.permission ?? chainById(chainId)?.contracts['permission']?.address;
+    const block = useBlockNumber({
+        chainId,
+        watch: watchBlocks && enabled,
+        query: { enabled: watchBlocks && enabled },
+    });
+    const allowed = useReadContract({
+        address: permission,
+        abi: permissionAbi,
+        functionName: 'isAllowed',
+        args: address ? [address] : undefined,
+        chainId,
+        query: {
+            enabled: enabled && Boolean(permission),
+            staleTime: refreshInterval,
+            refetchInterval: refreshInterval,
+            refetchOnWindowFocus: false,
+        },
+    });
+    const eligible = useReadContract({
+        address: verifier,
+        abi: verifierAbi,
+        functionName: 'isEligible',
+        args: address && requestIdBig !== undefined ? [address, requestIdBig] : undefined,
+        chainId,
+        query: {
+            enabled: enabled && Boolean(verifier) && requestIdBig !== undefined,
+            staleTime: refreshInterval,
+            refetchInterval: refreshInterval,
+            refetchOnWindowFocus: false,
+        },
+    });
+    const expiryFn = options.expiry;
+    const expiry = useQuery({
+        queryKey: ['redbelly-frontend-kit', 'expiry', chainId, address, verifier, requestIdBig?.toString()],
+        queryFn: async () => {
+            if (!expiryFn || !address || requestIdBig === undefined)
+                return null;
+            const value = await expiryFn({ address, requestId: requestIdBig });
+            return value === null || value === undefined ? null : Number(value);
+        },
+        enabled: enabled && Boolean(expiryFn) && eligible.data === true,
+        staleTime: refreshInterval,
+        refetchInterval: refreshInterval,
+        refetchOnWindowFocus: false,
+    });
+    // Refetch on a new block, and only on a new block: the block number itself is polled by wagmi.
+    const lastBlock = useRef(undefined);
+    const refetchAllowed = allowed.refetch;
+    const refetchEligible = eligible.refetch;
+    const refetchExpiry = expiry.refetch;
+    useEffect(() => {
+        if (!watchBlocks || !enabled || block.data === undefined)
+            return;
+        if (lastBlock.current === undefined) {
+            lastBlock.current = block.data;
+            return;
+        }
+        if (block.data !== lastBlock.current) {
+            lastBlock.current = block.data;
+            void refetchAllowed();
+            void refetchEligible();
+            if (expiryFn)
+                void refetchExpiry();
+        }
+    }, [block.data, watchBlocks, enabled, refetchAllowed, refetchEligible, refetchExpiry, expiryFn]);
+    const refresh = useCallback(async () => {
+        await Promise.all([refetchAllowed(), refetchEligible(), expiryFn ? refetchExpiry() : Promise.resolve()]);
+    }, [refetchAllowed, refetchEligible, refetchExpiry, expiryFn]);
+    // Something in this tab changed a wallet's eligibility (the dev state panel after `setStatus`
+    // on a local Anvil, or the app after its own transaction): read again now, for this wallet.
+    useEffect(() => {
+        if (!enabled || !address)
+            return;
+        return onEligibilityChanged((changed) => {
+            if (changed === undefined || changed.toLowerCase() === address.toLowerCase())
+                void refresh();
+        });
+    }, [enabled, address, refresh]);
+    const expiresAt = expiry.data ?? null;
+    const window = options.expiringWindowSeconds ?? SEVEN_DAYS;
+    return useMemo(() => {
+        const error = (allowed.error ?? eligible.error ?? expiry.error);
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        const secondsToExpiry = expiresAt === null || expiresAt === 0 ? null : expiresAt - nowSeconds;
+        let state;
+        if (!address)
+            state = 'disconnected';
+        else if (error && allowed.data === undefined && eligible.data === undefined)
+            state = 'error';
+        else if (allowed.data === undefined && eligible.data === undefined)
+            state = 'checking';
+        else if (allowed.data === false)
+            state = 'unverified';
+        else if (eligible.data === false)
+            state = 'ineligible';
+        else if (eligible.data === true && secondsToExpiry !== null && secondsToExpiry <= window)
+            state = 'expiring';
+        else if (eligible.data === true)
+            state = 'eligible';
+        else
+            state = 'checking';
+        return {
+            state,
+            isAllowed: allowed.data,
+            isEligible: eligible.data,
+            expiresAt: expiresAt === 0 ? null : expiresAt,
+            secondsToExpiry,
+            lastCheckedAt: eligible.dataUpdatedAt || null,
+            blockNumber: block.data,
+            isFetching: allowed.isFetching || eligible.isFetching,
+            error,
+            refresh,
+        };
+    }, [address, allowed.data, allowed.error, allowed.isFetching, eligible.data, eligible.error, eligible.isFetching, eligible.dataUpdatedAt, expiry.error, expiresAt, window, block.data, refresh]);
+}

package/docs/wallet-gas-warning.md

@@ -0,0 +1,44 @@
+# The wallet gas warning
+
+Vine's page on interacting with smart contracts carries a warning that every Redbelly dApp
+should repeat near its first transaction. Read on 12 September 2026 at
+https://vine.redbelly.network/smart-contracts/interaction/ (RESEARCH.md question 13):
+
+> for most wallets, gas related information may not be handled accurately
+
+The same page steers dApps to WalletConnect. Here is why the warning exists and what the kit does
+about it.
+
+## Why wallets get it wrong here
+
+Gas on Redbelly is priced in US dollars, not in a fee market. A native transfer costs US$0.01 at
+21,000 gas; an on-chain price oracle publishes the USD/RBNT rate and nodes read it at block
+execution, so the base fee in wei moves with the RBNT price and `eth_maxPriorityFeePerGas` is
+zero (https://vine.redbelly.network/network-fees/, and measured, RESEARCH.md question 6). Wallets
+built for Ethereum assume a fee market: they estimate a priority fee, show "low, medium, high"
+tiers that mean nothing here, sometimes display the fee in a fiat conversion that uses their own
+price source rather than the network's oracle, and may warn about "high gas" when the number is
+just the RBNT price doing its job.
+
+The consequences for a dApp:
+
+- The fee your app shows should come from the chain, not the wallet. `gasCostUsd` in
+  `@gatedpath/chains` reads the base fee and the feed and returns RBNT and USD for a gas
+  amount. `<GasWarning transferUsd={...}>` takes that figure.
+- Never set fee fields in the transaction request. Leave `maxFeePerGas` and
+  `maxPriorityFeePerGas` unset and let the client estimate; a hard-coded value copied from
+  Ethereum will be wrong in one direction or the other. The scaffolder's wagmi config leaves them
+  unset on purpose.
+- There is nothing to bump. With no priority fee there is no "speed up" that does anything; a
+  transaction that is not in the next block produced is not coming (RESEARCH.md question 4, blocks
+  on demand). Tell the user to re-send rather than re-price.
+- Show the warning once, near the first action, and link to Vine rather than restating the fee
+  model. `<GasWarning>` links to the interaction page and the network-fees page.
+
+## What the component says
+
+"Gas on Redbelly is priced in US dollars and paid in RBNT; a plain transfer costs about US$X right
+now. Redbelly warns that most wallets show gas information wrongly on this network, so trust the
+figure here over the wallet's", followed by the two links. The X is whatever you pass in
+`transferUsd`; the scaffolder's page fills it from `gasCostUsd({ gasUsed: 21_000 })`. Without a
+figure the sentence drops the number rather than printing a stale one.

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@gatedpath/frontend-kit",
+  "version": "0.1.0",
+  "description": "React components and one hook for the five eligibility states every Redbelly dApp has: not connected, connected but not verified on the network, verified but ineligible for this action, eligible, credential expiring soon; plus explainError, the plain words for a viem or wagmi error from the shared failure table. wagmi + viem, headless with a small default style.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tshirtdropper/redbelly-development-tool.git",
+    "directory": "packages/frontend-kit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./dev": {
+      "types": "./dist/dev/index.d.ts",
+      "import": "./dist/dev/index.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./dev.css": "./dist/dev.css"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node -e \"require('fs').copyFileSync('src/styles.css','dist/styles.css');require('fs').copyFileSync('src/dev.css','dist/dev.css')\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@gatedpath/chains": "*",
+    "@tanstack/react-query": ">=5.0.0",
+    "react": ">=18.0.0",
+    "viem": ">=2.0.0",
+    "wagmi": ">=2.0.0",
+    "@gatedpath/agent-rules": "*"
+  },
+  "devDependencies": {
+    "@gatedpath/agent-rules": "file:../agent-rules",
+    "@gatedpath/chains": "file:../chain-definitions",
+    "@tanstack/react-query": "5.102.8",
+    "@testing-library/react": "16.3.3",
+    "@types/react": "19.2.3",
+    "@types/react-dom": "19.2.3",
+    "jsdom": "30.0.1",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "typescript": "5.9.3",
+    "viem": "2.56.3",
+    "vitest": "5.0.0",
+    "wagmi": "3.7.7"
+  }
+}