The on-chain trust layer: invoice state that can't be forged, settlements that need 2-of-3 signatures, and a compliance gate checked before any payment is built.
Stargate Protocol — The Stripe for Stellar. Founded and built by dreamgene · Founder & CEO
| 🌍 Live app | stargate-frontend-psi.vercel.app — the product these contracts anchor |
| 📖 Docs | stargate-frontend-psi.vercel.app/docs · in-repo guides under docs/ |
| 🖥️ Frontend | FX-GENE/stargate-frontend — dashboard, checkout, widget |
| 🧩 Backend | FX-GENE/stargate-backend — NestJS API + Rust reconciler |
A payment processor that says "trust our database" is just a bank with extra steps. Stargate moves the parts that demand neutrality on-chain: whether an invoice was paid, whether a payer is allowed to pay, and whether a settlement was properly authorized. Off-chain services can crash, be compromised, or misbehave — these contracts are the parts that can't quietly lie.
| Contract | Path | What it enforces |
|---|---|---|
| Invoice | contracts/invoice |
Invoice escrow state machine: creation, admin-only payment marking, expiry rejection, pause protection, duplicate-payment rejection. Emits typed events. |
| Treasury | contracts/treasury |
Merchant settlement disbursement gated behind a 2-of-3 multi-sig approval workflow — no single key can move settled funds. |
| Compliance | contracts/compliance |
Admin-managed allow/block list. The backend calls is_allowed() before building any payment XDR, so blocked addresses never receive a transaction to sign. |
All contracts are #![no_std] Soroban (Rust) with typed contract errors and event emission; committed ABI snapshots in abis/ are the integration contract consumed by stargate-backend.
| Repo | Role |
|---|---|
| stargate-frontend | Next.js dashboard, hosted checkout, embeddable widget, public docs |
| stargate-backend | NestJS API, PostgreSQL, Redis Streams webhooks, Rust reconciler |
| stargate-contracts (this) | Soroban contracts + committed ABI snapshots + deployment tooling |
How they communicate: the backend invokes these contracts over Soroban RPC using env-injected IDs (COMPLIANCE_CONTRACT_ID, TREASURY_CONTRACT_ID, INVOICE_CONTRACT_ID) and validates call shapes against the ABI snapshots committed here. The frontend never touches the contracts directly.
contracts/invoice/ invoice escrow state machine
contracts/treasury/ 2-of-3 settlement approval workflow
contracts/compliance/ admin-managed allow/block list
abis/ committed ABI metadata (consumed by stargate-backend)
scripts/ deploy_testnet.sh, export_deployed_addresses.sh, coverage.sh
docs/ dev-environment, MAINNET_DEPLOYMENT (signing ceremony)
justfile / Makefile common development tasks
Requires Docker and Docker Compose.
docker-compose up -d # Stellar quickstart (Horizon :8000) + Redis
docker-compose ps
curl http://localhost:8000/healthDeploy locally:
cp .env.local.example .env.local # add your test keys
scripts/deploy_local.sh # or stellar-cli directlyTear down with docker-compose down (-v to remove data).
Uses just for common commands:
just fmt # format
just lint # clippy -D warnings
just test # cargo test
just check # all of the above
# or cargo directly
cargo fmt --all
cargo clippy -- -D warnings
cargo test
make check-abi-snapshotsA fully configured VS Code Dev Container (Rust + Soroban CLI) is included — see docs/dev-environment.md.
abis/ is generated from contract sources and is the interface stargate-backend builds against. Before opening a PR that changes contract behavior:
make update-abi-snapshots # or: just snapshot
make check-abi-snapshots # confirm clean: git diff --exit-code abis/The generator pins LC_ALL=C / LANG=C so output is byte-identical across machines. See CONTRIBUTING.md for pre-commit hooks.
scripts/coverage.sh # → coverage/index.html + LCOV for CITestnet (self-serve):
cp .env.testnet.example .env.testnet
scripts/deploy_testnet.shDeployed IDs are exported to artifacts/addresses.json (gitignored; see artifacts/addresses.json.example for the schema). Feed them to the backend via COMPLIANCE_CONTRACT_ID / TREASURY_CONTRACT_ID / INVOICE_CONTRACT_ID.
Mainnet is intentionally manual: scripts/deploy_mainnet.sh refuses to run from a single local shell. Live deployment requires governance approval, a recorded multi-sig signing ceremony, WASM hash verification against a deployment issue, and KMS-backed signing — the full checklist lives in docs/MAINNET_DEPLOYMENT.md.
Real:
- All three contracts compile, pass clippy
-D warnings, and have test suites covering invoice creation, admin-only payment marking, expiry rejection, pause protection, duplicate-payment rejection, treasury threshold approvals, and compliance block/clear behavior. - The ABI-snapshot workflow is enforced (
make check-abi-snapshots) so backend/contract drift is caught in CI, not production.
Honestly unfinished:
- No public-network deployment yet — there are no canonical testnet/mainnet contract IDs to list here. Deploy to testnet with the script above; mainnet awaits the governance ceremony.
- The invoice contract mirrors off-chain state today (the backend's Postgres remains the operational source of truth); deeper on-chain escrow is future work.
MIT