DEV Community: Lucas Costa

Introducing Web3-Hooks

Lucas Costa — Fri, 07 Nov 2025 22:46:56 +0000

For several years, I have been working on Blockchain projects, and for most of them, my library choice is React, because React is usually the best architectural decision for these projects. The most common (and more repetitive) features are those such as sending transactions, reading smart contract functionalities, and keeping UIs synchronized with on-chain data. It has been great working with available blockchain/web3 libraries — but every new dApp meant re-implementing the same patterns: request/response typing, cache keys, polling vs. subscriptions, chain switching, and error boundaries. I kept wishing there was a lightweight, adapter-agnostic library that gave me the primitives and opinions I needed, without locking me into a single provider stack.

So I decided to build Web3-Hooks.

The goal with Web3-Hooks is to provide a modular React hooks library for Web3 that cleanly separates concerns. You can swap transports and providers (e.g., Viem, Ethers, custom JSON-RPC), keep React-specific concerns in React, and scale your codebase without coupling every component to a specific SDK.

Why another Hooks library?

Adapter freedom. Many libraries bundle wallet connectors, transport, and React state in one box. That’s great when you want batteries included, but it can create problems for teams who need to mix & match RPCs (Alchemy/Infura/self-hosted), add custom middleware (retries, tracing), or target non-EVM chains later.
Predictable caching. Reads in dApps are perfect for TanStack Query (React Query): cache keys, stale times, SSR awareness, and deduplication eliminate flicker and wasted requests.
Typed flows end-to-end. Strong typing across JSON-RPC requests, hook signatures, and responses reduces “unknown hex” and any drift, especially with BigInt and 0x-prefixed data.

Architecture

Web3-Hooks ships as three composable layers:

1) @web3-hooks/core — the Base Layer (Framework-agnostic)

A tiny set of types, interfaces, and utilities that describe how a Web3 client performs requests. No React here.
Defines a Web3Client interface (request, subscribe?, chainId?, etc.)
Shapes for requests/responses and utilities for creating deterministic query keys
Intentionally unopinionated about transport—it can be JSON-RPC over HTTPS, a WebSocket, or something custom

Think of core as the protocol your app speaks to the chain, independent of React.

2) @web3-hooks/adapter-evm-viem — the EVM Adapter (Viem-powered)

A small adapter that implements the core interface using Viem. It:

Bridges core to Viem’s publicClient/walletClient
Normalizes hex, numbers, and BigInts
Provides EVM-specific actions (e.g., eth_chainId, eth_getBalance, log filters)

Swap this adapter out for others (E.g., Ethers, Solana, Starknet) later without touching your React code.

3) @web3-hooks/react — the React Layer (TanStack Query inside)

The React package exposes hooks (e.g., useBlockNumber, useBalance, useLogs) and a Web3Provider that injects your client into context, then leverages TanStack Query to cache/dedupe requests, manage refetching intervals, and provide optimistic UI patterns for writes.

React code depends only on the core contracts and query semantics. The actual RPC “how” is an adapter concern.

Design Principles

Small, sharp interfaces. Each layer does one thing well.
Predictable cache keys. JSON-stable query keys ensure deduplication across components.
Zero UI opinions. Bring your own design system (or none).
Escape hatches. Drop to raw RPC when needed. Nothing prevents you from calling custom methods.

Quick Start (Preset EVM)

If you want everything wired for an EVM dApp, use your preset bundle (or wire the three packages manually).

pnpm add @web3-hooks/react @web3-hooks/core @web3-hooks/adapter-evm-viem @tanstack/react-query viem react react-dom

// app root (Next.js or CRA)
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { Web3Provider } from '@web3-hooks/react'
import { createClient } from '@web3-hooks/core'
import { viemAdapter } from '@web3-hooks/adapter-evm-viem'
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const queryClient = new QueryClient()

