Development Environment Setup

This guide covers setting up a full local development environment for the COMEBACKHERE protocol, spanning the contracts, backend, and frontend repositories.

Prerequisites

Rust 1.70+ with wasm32-unknown-unknown target:

rustup install stable
rustup target add wasm32-unknown-unknown

Soroban CLI: cargo install soroban-cli
Node.js 18+ (for frontend)
Docker (for local Soroban sandbox)
Stellar testnet account with funded testnet USDC

Directory Layout

Create a workspace directory and clone in this order:

~/comebackhere/
  ├── COMEBACKHERE-contracts/   # Smart contracts repo
  ├── COMEBACKHERE/             # Tooling, scripts, ABIs repo
  ├── comebackhere-backend/     # Backend API
  └── comebackhere-frontend/    # Frontend UI

mkdir ~/comebackhere && cd ~/comebackhere
git clone https://github.com/dreamgeneX/COMEBACKHERE-contracts.git
git clone https://github.com/dreamgeneX/COMEBACKHERE.git
git clone https://github.com/dreamgeneX/comebackhere-backend.git
git clone https://github.com/dreamgeneX/comebackhere-frontend.git

Local Soroban Sandbox

Start a local Soroban sandbox for testing without testnet:

soroban-cli start --standalone

This runs Soroban RPC on http://localhost:8000 and Horizon on http://localhost:8001.

Alternatively, start the complete stack via Docker Compose:

docker-compose up -d

Expected `docker-compose ps` Output

When all services initialize successfully, docker-compose ps reports healthy states:

NAME                      IMAGE                       COMMAND                  SERVICE    CREATED          STATUS                    PORTS
comebackhere-backend-1    comebackhere-backend        "docker-entrypoint.s…"   backend    15 seconds ago   Up 14 seconds (healthy)   0.0.0.0:3001->3001/tcp
comebackhere-frontend-1   comebackhere-frontend       "/bin/sh -c 'npm run…"   frontend   15 seconds ago   Up 14 seconds (healthy)   0.0.0.0:5173->5173/tcp
comebackhere-mongodb-1    mongo:7                     "docker-entrypoint.s…"   mongodb    15 seconds ago   Up 15 seconds (healthy)   0.0.0.0:27017->27017/tcp
comebackhere-redis-1      redis:7-alpine              "docker-entrypoint.s…"   redis      15 seconds ago   Up 15 seconds (healthy)   0.0.0.0:6379->6379/tcp
comebackhere-soroban-1    stellar/quickstart:latest   "/start standalone"      soroban    15 seconds ago   Up 15 seconds (healthy)   0.0.0.0:8000->8000/tcp, 0.0.0.0:11625-11626->11625-11626/tcp

Service Health Checks & Expected Output

Validate individual service health:

Soroban Node / RPC (http://localhost:8000):

curl -s http://localhost:8000/health
# Expected output:
# {"status":"healthy"}

Redis (localhost:6379):

docker-compose exec -T redis redis-cli ping
# Expected output:
# PONG

MongoDB (localhost:27017):

docker-compose exec -T mongodb mongosh --eval "db.adminCommand('ping')" --quiet
# Expected output:
# { ok: 1 }

Backend API (http://localhost:3001):

curl -s http://localhost:3001/health/rpc
# Expected output:
# {"status":"ok"}

Frontend UI (http://localhost:5173):

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5173/
# Expected output:
# 200

Pre-Flight Verification Script

Run this verification block before running app-specific commands or tests:

echo "Testing local development stack health..."
curl -sf http://localhost:8000/health > /dev/null && echo "✔ Soroban RPC is healthy"
docker-compose exec -T redis redis-cli ping 2>/dev/null | grep -q "PONG" && echo "✔ Redis is healthy"
docker-compose exec -T mongodb mongosh --eval "db.adminCommand('ping')" --quiet 2>/dev/null | grep -q "1" && echo "✔ MongoDB is healthy"
curl -sf http://localhost:3001/health/rpc > /dev/null && echo "✔ Backend service is healthy"
curl -sf -o /dev/null http://localhost:5173/ && echo "✔ Frontend UI is responsive"
echo "All services verified."

Environment Setup

Contracts

Copy the testnet configuration and generate a test account:

cd COMEBACKHERE
cp .env.testnet.example .env.testnet

Generate a new testnet keypair for local testing:

soroban config identity generate dev
soroban config set --scope testnet RPC_URL http://localhost:8000
soroban config set --scope testnet NETWORK_PASSPHRASE "Standalone Network ; February 2025"

Export your account ID for use in backend/frontend configuration:

ADMIN_PUBLIC_KEY=$(soroban config identity show dev)
echo "ADMIN_PUBLIC_KEY=$ADMIN_PUBLIC_KEY"

Deploy Contracts Locally

cd COMEBACKHERE

# Build WASM artifacts (from the contracts repo)
(cd ../COMEBACKHERE-contracts && cargo build --target wasm32-unknown-unknown --release)

# Deploy to local sandbox
./scripts/deploy_testnet.sh

This outputs contract IDs. Save them:

export INVOICE_CONTRACT_ID=<id>
export TREASURY_CONTRACT_ID=<id>
export COMPLIANCE_CONTRACT_ID=<id>

Backend

cd comebackhere-backend

cat > .env <<EOF
STELLAR_NETWORK=testnet
SOROBAN_RPC_URL=http://localhost:8000
HORIZON_URL=http://localhost:8001
ADMIN_PUBLIC_KEY=$ADMIN_PUBLIC_KEY
INVOICE_CONTRACT_ID=$INVOICE_CONTRACT_ID
TREASURY_CONTRACT_ID=$TREASURY_CONTRACT_ID
COMPLIANCE_CONTRACT_ID=$COMPLIANCE_CONTRACT_ID
USDC_CONTRACT_ID=CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4
MONGODB_URI=mongodb://localhost:27017/comebackhere
REDIS_URL=redis://localhost:6379
WEBHOOK_SIGNING_SECRET=<generate-a-32-char-or-longer-secret>
EOF

Before starting the backend, validate all required environment variables:

cd ../COMEBACKHERE
scripts/validate_backend_env.sh ../comebackhere-backend/.env

A missing or blank required variable causes the script to exit with a clear error message. To also enforce the optional contract ID variables (e.g. in CI), run with STRICT=1:

STRICT=1 scripts/validate_backend_env.sh ../comebackhere-backend/.env

Then start the backend:

cd ../comebackhere-backend
npm install
npm run dev

Backend listens on http://localhost:3000.

Required backend variables

These seven are checked by validateEnv() in comebackhere-backend/src/lib/env.ts before the server binds its port. If any is missing — or any Stellar identifier is malformed — the process exits immediately with a message naming every problem at once. scripts/validate_backend_env.sh enforces the same list.

Variable	Description
`MONGODB_URI`	MongoDB connection string (`mongodb://` or `mongodb+srv://`)
`REDIS_URL`	Redis connection string (`redis://`)
`SOROBAN_RPC_URL`	Soroban RPC endpoint
`TREASURY_CONTRACT_ID`	Deployed treasury contract address (`C...`)
`INVOICE_CONTRACT_ID`	Deployed invoice contract address (`C...`)
`ADMIN_KEY`	Admin key sent as the `X-Admin-Key` header on `/webhooks/dead-letters*`
`WEBHOOK_SIGNING_SECRET`	HMAC-SHA256 secret for signing outgoing webhook payloads (≥ 32 chars)

There is no WEBHOOK_SECRET. The backend reads WEBHOOK_SIGNING_SECRET and nothing else. Setting WEBHOOK_SECRET has no effect.

Optional contract integration variables

Validated for strkey format when set, but not required at startup.

Variable	Description
`USDC_CONTRACT_ID`	USDC token contract address (`C...`)
`COMPLIANCE_CONTRACT_ID`	Deployed compliance contract address (`C...`)
`SETTLEMENT_CONTRACT_ID`	Settlement contract address (`C...`)
`ADMIN_PUBLIC_KEY`	Admin account public key (`G...`)
`SIGNER_SECRET_KEY`	Stellar secret seed (`S...`) for signing transactions

Frontend

cd comebackhere-frontend

cat > .env <<EOF
VITE_API_URL=http://localhost:3000
VITE_SOROBAN_RPC=http://localhost:8000
VITE_HORIZON_URL=http://localhost:8001
VITE_NETWORK_PASSPHRASE="Standalone Network ; February 2025"
EOF

npm install && npm run dev

Frontend runs on http://localhost:5173.

Full Environment Variable Reference

The tables below list every environment variable used across the repository. Variables marked Required must be set for the service to start. Variables marked Optional have sensible defaults or are only needed for specific features.

Backend — `comebackhere-backend` (TypeScript/Express)

Variable	Required	Default	Description
`SOROBAN_RPC_URL`	Yes	—	Soroban RPC endpoint (e.g. `http://localhost:8000/soroban/rpc`)
`MONGODB_URI`	Yes	—	MongoDB connection string
`REDIS_URL`	Yes	—	Redis connection string backing the rate limiter
`INVOICE_CONTRACT_ID`	Yes	—	Deployed invoice contract address (`C...`)
`TREASURY_CONTRACT_ID`	Yes	—	Deployed treasury contract address (`C...`)
`ADMIN_KEY`	Yes	—	Admin key for the `/webhooks/dead-letters*` routes (sent as `X-Admin-Key`)
`WEBHOOK_SIGNING_SECRET`	Yes	—	HMAC-SHA256 signing secret for outbound webhooks
`USDC_CONTRACT_ID`	No	—	USDC token contract address (`C...`)
`SETTLEMENT_CONTRACT_ID`	No	—	Settlement contract address (`C...`, used by disputes)
`COMPLIANCE_CONTRACT_ID`	No	—	Compliance contract address (`C...`)
`ADMIN_PUBLIC_KEY`	No	—	Admin account public key (`G...`)
`SIGNER_SECRET_KEY`	No	—	Stellar secret seed (`S...`) for signing transactions
`NETWORK_PASSPHRASE`	No	`Standalone Network ; February 2025`	Stellar network passphrase
`MONGODB_DB`	No	`comebackhere`	MongoDB database name
`WEBHOOK_URL`	No	—	Merchant endpoint that receives webhook POSTs; unset disables outbound webhooks
`WEBHOOK_MAX_ATTEMPTS`	No	`5`	Maximum delivery attempts
`WEBHOOK_BASE_DELAY_MS`	No	`1000`	Initial retry delay in milliseconds
`WEBHOOK_MAX_DELAY_MS`	No	`60000`	Maximum exponential backoff delay in milliseconds
`WEBHOOK_JITTER_RATIO`	No	`0.2`	Retry delay jitter, between `0` and `1`
`PORT`	No	`3000`	HTTP server port
`SHUTDOWN_TIMEOUT_MS`	No	`10000`	Graceful shutdown timeout in milliseconds
`WEBHOOK_DRAIN_TIMEOUT_MS`	No	`5000`	Max time to drain in-flight webhook deliveries on shutdown
`CORS_ORIGINS`	No	— (none)	Comma-separated allowlist of browser origins
`RATE_LIMIT_POINTS`	No	`60`	Max requests per window for the per-IP bucket
`RATE_LIMIT_API_KEY_POINTS`	No	`600`	Max requests per window for the per-`X-API-Key` bucket
`RATE_LIMIT_DURATION`	No	`60`	Rate limit window in seconds
`DISPUTE_VOTE_THRESHOLD`	No	`2`	Minimum votes to resolve a dispute
`INDEXER_START_CURSOR`	No	`0`	Starting cursor for the event indexer

A malformed value in RATE_LIMIT_POINTS, RATE_LIMIT_API_KEY_POINTS or RATE_LIMIT_DURATION falls back to its default rather than disabling the limiter. See rate-limits.md.

Backend — `backend` (Rust/Axum, legacy)

Variable	Required	Default	Description
`SOROBAN_RPC_URL`	Yes	—	Soroban RPC endpoint
`STELLAR_NETWORK`	No	`standalone`	Stellar network name (`standalone`, `testnet`, `mainnet`)
`HORIZON_URL`	No	—	Horizon server URL
`REDIS_URL`	No	`redis://localhost:6379`	Redis connection string
`ADMIN_PUBLIC_KEY`	Yes*	—	Admin account public key (`G...`)
`INVOICE_CONTRACT_ID`	Yes*	—	Invoice contract address
`TREASURY_CONTRACT_ID`	Yes*	—	Treasury contract address
`COMPLIANCE_CONTRACT_ID`	Yes*	—	Compliance contract address
`USDC_CONTRACT_ID`	Yes*	—	USDC token contract address
`HOST`	No	`0.0.0.0`	Server bind address
`PORT`	No	`3000`	Server port
`RATE_LIMIT_POINTS`	No	`60`	Max requests per IP per window
`RATE_LIMIT_DURATION`	No	`60`	Rate limit window in seconds

* This legacy tree is per-IP only — it has no X-API-Key tier and returns a different 429 body shape from the TypeScript backend. See rate-limits.md.

Frontend — `comebackhere-frontend` (React/Vite)

Variable	Required	Default	Description
`VITE_API_URL`	Yes	—	Backend API base URL (e.g. `http://localhost:3000`)
`VITE_SOROBAN_RPC`	Yes	—	Soroban RPC endpoint for wallet interactions
`VITE_HORIZON_URL`	No	—	Horizon server URL
`VITE_NETWORK_PASSPHRASE`	No	`Standalone Network ; February 2025`	Stellar network passphrase

Root-level configuration files

File	Purpose
`.env.local.example`	Local development (standalone sandbox)
`.env.testnet.example`	Stellar testnet configuration
`.env.mainnet.example`	Stellar mainnet configuration (manual, requires multisig approval)
`backend/.env.example`	Legacy Rust backend configuration

Running Contract Tests

cd COMEBACKHERE-contracts

# Run all contract tests
cargo test

# Generate coverage report
cd ../COMEBACKHERE && scripts/coverage.sh

Development Workflow

Make contract changes in COMEBACKHERE-contracts/contracts/*/src/

Rebuild and redeploy:

cd COMEBACKHERE-contracts
cargo build --target wasm32-unknown-unknown --release
cd ../COMEBACKHERE && ./scripts/deploy_testnet.sh

Regenerate ABI metadata:

cd COMEBACKHERE && make update-abi-snapshots

Restart backend to reload new contract IDs (if changed)
Test in frontend UI

Troubleshooting

"Soroban RPC not reachable": Ensure sandbox is running with soroban-cli start --standalone
"Contract not found": Verify contract IDs in .env match deployed IDs from deployment script
"USDC balance insufficient": Fund your testnet account at Stellar Lab
Port already in use: Change the port in backend/frontend env files if 3000 or 5173 are taken

Navigation Menu

Repository navigation

Development Environment Setup

Prerequisites

Directory Layout

Local Soroban Sandbox

Expected `docker-compose ps` Output

Service Health Checks & Expected Output

Pre-Flight Verification Script

Environment Setup

Contracts

Deploy Contracts Locally

Backend

Required backend variables

Optional contract integration variables

Frontend

Full Environment Variable Reference

Backend — `comebackhere-backend` (TypeScript/Express)

Backend — `backend` (Rust/Axum, legacy)

Frontend — `comebackhere-frontend` (React/Vite)

Root-level configuration files

Running Contract Tests

Development Workflow

Troubleshooting

Further Reading

FilesExpand file tree

dev-environment.md

Latest commit

History

dev-environment.md

File metadata and controls

Development Environment Setup

Prerequisites

Directory Layout

Local Soroban Sandbox

Expected docker-compose ps Output

Service Health Checks & Expected Output

Pre-Flight Verification Script

Environment Setup

Contracts

Deploy Contracts Locally

Backend

Required backend variables

Optional contract integration variables

Frontend

Full Environment Variable Reference

Backend — comebackhere-backend (TypeScript/Express)

Backend — backend (Rust/Axum, legacy)

Frontend — comebackhere-frontend (React/Vite)

Root-level configuration files

Running Contract Tests

Development Workflow

Troubleshooting

Further Reading

Expected `docker-compose ps` Output

Backend — `comebackhere-backend` (TypeScript/Express)

Backend — `backend` (Rust/Axum, legacy)

Frontend — `comebackhere-frontend` (React/Vite)