diff --git a/docs/agents.md b/docs/agents.md index 4de882baa..e4bb3c74a 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -11,11 +11,13 @@ Base is an Ethereum L2 by Coinbase. Docs for: Base Chain, Smart Wallet, OnchainK |ai-agents/skills/trading:alchemy-agentic-gateway,coingecko,swap-execution |ai-agents/skills/wallets:bankr,cdp-agentic-wallet,sponge-wallet |ai-agents/trading:data-fetching,trade-execution +|apps/builder-codes:agent-developers,app-developers,builder-codes,wallet-developers |apps/growth:rewards -|apps/quality-and-publishing:overview,quality-bar,submission-guidelines -|apps/quickstart:build-checklist,building-for-the-base-app,create-new-app,migrate-existing-apps,migrate-to-standard-web-app,template -|apps/technical-guides:accept-payments,base-notifications,building-chat-agents,neynar-notifications,sharing-and-social-graph,sign-manifest -|base-account/basenames:basename-transfer,basenames-faq,basenames-wagmi-tutorial +|apps/guides:migrate-to-standard-web-app +|apps/quickstart:build-app +|apps/resources:design-resources,templates +|apps/technical-guides:base-notifications +|base-account/basenames:basename-transfer,basenames-faq |base-account/contribute:contribute-to-base-account-docs,security-and-bug-bounty |base-account/framework-integrations:cdp,rainbowkit,reown,thirdweb |base-account/framework-integrations/privy:authentication,setup,spend-permissions,sub-accounts,wallet-actions @@ -40,12 +42,11 @@ Base is an Ethereum L2 by Coinbase. Docs for: Base Chain, Smart Wallet, OnchainK |base-chain/api-reference/debug-api:debug_traceBlockByHash,debug_traceBlockByNumber,debug_traceTransaction |base-chain/api-reference/ethereum-json-rpc-api:eth_blockNumber,eth_call,eth_chainId,eth_estimateGas,eth_feeHistory,eth_gasPrice,eth_getBalance,eth_getBlockByHash,eth_getBlockByNumber,eth_getBlockReceipts,eth_getBlockTransactionCountByHash,eth_getBlockTransactionCountByNumber,eth_getCode,eth_getLogs,eth_getStorageAt,eth_getTransactionByBlockHashAndIndex,eth_getTransactionByBlockNumberAndIndex,eth_getTransactionByHash,eth_getTransactionCount,eth_getTransactionReceipt,eth_maxPriorityFeePerGas,eth_sendRawTransaction,eth_subscribe,eth_syncing,eth_unsubscribe,net_version,web3_clientVersion |base-chain/api-reference/flashblocks-api:base_transactionStatus,eth_simulateV1,flashblocks-api-overview,newFlashblockTransactions,newFlashblocks,pendingLogs -|base-chain/builder-codes:agent-developers,app-developers,builder-codes,wallet-developers -|base-chain/flashblocks:app-integration,architecture,faq,overview,run-a-flashblocks-node +|base-chain/flashblocks:app-integration,architecture,faq,overview |base-chain/network-information:base-contracts,block-building,bridges,configuration-changelog,diffs-ethereum-base,ecosystem-contracts,network-faucets,network-fees,transaction-finality,troubleshooting-transactions -|base-chain/node-operators:node-providers,performance-tuning,run-a-base-node,snapshots,troubleshooting +|base-chain/node-operators:base-v1-upgrade,node-providers,performance-tuning,run-a-base-node,snapshots,troubleshooting |base-chain/quickstart:base-solana-bridge,connecting-to-base,deploy-on-base,why-base |base-chain/security:avoid-malicious-flags,bug-bounty,report-vulnerability,security-council -|get-started:base-mentorship-program,base-services-hub,base,block-explorers,build-app,concepts,country-leads-and-ambassadors,data-indexers,deploy-smart-contracts,docs-llms,docs-mcp,get-funded,launch-token,learning-resources,mistakes,prompt-library,resources-for-ai-agents +|get-started:base-mentorship-program,base-services-hub,base,block-explorers,concepts,country-leads-and-ambassadors,data-indexers,deploy-smart-contracts,docs-llms,docs-mcp,get-funded,launch-token,learning-resources,mistakes,prompt-library,resources-for-ai-agents |onchainkit:migrate-from-onchainkit |root:agents,changes,cookie-policy,privacy-policy,terms-of-service,tone_of_voice diff --git a/docs/apps/quickstart/migrate-to-standard-web-app.mdx b/docs/apps/guides/migrate-to-standard-web-app.mdx similarity index 93% rename from docs/apps/quickstart/migrate-to-standard-web-app.mdx rename to docs/apps/guides/migrate-to-standard-web-app.mdx index e4796ea30..afe2fd066 100644 --- a/docs/apps/quickstart/migrate-to-standard-web-app.mdx +++ b/docs/apps/guides/migrate-to-standard-web-app.mdx @@ -1,7 +1,6 @@ --- title: "Migrate to a Standard Web App" description: "Migrate your Farcaster mini-app to work in the Base App. Covers replacing deprecated SDK methods, and registering on Base.dev." -tag: "NEW" --- @@ -20,7 +19,7 @@ The Base App is moving from the Farcaster mini-app spec to a single model: **sta | --- | --- | | Farcaster manifest (`/.well-known/farcaster.json`) | App metadata on [Base.dev](https://www.base.dev) projects. Already registered apps do not need to update metadata. | | Neynar webhooks for add/remove events | Base-owned backends (Base Account / address preferences) | -| FID-based notifications via Neynar | Wallet-address notifications via Base.dev notifications API *(coming soon)* | +| FID-based notifications via Neynar | Wallet-address notifications through the [Notifications API](/apps/technical-guides/base-notifications) | | Farcaster SDK for auth and actions | wagmi + viem + Sign-In with Ethereum (SIWE) | | Search and discovery via Farcaster | Base.dev app metadata + [builder codes](https://docs.base.org/apps/builder-codes/builder-codes) | @@ -166,10 +165,7 @@ Your app uses the Farcaster SDK. The migration replaces Farcaster-specific auth, - - Notifications migration will be available in Base.dev soon. - - Farcaster-based notifications (via Neynar, FIDs, or tokens) will not reach Base App users. Replace them with the Base.dev notifications API, which sends by wallet address. + Farcaster-based notifications (via Neynar, FIDs, or tokens) will not reach Base App users. Follow the [Notifications guide](/apps/technical-guides/base-notifications) to fetch opted-in wallet addresses and send notifications through the Base Dashboard API. @@ -197,10 +193,7 @@ Your app is already a standard web app. You're mostly done — just verify your - - Notifications migration will be available in Base.dev soon. - - Use the Base.dev notifications API to send wallet-address notifications to users who installed your app and opted in. + Follow the [Notifications guide](/apps/technical-guides/base-notifications) to send wallet-address notifications to users who installed your app and opted in. @@ -250,10 +243,7 @@ Before considering your app migrated, verify the following: - - Notifications migration will be available in Base.dev soon. - - Notifications are sent via the Base.dev notifications API by wallet address — not via Neynar, FIDs, or tokens. + Notifications are sent by wallet address using the [Notifications guide](/apps/technical-guides/base-notifications), not through Neynar, FIDs, or tokens. diff --git a/docs/apps/llms-full.txt b/docs/apps/llms-full.txt index 1a9f7b432..bac73aa22 100644 --- a/docs/apps/llms-full.txt +++ b/docs/apps/llms-full.txt @@ -5,23 +5,35 @@ > The Base App now treats all apps as standard web apps. Migrate from Farcaster-specific SDKs to wagmi + SIWE, register on Base.dev, and earn rewards for driving onchain activity. ### What you can do here +- Build a Next.js app on Base with wagmi, viem, wallet connection, contract reads, contract writes, and batch transactions - Migrate an existing Farcaster-embedded app to a standard web app compatible with the Base App - Register your app on Base.dev for search, discovery, and rewards eligibility - Replace deprecated Farcaster SDK methods with standard web equivalents (wagmi, viem, SIWE) - Earn financial rewards for building apps that drive user engagement and onchain transactions +- Attribute onchain transactions to your app using Builder Codes (ERC-8021) +- Send in-app push notifications to opted-in users via the Base Dashboard Notifications API ## Navigation (with brief descriptions) ### Quickstart -- [Migrate to a Standard Web App](https://docs.base.org/apps/quickstart/migrate-to-standard-web-app.md) — Step-by-step migration guide: replace Farcaster SDK, update auth and wallet logic, register on Base.dev +- [Build an App](https://docs.base.org/apps/quickstart/build-app.md) — Step-by-step guide to build a Next.js app on Base with wagmi and viem + +### Guides +- [Add notifications](https://docs.base.org/apps/technical-guides/base-notifications.md) — REST API (via Base Dashboard) to fetch opted-in users and send in-app notifications; Base App only +- [Migrate to a Standard Web App](https://docs.base.org/apps/guides/migrate-to-standard-web-app.md) — Step-by-step migration guide: replace Farcaster SDK, update auth and wallet logic, register on Base.dev ### Growth - [Rewards](https://docs.base.org/apps/growth/rewards.md) — Verification programs, competitions, and partner opportunities for earning rewards +### Builder Codes +- [Builder Codes overview](https://docs.base.org/apps/builder-codes/builder-codes.md) — ERC-8021 NFT codes that attribute onchain transactions to your app; register on base.dev under Settings → Builder Code +- [For App Developers](https://docs.base.org/apps/builder-codes/app-developers.md) — Append a dataSuffix to transactions using wagmi or viem; no contract changes required +- [For Wallet Developers](https://docs.base.org/apps/builder-codes/wallet-developers.md) — Implement the ERC-5792 DataSuffixCapability so wallets pass through attribution suffixes +- [For Agent Developers](https://docs.base.org/apps/builder-codes/agent-developers.md) — Attribute AI agent transactions via the Builder Codes API ## Key Concepts (excerpts) -Source: `https://docs.base.org/apps/quickstart/migrate-to-standard-web-app.md` +Source: `https://docs.base.org/apps/guides/migrate-to-standard-web-app.md` After April 9, 2026, the Base App treats all apps as standard web apps regardless of Farcaster manifests. Key changes: @@ -29,7 +41,7 @@ After April 9, 2026, the Base App treats all apps as standard web apps regardles | --- | --- | | Farcaster manifest (`/.well-known/farcaster.json`) | App metadata on Base.dev | | Neynar webhooks for add/remove events | Base-owned backends (Base Account / address preferences) | -| FID-based notifications via Neynar | Wallet-address notifications via Base.dev notifications API | +| FID-based notifications via Neynar | Wallet-address notifications through the Notifications API | | Farcaster SDK for auth and actions | wagmi + viem + Sign-In with Ethereum (SIWE) | | Search and discovery via Farcaster | Base.dev app metadata + builder codes | @@ -43,6 +55,25 @@ Base.dev rewards developers who build apps that deliver real value and drive mea 1. Submit your app for verification on Base.dev — validates ownership by adding a Base builder address in the manifest 2. Access earning opportunities — partner programs, competitions, and special campaigns +Source: `https://docs.base.org/apps/builder-codes/builder-codes.md` + +Builder Codes are ERC-721 NFTs (unique strings like "abc123") that tag transactions with your app identity using ERC-8021 calldata suffixes. No contract changes are required — attribution is extracted offchain. Benefits: automatic reward attribution, analytics on base.dev, and discovery surface visibility. The suffix adds 16 gas per non-zero byte. Works with EOAs, smart wallets (ERC-5792 `dataSuffix` capability), and embedded wallets (Privy, Turnkey). + +Source: `https://docs.base.org/apps/technical-guides/base-notifications.md` + +The Notifications API sends in-app push notifications to Base App users who have pinned your app and opted in. Requires a Base Dashboard project and API key. + +Key constraints: +- Notifications delivered in the **Base App only** — not other platforms +- Rate limit: **20 requests/minute per IP** shared across both endpoints +- `POST /send`: up to 1,000 addresses per request; title ≤30 chars, message ≤200 chars +- Deduplication: identical notifications within 24 hours are suppressed automatically +- Failure reasons: `user has not saved this app`, `user has notifications disabled` + +Workflow: +1. `GET /v1/notifications/app/users?app_url=¬ification_enabled=true` — fetch opted-in wallet addresses (paginated, cursor-based) +2. `POST /v1/notifications/send` — send title + message + optional `target_path` to up to 1,000 addresses + ## Related indexes - Root index: `../llms.txt` diff --git a/docs/apps/llms.txt b/docs/apps/llms.txt index 53c10eba2..9984d6f6c 100644 --- a/docs/apps/llms.txt +++ b/docs/apps/llms.txt @@ -5,7 +5,18 @@ > Build apps that run in the Base App as standard web apps — no Farcaster SDK required. Register on Base.dev, use wagmi + SIWE for auth, and earn rewards for driving onchain activity. ## Quickstart -- [Migrate to a Standard Web App](https://docs.base.org/apps/quickstart/migrate-to-standard-web-app.md) — Replace deprecated Farcaster SDK methods and register your app on Base.dev +- [Build an App](https://docs.base.org/apps/quickstart/build-app.md) — End-to-end guide to ship your first app on Base + +## Guides +- [Add notifications](https://docs.base.org/apps/technical-guides/base-notifications.md) — Send in-app notifications to users via the Base Dashboard REST API +- [Migrate to a Standard Web App](https://docs.base.org/apps/guides/migrate-to-standard-web-app.md) — Replace deprecated Farcaster SDK methods and register your app on Base.dev ## Growth - [Rewards](https://docs.base.org/apps/growth/rewards.md) — Earn financial incentives for building apps that drive user engagement and onchain transactions + +## Builder Codes +- [Builder Codes overview](https://docs.base.org/apps/builder-codes/builder-codes.md) — Attribute onchain activity to your app using ERC-8021 NFT codes; register on base.dev +- [For App Developers](https://docs.base.org/apps/builder-codes/app-developers.md) — Integrate Builder Codes using wagmi or viem +- [For Wallet Developers](https://docs.base.org/apps/builder-codes/wallet-developers.md) — Implement the dataSuffix ERC-5792 capability +- [For Agent Developers](https://docs.base.org/apps/builder-codes/agent-developers.md) — Attribute AI agent transactions via the API + diff --git a/docs/get-started/build-app.mdx b/docs/apps/quickstart/build-app.mdx similarity index 99% rename from docs/get-started/build-app.mdx rename to docs/apps/quickstart/build-app.mdx index c292e60a8..b2253affa 100644 --- a/docs/get-started/build-app.mdx +++ b/docs/apps/quickstart/build-app.mdx @@ -541,6 +541,7 @@ Base is a fast, low-cost Ethereum L2 built to bring the next billion users oncha - **Go to mainnet** — add `base` to your `chains` array and transports in `config/wagmi.ts`, redeploy your contract to Base mainnet, and update `COUNTER_ADDRESS`. - **Sponsor gas** — use the `paymasterService` capability with `useSendCalls` to cover your users' transaction fees. See [Sponsor Gas](/base-account/improve-ux/sponsor-gas/paymasters). +- **Send notifications** — use the [Notifications guide](/apps/technical-guides/base-notifications) to fetch opted-in wallet addresses and send in-app notifications. - **Batch read calls** — reduce RPC round trips by batching reads via viem's `multicall`. - **Optimistic updates** — update the UI before confirmation using TanStack Query's `onMutate` callback. - **Wagmi setup reference** — review the full [Wagmi setup guide](/base-account/framework-integrations/wagmi/setup) for additional configuration options. diff --git a/docs/apps/technical-guides/base-notifications.mdx b/docs/apps/technical-guides/base-notifications.mdx index 1c699e501..7469ce987 100644 --- a/docs/apps/technical-guides/base-notifications.mdx +++ b/docs/apps/technical-guides/base-notifications.mdx @@ -1,5 +1,5 @@ --- -title: "Notifications" +title: "Add notifications" description: "Send in-app notifications to your app's users through the Base Dashboard REST API." --- @@ -19,7 +19,7 @@ The Notifications API lets you send in-app notifications to users who have pinne Both endpoints require your API key in the `x-api-key` header. - The notification endpoints share a rate limit of **10 requests per minute per IP**. Requests to either endpoint count toward the same limit. Exceeding it returns a `429 Too Many Requests` response. + The notification endpoints share a rate limit of **20 requests per minute per IP**. Requests to either endpoint count toward the same limit. Exceeding it returns a `429 Too Many Requests` response. Fetch the wallet addresses of users who have opted in to notifications for your app: @@ -90,7 +90,7 @@ GET https://dashboard.base.org/api/v1/notifications/app/users - Maximum users per page. Capped at 100. + Maximum users per page. Capped at 500. #### Response diff --git a/docs/base-chain/llms-full.txt b/docs/base-chain/llms-full.txt index 61d969c78..f3401cbf9 100644 --- a/docs/base-chain/llms-full.txt +++ b/docs/base-chain/llms-full.txt @@ -48,6 +48,7 @@ ### Node Operators - [Run a Base Node](https://docs.base.org/base-chain/node-operators/run-a-base-node.md) — Node setup +- [Base Azul Upgrade](https://docs.base.org/base-chain/node-operators/base-v1-upgrade.md) — Migrate to base-reth-node and base-consensus for Azul - [Performance Tuning](https://docs.base.org/base-chain/node-operators/performance-tuning.md) — Optimization - [Snapshots](https://docs.base.org/base-chain/node-operators/snapshots.md) — Snapshot sync - [Troubleshooting](https://docs.base.org/base-chain/node-operators/troubleshooting.md) — Common fixes diff --git a/docs/base-chain/llms.txt b/docs/base-chain/llms.txt index 88080db73..8c790637b 100644 --- a/docs/base-chain/llms.txt +++ b/docs/base-chain/llms.txt @@ -13,13 +13,18 @@ ## Network Information - [Network Fees](https://docs.base.org/base-chain/network-information/network-fees.md) — L2 execution and L1 data costs on Base - [Base Contracts](https://docs.base.org/base-chain/network-information/base-contracts.md) — Core contracts and addresses +- [Block Building](https://docs.base.org/base-chain/network-information/block-building.md) — How blocks are ordered and built on Base - [Bridges](https://docs.base.org/base-chain/network-information/bridges.md) — Official and third-party bridge options +- [Differences: Ethereum & Base](https://docs.base.org/base-chain/network-information/diffs-ethereum-base.md) — Behavioral differences between Base and Ethereum +- [Transaction Finality](https://docs.base.org/base-chain/network-information/transaction-finality.md) — When transactions become irreversible on Base - [Troubleshooting Transactions](https://docs.base.org/base-chain/network-information/troubleshooting-transactions.md) — Diagnose and fix common transaction issues +- [Configuration Changelog](https://docs.base.org/base-chain/network-information/configuration-changelog.md) — Log of network configuration changes - [Network Faucets](https://docs.base.org/base-chain/network-information/network-faucets.md) — Obtain testnet ETH for Base Sepolia ## Flashblocks - [Overview](https://docs.base.org/base-chain/flashblocks/overview.md) — What Flashblocks is and how it works - [App Integration](https://docs.base.org/base-chain/flashblocks/app-integration.md) — How apps integrate with Flashblocks +- [Architecture](https://docs.base.org/base-chain/flashblocks/architecture.md) — Sequencer architecture and infrastructure components - [FAQ](https://docs.base.org/base-chain/flashblocks/faq.md) — Frequently asked questions about Flashblocks ## API Reference @@ -30,7 +35,10 @@ ## Node Operators - [Run a Base Node](https://docs.base.org/base-chain/node-operators/run-a-base-node.md) — Setup and operations guide +- [Base Azul Upgrade](https://docs.base.org/base-chain/node-operators/base-v1-upgrade.md) — Migrate to base-reth-node and base-consensus for Azul - [Performance Tuning](https://docs.base.org/base-chain/node-operators/performance-tuning.md) — Optimize node performance +- [Snapshots](https://docs.base.org/base-chain/node-operators/snapshots.md) — Snapshot sync to speed up initial node setup +- [Troubleshooting](https://docs.base.org/base-chain/node-operators/troubleshooting.md) — Diagnose and fix common node issues - [Node Providers](https://docs.base.org/base-chain/node-operators/node-providers.md) — RPC node providers for Base ## Protocol Specs @@ -59,6 +67,7 @@ ## Security - [Report a Vulnerability](https://docs.base.org/base-chain/security/report-vulnerability.md) — Security contact and disclosure - [Security Council](https://docs.base.org/base-chain/security/security-council.md) — Governance and process overview +- [Avoid Malicious Flags](https://docs.base.org/base-chain/security/avoid-malicious-flags.md) — How to avoid app-blocklist flags ## Builder Codes - [Builder Codes](https://docs.base.org/apps/builder-codes/builder-codes.md) — Overview of the Builder Codes program diff --git a/docs/changes.md b/docs/changes.md index b9b9970e8..642d253ae 100644 --- a/docs/changes.md +++ b/docs/changes.md @@ -33,7 +33,7 @@ Cross-links updated in **non-hidden** docs only, e.g. [`get-started/learning-res - [`docs/docs.json`](docs.json) — navigation, redirects, wildcard. - [`docs/.mintignore`](.mintignore) — paths under `/apps/...`. -- [`docs/apps/**`](apps/) — **Visible** pages (e.g. `quickstart/migrate-to-standard-web-app`, `growth/rewards`, `technical-guides/base-notifications`) plus `llms.txt` / `llms-full.txt`. +- [`docs/apps/**`](apps/) — **Visible** pages (e.g. `guides/migrate-to-standard-web-app`, `growth/rewards`, `technical-guides/base-notifications`) plus `llms.txt` / `llms-full.txt`. - [`docs/llms.txt`](llms.txt), [`docs/llms-full.txt`](llms-full.txt). - [`claude.md`](../claude.md) — repo structure diagram. - [`scripts/generate-agents-md.js`](../scripts/generate-agents-md.js) — comments. @@ -42,5 +42,5 @@ Cross-links updated in **non-hidden** docs only, e.g. [`get-started/learning-res ## Verification 1. **`node scripts/lint-mdx.js`** — Run after edits. -2. **Spot-check**: `/apps/quickstart/migrate-to-standard-web-app`, `/apps/quickstart/create-new-app`, `/apps/growth/rewards`. +2. **Spot-check**: `/apps/guides/migrate-to-standard-web-app`, `/apps/quickstart/create-new-app`, `/apps/growth/rewards`. 3. **Legacy URLs**: `/mini-apps/...` → `/apps/...` via redirects; hidden pages may still contain `/mini-apps/` in **source** links (unchanged); those URLs redirect when hit. diff --git a/docs/docs.json b/docs/docs.json index 9b779b87d..414f00fc5 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -38,7 +38,7 @@ "group": "Quickstart", "pages": [ "get-started/resources-for-ai-agents", - "get-started/build-app", + "apps/quickstart/build-app", "get-started/launch-token", "get-started/deploy-smart-contracts", "get-started/learning-resources" @@ -646,17 +646,19 @@ { "group": "Quickstart", "pages": [ - "apps/quickstart/migrate-to-standard-web-app", - "get-started/build-app" + "apps/quickstart/build-app" ] }, { - "group": "Growth", - "pages": ["apps/growth/rewards"] + "group": "Guides", + "pages": [ + "apps/technical-guides/base-notifications", + "apps/guides/migrate-to-standard-web-app" + ] }, { - "group": "Notifications", - "pages": ["apps/technical-guides/base-notifications"] + "group": "Growth", + "pages": ["apps/growth/rewards"] }, { "group": "Builder Codes", @@ -847,95 +849,95 @@ }, { "source": "/mini-apps/core-concepts/*", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/mini-apps/resources/*", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/mini-apps/featured-guidelines/*", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/mini-apps/troubleshooting/*", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/mini-apps/introduction/*", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/mini-apps/growth/optimize-onboarding", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/mini-apps/technical-guides/dynamic-embeds", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/getting-started", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/latest/getting-started/overview", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/latest/getting-started/quickstart-guide", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/latest/getting-started/manual-installation", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/latest/getting-started/troubleshooting", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/installation/nextjs", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/installation/vite", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/installation/remix", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/installation/astro", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/config/onchainkit-provider", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/config/supplemental-providers", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/config/is-base", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/config/is-ethereum", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/config/types", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/latest/configuration/onchainkit-provider", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/latest/configuration/wagmi-viem-integration", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/ai-agents/guides/agent-builder-codes", @@ -943,11 +945,11 @@ }, { "source": "/onchainkit/latest/configuration/themes", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/guides/telemetry", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/base-account/basenames/basenames-wagmi-tutorial", @@ -955,95 +957,95 @@ }, { "source": "/onchainkit/guides/troubleshooting", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/guides/lifecycle-status", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/guides/tailwind", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/guides/themes", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/guides/use-basename-in-onchain-app", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/guides/using-ai-powered-ides", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/guides/ai-prompting-guide", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/guides/contribution", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/guides/reporting-bug", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/latest/guides/ai-prompting-guide", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/latest/guides/contributing", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/templates/onchain-nft-app", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/templates/onchain-commerce-app", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/templates/onchain-social-profile", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/paymaster/welcome", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/paymaster/quickstart-guide", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/paymaster/quickstart-headless", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/paymaster/erc20-paymaster", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/paymaster/gasless-transactions-with-paymaster", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/paymaster/security", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/paymaster/troubleshooting", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/paymaster/errors", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/paymaster/how-to-contribute", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/onchainkit/latest/components/minikit/overview", @@ -2595,7 +2597,15 @@ }, { "source": "/quickstart", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" + }, + { + "source": "/get-started/build-app", + "destination": "/apps/quickstart/build-app" + }, + { + "source": "/apps/quickstart/migrate-to-standard-web-app", + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/tools/network-faucets", @@ -2655,7 +2665,7 @@ }, { "source": "/wallet-app/mini-apps", - "destination": "/get-started/build-app" + "destination": "/apps/quickstart/build-app" }, { "source": "/wallet-app/chat-agents", @@ -2691,11 +2701,11 @@ }, { "source": "/base-app/miniapps/existing-app-integration", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/base-app/build-with-minikit/existing-app-integration", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/base-app/miniapps/quickstart", @@ -2707,11 +2717,11 @@ }, { "source": "/mini-apps/quickstart/existing-apps/:slug*", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/mini-apps/quickstart/migrate-existing-apps", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/mini-apps/quickstart/new-apps/:slug*", @@ -2943,23 +2953,23 @@ }, { "source": "/cookbook/converting-customizing-mini-apps", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/cookbook/minikit/fork-and-customize", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/cookbook/minikit/install", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/cookbook/minikit/add-minikit", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/cookbook/minikit/configure-environment", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/cookbook/minikit/manifest-cli", @@ -2979,7 +2989,7 @@ }, { "source": "/mini-apps/mini-apps/quickstart/migrate-to-standard-web-app", - "destination": "/apps/quickstart/migrate-to-standard-web-app" + "destination": "/apps/guides/migrate-to-standard-web-app" }, { "source": "/ai-agents/core-concepts/agent-frameworks", diff --git a/docs/get-started/llms-full.txt b/docs/get-started/llms-full.txt index ac7bcf509..607bbaf7a 100644 --- a/docs/get-started/llms-full.txt +++ b/docs/get-started/llms-full.txt @@ -7,7 +7,7 @@ ### What you can do here - Understand Base's value prop and ecosystem - Explore core concepts -- Follow quickstarts to build app/token/contracts +- Follow quickstarts to build apps, launch tokens, and deploy contracts - Find funding, services, and community support - Use AI prompting resources and prompt library - Find block explorers and data indexers for onchain development @@ -19,7 +19,7 @@ - [Concepts](https://docs.base.org/get-started/concepts.md) — Core concepts and terminology ### Quickstart -- [Build an App](https://docs.base.org/get-started/build-app.md) — Ship an app on Base +- [Build an App](https://docs.base.org/apps/quickstart/build-app.md) — Ship an app on Base - [Launch a Token](https://docs.base.org/get-started/launch-token.md) — Token planning and launch - [Deploy Smart Contracts](https://docs.base.org/get-started/deploy-smart-contracts.md) — Contracts - [Learning Resources](https://docs.base.org/get-started/learning-resources.md) — Tutorials and guides @@ -31,6 +31,7 @@ - [Country Leads & Ambassadors](https://docs.base.org/get-started/country-leads-and-ambassadors.md) — Community ### Build with AI +- [Resources for AI Agents](https://docs.base.org/get-started/resources-for-ai-agents.md) — Docs indexes, MCP access, skills, and recommended starting points for AI agents - [Docs LLMs](https://docs.base.org/get-started/docs-llms.md) — How to use these docs with AI tools - [Docs MCP](https://docs.base.org/get-started/docs-mcp.md) — Model Context Protocol integration - [Prompt Library](https://docs.base.org/get-started/prompt-library.md) — Reusable prompts diff --git a/docs/get-started/llms.txt b/docs/get-started/llms.txt index 43d3a8d00..10d6939ca 100644 --- a/docs/get-started/llms.txt +++ b/docs/get-started/llms.txt @@ -9,7 +9,7 @@ - [Concepts](https://docs.base.org/get-started/concepts.md) — Core concepts and terminology ## Quickstart -- [Build an App](https://docs.base.org/get-started/build-app.md) — End‑to‑end guide to ship your first app on Base +- [Build an App](https://docs.base.org/apps/quickstart/build-app.md) — End-to-end guide to ship your first app on Base - [Launch a Token](https://docs.base.org/get-started/launch-token.md) — Plan and launch tokens responsibly - [Deploy Smart Contracts](https://docs.base.org/get-started/deploy-smart-contracts.md) — Contracts on Base (testnet/mainnet) - [Learning Resources](https://docs.base.org/get-started/learning-resources.md) — Tutorials, courses, and guides @@ -21,6 +21,7 @@ - [Country Leads & Ambassadors](https://docs.base.org/get-started/country-leads-and-ambassadors.md) — Community contacts ## Build with AI +- [Resources for AI Agents](https://docs.base.org/get-started/resources-for-ai-agents.md) — Docs indexes, MCP access, skills, and recommended starting points for AI agents - [Docs LLMs](https://docs.base.org/get-started/docs-llms.md) — How to use these docs with AI tools - [Docs MCP](https://docs.base.org/get-started/docs-mcp.md) — Model Context Protocol integration - [Prompt Library](https://docs.base.org/get-started/prompt-library.md) — Ready‑to‑use prompts diff --git a/docs/get-started/mistakes.md b/docs/get-started/mistakes.md deleted file mode 100644 index 0a37acab4..000000000 --- a/docs/get-started/mistakes.md +++ /dev/null @@ -1,429 +0,0 @@ -# mistakes - -## 2026-03-04 - -1. The guide examples used `useWriteContracts` from `wagmi/experimental`, but in current wagmi this path is unavailable. I switched to `useSendCalls` with encoded calldata for EIP-5792 batching. -2. First contract deploy attempt was only a dry run because `forge create` requires `--broadcast` to publish onchain. -3. WalletConnect requires `NEXT_PUBLIC_WC_PROJECT_ID`. If this is missing in Vercel environment variables, WalletConnect flow will fail. -4. Next.js warned about multiple lockfiles in parent folders (`/Users/canton/git/package-lock.json` and local lockfile), which may affect inferred workspace root in local builds. -5. Docs gap: the guide does not explicitly pin `chainId` on `useReadContract`/write calls. With multiple configured chains and a contract deployed only on Base Sepolia, disconnected users can default to Base mainnet and see `Failed to read contract`. Fix is to set `chainId: baseSepolia.id` for reads/writes (or gate reads by selected chain). -6. Docs gap: chain switching should be documented as part of the core flow (not only in "Next steps"). When multiple chains are configured, the guide should include `useSwitchChain` gating before writes and clear UX copy for "Switch to Base Sepolia" to prevent silent transaction failures. -7. Docs gap: write UX should include an explicit wrong-network state and actionable button before calling `writeContract`/`sendCalls`. Implemented fix in this app: disable write buttons on wrong chain and show `Switch to Base Sepolia`. -8. Docs gap: batching example uses `useWriteContracts` from `wagmi/experimental`, which is not available in current wagmi versions used here. Implemented fix in this app: use `useSendCalls` with encoded calldata for EIP-5792 batches. - -# Build Mistakes & Lessons Learned - -Each entry records: origin, symptom, cause, the exact code fix applied, and a recommendation -for the docs. Entries are in the order they were encountered during the build. - ---- - -## 1. `wagmi/experimental` subpath removed in wagmi v3 - -**Origin: Docs error — stale API** - -The guide instructs: -```ts -import { useWriteContracts } from 'wagmi/experimental' -``` -`wagmi/experimental` no longer exists as a subpath export in wagmi v3. The `useWriteContracts` -hook was replaced by `useSendCalls` in the main `'wagmi'` package. - -**Symptom:** Hard build error at compile time. -``` -Package subpath './experimental' is not defined by "exports" -``` - -**Fix applied (`src/components/BatchIncrement.tsx`):** -- Replaced `import { useWriteContracts } from 'wagmi/experimental'` with - `import { useSendCalls, useWaitForCallsStatus } from 'wagmi'` -- Calls are passed as `{ to, data }` objects using viem's `encodeFunctionData` rather than - `{ address, abi, functionName }` tuples -- Replaced `useWaitForTransactionReceipt` in the batch flow with `useWaitForCallsStatus` - -**Docs recommendation:** Update all batch code examples from `useWriteContracts` to -`useSendCalls` to reflect the wagmi v3 API. - ---- - -## 2. `useSendCalls` data is an object, not a plain string - -**Origin: Docs error — stale API shape** - -The guide implies the call ID returned from the batch hook can be passed directly to the -status hook. In wagmi v3, `useSendCalls` returns `data: { id: string, capabilities?: ... }`. -Passing `data` directly to `useWaitForCallsStatus({ id })` causes a TypeScript error: -``` -Type '{ capabilities?: ...; id: string; } | undefined' is not assignable to type 'string | undefined' -``` - -**Fix applied (`src/components/BatchIncrement.tsx`):** -```ts -// Before -const { data: callsId, ... } = useSendCalls() -useWaitForCallsStatus({ id: callsId }) - -// After -const { data, ... } = useSendCalls() -useWaitForCallsStatus({ id: data?.id }) -``` - -**Docs recommendation:** Show the correct shape for `useSendCalls` return data and demonstrate -the `.id` extraction. - ---- - -## 3. WalletConnect connector crashes when project ID is not set - -**Origin: Docs gap — missing prerequisite and unsafe non-null assertion** - -The guide shows: -```ts -walletConnect({ - projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID!, -}) -``` -The non-null assertion (`!`) tells TypeScript to ignore the possibility of `undefined`, but -at runtime, if `NEXT_PUBLIC_WC_PROJECT_ID` is not set, wagmi initialises WalletConnect with -an empty project ID and throws. Most developers following the guide will not have a -WalletConnect project ID ready at the start of the tutorial. - -**Symptom:** App crashes on load with a WalletConnect initialisation error when the -environment variable is absent. - -**Fix applied (`src/config/wagmi.ts`):** -```ts -// Before -walletConnect({ projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID! }) - -// After — only include the connector when the project ID is actually set -...(process.env.NEXT_PUBLIC_WC_PROJECT_ID - ? [walletConnect({ projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID })] - : []) -``` - -**Docs recommendation:** Add a note that a WalletConnect Cloud project ID is required before -the wagmi config step, with a link to https://cloud.walletconnect.com. Replace the `!` -assertion with a conditional connector so the app works without WalletConnect during -development. - ---- - -## 4. Foundry not pre-installed - -**Origin: Environment — missing prerequisite** - -`forge` was not present. The guide proceeds directly to `forge init` with no prerequisite -check. - -**Fix applied:** -```bash -curl -L https://foundry.paradigm.xyz | bash -source ~/.zshenv -foundryup -``` - -**Docs recommendation:** Add a prerequisites section with `forge --version` as a check before -the contract deployment step. - ---- - -## 5. Next.js workspace root warning - -**Origin: Environment — non-fatal** - -Next.js 16 + Turbopack detected multiple `package-lock.json` files and warned about the -inferred workspace root. Does not affect the build. - -**Fix applied:** No code change required. - -**Docs recommendation:** Note that projects inside a monorepo may see this warning and that -`turbopack.root` in `next.config.ts` silences it. - ---- - -## 6. `cast wallet import --interactive` requires a TTY - -**Origin: Docs gap — environment assumption** - -`cast wallet import deployer --interactive` requires an interactive terminal and cannot run -in scripted or piped environments. - -**Fix applied (deployment only):** Used `cast wallet new` to generate a throwaway key and -passed it via `--private-key`. **Never use this with real funds.** - -**Docs recommendation:** Note the TTY requirement and show a `--private-key $DEPLOYER_KEY` -alternative for non-interactive environments. - ---- - -## 7. Official Base Sepolia RPC URL unreachable - -**Origin: Docs error — broken default RPC** - -The guide uses `https://sepolia.base.org`. This returned "Connection reset by peer" -consistently during the build and deployment steps. - -**Fix applied (`src/config/wagmi.ts`):** -```ts -// Before -[baseSepolia.id]: http() - -// After -[baseSepolia.id]: http('https://base-sepolia-rpc.publicnode.com') -``` - -**Docs recommendation:** Replace `https://sepolia.base.org` with a verified working public -endpoint, or list at least one fallback option. - ---- - -## 8. Wrong default chain — all reads and writes target Base mainnet - -**Origin: Docs gap caught late by agent (shared blame)** - -The guide shows `chains: [base, baseSepolia]` with `base` first, deploys the contract to -`baseSepolia`, but never instructs you to specify `chainId` in hook calls. wagmi defaults -every unqualified call to the first chain in the array (`base` = mainnet), where the contract -does not exist. - -**Symptom:** "Failed to read contract" on every page load. Write calls silently fail. - -**Fix applied:** -- `src/components/CounterDisplay.tsx` — added `chainId: baseSepolia.id` to `useReadContract` -- `src/components/IncrementButton.tsx` — added `chainId: baseSepolia.id` to `writeContract` -- `src/components/BatchIncrement.tsx` — added `chainId: baseSepolia.id` to `writeContract` - and `sendCalls` - -**Docs recommendation:** Either list `baseSepolia` first in the chains array, or include -`chainId` explicitly in every hook example. Add a callout explaining that the first chain in -the array is the default for all calls that do not specify one. - ---- - -## 9. Wrong chain used for EIP-5792 capability check - -**Origin: Docs error — misleading hook usage** - -The guide shows: -```ts -const chainId = useChainId() -const supportsBatching = useMemo(() => { - const atomic = capabilities?.[chainId]?.atomic // chainId = wallet's CURRENT chain - ... -}, [capabilities, chainId]) -``` - -`useChainId()` returns the wallet's current chain. MetaMask reports partial EIP-5792 support -for Ethereum mainnet, so a MetaMask user on mainnet gets `supportsBatching = true` and sees -the EIP-5792 batch UI instead of the correct EOA single-transaction flow. - -**Symptom:** MetaMask users see "Smart wallet detected — using EIP-5792 batch" and the -purple batch button instead of the green increment button. - -**Fix applied (`src/hooks/useWalletCapabilities.ts`):** -```ts -// Before -import { useCapabilities, useChainId } from 'wagmi' -const chainId = useChainId() -const atomic = capabilities?.[chainId]?.atomic - -// After — always check against the app's target chain -import { useCapabilities } from 'wagmi' -import { baseSepolia } from 'wagmi/chains' -const atomic = capabilities?.[baseSepolia.id]?.atomic -``` -`useChainId` import also removed since it is no longer used. - -**Docs recommendation:** Replace `useChainId()` with the app's hardcoded target chain ID, -and add a note that `useChainId()` reflects the wallet's current chain, not your deployment -chain. - ---- - -## 10. Write buttons freeze silently when wallet is on the wrong chain - -**Origin: Docs gap — critical UX step deferred to "Next steps"** - -The guide builds write buttons with no chain-switching mechanism and lists `useSwitchChain` -only in the "Next steps" section as optional polish. Without it, calling -`writeContract({ chainId: baseSepolia.id })` while connected to mainnet causes wagmi to -attempt a background chain switch. If MetaMask's popup is missed or dismissed, the button -stays at `isPending: true` with no error, no timeout, and no recovery path. - -**Symptom:** Increment button shows "Confirm in Wallet..." and never changes. Nothing happens -on click. - -**Fix applied:** -- `src/components/IncrementButton.tsx` — added `useChainId()` check; renders a - "Switch to Base Sepolia" button via `useSwitchChain` when `chainId !== baseSepolia.id` -- `src/components/BatchIncrement.tsx` — same check added to both `BatchFlow` and - `SequentialFlow` via a shared `ChainSwitchButton` component - -```ts -const chainId = useChainId() -const { switchChain, isPending: isSwitching } = useSwitchChain() - -if (chainId !== baseSepolia.id) { - return ( - - ) -} -``` - -**Docs recommendation:** Move chain switching from "Next steps" into the core `IncrementButton` -step. Add a warning that omitting `useSwitchChain` causes silent freezes for any user not -already on the target network. - ---- - -## 11. `useReadContract` fails after wallet connect — injected provider overrides HTTP transport - -**Origin: Docs gap — wagmi account-awareness and provider preference not explained** - -**Console signal:** `Unchecked runtime.lastError: Could not establish connection. Receiving end does not exist.` - -This Chrome error means MetaMask's MV3 background service worker has been killed by the -browser. When dead, every call through `window.ethereum` fails silently. - -wagmi's `useReadContract` includes the connected account in its TanStack Query key. When -MetaMask connects, the key changes and a fresh fetch is triggered. wagmi v3 prefers the -injected provider for chains it detects as available, so this new fetch goes through -`window.ethereum` (dead) instead of the configured HTTP transport. The fetch fails, -`data` is `undefined` (new key, no cache), and "Failed to read contract" is shown. - -The same dead service worker also causes `useSwitchChain` and `writeContract` to fail with -no visible error — buttons appear completely frozen. - -**Symptom:** Counter shows correctly before wallet connect, then immediately shows -"Failed to read contract" after connecting. Clicking any transaction or chain-switch button -does nothing. - -**Fix applied:** - -*For reads (`src/components/CounterDisplay.tsx`):* -Replaced `useReadContract` entirely with `usePublicClient` + `useQuery`: -```ts -// Before — account-aware, uses injected provider after wallet connects -const { data: count, isError } = useReadContract({ - address: COUNTER_ADDRESS, - abi: counterAbi, - functionName: 'number', - chainId: baseSepolia.id, -}) - -// After — HTTP transport only, stable query key never affected by wallet state -const publicClient = usePublicClient({ chainId: baseSepolia.id }) -const { data: count, isError, error } = useQuery({ - queryKey: ['counter', COUNTER_ADDRESS, baseSepolia.id], - queryFn: () => publicClient!.readContract({ - address: COUNTER_ADDRESS, - abi: counterAbi, - functionName: 'number', - }), - enabled: !!publicClient, - refetchInterval: 5_000, -}) -``` - -`usePublicClient({ chainId: baseSepolia.id })` returns the client built from the configured -`http('https://base-sepolia-rpc.publicnode.com')` transport — no injected provider involved. -The query key contains no account, so connecting a wallet never invalidates or refetches it. - -*For write/switch errors (`src/components/IncrementButton.tsx`, `BatchIncrement.tsx`):* -Exposed the `error` field from `useSwitchChain`, `useWriteContract`, and `useSendCalls` and -rendered it with MetaMask-aware messaging: -```ts -const { switchChain, error: switchError } = useSwitchChain() -const { writeContract, error: writeError } = useWriteContract() - -{switchError && ( -

- {switchError.message.includes('Receiving end') - ? 'MetaMask is not responding. Reload the extension or refresh the page.' - : switchError.message} -

-)} -``` - -**Docs recommendation:** -- In the "Read contract data" step, warn that `useReadContract` uses the injected provider - for refetches after wallet connection. Recommend `usePublicClient` + `useQuery` for reads - that must remain transport-stable across wallet state changes. -- In all write examples, show the `error` field being rendered. Silent mutation failures - leave users with no actionable information. - ---- - -## 12. `if (isError)` wipes cached counter value on any refetch failure - -**Origin: Docs error — incorrect TanStack Query error pattern** - -**Note:** This was an intermediate fix that was subsequently superseded by the full -`usePublicClient + useQuery` rewrite in entry 11. Documented here because it represents -a general TanStack Query pitfall that applies beyond this guide. - -The guide shows: -```tsx -if (isLoading) return