const client = createClient(
  viemAdapter({
    publicClient: createPublicClient({
      chain: mainnet,
      transport: http('https://ethereum.publicnode.com')
    })
  })
)

export default function App({ children }) {
  return (
    <QueryClientProvider client={queryClient}>
      <Web3Provider client={client}>
        {children}
      </Web3Provider>
    </QueryClientProvider>
  )
}

Read the chain data with hooks:

import { useBlockNumber, useBalance } from '@web3-hooks/react'

export function Dashboard({ address }: { address: `0x${string}` }) {
  const { data: blockNumber } = useBlockNumber({ refetchInterval: 4_000 })
  const { data: balance } = useBalance({ address, unit: 'ether' })

  return (
    <div>
      <p>Block: {blockNumber ?? '—'}</p>
      <p>Balance: {balance ?? '—'} ETH</p>
    </div>
  )
}

Under the hood, each hook constructs stable query keys (e.g., ['blockNumber', chainId]) and leverages React Query for caching/deduplication.

How It Works (Deep Dive)

Component calls hook → useBlockNumber({ chainId })
Hook builds a deterministic query key and hands a queryFn to TanStack Query
Query function calls client.request({ method: 'eth_blockNumber', params: [] })
The adapter (e.g., Viem) executes the request (HTTP/WebSocket)
The core layer normalizes/validates the response (hex → BigInt/number/string as configured)
React Query caches the result and dedupes concurrent calls
Refetching is handled by stale times, visibility focus, or explicit refetchInterval

For writes:

A hook (e.g., useSendTransaction) calls walletClient.sendTransaction(...)
You can optimistically update UI or invalidate queries on receipt Errors bubble through React Query’s error states/error boundaries

SSR & Next.js: Because TanStack Query plays well with SSR, you can prefetch critical reads on the server (where appropriate), and hydrate on the client for instant UI.

Where It Fits Among Other Tools

Viem — a modern, typed, EVM toolkit. web3-hooks uses it via the EVM adapter today.
Ethers.js — the classic EVM library. An Ethers adapter could be added; the React layer wouldn’t change.
wagmi — a feature-rich React EVM library with connectors and actions. If you want more control over transport/adapters (or you’re mixing chains), web3-hooks gives you a lean alternative.
The Graph — for indexed data and historical queries. web3-hooks focuses on live RPC reads/writes; combine them when you need richer analytics/history.
TypeChain — generate TypeScript typings for contract ABIs. Works great alongside web3-hooks for type-safe contract calls.

Roadmap

Additional adapters: Ethers, WS transports, non-EVM chains (Solana/Starknet)
More hooks: useFeeHistory, useEnsName, useTokenList, useBundlePrice
Event streams via WebSocket subscriptions with backoff/retry
DevTools integ ration (React Query + request tracing)

If you’ve use cases (rollups, L2 gas oracles, MEV-resistant patterns), I’d love to hear about them.

Contributing

Issues/Ideas: Open a GitHub issue describing the use-case and API shape you expect
PRs: Add tests, update docs, and keep adapters small and isolated
Discussions: Email/LinkedIn/PR threads

If you maintain infra at Alchemy/Infura or work on chain clients, I’d love input on transport ergonomics and best-practice retries/backoff.

References & Further Reading

TanStack Query (React Query): caching, dedupe, stale time, SSR hydration — https://tanstack.com/query/latest
Viem: typed EVM toolkit (clients, actions, transports) — https://viem.sh/
ethers.js: mature EVM library (v6 docs) — https://docs.ethers.org/v6/
The Graph: Subgraphs & Substreams for indexed on-chain data — https://thegraph.com/docs/
EIP-1193: Ethereum Provider API (standard) — https://eips.ethereum.org/EIPS/eip-1193
JSON-RPC 2.0: transport/specification — https://www.jsonrpc.org/specification

How I’m Building a Permanent Blockchain Archive - Part 2

Lucas Costa — Fri, 18 Jul 2025 02:11:17 +0000

AI Moderation and Sensitive Data Protection

