Trellis Trustless Milestone Escrow on Stellar Soroban LIVE ON TESTNET | Contract: CAUAO7C...

Trustless, milestone-based escrow for freelance and remote work — built on Stellar's Soroban smart contract platform.

---

The Problem

Remote work and freelance contracting run on trust that often doesn't exist between strangers across borders. Clients hesitate to pay upfront. Workers hesitate to deliver without payment guarantees. The usual fix — a centralized escrow middleman — adds fees, delays, and a single point of failure.

Trellis removes the middleman. Funds are locked on-chain, released milestone by milestone as work is verified, with a built-in dispute process if either party disagrees. No platform holds your money. The contract does.

This matters everywhere, but especially for contributors in emerging markets — where access to reliable, low-fee, borderless payment infrastructure can be the difference between taking on international work or not.

💡 Why Soroban?

Contracts are written in real Rust, compiled to WASM, and run on the Stellar network — which has fast finality, low fees (~fractions of a cent), and an established USDC presence via Circle's Stellar Asset Contract. This makes it well-suited for cross-border payment use cases.

---

Live on Testnet

LIVE ON STELLAR TESTNET Network: Test SDF Network ; September 2015 Contract: CAUAO7CYKULE2K4EJMQ6LLRUHP7Y7JYOH6G2VBXKYG7PTETE3UZ3DU7Q

A live test agreement exists on-chain and is queryable right now:

trellis status --agreement-id 0101010101010101010101010101010101010101010101010101010101010101

Attribute	Value
Contract ID	CAUAO7CYKULE2K4EJMQ6LLRUHP7Y7JYOH6G2VBXKYG7PTETE3UZ3DU7Q
Network	Stellar Testnet
Explorer	View on Stellar Lab

Full deployment details, every verified command, and step-by-step deployment instructions are in DEPLOYMENT.md.

---

How It Works

Trellis models a freelance engagement as an agreement made up of one or more milestones, each with its own funding, work submission, and release lifecycle.

PENDING FUNDED WORK SUBMITTED COMPLETED DISPUTED REFUNDED CANCELLED lock_funds submit_work approve & release cancel_unfunded raise_dispute raise_dispute resolve (refund) resolve (release) Payer action Payee action Either party Resolver action

The Roles

Role	Responsibility
Payer 🧑‍💼	Funds milestones and approves completed work
Payee 👨‍💻	Submits proof of completed work and receives payment on approval
Dispute Resolver ⚖️	A neutral third party who can rule on disputes, releasing funds to either side

The Guarantees

• ✅ Funds are held by the contract — not by either party or a platform
• ✅ Either party can raise a dispute — neither can unilaterally freeze funds by going silent
• ✅ Unfunded milestones can be cancelled — walk away cleanly with no cost
• ✅ Every state transition emits an on-chain event — off-chain clients track progress in real time without polling

---

Architecture

Trellis is a monorepo with three layers:

LAYER 1 · ON-CHAIN contracts/trellis_core/ Soroban Smart Contract (Rust → WASM) lib.rs types.rs storage.rs events.rs LAYER 2 · OFF-CHAIN cli/trellis_cli/ Command-Line Interface (Rust + clap + reqwest) main.rs config.rs rpc.rs LAYER 3 · WEB frontend/ Web Dashboard (React + Vite + TypeScript + Tailwind) App.tsx components/ lib/ Stellar Network

Contract Entrypoints

Function	Caller	Effect
init	Payer	Creates a new agreement with one or more milestones (each amount must be strictly positive)
lock_funds	Payer	Deposits funds for a milestone into the contract
submit_work	Payee	Submits proof of completed work for a funded milestone
approve_and_release	Payer	Approves submitted work, releases funds to payee
raise_dispute	Payer or Payee	Flags a milestone for resolver review
resolve_dispute	Dispute Resolver	Rules on a dispute — refunds payer or pays payee
cancel_unfunded_milestone	Payer	Cancels a milestone that was never funded
get_agreement	Anyone	Returns the full current state of an agreement (read-only)
get_total_amount	Anyone	Returns the agreement's total value — sum of all milestone amounts (read-only)
extend_agreement_ttl	Anyone	Renews an agreement's ledger TTL to avoid archival

📦 Storage Lifetime

Soroban archives persistent ledger entries once their TTL expires, so an agreement that is never touched would eventually be lost. Every state-mutating entrypoint renews the agreement's TTL to ~30 days automatically. Agreements that stay idle longer than that — a long delivery window, a stalled dispute — need extend_agreement_ttl called before the TTL runs out; any address may call it, and the caller pays the rent.

Tech Stack

