@manifoldxyz/dropkit 0.1.0 → 0.2.0

package/README.md

@@ -110,6 +110,8 @@ The adapter reads allowance and creates an approval leg when required. Manifold
 | `onQuantityChange` | Receives the clamped requested quantity. The parent must update `quantity`. |
 | `connect` | Optional `{ walletConnectProjectId }` forwarded to the shared connect widget. |
 | `onEvent` | Optional event callback. No telemetry is sent by the package. |
+| `crossChain` | Manifold claims only. Default on. `false` turns cross-chain minting off; `{ chains: [8453] }` narrows the pay chains. |
+| `payChainId` | Forces the pay chain. The drop chain means a direct mint. Must be a pay chain. |
 
 `MintButton` additionally accepts `className`, `labels`, and `children`.
 A function child receives the full `MintState` and replaces the default button.
@@ -148,6 +150,8 @@ export function CustomMint({ config }: { config: MintConfig }) {
 | `refresh` | Stable callback returning `Promise<void>`. Re-reads drop data. Queues refreshes during an attempt. |
 | `result` | `{ txHash, explorerUrl, tokens }` after success, otherwise null. Token IDs and amounts are bigint. |
 | `canAct` | Whether a click can act. False during an attempt, including its pre-prompt planning phase. |
+| `route` | `{ kind: 'direct', chainId }` or `{ kind: 'relay', originChainId, amountIn, relayFee, originGas, quotedAt }`. Null before the wallet read. |
+| `crossChain` | Inputs for `PayWithPicker`. Null when Relay cannot mint this drop for this wallet. |
 
 `Money` is `{ value: bigint, decimals: number, symbol: string, formatted: string }`.
 The component ships no CSS. The default button exposes `data-state`, `data-reason`, `disabled`, and `aria-busy` during asynchronous states.
@@ -174,7 +178,7 @@ A reset click never sends another transaction. Fresh drop and wallet reads must
 | `sold-out` | Sold out | None |
 | `disconnected` | Connect wallet | Open connect modal |
 | `connecting` | Connecting… | None |
-| `live` | Mint · {total} | Switch chain if needed, then approve and mint |
+| `live` | Mint · {total}, or Mint · {amount} on {chain} over Relay | Switch chain if needed, then approve and mint |
 | `ineligible` | Not eligible | None |
 | `insufficient-funds` | Insufficient {symbol} | None |
 | `switching-chain` | Switching network… | None |
@@ -207,10 +211,15 @@ ERC20 totals include the token price and any native fee. Gas is checked separate
 | `RPC_ERROR` | `error` | Read or transaction transport failed. Supply a working RPC URL. |
 | `CHAIN_SWITCH_FAILED` | `error` | Wallet could not switch to, or did not remain on, the configured chain. |
 | `ALLOWLIST_UNAVAILABLE` | `error` | Required allowlist data could not be loaded. |
+| `BRIDGE_UNAVAILABLE` | `error` | Relay could not quote or returned a route the button cannot run. Nothing was sent. |
+| `BRIDGE_TIMEOUT` | `error` | Paid, but Relay had no final status after 10 minutes. The next click resumes the same request. |
+| `BRIDGE_REFUNDED` | `error` | Relay could not mint and is refunding the payer. |
+| `BRIDGE_FAILED` | `error` | Relay failed. `message` names the Relay request and says whether a refund was sent. |
 
 ## Events and lifecycle
 
-`onEvent` receives `{ type, state, reason, chainId, quantity, config: { type, chainId, address }, txHash? }`.
+`onEvent` receives `{ type, state, reason, chainId, quantity, config: { type, chainId, address }, route, originChainId, txHash? }`.
+`route` is `direct` or `relay`. `originChainId` is the chain the collector pays on.
 Types are `state`, `attempt`, `approve-submitted`, `tx-submitted`, `success`, and `error`.
 The config address is the mint target for contract configs and the creator contract for Manifold claims.
 Transaction events use the frozen attempt, not later props. Payloads omit payer and recipient addresses.
@@ -229,18 +238,57 @@ Receipt parsing filters mint transfers by token contract and recipient. Cancella
 No direct analytics requests or `/public/instance/tx` posts are made.
 Manifold allowlist calls are GET requests. JSON-RPC reads and wallet transactions still use their normal transports.
 
+## Cross-chain mint (Relay)
+
+A Manifold claim can be paid from another chain. Relay takes the payment there and calls `mintProxy` on the drop chain, minting to the recipient.
+
+- **When:** native-priced claim on a V6/V7 extension (721 or 1155), drop on Ethereum, Base, Optimism or Shape (pay chains: Ethereum, Base, Optimism, Shape, ApeChain), or on Sepolia (pay chain: Base Sepolia). ERC20-priced drops, V8 claims and contract configs mint directly only.
+- **Which chain pays:** the chain the wallet is on. A wallet on another pay chain with enough funds mints over Relay, even when the drop chain also has funds. A wallet on the drop chain mints directly.
+- **Providers:** Dropkit only reads balances through the connected wallet, for the chain it is on. It never queries another chain's RPC. Relay quotes come from `api.relay.link` (no API key).
+- **Cost:** the label shows the amount paid on the pay chain, excluding gas, e.g. `Mint · 0.00326 ETH on Base` for a 0.003 ETH mint (Relay fee ≈ 0.00026 ETH). The funds check includes gas.
+- **Short on the wallet chain:** `Not enough ETH on Base. Pick another network to pay from.` Render `PayWithPicker` so collectors can switch.
+- **One signature:** the collector signs one deposit on the pay chain. The button polls Relay until the mint lands on the drop chain, then reads token IDs. `result.relay` holds `{ requestId, originTxHash, originChainId }`.
+- **Never pays twice on this page:** after a timeout, the next click resumes the same Relay request instead of paying again. Only one button per drop and wallet can prompt a payment at a time. A reload forgets it, same as claim-widgets.
+
+`PayWithPicker` lists every pay chain with Relay's fee (`None` on the drop chain) and the balance of the wallet's current chain. Chains Relay cannot quote are hidden. Picking a row switches the wallet. It quotes every 20 seconds while mounted and renders nothing when Relay does not apply.
+
+```tsx
+import { MintButton, PayWithPicker, type MintConfig } from '@manifoldxyz/dropkit';
+
+export function CrossChainMint({ config }: { config: MintConfig }) {
+  return (
+    <MintButton config={config}>
+      {(m) => (
+        <>
+          <button type="button" onClick={m.mint} disabled={!m.canAct} data-state={m.state}>
+            {m.route?.kind === 'relay' ? `Mint · ${m.route.amountIn.formatted} ${m.route.amountIn.symbol}` : 'Mint'}
+          </button>
+          {m.message && <p role="status">{m.message}</p>}
+          <PayWithPicker mint={m} className="pay-with" />
+        </>
+      )}
+    </MintButton>
+  );
+}
+```
+
+Rows expose `data-chain`, `data-selected`, `data-loading` and `aria-pressed`. `renderRow` replaces the row content.
+
 ## Local verification
 
-From the repository root, use Node 24 and put Foundry binaries in `PATH`:
+From the repository root, use Node 24 and pnpm 10.34.5:
 
 ```sh
 pnpm install --frozen-lockfile
 cd packages/react/dropkit
-pnpm exec vitest run
+pnpm test             # fast unit and component tests, no network
+pnpm test:chain       # adapters against a local Sepolia fork
 pnpm run typecheck
 pnpm run lint
 pnpm run build
+pnpm verify:package   # packed tarball in clean React 18 and 19 consumers
 ```
 
-The full tests require `SEPOLIA_RPC_URL` and `anvil`. Fork tests use block 11838500 and fail rather than skip when prerequisites are missing.
+`test:chain` requires `anvil` on `PATH` and `SEPOLIA_RPC_URL`. It forks block 11838500 and fails rather than skips when either is missing.
+`verify:package` needs npm registry access. It type-checks every TypeScript example in this README.
 The repository's pnpm policy enforces a seven-day release age, except for `@manifoldxyz/*` packages.