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 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.

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.

License

MIT (LICENSE).