Category	Technologies
Smart Contract	Soroban · soroban-sdk 22.x · Rust (#![no_std] → WASM)
CLI	clap 4 · clap_complete · reqwest · serde + serde_json · dotenvy
Frontend	React 19 · Vite · TypeScript · Tailwind CSS · React Router
Stellar SDK	@stellar/stellar-sdk · @stellar/freighter-api · Soroban RPC

---

Quickstart

Prerequisites

• Rust (stable toolchain)
• wasm32-unknown-unknown target: rustup target add wasm32-unknown-unknown
• stellar CLI 26.x+
• Node.js 20+ (for the frontend)

🖥️ Run the frontend locally

cd frontend
cp .env.example .env
npm install
npm run dev

Open http://localhost:5173 to see the animated landing page with the particle network background, typewriter effects, and full agreement management UI.

🛠️ Build and test the contract

cd contracts/trellis_core
cargo test

All 9 integration tests run in the Soroban sandbox — happy path, double-init protection, dispute resolution, milestone cancellation (including the state-transition guard on already-funded milestones), positive-amount validation on init, the pre-computed total_amount, and the get_agreement view function.

📦 Build everything at once

make build

Runs the contract WASM build, CLI binary build, and frontend bundle in sequence. See make help for all available targets.

Building the contract WASM

cd contracts/trellis_core
cargo rustc --manifest-path=Cargo.toml --crate-type=cdylib --target=wasm32-unknown-unknown --release

See DEPLOYMENT.md for the full deployment walkthrough and why this command is used instead of stellar contract build.

⌨️ CLI Usage

cd cli/trellis_cli
cargo build --release

export STELLAR_RPC_URL="https://soroban-testnet.stellar.org"
export STELLAR_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
export TRELLIS_CONTRACT_ID="CAUAO7CYKULE2K4EJMQ6LLRUHP7Y7JYOH6G2VBXKYG7PTETE3UZ3DU7Q"
export TRELLIS_SOURCE_KEY="<your stellar identity name>"

# Create a new agreement
trellis init \
  --agreement-id <hex-id> \
  --payer <payer-address> \
  --payee <payee-address> \
  --token <token-contract-address> \
  --resolver <resolver-address> \
  --milestones "1000,2000"

# Check status
trellis status --agreement-id <hex-id>

# Fund the first milestone
trellis lock-funds --agreement-id <hex-id> --milestone-id 0

All 8 CLI commands are implemented — init, lock-funds, submit-work, approve-release, raise-dispute, resolve-dispute, cancel-milestone, and status. See DEPLOYMENT.md for the full command reference.

Global Output Flags

These flags work with every command and can be combined with .env/env-var configuration:

# Preview without submitting
trellis lock-funds --agreement-id <hex-id> --milestone-id 0 --dry-run

# Machine-parseable JSON
trellis status --agreement-id <hex-id> --json

# Suppress everything except final JSON (implies --json)
trellis status --agreement-id <hex-id> --quiet

# Colorized summary
trellis status --agreement-id <hex-id> --human-readable   # or -H

--json takes priority over --human-readable when both are passed.

Shell Completions

# bash
trellis completion bash > /etc/bash_completion.d/trellis

# zsh
trellis completion zsh > "${fpath[1]}/_trellis"

# fish
trellis completion fish > ~/.config/fish/completions/trellis.fish

Supported shells: bash, zsh, fish, elvish, powershell.

---

Project Status

✅ Complete

• Core Soroban escrow contract — all 10 entrypoints implemented and tested
• Full state machine — happy path, dispute resolution, and cancellation paths
• Integration test suite — 9/9 passing in the Soroban sandbox
• Full CLI — all 8 commands wired end-to-end with JSON, dry-run, and human-readable output modes
• Deployed live on Stellar testnet — init and status verified against the live contract
• Frontend dashboard — 5 pages, 28 components, 12 custom hooks, animated particle network background
• Wallet connect — Freighter wallet integration with connection states
• Event feed — real-time on-chain event history per agreement
• Shell completions — bash, zsh, fish, elvish, powershell

🚧 Open for Contribution

Area	Description	Difficulty
Frontend — Agreement Status page	Polish and edge cases for live agreement state display	Intermediate
Frontend — Create Agreement form	Validation UX, milestone builder refinements	Intermediate
Frontend — Milestone actions	lock, submit, approve, dispute button workflows	Intermediate
Frontend — Event feed enhancements	Real-time updates, filtering, pagination	Intermediate
Native RPC client	Replace stellar CLI shell-out with native Rust HTTP client	Advanced
Documentation	CONTRIBUTING.md and contributor onboarding guide	Beginner

See Issues for the full task list — each issue has exact requirements, acceptance criteria, a suggested branch name, and a timeframe.

---

Contributing

Trellis is built in the open and welcomes contributors of all experience levels — from documentation and frontend components to contract enhancements and tooling.

1. Fork the repo and clone it locally
2. Browse open issues tagged good first issue or help wanted
3. Comment on the issue to claim it — wait for maintainer confirmation before starting
4. Branch: git checkout -b feat/your-feature-name
5. Verify: run cargo test in contracts/trellis_core
6. PR: open a PR referencing the issue with Closes #X

New to Soroban? Start with the official Soroban docs.
New to React + Stellar? Read through frontend/src/lib/config.ts and the Stellar SDK docs.

---

License

MIT — see LICENSE for the full text.

---

Built by Allen · Trellis Ecosystem ✦ Trustless Escrow for the Global Workforce ✦