DEV Community: Pavel Espitia

Function Calling with Ollama: Make Your Local LLM Run Real Tools

Pavel Espitia — Fri, 01 May 2026 15:06:05 +0000

Function Calling with Ollama: Make Your Local LLM Run Real Tools

Most Ollama tutorials end at chat completion. The interesting stuff starts when the model can call your code.

Function calling is the protocol that lets an LLM say "I want to call getWeather(city: 'Bogotá')" instead of trying to fake the answer from training data. Cloud models like GPT and Claude have had it for over a year. Ollama supports it natively for compatible models. Almost nobody talks about it.

This post walks through a complete working example. End to end, two hundred lines of TypeScript.

Why function calling matters

Without it, your LLM is a closed system. It only knows what's in its training data. With it, the LLM becomes a planner that calls real APIs, queries databases, runs calculations, hits your code. That's the difference between "interesting demo" and "production-grade agent."

The trick: the LLM doesn't actually call your function. It returns a structured request, and your code decides whether to execute it. Always.

Which Ollama models support it

As of 2026:

qwen2.5:7b and larger — strong support
llama3.1:8b and larger — strong support
mistral-nemo — strong support
qwen2.5-coder:7b — works for technical functions
llama3.2:3b — limited, expect quirks

Pull the model:

ollama pull qwen2.5:7b

The minimum example

Define a tool. The schema follows the JSON Schema format the OpenAI API uses, so any existing tool you have works without translation.

const tools = [
  {
    type: "function",
    function: {
      name: "get_weather",
      description: "Get the current weather for a city",
      parameters: {
        type: "object",
        properties: {
          city: { type: "string", description: "City name" },
          unit: {
            type: "string",
            enum: ["celsius", "fahrenheit"],
            description: "Temperature unit",
          },
        },
        required: ["city"],
      },
    },
  },
];

Call Ollama with the tools attached:

const response = await fetch("http://localhost:11434/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "qwen2.5:7b",
    messages: [{ role: "user", content: "What's the weather in Bogotá?" }],
    tools,
    tool_choice: "auto",
  }),
});

const json = await response.json();
const message = json.choices[0].message;
console.log(message.tool_calls);

The response looks like this:

{
  "tool_calls": [
    {
      "id": "call_1",
      "type": "function",
      "function": {
        "name": "get_weather",
        "arguments": "{\"city\":\"Bogotá\",\"unit\":\"celsius\"}"
      }
    }
  ]
}

The model didn't fabricate a temperature. It told you exactly which function to call and with what arguments.

Closing the loop

Now your code executes the function and feeds the result back to the model so it can produce a natural-language answer.

async function getWeather(city: string, unit: string) {
  // Call your real weather API here. Returning a stub for the example.
  return { city, temperature: 19, unit, conditions: "partly cloudy" };
}

const toolCall = message.tool_calls[0];
const args = JSON.parse(toolCall.function.arguments);
const result = await getWeather(args.city, args.unit ?? "celsius");

// Send the result back to the model
const final = await fetch("http://localhost:11434/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "qwen2.5:7b",
    messages: [
      { role: "user", content: "What's the weather in Bogotá?" },
      message,
      {
        role: "tool",
        tool_call_id: toolCall.id,
        content: JSON.stringify(result),
      },
    ],
  }),
});

const finalJson = await final.json();
console.log(finalJson.choices[0].message.content);
// "The weather in Bogotá is currently 19°C and partly cloudy."

Two round trips, total. Local. Free.

Multiple tools, one prompt

Real agents use several tools. Define them all in the array; the model picks which to call.

const tools = [
  { type: "function", function: { name: "get_weather", ... } },
  { type: "function", function: { name: "search_web", ... } },
  { type: "function", function: { name: "send_email", ... } },
  { type: "function", function: { name: "query_database", ... } },
];

For "Email my team the weather forecast for tomorrow", the model will chain get_weather → send_email automatically. You get back two tool calls in the same response. Execute both, return the results, and the model produces the final summary.

Things that break, and how to handle them

The model invents argument values. Smaller models (3B and below) sometimes hallucinate fields. Defend against this with strict validation. I use Zod:

import { z } from "zod";

const WeatherArgs = z.object({
  city: z.string(),
  unit: z.enum(["celsius", "fahrenheit"]).default("celsius"),
});

const args = WeatherArgs.parse(JSON.parse(toolCall.function.arguments));

If parse throws, return the error to the model and let it retry. Surprisingly, it usually fixes itself on the second pass.

The model ignores the tool when it shouldn't. Some questions get a chat answer instead of a tool call ("What's the weather like?" without a city). Reword your prompt: "If the user asks about weather, always call get_weather. Ask the user for missing parameters before calling." Models follow this consistently.

The model calls a tool when it shouldn't. Less common but it happens. Add to the system prompt: "Only call a function if the user is asking for live data. For general questions, answer from your knowledge."

What this unlocks

You now have a local agent loop. The same pattern scales to:

File system tools — let the LLM read and write files in a sandbox.
Shell tools — execute commands and feed back the output.
Database tools — query and update your app's data.
API tools — wrap any REST endpoint as a function.

The LLM becomes the planner. Your code is the executor. Local LLMs are now legitimately useful for agent workflows, not just chat.

Next post in the series: building a local-only RAG system with Ollama, ChromaDB, and TypeScript. We'll combine retrieval with the function calling pattern from this post.

If you enjoy dissecting why systems break down, I make video case studies of historical engineering disasters at Why It Crashed — same first-principles approach, different domain. Latest: how five words on a foggy radio call killed 583 people on a runway in 1977.

Ollama vs LM Studio vs Jan: Which Local AI Runner Wins in 2026?

Pavel Espitia — Thu, 30 Apr 2026 20:30:33 +0000

Ollama vs LM Studio vs Jan: Which Local AI Runner Wins in 2026?

Three projects. Same goal: run LLMs on your laptop. Different design philosophies, very different best-fits.

I've used all three in production over the last six months. Here's an honest comparison so you don't waste a weekend picking the wrong one.

TL;DR

Ollama — best for developers who want a CLI and an HTTP API. The default for engineers.
LM Studio — best for non-developers and researchers who want a polished GUI.
Jan — best if open-source-everything matters and you want a ChatGPT-like UI you fully own.

If you're shipping code that calls a local LLM, pick Ollama. The rest of this post explains why and when the others are correct.

Installation

Ollama

curl -fsSL https://ollama.com/install.sh | sh

A single binary, runs as a background daemon, exposes a REST API on localhost:11434. Done in thirty seconds.

LM Studio

Desktop installer (.dmg / .exe / .AppImage). After install, open the app, click "Discover", search for a model, click download. GUI-first.

Jan

Desktop installer like LM Studio, but the UI is more chat-focused. After install, you import GGUF models manually or download from their model hub.

Model library

	Ollama	LM Studio	Jan
Models in registry	200+	1000+ via HuggingFace	Curated, smaller list
One-line pull	`ollama pull llama3.1`	UI search	UI search
Custom GGUF	`Modelfile` import	Drag-and-drop	File copy
Auto-quant selection	✓	Manual	Manual

Ollama's Modelfile system is the most developer-friendly way to package a model with its parameters and prompt template. It's roughly to local LLMs what Dockerfile is to containers.

LM Studio wins on raw breadth — it can run anything HuggingFace has, with manual quantisation. If you're researching obscure models, that matters.

API surface

Ollama

REST API, fully OpenAI-compatible:

const r = await fetch("http://localhost:11434/v1/chat/completions", {
  method: "POST",
  body: JSON.stringify({
    model: "qwen2.5-coder:7b",
    messages: [{ role: "user", content: "Hello" }],
    stream: true,
  }),
});

Drop-in for any OpenAI SDK by changing the base URL.

LM Studio

Also exposes an OpenAI-compatible server, but you have to start it manually from the GUI ("Local Server" tab → "Start Server"). Easier to forget.

Jan

OpenAI-compatible. Toggleable from the GUI.

If you're integrating into an existing app, all three speak the same dialect at the API layer. The difference is whether the server is a daemon (Ollama) or requires a GUI to be running (LM Studio, Jan).

Performance

I tested qwen2.5-coder:7b on a 32 GB MacBook M2 Pro. Same prompt, same temperature, same context window, three runs each, taking the median.

	Ollama	LM Studio	Jan
Tokens/sec	38	35	32
Time to first token	240 ms	280 ms	350 ms
Idle RAM	200 MB	1.4 GB	2.1 GB

Ollama is the lightest at idle because it can unload the model when not in use and reload on demand. LM Studio and Jan keep the model resident as long as the app is open.

For long-running coding sessions on a 16 GB machine, that idle-RAM difference matters. Ollama's lazy loading is the reason I run it on my older MacBook.

Where each one wins

Use Ollama if

You write code that calls local LLMs (90 percent of developers).
You want a single binary on a server, not a desktop app.
You're integrating with VS Code's Continue extension, LangChain, llama_index, or any OpenAI-compatible SDK.
You care about idle RAM.

Use LM Studio if

You want to chat with local models without writing code.
You need to test exotic models that aren't in Ollama's registry.
You like a polished UI for managing model files.
You're doing model research and need fine-grained control over quantisation.

Use Jan if

"Fully open-source, every dependency" is a hard requirement.
You want a ChatGPT-style chat UI that's yours forever, regardless of what OpenAI does.
You're building for users who want a desktop AI assistant they own, not a developer tool.

What about combining them?

This actually works. I run Ollama as my background daemon for code (Continue extension, local agents, scripts) and use LM Studio when I want to compare three models side by side on the same prompt. They don't conflict because LM Studio defaults to port 1234 and Ollama uses 11434.