If it’s forever, it better be safe.

In Part 1, I introduced Immutable Notes, a decentralized archive where people can mint messages or personal notes as on-chain SVG NFTs — no IPFS, no servers, no silent failures. The entire visual output is generated in SVG and stored fully on-chain.

But blockchain permanence comes with responsibility.
If you let people write anything to the chain, you risk storing:

NSFW or hateful content

Personally identifiable information (PII) like emails, phone numbers, and passwords

Sensitive data they might later regret putting on a permanent ledger

So in Part 2, I focused on making minting safe by design, using a combination of AI moderation and custom validation logic.

The Moderation Stack
I added a two-layer protection system:

1. OpenAI Moderation API
Before minting, the user’s message is sent to the OpenAI Moderation endpoint, which checks the text for violations like:

Hate or harassment
Sexual or violent content
Self-harm
Criminal activity

It returns a simple flagged: true/false response — fast, accurate, and cheap ($0.002 per 1,000 messages).

2. PII Detection with Regex
OpenAI’s moderation doesn’t catch everything, so I wrote a set of custom filters to block:

Emails: lucas@example.com
Phone numbers: (555) 123-4567
Card numbers: 4242 4242 4242 4242
Passwords: password=secret123

function containsSensitiveInfo(text: string): string | null {
  const emailRegex = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i;
  const phoneRegex = /\b(\+?\d{1,3}[-.\s]?)?\(?\d{2,4}\)?[-.\s]?\d{3,5}[-.\s]?\d{4}\b/;
  const cardRegex = /\b(?:\d[ -]*?){13,16}\b/;
  const passwordRegex = /(?:password|passwd|pass)\s*[:=]\s*\S+/i;

  if (emailRegex.test(text)) return "email address";
  if (phoneRegex.test(text)) return "phone number";
  if (cardRegex.test(text)) return "credit card number";
  if (passwordRegex.test(text)) return "password";

  return null;
}

If any of those patterns are detected, the user gets an alert and can’t proceed to minting.

Sample Workflow
The user types their message into the NftSvgEditor.

On “Submit”, the app:

Runs PII checks
Sends the message to /api/moderate
Receives moderation response from OpenAI

If the message is flagged or contains PII, the app shows a helpful alert and blocks minting.

Built With

Next.js 15.3.5 App Router (Edge-ready)
React 19 with server/client components
OpenAI Moderation API
Regex-based validation for common PII patterns
Custom Alert component for UX feedback

Why It Matters
I believe blockchain permanence requires thoughtful constraints. Immutable Notes isn't just a place to write — it’s a place to preserve something that should be preserved.

Letting harmful, illegal, or personal data into the system would contradict that mission, so these safeguards are essential.

Coming in Part 3…
Next up, I’ll show how I’m:

Storing the SHA-256 hash of the message for on-chain verification
Using that to ensure messages aren’t altered after moderation
Making the smart contract enforce this safety — not just the frontend

Want to Collaborate?
GitHub: github.com/lucas-costa/immutable-notes
Feedback and pull requests are welcome.

If you’ve built something similar or have ideas on improving this moderation pipeline, I’d love to hear from you.

Let’s build something worth remembering — and safe enough to last forever.

How I’m Building a Permanent Blockchain Archive - Part 1

Lucas Costa — Wed, 16 Jul 2025 00:39:18 +0000

Rendering Immutable SVG NFTs

“If the blockchain survives, so will these messages.”

I’m building a dApp called Immutable Notes — a decentralized archive where people can mint anonymous messages, thoughts, or notes as NFTs that will live on-chain forever.

Whether it’s a memory, a thought you can’t afford to lose, or even just a timestamped idea — this project aims to preserve what matters most, permanently, without relying on platforms, servers, or external storage.

To do that, I had to solve one key problem:

How do you create NFTs that don’t rely on IPFS or off-chain storage?
Most NFTs today depend on IPFS or Arweave to store the actual media or metadata. That works — until:

Someone unpins the file
Gateways go offline
Metadata links rot silently

That breaks the very idea of “immutability.”

Instead, I’m storing everything on-chain using SVG, a format that’s:

Lightweight
Browser-native
Human-readable
Fully expressible in plain text

SVG can be stored directly in the smart contract and displayed without depending on any external service.

If Ethereum lives, the message lives.

The Solution: SVG
SVG (Scalable Vector Graphics) is ideal for this use case:

It’s just text (XML) — so it fits naturally in smart contracts
It’s visual — so each note becomes a piece of generative art
It supports styling — colors, fonts, layout
It renders everywhere — no plugins, no IPFS dependency

Each Immutable Note is minted as a fully self-contained SVG NFT: the layout, colors, timestamp, and user message are all stored directly inside the blockchain.

Example: A component for editing the SVG note

This is base64-encoded and embedded into the smart contract’s tokenURI() return — making the NFT truly on-chain and self-reliant.

How It Works: The SVG Editor Component
To let users create and preview their NFTs before minting, I built a React component called NftSvgEditor. It handles everything from text layout to real-time rendering.

Here’s what it does:

1 - Text Wrapping with Pixel Precision
SVG doesn’t support native word wrapping, so I wrote a custom function called measureSegments() that uses a hidden canvas to split text into properly wrapped lines:

const measure = (str: string) => context.measureText(str).width;

const splitByWidth = (line: string) => {
  // Binary search to find the longest substring that fits
  while (start < line.length) {
      let low = start;
      let high = line.length;

      while (low < high) {
        const mid = Math.floor((low + high + 1) / 2);
        const slice = line.slice(start, mid);
        if (measure(slice) <= maxWidth) {
          low = mid;
        } else {
          high = mid - 1;
        }
      }

      const segment = line.slice(start, low);
      result.push(segment || '\u00A0');
      start = low;
    }
}

This ensures the text never overflows the boundaries of the SVG.

2 - Real-Time SVG Rendering
The component overlays a transparent <textarea> over the SVG so users can type naturally, while the text is rendered as elements below:

<text x="20" y={60} fontSize="18px">
  {segments.map((segment, i) => (
    <tspan key={i} x="20" dy={i === 0 ? '0' : '1.2em'}>
      {segment}
    </tspan>
  ))}
</text>

It also adds:

A “To:” field for an optional recipient label
A timestamp that updates in real time
A background color chosen by the user

All of this lives inside a fixed-size SVG container (320x360px) designed for on-chain rendering consistency.

3 - Live Preview = Trust
Users can see exactly what they’re minting before they hit the blockchain. No surprises, no broken layouts. What you see is what you mint — forever.

Why This Matters
We talk a lot about “immutability” in blockchain — but most NFTs aren’t truly immutable. They rely on links to files stored off-chain.

By contrast, Immutable Notes:

Stores the entire NFT in the contract
Has no reliance on IPFS or Arweave
Can’t be changed, erased, or hidden

This is true permanence — the kind worth using when the message matters.

Open Source & In Progress
You can view the source code (including the NftSvgEditor component) here:

🔗 GitHub: github.com/lucas-costa/immutable-notes

The project is still in early development — I’d love feedback, ideas, and even pull requests from other devs interested in on-chain data, SVG rendering, or Web3 UX.

What’s Next (Part 2 Preview)
In Part 2, I’ll walk through how I’m using OpenAI’s Moderation API to prevent harmful or NSFW content from ever making it on-chain — and how I enforce that on-chain using hash validation to prevent bypassing the moderation step.

Stay tuned — and follow the journey as I continue building Immutable Notes in public.

Want to Talk?

What would you optimize in the SVG rendering or layout system?
Have you worked on fully on-chain NFTs? What lessons did you learn?
Do you think text-based NFTs hav e a future in digital memory?

Let’s chat in the comments — or connect with me on LinkedIn!