Bankr has migrated their token launcher from Clanker to Doppler Protocol, the same professional-grade infrastructure used by Zora, Paragraph, and Noice. This isn't a fork or a copy: Bankr is using the canonical Doppler contracts on Base, deployed and maintained by Whetstone Research.

This article breaks down the technical architecture, explains the liquidity mechanics, and clarifies what this means if you're trading these tokens.

Note: Bankr's initial Feb 10 deployment used ScheduledMulticurveInitializer. Within three days, they switched to DecayMulticurveInitializer with a significantly different curve structure. The article documents both setups. Skip to Current Setup if you only care about how it works now.

The Core Infrastructure

The Airlock Pattern

Doppler uses a modular "Airlock" architecture where a central orchestrator contract delegates to specialized components:

Airlock (0x660eAaEdEBc968f8f3694354FA8EC0b4c5Ba8D12)
    ├── TokenFactory80 → Deploys DERC20 tokens
    │
    ├── Pool Initializer (one of):
    │     ├─ ScheduledMulticurveInitializer (0xA36715d..., Feb 10)
    │     │    └── Hook: binary start-time gate
    │     │
    │     └─ DecayMulticurveInitializer (0xd59ce43..., Feb 13+) ← CURRENT
    │          └── Hook: 80% → 1.2% fee decay over 10s
    │
    ├── NoOpGovernanceFactory → Immutable, no admin controls
    ├── NoOpMigrator → Required param (always reverts)
    └── StreamableFeesLockerV2 → Locks positions, streams fees

Key takeaway: Once deployed, these tokens are fully immutable. No admin can change parameters, pause trading, or rug the liquidity.

Original Liquidity Design: Scheduled Multicurve (Feb 10)

Historical: This section describes Bankr's initial setup which was replaced on Feb 13. See Current Setup for the active configuration.

Bankr's initial deployment used Doppler's Uniswap V4 Scheduled Multicurve with four overlapping curve definitions subdivided into ~21 segments.

What This Means Technically

Instead of a single liquidity position or full-range V3 LP, Bankr tokens launch with:

The Four Curves (Example: BlueWhale deployment)

Total deployed: ~4.55 ETH across 21 positions

Market Cap Depth Map (WETH @ ~$2,700)

Critical Trading Implications

1. Designed for Volatility, Not Stability

The liquidity structure is optimized for fast, violent price action in a narrow mcap band:

• Entire concentrated range: \(27K → \)205K (7.5x price journey)

• Beyond $205K: Near-zero liquidity, price can moon or crater on minimal volume

• All segments activate at once: The "scheduled" hook is a binary gate (blocked → fully live), not gradual activation

Bottom line: These tokens are engineered for micro-cap speculation, not gradual price discovery.

2. No External Liquidity

The Doppler hook blocks all third-party liquidity additions. What you see at launch is what you get:

• No retail LPs can add depth to stabilize price

• No whale can come in and provide "support"

• The curve structure is immutable, no adjustments possible

3. Locked but Not Burned

Liquidity positions are locked in the UniswapV4MulticurveInitializer, not burned. This means:

• Fees stream to beneficiaries forever.

• Migration is effectively disabled (NoOpMigrator always reverts)

• The initializer holds the liquidity position, but the fees are distributed to beneficiaries configured by the user, plus 5% for Doppler.

The "Scheduled" Hook Explained (Feb 10)

Historical: Bankr now uses DecayMulticurveInitializerHook instead. See Current Setup.

Despite the name, "Scheduled" doesn't mean gradual liquidity activation:

1. At creation, a startingTime timestamp is set

2. Before that time: all swaps revert with CannotSwapBeforeStartingTime()

3. After that time: all 21 segments are immediately tradeable

There's no phased rollout, no time-based dampening. It's a binary switch from "no trading" to "full volatility."

DERC20: The Token Standard

Doppler tokens are DERC20, an extended ERC20 with additional built-in functionality.

contract DERC20 is ERC20, ERC20Votes, ERC20Permit, Ownable {
    uint256 public immutable vestingStart;
    uint256 public immutable vestingDuration;
    uint256 public immutable vestedTotalAmount;
    address public pool;
    bool public isPoolUnlocked;
    uint256 public yearlyMintRate; // Max 2%
    string public tokenURI;
}

Built-in features:

• Vesting: Up to 80% of supply can be time-locked

• Governance: ERC20Votes for DAO functionality (though irrelevant for Bankr)

• Inflation controls: Max 2% yearly mint rate

• Permit2: Gasless approvals.

• Pool locking: Liquidity locked until conditions met (in our case, forever)

Current Setup (Feb 13): DecayMulticurveInitializer

Bankr switched to a newer Doppler contract within three days of launch. The following reflects the current active configuration.

Current Contracts

Source: DecayMulticurveInitializer.sol / DecayMulticurveInitializerHook.sol

What Changed: Decaying Fee Instead of Start-Time Gate

The old "Scheduled" hook blocked all swaps until startingTime, then opened the floodgates. The new "Decay" hook takes a different approach: swaps are always allowed, but the fee starts extremely high and linearly decays to the terminal rate.

The hook struct (from source, single storage slot):

struct FeeSchedule {
    uint32 startingTime;
    uint24 startFee;    // Fee at start
    uint24 endFee;      // Terminal fee
    uint24 lastFee;     // Last applied (monotonically decreasing)
    uint32 durationSeconds;
}

Flow Caster deployment values (verified on-chain):

The fee decays linearly: currentFee = startFee - (startFee - endFee) * elapsed / durationSeconds. At second 0 it's 80%, at second 5 it's ~41%, at second 10 it locks at 1.2%.

This is an anti-snipe mechanism. Bots that buy in the first seconds get taxed at up to 80%. Wait 10 seconds and you pay a normal 1.2%.

Current Curve Structure

The Feb 10 setup used 4 overlapping curves with ~21 segments in a narrow \(27K–\)205K range. The current setup is much simpler:

The concentrated range now extends to \(1.66B, roughly 60x wider than the previous \)205K ceiling. No overlapping curves, no stacked "speed bump" zones. One large position holds 99% of supply.

Revised Comparison

The tick ranges are nearly identical, both platforms now target the same ~\(27K → ~\)1.66B market cap corridor.

Current Trading Implications

• The "cliff edge at \(205K" no longer applies to new Bankr deployments, the concentrated range now extends to ~\)1.66B

• Anti-snipe via fee decay is aggressive: buying in the first 10 seconds costs up to 80%

• The safety-net tail (1% of supply beyond $1.66B) means there's some liquidity above the concentrated range. Clanker allows adding liquidity on arbitrary ranges after token deployment.

Summary

Bankr's migration to Doppler represents a shift in infrastructure philosophy.

Both Clanker and Doppler are professional-grade systems, Clanker is backed by Farcaster/Neynar, has processed billions in volume, and its v4 now offers similar features including custom curves (up to 7 positions), dynamic fees, and MEV protection.

The key differences are economic: Clanker protocol fees are significantly higher than Doppler's. Doppler also offers richer token primitives (DERC20 with built-in governance, vesting, and inflation controls) and more granular curve design flexibility through its multicurve architecture.

The current setup concentrates 99% of liquidity in a ~\(27K–\)1.66B range with a 1% safety net above. Combined with aggressive anti-snipe fees (80% decaying to 1.2% over 10 seconds) and no external LP access, the design prioritizes fee capture from active trading while providing reasonable depth acraoss a wide mcap range.

Trade accordingly.

References

• Doppler App: https://app.doppler.lol/

• Doppler Docs: https://docs.doppler.lol/

• Doppler GitHub: https://github.com/whetstoneresearch/doppler

• Bankr Announcement: https://x.com/i/status/2021103152246775936

Note: This article has been updated from the original version to reflect the breaking changes and new patterns introduced in wagmi v3. The core concepts remain the same, but the API syntax has been modernized to align with TanStack Query conventions and improve type safety.

If you have ever done Web3 frontend, then you must have heard about or used the wagmi library. Wagmi allows devs to make all kind of blockchain interactions on the frontend in a manner that feels very native to React, with a set of 40+ React hooks. From getting info about the connected wallet to smart contract interaction passing through fetching blockchain state data.

As you know, I'm a big fan of the 80/20 rule. For me that means that even if most of the functionality that wagmi has to offer is interesting, you will probably use around 20 percent of it on a regular basis. That leaves us with...8 hooks?

I'm not going to cajole this series of articles to fit that number but the plan is to talk about what I use most frequently at work. I'm also going to focus on doubts and questions that frequently come up so you can speed run your smart contract interaction tasks.

Talking about frequently asked questions, another of the reasons for this article is that the wagmi library continues to evolve with breaking changes. After the significant changes from v1 to v2, wagmi v3 introduces a more streamlined API that better aligns with TanStack Query patterns. The main changes in v3 include:

• Hook renames: useAccount -> useConnection (better reflects the connection model)

• Mutation function standardization: hooks now return a mutation object with .mutate() and .mutateAsync() methods instead of direct functions

• TypeScript requirement bumped to 5.7.3+

• Connector dependencies are now optional peer dependencies (install only the connectors you use)

You can see the full v3 migration guide here

First, a bit of setup

I will assume that you are using a React-based framework (I'm using Next.js) with Typescript.

Note: If you plan to use wallet connectors (WalletConnect, Coinbase, MetaMask, etc.), you now need to install their peer dependencies manually in v3.

1. Install wagmi v3 and dependencies

npm install wagmi@3 viem@2 @tanstack/react-query

2. Create a custom Provider. We need to set up two providers:

   1. The WagmiProvider provides blockchain context to your app

   2. The QueryClientProvider from TanStack Query manages data fetching and caching

Don't forget to add use client if you are using Next.js with the App Router.

"use client"
import { WagmiProvider, createConfig, http } from "wagmi";
import { mainnet, sepolia } from "wagmi/chains";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// Create wagmi config
const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
          // RPC URL for each chain
    [mainnet.id]: http(
      process.env.NEXT_PUBLIC_ETH_MAINNET_RPC,
    ),
    [sepolia.id]: http(
      process.env.NEXT_PUBLIC_ETH_SEPOLIA_RPC,
    ),
    ),
  },
});

// Create TanStack Query client
const queryClient = new QueryClient();

export const Web3Provider = ({ children }: { children: React.ReactNode }) => {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    </WagmiProvider>
  );
};

Finally, add your custom provider to your root layout.tsx file in your Next project.

"use client"
import "./globals.css";
import React from "react";
import { Web3Provider } from "./Web3Provider";

export default function RootLayout({children}: Readonly<{children:React.ReactNode;}>) {
      return (
          <html>
              <body>
                  <Web3Provider>
                      {children}
            </Web3Provider>
              </body>
        </html>
      );
};

Wallet UI note for v3

wagmi v3 refactored connectors into optional peer dependencies. This reduces bundle size and lets you control wallet SDK versions, but it also means many wallet UI libraries (like Rainbowkit and Connectkit) still targeting wagmi v2 need time to update. The result is that v3 can look "unsupported" until you manually install connectors and pass them into createConfig.

If you only need injected wallets (MetaMask, Coinbase Wallet extension, etc.), a small custom button built with wagmi hooks is enough to unblock you while the ecosystem catches up.

Read from a single smart contract

Lets start reading data from a smart contract. You can access data from any function marked as view on a smart contract, and you don't even need that your user's wallet is connected to your application.

Oftentimes you will use these functions to check token ownership or balance, this is how it looks like.

export default function RandomComponent() {
  const { address, isConnected } = useConnection();
  const {
    data: balance,
    isLoading: isLoadingBalance,
    isError: errorBalance,
    isSuccess: successBalance,
  } = useReadContract({
    // APE coin
    address: "0x4d224452801ACEd8B2F0aebE155379bb5D594381",
    abi: erc20Abi,
    functionName: "balanceOf",
    args: [address],
    chainId: 1,
  })
  //...Rest of the component ...
}

Take into account:

• If you are using balance or whatever data you have directly in your component, be sure to handle the undefined case well, as on the first render it will almost 100% return undefined.

• wagmi uses Tanstack Query, so the retries are baked in. You don't need to add balance to a useEffect dependency array just to fetch the data.

• If your output is a number, it will probably be a BigInt, handle with formatEther to get something readable.

I added chainId because, in my case, my app is configured to be able to read from both Sepolia and ETH Mainnet. Normally, wagmi hooks will fetch the config that you set up in the Provider, but if you need to read data from a different chain in just one specific component, you can define this config and only apply it to that contract call in the hook.

Example on how to read from the USDT contract on Arbitrum, just for this component. We first define the custom config for the component.

import { http, createConfig } from "wagmi"
import { arbitrum } from "wagmi/chains"

export const config = createConfig({
  chains: [arbitrum],
  transports: {
    [arbitrum.id]: http(),
  },
})

Then we just use this config on the hook

export default function RandomComponent() {
  const { address, isConnected } = useConnection();
  const { data: balance } = useReadContract({
    config,
    address: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
    abi: erc20Abi,
    functionName: "balanceOf",
    args: [address],
    chainId: 42161,
  })
  //...Rest of the component ...
}

What happens if I need to wait for another piece of data as input for the read function?

Remember, if the hook has a dependency on the args array, just handle the undefined case.

Auto-refresh after writes

If a read depends on a write you just performed, you can refetch once the write confirms. This keeps the read UI fresh without polling.

const writeContract = useWriteContract();
const { data: receipt, isSuccess: isConfirmed } = useWaitForTransactionReceipt({
  hash: writeContract.data as `0x${string}`,
});

const { refetch: refetchBalance } = useReadContract({
  address: tokenAddress,
  abi: erc20Abi,
  functionName: "balanceOf",
  args: [address],
});

useEffect(() => {
  if (!isConfirmed || !receipt) return;
  refetchBalance();
}, [isConfirmed, receipt, refetchBalance]);

Read from multiple smart contracts

You can also use wagmi's hooks to perform batch reads of different contracts, multiple functions inside the same contract or even multiple reads of the same smart contract with different input parameters.

To achieve this, we will use the useReadContracts hook, it works almost the same, but it takes an array of contract configs under the contracts key

const { data: balanceTest } = useReadContracts({
  contracts: [{
    address: "0x4d224452801ACEd8B2F0aebE155379bb5D594381",
    abi: erc20Abi,
    functionName: "balanceOf",
    args: [testAddress],
    chainId: 1,
  },
  {
    address: "0x6B175474E89094C44Da98b954EedeAC495271d0F",
    abi: erc20Abi,
    functionName: "balanceOf",
    args: [testAddress],
    chainId: 1,
  }],
})

In this case, the response will be an array of objects, "[{result: 0n, status: success}]"

Of course, if you hold the list of contracts in a separate variable, you can use map to iterate over the whole list. This often looks cleaner and the code for the component ends up less cluttered. In this case you need to do a bit more of explicit type casting.

const { data: balanceTest } = useReadContracts({
  contracts: contractConfigs.map(contract => ({
    address: contract.address as `0x${string}`,
    abi: contract.abi as Abi,
    functionName: contract.functionName,
    args: contract.args,
    chainId: contract.chainId,
  })),
})

Example repo

I set up a repo with examples for this series of articles on my Github. Feel free to explore it and run it locally!

References

• https://wagmi.sh/

• https://wagmi.sh/react/guides/migrate-from-v2-to-v3 (v3 Migration Guide)

• https://tanstack.com/query/v5/docs/framework/react/overview

• https://wagmi.sh/react/api/hooks/useReadContract#usage

Note: This article has been updated from the original version to reflect the breaking changes and new patterns introduced in wagmi v3. The core concepts remain the same, but the API syntax has been modernized to align with TanStack Query conventions and improve type safety.

Sometimes, you need to listen for an event emitted by a smart contract in your frontend. Often after making a contract call so the UI can advance to the next step of the process. So, how do we do this?

wagmi

If you have ever done Web3 frontend, then you must have heard about or used the wagmi library. Wagmi allows devs to make all kind of blockchain interactions on the frontend in a manner that feels very native to React, with a set of 40+ React hooks. From getting info about the connected wallet to smart contract interaction passing through fetching blockchain state data.

As you know, I'm a big fan of the 80/20 rule. For me that means that even if most of the functionality that wagmi has to offer is interesting, you will probably use around 20 percent of it on a regular basis. That leaves us with...8 hooks?

I'm not going to cajole this series of articles to fit that number but the plan is to talk about what I use most frequently at work. I'm also going to focus on doubts and questions that frequently come up so you can speed run your smart contract interaction tasks.

Talking about frequently asked questions, another of the reasons for this article is that the wagmi library continues to evolve with breaking changes. After the significant changes from v1 to v2, wagmi v3 introduces a more streamlined API that better aligns with TanStack Query patterns. The main changes in v3 include:

• Hook renames: useAccount -> useConnection (better reflects the connection model)

• Mutation function standardization: hooks now return a mutation object with .mutate() and .mutateAsync() methods instead of direct functions

• TypeScript requirement bumped to 5.7.3+

• Connector dependencies are now optional peer dependencies (install only the connectors you use)

You can see the full v3 migration guide here

First, a bit of setup