You can also point LM Studio's UI at an Ollama backend if you really want — it's OpenAI-compatible. But at that point just use the Ollama CLI; the indirection isn't paying for itself.

My recommendation

Start with Ollama. It's the right default for ninety percent of developer workflows in 2026. If your needs grow into research or non-developer audiences, add LM Studio or Jan alongside. They coexist fine.

The wrong move is picking the GUI-first option because the install is friendlier, and then six months later trying to retrofit it into a programmatic pipeline. Pick the tool that matches what you'll be doing in twelve months.

Next post in this series: function calling with local models. Most Ollama tutorials skip it. We'll go through it end to end.

How to Replace GitHub Copilot with Ollama (Local AI Coding, Free Forever)

Pavel Espitia — Thu, 30 Apr 2026 20:30:32 +0000

Self-Hosted GitHub Copilot Alternative: Code with Ollama for Free

GitHub Copilot is ten dollars a month and your code goes to a third party. Both are fine until they're not. If you write proprietary code, work in a regulated industry, or just don't want to ship every keystroke to Microsoft, there's a free, local alternative that runs entirely on your laptop.

This post walks through the setup. End to end, twenty minutes.

The stack

Ollama — the local model runner.
Continue.dev — a VS Code extension that talks to Ollama.
A code-focused LLM — qwen2.5-coder:7b for speed, qwen2.5-coder:32b for quality.

That's it. No API keys, no monthly bill, no telemetry.

Why this actually works in 2026

Local code models have closed the gap. Qwen2.5-Coder 32B benchmarks within five points of Claude Sonnet on HumanEval. The 7B variant is fast enough to autocomplete in real time on a 16 GB MacBook M2. DeepSeek-Coder-V2 and CodeLlama 70B are also strong choices if you have more RAM.

The key shift: you no longer need a cloud GPU farm to get usable AI assistance.

Install Ollama

# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows: download the installer from ollama.com

Pull the code model:

ollama pull qwen2.5-coder:7b      # 4 GB, fast
ollama pull qwen2.5-coder:32b     # 19 GB, slower but smarter

Verify it's running:

ollama run qwen2.5-coder:7b "write a TypeScript debounce function"

It should respond in one to three seconds.

Install Continue

In VS Code, install the extension continue.continue.

Open Continue's settings (Cmd+L on macOS, then click the gear icon) and edit your ~/.continue/config.json to point at Ollama:

{
  "models": [
    {
      "title": "Qwen 2.5 Coder 7B",
      "provider": "ollama",
      "model": "qwen2.5-coder:7b",
      "apiBase": "http://localhost:11434"
    }
  ],
  "tabAutocompleteModel": {
    "title": "Tab Autocomplete",
    "provider": "ollama",
    "model": "qwen2.5-coder:7b",
    "apiBase": "http://localhost:11434"
  },
  "embeddingsProvider": {
    "provider": "ollama",
    "model": "nomic-embed-text"
  }
}

Pull the embedding model so codebase indexing works:

ollama pull nomic-embed-text

Reload VS Code. Open any TypeScript file and start typing. You should see grey ghost-text suggestions, just like Copilot.

Test it like a real user

Hit Cmd+I and ask:

Write a function that debounces a callback. Use TypeScript generics.

You should see a response in two to four seconds. The function should be correct on first attempt.

For inline edits, select code and hit Cmd+I:

Refactor this to use early returns.

The diff appears inline. Accept or reject with one keystroke.

Latency comparison

Action	Cloud Copilot	Local Ollama (7B)	Local Ollama (32B)
Tab autocomplete	200-400 ms	300-600 ms	1.5-3 s
Inline edit	1-2 s	2-4 s	8-15 s
Multi-file refactor	3-5 s	5-10 s	20-40 s

The 7B model is the right default for most flows. Bring out the 32B model when you're doing architecture work or asking for explanations.

What you actually give up

I don't want to oversell this. The 7B local model misses subtle bugs that Copilot's frontier model catches — null-check edge cases, Promise.all vs Promise.allSettled distinctions, that kind of thing. Multi-file context is also weaker. Continue indexes your repo locally, but it's not at the level of Copilot's whole-workspace awareness.

For senior engineers writing performance-sensitive code at the limit of the language, Copilot is still better. For everyone else doing 80 percent of normal day-to-day work, local Ollama is indistinguishable in quality and zero in cost.

What you save

A hundred and twenty dollars a year, plus the value of your code never leaving your machine. If you ship in a regulated industry where data sovereignty matters — health, finance, defense, legal — this is the difference between "no AI assistance allowed" and "AI assistance with a full local audit trail." That trade rarely makes sense at the cost of a single subscription.

What's next

If this works for you, the next post in this series goes deeper: comparing Ollama against LM Studio and Jan, the two other serious local AI runners. Different tradeoffs, different best-fits. Worth knowing before you commit a tool to your daily flow.

For now, you have a working local Copilot. Happy not-paying.

Solidity vs Vyper: Security Differences Every Auditor Should Know

Pavel Espitia — Thu, 30 Apr 2026 15:06:11 +0000

When I started building spectr-ai, one of the first decisions was which EVM languages to support. Solidity was obvious — it powers over 90% of deployed contracts. But Vyper kept showing up in DeFi protocols I was auditing, and the security differences between the two languages are more significant than most developers realize.

This post breaks down where each language helps (and hurts) your contract's security posture, with concrete code examples.

Solidity's Footgun Collection

Solidity gives you enormous power and enormous rope to hang yourself with. Here are the features that keep auditors employed.

delegatecall

delegatecall executes another contract's code in the context of the calling contract. This means the called contract can modify the caller's storage. It's the backbone of upgradeable proxies — and the source of hundreds of millions in losses.

// Dangerous: anyone can call this and change contract storage
contract Vulnerable {
    address public owner;

    function execute(address target, bytes memory data) public {
        (bool success, ) = target.delegatecall(data);
        require(success);
    }
}

An attacker deploys a malicious contract that sets owner to their address, then calls execute pointing to it. Game over.

tx.origin

tx.origin returns the original external account that initiated the transaction, not the immediate caller. This breaks when contracts call other contracts.

// Vulnerable to phishing attacks
function withdraw() public {
    require(tx.origin == owner, "Not owner");
    payable(msg.sender).transfer(address(this).balance);
}

If the owner interacts with a malicious contract, that contract can call withdraw and the tx.origin check passes because the owner initiated the transaction chain.

Inline Assembly

Solidity's assembly blocks give you raw EVM access. No type safety, no overflow checks, no guard rails.

function unsafeAdd(uint256 a, uint256 b) public pure returns (uint256) {
    assembly {
        mstore(0x0, add(a, b))  // No overflow check
        return(0x0, 32)
    }
}

selfdestruct

selfdestruct removes a contract from the blockchain and force-sends its ETH balance to any address. This bypasses receive() and fallback() functions, breaking contracts that rely on address(this).balance for logic.

// This invariant can be broken by selfdestruct
function isBalanceCorrect() public view returns (bool) {
    return address(this).balance == totalDeposits;
}

Note: selfdestruct behavior changed after EIP-6780 (Dencun upgrade), but force-sending ETH still works during the creation transaction.

Vyper's Safety-by-Design Philosophy

Vyper takes the opposite approach: remove dangerous features entirely. No inheritance, no operator overloading, no inline assembly, no function overloading, and bounded loops only.

Bounded Loops

Vyper requires loop bounds at compile time. You literally cannot write an unbounded loop.

# Vyper: must specify max iterations
@external
def sum_deposits(deposits: DynArray[uint256, 100]) -> uint256:
    total: uint256 = 0
    for deposit: uint256 in deposits:
        total += deposit
    return total

Compare that to Solidity, where an unbounded loop over a growing array is a classic gas griefing vector:

// Solidity: nothing stops you from iterating forever
function sumDeposits() public view returns (uint256) {
    uint256 total = 0;
    for (uint256 i = 0; i < deposits.length; i++) {
        total += deposits[i];  // Gas bomb if array grows large
    }
    return total;
}

No Inheritance

Vyper has no inheritance. This sounds limiting until you realize that inheritance is a major source of audit complexity. Diamond inheritance, storage layout conflicts between parent contracts, and shadowed functions have caused real exploits.

In Vyper, every contract is flat. What you see is what you get.

Default Overflow Protection

Both languages now have overflow protection by default (Solidity since 0.8.0, Vyper since inception), but Vyper had it from day one. In Solidity, developers can still opt out with unchecked blocks — and they do, often incorrectly, to save gas.

// Solidity: developers can bypass overflow checks
function riskyMath(uint256 a, uint256 b) public pure returns (uint256) {
    unchecked {
        return a - b;  // Wraps on underflow
    }
}

Vyper has no equivalent escape hatch.

Vyper Is Not Immune

Vyper's safety-first design reduces the attack surface, but it does not eliminate it.

raw_call

Vyper's raw_call is analogous to Solidity's low-level call. It gives you the same reentrancy and return-data risks.

# Vyper: raw_call is just as dangerous as Solidity's .call()
@external
def forward_call(target: address, data: Bytes[1024]):
    raw_call(target, data)  # No reentrancy guard

The Reentrancy Lock Bug (2023)

In July 2023, a compiler bug in Vyper versions 0.2.15, 0.2.16, and 0.3.0 broke the @nonreentrant decorator. The reentrancy lock was not properly enforced, leading to exploits on several Curve Finance pools and roughly $70M in losses.

This is a crucial lesson: language-level safety features are only as reliable as the compiler that implements them.

Storage Collisions in Older Versions

