Web3

FiduWork Escrow Architecture Deep Dive: How Contracts Work

FiduWork escrow architecture deep dive: USDC milestone state machine, Aragon-OSx juror panel selection, 5% stake mechanics, and 30/70 redistribution on-chain.

JUL 13, 2026

Share Post Share

TL;DR

USDC milestone escrow deployed on Sepolia beta, non-custodial, state-machine driven.
Aragon-OSx panels of 3, 5, or 7 jurors resolve disputes on-chain inside a 72 hour window.
Both parties post a 5% USDC stake; the settlement pays 30% to jurors and 70% to the winner.
Design goal: keep custody in code, keep reputation in the wallet, keep the platform out of every value transfer.

FiduWork moves value between two wallets through a contract, not through the platform. The contract holds USDC, tracks milestones, and either releases funds on approval or routes them to a juror panel on dispute. Everything else in the product is user experience around that primitive.

This piece walks through the escrow contract at the state-machine level, describes how the panel is drawn and paid, discusses the failure modes that shaped the design, and lists what an evaluator or auditor should verify before recommending the system for real budget.

What is the FiduWork escrow smart contract?

A non-custodial contract that holds USDC per milestone, moves through 6 fixed states, and delegates dispute rulings to an Aragon-OSx panel of 3, 5, or 7 jurors. The Ethereum whitepaper frames the atomicity guarantee behind this pattern. Every job produces a contract instance keyed to the client wallet, the freelancer wallet, and the milestone schedule.

Roles the contract knows

Client: the wallet that funds the milestone.
Freelancer: the wallet that submits deliverables.
Juror panel: a set of wallets drawn by governance for dispute resolution.
Protocol: a fee sink for the flat 10% commission on approved contracts.

Data the contract stores

Milestone amount in USDC.
Milestone state.
Deadline timestamps.
Stake balances per party.
Panel address and vote outcome when relevant.

How does the USDC milestone state machine work?

The state machine has six states and enforces one transition per action. The Solidity documentation on common patterns is the reference for state-machine implementation patterns in EVM contracts, and the OpenZeppelin ERC-20 documentation is the reference for safe USDC token movement.

State list

Draft · Enters via: Constructor · Exits to: `Funded` · Notes: Terms signed, no funds moved
Funded · Enters via: `deposit()` by client · Exits to: `Submitted` or `Disputed` · Notes: Client transfers USDC in
Submitted · Enters via: `submitMilestone()` by freelancer · Exits to: `Approved`, `Disputed`, or `AutoApproved` · Notes: Deliverables link stored
Approved · Enters via: `approve()` by client or auto-timer · Exits to: `Settled` · Notes: Fee applied, funds released
Disputed · Enters via: `raiseDispute()` by either side · Exits to: `PanelRuled` · Notes: Panel drawn from governance
Settled · Enters via: `release()` internal call · Exits to: terminal · Notes: Funds transferred, credentials written

Auto-approval timer

If the client fails to act inside the milestone window, the state transitions to AutoApproved and moves to Settled. This prevents indefinite escrow holding, which is the single most common failure mode in traditional freelance escrow.

Events emitted per transition

Every state change emits a topic-hashed event so indexers can build downstream views without hitting private endpoints. MilestoneFunded, MilestoneSubmitted, MilestoneApproved, DisputeRaised, PanelRuled, and MilestoneSettled cover the primary transitions. Indexers subscribe to the escrow factory and receive the full lifecycle per contract instance, which is the same pattern the Trail of Bits research on DeFi dimensional analysis recommends for auditability in DeFi.

Reentrancy posture

release() follows the checks-effects-interactions pattern. State is finalized before the token transfer. Because USDC is a standard ERC-20, the OpenZeppelin ERC-20 documentation recommendations apply directly: use safeTransfer, avoid raw calls, and treat every external interaction as untrusted.

Storage layout notes

Milestone deadlines and stake balances are packed to reduce SLOAD cost on the hot path. Panel address is stored only when a dispute is filed, which keeps the common approval path in a single storage slot for gas efficiency. The Solidity common patterns documentation covers the state-machine idioms in more detail.

Why non-custodial custody instead of platform-held funds?

Custodial models concentrate risk and regulatory surface for the platform. The Circle USDC documentation shows programmatic USDC transfers on EVM chains, and keeping custody in contract logic means the $2.4M+ moved on Sepolia never touched a FiduWork account. That has 3 engineering consequences worth naming.

Consequence one: audit surface narrows

The auditable surface becomes the contract source rather than a platform database. Any auditor can inspect the deployed bytecode and reproduce state transitions in a local fork without platform cooperation.

Consequence two: incident recovery changes

There is no support ticket that releases funds. Recovery is either the panel path or a governance-authorized contract upgrade with time-locked migration. This is why the panel window is short.

Consequence three: composability opens

Because state changes emit events, integrators can index them the same way the Trail of Bits research on DeFi dimensional analysis recommends indexing DeFi protocol events. Downstream indexers can build treasury reports, tax exports, or reputation graphs without asking the platform for CSV dumps.

How does the Aragon-OSx juror panel resolve disputes?