I will assume that you are using a React-based framework (I'm using Next.js) with Typescript.

Note: If you plan to use wallet connectors (WalletConnect, Coinbase, MetaMask, etc.), you now need to install their peer dependencies manually in v3.

1. Install wagmi v3 and dependencies

npm install wagmi@3 viem@2 @tanstack/react-query

2. Create a custom Provider. We need to set up two providers:

   1. The WagmiProvider provides blockchain context to your app

   2. The QueryClientProvider from TanStack Query manages data fetching and caching

Don't forget to add use client if you are using Next.js with the App Router.

"use client"
import { WagmiProvider, createConfig, http } from "wagmi";
import { mainnet, sepolia } from "wagmi/chains";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// Create wagmi config
const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
       // RPC URL for each chain
    [mainnet.id]: http(
      process.env.NEXT_PUBLIC_ETH_MAINNET_RPC,
    ),
    [sepolia.id]: http(
      process.env.NEXT_PUBLIC_ETH_SEPOLIA_RPC,
    ),
    ),
  },
});

// Create TanStack Query client
const queryClient = new QueryClient();

export const Web3Provider = ({ children }: { children: React.ReactNode }) => {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    </WagmiProvider>
  );
};

Finally, add your custom provider to your root layout.tsx file in your Next project.

"use client"
import "./globals.css";
import React from "react";
import { Web3Provider } from "./Web3Provider";

export default function RootLayout({children}: Readonly<{children:React.ReactNode;}>) {
      return (
          <html>
              <body>
                  <Web3Provider>
                      {children}
            </Web3Provider>
              </body>
        </html>
      );
};

Wallet UI note for v3

wagmi v3 made connectors optional peer dependencies. This gives you more control over wallet SDKs but requires you to install and wire them manually. Wallet UI kits (like Rainbowkit and Connectkit) are still adapting to this change, which is why v3 adoption looks slower in the ecosystem.

For injected-only flows, a small custom connect button using wagmi hooks is often the simplest, most reliable option.

Listen and parse smart contract events

The hook that you will use for creating a smart contract event listener on your frontend is useWatchContractEvent.

useWatchContractEvent({
  address: process.env.SMART_CONTRACT_ADDRESS,
  abi: ERC20Abi.abi,
  eventName: "Minted",
  onLogs(logs) {
    console.log("Contract event log:", logs)
  },
});

This hook does not have a return value (well, void) so all the information received through it has to be handled through the onLogs callback.

Logging the contract event logs like we do in this example will render the whole event object, with things like eventName and args that might be useful to extract information that you may need in your frontend, like fetching the tokenID of the new NFT that has been minted (transferred from the address zero) to your user or the amount of ERC20 that went from one EOA to another.

Manually decoding event logs

If, for any reason, you need to decode the raw event data received from your smart contract, you can use the lower level viem's decodeEventLog and use it on your useWatchContractEvent hook onLogs callback. You will need to pass it your contract's abi, the data and topics fields that you received in the contract event object.

useWatchContractEvent({
  address: process.env.SMART_CONTRACT_ADDRESS,
  abi: ERC721Abi.abi,
  eventName: "Minted",
  onLogs(logs) {
    const decodedLogs: any = decodeEventLog({
      abi: ERC721Abi.abi,
      data: logs[0].data,
      topics: logs[0].topics,
    });
    const tokenIdString = decodedLogs?.args?.tokenId.toString();
    setTokenId(tokenIdString);
  },
});

As you see, I'm using the callback to update a React state variable that will be used elsewhere in my component. You can use this hook together or instead of useWaitForTransactionReceipt to wait for the "response" from the smart contract when making a contract call. Both of these hooks include in their responses logs corresponding to the events emitted. The difference is that useWaitForTransactionReceipt is more targeted, as it only deals with one specific transaction hash, while useWatchContractEvent will deal with any events emitted by the contract, no matter who initiated that transaction.

This is why you want to be mindful when using this hook, as you could accidentally get data from a different user than the one currently using the UI.

Auto-refresh after events

If your UI depends on read hooks (balances, ownership, supply), you can refetch them when a relevant event arrives. This keeps the UI in sync without manual refreshes.

useWatchContractEvent({
  address: tokenAddress,
  abi: erc20Abi,
  eventName: "Transfer",
  onLogs() {
    refetchBalance();
  },
});

Example repo

I set up a repo with examples for this series of articles on my Github. Feel free to explore it and run it locally!

References

• https://wagmi.sh/

• https://wagmi.sh/react/guides/migrate-from-v2-to-v3 (v3 Migration Guide)

• https://tanstack.com/query/v5/docs/framework/react/overview

• https://wagmi.sh/react/api/hooks/useWatchContractEvent

• https://viem.sh/docs/contract/decodeEventLog.html

Note: This article has been updated from the original version to reflect the breaking changes and new patterns introduced in wagmi v3. The core concepts remain the same, but the API syntax has been modernized to align with TanStack Query conventions and improve type safety.

How do you call a smart contract function that performs a change of state (write) on the blockchain? And how could we be sure that the write transaction went through correctly?

wagmi

If you have ever done Web3 frontend, then you must have heard about or used the wagmi library. Wagmi allows devs to make all kind of blockchain interactions on the frontend in a manner that feels very native to React, with a set of 40+ React hooks. From getting info about the connected wallet to smart contract interaction passing through fetching blockchain state data.

As you know, I'm a big fan of the 80/20 rule. For me that means that even if most of the functionality that wagmi has to offer is interesting, you will probably use around 20 percent of it on a regular basis. That leaves us with...8 hooks?

I'm not going to cajole this series of articles to fit that number but the plan is to talk about what I use most frequently at work. I'm also going to focus on doubts and questions that frequently come up so you can speed run your smart contract interaction tasks.

Talking about frequently asked questions, another of the reasons for this article is that the wagmi library continues to evolve with breaking changes. After the significant changes from v1 to v2, wagmi v3 introduces a more streamlined API that better aligns with TanStack Query patterns. The main changes in v3 include:

• Hook renames: useAccount -> useConnection (better reflects the connection model)

• Mutation function standardization: hooks now return a mutation object with .mutate() and .mutateAsync() methods instead of direct functions

• TypeScript requirement bumped to 5.7.3+

• Connector dependencies are now optional peer dependencies (install only the connectors you use)

You can see the full v3 migration guide here

First, a bit of setup

I will assume that you are using a React-based framework (I'm using Next.js) with Typescript.

Note: If you plan to use wallet connectors (WalletConnect, Coinbase, MetaMask, etc.), you now need to install their peer dependencies manually in v3.

1. Install wagmi v3 and dependencies

npm install wagmi@3 viem@2 @tanstack/react-query

2. Create a custom Provider. We need to set up two providers:

   1. The WagmiProvider provides blockchain context to your app

   2. The QueryClientProvider from TanStack Query manages data fetching and caching

Don't forget to add use client if you are using Next.js with the App Router.

"use client"
import { WagmiProvider, createConfig, http } from "wagmi";
import { mainnet, sepolia } from "wagmi/chains";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// Create wagmi config
const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    // RPC URL for each chain
    [mainnet.id]: http(
      process.env.NEXT_PUBLIC_ETH_MAINNET_RPC,
    ),
    [sepolia.id]: http(
      process.env.NEXT_PUBLIC_ETH_SEPOLIA_RPC,
    ),
  },
});

// Create TanStack Query client
const queryClient = new QueryClient();

export const Web3Provider = ({ children }: { children: React.ReactNode }) => {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    </WagmiProvider>
  );
};

Finally, add your custom provider to your root layout.tsx file in your Next project.

"use client"
import "./globals.css";
import React from "react";
import { Web3Provider } from "./Web3Provider";

export default function RootLayout({children}: Readonly<{children:React.ReactNode;}>) {
      return (
          <html>
              <body>
                  <Web3Provider>
                      {children}
                </Web3Provider>
              </body>
        </html>
      );
};

Wallet UI note for v3

wagmi v3 moved wallet connector SDKs into optional peer dependencies. That means wagmi no longer bundles wallet SDKs by default, and connector UI libraries (like Rainbowkit and Connectkit) need to catch up to the new model. Some popular kits still target wagmi v2, so it can feel like v3 has "no wallet support" until you wire connectors yourself.

Practical path right now:

• install only the connector packages you need (injected, WalletConnect, Coinbase, etc.)

• pass them into createConfig

• or build a small custom connect button with wagmi hooks while the ecosystem updates

If you are using injected wallets only, you can ship a tiny custom button with useConnect, useConnection, and useDisconnect and skip third-party UI kits.

Call a smart contract

To call a smart contract using wagmi v3, you will use useWriteContract. The hook returns a mutation object following TanStack Query conventions.

const writeContract = useWriteContract()

Key changes in v3: The mutation object exposes several useful properties and methods:

• writeContract.data - Returns undefined until you call the contract. Once called, it contains the transaction hash, useful for feeding into useWaitForTransactionReceipt.

• writeContract.mutate() - Function to execute the contract call. Pass contract interaction params as an object. Use this in onClick handlers or custom functions.

• writeContract.mutateAsync() - Promise-based version if you need to await the result.

• writeContract.isPending, writeContract.isSuccess, writeContract.isError - Status flags for tracking the mutation state.

    const handleMint = (address: string) => {
        console.log('Minting...');
        writeContract.mutate({
            address: process.env.CONTRACT_ADDRESS as Address,
            abi: erc20Abi,
            functionName: "mint",
            args: [address],
        })
    };

You can also manually change the config for this hook, instead of letting it pick up from the global config. If you do this, you probably will also want to use a hook like useSwitchChain to drive the user to connect to your target chain.

const config = createConfig({
    chains: [arbitrum]
    transports: {
        [arbitrum.id]: http()
    },
})

const writeContract = useWriteContract({config})

How to handle next steps

If you only want to check if the tx was sent successfully, you can use the mutation object's status flags (isPending, isSuccess, isError) or pass callbacks to the .mutate() function like onSuccess, onError, or onSettled.

But some times you need to use the tx confirmation, the function return values or even an event emitted by the contract.

This is when useWaitForTransactionReceipt and useWatchContractEvent come in handy. I talk about the latter one on the next article but lets see now how you would wait for the tx receipt event.

Wait for the tx receipt with wagmi

After calling a smart contract, you normally wait for some confirmation that your transaction went through and then you make some action.

This is a key element of blockchain UX, your users want to be sure that they did everything right and the action that they intended to make is completed.

This is when useWaitForTransactionReceipt comes into play. Remember the writeContract.data property? That contains the tx hash of our contract call, and that's what we use as input for this hook.

const writeContract = useWriteContract();
const { data:receipt, isLoading: isConfirming, isSuccess: isConfirmed } =
      useWaitForTransactionReceipt({hash: writeContract.data as `0x${string}`});

The receipt object is a complex one, with lots of data about your transaction. Info about gas usage, transaction type and a logs object which you can decode to get data about events emitted by the transaction.

The logs field includes a data and a topics field. They are hex-encoded, but you can transform them to a human readable format using viem's lower level decodeEventLogs

const decodedLogs:any = decodeEventLog({
            abi: ERC20Abi,
            data: logs[0].data,
            topics: logs[0].topics,
          });

Auto-refresh after confirmation

A simple pattern is to refetch any related reads once the transaction is confirmed. This keeps the UI in sync without manual refreshes.

const writeContract = useWriteContract();
const { data: receipt, isSuccess: isConfirmed } = useWaitForTransactionReceipt({
  hash: writeContract.data as `0x${string}`,
});

const { refetch: refetchBalance } = useReadContract({
  address: tokenAddress,
  abi: erc20Abi,
  functionName: "balanceOf",
  args: [address],
});

useEffect(() => {
  if (!isConfirmed || !receipt) return;
  refetchBalance();
}, [isConfirmed, receipt, refetchBalance]);

Example repo

I set up a repo with examples for this series of articles on my Github. Feel free to explore it and run it locally!

References

• https://wagmi.sh/

• https://wagmi.sh/react/guides/migrate-from-v2-to-v3 (v3 Migration Guide)

• https://tanstack.com/query/v5/docs/framework/react/overview

• https://wagmi.sh/react/api/hooks/useWriteContract

• https://wagmi.sh/react/api/hooks/useWaitForTransactionReceipt#usewaitfortransactionreceipt

• https://viem.sh/docs/contract/decodeEventLog.html

The conversation goes somewhat like this:
- PM: Can we create multiple copies of the same contract without redeploying the same one over and over? We can save a lot of gas costs in that way.
You, savvy Solidity developer who did his homework, answer confidently:
- 0x9: Sure, there is EIP1167, the Minimal Proxy Contract (Minimal Clones), that allows us to deploy proxies pointing to an implementation address with minimal cost.
- PM: That sounds perfect, but if we are using a Proxy, then that means that those Clone contracts will still be upgradeable right?
Wrong, your soul sinks into an abysm of despair.
- 0x9: Erm...not really, in Minimal Proxy contract the implementation address is hardcoded into the bytecode, so you can't just change it without breaking the standard. Plus, even if you could, you would have to go over every Clone changing the address (and I would rather not do that).
- PM: I see, then please get me the best option to implement an Upgradeable Factory pattern while keeping the ability to upgrade all the copies at the same time.

That is more or less how it goes. You are left alone in your home office to speak with your rubber duck 🦆 about how you can figure this out.

How to create multiple proxies pointing to the same implementation?

