StellarWork

StellarWork is an open-source decentralized freelance marketplace on Stellar. Payments are held in Soroban escrow and released by state transitions, not platform custody logic.

Repository Layout

stellarwork
├── contracts/escrow
├── frontend
└── docs

Local DevNet (Isolated Testing)

For fully isolated contract testing without relying on public testnets, use the devnet scripts:

# 1. Set up a local Soroban devnet (requires Docker)
./scripts/setup-devnet.sh

# 2. Reset the devnet state when needed
./scripts/reset-devnet.sh

# 3. Run tests against the local devnet
./scripts/run-tests-local.sh

The setup script:

• Starts a Stellar Quickstart container with a standalone network
• Funds a test admin account
• Deploys and initializes the escrow contract
• Saves configuration to .env.dev

Local Setup

Using Docker (Recommended)

You can spin up the full development environment with a single command (requires Docker installed):

cp frontend/.env.example frontend/.env.local
docker compose up -d

This starts:

• frontend — Next.js dev server at http://localhost:3000 with hot-reload
• contract-builder — Rust + Soroban CLI environment for building/testing contracts
• stellar-quickstart — Local Stellar dev network with Soroban RPC at http://localhost:8000

File changes in frontend/ will trigger hot-reload inside the container automatically.

To run contract tests inside the container:

docker compose exec contract-builder cargo test --manifest-path contracts/escrow/Cargo.toml

Common commands are also available via Makefile:

make up      # Start all services
make down    # Stop all services
make test-contract  # Run contract unit tests
make test-frontend  # Run frontend unit tests

Manual Setup

1) Contract

cd contracts/escrow
cargo test

2) Frontend

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

Open http://localhost:3000.

3) Pre-commit Hooks (Optional)

To automate quality checks, see the pre-commit setup guide in the contribution docs.

Deploy Contract to Stellar Testnet (Step-by-Step)

This walkthrough takes you from build to frontend integration with copy-pasteable commands.

1) Prerequisites

• Install Soroban CLI (docs).
• Have a funded Stellar Testnet account.
• Configure a Soroban identity:

soroban config identity generate stellarwork-admin
soroban config identity address stellarwork-admin

• Add Testnet network (if not already configured):

soroban config network add testnet \
  --rpc-url https://soroban-testnet.stellar.org \
  --network-passphrase "Test SDF Network ; September 2015"

2) Build the Escrow Contract

cd contracts/escrow
cargo test
soroban contract build

Expected wasm output:

target/wasm32-unknown-unknown/release/escrow.wasm

3) Deploy to Testnet

cd contracts/escrow
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/escrow.wasm \
  --source stellarwork-admin \
  --network testnet

Save the returned contract ID (for example CC...).

4) Initialize Contract State

initialize(admin, native_token) must be called once.

1. Determine your admin address:

soroban config identity address stellarwork-admin

2. Choose a native token contract address on testnet (or your token contract).
3. Invoke initialize:

soroban contract invoke \
  --id <CONTRACT_ID> \
  --source stellarwork-admin \
  --network testnet \
  -- initialize \
  --admin <ADMIN_ADDRESS> \
  --native_token <NATIVE_TOKEN_CONTRACT_ADDRESS>

5) Configure Frontend Environment

cd frontend
cp .env.example .env.local

Set at minimum:

NEXT_PUBLIC_CONTRACT_ID=<CONTRACT_ID>
NEXT_PUBLIC_NETWORK=testnet
NEXT_PUBLIC_SOROBAN_RPC=https://soroban-testnet.stellar.org

See docs/environments.md for the complete environment variable reference, defaults, and Testnet/Mainnet notes.

Then run:

npm install
npm run dev

Open http://localhost:3000.

6) Verify Deployment

Read methods should return values without requiring a signed transaction:

soroban contract invoke \
  --id <CONTRACT_ID> \
  --network testnet \
  -- get_job_count

Troubleshooting