Before Vyper 0.4.0, storage slot assignments could collide when using certain patterns with DynArray and mappings. The compiler has since fixed this, but contracts deployed with older versions remain vulnerable.

Default Visibility

In Vyper, functions without a decorator default to @internal. In Solidity, functions default to public (prior to 0.5.0, they defaulted to public — a common footgun). However, Vyper's @external decorator is still easy to misapply:

# Vyper: accidentally exposing an admin function
@external
def set_fee(new_fee: uint256):
    # Forgot access control — anyone can call this
    self.fee = new_fee

The language does not enforce access control; that is still the developer's job.

The Same Vulnerability in Both Languages

Let's look at a classic reentrancy bug implemented in both languages.

Solidity:

contract VulnerableVault {
    mapping(address => uint256) public balances;

    function withdraw() external {
        uint256 amount = balances[msg.sender];
        (bool success, ) = msg.sender.call{value: amount}("");
        require(success);
        balances[msg.sender] = 0;  // State update AFTER external call
    }
}

Vyper:

balances: public(HashMap[address, uint256])

@external
def withdraw():
    amount: uint256 = self.balances[msg.sender]
    raw_call(msg.sender, b"", value=amount)
    self.balances[msg.sender] = 0  # Same bug: state update after call

Both are vulnerable to reentrancy. The fix is the same in both languages: update state before making external calls (checks-effects-interactions pattern), or use a reentrancy lock.

What This Means for Auditors

When auditing Solidity, your checklist is longer. You need to check for delegatecall misuse, selfdestruct edge cases, tx.origin phishing, inline assembly correctness, inheritance conflicts, and unchecked arithmetic.

When auditing Vyper, the attack surface is smaller, but you need to verify the compiler version (especially for the reentrancy lock bug), check raw_call usage, and still look for access control issues and logic errors that no language can prevent.

In spectr-ai, we weight findings differently based on the source language. A delegatecall in Solidity triggers a high-severity check. In Vyper, that pattern does not exist, so the engine focuses on raw_call patterns and compiler-version-specific issues instead.

The Takeaway

Vyper is genuinely safer by default. If your contract does not need Solidity's advanced features (upgradeable proxies, complex inheritance hierarchies, inline assembly optimizations), Vyper reduces the surface area an attacker can probe.

But "safer by default" is not "safe." The Curve exploit proved that compiler bugs can undermine language-level guarantees. No matter the language, the fundamentals still apply: checks-effects-interactions, access control, input validation, and — ideally — a thorough audit by both AI and human reviewers.

The best security comes from using the right tool for the job and understanding the specific risks of whichever language you choose.

How I Structured a TypeScript Monorepo with pnpm Workspaces

Pavel Espitia — Thu, 30 Apr 2026 15:06:10 +0000

When spectr-ai started as a single package, everything lived in one directory: the CLI engine, the web frontend, shared types, and configuration. It worked fine until it did not. The engine needed its own publish cycle. The web app had different build tooling. Shared types were copy-pasted between files. It was time for a monorepo.

This is the practical guide I wish I had. No theory — just the steps, the config files, and the problems I hit along the way.

Why pnpm Workspaces

I chose pnpm over npm workspaces or Turborepo for three reasons: strict dependency isolation (packages cannot access undeclared dependencies), disk efficiency through content-addressable storage, and the workspace:* protocol that makes cross-package references explicit. Turborepo is great for build orchestration, but pnpm workspaces handle dependency management better out of the box.

The Target Structure

Here is what spectr-ai's monorepo looks like after the migration:

spectr-ai/
  pnpm-workspace.yaml
  package.json
  tsconfig.base.json
  packages/
    engine/
      package.json
      tsconfig.json
      src/
    shared/
      package.json
      tsconfig.json
      src/
  apps/
    web/
      package.json
      tsconfig.json
      src/

Three workspace packages: @spectr-ai/engine (the CLI and analysis core), @spectr-ai/shared (types, constants, utilities), and the web app under apps/web.

Step 1: pnpm-workspace.yaml

This file tells pnpm where your packages live. Create it at the repo root:

packages:
  - "packages/*"
  - "apps/*"

That is the entire file. Every directory matching these globs that contains a package.json becomes a workspace package.

Step 2: Root package.json

The root package.json is not a publishable package. It holds shared dev dependencies and workspace-level scripts.

{
  "name": "spectr-ai",
  "private": true,
  "scripts": {
    "build": "pnpm --filter './packages/**' build",
    "dev": "pnpm --filter @spectr-ai/web dev",
    "lint": "pnpm -r lint",
    "test": "pnpm -r test",
    "typecheck": "pnpm -r typecheck"
  },
  "devDependencies": {
    "typescript": "5.7.3"
  }
}

Key details: "private": true prevents accidental publishing of the root. The -r flag runs a script recursively across all workspace packages. The --filter flag targets specific packages.

Step 3: Package-Level package.json

Each package declares its own name, dependencies, and entry points. Here is the engine package:

{
  "name": "@spectr-ai/engine",
  "version": "0.3.0",
  "type": "module",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./analyzers": {
      "import": "./dist/analyzers/index.js",
      "types": "./dist/analyzers/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsc --build",
    "lint": "oxlint src/",
    "test": "vitest run",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "@spectr-ai/shared": "workspace:*"
  }
}

The workspace:* protocol is the critical piece. It tells pnpm to resolve @spectr-ai/shared from the local workspace instead of the registry. When you publish, pnpm automatically replaces workspace:* with the actual version number.

The exports field replaces the old main/types fields and gives you fine-grained control over what consumers can import. Without it, any file in dist/ is importable — which leaks internal implementation details.

Step 4: TypeScript Configuration

A base tsconfig.base.json at the root defines shared compiler options:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "skipLibCheck": true
  }
}

Each package extends it and adds its own paths:

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist",
    "composite": true
  },
  "include": ["src"],
  "references": [
    { "path": "../shared" }
  ]
}

The composite: true and references fields enable TypeScript's project references. This gives you incremental builds: changing a file in shared only rebuilds shared and its dependents, not the entire repo.

Step 5: Cross-Package Imports

With the setup above, importing from a sibling package looks like importing from any npm package:

import { AuditResult, Severity } from "@spectr-ai/shared";
import { analyzeContract } from "@spectr-ai/engine/analyzers";

No relative paths crossing package boundaries. No path aliases that break at runtime. The exports field in each package's package.json controls what is importable.

Step 6: CI with --filter

In CI, you do not want to rebuild and test everything when only one package changed. pnpm's --filter flag handles this:

jobs:
  test-engine:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda  # v4.1.0
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4.4.0
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm --filter @spectr-ai/engine build
      - run: pnpm --filter @spectr-ai/engine test
      - run: pnpm --filter @spectr-ai/engine typecheck

The --filter flag also resolves dependencies automatically. If engine depends on shared, running pnpm --filter @spectr-ai/engine build builds shared first.

For change-based filtering, you can use --filter ...[origin/main] to only run against packages that changed since the main branch:

pnpm --filter '...[origin/main]' test

Problems I Hit

Problem 1: Phantom dependencies. A package imported zod without declaring it in its own package.json. It worked locally because another package had zod installed. pnpm's strict mode caught this immediately — npm workspaces would not have.

Problem 2: Build order. Running pnpm -r build without project references built packages in alphabetical order. The web app tried to build before shared was compiled. Adding references to each tsconfig.json and using tsc --build fixed the ordering.

Problem 3: Type resolution during development. Before building, TypeScript could not resolve types from sibling packages because the dist/ directories did not exist yet. The fix was adding declarationMap: true to the base config and ensuring the references array was correct. With project references, tsc resolves types from source during development.

Problem 4: IDE performance. VS Code's TypeScript server struggled with three projects. The solution was adding a root tsconfig.json with only references (no include), which tells the language server about the project structure:

{
  "references": [
    { "path": "packages/engine" },
    { "path": "packages/shared" },
    { "path": "apps/web" }
  ],
  "files": []
}

Was It Worth It

Yes. Dependency boundaries are enforced by tooling instead of convention. Each package has its own test suite, lint config, and build step. The engine can be published to npm independently. CI runs are faster because only changed packages are tested.

The migration took about a day. Most of that time was moving files and fixing import paths. The configuration itself — once you know what each field does — is maybe 30 minutes of work.

If your project has two or more distinct concerns sharing code, a pnpm monorepo is worth the setup cost. Start with the structure above and adjust as your project grows.

AI Won't Replace Smart Contract Auditors — But Auditors Using AI Will Replace Those Who Don't

Pavel Espitia — Thu, 30 Apr 2026 15:06:08 +0000

Every few months, someone on Twitter declares that AI will make smart contract auditors obsolete. I have been building spectr-ai — an AI-powered smart contract analysis tool — for the past several months, and I can tell you definitively: that take is wrong. But so is the opposite claim that AI is useless for security work.

The truth is more nuanced, more interesting, and has real implications for anyone building or auditing smart contracts.

What AI Actually Does Well

AI excels at pattern recognition at scale. Feed a language model a Solidity contract, and it will reliably catch:

Known vulnerability patterns. Reentrancy, unchecked return values, tx.origin authentication, uninitialized storage pointers, integer overflow in pre-0.8.0 contracts — these are well-documented patterns that appear in training data thousands of times. AI catches them fast and consistently.

Style and hygiene issues. Missing events on state changes, functions that should be view/pure but are not, overly permissive visibility, missing zero-address checks. These are not exploits, but they indicate sloppy code that often harbors deeper issues.

Deviation from known-safe patterns. When a contract implements a DEX but deviates from the Uniswap V2/V3 pattern in a specific function, AI can flag the deviation. It may not know why the deviation is dangerous, but it knows it is unusual.