This one is the easiest part (but spoiler, it won't be enough)You can create multiple copies of a Universal Upgradeable Proxy Standard (UUPS) or a Transparent Proxy. Since we have been told to get the most gas-efficient solution possible we will go with UUPS, since Transparent Proxies are more expensive to deploy and operate.

In UUPS the upgrade logic is handled by the implementation contract. This means that the contract holding the logic must include an upgradeTo(newImplementation address) that will update the implementation address in storage, therefore changing where the Proxy directs its delegatecall() function.

Before we continue: project setup

I am assuming that you know how to set up a Solidity project so I will skip all of those steps. I normally use Foundry so if you want to follow along you can either go to the article's repo or set up a new project through my Foundry template.

How do we create multiple copies of the contract?

1. Implementation contract

   Once we deploy our implementation contract, we deploy an ERC1967 Proxy that points to this implementation. Since our that contract inherits from UUPSUpgradeable, the upgrade() logic resides there. We are going to implement 2 versions of an NFT contract, V1 only has a mint()function while V2 also includes a burn()function. Most of the initial parameters for a standard NFT contract are defined within the initialize() function.

//SPDX-License-Identifier: MIT
pragma solidity 0.8.20;

import "@openzeppelin-contracts-upgradeable/contracts/token/ERC721/ERC721Upgradeable.sol";
import "@openzeppelin-contracts-upgradeable/contracts/access/OwnableUpgradeable.sol";
import "@openzeppelin/contracts/proxy/utils/UUPSUpgradeable.sol";
import "../interfaces/Inft.sol";


error MintPriceNotPaid();
error SupplyExceeded();

contract NFTV1UUPS is INFT, ERC721Upgradeable, OwnableUpgradeable, UUPSUpgradeable {
    uint256 public maxSupply;
    uint256 public price;
    uint256 public tokenId;
    string public baseTokenURI;

    constructor() {
        _disableInitializers();
    }

    function initialize(
        string memory name,
        string memory symbol,
        string memory baseURI,
        uint256 initialMaxSupply, 
        uint256 initialPrice,
        address owner
    ) external initializer {

        __ERC721_init_unchained(name, symbol);
        __Ownable_init_unchained();

        baseTokenURI = baseURI;
        maxSupply = initialMaxSupply;
        price = initialPrice;
        transferOwnership(owner);
    }

    function mint(address to, uint256 amount) external payable onlyOwner {
        uint256 currentId = tokenId;

        if(currentId + amount > maxSupply) revert SupplyExceeded();
        if(msg.value != price * amount) revert MintPriceNotPaid();

        tokenId += amount;

        for (uint256 i= 0; i < amount; i++){
            _mint(to, currentId + i);
        }
    }

    function withdraw() external onlyOwner {
     uint256 balance = address(this).balance;
     require(balance > 0, "No ether left to withdraw");

     (bool success, ) = payable(owner()).call{value: balance}("");

     require(success, "Transfer failed.");
    }

    function _authorizeUpgrade(address) internal override onlyOwner {}

    function _baseURI() internal view override returns (string memory) {
       return baseTokenURI;
    }
}

1. Factory contract

   Now to generate multiple "copies" of the implementation contract, we can create a Factory contract that will generate a new ERC1967 Proxy each time we call our createNft() function. We are using the CREATE2 opcode to generate the contract addresses deterministically.

   Each time we create a new contract we increment an id counter. This counter will allow us to:

   1. Know how many copies of our contract exist.

   2. Fetch the address of any of those copies according to their id.

   3. Use it as the saltvalue that lets us create the contract with a deterministic address.

If you add the {salt:bytes32(ID)}param when you create a new contract from another contract, the compiler will interpret that you intend to use CREATE2 instead of CREATE.

Also, note that the best practice is to include the ABI-encoded call to the initialize function in the _data argument within the constructor call to the ERC1967 Proxy as per the Openzeppelin docs to avoid leaving the Proxy uninitialized. However, we are doing it in a separate call within the same function. Otherwise, we would need to know the initial deployment arguments when trying to reconstruct the newly deployed contract address.

//SPDX-License-Identifier: MIT
pragma solidity 0.8.20;

import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";
import "@openzeppelin/contracts/access/Ownable.sol";
import "../interfaces/Inft.sol";

error NonExistingProxy();
error ZeroAddress();
contract UUPSProxyFactory is Ownable {
    uint256 private _proxyId;
    address private _implementation;

    constructor (address implementation) {
        _implementation = implementation;
    }

    function createNewProxy(
        string memory name, 
        string memory symbol, 
        string memory baseURI, 
        uint256 maxSupply, 
        uint256 price
    ) external returns (address) {
        ERC1967Proxy proxy = new ERC1967Proxy{salt: bytes32(_proxyId)}(_implementation, "");
        INFT inft = INFT(address(proxy));
        inft.initialize(name, symbol, baseURI, maxSupply, price, msg.sender);
        _proxyId++;
        return address(proxy);
    }

    function setImplementation(address implementation) external onlyOwner {
        if(implementation == address(0)) revert ZeroAddress();
        _implementation = implementation;
    }

    function getProxyAddress(uint256 proxyId) external view returns (address) {
        if (proxyId > _proxyId) revert NonExistingProxy();

        bytes memory bytecode = type(ERC1967Proxy).creationCode;
        bytecode = abi.encodePacked(bytecode, abi.encode(_implementation,""));
        bytes32 hash = keccak256(
            abi.encodePacked(
                bytes1(0xff),
                address(this),
                proxyId,
                keccak256(bytecode)
            )
        );

        return address(uint160(uint256(hash)));
    }

    function getCurrentProxyId() external view returns (uint256) {
        return _proxyId;
    }
}

Why this is not enough? Simultaneous Upgrades

I am sure by now you were pulling your hair out. You got it wrong! That's not how it works! Well yeah, my internet frens but this is a walkthrough on the thought process of how to solve a given problem, as well as a code tutorial.

Why our current solution won't work? Because, one of the key requirements that we were given was to be able to simultaneously upgrade all the proxy copies of our contract. Neither UUPS nor Transparent proxies can do that because the address of the implementation contract lives on the storage of each instance of the proxy (even though the logic on how to upgrade it lives in different places depending on the standard).

So how can we update the implementation address without going through each one of the proxies that our factory contract has generated? We use a Beacon Proxy.

Beacon proxy

In the Beacon proxy pattern, the implementation address is stored in a special contract, called precisely a Beacon, and every proxy checks against it what is the current implementation address before performing the delegateCall .

This makes it more costly to deploy than UUPS, as we will be deploying 3 contracts initially (implementation, Beacon, and proxy factory) but it checks all the boxes of our requirements as we only need to change the implementation address stored in the Beacon and then all of our proxy copies will begin forwarding their calls to the new logic contract. Note that this extra call also makes it a bit more expensive to use than UUPS, as we need more gas to go through the whole process.

This is what it looks like:

On the implementation side, NFTV1 doesn't inherit from UUPSUpgradeable anymore.

//SPDX-License-Identifier: MIT
pragma solidity 0.8.20;

import "@openzeppelin-contracts-upgradeable/contracts/token/ERC721/ERC721Upgradeable.sol";
import "@openzeppelin-contracts-upgradeable/contracts/access/OwnableUpgradeable.sol";
import "./interfaces/Inft.sol";


contract NFTV1 is INFT, ERC721Upgradeable, OwnableUpgradeable {
    uint256 public maxSupply;
    uint256 public price;
    uint256 public tokenId;
    string public baseTokenURI;

    error MintPriceNotPaid();
    error SupplyExceeded();

    constructor() {
        _disableInitializers();
    }

    function initialize(
        string memory name,
        string memory symbol,
        string memory baseURI,
        uint256 initialMaxSupply, 
        uint256 initialPrice,
        address owner
    ) external initializer {

        __ERC721_init_unchained(name, symbol);
        __Ownable_init_unchained();

        baseTokenURI = baseURI;
        maxSupply = initialMaxSupply;
        price = initialPrice;
        transferOwnership(owner);
    }

    function mint(address to, uint256 amount) external payable onlyOwner {
        uint256 currentId = tokenId;

        if(currentId + amount > maxSupply) revert SupplyExceeded();
        if(msg.value != price * amount) revert MintPriceNotPaid();

        tokenId += amount;

        for (uint256 i= 0; i < amount; i++){
            _mint(to, currentId + i);
        }
    }

    function _baseURI() internal view override returns (string memory) {
       return baseTokenURI;
    }

    function withdraw() external onlyOwner {
     uint256 balance = address(this).balance;
     require(balance > 0, "No ether left to withdraw");

     (bool success, ) = payable(owner()).call{value: balance}("");

     require(success, "Transfer failed.");
    }
}

On the Factory contract, we are not deploying ERC1967 Proxies anymore, but Beacon Proxies.

//SPDX-License-Identifier: MIT
pragma solidity 0.8.20;

import "@openzeppelin/contracts/proxy/beacon/BeaconProxy.sol";
import "@openzeppelin/contracts/access/Ownable.sol";
import "./interfaces/Inft.sol";

contract BeaconProxyFactory is Ownable {
    uint256 private _proxyId;
    address private _beacon;

    constructor (address beacon) {
        _beacon = beacon;
    }

    function createNewProxy(
        string memory name, 
        string memory symbol, 
        string memory baseURI, 
        uint256 maxSupply, 
        uint256 price
    ) external returns (address) {
        BeaconProxy proxy = new BeaconProxy{salt: bytes32(_proxyId)}(_beacon, "");
        INFT inft = INFT(address(proxy));
        inft.initialize(name, symbol, baseURI, maxSupply, price, msg.sender);
        _proxyId++;
        return address(proxy);
    }
    function getProxyAddress(uint256 proxyId) external view returns (address) {
        bytes memory bytecode = type(BeaconProxy).creationCode;
        bytecode = abi.encodePacked(bytecode, abi.encode(_beacon,""));
        bytes32 hash = keccak256(
            abi.encodePacked(
                bytes1(0xff),
                address(this),
                proxyId,
                keccak256(bytecode)
            )
        );

        return address(uint160(uint256(hash)));
    }
    function getCurrentProxyId() external view returns (uint256) {
        return _proxyId;
    }
}

Don't get confused by the contract's naming. If you are using Openzeppelin's contracts, Beacon Proxy is the proxy that looks up the implementation address in the Beacon contract, and that Beacon contract is called UpgradeableBeacon . You can see it clearly in the deployment script.

// SPDX-License-Identifier: UNLICENSED
pragma solidity 0.8.20;

import {Script, console2} from "forge-std/Script.sol";
import "../src/NFTV1Implementation.sol";
import "../src/BeaconProxyFactory.sol";
import "@openzeppelin/contracts/proxy/beacon/UpgradeableBeacon.sol";


contract Deploy is Script {
    function setUp() public {
    }

    function run() public {
        vm.startBroadcast();

        NFTV1 implementationV1 = new NFTV1();
        console2.log("Deployed NFTV1 Implementation at address: %s", address(implementationV1));

        UpgradeableBeacon beacon = new UpgradeableBeacon(address(implementationV1));

        BeaconProxyFactory beaconProxyFactory = new BeaconProxyFactory(address(beacon));

        vm.stopBroadcast();
    }
}

Conclusion

As we mentioned before, if we deploy a new version of our implementation, like our NFTV2 which includes a burn()functionality, we can just change the current address stored in UpgradeableBeacon and all the deployed proxies will acquire the new functionality. Be mindful of security on your upgrades as you can also potentially include a bug in all the copies of your contract at once.

References

• https://docs.openzeppelin.com/contracts/5.x/api/proxy#BeaconProxy

• https://blog.openzeppelin.com/deep-dive-into-the-minimal-proxy-contract

• https://blog.logrocket.com/using-uups-proxy-pattern-upgrade-smart-contracts/#what-is-a-uups-proxy-pattern

• https://dev.to/nvn/proxy-patterns-for-upgradeability-of-solidity-contracts-transparent-vs-uups-proxies-3ig2

• https://defihacklabs.substack.com/p/secure-proxy-models-understanding

The Graph is a protocol for indexing and querying blockchain data. It enables you to use your smart contract's events to create and update entities that represent the internal state of such a smart contract.

Why is this useful? Imagine a smart contract that requires an intensive lookup of information. An NFT marketplace is a good example. You have potentially thousands of listings going on at the same time, assuming that you need a listing ID to buy an item from another user. How do you identify a specific listing that you are interested in? How do you find it? From a front-end point of view, how do you get all listings, and filter them by seller, or by any other criteria?

If you are familiar with Solidity, you know you can do some of these things, but most of them are not very practical or are directly impossible when you reach a certain scale.

Let's see: if you use mappings to index a Listing struct, you need to know beforehand the key that identifies a given listing so you can track it in your frontend. Even if you do some composite key (mapping-ception) and use, say, the user address and the token ID, how do you get all the listings for a given user? You can't traverse a mapping and trying all the existing possibilities is not practical.

"I will use an array then", fine but then you will eventually run out of gas just reading your arrays if your marketplace is even marginally successful.

With The Graph, you can create a Listing entity that gets updated anytime your users interact with any given listing. You can create, update, and delete any particular Listing instance, just telling the Graph the effect that your smart contract's events should have over that entity. Using GraphQL you can get any of those Listing entities, filter them to display the appropriate data, or even fetch info that you can use as input for a new smart contract function call.

"I could do that with a regular database, just storing anything that goes through my front end" I hear you saying. You are right, but there are some advantages to using this approach:

• You don't depend on your front end. You already know that not all transactions need to/will go through your front end as anyone can interact directly with your smart contracts.

• Less surface area for mistakes. All the Subgraph information comes from the events emitted in the smart contract. We could say that the data comes from a primary source.

• Decentralization. This is still a work in progress. If you deploy your Subgraph to the Graph network (or even to the Hosted Service) your users don't need to trust that you won't be manipulating the data in your favor. They still need to trust that you won't stop paying the Network fees so the data remains available, but that's a different problem. If you don't want to go over the trouble of deploying to the Graph network, there are other services that offer more centralized solutions.

Ok, I'm convinced. How do I start?

We will deploy our first Subgraph to the Subgraph Studio for testing.

You will need a wallet to connect to Subgraph Studio and an already deployed contract to bootstrap your subgraph. It's probably best to design your subgraph while on testnet, as you will likely want to change your smart contracts events while creating the subgraph.

Set up your Graph Studio/Hosted Service Account

You will need to connect your wallet (Graph Studio) or your Github Account (Hosted Service) and then create a subgraph through the UI. This is important as you will need that name to be the same in your local setup so you can later deploy it.

Graph CLI

Then, you will need to install the Graph CLI.

# NPM
$ npm install -g @graphprotocol/graph-cli

# Yarn
$ yarn global add @graphprotocol/graph-cli

Subgraph bootstrapping

Using graph init you will start the process of bootstrapping your subgraph.

• Choose your protocol. No matter the specific chain your contracts are deployed into, if you are on an EVM chain, choose Ethereum.

• Product to initialize. subgraph-studio in our case.

• Subgraph slug. You should have set this when creating a new subgraph in the Studio 2 steps ago.

• Directory to create subgraph in (self-explanatory).

• Ethereum network. Here is where you choose the network where your contract is deployed.

• Contract Address. If you have more than one contract address, just choose one. You can add the rest later.

• Fetch ABI and start block. If your contract is verified on Etherscan, the CLI should be able to fetch the abi file and start block from there. Otherwise, you will need to provide a directory where the CLI can fetch the abi from.

• Contract Name. Same as your contract name. Please don't skip this, or else all your relevant files and handlers will be named as Contract and that's annoying.

• Index contract events as entities? This is an example of a Good/Bad Default. We will talk more about this later. Choose YES for now.

• After some automatic code generation, you will be asked if you want to add another contract. Do so if you need to but if it fails, don't fret, you can use graph add <CONTRACT_ADDRESS> later to add new contracts.

  

Code away! Design your subgraph

For our example marketplace subgraph, we will assume that we will only deal with 2 entities: ItemSold and Listing. Item Sold will help us keep track of all successful sales, while we will use Listing to keep track of all marketplace listings during all of their lifecycle.

Remember when we bootstrapped the project, we said yes to indexing all contracts as entities? This is useful to get a feeling of how these entities look according to your events, data types, etc. This is the moment to actually design a data structure (the entities) that makes sense for your application. In our case, if we take Listing, it makes much more sense to just create one entity and modify it according to any changes that a specific instance might have, rather than just keep a record of all the events that happen, disconnected from each other.

schema.graphql

This is the file where you declare your entities, the ones that you want to track and query in your application. Any change to these entities will come from emitted events in your smart contracts.

Eliminate all the events-turned-entities and just leave ItemsSold plus a new Listing entity that gathers all the useful information of a given entity (all the info contained in the Listing struct in ISimpleMarketplace.sol). I also leave the blockNumber, timestamp, and tx hash.

Every entity needs to have a unique ID. By default, the event handlers create one based on the tx hash. If you only want to record all events then you can leave it like that, but if you want to modify an entity state based on the events that affect it (like a Listing having a new price) then you need to have an ID that you can reference in all the events that affect a given entity, and use it as an entry point to modify it.

This is when subgraph design and smart contract development should (ideally) work together. For example, each listing has a unique ID, a counter in the smart contract, and this ID is emitted in all the events that affect a listing.

//@dev from IBasicMarketplace.sol
// Emitted when a valid listing is created
event ListingCreated(uint256 listingId, address seller, address nft, uint256 tokenId, uint256 price, bool exist);
// Emitted when a valid listing is updated by the Seller
event ListingUpdated(uint256 listingId, address seller,  address nft, uint256 tokenId, uint256 price);
// Emitted when a listing is cancelled 
event ListingCancelled(uint256 listingId);

I will be using this listingId, which is emitted in every event as an ID for the Listing entity. This is how I know that I am modifying the correct entity instance for each change in every listing estate. This is not seen clearly in the GraphQL schema but will be clear in the mapping file when we deal with the event handlers.

type ItemSold @entity(immutable: true) {
  id: ID!
  listingId: BigInt! # uint256
  nft: Bytes! # address
  seller: Bytes! # address
  buyer: Bytes! # address
  price: BigInt! # uint256
  blockNumber: BigInt!
  blockTimestamp: BigInt!
  transactionHash: Bytes!
}

type Listing @entity {
  id: ID!
  listingId: BigInt! # uint256
  seller: Bytes! # address
  nft: Bytes! # address
  tokenId: BigInt! # uint256
  price: BigInt! # uint256
  exist: Boolean! # bool
  blockNumber: BigInt!
  blockTimestamp: BigInt!
  transactionHash: Bytes!
}

your-contracts.ts (Mapping file)

In our case simple-marketplace.ts often referred to in the docs as the mapping file, which I found to be a confusing term at first but it actually makes sense.

This is the file that maps the events emitted by your smart contract to the entities that you declared in your schema. It is the backend business logic that handles the changes in your database.

The subgraph is constantly listening for events from our contract. Each time an event hits the subgraph, the appropriate event handler gets triggered. Here you can see clearly why it is important to design our smart contracts with subgraph design in mind, as we use the listingId as a handle to get the correct listing every time we receive an event. At any given point, each listing instance reflects the current state of the listing within our smart contract.

import {
  ListingCancelled as ListingCancelledEvent,
  ListingCreated as ListingCreatedEvent,
  ListingUpdated as ListingUpdatedEvent,
} from "../generated/SimpleMarketplace/SimpleMarketplace"
import {
  Listing
} from "../generated/schema"
import { store } from '@graphprotocol/graph-ts'

export function handleListingCancelled(event: ListingCancelledEvent): void {
  let entity: Listing | null
  entity = Listing.load(event.params.listingId.toString())

  if (entity!== null){
    store.remove("Listing", event.params.listingId.toString())
  }
}

export function handleListingCreated(event: ListingCreatedEvent): void {
  let entity: Listing | null
  entity = new Listing(event.params.listingId.toString())

  entity.listingId = event.params.listingId
  entity.seller = event.params.seller
  entity.nft = event.params.nft
  entity.tokenId = event.params.tokenId
  entity.price = event.params.price
  entity.exist = event.params.exist

  entity.blockNumber = event.block.number
  entity.blockTimestamp = event.block.timestamp
  entity.transactionHash = event.transaction.hash

  entity.save()
}

export function handleListingUpdated(event: ListingUpdatedEvent): void {
  let entity: Listing | null
  entity = Listing.load(event.params.listingId.toString())

  if(entity !== null){
    entity.listingId = event.params.listingId
    entity.seller = event.params.seller
    entity.nft = event.params.nft
    entity.tokenId = event.params.tokenId
    entity.price = event.params.price

    entity.blockNumber = event.block.number
    entity.blockTimestamp = event.block.timestamp
    entity.transactionHash = event.transaction.hash

    entity.save()
  }
}

subgraph.yaml

This file controls de deployment of the subgraph. Here we declare what is the contract's deployment address, what is the starting block to begin the indexing, network, tracked events, handlers... everything!

We will keep just 2 entities, ItemSold and Listing. We delete all the other entities. Regarding event handlers, we keep all of those already declared (we modified their original behavior in the mapping file) except for OwnershipTransferred which is inherited from Ownable and has no interest for us.

specVersion: 0.0.5
schema:
  file: ./schema.graphql
dataSources:
  - kind: ethereum
    name: SimpleMarketplace
    network: sepolia
    source:
      address: "0xf91C1bfb2dbAcbfBD39a171eF0Cd3E3b47893099"
      abi: SimpleMarketplace
      startBlock: 4233781
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - ItemSold
        - Listing
      abis:
        - name: SimpleMarketplace
          file: ./abis/SimpleMarketplace.json
      eventHandlers:
        - event: ItemSold(uint256,address,address,address,uint256)
          handler: handleItemSold
        - event: ListingCancelled(uint256)
          handler: handleListingCancelled
        - event: ListingCreated(uint256,address,address,uint256,uint256,bool)
          handler: handleListingCreated
        - event: ListingUpdated(uint256,address,address,uint256,uint256)
          handler: handleListingUpdated
      file: ./src/simple-marketplace.ts

Build and deploy your subgraph

Once you finish with the previous step, how do you deploy your subgraph to Studio?

From your root directory, first, compile the project running:

graph codegen && graph build

You will surely find some compilation errors and will need to make adjustments to the code. (Assemblyscript is quite strict, plus not all JS features are implemented, like object spreading).

Once these difficulties are overcome, run graph auth with the deploy key that you will find in the Subgraph Studio UI, on your newly created subgraph.

graph auth --studio <DEPLOY_KEY>

Then finally, deploy to your subgraph name.

graph deploy --studio <SUBGRAPH_NAME>

You will be asked to provide a version label. You can change your code or metadata and redeploy as many times as you want before publishing to the decentralized network.

Thats it! You successfully deployed your first subgraph.

Next steps: publish to the Graph Decentralized Network

Publishing to the Decentralized network is as easy as pushing "Publish" on your subgraph Studio UI.

You can publish to Ethereum Mainnet, Goerli, Arbitrum One, or Arbitrum Goerli, but that (supposedly) does not have an effect on your indexing as long as the subgraph points to one of the supported networks.

It is recommended that you curate your own subgraph upon deployment, so Indexers and other Curators can pick it up and start indexing it as well. It is recommended to use at least 10K GRT to begin with, which at current prices is close to 740 USD. For testing purposes querying to Subgraph Studio is more than enough.

Indexing and Curation are topics in themselves, and it's probably worth writing another article on them. So for now I'm leaving you the docs on Curators and Indexers.

See also

Link to the full example repository on Github

The Graph docs

• https://thegraph.com/docs/en/about/

• https://thegraph.com/docs/en/developing/creating-a-subgraph/

• https://thegraph.com/docs/en/deploying/subgraph-studio/

Centralized services to deploy subgraphs (not sponsored)

• https://chainstack.com/subgraphs/

• https://chainstack.com/how-to-build-a-subgraph-in-5-minutes/

• https://alchemy.com/blog/alchemy-acquires-satsuma

Link to query the example subgraph

Link to the deployed smart contract on Sepolia

The EIP-2981 aims to standardize the way that marketplaces and other intermediaries pay royalties to the original creator of a given non-fungible token.

Soon after the NFT explosion in popularity (Thank you, Beeple?) it became evident that blockchain technology could enable creators and artists to receive a share of the sale price of their creative production every time it changed hands. This kind of royalty payment required ownership and exchange tracking that was basically impossible in a market as opaque as the art market or as free as the Internet.

The problem was, that each marketplace implemented this royalty payment differently and they were not compatible across them. This made it impossible again to track the royalty amount to be paid and the receiver of those funds. The implementation of this standard solves this problem and allows for the "ongoing funding of artists and other NFT creators"(EIP-2981).

Key characteristics

Royalties are just a piece of information, that live the smart contract and say "Hey, this is the creator of this collection or token, and he would like to be paid x% of the price paid by his artwork)

• It is non-enforceable by design. It is recognized that not all NFT transfers are part of a sale, so it doesn't make sense to create a standard that would pay creators for every time an NFT changes wallet. Marketplaces as an industry are expected to implement it.
• It is agnostic to the unit of exchange. Royalties are calculated as a percentage of the sale price, independently of the token used for payment. Therefore royalties can be paid in ETH or any ERC-20.

I was about to call this section the "NFT Royalties Standard" but then I realized that it would be inaccurate. Although originally designed with non-fungible tokens in mind, the standard is intentionally designed to be as minimal as possible. It is compatible with ERC1155 and ERC721 but it isn't exclusive to them and it could be used to set royalties payments for any asset class.

Implementing EIP-2981

Before diving into the full implementation, we need to be aware of some limitations of the standard and different ways of assigning the royalties.

Currently, the standard only allows for ONE address as the payee of royalties. If any given NFT, collection, etc... has a number of creators or royalties that want to be shared among different team members, then the best course of action is to set a split payment contract as the recipient of the royalties and then periodically send each participant's share of the balance to their wallets. For quick implementation, check out OpenZeppelin´s Payment Splitter contract.

In this article, we will set a single royalties recipient for all the tokens in an NFT contract (contract-wide royalties). However, the standard allows for more granularity so you could set a different royalty recipient and amount for each Token ID in a given NFT collection. I will show you how in the bonus section.

Which marketplaces currently support EIP-2981?

So far, I have not easily found a list of marketplaces that implement this standard. So, I went to the docs of the major ones and checked for myself so you don't have to. I am only including the ones where I could find explicitly in their docs that they support EIP-2981.

• Mintable. One of the original actors involved in EIP-2981. See here
• Rarible. They use 3 different royalties system, including EIP-2981. See here
• LooksRare. Also uses a double system, with EIP-2981 taking precedence. See here

I am sure I am missing some others. If so, please let me know!

Opensea does NOT support EIP-2981. You can set up contract wide royalties through their UI or a parameter in contractURI see here.

Lets code!

The EIP-2981 implements a single function:

royaltyInfo(uint256 _tokenID, uint256 _salePrice) external view returns(address receiver, uint256 royaltyAmount)

Before implementing the body of the function, we will need some auxiliary structures to store this information and will add a utility function setRoyalties so we are able to modify the recipient of our royalties proceeds and the amount to be paid.

struct RoyaltyInfo {
        address recipient;
        uint256 amount;
    }

RoyaltyInfo private _royalties;

Using the information in the Royalties struct, now we can implement the body of royaltyInfo(). Note that we are calculating the percentage to be paid as a fraction of 10,000 in order to increase the accuracy of the division.

    function royaltyInfo(uint256 tokenId, uint256 value) external view returns (address receiver, uint256 royaltyAmount)
    {
        RoyaltyInfo memory royalties = _royalties;
        receiver = royalties.recipient;
        royaltyAmount = (value * royalties.amount) / 10000;
    }

How do you set those royalties? You could set the info in _royalties inside the constructor, but it's a common pattern to just create a function that updates that information.

    function setRoyalties(address recipient, uint256 value) public onlyOwner {
        require(value <= 10000, 'ERC2981Royalties: Too high');

        _royalties = RoyaltyInfo(recipient, value);
    }

Also, if you want to set up the royalties upon contract creation, then you can still call this function inside the constructor() function.

Lastly, we need to inform other contracts (marketplaces) about the fact that ours is implementing EIP-2981:

//Interface for royalties
    bytes4 private constant _INTERFACE_ID_ERC2981 = 0x2a55205a;

       function supportsInterface(bytes4 interfaceId) public view override(ERC721) returns (bool){

        return interfaceId == _INTERFACE_ID_ERC2981 || super.supportsInterface(interfaceId);
    }

That was a bit messy and not so well structured. See the whole NFT contract below with proper formatting.

// SPDX-License-Identifier: UNLICENSED

pragma solidity ^0.8.0;

import "@openzeppelin/contracts/utils/Counters.sol";
import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "@openzeppelin/contracts/token/ERC20/IERC20.sol";

contract CoolPinapple is ERC721, Ownable {
    using Counters for Counters.Counter;

    struct RoyaltyInfo {
        address recipient;
        uint256 amount;
    }

    RoyaltyInfo private _royalties;

    //Interface for royalties
    bytes4 private constant _INTERFACE_ID_ERC2981 = 0x2a55205a;

    Counters.Counter private _tokenIds;

    uint256 public constant MAX_SUPPLY = 10001;

    uint256 public constant PRICE = 1 ether;

    string public baseTokenURI;

    constructor(string memory baseURI) ERC721("NFTContract", "NFT") {
        baseTokenURI = baseURI;
        setRoyalties(owner(), 500); //5%

    }

    function _baseURI() internal view override returns (string memory) {
       return baseTokenURI;
    }

    function mintNFTs(uint256 _number) public payable {
        uint256 totalMinted = _tokenIds.current();

        require(totalMinted + _number < MAX_SUPPLY, "Not enough NFTs!");
        require(msg.value == PRICE * _number , "Not enough/too much ether sent");

        mintsPerAddress[msg.sender] += _number;

        for (uint i = 0; i < _number; ++i) {
            _mintSingleNFT();
        }

    }

    function _mintSingleNFT() internal {
      uint newTokenID = _tokenIds.current();
      _safeMint(msg.sender, newTokenID);
      _tokenIds.increment();
    }

    function getCurrentId() public view returns (uint256) {
        return _tokenIds.current();
    }

    function supportsInterface(bytes4 interfaceId) public view override(ERC721) returns (bool){

        return interfaceId == _INTERFACE_ID_ERC2981 || super.supportsInterface(interfaceId);
    }

    function setRoyalties(address recipient, uint256 percentagePoints) public onlyOwner {
        require(value < 10001, 'ERC2981Royalties: Too high');

        _royalties = RoyaltyInfo(recipient, percentagePoints);
    }

    function royaltyInfo(uint256 tokenId, uint256 value) external view returns (address receiver, uint256 royaltyAmount)
    {
        RoyaltyInfo memory royalties = _royalties;
        receiver = royalties.recipient;
        royaltyAmount = (value * royalties.amount) / 10000;
    }

function withdraw() external onlyOwner {
     uint256 balance = address(this).balance;
     require(balance > 0, "No ether left to withdraw");

     (bool success, ) = payable(owner()).call{value: balance}("");

     require(success, "Transfer failed.");
    }

receive() external payable { 
            revert();
    }

}

Bonus: Implementing token-level royalties.

To implement token-level royalties (minter becomes the receiver of the royalties, for example) you just need to add a mapping, modify royaltyInfo() as well as setRoyalties() and then call setRoyaltiesin your mint() function.

mapping(uint256=>RoyaltyInfo) royaltyPerTokenId; //Change here

function royaltyInfo(uint256 tokenId, uint256 value) external view returns (address receiver, uint256 royaltyAmount)
    {
        RoyaltyInfo memory royalties = royaltyPerTokenId[tokenId]; //Change here
        receiver = royalties.recipient;
        royaltyAmount = (value * royalties.amount) / 10000;
    }

 function setRoyalties(address recipient, uint256 value, uint256 tokenId) public onlyOwner {
        require(value <= 10000, 'ERC2981Royalties: Too high');

        royaltyPerTokenId[tokenId] = RoyaltyInfo(recipient, value); //Change here
    }

function _mintSingleNFT() internal {
      uint newTokenID = _tokenIds.current();
      _safeMint(msg.sender, newTokenID);
      setRoyalties(msg.sender, 500, newTokenID); //Change here
      _tokenIds.increment();

    }

You can see the full contract as CoolPinapleTokenIdRoyalties.sol in the Github Repo.

Bonus 2. Let's make it cleaner

If separation of concerns and making your project more orderly is important for you, you could implement the EIP-2981 interface and a base contract with the core Royalty logic in separate contracts, and then make your core NFT contract inherit from them.

If you are interested in that kind of file structure, check out this other Github repo.

Reference

• Zach Burks, James Morgan, Blaine Malone, James Seibel, "EIP-2981: NFT Royalty Standard," Ethereum Improvement Proposals, no. 2981, September 2020. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-2981.
• https://medium.com/quick-programming/erc2981-nft-royalty-standard-what-is-it-and-how-do-you-use-it-724f3f12ae36
• https://github.com/dievardump/EIP2981-implementation
• https://ethereum-blockchain-developer.com/121-erc721-secondary-sales-royalties-erc2981/06-mintable-erc2981-royalties/
• https://mintable.medium.com/grant-from-ethereum-foundation-ecosystem-support-eip-2981-royalties-for-nfts-and-a-way-to-mint-dfaa6cb3e08a
• https://medium.com/knownorigin/eip-2981-simple-and-effective-royalty-standards-for-all-dbd0b761a0f0

What is Foundry

Foundry started as a testing framework for smart contracts in Solidity with a simple premise: Solidity testing should be made using Solidity, not Javascript or Python. From there it has evolved into a fully-fledged development framework that includes:

• Forge: Command line tool that allows you to build, test and deploy your smart contracts using only Solidity. The test themselves are written using the Forge Standard Library and Forge`s Cheatcodes which allows altering the state of the blockchain.
• Cast: Another powerful cli tool used to interact with existing contracts in the blockchain. You can use it to call a contract, send transactions and view on-chain data.
• Anvil: Local blockchain node implementation, written in Rust (fast!). It is the equivalent of Ganache-cli or Hardhat Local Node.

Why Foundry

If you ask me, it just makes more sense, right? Develop your smart contracts in Solidity, test them in Solidity, and deploy them using Solidity scripts (plus a bit of bash here and there).

With other frameworks, (which I use and really like btw, let's not be a framework maxi) you can end up writing more Javascript than Solidity. This has 3 problems:

• You need to be switching contexts often.
• You miss out on the opportunity of actually practicing your Solidity.
• If you don´t know Javascript, it doubles the learning curve. Want to be a smart contract developer? Learn Solidity AND Javascript or Python. Not very efficient.

On the other side, if you already know Javascript it may be helpful to use other frameworks that abstract a lot of details on the inner workings of blockchain. But there will be a point where you need to make complex test use cases or simply want to get better at Solidity. That is when you should head over to Foundry.

As if this was not enough, Foundry is fast. Blazing fast. With each test case running in milliseconds instead of seconds, you won't lose your day looking at the screen and seeing the test suite painfully and sluggishly advancing.

Deploy your smart contract with Foundry

Enough with the Intro, I assume that if you are reading this you already have Foundry installed, you have a smart contract and you are ready to deploy it. Bookmark this article and use it as a cheatsheet.

Have a smart contract handy.

To keep this to the point, I have prepared a simple Alien-themed NFT contract as part of the Road to Web3 course made by the Alchemy team (check it out).

You can see the full code here.

Prepare a basic deployment script.

Foundry lets you prepare a script for deployment similar to the one you would prepare on Hardhat, but written in Solidity instead. Under the folder script create a file like deployScript.s.sol. This is a minimal example of what should go inside the script:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.13;

import "forge-std/Script.sol";
import "../src/CryptoAlien.sol"; //Your smart contract goes here

contract NftDeploy is Script {
    function setUp() public {}

    function run() public {
        vm.broadcast();

        CryptoAlien nft = new CryptoAlien();

        vm.stopBroadcast();
    }
}

Important to note

1. The name of the contract is not important, but having the run() function is essential.
2. vm.broadcast() is a cheatcode to record calls and send the transactions to the actual blockchain.
3. Any constructor arguments would go inside the new CryptoAlien("name", "symbol") object.

Deploy locally to Anvil

First, run anvil in your shell.

You will need to get one of the 10 private keys that Anvil creates for you. Store it in a .env file (not essential, but it is nice to do things right even in localhost) and run source .env in your Bash shell. to import the .env parameters as environment variables. If it doesn't work, head over the Troubleshooting area.

forge script script/nftDeploy.s.sol:NftDeploy --fork-url http://localhost:8545  --private-key $PRIVATE_KEY0 --broadcast

If everything went well you will see a message like this. Congrats!

Deploy to any network.

Deploying to an arbitrary network is almost the same as before. You don´t need to run Anvil and you will substitute http:localhost:8545 for a public RPC on the network you want to deploy.

In our case, we will deploy to the Goerli testnet and in the same command, we will be submitting the contract´s bytecode for verification on Etherscan so you will also need to have your Etherscan API key in the .env file.

source .env

forge script script/nftDeploy.s.sol:NftDeploy --rpc-url $GOERLI_RPC_URL  --private-key $PRIVATE_KEY --broadcast --verify --etherscan-api-key $ETHERSCAN_KEY -vvvv

And that`s it! Here is the link for our deployed and verified contract.

Bonus: troubleshooting

Solidity plugin and Remappings. If you are using the Solidity extension in VS Code, chances are the remapping in the imports are not working well for you. The quick solution is to create a remappings.txt in the root of your project, and then copy all the remappings to that file, either from your foundry.toml file or using forge remappings > remappings.txt if you are using Foundry´s default remappings.

.env files If you are like me and not THAT familiar with Bash, you may find that running source .env gives you an unexpected "Command not Found" error. If this happens make sure that your .env file has this structure on all its elements KEY="VALUE" with no whitespaces anywhere and value properly quoted.

Sources

• Book of Foundry
• Full Example for NFT deployment, Book of Foundry
• Road to Web3, week 1