@gatedpath/frontend-kit 0.2.1 → 0.2.3

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).
 ```
 
@@ -58,6 +62,23 @@ State derivation, in order: no address is `disconnected`; nothing cached and an
 says; `isEligible` false is `ineligible`; `isEligible` true with an expiry inside the window is
 `expiring`; otherwise `eligible`.
 
+## The register hook
+
+```tsx
+const r = useRegister(tokenAddress, address);
+// r.state: 'disconnected' | 'checking' | 'not-a-register' | 'registered' | 'not-registered' | 'frozen' | 'paused' | 'error'
+```
+
+`useRegister(token, wallet)` reads an ERC-3643 register (a T-REX token, the shape of every real asset
+on this network) and, when a wallet is given, whether that register's identity registry has verified
+it. It is the third gate a holder meets, after `permission.isAllowed` and a dApp's recipe, which
+`useEligibility` reads. The result carries the token's facts (name, symbol, decimals, supply, T-REX
+version, paused), the registry's shape (trusted issuers, required claim topics, and `gate`:
+`registration only` when no topics are required, `claims` otherwise) and the wallet's standing
+(verified, registered, frozen, balance). Reads are batched through Multicall3, cached per chain and
+refetched on a new block. Only the issuer can register a wallet, so `not-registered` is information
+for the page, never a button. The ops kit's `readRegister` is the same read from a script.
+
 ## The components
 
 | Component | State | Says |
@@ -116,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";
@@ -96,3 +114,234 @@ export declare const receptorMockStatusAbi: readonly [{
         readonly type: "uint8";
     }];
 }];
+/**
+ * ERC-3643 (T-REX 4.1.x), the shape of every real register on this network (RESEARCH.md source log,
+ * 12 October 2026): the token, its identity registry, the trusted-issuers and claim-topics registries.
+ * Reads only; the interface was confirmed against a live mainnet register before it was written here.
+ */
+export declare const registerTokenAbi: readonly [{
+    readonly type: "function";
+    readonly name: "identityRegistry";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "compliance";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "onchainID";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "name";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "symbol";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "decimals";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint8";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "totalSupply";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "version";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "paused";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "isFrozen";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getFrozenTokens";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}];
+export declare const identityRegistryAbi: readonly [{
+    readonly type: "function";
+    readonly name: "identityStorage";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "issuersRegistry";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "topicsRegistry";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "isVerified";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "identity";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "investorCountry";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint16";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "contains";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}];
+export declare const trustedIssuersRegistryAbi: readonly [{
+    readonly type: "function";
+    readonly name: "getTrustedIssuers";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address[]";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getTrustedIssuerClaimTopics";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "issuer";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256[]";
+    }];
+}];
+export declare const claimTopicsRegistryAbi: readonly [{
+    readonly type: "function";
+    readonly name: "getClaimTopics";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256[]";
+    }];
+}];

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 = [
     {
@@ -77,3 +91,38 @@ export const receptorMockStatusAbi = [
         outputs: [{ name: '', type: 'uint8' }],
     },
 ];
+/**
+ * ERC-3643 (T-REX 4.1.x), the shape of every real register on this network (RESEARCH.md source log,
+ * 12 October 2026): the token, its identity registry, the trusted-issuers and claim-topics registries.
+ * Reads only; the interface was confirmed against a live mainnet register before it was written here.
+ */
+export const registerTokenAbi = [
+    { type: 'function', name: 'identityRegistry', stateMutability: 'view', inputs: [], outputs: [{ name: '', type: 'address' }] },
+    { type: 'function', name: 'compliance', stateMutability: 'view', inputs: [], outputs: [{ name: '', type: 'address' }] },
+    { type: 'function', name: 'onchainID', stateMutability: 'view', inputs: [], outputs: [{ name: '', type: 'address' }] },
+    { type: 'function', name: 'name', stateMutability: 'view', inputs: [], outputs: [{ name: '', type: 'string' }] },
+    { type: 'function', name: 'symbol', stateMutability: 'view', inputs: [], outputs: [{ name: '', type: 'string' }] },
+    { type: 'function', name: 'decimals', stateMutability: 'view', inputs: [], outputs: [{ name: '', type: 'uint8' }] },
+    { type: 'function', name: 'totalSupply', stateMutability: 'view', inputs: [], outputs: [{ name: '', type: 'uint256' }] },
+    { type: 'function', name: 'version', stateMutability: 'view', inputs: [], outputs: [{ name: '', type: 'string' }] },
+    { type: 'function', name: 'paused', stateMutability: 'view', inputs: [], outputs: [{ name: '', type: 'bool' }] },
+    { type: 'function', name: 'isFrozen', stateMutability: 'view', inputs: [{ name: 'wallet', type: 'address' }], outputs: [{ name: '', type: 'bool' }] },
+    { type: 'function', name: 'getFrozenTokens', stateMutability: 'view', inputs: [{ name: 'wallet', type: 'address' }], outputs: [{ name: '', type: 'uint256' }] },
+    { type: 'function', name: 'balanceOf', stateMutability: 'view', inputs: [{ name: 'wallet', type: 'address' }], outputs: [{ name: '', type: 'uint256' }] },
+];
+export const identityRegistryAbi = [
+    { type: 'function', name: 'identityStorage', stateMutability: 'view', inputs: [], outputs: [{ name: '', type: 'address' }] },
+    { type: 'function', name: 'issuersRegistry', stateMutability: 'view', inputs: [], outputs: [{ name: '', type: 'address' }] },
+    { type: 'function', name: 'topicsRegistry', stateMutability: 'view', inputs: [], outputs: [{ name: '', type: 'address' }] },
+    { type: 'function', name: 'isVerified', stateMutability: 'view', inputs: [{ name: 'wallet', type: 'address' }], outputs: [{ name: '', type: 'bool' }] },
+    { type: 'function', name: 'identity', stateMutability: 'view', inputs: [{ name: 'wallet', type: 'address' }], outputs: [{ name: '', type: 'address' }] },
+    { type: 'function', name: 'investorCountry', stateMutability: 'view', inputs: [{ name: 'wallet', type: 'address' }], outputs: [{ name: '', type: 'uint16' }] },
+    { type: 'function', name: 'contains', stateMutability: 'view', inputs: [{ name: 'wallet', type: 'address' }], outputs: [{ name: '', type: 'bool' }] },
+];
+export const trustedIssuersRegistryAbi = [
+    { type: 'function', name: 'getTrustedIssuers', stateMutability: 'view', inputs: [], outputs: [{ name: '', type: 'address[]' }] },
+    { type: 'function', name: 'getTrustedIssuerClaimTopics', stateMutability: 'view', inputs: [{ name: 'issuer', type: 'address' }], outputs: [{ name: '', type: 'uint256[]' }] },
+];
+export const claimTopicsRegistryAbi = [
+    { type: 'function', name: 'getClaimTopics', stateMutability: 'view', inputs: [], outputs: [{ name: '', type: 'uint256[]' }] },
+];

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/dev/DevStatePanel.d.ts

@@ -5,7 +5,7 @@ export interface DevStatePanelProps {
     className?: string;
 }
 /**
- * The dev-only state switcher (PLAN.md 18.1). Lists the five wallets `npm run dev` seeded, marks
+ * The dev-only state switcher (the local loop). Lists the five wallets `npm run dev` seeded, marks
  * the connected one, and flips the connected wallet through the five credential states by calling
  * `setStatus` on the `ReceptorMock` as the deployer, through Anvil's impersonation RPC. Every
  * mounted `useEligibility` for that wallet refetches on the resulting signal, so the page moves

package/dist/dev/DevStatePanel.js

@@ -23,7 +23,7 @@ function rpc(client, method, params = []) {
     return client.request({ method, params });
 }
 /**
- * The dev-only state switcher (PLAN.md 18.1). Lists the five wallets `npm run dev` seeded, marks
+ * The dev-only state switcher (the local loop). Lists the five wallets `npm run dev` seeded, marks
  * the connected one, and flips the connected wallet through the five credential states by calling
  * `setStatus` on the `ReceptorMock` as the deployer, through Anvil's impersonation RPC. Every
  * mounted `useEligibility` for that wallet refetches on the resulting signal, so the page moves

package/dist/dev/index.js

@@ -1,4 +1,4 @@
-// `@gatedpath/frontend-kit/dev`: the local-loop pieces (PLAN.md 18.1). Import this path only from
+// `@gatedpath/frontend-kit/dev`: the local-loop pieces (the local loop). Import this path only from
 // code a dev server runs; the scaffold's `web/src/components/DevState.tsx` does, behind a build-time
 // check that leaves nothing of it in a production bundle.
 export { DevStatePanel } from './DevStatePanel.js';

package/dist/dev/localDeployment.d.ts

@@ -12,9 +12,9 @@ export interface LocalWallet {
     note: string;
 }
 /**
- * `deployments/local.json` as `scripts/dev.mjs` writes it in a scaffold (PLAN.md 18.1). `deployer`
+ * `deployments/local.json` as `scripts/dev.mjs` writes it in a scaffold (the local loop). `deployer`
  * is Anvil account 7, the account that deployed the mock and holds the contract's admin roles; the
- * panel impersonates it to call `setStatus`. Accounts 0 and 1 are never used (RESEARCH.md 30).
+ * panel impersonates it to call `setStatus`. Accounts 0 and 1 are never used (research question 30 on the builder site).
  */
 export interface LocalDeployment {
     chainId: number;

package/dist/index.d.ts

@@ -4,7 +4,11 @@ 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 } 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';
 export { explainError } from './explainError.js';
 export type { ExplainedError, ExplainErrorOptions } from './explainError.js';

package/dist/index.js

@@ -2,6 +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 } 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/dist/useRegister.d.ts

@@ -0,0 +1,55 @@
+import type { Address } from './useEligibility.js';
+/**
+ * Where a wallet stands with one ERC-3643 register, in words a page can switch on.
+ * `not-a-register`: the address does not answer `identityRegistry()` with a contract.
+ * `registered`: the register's identity registry has verified this wallet.
+ * `not-registered`: it has not; only the issuer can change that.
+ * `frozen`: verified, but the issuer has frozen this wallet's tokens.
+ * `paused`: the issuer has paused every transfer of this register.
+ */
+export type RegisterState = 'disconnected' | 'checking' | 'not-a-register' | 'registered' | 'not-registered' | 'frozen' | 'paused' | 'error';
+export interface UseRegisterOptions {
+    chainId?: number;
+    /** Refetch floor in milliseconds; the reads also refetch on every new block. Default 30 000. */
+    refreshInterval?: number;
+    watchBlocks?: boolean;
+    enabled?: boolean;
+}
+export interface RegisterResult {
+    state: RegisterState;
+    /** The token's own facts, when it is a register. */
+    token: {
+        name: string | null;
+        symbol: string | null;
+        decimals: number | null;
+        totalSupply: bigint | null;
+        version: string | null;
+        paused: boolean | null;
+        identityRegistry: Address | null;
+    };
+    /** The registry's shape: which issuers it trusts and which claim topics it requires. */
+    registry: {
+        trustedIssuers: Address[];
+        claimTopics: bigint[];
+        gate: 'registration only' | 'claims' | null;
+    };
+    /** The wallet's standing, when a wallet was given. */
+    wallet: {
+        isVerified: boolean | null;
+        registered: boolean | null;
+        frozen: boolean | null;
+        balance: bigint | null;
+    } | null;
+    blockNumber: bigint | undefined;
+    isFetching: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * Reads an ERC-3643 register (a T-REX token) and, if a wallet is given, whether that register's
+ * identity registry has verified it. The third of the three gates a holder meets on this network,
+ * after `permission.isAllowed` and a dApp's recipe (`useEligibility`). Read-only; batched through
+ * Multicall3 by wagmi; cached per chain and refetched on a new block. Only the issuer can register a
+ * wallet, so a `not-registered` answer is information for the page, never a button.
+ */
+export declare function useRegister(token: Address | undefined, wallet: Address | undefined, options?: UseRegisterOptions): RegisterResult;

package/dist/useRegister.js

@@ -0,0 +1,146 @@
+'use client';
+import { useEffect, useMemo, useRef } from 'react';
+import { useBlockNumber, useChainId, useReadContracts } from 'wagmi';
+import { registerTokenAbi, identityRegistryAbi, claimTopicsRegistryAbi, trustedIssuersRegistryAbi } from './abi.js';
+const ZERO = '0x0000000000000000000000000000000000000000';
+/**
+ * Reads an ERC-3643 register (a T-REX token) and, if a wallet is given, whether that register's
+ * identity registry has verified it. The third of the three gates a holder meets on this network,
+ * after `permission.isAllowed` and a dApp's recipe (`useEligibility`). Read-only; batched through
+ * Multicall3 by wagmi; cached per chain and refetched on a new block. Only the issuer can register a
+ * wallet, so a `not-registered` answer is information for the page, never a button.
+ */
+export function useRegister(token, wallet, options = {}) {
+    const currentChainId = useChainId();
+    const chainId = options.chainId ?? currentChainId;
+    const refreshInterval = options.refreshInterval ?? 30_000;
+    const watchBlocks = options.watchBlocks ?? true;
+    const enabled = (options.enabled ?? true) && Boolean(token);
+    const block = useBlockNumber({ chainId, watch: watchBlocks && enabled, query: { enabled: watchBlocks && enabled } });
+    const query = { enabled, staleTime: refreshInterval, refetchInterval: refreshInterval, refetchOnWindowFocus: false };
+    // Pass one: the token. `identityRegistry()` decides whether there is a register at all.
+    const tokenReads = useReadContracts({
+        allowFailure: true,
+        contracts: [
+            { address: (token ?? ZERO), abi: registerTokenAbi, functionName: 'identityRegistry', chainId },
+            { address: (token ?? ZERO), abi: registerTokenAbi, functionName: 'name', chainId },
+            { address: (token ?? ZERO), abi: registerTokenAbi, functionName: 'symbol', chainId },
+            { address: (token ?? ZERO), abi: registerTokenAbi, functionName: 'decimals', chainId },
+            { address: (token ?? ZERO), abi: registerTokenAbi, functionName: 'totalSupply', chainId },
+            { address: (token ?? ZERO), abi: registerTokenAbi, functionName: 'version', chainId },
+            { address: (token ?? ZERO), abi: registerTokenAbi, functionName: 'paused', chainId },
+        ],
+        query,
+    });
+    const t = tokenReads.data;
+    const registryAddress = (t?.[0]?.status === 'success' ? t[0].result : null) ?? null;
+    const isRegister = registryAddress !== null && registryAddress !== ZERO;
+    // Pass two: the registry's shape and the wallet's standing, once the registry is known.
+    // The wallet reads are always in the batch, against the zero address when no wallet is given, so the
+    // batch has one shape and the results can be read by position. Those answers are ignored without a wallet.
+    const who = (wallet ?? ZERO);
+    const registryFor = (registryAddress ?? ZERO);
+    const tokenFor = (token ?? ZERO);
+    const detailReads = useReadContracts({
+        allowFailure: true,
+        contracts: [
+            { address: registryFor, abi: identityRegistryAbi, functionName: 'issuersRegistry', chainId },
+            { address: registryFor, abi: identityRegistryAbi, functionName: 'topicsRegistry', chainId },
+            { address: registryFor, abi: identityRegistryAbi, functionName: 'isVerified', args: [who], chainId },
+            { address: registryFor, abi: identityRegistryAbi, functionName: 'identity', args: [who], chainId },
+            { address: tokenFor, abi: registerTokenAbi, functionName: 'isFrozen', args: [who], chainId },
+            { address: tokenFor, abi: registerTokenAbi, functionName: 'balanceOf', args: [who], chainId },
+        ],
+        query: { ...query, enabled: enabled && isRegister },
+    });
+    const d = detailReads.data;
+    const issuersRegistry = d?.[0]?.status === 'success' ? d[0].result : null;
+    const topicsRegistry = d?.[1]?.status === 'success' ? d[1].result : null;
+    // Pass three: the issuers and the topics.
+    const shapeReads = useReadContracts({
+        allowFailure: true,
+        contracts: [
+            { address: (issuersRegistry ?? ZERO), abi: trustedIssuersRegistryAbi, functionName: 'getTrustedIssuers', chainId },
+            { address: (topicsRegistry ?? ZERO), abi: claimTopicsRegistryAbi, functionName: 'getClaimTopics', chainId },
+        ],
+        query: { ...query, enabled: enabled && Boolean(issuersRegistry && topicsRegistry) },
+    });
+    const s = shapeReads.data;
+    const refresh = async () => {
+        await Promise.all([tokenReads.refetch(), detailReads.refetch(), shapeReads.refetch()]);
+    };
+    // Refetch on a new block, and only on a new block: wagmi polls the block number for us.
+    const lastBlock = useRef(undefined);
+    const refetchToken = tokenReads.refetch;
+    const refetchDetail = detailReads.refetch;
+    const refetchShape = shapeReads.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 refetchToken();
+            if (isRegister)
+                void refetchDetail();
+            if (issuersRegistry && topicsRegistry)
+                void refetchShape();
+        }
+    }, [block.data, watchBlocks, enabled, isRegister, issuersRegistry, topicsRegistry, refetchToken, refetchDetail, refetchShape]);
+    return useMemo(() => {
+        const ok = (r) => (r && r.status === 'success' ? r.result : null);
+        const error = (tokenReads.error ?? detailReads.error ?? shapeReads.error);
+        const trustedIssuers = (ok(s?.[0]) ?? []);
+        const claimTopics = (ok(s?.[1]) ?? []);
+        const paused = ok(t?.[6]);
+        const isVerified = wallet ? ok(d?.[2]) : null;
+        const identity = wallet ? ok(d?.[3]) : null;
+        const frozen = wallet ? ok(d?.[4]) : null;
+        const balance = wallet ? ok(d?.[5]) : null;
+        let state;
+        if (!token)
+            state = 'disconnected';
+        else if (error)
+            state = 'error';
+        else if (tokenReads.isPending)
+            state = 'checking';
+        else if (!isRegister)
+            state = 'not-a-register';
+        else if (wallet && detailReads.isPending)
+            state = 'checking';
+        else if (paused)
+            state = 'paused';
+        else if (wallet && frozen)
+            state = 'frozen';
+        else if (wallet)
+            state = isVerified ? 'registered' : 'not-registered';
+        else
+            state = 'registered';
+        return {
+            state,
+            token: {
+                name: ok(t?.[1]),
+                symbol: ok(t?.[2]),
+                decimals: ok(t?.[3]),
+                totalSupply: ok(t?.[4]),
+                version: ok(t?.[5]),
+                paused,
+                identityRegistry: isRegister ? registryAddress : null,
+            },
+            registry: {
+                trustedIssuers,
+                claimTopics,
+                gate: isRegister && s ? (claimTopics.length === 0 ? 'registration only' : 'claims') : null,
+            },
+            wallet: wallet && isRegister ? { isVerified, registered: identity !== null && identity !== ZERO, frozen, balance } : null,
+            blockNumber: block.data,
+            isFetching: tokenReads.isFetching || detailReads.isFetching || shapeReads.isFetching,
+            error,
+            refresh,
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [token, wallet, t, d, s, isRegister, registryAddress, tokenReads.isPending, detailReads.isPending, tokenReads.isFetching, detailReads.isFetching, shapeReads.isFetching, tokenReads.error, detailReads.error, shapeReads.error, block.data]);
+}

package/package.json

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