Loading...

-if (isError) return

Failed to read contract

// ← unconditional - -return

{count?.toString()}

-``` - -When a wallet connects, wagmi refetches. If that refetch errors, `isError` is `true` but -`data` still holds the last good value in the query cache. The docs pattern discards that -cached value and replaces the UI with an error message. - -**Symptom:** Counter value disappears and is replaced with "Failed to read contract" -immediately after wallet connection, even though the value was readable moments before. - -**Intermediate fix applied (later superseded by entry 11):** -```tsx -if (isLoading && count === undefined) return

Loading...

-if (isError && count === undefined) return

Failed to read contract

-return

{count.toString()}

-``` - -**Docs recommendation:** Gate all error renders on `data === undefined`. Add a note that -`isError` can be `true` while `data` is still populated with stale cache — stale data should -always be preferred over an error message. - ---- - -## 13. Trailing space in Vercel environment variable causes invalid address error - -**Origin: Agent error — unsafe env var injection method** - -When setting the contract address on Vercel using `vercel env add` with a shell heredoc -(`<<<`), the shell appended a trailing newline which Vercel stored as a trailing space: -``` -NEXT_PUBLIC_COUNTER_ADDRESS=0xe54182C63622A76Ab0C9Ac314601CD8A46AB4c2c ← trailing space -``` - -viem validates addresses strictly and rejects any value that is not exactly 40 hex -characters: -``` -Address "0xe54182C63622A76Ab0C9Ac314601CD8A46AB4c2c " is invalid. -- Address must be a hex value of 20 bytes (40 hex characters). -``` - -**Symptom:** "Failed to read contract" on page load and an address validation error on every -write, even though the address itself is correct. - -**Fix applied:** -1. Removed and re-added the Vercel env var using `printf` to prevent the trailing newline: - ```bash - printf '0xe54182C63622A76Ab0C9Ac314601CD8A46AB4c2c' | vercel env add NEXT_PUBLIC_COUNTER_ADDRESS production - ``` -2. Added `.trim()` to `src/config/counter.ts` as a permanent safety net: - ```ts - export const COUNTER_ADDRESS = ( - process.env.NEXT_PUBLIC_COUNTER_ADDRESS || '0xe54182C63622A76Ab0C9Ac314601CD8A46AB4c2c' - ).trim() as `0x${string}` - ``` - -**Docs recommendation:** When showing `vercel env add`, use `printf` rather than `echo` or -heredoc. Note that `echo` and `<<<` both append a newline that gets stored in the value. \ No newline at end of file diff --git a/docs/get-started/resources-for-ai-agents.mdx b/docs/get-started/resources-for-ai-agents.mdx index d071a9035..922b2ace0 100644 --- a/docs/get-started/resources-for-ai-agents.mdx +++ b/docs/get-started/resources-for-ai-agents.mdx @@ -80,7 +80,7 @@ Once your agent has docs context, point it at the section that matches what you' | Verifying identity between agents and services | [Agent registration & identity](/ai-agents/setup/agent-registration) | | Using AI tools with Base Account | [Base Account quickstart for AI tools](/base-account/quickstart/ai-tools-available-for-devs) | | Deploying contracts | [Deploy on Base](/base-chain/quickstart/deploy-on-base) | -| Building an app on Base | [Build a Base app](/get-started/build-app) | +| Building an app on Base | [Build a Base app](/apps/quickstart/build-app) | ## Example prompts diff --git a/docs/llms-full.txt b/docs/llms-full.txt index 177cb2354..1177d3889 100644 --- a/docs/llms-full.txt +++ b/docs/llms-full.txt @@ -75,9 +75,10 @@ const client = createPublicClient({ chain: base, transport: http() }) ## Directory of per-product full shards +- Get Started — `./get-started/llms-full.txt` +- Base Chain — `./base-chain/llms-full.txt` - Base Account — `./base-account/llms-full.txt` - AI Agents — `./ai-agents/llms-full.txt` -- Base Chain — `./base-chain/llms-full.txt` - Apps — `./apps/llms-full.txt` ## Related indexes diff --git a/docs/llms.txt b/docs/llms.txt index fef5ee98b..486790237 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -8,7 +8,7 @@ - [Base Chain](./base-chain/llms.txt) — Deploy/connect, network info, tools, node ops, security - [Base Account](./base-account/llms.txt) — Passkey smart wallet, payments, social verification, spend permissions, sponsored gas, sub‑accounts - [AI Agents](./ai-agents/llms.txt) — Build onchain AI agents: wallets, payments, identity, trading, and installable skills -- [Apps](./apps/llms.txt) — Migrate to standard web apps on Base, register on Base.dev, earn rewards +- [Apps](./apps/llms.txt) — Build apps on Base, migrate to standard web apps, register on Base.dev, earn rewards ## Tools available for AI assistants @@ -39,7 +39,7 @@ Narrow context to a specific type of work: - [Agent Registration](https://docs.base.org/ai-agents/setup/agent-registration) — Verification and trust between agents and services - [Base Account quickstart for AI tools](https://docs.base.org/base-account/quickstart/ai-tools-available-for-devs) — Agent-assisted wallet and account flows - [Deploy on Base](https://docs.base.org/base-chain/quickstart/deploy-on-base) — Contract deployment on Base -- [Build a Base app](https://docs.base.org/get-started/build-app) +- [Build a Base app](https://docs.base.org/apps/quickstart/build-app) ### Docs index @@ -51,18 +51,21 @@ IMPORTANT: Prefer retrieval-led reasoning. Read relevant docs before generating Base is an Ethereum L2 by Coinbase. Docs for: Base Chain, Smart Wallet, OnchainKit, MiniKit. [Docs]|root:./docs |ai-agents:index +|ai-agents/payments:accepting-payments,pay-for-services-with-x402 |ai-agents/quickstart:payments,trading -|ai-agents/setup:wallet-setup,agent-builder-codes,agent-registration -|ai-agents/payments:pay-for-services-with-x402,accepting-payments -|ai-agents/trading:data-fetching,trade-execution +|ai-agents/setup:agent-builder-codes,agent-registration,wallet-setup |ai-agents/skills:index -|ai-agents/skills/wallets:bankr,cdp-agentic-wallet,sponge-wallet |ai-agents/skills/payments:cdp-payment-skills,sponge-x402 -|ai-agents/skills/trading:coingecko,alchemy-agentic-gateway,swap-execution -|ai-agents/skills/base-account:building-with-base-account -|ai-agents/skills/base-chain:adding-builder-codes,connecting-to-base-network,deploying-contracts,running-a-base-node -|ai-agents/skills/migrations:convert-farcaster-miniapp-to-app,converting-minikit-to-farcaster,migrating-an-onchainkit-app -|base-account/basenames:basename-transfer,basenames-faq,basenames-wagmi-tutorial +|ai-agents/skills/trading:alchemy-agentic-gateway,coingecko,swap-execution +|ai-agents/skills/wallets:bankr,cdp-agentic-wallet,sponge-wallet +|ai-agents/trading:data-fetching,trade-execution +|apps/builder-codes:agent-developers,app-developers,builder-codes,wallet-developers +|apps/growth:rewards +|apps/guides:migrate-to-standard-web-app +|apps/quickstart:build-app +|apps/resources:design-resources,templates +|apps/technical-guides:base-notifications +|base-account/basenames:basename-transfer,basenames-faq |base-account/contribute:contribute-to-base-account-docs,security-and-bug-bounty |base-account/framework-integrations:cdp,rainbowkit,reown,thirdweb |base-account/framework-integrations/privy:authentication,setup,spend-permissions,sub-accounts,wallet-actions @@ -87,10 +90,9 @@ Base is an Ethereum L2 by Coinbase. Docs for: Base Chain, Smart Wallet, OnchainK |base-chain/api-reference/debug-api:debug_traceBlockByHash,debug_traceBlockByNumber,debug_traceTransaction |base-chain/api-reference/ethereum-json-rpc-api:eth_blockNumber,eth_call,eth_chainId,eth_estimateGas,eth_feeHistory,eth_gasPrice,eth_getBalance,eth_getBlockByHash,eth_getBlockByNumber,eth_getBlockReceipts,eth_getBlockTransactionCountByHash,eth_getBlockTransactionCountByNumber,eth_getCode,eth_getLogs,eth_getStorageAt,eth_getTransactionByBlockHashAndIndex,eth_getTransactionByBlockNumberAndIndex,eth_getTransactionByHash,eth_getTransactionCount,eth_getTransactionReceipt,eth_maxPriorityFeePerGas,eth_sendRawTransaction,eth_subscribe,eth_syncing,eth_unsubscribe,net_version,web3_clientVersion |base-chain/api-reference/flashblocks-api:base_transactionStatus,eth_simulateV1,flashblocks-api-overview,newFlashblockTransactions,newFlashblocks,pendingLogs -|apps/builder-codes:agent-developers,app-developers,builder-codes,wallet-developers |base-chain/flashblocks:app-integration,architecture,faq,overview |base-chain/network-information:base-contracts,block-building,bridges,configuration-changelog,diffs-ethereum-base,ecosystem-contracts,network-faucets,network-fees,transaction-finality,troubleshooting-transactions -|base-chain/node-operators:node-providers,performance-tuning,run-a-base-node,snapshots,troubleshooting +|base-chain/node-operators:base-v1-upgrade,node-providers,performance-tuning,run-a-base-node,snapshots,troubleshooting |base-chain/quickstart:base-solana-bridge,connecting-to-base,deploy-on-base,why-base |base-chain/security:avoid-malicious-flags,bug-bounty,report-vulnerability,security-council ||base-chain/specs:index @@ -117,7 +119,7 @@ Base is an Ethereum L2 by Coinbase. Docs for: Base Chain, Smart Wallet, OnchainK |apps/quickstart:migrate-to-standard-web-app |apps/growth:rewards |onchainkit:migrate-from-onchainkit -|root:agents,cookie-policy,privacy-policy,terms-of-service,tone_of_voice +|root:agents,changes,cookie-policy,privacy-policy,terms-of-service,tone_of_voice ```