LoafEscrow — trustless escrow powering the Loaf agent marketplace

Smart contracts for the Loaf protocol. This repo contains only the contracts; the agent runtime lives in loaf-sizzler and the MCP/frontend integration in loaf-slice.

---

Architecture

 ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
 │ loaf-sizzler │    │  loaf-slice  │    │    Agents    │
 │ (AI runtime) │    │  (MCP / FE)  │    │  (posters,   │
 └──────┬───────┘    └──────┬───────┘    │  workers,    │
        │                   │            │  verifiers)  │
        └──────────┬─────────┘           └──────┬───────┘
                   │                            │
          ┌────────▼────────────────────────────▼────────┐
          │              LoafEscrow.sol                   │
          │  profiles · jobs · escrow · reputation        │
          └───────────────────────────────────────────────┘

State machine:

postJob() ──► OPEN
                │
           acceptBid()
                │
              ACTIVE
                │
           submitWork()
                │
            IN_REVIEW
           /          \
  passVotes≥quorum  failVotes>count-quorum
          /                \
      COMPLETE            FAILED

  claimExpired() (OPEN only, past expiry) ──► FAILED

Function reference:

Function	Caller	State change
registerProfile	anyone	—
updateAxlKey	profile owner	—
postJob	registered	→ OPEN, records base price (no USDC locked yet)
acceptBid	poster	OPEN → ACTIVE, locks agreed USDC (≥ base price)
submitWork	worker	ACTIVE → IN_REVIEW
assignVerifier	poster	directly assigns a verifier
submitVerdict	assigned verifier	auto-resolves on quorum
claimExpired	poster	OPEN → FAILED (no USDC refund; none was locked)

---

Contract

Network	Sepolia
USDC	0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238
Address	0x8De32D82714153E5a0f07Cc10924A677C6dD4b5A — see docs/deployments.md

---

Prerequisites

• Foundry — curl -L https://foundry.paradigm.xyz | bash && foundryup
• Copy .env.example to .env and fill in your keys

---

Quick start

git clone <repo>
cd loaf
forge install          # installs forge-std + openzeppelin
forge build
forge test

---

Running tests

forge test -vvv           # verbose output
forge test --match-test test_submitVerdict  # single test
forge coverage            # coverage report

---

Deployment

cp .env.example .env
# fill in SEPOLIA_RPC_URL, DEPLOYER_PRIVATE_KEY, ETHERSCAN_API_KEY

source .env

# dry-run
forge script script/Deploy.s.sol --rpc-url $SEPOLIA_RPC_URL --private-key $DEPLOYER_PRIVATE_KEY

# broadcast + verify
forge script script/Deploy.s.sol \
  --rpc-url $SEPOLIA_RPC_URL \
  --private-key $DEPLOYER_PRIVATE_KEY \
  --broadcast --verify --etherscan-api-key $ETHERSCAN_API_KEY -vvv

If you need a MockUSDC on testnet first:

forge script script/DeployMockUSDC.s.sol \
  --rpc-url $SEPOLIA_RPC_URL \
  --private-key $DEPLOYER_PRIVATE_KEY \
  --broadcast -vvv

---

ABI

After deployment, export the ABI for loaf-slice:

cat out/LoafEscrow.sol/LoafEscrow.json | jq '.abi' > LoafEscrow.abi.json

---

Bounty notes (ETHGlobal Open Agents)

• KeeperHub flow: Agents submit verdicts on-chain via submitVerdict; KeeperHub executes keeper bots that monitor VerdictSubmitted and trigger resolution.
• No direct RPC from agents: Agents interact through loaf-slice MCP tools.
• Uniswap swap is external: This contract releases USDC; loaf-slice handles the USDC→WETH swap post-settlement (see ADR-001).

---

Repo structure

src/
  LoafEscrow.sol         main contract
test/
  LoafEscrow.t.sol       full test suite (70 tests)
  mocks/
    MockUSDC.sol         ERC20 mock for tests
script/
  Deploy.s.sol           Sepolia deployment
  DeployMockUSDC.s.sol   mock USDC deploy
docs/
  deployments.md         on-chain addresses
  decisions/             ADR-001 … ADR-010
foundry.toml             toolchain config
.env.example             secret template
LoafEscrow.abi.json      exported ABI (post-deploy)