• HostError: Error(Contract, #...) on write calls: check caller authorization and method preconditions.
• NEXT_PUBLIC_CONTRACT_ID is not configured: confirm frontend/.env.local and restart npm run dev.
• contract not found / RPC errors: verify --network testnet and correct contract ID.
• Initialize appears to do nothing: this contract ignores repeated initialize calls after first setup.
• Insufficient balance on deploy/invoke: fund the identity from Stellar Friendbot and retry.

Current Feature Set

• Core escrow lifecycle (post_job, accept_job, submit_work, approve_work, cancel_job)
• Freelancer-initiated job cancellation with penalty (freelancer_cancel_job)
• On-chain job storage and count queries
• Multi-token support with admin-managed whitelist (add_allowed_token, remove_allowed_token)
• IPFS-based job description storage via web3.storage (with localStorage fallback)
• Platform fee accounting (2.5%)
• Dispute resolution with flexible client/freelancer splits
• Contract upgrade mechanism with 24-hour timelock
• Contract unit tests for core paths
• Core pages: /, /post-job, /job/[id], /dashboard, /admin, /disputes, /profile/[address]

Environment Configuration

Copy frontend/.env.example to frontend/.env.local and set the required variables:

Variable	Required	Default	Description
NEXT_PUBLIC_CONTRACT_ID	Yes	—	Deployed escrow contract ID
NEXT_PUBLIC_NETWORK	No	testnet	testnet or mainnet
NEXT_PUBLIC_SOROBAN_RPC	No	https://soroban-testnet.stellar.org	Soroban RPC endpoint
NEXT_PUBLIC_NATIVE_TOKEN	No	—	Default token address for post-job form
NEXT_PUBLIC_ADMIN_ADDRESS	No	—	Admin wallet for UI access control
NEXT_PUBLIC_IPFS_GATEWAY_URL	No	https://dweb.link/ipfs/	IPFS gateway for descriptions
NEXT_PUBLIC_WEB3_STORAGE_TOKEN	No	—	Web3.storage token for IPFS uploads

The frontend validates configuration at runtime via lib/config.ts. Missing required variables produce clear error messages. See docs/environments.md for the full reference including Testnet/Mainnet notes.

Vercel Deployment

The frontend is deployed to Vercel automatically:

• Production — every push to main that changes frontend/** triggers a production deployment.
• Preview — every pull request gets a unique preview URL, posted as a comment by the GitHub Actions bot.

See docs/DEPLOY.md for the full setup guide (creating the Vercel project, required GitHub secrets, environment variable configuration, and troubleshooting).

For a command-only deployment reference, see docs/testnet-deployment-guide.md. For environment configuration, see docs/environments.md. For API reference, see docs/CONTRACT.md. For frontend architecture, see docs/FRONTEND_ARCHITECTURE.md. For third-party integration, see docs/INTEGRATION.md.

For the full documentation index, see docs/README.md.

Translation Status

StellarWork supports multiple languages. Community contributions to add or maintain translations are welcome — see docs/TRANSLATING.md for a step-by-step guide.

Locale	Language	Status	Maintainer
en	English	✅ Complete (reference)	Core team
es	Spanish	✅ Complete	Community

To add a new language, follow the translation guide.

Production Operations

For deploying and operating StellarWork in production, start with these three documents:

Document	Purpose
docs/DEPLOYMENT.md	Step-by-step production deployment: contract build/deploy/initialize, Vercel frontend, DNS/SSL, post-deploy verification
docs/OPS_RUNBOOK.md	Ongoing operations: monitoring signals, backup procedures, incident response, contract upgrades, regular maintenance
docs/PRODUCTION_CHECKLIST.md	Pre-launch checklist with sign-off table — complete before going live

Video Tutorials

Step-by-step video walkthroughs for the most common workflows. Videos are recorded on Stellar testnet — no real funds are used.

#	Title	Audience	Status
01	Getting Started: Connecting Your Wallet	All	Planned
02	Posting Your First Job	Clients	Planned
03	Finding and Accepting Jobs as a Freelancer	Freelancers	Planned
04	Completing a Job and Getting Paid	Freelancers	Planned
05	Managing Disputes	All	Planned

When videos are published, replace "Planned" with a link to the video (e.g., [Watch →](https://youtube.com/...)).

For recording setup, script templates, format guidelines, and closed captioning standards, see docs/VIDEO_TUTORIALS.md.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. All contributors are expected to uphold our community standards.

License

MIT (LICENSE).