Speed. An AI can analyze a 1,000-line contract in seconds. A human auditor spends hours or days. For a first pass, that speed difference is transformative.

When I run spectr-ai against contracts with known vulnerabilities, it catches the obvious stuff with high reliability. Reentrancy in a withdraw function? Flagged immediately. Missing access control on an admin function? Caught every time. These are the bread-and-butter findings that make up the majority of audit reports.

What AI Cannot Do

Here is where the hype falls apart.

Novel attack vectors. The most devastating hacks in DeFi history exploited logic that no one had seen before. The Euler Finance donation attack, the Mango Markets oracle manipulation, the Cream Finance flash loan chain — these required creative reasoning about how multiple systems interact under adversarial conditions. AI cannot reason about attacks that do not exist in its training data.

Cross-contract economic modeling. DeFi protocols are composable. A lending protocol interacts with an AMM, which interacts with an oracle, which interacts with a bridge. Understanding how a price manipulation in one protocol cascades through this stack requires modeling economic incentives, game theory, and multi-step attack paths. Current AI models can follow these chains if you lay them out, but they cannot discover them independently.

Business logic validation. A contract might be technically secure — no reentrancy, no overflow, proper access control — but implement the wrong business logic. If a governance contract lets a proposal execute immediately instead of after a timelock, AI might not flag it unless you tell it the intended behavior. AI does not know what the contract is supposed to do; it only knows what the code actually does.

Subtle storage layout issues. Upgradeable proxy contracts have strict requirements about storage slot ordering across implementations. AI can check basic rules, but complex storage layouts with inherited contracts and gap variables require careful manual analysis.

Context about deployment. A contract might be safe in isolation but dangerous in the context of its deployment. Who are the privileged roles? What is the expected call flow? Which external contracts will it interact with? AI does not have this context unless you provide it.

The Economics Are Reshaping the Market

Here is what matters most: the cost structure of security is changing.

A traditional smart contract audit from a top firm costs $50,000 to $200,000 and takes 2-4 weeks. This means only well-funded projects get audited. The long tail of smaller contracts — the ones deployed by indie developers, small DAOs, and experimental protocols — ship unaudited because the economics do not work.

An AI-powered first pass costs essentially nothing. Running a contract through spectr-ai or similar tools takes seconds and catches the most common issues. This does not replace a professional audit, but it does catch the low-hanging fruit that accounts for a large percentage of real exploits.

The market is not shrinking. It is widening. Projects that could never afford an audit now have access to automated analysis. Projects that can afford an audit get a faster, more thorough review because the auditor spends less time on obvious issues and more time on complex logic.

The Hybrid Model

The winning approach — and what spectr-ai is building toward — is a hybrid pipeline:

Layer 1: Automated static analysis. Traditional tools like Slither and Mythril catch known patterns through formal methods. They are deterministic and fast.

Layer 2: AI-powered analysis. LLMs analyze the code with broader context, catching patterns that static analysis misses and providing natural-language explanations of findings. This is where spectr-ai operates.

Layer 3: Human expert review. Auditors review the AI's findings, investigate flagged areas in depth, and focus their time on business logic, economic modeling, and novel attack surfaces.

Each layer filters noise for the next. By the time a human auditor sits down, the obvious issues are already documented, and they can focus on the work that actually requires human judgment.

What This Means for Auditors

If you are a smart contract auditor, AI is not your replacement. It is your leverage.

The auditors who will thrive are the ones who use AI to handle the repetitive work and redirect their attention to higher-value analysis. An auditor who reviews AI findings and spends their time on economic attack modeling, cross-protocol interaction analysis, and business logic validation will deliver more value in less time than one who manually checks for reentrancy.

The auditors who will struggle are the ones whose primary skill is recognizing known vulnerability patterns. That skill is being commoditized. If your audit reports mostly contain findings that Slither or an LLM could have caught, the market will adjust your pricing accordingly.

What This Means for Developers

If you are deploying smart contracts, run automated tools before hiring an auditor. This is not optional anymore — it is table stakes. Use Slither for static analysis. Use an AI tool for a broader review. Fix everything they find.

Then, if your contract handles significant value or has complex logic, hire a human auditor. They will be more effective because they are not wasting time on issues you could have caught yourself.

The security gap in Web3 is not going to be closed by AI alone or by humans alone. It is going to be closed by making basic security analysis accessible to every project and reserving expert human attention for the contracts that need it most.

That is what spectr-ai is building toward. Not a replacement for auditors, but a tool that makes the entire ecosystem more secure by meeting developers where they are.

I Analyzed 5 Famous Hacked Contracts with AI — Here's What It Found

Pavel Espitia — Mon, 27 Apr 2026 12:29:11 +0000

I fed the vulnerable code patterns from five of the most devastating DeFi hacks into spectr-ai to see what an AI auditor would catch — and what it would miss. The results were both encouraging and humbling.

For each hack, I reconstructed the vulnerable code pattern (simplified for clarity), ran it through the AI analysis pipeline, and recorded the findings. No cherry-picking. Here is what happened.

1. The DAO — Reentrancy ($60M, June 2016)

What happened: The DAO's splitDAO function sent ETH to users before updating their balance. An attacker called the function recursively through a fallback function, draining funds repeatedly before the balance was set to zero.

The vulnerable pattern:

function withdraw(uint amount) public {
    require(balances[msg.sender] >= amount);

    // ETH sent before state update
    (bool success, ) = msg.sender.call{value: amount}("");
    require(success);

    // State updated after external call
    balances[msg.sender] -= amount;
}

What the AI found: Flagged immediately. High severity. The finding identified the external call before state update, correctly described the reentrancy attack vector, and recommended the checks-effects-interactions pattern. It also suggested adding a reentrancy guard modifier.

Verdict: Caught. This is the canonical example of a known vulnerability pattern. Any tool worth its salt catches this one.

2. Parity Multisig — delegatecall + selfdestruct ($280M frozen, November 2017)

What happened: Parity's multisig wallet used a library contract via delegatecall. The library contract had an initWallet function that was left unprotected after deployment. An attacker called initWallet on the library itself, became its owner, then called kill() which executed selfdestruct. Since every wallet delegated to this library, all of them became nonfunctional — $280M in ETH was permanently frozen.

The vulnerable pattern:

contract WalletLibrary {
    address public owner;
    bool public initialized;

    function initWallet(address _owner) public {
        // No check if already initialized on the library itself
        require(!initialized);
        owner = _owner;
        initialized = true;
    }

    function kill(address to) public {
        require(msg.sender == owner);
        selfdestruct(payable(to));
    }
}

contract Wallet {
    address public library;

    fallback() external payable {
        (bool success, ) = library.delegatecall(msg.data);
        require(success);
    }
}

What the AI found: It flagged two issues. First, the selfdestruct usage was flagged as high severity with a note about permanent contract removal. Second, the open delegatecall in the fallback was flagged as a proxy pattern requiring careful access control review. However, it did not connect the dots — it did not identify that the library contract itself could be initialized by anyone because it was deployed as a standalone contract with no constructor protection.

Verdict: Partially caught. The individual dangerous primitives were flagged, but the compound attack — that the library was a standalone contract whose initialization could be hijacked — required understanding the deployment context that the AI did not have.

3. Ronin Bridge — Compromised Validators ($625M, March 2022)

What happened: The Ronin bridge required 5 of 9 validator signatures to approve withdrawals. The attacker compromised 4 validator private keys belonging to Sky Mavis and one third-party validator (Axie DAO). With 5 signatures, they approved fraudulent withdrawals of 173,600 ETH and 25.5M USDC.

The vulnerable pattern:

function withdrawERC20(
    uint256 id,
    address token,
    uint256 amount,
    address recipient,
    bytes[] calldata signatures
) external {
    require(signatures.length >= threshold, "Not enough sigs");

    bytes32 hash = keccak256(
        abi.encodePacked(id, token, amount, recipient)
    );

    uint256 validSigs = 0;
    for (uint256 i = 0; i < signatures.length; i++) {
        address signer = ECDSA.recover(hash, signatures[i]);
        if (isValidator[signer]) {
            validSigs++;
        }
    }

    require(validSigs >= threshold, "Invalid signatures");
    IERC20(token).transfer(recipient, amount);
}

What the AI found: It flagged a missing duplicate-signer check (the same validator signature could potentially be submitted multiple times depending on the implementation). It also noted that the threshold of 5/9 was relatively low for a bridge holding hundreds of millions. But fundamentally, the code logic was correct — the vulnerability was operational, not in the smart contract.

Verdict: Missed (correctly). This was not a code vulnerability. It was a key management failure. No static analysis or AI review of the contract source code could have caught this. The lesson here is that smart contract security is necessary but not sufficient — operational security matters just as much.

4. Cream Finance — Flash Loan + Oracle Manipulation ($130M, October 2021)