By running a fixed-window vote inside a governance plugin drawn from a juror pool. The Aragon-OSx documentation home covers plugin composition. On FiduWork the escrow contract calls a panel plugin that selects 3, 5, or 7 wallets at random from a staked juror registry, opens a vote, and closes it after 72 hours.

Selection rule

The panel size scales with dispute value. Small milestones draw three jurors; medium value draws five; large value draws seven. Odd sizes remove tie handling.

Voting rule

Each juror casts one vote for client or freelancer. The winning side receives the milestone balance minus commission and stake redistribution.

Timeout rule

If a juror fails to vote inside the window they forfeit their share of the juror payout. That is the incentive that drives responsiveness.

Why Aragon-OSx

Because the plugin model separates governance logic from escrow logic, upgrades to the panel do not require redeploying the escrow. The pattern is documented at the framework link above and is battle-tested by several DAOs using the same base plugin surface.

Juror registry mechanics

Any wallet can stake USDC into the juror registry to become eligible for panel selection. Stake size affects selection probability inside a fair-random distribution. A juror who fails to vote inside the 72 hour window forfeits their share of the payout for that case. A juror who votes against the eventual majority still receives their share; the design does not punish dissent because dissent is an evidence signal for panel-size scaling on future high-value disputes.

Random selection

Panel selection uses a verifiable randomness source anchored on-chain rather than a client-provided seed. That removes the classic front-running vector where a party observes selection off-chain and grinds a favorable panel address. Anyone can reproduce the selection by replaying the block that opened the dispute.

Panel size scaling

Small milestones (under a defined USDC threshold) draw three jurors. Medium value draws five. Large value draws seven. The thresholds are governance-tunable through the same Aragon-OSx plugin surface, which means panel sizing can be adjusted without touching the escrow contract itself.

What happens to the 5% stake on a dispute?

Both parties lose their 5% stake at the moment of dispute filing. That stake pool is then redistributed 30% to the juror panel and 70% to the winning party at settlement. The design mirrors incentive-aligned dispute economies documented in the Immunefi research pages for bug-bounty programs. Symmetric stakes on both sides remove weaponized-dispute incentives at the last milestone.

Purpose of the client-side stake

It discourages weaponized disputes at the last milestone. A client who tries to trigger a dispute in bad faith at settlement now forfeits capital regardless of outcome.

Purpose of the freelancer-side stake

It discourages spurious dispute escalations by contractors who lose an approval decision. Both stakes must be symmetric or one side has an incentive to escalate first.

Payout accounting

Milestone balance · Amount: 100% of deposit
Protocol commission on approved · Amount: 10% flat
Client stake at dispute · Amount: 5% USDC
Freelancer stake at dispute · Amount: 5% USDC
Juror share of stake pool · Amount: 30%
Winner share of stake pool · Amount: 70%
Loser share of stake pool · Amount: 0%

What are the trust assumptions behind the design?

Every escrow rests on 4 trust assumptions that decide what breaks first when something goes wrong. The OpenZeppelin ERC-20 documentation covers the safe transfer patterns behind assumption one, and the following list names each explicitly so an evaluator can decide whether the design fits their internal risk tolerance without guessing.

Assumption one: the USDC contract behaves as specified

The escrow inherits every risk that ships with USDC itself. If the issuer freezes an address, funds bound to that address stall. This risk is documented in the Circle USDC developer documentation. The mitigation is choosing settlement tokens with predictable governance and monitoring the issuer freeze list at integration time.

Assumption two: the panel plugin cannot be captured

Panel selection uses on-chain randomness, and juror stake sizing limits the marginal cost of Sybil attack. The mitigation is minimum stake thresholds and rotation across a wide juror pool. Integrators worried about capture should review the current juror registry size and the stake distribution before recommending the panel for high-value milestones.

Assumption three: chain liveness holds inside the panel window

The 72 hour vote window assumes the underlying chain is producing blocks. Under a prolonged outage the timer stalls with the funds. The mitigation is deploying on chains with high liveness records and setting operational alerts on missed block intervals during dispute windows.

Assumption four: governance upgrades are honest

Contract upgrades follow a time-locked path with public visibility. The mitigation is publishing every upgrade proposal and giving the community time to react before a new plugin version becomes live.

How do the failure modes compare to alternative escrow designs?

The dominant designs in the wild are custodial platform escrow, multisig-arbitrated escrow, and pure smart contract escrow with no dispute path. The Trail of Bits research on DeFi dimensional analysis shows how subtle unit errors surface in on-chain finance, and each escrow design below has 1 or more failure modes FiduWork tries to mitigate.

Custodial platform escrow

Failure mode: platform insolvency or account freeze locks funds. FiduWork removes this by keeping custody in a contract.

Multisig-arbitrated escrow

Failure mode: the multisig signers are known and can be socially targeted. FiduWork removes this by drawing the panel randomly from a staked pool at dispute time.

Pure smart contract escrow with no dispute path

Failure mode: any disagreement forces a fork or off-chain settlement. FiduWork adds the on-chain panel to keep resolution inside the contract.

On-chain governance escrow with unbounded vote

