@manifoldxyz/dropkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manifold
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,246 @@
+# @manifoldxyz/dropkit
+
+`MintButton` renders an unstyled mint button. `useMint` provides the same transaction flow for custom interfaces.
+Both support Manifold claims and ABI-configured contracts. Runtime peers are React 18+, React DOM 18+, and viem 2.
+
+## Agent recipe
+
+1. Obtain the chain ID, creator contract, and Studio instance ID from the creator's drop. Do not infer these from artwork URLs.
+2. Use `type: 'manifold-claim'` for a supported Manifold claim. Add `extension` if discovery finds multiple matches.
+3. For another contract, use `type: 'contract'` with its actual ABI and mint argument template. Verify the payable function and price units.
+4. Pass a domain-restricted RPC URL through `rpcUrls`. Never include a private key or an unrestricted secret in browser code.
+5. Render `MintButton`, or use its function child for custom markup. Call `mint` from a user gesture, never from an effect.
+6. Test disconnected, blocked, rejected, and successful paths before a release. Confirm the recipient's tokens on-chain.
+
+```tsx
+import { useState } from 'react';
+import { MintButton, type ManifoldClaimConfig } from '@manifoldxyz/dropkit';
+
+// Supply verified deployment values from the host application.
+export function Claim({ config, rpcUrl }: { config: ManifoldClaimConfig; rpcUrl: string }) {
+  const [quantity, setQuantity] = useState(1);
+  return (
+    <MintButton
+      config={config}
+      rpcUrls={{ [config.chainId]: rpcUrl }}
+      quantity={quantity}
+      onQuantityChange={setQuantity}
+      className="mint"
+      labels={{ live: 'Collect', 'sold-out': 'Gone' }}
+      onEvent={(event) => console.info(event.type, event.state)}
+    />
+  );
+}
+```
+
+A Manifold config has this shape:
+
+```ts
+import type { Address, ManifoldClaimConfig } from '@manifoldxyz/dropkit';
+
+function claimConfig(chainId: number, creatorContract: Address, instanceId: string): ManifoldClaimConfig {
+  return { type: 'manifold-claim', chainId, creatorContract, instanceId };
+}
+```
+
+`instanceId` is a decimal string. Eligibility belongs to `recipient`, which defaults to the connected wallet.
+The connected wallet pays for the mint and gas. Public claims read on-chain data without calling the Manifold allowlist API.
+
+## Contract config
+
+```ts
+import { parseAbi } from 'viem';
+import type { Address, ContractConfig } from '@manifoldxyz/dropkit';
+
+function contractConfig(chainId: number, address: Address): ContractConfig {
+  return {
+    type: 'contract',
+    chainId,
+    address,
+    abi: parseAbi([
+      'function mint(address to, uint256 quantity) payable',
+      'function price() view returns (uint256)',
+      'function totalSupply() view returns (uint256)',
+      'function maxSupply() view returns (uint256)',
+    ]),
+    mint: { functionName: 'mint', args: ['{recipient}', '{quantity}'] },
+    price: { read: { functionName: 'price' }, currency: 'native' },
+    totalMinted: { read: { functionName: 'totalSupply' } },
+    maxSupply: { read: { functionName: 'maxSupply' } },
+  };
+}
+```
+
+This example requires a contract with those exact functions. `tokenContract` overrides the address whose mint logs are parsed.
+Price currency is `'native'` or `{ address: erc20Address }`. ERC20 symbols and decimals come from the token contract.
+`price.per` defaults to `'unit'`; `'total'` means the price applies to the entire transaction.
+
+Numeric fields accept `{ value: bigint }` in base units, or `{ read: { functionName, args?, output? } }`.
+Price also accepts `{ value: '0.01', unit: 'display', currency: 'native' }`.
+Read `output` selects a tuple member by index or name. Times are Unix seconds. Absent or zero maximum supply means an open edition.
+Optional fields include `walletMinted`, `walletMax`, `startTime`, and `endTime`.
+
+Argument templates support `{recipient}`, `{payer}`, `{quantity}`, `{unitPrice}`, and `{totalPrice}`.
+Use bigint or decimal strings for integers beyond `Number.MAX_SAFE_INTEGER`.
+
+For an ERC20-priced contract with the same mint function, replace the native price with a token price:
+
+```ts
+function erc20ContractConfig(chainId: number, address: Address, paymentToken: Address): ContractConfig {
+  return {
+    ...contractConfig(chainId, address),
+    price: { value: 1_000_000n, currency: { address: paymentToken } },
+  };
+}
+```
+
+The example charges 1,000,000 token base units per mint. The deployed contract must spend that token from the payer.
+The adapter reads allowance and creates an approval leg when required. Manifold claims discover their payment token on-chain instead.
+
+## React API
+
+`useMint(options)` and `MintButton` accept:
+
+| Option | Behavior |
+| --- | --- |
+| `config` | Required `MintConfig` discriminated union. |
+| `rpcUrls` | Optional map of chain IDs to JSON-RPC URLs. |
+| `recipient` | Optional receiving address. Defaults to payer. |
+| `quantity` | Initial quantity, or controlled quantity with `onQuantityChange`. Defaults to 1. |
+| `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. |
+
+`MintButton` additionally accepts `className`, `labels`, and `children`.
+A function child receives the full `MintState` and replaces the default button.
+
+```tsx
+import { MintButton, type MintConfig } from '@manifoldxyz/dropkit';
+
+export function CustomMint({ config }: { config: MintConfig }) {
+  return (
+    <MintButton config={config}>
+      {(m) => (
+        <section>
+          <button type="button" onClick={m.mint} disabled={!m.canAct} data-state={m.state}>
+            {m.state === 'success' ? 'Minted' : m.state === 'disconnected' ? 'Connect wallet' : 'Mint'}
+          </button>
+          <p role="status">{m.message}</p>
+          {m.result?.explorerUrl && <a href={m.result.explorerUrl}>View transaction</a>}
+        </section>
+      )}
+    </MintButton>
+  );
+}
+```
+
+`useMint` returns:
+
+| Field | Type and meaning |
+| --- | --- |
+| `state`, `reason`, `message` | State name, nullable reason code, and nullable human-readable detail. |
+| `drop` | `DropInfo` or null before reads finish. Includes price, fee, supply, times, payment token, and allowlist flag. |
+| `wallet` | `WalletInfo` or null until wallet reads finish. Includes payer, recipient, chain, and mint limits. |
+| `quantity`, `setQuantity` | Current quantity and a setter that clamps requests to the supported range. |
+| `maxQuantity` | Minimum of remaining supply, wallet or allowlist limit, and 65535. Null before the drop loads. |
+| `total` | `{ native: Money, erc20: Money \| null }`, or null before the drop loads. Includes the Manifold fee. |
+| `mint` | Stable callback. Connects, submits an attempt, or resets a terminal state, depending on `state`. |
+| `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. |
+
+`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.
+
+```css
+.mint { padding: 0.75rem 1.25rem; border: 1px solid currentColor; border-radius: 0.5rem; }
+.mint:disabled { cursor: not-allowed; opacity: 0.6; }
+.mint[aria-busy="true"] { cursor: progress; }
+.mint[data-state="success"] { color: #176b39; }
+.mint[data-reason="INSUFFICIENT_FUNDS"] { color: #983b18; }
+```
+
+## States and labels
+
+Only `disconnected`, idle `live`, `success`, and `error` accept actions.
+A reset click never sends another transaction. Fresh drop and wallet reads must finish before a later mint click.
+
+| State | Default label | Action |
+| --- | --- | --- |
+| `loading` | Loading… | None |
+| `unsupported` | Unavailable | None |
+| `upcoming` | Starts {local date} | None |
+| `ended` | Ended | None |
+| `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 |
+| `ineligible` | Not eligible | None |
+| `insufficient-funds` | Insufficient {symbol} | None |
+| `switching-chain` | Switching network… | None |
+| `approving` | Approving {symbol}… | None |
+| `minting` | Confirm in wallet… | None |
+| `confirming` | Minting… | None |
+| `success` | Minted | Reset and re-read |
+| `error` | Try again | Reset and re-read |
+
+ERC20 totals include the token price and any native fee. Gas is checked separately and is not included in the label.
+
+## Reason codes
+
+| Reason | State | Meaning |
+| --- | --- | --- |
+| `UNKNOWN_EXTENSION` | `unsupported` | Extension is not supported on this chain. |
+| `AMBIGUOUS_EXTENSION` | `unsupported` | Discovery found multiple claims. Supply `extension`. |
+| `CLAIM_NOT_FOUND` | `unsupported` | No supported extension contains this claim. |
+| `SIGNATURE_CLAIM` | `unsupported` | Signature or redemption-code minting is not supported. |
+| `INVALID_CONFIG` | `unsupported` | Invalid field, ABI, function, placeholder, or chain. Read `message`. |
+| `CONNECT_WIDGET_TOO_OLD` | `unsupported` | Host widget lacks the required modal API. |
+| `NOT_ON_ALLOWLIST` | `ineligible` | Recipient has no allowlist allocation. |
+| `ALLOWLIST_USED` | `ineligible` | Recipient used all allocated indices. |
+| `WALLET_LIMIT` | `ineligible` | Recipient reached the wallet limit. |
+| `SIMULATION_REVERTED` | `ineligible` | Preflight call failed. `message` contains the available revert detail. |
+| `INSUFFICIENT_FUNDS` | `insufficient-funds` | Native payment plus gas, or ERC20 balance, is insufficient. |
+| `USER_REJECTED` | `error` | Wallet rejected or cancelled the request, or the selected payer changed before a prompt. |
+| `TX_REVERTED` | `error` | Mined transaction failed. `message` includes its hash. |
+| `RATE_LIMITED` | `error` | Upstream rate limit. Retry after the provider's cooldown. |
+| `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. |
+
+## Events and lifecycle
+
+`onEvent` receives `{ type, state, reason, chainId, quantity, config: { type, chainId, address }, txHash? }`.
+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.
+
+Every hook owns its reducer, read generations, and attempt guard. Buttons share only the connect widget.
+Server rendering produces a loading button without wallet calls or adapter reads.
+Drop data refreshes every 30 seconds while visible, on visibility changes, and at start or end boundaries.
+
+An attempt freezes config, payer, recipient, quantity, chain, and token contract.
+Prop changes and background refreshes wait until the attempt finishes.
+Unmount aborts the adapter lifetime and prevents subsequent prompts or callbacks. A submitted transaction cannot be cancelled by unmounting.
+
+Approval is simulated before its prompt. A successful approval receipt is followed by fresh eligibility checks and mint simulation.
+Receipt parsing filters mint transfers by token contract and recipient. Cancellation or changed transaction intent reports an error; a speed-up uses the replacement hash.
+
+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.
+
+## Local verification
+
+From the repository root, use Node 24 and put Foundry binaries in `PATH`:
+
+```sh
+pnpm install --frozen-lockfile
+cd packages/react/dropkit
+pnpm exec vitest run
+pnpm run typecheck
+pnpm run lint
+pnpm run build
+```
+
+The full tests require `SEPOLIA_RPC_URL` and `anvil`. Fork tests use block 11838500 and fail rather than skip when prerequisites are missing.
+The repository's pnpm policy enforces a seven-day release age, except for `@manifoldxyz/*` packages.