What happened: The attacker used a flash loan to manipulate the price of crYUSD (Cream's yUSD lending token), then used the inflated collateral value to borrow all available assets across Cream's lending markets. The attack exploited how Cream calculated the value of crYUSD as collateral — it relied on the token's exchange rate, which could be manipulated through large deposits.

The vulnerable pattern (simplified):

function getCollateralValue(
    address token,
    uint256 amount
) public view returns (uint256) {
    // Exchange rate can be manipulated via flash loan
    uint256 exchangeRate = ICToken(token).exchangeRateStored();
    uint256 underlyingAmount = amount * exchangeRate / 1e18;
    uint256 price = oracle.getPrice(token);
    return underlyingAmount * price / 1e18;
}

function borrow(
    address collateralToken,
    uint256 collateralAmount,
    address borrowToken,
    uint256 borrowAmount
) external {
    uint256 collateralValue = getCollateralValue(
        collateralToken, collateralAmount
    );
    uint256 borrowValue = borrowAmount
        * oracle.getPrice(borrowToken) / 1e18;
    require(
        collateralValue >= borrowValue * collateralFactor / 1e18
    );
    // ... execute borrow
}

What the AI found: It flagged the use of exchangeRateStored() instead of exchangeRateCurrent() as a potential stale-data issue. It also noted that the collateral valuation was susceptible to price manipulation if the underlying exchange rate could be moved within a single transaction. The flash loan attack vector was mentioned as a possibility.

Verdict: Partially caught. The AI identified the right area of concern — manipulable exchange rates used for collateral valuation — but did not construct the full multi-step attack path involving flash loans, cross-market borrowing, and the specific economic conditions needed for profitability.

5. Euler Finance — Donation Attack ($197M, March 2023)

What happened: The attacker exploited Euler's donateToReserves function, which allowed users to inflate their debt without a corresponding health check. By donating to reserves, the attacker made their own position liquidatable, then used a liquidation mechanism that was more favorable than it should have been given the manipulated state. The interaction between donateToReserves, the health check bypass, and the liquidation bonus created an extraction path.

The vulnerable pattern (simplified):

function donateToReserves(
    address subAccount,
    uint256 amount
) external {
    // Increases the donor's debt token balance
    // WITHOUT checking if the position remains healthy
    debtBalances[subAccount] += amount;
    reserveBalance += amount;
    // Missing: health check after debt increase
}

What the AI found: It flagged the missing health check after the debt increase. The finding noted that any function that modifies a user's debt-to-collateral ratio should verify the position remains solvent afterward. This was rated high severity.

However, the AI did not identify the full exploit chain — how the donation attack combined with the liquidation discount to create a profitable extraction. It caught the entry point but not the economic reasoning.

Verdict: Partially caught. The root cause (missing health check) was identified. The complete attack economics were not.

The Scorecard

Hack	Root Cause	AI Caught It?
The DAO	Reentrancy	Yes
Parity Multisig	Unprotected init + selfdestruct	Partial
Ronin Bridge	Key compromise	No (not a code bug)
Cream Finance	Oracle manipulation	Partial
Euler Finance	Missing health check	Partial

Full catches: 1/5. Partial catches: 3/5. Misses: 1/5.

What I Learned

The AI reliably catches known vulnerability patterns — reentrancy, missing access control, dangerous opcodes. That first finding from The DAO analysis would have saved $60M in 2016. That is not nothing.

But the most devastating modern hacks exploit economic logic, cross-protocol interactions, and deployment context. AI flags the ingredients (a manipulable exchange rate, a missing health check) without assembling them into the full recipe.

This confirms the hybrid model. AI as the first pass catches the known patterns quickly and cheaply. Human auditors then focus their expensive time on the economic modeling and novel attack surfaces that AI cannot reason about.

The goal of spectr-ai is not to produce a final audit report. It is to give the human auditor a head start — flagging the obvious issues so they can spend their time on the hard problems. Based on these results, that approach is working, but the gap between "flagging ingredients" and "identifying complete attack chains" remains wide.

That gap is where human expertise lives. And for now, it is not going anywhere.

Building a Chat Interface Over Any API with TypeScript

Pavel Espitia — Mon, 27 Apr 2026 12:29:10 +0000

Most AI chat interfaces do the same thing: the user types a message, the LLM generates text, and it appears on screen. But the interesting pattern is when the LLM does something — calls an API, queries a database, runs a command — and then explains what happened.

I built this pattern into AbiLens, a tool that lets you chat with any EVM smart contract. But the architecture generalizes to any external API. You can use the same approach to build a chat interface over a REST API, a database, a CLI tool, or any service with a programmatic interface.

Here's how it works.

The Architecture

The flow has four steps:

User sends a message
LLM decides what API call to make (or responds directly if no call is needed)
Your code executes the API call
LLM explains the result to the user

The key insight: the LLM never calls the API directly. It outputs a structured JSON object describing the call it wants to make. Your code validates and executes it. This keeps the LLM in a sandbox — it can only do what you allow.

User Message
    ↓
System Prompt (with available functions)
    ↓
LLM Response (JSON function call OR plain text)
    ↓
Your Code (validates, executes the call)
    ↓
API Result
    ↓
LLM Explanation (human-readable summary)

The System Prompt Template

The system prompt is where you define what the LLM can do. You list every available function with its name, description, and parameters.

function buildSystemPrompt(
  functions: FunctionDefinition[]
): string {
  const functionList = functions
    .map((fn) => {
      const params = fn.parameters
        .map((p) => `  - ${p.name}: ${p.type} — ${p.description}`)
        .join("\n");
      return `### ${fn.name}\n${fn.description}\n${params}`;
    })
    .join("\n\n");

  return `You are an assistant that helps users interact with an API.

When the user asks a question that requires data, respond with a JSON function call:
\`\`\`json
{ "function": "functionName", "args": { "key": "value" } }
\`\`\`

When you can answer directly without data, respond in plain text.

Available functions:
${functionList}

Always explain the results in plain language after receiving them.`;
}

For AbiLens, the functions are dynamically generated from the contract's ABI. For a REST API, you'd define them from your OpenAPI spec. For a database, they'd map to common queries.

interface FunctionDefinition {
  name: string;
  description: string;
  parameters: ParameterDefinition[];
}

interface ParameterDefinition {
  name: string;
  type: string;
  description: string;
  required: boolean;
}

Extracting Function Calls from the LLM Response

The LLM's response is either plain text or contains a JSON function call. You need to detect which one it is and extract the structured data.

import { z } from "zod";

const FunctionCallSchema = z.object({
  function: z.string(),
  args: z.record(z.unknown()),
});

type FunctionCall = z.infer<typeof FunctionCallSchema>;

function extractFunctionCall(
  response: string
): FunctionCall | null {
  const jsonMatch = response.match(
    /```
{% endraw %}
json\s*([\s\S]*?)
{% raw %}
```/
  );
  if (!jsonMatch?.[1]) return null;

  const parsed = FunctionCallSchema.safeParse(
    JSON.parse(jsonMatch[1].trim())
  );
  if (!parsed.success) return null;

  return parsed.data;
}

Zod validation here is not optional. LLMs produce malformed JSON, hallucinate function names, and invent parameters. Parse and validate before you execute anything.

Executing the Calls

Map function names to actual implementations. Each handler receives validated arguments and returns a result.

type FunctionHandler = (
  args: Record<string, unknown>
) => Promise<unknown>;

class FunctionRouter {
  private handlers = new Map<string, FunctionHandler>();

  register(
    name: string,
    handler: FunctionHandler
  ): void {
    this.handlers.set(name, handler);
  }

  async execute(call: FunctionCall): Promise<unknown> {
    const handler = this.handlers.get(call.function);
    if (!handler) {
      throw new Error(
        `Unknown function: ${call.function}`
      );
    }
    return handler(call.args);
  }
}

For a REST API wrapper, registration looks like this:

const router = new FunctionRouter();

router.register("getUser", async (args) => {
  const id = z.string().parse(args.id);
  const response = await fetch(`/api/users/${id}`);
  return response.json();
});

router.register("listOrders", async (args) => {
  const status = z.string().optional().parse(args.status);
  const url = new URL("/api/orders", baseUrl);
  if (status) url.searchParams.set("status", status);
  const response = await fetch(url);
  return response.json();
});

Feeding Results Back

After executing the function, send the result back to the LLM for explanation. The conversation history now includes the user's question, the LLM's function call, and the raw result.

async function handleMessage(
  userMessage: string,
  history: Message[],
  router: FunctionRouter,
  llm: LLMClient
): Promise<string> {
  history.push({ role: "user", content: userMessage });

  const response = await llm.chat(history);
  const functionCall = extractFunctionCall(response);

  if (!functionCall) {
    history.push({ role: "assistant", content: response });
    return response;
  }

  const result = await router.execute(functionCall);
  const resultText = JSON.stringify(result, null, 2);

  history.push({ role: "assistant", content: response });
  history.push({
    role: "user",
    content: `Function result:\n${resultText}\n\nExplain this result to the user.`,
  });

  const explanation = await llm.chat(history);
  history.push({
    role: "assistant",
    content: explanation,
  });
  return explanation;
}

The second LLM call is where the value lives. Raw API responses are JSON blobs. The LLM transforms them into answers: "The user has 3 pending orders totaling $142.50, the most recent one placed yesterday."

Error Handling

Things go wrong. The API returns 500. The LLM hallucinates a function that doesn't exist. The arguments are the wrong type. Handle all of these gracefully by feeding the error back to the LLM.

try {
  const result = await router.execute(functionCall);
  // ... feed result back
} catch (error) {
  const errorMessage =
    error instanceof Error
      ? error.message
      : "Unknown error";

  history.push({
    role: "user",
    content: `The function call failed: ${errorMessage}. Let the user know and suggest alternatives.`,
  });

  return llm.chat(history);
}

This creates a self-correcting loop. The LLM sees the error, explains what went wrong, and often suggests a different approach.

Where This Pattern Works

This same architecture applies beyond smart contracts:

Database explorer: Define functions for common queries (getTableSchema, runQuery, listTables). The LLM translates natural language into SQL and explains the results.
DevOps assistant: Functions for getDeployStatus, listPods, getLogsTail. Chat with your infrastructure.
API documentation: Point it at any REST API and let users explore endpoints conversationally.
CLI wrapper: Functions map to CLI commands. The LLM picks the right flags and explains the output.

The pattern always looks the same: define available functions, let the LLM choose which to call, execute in a sandbox, explain the results.

Practical Tips

Keep the function list short. More than 15-20 functions degrades LLM accuracy. Group related operations or use a two-step approach where the LLM first picks a category, then a specific function.

Include examples in function descriptions. "Returns the user's order history. Example: { 'userId': '123', 'limit': 10 }" helps the LLM format arguments correctly.

Log every function call. You want a complete audit trail of what the LLM asked for, what you executed, and what came back. This is essential for debugging and for trust.

Rate limit aggressively. The LLM doesn't know about your API quotas. Add rate limiting in your router, not in the LLM prompt.

The full AbiLens source is on my GitHub if you want to see this pattern applied to smart contract interaction. The core chat loop is under 200 lines — most of the complexity lives in the function definitions, not the orchestration.

RWA Tokenization in 2026: What Developers Need to Know

Pavel Espitia — Mon, 27 Apr 2026 12:29:07 +0000

Real World Asset tokenization crossed $36 billion on-chain in early 2026. That number was under $2 billion two years ago. BlackRock's BUIDL fund alone holds over $5 billion in tokenized US Treasuries. Franklin Templeton's BENJI tokens represent money market fund shares on Stellar and Polygon. Ondo Finance, Centrifuge, and Maple are tokenizing everything from government bonds to trade receivables.

This is not speculative DeFi. These are regulated financial instruments, on-chain, earning real yield. And the infrastructure to build them is still being figured out.

If you're a developer in the blockchain space, RWA tokenization is where the jobs and opportunities are heading. Here's what you need to understand.

Why Tokenize Real Assets?

The traditional financial system runs on T+2 settlement, paper-based custody chains, and business-hours-only operations. Tokenization replaces that with:

Instant settlement: Transfer ownership in a single transaction, 24/7
Fractional ownership: A $100M building becomes 100 million tokens at $1 each
Programmable compliance: Enforce transfer restrictions, KYC, and jurisdiction rules in code
Composability: Tokenized assets plug into DeFi lending, collateral, and yield protocols

The value proposition for institutions is clear: lower costs, faster settlement, broader distribution. For developers, this creates an entirely new infrastructure layer to build.

ERC-3643: The Compliance Token Standard

You can't tokenize a security with a standard ERC-20. Securities have transfer restrictions — you can't sell them to unaccredited investors, in sanctioned jurisdictions, or beyond ownership caps.

ERC-3643 (formerly T-REX) is the standard that solves this. It adds an identity and compliance layer on top of ERC-20 transfers.

The architecture has three components:

Identity Registry: Maps wallet addresses to on-chain identity claims. Before any transfer, the token contract checks if both sender and receiver have valid identity claims.

Compliance Module: Encodes transfer rules. Maximum holder count, country restrictions, lock-up periods, ownership caps. These are modular — you compose the rules your asset requires.

Trusted Issuers Registry: Lists which identity providers are trusted. A KYC provider issues a claim to a wallet, the claim is stored on-chain (or referenced via a hash), and the token contract verifies it during transfers.

// Simplified ERC-3643 transfer check
function _beforeTokenTransfer(
    address from,
    address to,
    uint256 amount
) internal override {
    require(
        identityRegistry.isVerified(to),
        "Recipient not verified"
    );
    require(
        compliance.canTransfer(from, to, amount),
        "Transfer not compliant"
    );
}

Every transfer goes through these checks. If the recipient isn't KYC'd, the transfer reverts. If the transfer would violate a compliance rule, it reverts. This is securities regulation enforced at the protocol level.

KYC/AML Hooks and Identity

The identity layer is where most of the complexity lives. On-chain identity for financial compliance requires:

Claim-based identity: Wallets hold verifiable claims (accredited investor, jurisdiction, tax status) issued by trusted third parties
Privacy-preserving verification: You need to prove "this wallet belongs to a KYC'd US accredited investor" without revealing their name or social security number
Revocability: When someone fails an AML check, their claims get revoked, and their tokens become non-transferable until resolved

Most production systems use a hybrid approach: identity verification happens off-chain with a traditional KYC provider, and the result is posted on-chain as a hash or a zero-knowledge proof.

// Identity claim structure
struct Claim {
    uint256 topic;      // e.g., 1 = KYC, 2 = accredited
    address issuer;     // trusted KYC provider
    bytes signature;    // issuer's signature over claim data
    bytes data;         // claim details (often a hash)
    string uri;         // off-chain data reference
}

Privacy with Zero-Knowledge Proofs

Here's the tension: financial regulations require knowing who holds what, but blockchain transactions are public. If BlackRock tokenizes a fund, they don't want the world seeing every investor's position in real-time.

ZK-proofs solve this. A holder can prove "I am KYC'd and accredited" without revealing identity. A compliance check can verify "this transfer doesn't violate any rules" without exposing the rule parameters.

Midnight, a privacy-focused blockchain from the Cardano ecosystem, is built specifically for this use case. It supports confidential smart contracts where the logic executes in a shielded environment — the chain verifies the proof of correct execution without seeing the data.

Other approaches include:

zkKYC protocols: Prove identity claims without revealing underlying data
Confidential ERC-20s: Token balances and transfers are encrypted, with ZK-proofs ensuring correctness
Selective disclosure: Reveal only what's needed for a specific compliance check

This is still early. The tooling is immature and the standards are evolving. But privacy-preserving compliance is where the industry is heading, and developers who understand both ZK and securities regulation will be in high demand.

The Opportunity for Tooling Builders

The RWA stack has massive gaps. Here's where developers can build:

Compliance SDKs: ERC-3643 is a standard, but deploying a compliant token still requires deep knowledge of the spec. A developer-friendly SDK that handles identity registry setup, compliance module configuration, and trusted issuer management would be valuable.

Tokenization platforms: Think "Stripe for tokenizing assets." Upload your legal documents, configure compliance rules, deploy to your target chain. Companies like Securitize and Tokeny are building this, but the space is far from consolidated.

Audit tools for RWA contracts: Standard smart contract auditors don't understand securities compliance. An audit tool that checks not just for reentrancy and overflow but also for compliance gaps — missing transfer restrictions, incorrect identity checks, inadequate access controls on admin functions — is a real product opportunity. This is exactly the kind of domain-specific analysis that AI auditors like spectr-ai could be extended to handle.

Cross-chain bridges for regulated assets: Moving tokenized securities between chains while maintaining compliance state is an unsolved problem. The identity claims on Ethereum don't automatically exist on Polygon.

Reporting and analytics: Regulators want reports. Token issuers need dashboards showing holder distribution by jurisdiction, transfer volumes, compliance violations. The data is all on-chain — someone needs to build the indexing and visualization layer.

What to Learn

If you want to work in RWA tokenization, here's a practical learning path:

Understand ERC-3643 deeply. Read the spec, deploy a test token, try transferring between verified and unverified wallets.
Learn the regulatory basics. You don't need a law degree, but you need to understand what "accredited investor," "Reg D," "Reg S," and "MiFID II" mean. The rules determine the code.
Study ZK fundamentals. Circom, Noir, or Halo2 — pick one and build a simple proof. Understand what can be proven and what the computational costs are.
Build something. A toy tokenization platform that mints compliant tokens with mock KYC. The best way to learn the ERC-3643 flow is to implement it.

The RWA space is hiring and the talent pool is thin. Most blockchain developers understand DeFi but not securities compliance. Most fintech developers understand compliance but not smart contracts. The intersection is where the opportunity lives.

What I Learned Building 2 AI Products in 2 Weeks

Pavel Espitia — Mon, 27 Apr 2026 12:26:02 +0000

Two weeks ago, spectr-ai and AbiLens didn't exist. Today, spectr-ai is a working AI smart contract auditor with a CLI engine and a Next.js web interface. AbiLens lets you chat with any deployed EVM smart contract by address. Both use multiple LLM providers, both have test suites, and both solve real problems I actually had.

Here's what I learned building them.

1. Start with the CLI, Add the Web UI Later

Both projects started as command-line tools. spectr-ai began as a Node.js script that took a Solidity file path, sent it to Claude, and printed the audit report. AbiLens started as a terminal chat loop that resolved contract ABIs and let me call read functions.

The CLI-first approach forced me to get the core logic right before worrying about layout, state management, or component architecture. The engine module in spectr-ai is completely independent of the web layer — it exports functions that accept a file path and options and return structured results.

// The core function works identically in CLI and web
async function auditContract(
  source: string,
  options: AuditOptions
): Promise<AuditReport> {
  const provider = createProvider(options.provider);
  const prompt = buildAuditPrompt(source, options.depth);
  const response = await provider.analyze(prompt);
  return parseAuditReport(response);
}

When I added the Next.js frontend, it was just a thin wrapper around this function. The API route calls auditContract() with the uploaded source and streams the result back. Zero logic duplication.

If you start with a web UI, you end up coupling business logic to React state and API routes. Starting with the CLI forces clean separation because there's no UI framework to lean on.

2. Provider Abstraction from Day 1

Both projects support Claude (via the Anthropic API) and Ollama (for local models). I built the provider abstraction on day one of spectr-ai, and I'm glad I did.

interface LLMProvider {
  analyze(prompt: string): Promise<string>;
  chat(messages: Message[]): Promise<string>;
}

function createProvider(
  name: "claude" | "ollama"
): LLMProvider {
  switch (name) {
    case "claude":
      return new ClaudeProvider(process.env.ANTHROPIC_API_KEY);
    case "ollama":
      return new OllamaProvider(process.env.OLLAMA_HOST);
  }
}

Switching providers is a flag: spectr-ai audit contract.sol --provider ollama. The core logic doesn't know or care which model is answering.

Without this abstraction, swapping providers means rewriting every LLM call. The API shapes are different (Anthropic uses messages with role/content, Ollama has a different format), the authentication is different, and the streaming interfaces are different. The provider wrapper absorbs all of that.

This took about an hour to build. It would have taken days to retrofit.

3. Structured Output Is the Hard Part

The hardest part of both projects wasn't the LLM calls — it was getting structured data out of the LLM responses. When spectr-ai audits a contract, it needs a structured report with severity levels, line numbers, descriptions, and recommendations. When AbiLens parses a chat response, it needs to extract function calls with typed arguments.

LLMs don't reliably produce valid JSON. They add trailing commas, use single quotes, wrap JSON in markdown code blocks inconsistently, and sometimes produce almost-JSON that looks right but doesn't parse.

Zod saved both projects:

const VulnerabilitySchema = z.object({
  severity: z.enum(["critical", "high", "medium", "low", "info"]),
  title: z.string(),
  description: z.string(),
  lineNumbers: z.array(z.number()).optional(),
  recommendation: z.string(),
});

const AuditReportSchema = z.object({
  summary: z.string(),
  vulnerabilities: z.array(VulnerabilitySchema),
  gasOptimizations: z.array(z.string()),
  overallRisk: z.enum(["critical", "high", "medium", "low"]),
});

I parse the LLM response, extract the JSON block, and run it through Zod. If validation fails, I send the error back to the LLM with the schema and ask it to fix the output. This retry loop succeeds on the second attempt about 90% of the time.

Invest in your output schemas early. Define them with Zod, validate everything, and build the retry loop. It's the difference between a demo and a product.

4. LLMs Are Good at Code Analysis, Not Great at Novel Reasoning

spectr-ai works well because code analysis plays to LLM strengths. Models have seen millions of Solidity files during training. They recognize patterns — reentrancy, access control gaps, integer issues — because they've seen them before.

But when I tried to make spectr-ai reason about novel protocol-level interactions ("if contract A calls contract B which calls contract C, could this create a flash loan attack vector?"), the results were unreliable. The model would confidently describe attack paths that didn't actually work, or miss obvious ones.

The lesson: design your prompts around pattern recognition, not novel reasoning. spectr-ai's prompts break the audit into specific categories — "check for reentrancy patterns," "check for access control issues," "check for integer overflow" — rather than asking "find all vulnerabilities." Each focused prompt plays to the model's strength of recognizing known patterns.

5. Ship Fast, Iterate in Public

spectr-ai went from empty directory to working CLI in three days. AbiLens took two days for the core chat loop. Both were rough — limited error handling, minimal tests, hardcoded configurations. But they worked.

Shipping early forced real usage. I audited actual contracts with spectr-ai and found bugs in my own prompts. I chatted with mainnet contracts through AbiLens and discovered edge cases in ABI resolution. Real usage generates real feedback faster than any amount of planning.

The iteration cycle after the initial ship was faster too. Once the architecture is in place, adding features is incremental. Adding a new vulnerability category to spectr-ai is a new prompt template and a schema update. Adding a new chain to AbiLens is a new RPC endpoint in the config.

6. The Best Portfolio Projects Are Tools You Actually Use

I built spectr-ai because I was manually auditing contracts and wanted to automate the boring parts. I built AbiLens because I was tired of going to Etherscan to read contract state. Both solve problems I personally have.

This matters for two reasons. First, you make better design decisions because you're the user. You know which features matter and which are noise. Second, you keep maintaining the project because you need it. Portfolio projects built for resume filler die after the initial push.

The Numbers

Across both projects in two weeks:

spectr-ai: ~3,200 lines of TypeScript, 47 tests, supports 12 vulnerability categories, CLI + web interface, 2 LLM providers
AbiLens: ~1,800 lines of TypeScript, 23 tests, automatic ABI resolution for verified contracts, conversational contract interaction
Total development time: ~80 hours across 14 days
Dependencies: 18 (spectr-ai) and 12 (AbiLens), each justified

The code is on GitHub. Both projects are functional tools, not demos. They have error handling, test coverage, structured logging, and documentation.

Two weeks is enough time to build something real. The LLM APIs make the AI part straightforward — the engineering challenge is everything around it: structured output, provider abstraction, clean architecture, and actually shipping.

Build tools you'll use. Start with the CLI. Validate your outputs. Ship on day three and fix it on day four.

What Happens When You Call a Smart Contract? A Visual Guide

Pavel Espitia — Fri, 24 Apr 2026 12:56:07 +0000

Every interaction with a smart contract — checking a token balance, swapping on Uniswap, minting an NFT — follows the same fundamental path. Understanding that path turns blockchain development from "it works but I don't know why" into "I know exactly what's happening at every step."

Let's trace a contract call from your browser all the way to the EVM and back.

The Journey of a Contract Call

Here's the high-level flow:

Your App → JSON-RPC Request → RPC Node → EVM Execution → State Change → Response

Let's break down each step.

Step 1: ABI Encoding

Your application doesn't send human-readable function calls to the blockchain. It sends raw bytes. The ABI (Application Binary Interface) defines how to encode function names and parameters into those bytes.

A function call is encoded as:

4 bytes: the function selector (first 4 bytes of the keccak256 hash of the function signature)
32 bytes per parameter: each argument padded to 32 bytes

For example, calling transfer(address to, uint256 amount) with address 0xAbC...123 and amount 1000000:

Function signature: "transfer(address,uint256)"
Keccak256 hash:     0xa9059cbb2ab09eb219583f4a59a5d0623ade346d962bcd4e46b11da047c9049b
Function selector:  0xa9059cbb (first 4 bytes)

The final calldata is the selector followed by the ABI-encoded parameters — the address padded to 32 bytes and the amount padded to 32 bytes.

Using viem, you don't do this manually:

import {
  encodeFunctionData,
  parseAbi,
} from "viem";

const abi = parseAbi([
  "function transfer(address to, uint256 amount) returns (bool)",
]);

const data = encodeFunctionData({
  abi,
  functionName: "transfer",
  args: [
    "0xAbCdEf0123456789AbCdEf0123456789AbCdEf01",
    1000000n,
  ],
});

// data = "0xa9059cbb000000000000000000000000abcdef..."

The encodeFunctionData function takes the ABI, function name, and arguments, and returns the hex-encoded calldata. This is what actually gets sent to the network.

Step 2: The JSON-RPC Request

Your app sends the encoded data to an RPC node (Infura, Alchemy, or your own node) via a JSON-RPC call. For a read-only call:

{
  "jsonrpc": "2.0",
  "method": "eth_call",
  "params": [
    {
      "to": "0xContractAddress...",
      "data": "0xa9059cbb000000000000..."
    },
    "latest"
  ],
  "id": 1
}

For a state-changing call (a transaction), the method is eth_sendRawTransaction and the params include a signed transaction with gas, nonce, and value fields.

This distinction matters: eth_call is free and instant. eth_sendRawTransaction costs gas and waits for block inclusion.

Step 3: View Calls vs. Write Calls

This is the most important distinction in smart contract development.

View calls (eth_call) execute the contract code on the RPC node without creating a transaction. They read state but don't change it. They're free, instant, and don't need a wallet signature.

import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
});

// View call — free, instant, no signature needed
const balance = await client.readContract({
  address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  abi: parseAbi([
    "function balanceOf(address) view returns (uint256)",
  ]),
  functionName: "balanceOf",
  args: ["0xYourAddress..."],
});

Write calls (eth_sendRawTransaction) create a transaction that gets included in a block. They can change contract state — update balances, transfer tokens, modify mappings. They cost gas and require the sender's signature.

import { createWalletClient, custom } from "viem";

const walletClient = createWalletClient({
  chain: mainnet,
  transport: custom(window.ethereum),
});

// Write call — costs gas, needs signature, waits for block
const hash = await walletClient.writeContract({
  address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  abi: parseAbi([
    "function transfer(address, uint256) returns (bool)",
  ]),
  functionName: "transfer",
  args: ["0xRecipient...", 1000000n],
});

In Solidity, view and pure functions are view calls. Everything else is a write call.

Step 4: EVM Execution

When the RPC node receives the call, it feeds the calldata to the Ethereum Virtual Machine. The EVM:

Loads the contract's bytecode from the target address
Reads the function selector (first 4 bytes of calldata)
Jumps to the corresponding function in the bytecode
Executes opcodes one by one, consuming gas for each
Reads from and writes to the contract's storage slots
Returns the result or reverts with an error

