@gatedpath/frontend-kit 0.2.2 → 0.2.4

package/README.md

@@ -17,6 +17,10 @@ For agents
   table (`@gatedpath/agent-rules/failures`): NotEligible (with the credential state when you pass
   one), a wallet rejection, a wrong chain, not enough RBNT. Show `plainWords` and `fix.link`, never
   `error.message` alone; `kind: "unknown"` carries the error's own words in `raw`.
+- Before a send, `checkRecipient(client, { recipient, chainId })` (or `useRecipientCheck(recipient)`)
+  answers what card 13's `RecipientGuard` will answer on chain: `ok`, a `verdict`, and `reasons`
+  with a sentence each. Show the sentences; never build the transaction while `ok` is false. It
+  means an address someone verified holds, not the right person.
 - Build: `npm run build`. Tests: `npm test` (Vitest, jsdom, a mocked transport; no network).
 ```
 
@@ -133,12 +137,51 @@ The panel renders only on chain 31337. On 151 or 153 it renders nothing whatever
 and the scaffold imports it only in the dev server behind a build-time constant, so a production
 bundle carries none of it; the scaffolder's integration test builds one and checks.
 
+## checkRecipient
+
+```tsx
+import { useRecipientCheck } from '@gatedpath/frontend-kit';
+
+const { check, isChecking, error } = useRecipientCheck(recipient, { allowContract });
+// check: { ok, verdict, reasons: [{ kind, error, plainWords }], permission, chainId } | null
+return (
+  <>
+    {isChecking && <p>Asking the network…</p>}
+    {check?.reasons.map((r) => <p key={r.kind}>{r.plainWords}</p>)}
+    <button disabled={!check?.ok} onClick={send}>Send through the guard</button>
+  </>
+);
+```
+
+A transfer that refuses to lose your money (card 13) goes through `RecipientGuard`, a contract
+that asks the network whether the recipient has passed the identity gate on this chain and
+refuses if not. `checkRecipient(client, { recipient, chainId, allowContract?, amount?, permission?,
+registry? })` asks the same questions from the browser first, in the guard's order, so the page can
+say no before it asks for a signature: the zero address (`ZeroRecipient`); code at the address,
+which makes it a contract the guard refuses unless `allowContract` is true (`RecipientIsContract`;
+a 23-byte EIP-7702 delegation is still a wallet); the bootstrap registry naming no permission
+contract, or one with no code (`NoPermissionContract`); `permission.isAllowed` false
+(`RecipientNotPermissioned`); and, when you pass `amount`, zero (`NothingToSend`). Each reason
+carries the guard's error name and a sentence for the page. The permission contract is resolved
+through the registry on every call, as the guard does, because its proxy admin has moved before;
+pass `permission` to skip that when the page already holds it. `client` is a viem `PublicClient`
+(`usePublicClient()` in wagmi); the call throws if the client is on another chain than `chainId`,
+and an RPC failure is thrown, never turned into a verdict.
+
+`useRecipientCheck(recipient, { chainId?, allowContract?, permission?, registry?, refreshInterval?,
+enabled? })` runs it when a recipient is set, caches the answer under the chain id and the recipient
+for 30 s, and exposes `refresh()`. The page's answer is a courtesy and the contract's is the rule:
+`ok` means an address someone verified holds on this chain, or a contract the user said they mean.
+A typo that lands on another verified address goes through, and the page should say so.
+
 ## Tests
 
-`npm test`: 80 Vitest tests in jsdom. `test/mock-chain.tsx` is a wagmi config over a `custom`
+`npm test`: 122 Vitest tests in jsdom. `test/mock-chain.tsx` is a wagmi config over a `custom`
 transport that answers `eth_chainId`, `eth_blockNumber`, `eth_call` and Multicall3 `aggregate3`
+(and, since `checkRecipient`, `eth_getCode` and the bootstrap registry's `getContractAddress`)
 from an in-memory state the tests mutate; nothing leaves the process and no address in it exists
-anywhere. The hook tests cover every state, that reads happen once and then only on a new block,
+anywhere. `test/checkRecipient.test.tsx` covers every refusal the guard makes, the ok path, the
+EIP-7702 case, a given permission contract, the chain mismatch and the hook's cache and refresh. The hook tests cover every state, that reads happen once and then only on a new block,
 manual refresh without a block, shared reads, the expiry window, errors and `enabled: false`. The
 component tests render every state, the gate's selection and override, the links (Access dApp,
 faucet, Vine) and the retry and refresh buttons. `test/dev-panel.test.tsx` runs the dev panel

package/dist/abi.d.ts

@@ -15,6 +15,24 @@ export declare const verifierAbi: readonly [{
         readonly type: "bool";
     }];
 }];
+/**
+ * The bootstrap registry, the one fixed address on both chains: `getContractAddress("permission")`
+ * names the permission contract. `checkRecipient` asks it on every call rather than remembering
+ * the answer, because the permission proxy's admin has moved before.
+ */
+export declare const bootstrapRegistryAbi: readonly [{
+    readonly type: "function";
+    readonly name: "getContractAddress";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "name";
+        readonly type: "string";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}];
 /** The network's permission contract: `isAllowed(address)` (RESEARCH.md question 7). */
 export declare const permissionAbi: readonly [{
     readonly type: "function";

package/dist/abi.js

@@ -12,6 +12,20 @@ export const verifierAbi = [
         outputs: [{ name: '', type: 'bool' }],
     },
 ];
+/**
+ * The bootstrap registry, the one fixed address on both chains: `getContractAddress("permission")`
+ * names the permission contract. `checkRecipient` asks it on every call rather than remembering
+ * the answer, because the permission proxy's admin has moved before.
+ */
+export const bootstrapRegistryAbi = [
+    {
+        type: 'function',
+        name: 'getContractAddress',
+        stateMutability: 'view',
+        inputs: [{ name: 'name', type: 'string' }],
+        outputs: [{ name: '', type: 'address' }],
+    },
+];
 /** The network's permission contract: `isAllowed(address)` (RESEARCH.md question 7). */
 export const permissionAbi = [
     {

package/dist/checkRecipient.d.ts

@@ -0,0 +1,73 @@
+import type { PublicClient } from 'viem';
+import type { Address } from './useEligibility.js';
+/** `RecipientGuard.Verdict`, plus the one case where the guard cannot reach a verdict at all. */
+export type RecipientVerdict = 'permissioned' | 'not-permissioned' | 'contract' | 'zero' | 'no-permission-contract';
+/** One per named revert in `RecipientGuard`, except `NativeTransferFailed`, which only the send itself can find. */
+export type RecipientReasonKind = 'zero-recipient' | 'recipient-is-contract' | 'recipient-not-permissioned' | 'no-permission-contract' | 'nothing-to-send';
+export interface RecipientReason {
+    kind: RecipientReasonKind;
+    /** The guard's error name for this refusal, as a block explorer or `explainError` would show it. */
+    error: 'ZeroRecipient' | 'RecipientIsContract' | 'RecipientNotPermissioned' | 'NoPermissionContract' | 'NothingToSend';
+    /** A sentence for the page. */
+    plainWords: string;
+}
+export interface CheckRecipientOptions {
+    recipient: Address;
+    /** The chain the client reads. Refused when the client says it is on a different one. */
+    chainId: number;
+    /** True when the user has said a contract is what they mean to pay (`send(to, allowContract)`). Default false. */
+    allowContract?: boolean;
+    /** The amount about to be sent, when known; zero is refused the way `send` refuses an empty call. */
+    amount?: bigint;
+    /** Skip the registry and read this permission contract. Default: resolve it live, as the guard does. */
+    permission?: Address;
+    /** The bootstrap registry. Default: the shared address from @gatedpath/chains. */
+    registry?: Address;
+}
+export interface RecipientCheck {
+    /** True when the guard would let the send through to this recipient. */
+    ok: boolean;
+    verdict: RecipientVerdict;
+    /** Empty when `ok`. Otherwise every refusal the guard would raise, in the order it raises them. */
+    reasons: RecipientReason[];
+    recipient: Address;
+    chainId: number;
+    /** The permission contract the answer came from, when one was read. */
+    permission: Address | null;
+}
+/**
+ * Asks the network what `RecipientGuard.check(to)` would answer, and turns it into the refusals
+ * `send` would raise. Reads, in the guard's order: the recipient's code; then, for a wallet, the
+ * registry's code, the permission contract it names, that contract's code, and `isAllowed`. The
+ * permission contract is resolved on every call and never remembered, because its proxy admin has
+ * moved before (14 September 2026); pass `permission` to skip that when the page already knows it.
+ *
+ * What `ok` means: an address someone verified holds on this chain, or a contract the user has
+ * said they mean. It does not mean the right person: a typo that lands on another verified
+ * address goes through. Say that on the page.
+ */
+export declare function checkRecipient(client: PublicClient, options: CheckRecipientOptions): Promise<RecipientCheck>;
+export interface UseRecipientCheckOptions {
+    /** Chain to read on. Defaults to wagmi's current chain. */
+    chainId?: number;
+    allowContract?: boolean;
+    permission?: Address;
+    registry?: Address;
+    /** How long an answer is kept before the next render reads again. Default 30 000 ms. */
+    refreshInterval?: number;
+    enabled?: boolean;
+}
+export interface RecipientCheckResult {
+    /** The last answer, or null before the first one. */
+    check: RecipientCheck | null;
+    isChecking: boolean;
+    error: Error | null;
+    /** Read again now. */
+    refresh: () => Promise<void>;
+}
+/**
+ * `checkRecipient` as a hook: runs when `recipient` is set, caches the answer under the chain id
+ * and the recipient for `refreshInterval`, and reads again on `refresh()`. Mount it on the
+ * recipient field; show `check.reasons[*].plainWords` under it.
+ */
+export declare function useRecipientCheck(recipient: Address | undefined, options?: UseRecipientCheckOptions): RecipientCheckResult;

package/dist/checkRecipient.js

@@ -0,0 +1,118 @@
+'use client';
+// checkRecipient: the question card 13's RecipientGuard asks on chain, asked from the browser
+// first, so a page can refuse before it asks for a signature. Same reads, same order, same
+// answers as `RecipientGuard.check` and `_requirePasses`; the contract's answer is still the rule
+// and this one is the courtesy. No cache here: `useRecipientCheck` caches per chain so an answer
+// from 153 is never shown for 151.
+import { useCallback, useMemo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { useChainId, usePublicClient } from 'wagmi';
+import { addresses, chainById } from '@gatedpath/chains';
+import { bootstrapRegistryAbi, permissionAbi } from './abi.js';
+const ZERO = '0x0000000000000000000000000000000000000000';
+const WORDS = {
+    'zero-recipient': {
+        error: 'ZeroRecipient',
+        plainWords: 'That is the zero address. Nothing can be sent there, and the guard refuses it.',
+    },
+    'recipient-is-contract': {
+        error: 'RecipientIsContract',
+        plainWords: 'This is a contract, not a wallet, so it has never been through the identity gate. The guard refuses it unless you say a contract is what you mean to pay.',
+    },
+    'recipient-not-permissioned': {
+        error: 'RecipientNotPermissioned',
+        plainWords: 'No one verified holds this address on this chain. Money sent there would be gone, so the guard refuses.',
+    },
+    'no-permission-contract': {
+        error: 'NoPermissionContract',
+        plainWords: 'This chain has no permission contract behind its registry, so there is nothing to check a recipient against. The guard refuses every send here.',
+    },
+    'nothing-to-send': {
+        error: 'NothingToSend',
+        plainWords: 'The amount is zero. There is nothing to send.',
+    },
+};
+function reason(kind) {
+    return { kind, ...WORDS[kind] };
+}
+/** `RecipientGuard._isContract`: code at the address, unless it is an EIP-7702 delegation designator, which is still a wallet. */
+function isContractCode(code) {
+    if (!code || code === '0x')
+        return false;
+    const bytes = (code.length - 2) / 2;
+    return !(bytes === 23 && code.toLowerCase().startsWith('0xef0100'));
+}
+/**
+ * Asks the network what `RecipientGuard.check(to)` would answer, and turns it into the refusals
+ * `send` would raise. Reads, in the guard's order: the recipient's code; then, for a wallet, the
+ * registry's code, the permission contract it names, that contract's code, and `isAllowed`. The
+ * permission contract is resolved on every call and never remembered, because its proxy admin has
+ * moved before (14 September 2026); pass `permission` to skip that when the page already knows it.
+ *
+ * What `ok` means: an address someone verified holds on this chain, or a contract the user has
+ * said they mean. It does not mean the right person: a typo that lands on another verified
+ * address goes through. Say that on the page.
+ */
+export async function checkRecipient(client, options) {
+    const { recipient, chainId } = options;
+    if (client.chain && client.chain.id !== chainId) {
+        throw new Error(`checkRecipient: the client is on chain ${client.chain.id}, not ${chainId}; an answer from one chain is never shown for another`);
+    }
+    const reasons = [];
+    if (options.amount !== undefined && options.amount === 0n)
+        reasons.push(reason('nothing-to-send'));
+    const base = { recipient, chainId, permission: null };
+    if (recipient.toLowerCase() === ZERO) {
+        reasons.push(reason('zero-recipient'));
+        return { ...base, ok: false, verdict: 'zero', reasons };
+    }
+    const code = await client.getCode({ address: recipient });
+    if (isContractCode(code)) {
+        if (!options.allowContract)
+            reasons.push(reason('recipient-is-contract'));
+        return { ...base, ok: reasons.length === 0, verdict: 'contract', reasons };
+    }
+    let permission = options.permission ?? null;
+    if (!permission) {
+        const registry = options.registry ?? chainById(chainId)?.contracts['bootstrapRegistry']?.address ?? addresses.mainnet.bootstrapRegistry.address;
+        const registryCode = await client.getCode({ address: registry });
+        const named = registryCode && registryCode !== '0x'
+            ? await client.readContract({ address: registry, abi: bootstrapRegistryAbi, functionName: 'getContractAddress', args: ['permission'] })
+            : ZERO;
+        const permissionCode = named.toLowerCase() === ZERO ? '0x' : await client.getCode({ address: named });
+        if (!permissionCode || permissionCode === '0x') {
+            reasons.push(reason('no-permission-contract'));
+            return { ...base, ok: false, verdict: 'no-permission-contract', reasons };
+        }
+        permission = named;
+    }
+    const allowed = await client.readContract({ address: permission, abi: permissionAbi, functionName: 'isAllowed', args: [recipient] });
+    if (!allowed)
+        reasons.push(reason('recipient-not-permissioned'));
+    return { ...base, permission, ok: reasons.length === 0, verdict: allowed ? 'permissioned' : 'not-permissioned', reasons };
+}
+/**
+ * `checkRecipient` as a hook: runs when `recipient` is set, caches the answer under the chain id
+ * and the recipient for `refreshInterval`, and reads again on `refresh()`. Mount it on the
+ * recipient field; show `check.reasons[*].plainWords` under it.
+ */
+export function useRecipientCheck(recipient, options = {}) {
+    const currentChainId = useChainId();
+    const chainId = options.chainId ?? currentChainId;
+    const client = usePublicClient({ chainId });
+    const allowContract = options.allowContract ?? false;
+    const enabled = (options.enabled ?? true) && Boolean(client && recipient);
+    const { permission, registry } = options;
+    const query = useQuery({
+        queryKey: ['redbelly-frontend-kit', 'recipient', chainId, recipient?.toLowerCase(), allowContract, permission, registry],
+        queryFn: () => checkRecipient(client, { recipient: recipient, chainId, allowContract, permission, registry }),
+        enabled,
+        staleTime: options.refreshInterval ?? 30_000,
+        refetchOnWindowFocus: false,
+    });
+    const refetch = query.refetch;
+    const refresh = useCallback(async () => {
+        await refetch();
+    }, [refetch]);
+    return useMemo(() => ({ check: query.data ?? null, isChecking: enabled && query.isPending, error: query.error ?? null, refresh }), [query.data, query.isPending, query.error, enabled, refresh]);
+}

package/dist/index.d.ts

@@ -4,7 +4,9 @@ export { receptorMockExpiry } from './expiry.js';
 export { notifyEligibilityChanged, onEligibilityChanged } from './events.js';
 export { EligibilityGate, NotConnected, NotVerified, Ineligible, Eligible, ExpiringSoon, Checking, EligibilityError, LastChecked, GasWarning, } from './components.js';
 export type { EligibilityGateProps, StateProps, NotVerifiedProps, IneligibleProps, ExpiringSoonProps, EligibilityErrorProps, LastCheckedProps, GasWarningProps, } from './components.js';
-export { verifierAbi, permissionAbi, receptorMockAbi, receptorMockStatusAbi, registerTokenAbi, identityRegistryAbi, trustedIssuersRegistryAbi, claimTopicsRegistryAbi } from './abi.js';
+export { checkRecipient, useRecipientCheck } from './checkRecipient.js';
+export type { RecipientCheck, RecipientReason, RecipientReasonKind, RecipientVerdict, CheckRecipientOptions, UseRecipientCheckOptions, RecipientCheckResult } from './checkRecipient.js';
+export { verifierAbi, permissionAbi, bootstrapRegistryAbi, receptorMockAbi, receptorMockStatusAbi, registerTokenAbi, identityRegistryAbi, trustedIssuersRegistryAbi, claimTopicsRegistryAbi } from './abi.js';
 export { useRegister } from './useRegister.js';
 export type { RegisterState, RegisterResult, UseRegisterOptions } from './useRegister.js';
 export { ACCESS_URL, FAUCET_URL, VINE_INTERACTION_URL, VINE_FEES_URL } from './urls.js';

package/dist/index.js

@@ -2,7 +2,8 @@ export { useEligibility } from './useEligibility.js';
 export { receptorMockExpiry } from './expiry.js';
 export { notifyEligibilityChanged, onEligibilityChanged } from './events.js';
 export { EligibilityGate, NotConnected, NotVerified, Ineligible, Eligible, ExpiringSoon, Checking, EligibilityError, LastChecked, GasWarning, } from './components.js';
-export { verifierAbi, permissionAbi, receptorMockAbi, receptorMockStatusAbi, registerTokenAbi, identityRegistryAbi, trustedIssuersRegistryAbi, claimTopicsRegistryAbi } from './abi.js';
+export { checkRecipient, useRecipientCheck } from './checkRecipient.js';
+export { verifierAbi, permissionAbi, bootstrapRegistryAbi, receptorMockAbi, receptorMockStatusAbi, registerTokenAbi, identityRegistryAbi, trustedIssuersRegistryAbi, claimTopicsRegistryAbi } from './abi.js';
 export { useRegister } from './useRegister.js';
 export { ACCESS_URL, FAUCET_URL, VINE_INTERACTION_URL, VINE_FEES_URL } from './urls.js';
 export { explainError } from './explainError.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gatedpath/frontend-kit",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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": {