From 449b960ffa94a380d9f04a038ee52fadbec83fc9 Mon Sep 17 00:00:00 2001 From: Pablo Alayeto <55535804+Pabl0cks@users.noreply.github.com> Date: Tue, 5 Aug 2025 19:22:50 +0200 Subject: [PATCH 1/6] Add initial version of read events recipe --- docs/recipes/ReadEventsFromContract.md | 208 +++++++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 docs/recipes/ReadEventsFromContract.md diff --git a/docs/recipes/ReadEventsFromContract.md b/docs/recipes/ReadEventsFromContract.md new file mode 100644 index 0000000..d019d6c --- /dev/null +++ b/docs/recipes/ReadEventsFromContract.md @@ -0,0 +1,208 @@ +--- +sidebar_position: 6 +title: Read and Display Contract Events +description: Learn how to fetch and display smart contract events in your dApp. +--- + +# Read and Display Contract Events + +This recipe shows how to fetch and display events emitted by your smart contract using the `useScaffoldEventHistory` hook. You'll learn how to efficiently query, parse, and render contract events in your UI, and see how to extend your project with production-grade event indexing using Subgraph or Ponder. + +
+Here is the full code, which we will be implementing in the guide below: + +```tsx title="components/ContractEvents.tsx" +import * as React from "react"; +import { useScaffoldEventHistory } from "~~/hooks/scaffold-eth"; + +export const ContractEvents = () => { + const { + data: events, + isLoading, + error, + } = useScaffoldEventHistory({ + contractName: "YourContract", + eventName: "GreetingChange", + // fromBlock defaults to deployedOnBlock if available (block number of the contract deployment) + watch: true, + blockData: true, + }); + + if (isLoading) return
Loading events...
; + if (error) return
Error loading events: {error.message}
; + + return ( +
+

GreetingChange Events

+ +
+ ); +}; +``` + +
+ +## Implementation Guide + +### Step 1: Create a Component + +Create a new file, e.g., `components/ContractEvents.tsx`, in your project. + +```tsx title="components/ContractEvents.tsx" +import * as React from "react"; + +export const ContractEvents = () => { + return
Contract Events will be displayed here.
; +}; +``` + +### Step 2: Use the `useScaffoldEventHistory` Hook + +Import and use the `useScaffoldEventHistory` hook to fetch events. By default, the hook will start fetching from the block the contract was deployed (`deployedOnBlock`), so you don’t need to specify `fromBlock` unless you want to override it. + +```tsx title="components/ContractEvents.tsx" +import * as React from "react"; +// highlight-start +import { useScaffoldEventHistory } from "~~/hooks/scaffold-eth"; +// highlight-end + +export const ContractEvents = () => { + // highlight-start + const { + data: events, + isLoading, + error, + } = useScaffoldEventHistory({ + contractName: "YourContract", + eventName: "GreetingChange", + // fromBlock defaults to deployedOnBlock if available (block number of the contract deployment) + watch: true, + blockData: true, + }); + // highlight-end + return
Contract Events will be displayed here.
; +}; +``` + +### Step 3: Handle Loading and Error States + +Show feedback to the user while events are loading or if an error occurs. + +```tsx title="components/ContractEvents.tsx" +import * as React from "react"; +import { useScaffoldEventHistory } from "~~/hooks/scaffold-eth"; + +export const ContractEvents = () => { + const { + data: events, + isLoading, + error, + } = useScaffoldEventHistory({ + contractName: "YourContract", + eventName: "GreetingChange", + watch: true, + blockData: true, + }); + // highlight-start + if (isLoading) return
Loading events...
; + if (error) return
Error loading events: {error.message}
; + // highlight-end + return
Contract Events will be displayed here.
; +}; +``` + +### Step 4: Display the Events + +Render the events in your UI. Adjust the argument names to match your contract's event signature. + +```tsx title="components/ContractEvents.tsx" +import * as React from "react"; +import { useScaffoldEventHistory } from "~~/hooks/scaffold-eth"; + +export const ContractEvents = () => { + const { + data: events, + isLoading, + error, + } = useScaffoldEventHistory({ + contractName: "YourContract", + eventName: "GreetingChange", + watch: true, + blockData: true, + }); + if (isLoading) return
Loading events...
; + if (error) return
Error loading events: {error.message}
; + // highlight-start + return ( +
+

GreetingChange Events

+ +
+ ); + // highlight-end +}; +``` + +## How `fromBlock` and `deployedOnBlock` Work + +The `useScaffoldEventHistory` hook uses the `fromBlock` parameter to determine where to start fetching events from the blockchain. + +- **Default behavior:** + If you do not specify `fromBlock`, the hook will automatically start fetching events from the block where your contract was deployed. This block number is stored as `deployedOnBlock` in your deployed contracts metadata. This makes event queries more efficient, as it avoids scanning blocks before your contract existed. + +- **Customizing `fromBlock`:** + You can override this behavior by explicitly setting the `fromBlock` parameter in the hook options. For example, you might want to fetch events from a more recent block, or from the very beginning of the chain (`fromBlock: 0n`), depending on your use case. + +**Example:** + +```tsx title="components/ContractEvents.tsx" +useScaffoldEventHistory({ + contractName: "YourContract", + eventName: "GreetingChange", + fromBlock: 0n, // fetch from the genesis block (not recommended unless needed) + watch: true, + blockData: true, +}); +``` + +## Displaying Event Arguments + +The argument names (`greetingSetter`, `newGreeting`, `premium`, `value`, etc.) should match those defined in your contract’s event. Adjust them as needed for your use case. + +## Next Steps + +- **Subgraph (The Graph):** For advanced, production-grade event indexing and GraphQL querying, use the [Subgraph extension](https://github.com/scaffold-eth/create-eth-extensions/tree/subgraph). Install with: + + ```sh + npx create-eth@latest -e subgraph + ``` + + See the extension docs for setup and deployment. + +- **Ponder:** For a TypeScript-first, flexible event indexer suitable for both local development and production, use the [Ponder extension](https://github.com/scaffold-eth/create-eth-extensions/tree/ponder). Install with: + ```sh + npx create-eth@latest -e ponder + ``` + See the extension docs for configuration and usage. + +Both tools let you efficiently index and query contract events at scale. Choose the one that best fits your stack and workflow. From cf4ca75521452c7d307df340f0da98f16fca4c92 Mon Sep 17 00:00:00 2001 From: Pablo Alayeto <55535804+Pabl0cks@users.noreply.github.com> Date: Sun, 10 Aug 2025 01:33:56 +0200 Subject: [PATCH 2/6] Recipe tweaks --- docs/recipes/ReadEventsFromContract.md | 42 +++++--------------------- 1 file changed, 8 insertions(+), 34 deletions(-) diff --git a/docs/recipes/ReadEventsFromContract.md b/docs/recipes/ReadEventsFromContract.md index d019d6c..6014f23 100644 --- a/docs/recipes/ReadEventsFromContract.md +++ b/docs/recipes/ReadEventsFromContract.md @@ -1,12 +1,12 @@ --- sidebar_position: 6 -title: Read and Display Contract Events +title: Read and display contract events description: Learn how to fetch and display smart contract events in your dApp. --- # Read and Display Contract Events -This recipe shows how to fetch and display events emitted by your smart contract using the `useScaffoldEventHistory` hook. You'll learn how to efficiently query, parse, and render contract events in your UI, and see how to extend your project with production-grade event indexing using Subgraph or Ponder. +This recipe shows how to fetch and display events emitted by your smart contract using the [useScaffoldEventHistory](/hooks/useScaffoldEventHistory) hook. You'll learn how to efficiently query, parse, and render contract events in your UI, and see how to extend your project with production-grade event indexing using Subgraph or Ponder.
Here is the full code, which we will be implementing in the guide below: @@ -36,7 +36,7 @@ export const ContractEvents = () => {

GreetingChange Events

-## Implementation Guide +## Implementation guide -### Step 1: Create a Component +### Step 1: Create a new Component -Create a new file, e.g., `components/ContractEvents.tsx`, in your project. +Create a new component in the `components` folder of your application. ```tsx title="components/ContractEvents.tsx" import * as React from "react"; @@ -66,7 +66,7 @@ export const ContractEvents = () => { }; ``` -### Step 2: Use the `useScaffoldEventHistory` Hook +### Step 2: Initialize the `useScaffoldEventHistory` hook Import and use the `useScaffoldEventHistory` hook to fetch events. By default, the hook will start fetching from the block the contract was deployed (`deployedOnBlock`), so you don’t need to specify `fromBlock` unless you want to override it. @@ -148,7 +148,7 @@ export const ContractEvents = () => {

GreetingChange Events

); - // highlight-end }; ``` From 74a49d4533d7b23e20a2408855bfa1bfb473b1ad Mon Sep 17 00:00:00 2001 From: Pablo Alayeto <55535804+Pabl0cks@users.noreply.github.com> Date: Tue, 12 Aug 2025 09:31:47 +0200 Subject: [PATCH 4/6] Add listen --- docs/recipes/ReadEventsFromContract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/recipes/ReadEventsFromContract.md b/docs/recipes/ReadEventsFromContract.md index 05a128a..1803b8e 100644 --- a/docs/recipes/ReadEventsFromContract.md +++ b/docs/recipes/ReadEventsFromContract.md @@ -6,7 +6,7 @@ description: Learn how to fetch and display smart contract events in your dApp. # Read and display contract events -This recipe shows how to fetch and display events emitted by your smart contract using the [useScaffoldEventHistory](/hooks/useScaffoldEventHistory) hook. You'll learn how to efficiently query, parse, and render contract events in your UI, and see how to extend your project with production-grade event indexing using Subgraph or Ponder. +This recipe shows how to fetch and display events emitted by your smart contract using the [useScaffoldEventHistory](/hooks/useScaffoldEventHistory) hook. You'll learn how to efficiently query, listen, parse, and render contract events in your UI, and see how to extend your project with production-grade event indexing using Subgraph or Ponder.
Here is the full code, which we will be implementing in the guide below: From 4b275f9eb0e864c376e4e144a2c08ff4f8403b0d Mon Sep 17 00:00:00 2001 From: Pablo Alayeto <55535804+Pabl0cks@users.noreply.github.com> Date: Tue, 12 Aug 2025 09:37:14 +0200 Subject: [PATCH 5/6] Add comment to watch parameter --- docs/recipes/ReadEventsFromContract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/recipes/ReadEventsFromContract.md b/docs/recipes/ReadEventsFromContract.md index 1803b8e..f165b2d 100644 --- a/docs/recipes/ReadEventsFromContract.md +++ b/docs/recipes/ReadEventsFromContract.md @@ -24,7 +24,7 @@ export const ContractEvents = () => { contractName: "YourContract", eventName: "GreetingChange", // fromBlock defaults to deployedOnBlock if available (block number of the contract deployment) - watch: true, + watch: true, // Defaults to false. Set to true to listen for new events in real-time blockData: true, }); From 4d5c3cb589356745388b9ac274b65c9ba2d7bab2 Mon Sep 17 00:00:00 2001 From: Pablo Alayeto <55535804+Pabl0cks@users.noreply.github.com> Date: Wed, 20 Aug 2025 12:23:53 +0200 Subject: [PATCH 6/6] Add warning in read events recipe and hook --- docs/hooks/useScaffoldEventHistory.md | 4 ++++ docs/recipes/ReadEventsFromContract.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/hooks/useScaffoldEventHistory.md b/docs/hooks/useScaffoldEventHistory.md index 1526bbe..2492ac5 100644 --- a/docs/hooks/useScaffoldEventHistory.md +++ b/docs/hooks/useScaffoldEventHistory.md @@ -6,6 +6,10 @@ sidebar_position: 4 Use this hook to retrieve historical event logs for your smart contract, providing past activity data, with the option to watch for new events. +:::caution Production Usage +This hook is primarily intended for **local development environments** (hardhat/anvil chains). In production, (mainnet or L2 chains with short block times), it can cause performance issues and excessive RPC usage due to its use of the `getLogs` method. For production applications, consider using dedicated indexing solutions like [The Graph](https://thegraph.com/) or [Ponder](https://ponder.sh/) for efficient event querying. +:::caution + ```ts const { data: events, diff --git a/docs/recipes/ReadEventsFromContract.md b/docs/recipes/ReadEventsFromContract.md index f165b2d..66e29f2 100644 --- a/docs/recipes/ReadEventsFromContract.md +++ b/docs/recipes/ReadEventsFromContract.md @@ -8,6 +8,10 @@ description: Learn how to fetch and display smart contract events in your dApp. This recipe shows how to fetch and display events emitted by your smart contract using the [useScaffoldEventHistory](/hooks/useScaffoldEventHistory) hook. You'll learn how to efficiently query, listen, parse, and render contract events in your UI, and see how to extend your project with production-grade event indexing using Subgraph or Ponder. +:::caution Performance Considerations +The `useScaffoldEventHistory` hook is primarily designed for **local development** (hardhat/anvil chains). Using it in production environments(mainnet or L2 chains), can cause performance issues and excessive RPC usage. For production applications, consider using specialized indexing solutions like [Subgraph](#next-steps) or [Ponder](#next-steps) instead. +:::caution +
Here is the full code, which we will be implementing in the guide below: