Milestone-Gated Web3 Invoice & Payout Manager

The situation

Payments sit outside the work they pay for.

Cross-border freelance and project work lacks a neutral way to hold money — either the manager pays before seeing deliverables, or the freelancer delivers before being paid. A milestone-gated way to hold money removes both risks by locking funds and releasing them only when work is approved.

The system is deliberately split: everyday details are cheap to keep in a regular database, while money moves where anyone can check it.

Our approach

Money is moved into a holding arrangement when a project starts. Milestones are released one at a time, only when the manager approves, with the platform fee set when the project is funded. Unfinished milestones can be cancelled and money returned to the manager.

What we built

Holding arrangement

A single agreement holds the money state. Projects define a manager, freelancer, digital dollar address, milestone list and set fee percentage. The fixed digital dollar address stops unauthorized tokens, and the milestone list is limited to 50 to keep creation and refund steps manageable. Fees are limited to 10%.

Milestone steps

• createProject — manager adds all the money; the agreement checks the digital dollar address and limits milestones.
• approveMilestone — manager only; sends the money to the freelancer and the set fee to the fee receiver, recording the release.
• cancelProject — manager only; returns locked money for unfinished milestones, taking no fee.
• setFeeConfig — owner only; sets the fee receiver and rate for future projects; existing projects keep their set rate.

Regular database

Users, projects, milestones and a step-by-step record of agreement events live in a regular database, linked to agreement IDs and transaction numbers. A progress marker tracks the latest processed block so a background worker can match regular status against agreement events without duplicating records.

Frontend and setup

A web app with CSS, a sign-in system and built-in wallets, and tools for reading and writing to the agreement. Manager addresses can point to a shared-signature wallet connected through wallet links for multiple people to approve.

Safety and edge cases

• Duplicate protection: money changes use protections and careful ordering.
• Safe to repeat matching: the record is keyed by transaction number and step so repeats never make duplicate entries.
• Fail safely: if payment checking or an important connection is unavailable, the system does not invent a success result.
• Shared-signature support: manager can be a shared wallet, signed through wallet links.

Outcome

Money sits in a verifiable holding arrangement and is released milestone-by-milestone only on manager approval. Cancellations return unfinished money. Both parties have a single source of truth for money and work.