diff --git a/apps/base-docs/assets/images/onchainkit-tutorials/swapped-theme-before.png b/apps/base-docs/assets/images/onchainkit-tutorials/swapped-theme-before.png new file mode 100644 index 0000000000..39599d6680 Binary files /dev/null and b/apps/base-docs/assets/images/onchainkit-tutorials/swapped-theme-before.png differ diff --git a/apps/base-docs/assets/images/onchainkit-tutorials/swapped-theme-final.png b/apps/base-docs/assets/images/onchainkit-tutorials/swapped-theme-final.png new file mode 100644 index 0000000000..e38455e417 Binary files /dev/null and b/apps/base-docs/assets/images/onchainkit-tutorials/swapped-theme-final.png differ diff --git a/apps/base-docs/assets/images/paymaster-tutorials/connect-wallet-mint-page.png b/apps/base-docs/assets/images/paymaster-tutorials/connect-wallet-mint-page.png new file mode 100644 index 0000000000..f2d43727d5 Binary files /dev/null and b/apps/base-docs/assets/images/paymaster-tutorials/connect-wallet-mint-page.png differ diff --git a/apps/base-docs/assets/images/paymaster-tutorials/sponsored_mint_nft.png b/apps/base-docs/assets/images/paymaster-tutorials/sponsored_mint_nft.png new file mode 100644 index 0000000000..e678f5d7db Binary files /dev/null and b/apps/base-docs/assets/images/paymaster-tutorials/sponsored_mint_nft.png differ diff --git a/apps/base-docs/assets/images/paymaster-tutorials/wallet-home.png b/apps/base-docs/assets/images/paymaster-tutorials/wallet-home.png new file mode 100644 index 0000000000..8edda0d142 Binary files /dev/null and b/apps/base-docs/assets/images/paymaster-tutorials/wallet-home.png differ diff --git a/apps/base-docs/assets/images/paymaster-tutorials/wallet-nft-page.png b/apps/base-docs/assets/images/paymaster-tutorials/wallet-nft-page.png new file mode 100644 index 0000000000..1e05dfc452 Binary files /dev/null and b/apps/base-docs/assets/images/paymaster-tutorials/wallet-nft-page.png differ diff --git a/apps/base-docs/tutorials/docs/1_ock-swap-theme.md b/apps/base-docs/tutorials/docs/1_ock-swap-theme.md new file mode 100644 index 0000000000..a6b77f6078 --- /dev/null +++ b/apps/base-docs/tutorials/docs/1_ock-swap-theme.md @@ -0,0 +1,196 @@ +--- +title: 'Create a Custom Themed Swap Component with OnchainKit' +slug: /create-custom-themed-swap-component +description: Learn how to implement a swap component with a custom theme using OnchainKit in your React application. +author: hughescoin +keywords: [OnchainKit, Swap Component, Custom Theme, React, TypeScript, ERC20 Tokens, Base Chain] +tags: ['frontend', 'defi', 'ethereum', 'base'] +difficulty: medium +displayed_sidebar: null +--- + +In this tutorial, you'll learn how to create a swap component with a custom theme using OnchainKit. We'll start with the OnchainKit App Template and modify it to include a swap interface for ERC20 tokens on Base. + +--- + +## Objectives + +By the end of this tutorial, you will be able to: + +- Set up a project using the OnchainKit App Template +- Implement a swap component for ERC20 tokens +- Customize the theme of your OnchainKit components +- Apply CSS overrides to fine-tune the appearance of your app + +## Prerequisites + +### React and TypeScript + +You should be familiar with React and TypeScript. If you're new to these technologies, consider reviewing their [official documentation](https://react.dev/) first. + +### OnchainKit + +This tutorial uses [OnchainKit]. Familiarity with its basic concepts will be helpful. + +--- + +## Setting up the Project + +To get started, clone the OnchainKit App Template by running: + +```bash +git clone git@github.com:coinbase/onchain-app-template.git +``` + +If you have an existing app that uses OnchainKit, update to the latest version: + +```bash +bun update @coinbase/onchainkit --latest +``` + +Now let's implement the Swap component by importing it from OnchainKit. Import it into a new route of your app or, if you're following along, the `src/app/page.tsx` file: + +```ts +import { + Swap, + SwapAmountInput, + SwapToggleButton, + SwapButton, + SwapMessage, + SwapToast, +} from '@coinbase/onchainkit/swap'; + +import type { Token } from 'node_modules/@coinbase/onchainkit/esm/token/types'; +``` + +The `` component enables you to swap any ERC20 token on Base. For this example, your users will be able to swap between USDC and ETH. Next, using the `Token` type, create instances of ETH and USDC. + +```ts +const ETHToken: Token = { + address: '', + chainId: 8453, + decimals: 18, + name: 'Ethereum', + symbol: 'ETH', + image: + 'https://dynamic-assets.coinbase.com/dbb4b4983bde81309ddab83eb598358eb44375b930b94687ebe38bc22e52c3b2125258ffb8477a5ef22e33d6bd72e32a506c391caa13af64c00e46613c3e5806/asset_icons/4113b082d21cc5fab17fc8f2d19fb996165bcce635e6900f7fc2d57c4ef33ae9.png', +}; + +const USDCToken: Token = { + address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', + chainId: 8453, + decimals: 6, + name: 'USDC', + symbol: 'USDC', + image: + 'https://dynamic-assets.coinbase.com/3c15df5e2ac7d4abbe9499ed9335041f00c620f28e8de2f93474a9f432058742cdf4674bd43f309e69778a26969372310135be97eb183d91c492154176d455b8/asset_icons/9d67b728b6c8f457717154b3a35f9ddc702eae7e76c4684ee39302c4d7fd0bb8.png', +}; +``` + +![swap-component-default](../../assets/images/onchainkit-tutorials/swapped-theme-before.png) + +Here's a [sample](https://gist.github.com/hughescoin/4558feabb4f40b51f800091f04a945ae) of the full `page.tsx` file for reference. + +## Changing the Theme + +To change the theme of the site, navigate to `src/components/OnchainProviders.tsx` and add a `config` object to the `OnchainKitProvider`. This is the first step in enabling Themes for your project. + +```js +config={{ + appearance: { + mode: 'auto', // 'auto' | 'light' | 'dark' + theme: 'default', // 'default' | 'base' | 'cyberpunk' | 'hacker' + }, +}} +``` + +OnchainKit provides you with four preset themes. We'll use the "hacker" theme for its fonts but change the colors to a different palette. + +If you need help coming up with a color palette, there are many online tools available. For example, I used [color magic](https://colormagic.app). + +## Customizing the CSS + +Once you've chosen your colors, add them to the CSS file. Update the `src/app/global.css` file to include CSS overrides for OnchainKit properties. In the sample below, the comments provide guidance on which properties will change color. + +:::tip Having trouble changing an element? + +Use the "Inspect" feature in your browser to identify the element you wish to override in your `global.css` file. + +::: + +```css +@layer base { + :root, + .default-light, + .default-dark, + .base, + .cyberpunk, + .hacker { + /* Text colors */ + --ock-text-inverse: #f1d579; + --ock-text-foreground: #8c3e21; + --ock-text-foreground-muted: #f1d579; + --ock-text-error: #c85c2d; + --ock-text-primary: #e1a04c; + --ock-text-success: #f5b370; + --ock-text-warning: #f1d579; + --ock-text-disabled: #8c3e21; + + /* Background colors */ + --ock-bg-default: #8c3e21; + --ock-bg-default-hover: #c85c2d; + --ock-bg-default-active: #f1d579; + --ock-bg-alternate: #f1d579; + --ock-bg-alternate-hover: #e1a04c; + --ock-bg-alternate-active: #c85c2d; + --ock-bg-inverse: #c85c2d; + --ock-bg-inverse-hover: #e1a04c; + --ock-bg-inverse-active: #f5b370; + --ock-bg-primary: #c85c2d; + --ock-bg-primary-hover: #e1a04c; + --ock-bg-primary-active: #f1d579; + --ock-bg-primary-washed: #f5b370; + --ock-bg-primary-disabled: #8c3e21; + --ock-bg-secondary: #e1a04c; + --ock-bg-secondary-hover: #f1d579; + --ock-bg-secondary-active: #f5b370; + --ock-bg-error: #c85c2d; + --ock-bg-warning: #f1d579; + --ock-bg-success: #f5b370; + --ock-bg-default-reverse: #c85c2d; + + /* Icon colors */ + --ock-icon-color-primary: #c85c2d; + --ock-icon-color-foreground: #c85c2d; + --ock-icon-color-foreground-muted: #e1a04c; + --ock-icon-color-inverse: #f5b370; + --ock-icon-color-error: #c85c2d; + --ock-icon-color-success: #f5b370; + --ock-icon-color-warning: #f1d579; + + /* Line colors */ + --ock-line-primary: #c85c2d; + --ock-line-default: #8c3e21; + --ock-line-heavy: #f1d579; + --ock-line-inverse: #e1a04c; + } +} + +.ock-font-family.font-semibold.text-xl.leading-7 { + color: #f1d579; +} +``` + +Now refresh your page, and you should see your swap component change to your defined color palette! + +![swap-component](../../assets/images/onchainkit-tutorials/swapped-theme-final.png) + +If something looks off, remember to check that you've overridden the correct element. See the above tip to learn how to find the correct element. + +## Conclusion + +Congratulations! You've successfully implemented the `` component and customized it to a theme of your choice. Pretty neat, right? +[OnchainKit]: https://github.com/coinbase/onchainkit +[OnchainKit App Template]: https://github.com/coinbase/onchain-app-template +[color magic]: https://colormagic.app +[sample]: https://gist.github.com/hughescoin/4558feabb4f40b51f800091f04a945ae diff --git a/apps/base-docs/tutorials/docs/2_ock-fund-tutorial.md b/apps/base-docs/tutorials/docs/2_ock-fund-tutorial.md index 58a254b9a8..95b7814116 100644 --- a/apps/base-docs/tutorials/docs/2_ock-fund-tutorial.md +++ b/apps/base-docs/tutorials/docs/2_ock-fund-tutorial.md @@ -28,10 +28,10 @@ In this tutorial, you'll learn how to build an onchain app that checks a user's By the end of this tutorial you should be able to: -- Set up a project using the Onchain Kit App Template +- Set up a project using the [OnchainKit App Template] - Configure the app for to onboard users easily using [Smart Wallets] - Implement balance checking and conditional rendering -- Use the Fund component to allow users to add funds to their wallet +- Use the Fund component to allow users to add buy tokens from their wallet without leaving your app ## Prerequisites @@ -41,7 +41,7 @@ You should be familiar with React and TypeScript. If you're new to these technol ### OnchainKit -This tutorial uses Coinbase's Onchain Kit. Familiarity with its basic concepts will be helpful. +This tutorial uses Coinbase's OnchainKit. Familiarity with its basic concepts will be helpful. ### Access to the Coinbase Developer Platform @@ -58,7 +58,7 @@ If you see a "something went wrong" error message when navigating to pay.coinbas ## Setting up the Project -To get started, clone the Onchain Kit App Template by running +To get started, clone the OnchainKit App Template by running: ```bash git clone git@github.com:coinbase/onchain-app-template.git @@ -172,7 +172,8 @@ This app can serve as a foundation for more complex onchain applications that re --- -[Onchain Kit]: https://github.com/coinbase/onchainkit +[OnchainKit]: https://github.com/coinbase/onchainkit +[OnchainKit App Template]: https://github.com/coinbase/onchain-app-template [Viem]: https://viem.sh/ [Smart Wallets]: https://keys.coinbase.com/onboarding [viem]: https://viem.sh/docs/introduction diff --git a/apps/base-docs/tutorials/docs/2_paymaster-sponsor-using-wagi.md b/apps/base-docs/tutorials/docs/2_paymaster-sponsor-using-wagi.md new file mode 100644 index 0000000000..456b46b140 --- /dev/null +++ b/apps/base-docs/tutorials/docs/2_paymaster-sponsor-using-wagi.md @@ -0,0 +1,383 @@ +--- +title: How to Implement Base Paymaster into a Wagmi Project +slug: /implement-base-paymaster-wagmi +description: 'A tutorial to create a Mint button for free NFT minting with Base Paymaster sponsorship' +author: hughescoin +keywords: ['Base Paymaster', 'NFT', 'Wagmi', 'WalletConnect', 'Coinbase Wallet'] +tags: ['smart wallets', 'NFT minting', 'Wagmi integration'] +difficulty: beginner +displayed_sidebar: null +--- + +# How to Implement Base Paymaster into a Wagmi Project + +In this tutorial, we’ll create a **Mint** button that allows users to mint an NFT for free through transaction sponsorship from a **Base Paymaster**. This setup enables users to mint NFTs directly to their wallets without incurring gas fees. By the end, you’ll have a fully functional NFT minting setup with transaction sponsorship via the Base Paymaster. Let's build! + +## Objectives + +- **Configure Wagmi for the Base Network** + Set up your Wagmi project to seamlessly interact with the Base blockchain, allowing users to connect their wallets and initiate transactions with ease. + +- **Define Essential Constants** + Learn how to manage key information such as contract ABIs and addresses, which are crucial for interacting with smart contracts in your application. + +- **Implement Paymaster-Sponsored NFT Minting** + Update onchain actions using Wagmi's `writeContracts` and `useCalls` hooks to enable gas-free NFT minting, allowing users to mint directly to their wallets without incurring transaction fees. + +- **Enhance User Experience with Gasless Transactions** + Create a user-friendly experience by abstracting away the concept of gas fees, making it easier for users to engage with your application and mint NFTs. + +## Prerequisites + +### Wallet Connect Project ID + +You’ll need to set up a cloud account with [Reown] (FKA, WalletConnect), a protocol that enables secure wallet connections across different platforms. + +### Base Paymaster + Bundler Endpoint + +You'll need to set up an account (free) with the [Coinbase Developer Platform (CDP)](https://www.coinbase.com/cloud) to obtain a Paymaster + Bundler endpoint, which is required for this tutorial. The CDP provides these essential services that enable transaction sponsorship. + +### Smart Wallet + +Smart Wallets enables users to create an account in seconds with no app or extension required through the use of Passskey signing. This tutorial uses the [Base Wallet] (FKA Coinbase Smart Wallet) to sign and mint transactions. + +--- + +## Set Up Your Project + +### Create a New Wagmi Project + +Start by creating a new Wagmi project with Bun: + +```bash +bun create wagmi +``` + +### Add WalletConnect Project ID + +Add your WalletConnect Project ID to the .env file to enable wallet connection in the app. Open the .env file and add the following lines: + +``` +NEXT_PUBLIC_WC_PROJECT_ID= +NEXT_TELEMETRY_DISABLED=1 +``` + +Replace`` with your actual WalletConnect Project ID. + +### Update Wagmi Configuration + +### Configure Wagmi for Base Network To integrate the Base network with Wagmi, update `wagmi.ts` as follows: + +```ts +import { http, cookieStorage, createConfig, createStorage } from 'wagmi'; +import { base } from 'wagmi/chains'; +import { coinbaseWallet, injected, walletConnect } from 'wagmi/connectors'; + +export function getConfig() { + return createConfig({ + chains: [base], + connectors: [ + injected(), + coinbaseWallet(), + walletConnect({ projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID }), + ], + storage: createStorage({ + storage: cookieStorage, + }), + ssr: true, + transports: { + [base.id]: http(), + }, + }); +} + +declare module 'wagmi' { + interface Register { + config: ReturnType; + } +} +``` + +This configuration sets up your project to connect to the Base network and supports multiple connectors, including WalletConnect. + +### Create utils.ts for Contract ABI and Address + +Create a new file `utils.ts` in the `src` folder. This file will store the contract’s ABI and address. + +**`src/utils.ts`** + +```ts +// utils.js + +import { Abi } from 'viem'; + +export const contractAddress = '0x83bd615eb93ee1336aca53e185b03b54ff4a17e8' as `0x${string}`; + +export const abi = [ + { + type: 'constructor', + inputs: [ + { name: '_name', type: 'string', internalType: 'string' }, + { name: '_symbol', type: 'string', internalType: 'string' }, + ], + stateMutability: 'nonpayable', + }, + // ABI code here +] as Abi; +``` + +Replace the contract address and ABI as per your contract’s details. + +## Create the NFT Minting Page + +In this step, we’ll create a new page in our project where users can mint an NFT. The minting page will use Wagmi’s hooks, including [`useCapabilities`][useCapabilities] to check the capabilities supported by the connected wallet and [`useWriteContracts`][useWriteContracts] to execute a mint function on our smart contract. + +### Set Up `mint/page.tsx` + +In your project’s `src/app` folder, create a new file called `mint/page.tsx`. This file will contain the code to manage wallet connection, check for paymaster capabilities, and execute the minting action. + +:::info Experimenal Hooks and Capabilities + +To ensure a smooth, gas-free NFT minting experience, it’s important to understand the purpose of two key hooks from Wagmi: + +- **[`useCapabilities`][useCapabilities]:** This hook retrieves the list of capabilities (such as `paymasterService`) supported by the connected wallet, grouped by chain ID. This is crucial because we need to confirm that the connected wallet supports paymaster sponsorship, which allows transactions to be sponsored by a third party (in this case, Base Paymaster). + +- **[`useWriteContracts`][useWriteContracts]:** This hook allows us to interact with smart contracts on the blockchain. Specifically, we’ll use it to trigger the `mintTo` function, which will mint an NFT to the user’s wallet. + +By combining these hooks, we can detect whether the user’s wallet is capable of sponsored transactions and, if so, use the `writeContracts` function to mint an NFT without charging the user any gas fees. + +::: + +### Add the Code for NFT Minting + +**For Wallet Connection:** +We use useAccount, useConnect, and useDisconnect to manage wallet connection. This allows users to connect via Coinbase Smart Wallet and disconnect as needed. + +```tsx + +'use client'; +import { useAccount, useConnect, useDisconnect } from 'wagmi'; +import { useState, useMemo } from 'react'; +import { coinbaseWallet } from 'wagmi/connectors'; +import { abi, contractAddress } from '../utils'; +import { useCapabilities, useWriteContracts } from 'wagmi/experimental'; + +export default function Home() { + const { address, isConnected } = useAccount(); + const { connect } = useConnect(); + const { disconnect } = useDisconnect(); + const [isMinting, setIsMinting] = useState(false); + const [id, setId] = useState(undefined); + + // Follow along for more code ... +``` + +**Capabilities Check with `useCapabilities`:** +Using `useCapabilities`, we retrieve the wallet’s supported capabilities, grouped by chain ID. In this example, we’re checking if the wallet has the `paymasterService` capability, which indicates it can use a Base Paymaster for gas-free transactions. If paymaster service is supported, we configure the capabilities object to include the Base Paymaster URL. + +```tsx +// Retrieve wallet capabilities to check for paymaster support +const { data: availableCapabilities } = useCapabilities({ + account: address, +}); +const capabilities = useMemo(() => { + if (!availableCapabilities || !address) return {}; + const capabilitiesForChain = availableCapabilities[address.chainId]; + if ( + capabilitiesForChain['paymasterService'] && + capabilitiesForChain['paymasterService'].supported + ) { + return { + paymasterService: { + url: `https://api.developer.coinbase.com/rpc/v1/base/rcNfIncd3jL3FztkZ7TPOV_sfHUGlcVP`, + }, + }; + } + return {}; +}, [availableCapabilities, address]); +``` + +**Minting Logic with `useWriteContracts`:** +We use `useWriteContracts` to interact with the smart contract and call the mintTo function, which mints the NFT. By passing capabilities, the transaction is sponsored by the Base Paymaster, covering gas fees for the user. + +The Mint button will either prompt the user to connect their wallet (if not connected), or execute the handleMint function to mint an NFT (if connected). During the minting process, the button shows “Minting…” to indicate the ongoing transaction. + +The full `src/app/mint/page.tsx` file should look something like this: + +:::tip Smart Wallet Only + +To enable [Base Wallet] functionality add the `smartWalletOnly` prefence to the [wagmi connector] + +```jsx + + )} + + + + ); +} +``` + +This component detects if a wallet is connected, then allows users to mint an NFT. If no wallet is detected, it prompts the user to connect via the Coinbase Smart Wallet. + +### Testing + +Start your development server to test the minting functionality: + +```bash +bun run dev +``` + +Open your browser and navigate to your site’s local URL: + +```bash + +http://localhost:3000/mint +``` + +![image-of-server](../../assets/images/paymaster-tutorials/connect-wallet-mint-page.png) + +**Connect Your Wallet and Mint** +Once on the mint page, connect your wallet. You should see a Mint button appear. Upon clicking the Mint button, a smart wallet popup will prompt you to confirm the mint transaction. + +![image-of-mint-modal](../../assets/images/paymaster-tutorials/sponsored_mint_nft.png) + +## Verify Your NFT + +After minting, you can verify the NFT in your Base Wallet: + +Go to [Coinbase Wallet](https://wallet.coinbase.com/). + +Navigate to the **Assets** section and select the [**NFT** tab](https://wallet.coinbase.com/assets/nft). + +![smart-wallet-home](../../assets/images/paymaster-tutorials/wallet-home.png) + +You should see your newly minted NFT in your collection. + +![smart-wallet-assets](../../assets/images/paymaster-tutorials/wallet-nft-page.png) + +## Conclusion + +Congratulations! You’ve successfully integrated a Base Paymaster to enable gas-free NFT minting within your Wagmi project. By configuring your project with Base network support, defining contract details, and using Wagmi hooks for minting, you’ve created a user-friendly, gasless minting experience. Now your users can mint NFTs without transaction costs, enhancing both accessibility and engagement with your app. + +Happy building! + +--- + +[OnchainKit]: https://github.com/coinbase/onchainkit +[Viem]: https://viem.sh/ +[Smart Wallets]: https://keys.coinbase.com/onboarding +[viem]: https://viem.sh/docs/introduction +[react hooks]: https://react.dev/reference/react/hooks +[Onramp config page]: https://portal.cdp.coinbase.com/products/onramp +[official documentation]: https://react.dev/ +[useWriteContracts]: https://wagmi.sh/react/api/hooks/useWriteContract +[useCapabilities]: https://wagmi.sh/react/api/hooks/useCapabilities +[wagmi connector]: https://wagmi.sh/core/api/actions/connect#connect +[Base Wallet]: https://www.smartwallet.dev/