Each operation costs gas. Storage writes (SSTORE) are the most expensive at 20,000 gas for a new slot. Storage reads (SLOAD) cost 2,100 gas. Simple arithmetic (ADD, MUL) costs 3-5 gas. This is why optimizing storage access matters in smart contracts.

Step 5: Decoding the Response

The EVM returns raw bytes. Your application needs to decode them back into usable values using the ABI.

import { decodeFunctionResult, parseAbi } from "viem";

const abi = parseAbi([
  "function balanceOf(address) view returns (uint256)",
]);

// Raw hex response from eth_call
const rawResult =
  "0x00000000000000000000000000000000000000000000000000000000000f4240";

const balance = decodeFunctionResult({
  abi,
  functionName: "balanceOf",
  data: rawResult,
});

// balance = 1000000n (BigInt)

The response 0x...0f4240 is the hex representation of 1,000,000 padded to 32 bytes. decodeFunctionResult reads the ABI to know the return type is uint256 and decodes accordingly.

In practice, viem's readContract handles both encoding and decoding — you pass in typed arguments and get back typed results. But understanding the underlying encoding helps you debug when things go wrong.

Function Selectors: Why 4 Bytes Matter

The function selector is the keccak256 hash of the function signature, truncated to 4 bytes. This means different functions can have the same selector if their signature hashes collide in the first 4 bytes. It's rare but it happens.