Failure mode: the vote never closes and the funds sit indefinitely. FiduWork adds the 72 hour window and the juror payout forfeiture rule.

Optimistic release with fraud proofs

Failure mode: optimistic designs require the challenger to notice within the window and post capital, which shifts monitoring cost onto every honest party. FiduWork keeps a deterministic auto-approval window on the approval path but replaces the challenge-response game on the dispute path with a bounded panel vote. That trades some throughput for a shorter, capped worst-case latency.

Fully manual signing threshold

Failure mode: any escrow that requires both parties to co-sign every release becomes a liveness hazard when one party goes dark. FiduWork resolves this with the auto-approval timer and the panel path, so a silent client never traps a delivered milestone forever.

Platform Signal. The Sepolia beta processed $2.4M+ in USDC across 1,200+ freelancer profiles with a 72 hour panel window and a 30/70 stake redistribution.

What regulations govern this architecture?

2 regimes matter for anyone integrating the contracts at production scale: EU MiCA and FATF. The EU MiCA Regulation (EU) 2023/1114 governs authorisation of crypto-asset service providers, and non-custodial escrow generally falls outside the CASP definition even though the authorisation regime still shapes any custodial component of the wider product.

EU MiCA

The EU MiCA Regulation (EU) 2023/1114 Article 60 governs authorisation of crypto-asset service providers, which includes custodial payment services. Non-custodial escrow generally falls outside the CASP definition, but the authorisation regime shapes how any custodial component of the wider product must be handled.

FATF Recommendation 15

The FATF Virtual Asset guidance sets the global baseline for Virtual Asset Service Provider definitions and travel-rule expectations. Integrators handling identity verification or fiat on-ramps around the escrow flow should treat this as required reading.

Compliance corner

Escrow contract logic is jurisdiction neutral. Everything that touches identity, on-ramp, off-ramp, or tax reporting is not. Counsel review is expected before running material USDC contractor spend across borders.

Sanctions screening

Integrators pushing enterprise volume should screen client and freelancer wallets against the OFAC SDN list at contract creation. This is not part of the escrow itself, which stays neutral, but it is standard operating procedure for any regulated organization deploying value transfers through the contracts.

Tax reporting hooks

Every settlement event carries the payer wallet, payee wallet, and amount, which are the primary fields required for downstream 1099 style reporting in some jurisdictions. Because the events are public an internal indexer can produce annual reports without asking the platform for a data pull.

Data protection notes

No personal data touches the escrow contract. Identity attestations sit off-chain and reference the wallet address only. This keeps the design compatible with data minimisation principles common across privacy regimes, and it reduces the scope of any breach involving the platform itself.

How can auditors and integrators verify the contracts?

By replaying state transitions in a local Sepolia fork and checking the events emitted at every transition. The Aragon-OSx documentation home covers the plugin surface that the panel selection reads from, so an auditor can reproduce the 3-5-7 panel draw for any historical dispute inside a single afternoon of work.

Verification steps

Fork Sepolia at a known block.
Instantiate a contract with test client, freelancer, and juror addresses.
Walk the state machine from Draft through Funded, Submitted, Approved, and Settled.
Replay the dispute path from Funded through Disputed, PanelRuled, and Settled with panel sizes of 3, 5, and 7.
Check every emitted event against expected topic hashes.
Run an unbounded fuzzer over the milestone deadline and juror timeout variables.

What to red-team

Reentrancy at release() given USDC is standard ERC-20; the OpenZeppelin ERC-20 docs cover the safe patterns.
Panel replay after upgrade of the panel plugin.
Auto-approval timer skew under chain reorg.

What to publish

Every audited contract deployment addresses, panel plugin version, and juror registry snapshot at the time of audit. Reproducibility is the only meaningful trust signal for evaluators.

Gas cost profile on Sepolia

Approval path calls (fund, submit, approve, settle) sit well within typical L1 gas envelopes because storage writes are packed and the token transfer is a single ERC-20 call. Dispute path is heavier because it invokes the panel plugin and records vote tallies. Integrators building custom flows on top of the escrow should benchmark on Sepolia at production milestone sizes before extrapolating to a target L2 or mainnet.

Indexer patterns for treasury reporting

Because every state change emits an event, treasury teams can build reconciliation views by subscribing to the escrow factory and grouping events by client wallet. Milestone approval events convert cleanly into GL entries. Dispute events convert into contingent liability entries until settlement. The Circle USDC documentation covers the token-side accounting semantics that pair with these events.

What ships with the audit package

An audit deliverable for an evaluator recommending FiduWork internally usually contains contract source, deployed addresses, panel plugin version, juror registry snapshot, event topic hash table, and a reproducible test suite. Reviewers can then run the state-machine walk from Draft through Settled with both approval and dispute branches inside a single afternoon.

Where to go next on FiduWork

Read the protocol documentation for the current contract addresses, the on-chain escrow explainer, and the dispute resolution jury deep dive for panel mechanics in production.

Review Our Smart Contract Docs. Inspect the deployed Sepolia contracts and reproduce the state-machine transitions in a local fork. Open the app.

Sources

Update Log

2026-07-14: Published.