Case study

Milestone Escrow

Base · ERC-4337 · NestJS · Solidity

SolidityFoundryNestJSTypeScriptBasePostgreSQLERC-4337pnpm

Key outcomes

WorkstreamEscrow contract: milestones, disputes, resolution, refunds
NestJS API: OTP/JWT sessions, SIWE wallet flow, escrow gateway + receipts
Postgres persistence, IP-aware OTP throttling, compliance policy package

The Problem

Freelance and contractor payment is a trust problem. Clients want to know their money is protected until work is delivered. Contractors want to know they will get paid when they deliver. Traditional escrow is expensive, slow, and requires a trusted third party.

On-chain escrow solves the trust problem but introduces new ones: wallet onboarding friction, gas abstraction, dispute resolution, and compliance. Most crypto escrow projects stop at the smart contract and leave these problems for someone else to solve.

This system addresses all of them.

What Was Built

Milestone Escrow is a production-grade monorepo built on Base (Ethereum L2) with five distinct packages:

  • packages/contracts — Solidity + Foundry: WorkstreamEscrow contract
  • services/api — NestJS API: auth, wallet, escrow orchestration
  • apps/web — Client-facing Next.js app
  • apps/admin — Internal operations dashboard
  • packages/compliance — Shared compliance policy and jurisdiction rules

The Smart Contract

WorkstreamEscrow handles the entire lifecycle of a milestone-based payment:

  • Funding — client deposits funds into the contract for a specific workstream
  • Milestone release — funds are released per milestone upon contractor completion
  • Disputes — either party can raise a dispute; a resolver (multisig or oracle) decides
  • Refunds — unfunded milestones or resolved-in-client-favor disputes trigger refund paths

Every state transition emits events. The API listens for these events and updates its local record—providing fast UI reads without hitting the chain on every request.

ERC-4337 Smart Accounts

Standard wallet onboarding requires users to manage private keys from day one. ERC-4337 (account abstraction) allows the platform to provision a smart account for each user—a contract wallet with programmable rules.

The wallet API:

  1. Verifies wallet ownership via SIWE (Sign-In with Ethereum)
  2. Provisions a deterministic smart account address (the same address every time, derived from the user's signing key)
  3. Manages a sponsorship policy so gas fees can be abstracted away for new users
  4. Routes transactions through an execution wallet under platform control

This means a user can start using the escrow before they have ETH for gas—the platform sponsors early transactions until the user's account has sufficient balance.

Auth Architecture

The auth system is more complex than typical because it must support both web2 sessions (email/OTP) and web3 wallet proofs (SIWE):

  • OTP login: email-delivered one-time code with IP-aware rate limiting, relay-mode delivery
  • JWT sessions: rotating refresh tokens with replay-triggered revocation
  • SIWE flow: wallet ownership proof that upgrades a session to a verified wallet-linked account

Both session types share the same JWT validation and expiry logic—the difference is how they are initiated, not how they are enforced.

Key Engineering Decisions

Foundry for contracts. Faster test iteration than Hardhat for pure Solidity work. The test suite covers happy path, dispute resolution, and refund scenarios with fuzz inputs.

NestJS for the API. The module system and dependency injection made it straightforward to compose auth, wallet, and escrow logic as separate services with clean interfaces.

Compliance as a package. Jurisdiction rules and policy checks live in packages/compliance—imported by both the API and the admin app. A single change to a compliance rule propagates everywhere.

Scope

  • Foundry contract workspace with tests for happy-path and refund scenarios.
  • Auth: rotating refresh tokens with replay-triggered revocation, relay-mode OTP email, validated JWT/session/OTP config and rate limits.
  • Wallet API: SIWE ownership proof, deterministic smart-account provisioning, sponsorship policy, default execution-wallet management.
  • Escrow orchestration submits lifecycle actions through a contract gateway, waits for confirmed receipts, and persists execution history.
  • Monorepo layout: packages/contracts, services/api, apps/web & admin, packages/compliance—documented architecture and execution roadmap.
Like what you see?

Waqas Raza

AI-Native Full-Stack Engineer. Top Rated on Upwork · $180K+ earned · 93% job success. I build production AI agents, LLM systems, Web3 platforms, and full-stack applications.

Hire me on Upwork