You can compute selectors yourself:

import { keccak256, toBytes, slice } from "viem";

const signature = "transfer(address,uint256)";
const hash = keccak256(toBytes(signature));
const selector = slice(hash, 0, 4);
// selector = "0xa9059cbb"

Tools like AbiLens use function selectors to identify what a transaction is doing. When you see calldata starting with 0xa9059cbb, you know it's an ERC-20 transfer — even without the contract's source code.

This is also how proxy contracts work. The proxy receives the calldata, sees the function selector, and delegates the call to an implementation contract. The selector is the routing mechanism.

The Complete Picture

Putting it all together for a token balance check:

Your app calls readContract({ functionName: "balanceOf", args: [address] })
Viem encodes this as 0x70a08231 + the address padded to 32 bytes
Viem sends an eth_call JSON-RPC request to your configured RPC node
The RPC node executes the contract bytecode in the EVM
The EVM reads the balance from storage slot and returns the raw bytes
Viem decodes the raw bytes back into a BigInt
Your app displays "1,000,000 USDC"

Every dapp interaction — from checking balances to swapping tokens to voting in a DAO — follows this same flow. The functions change, the parameters change, but the encoding, transport, execution, and decoding steps are always the same.

Understanding this pipeline is what separates copying tutorial code from building contracts and dapps with confidence. When a transaction reverts, you'll know to check the calldata encoding. When gas estimates are high, you'll know to look at storage operations. When a function returns unexpected data, you'll know to verify the ABI matches the deployed contract.

Building a Real-Time Progress Bar with Server-Sent Events in Next.js

Pavel Espitia — Thu, 23 Apr 2026 13:18:47 +0000

When spectr-ai analyzes a smart contract, it's not instant. The LLM needs time to reason through the code, identify vulnerabilities, and generate structured output. That analysis can take 10-30 seconds depending on the model and contract size. Staring at a spinner for 30 seconds feels broken. Users need to see progress.

I considered WebSockets, but they're overkill for this. The communication is one-directional — the server sends progress updates, the client displays them. That's exactly what Server-Sent Events (SSE) are designed for.

Why SSE Over WebSockets

WebSockets give you a full-duplex communication channel. Both sides can send messages at any time. That's powerful, but it comes with complexity: connection management, heartbeats, reconnection logic, and a separate protocol that doesn't play well with HTTP middleware.

SSE is simpler. It's a standard HTTP response with Content-Type: text/event-stream. The server writes events. The client reads them. The browser handles reconnection automatically. It works through every proxy, load balancer, and CDN that supports HTTP.

For progress updates where only the server needs to push data, SSE is the right choice.

The Server: A Streaming API Route

In Next.js App Router, you can return a ReadableStream from a route handler. Here's the analysis endpoint that streams progress events:

// app/api/analyze/route.ts
import { NextRequest } from "next/server";

interface ProgressEvent {
  step: string;
  progress: number;
  message: string;
}

interface CompleteEvent {
  step: "complete";
  progress: 100;
  result: AuditResult;
}

type AnalyzeEvent = ProgressEvent | CompleteEvent;

export async function POST(request: NextRequest) {
  const formData = await request.formData();
  const file = formData.get("file") as File;

  if (!file) {
    return Response.json(
      { error: "No file provided" },
      { status: 400 },
    );
  }

  const contract = await file.text();

  const stream = new ReadableStream({
    async start(controller) {
      const encoder = new TextEncoder();

      function sendEvent(event: AnalyzeEvent) {
        const data = JSON.stringify(event);
        controller.enqueue(
          encoder.encode(`data: ${data}\n\n`),
        );
      }

      try {
        sendEvent({
          step: "parsing",
          progress: 10,
          message: "Parsing contract...",
        });

        const parsed = parseContract(contract);

        sendEvent({
          step: "analyzing",
          progress: 30,
          message: `Analyzing ${parsed.name} with ${provider.model}...`,
        });

        const raw = await provider.analyze(
          SYSTEM_PROMPT,
          contract,
        );

        sendEvent({
          step: "validating",
          progress: 70,
          message: "Validating results...",
        });

        const result = parseAuditResult(raw);

        sendEvent({
          step: "formatting",
          progress: 90,
          message: "Formatting report...",
        });

        sendEvent({
          step: "complete",
          progress: 100,
          result,
        });
      } catch (err) {
        const message =
          err instanceof Error
            ? err.message
            : "Analysis failed";
        controller.enqueue(
          encoder.encode(
            `data: ${JSON.stringify({ step: "error", message })}\n\n`,
          ),
        );
      } finally {
        controller.close();
      }
    },
  });

  return new Response(stream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
      Connection: "keep-alive",
    },
  });
}

Each event follows the SSE format: data: <json>\n\n. The double newline is the event delimiter. The Cache-Control: no-cache header prevents proxies from buffering the stream. The Connection: keep-alive header keeps the connection open for the duration of the analysis.

The Client: Reading the Stream

The browser's EventSource API is designed for SSE, but it only supports GET requests. Since the analysis endpoint is a POST (it receives a file upload), we use the fetch API to read the stream directly:

async function analyzeContract(
  file: File,
  onProgress: (event: AnalyzeEvent) => void,
): Promise<AuditResult> {
  const formData = new FormData();
  formData.append("file", file);

  const response = await fetch("/api/analyze", {
    method: "POST",
    body: formData,
  });

  if (!response.ok) {
    throw new Error(`Upload failed: ${response.status}`);
  }

  const reader = response.body?.getReader();
  if (!reader) {
    throw new Error("No response body");
  }

  const decoder = new TextDecoder();
  let buffer = "";
  let finalResult: AuditResult | null = null;

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });

    const events = buffer.split("\n\n");
    // Keep the last incomplete chunk in the buffer
    buffer = events.pop() ?? "";

    for (const event of events) {
      const dataLine = event
        .split("\n")
        .find((line) => line.startsWith("data: "));
      if (!dataLine) continue;

      const json = dataLine.slice(6); // Remove "data: " prefix
      const parsed = JSON.parse(json) as AnalyzeEvent;

      onProgress(parsed);

      if (parsed.step === "complete") {
        finalResult = parsed.result;
      }
      if (parsed.step === "error") {
        throw new Error(parsed.message);
      }
    }
  }

  if (!finalResult) {
    throw new Error("Stream ended without result");
  }

  return finalResult;
}

The buffer handling is the tricky part. The stream delivers chunks of arbitrary size — a chunk might contain half an event, one event, or three events. By splitting on \n\n and keeping the last (possibly incomplete) chunk, you correctly parse events regardless of chunk boundaries.

The React Component

"use client";

import { useState, useCallback } from "react";

interface ProgressState {
  step: string;
  progress: number;
  message: string;
}

function UploadZone() {
  const [progress, setProgress] =
    useState<ProgressState | null>(null);
  const [result, setResult] =
    useState<AuditResult | null>(null);
  const [error, setError] = useState<string | null>(null);

  const handleFile = useCallback(async (file: File) => {
    setProgress(null);
    setResult(null);
    setError(null);

    try {
      const auditResult = await analyzeContract(
        file,
        (event) => {
          if (event.step !== "complete") {
            setProgress({
              step: event.step,
              progress: event.progress,
              message: event.message,
            });
          }
        },
      );
      setResult(auditResult);
    } catch (err) {
      setError(
        err instanceof Error
          ? err.message
          : "Unknown error",
      );
    } finally {
      setProgress(null);
    }
  }, []);

  return (
    <div>
      <FileDropzone onFile={handleFile} />

      {progress && (
        <div className="mt-4">
          <div className="flex justify-between text-sm">
            <span>{progress.message}</span>
            <span>{progress.progress}%</span>
          </div>
          <div className="mt-1 h-2 rounded bg-gray-200">
            <div
              className="h-full rounded bg-blue-500 transition-all duration-500 ease-out"
              style={{ width: `${progress.progress}%` }}
            />
          </div>
        </div>
      )}

      {error && (
        <div className="mt-4 rounded bg-red-50 p-3 text-red-700">
          {error}
        </div>
      )}

      {result && <AuditReport result={result} />}
    </div>
  );
}

The transition-all duration-500 ease-out on the progress bar is what makes it feel smooth. Without it, the bar jumps from 10% to 30% to 70% in discrete steps. With the CSS transition, it animates between values, giving the impression of continuous progress even though the server only sends a handful of events.

Gotchas

Vercel's streaming timeout. On Vercel's Hobby plan, serverless functions time out at 10 seconds. Pro plan gives you 60 seconds. For long-running LLM analysis, you might need Vercel Functions with maxDuration set, or a separate backend.

Buffering by reverse proxies. Some proxies (nginx, Cloudflare) buffer responses by default. The X-Accel-Buffering: no header disables nginx buffering. Cloudflare respects Cache-Control: no-cache for SSE.

Error after partial stream. If the server errors after sending some events, the response already has a 200 status code. You can't change it. Handle errors as events in the stream, not as HTTP status codes.

Browser connection limits. Browsers limit concurrent connections per domain (typically 6 for HTTP/1.1). Each SSE connection counts. This rarely matters for single-user tools, but keep it in mind for dashboards with multiple streams.

SSE is one of those underused web APIs that solves a specific problem well. For progress tracking in AI-powered tools — where the server does heavy work and the client waits — it's the simplest path from "loading spinner" to "real-time feedback."