Rust & Soroban smart contracts powering the COMEBACKHERE Protocol.
This repository contains the core on-chain components that power the COMEBACKHERE Protocol on the Stellar network. It manages invoice escrow, payment verification, treasury settlement, and compliance controls while providing a secure and auditable foundation for protocol operations.
The smart contracts in this repository are responsible for:
- Managing invoice escrow and lifecycle
- Validating and recording payments
- Executing multi-signature treasury settlements
- Enforcing compliance through allowlists and blocklists
Built with Rust and Soroban, these contracts prioritize security, performance, and maintainability.
contracts/
├── invoice/ # Invoice escrow state machine and payment lifecycle
├── treasury/ # 2-of-3 multisignature treasury settlement workflow
└── compliance/ # Admin-managed allowlist and blocklist controls
| Contract | Purpose |
|---|---|
invoice |
Manages invoice creation, escrow state, and payment confirmation |
treasury |
Handles secure multi-signature settlement approvals (2-of-3) |
compliance |
Maintains protocol allowlists and blocklists for compliance enforcement |
This repository maintains two cohesive rounds of issues — an initial foundational set and a follow-up round building on those foundations. Many issues are independent; some explicitly depend on others landing first.
New contributor orientation:
- Check the
Issuestab and filter by labels (e.g.,Stellar Wave,easy,hard) to find work that fits your scope. - You must request assignment before starting. Comment on the issue asking for assignment; an issue must be assigned to you before you begin work.
- Some issues in the current wave depend on others in the same wave. Read the full issue description to check for dependency notes.
- If you discover an issue is already resolved by a recent change, or is a duplicate of another unnoticed issue, comment to flag it for triage rather than opening conflicting work.
For detailed branch naming, commit message, and pull request conventions, see CONTRIBUTING.md.
Using Just:
just fmtOr directly with Cargo:
cargo fmt --allUsing Just:
just lintOr with Cargo:
cargo clippy -- -D warningsUsing Just:
just testOr with Cargo:
cargo testExecute formatting, linting, and tests in a single command:
just checkRun the exact same command sequence, in the same order, as the Pre-commit CI job (cargo fmt --all -- --check, cargo clippy -- -D warnings, scripts/check-enum-ordering.sh):
Using Just:
just precommitOr with Make:
make precommitStart a local Stellar quickstart network matching the exact image, environment variables, and port used by the Init Contracts Smoke Test CI workflow, so scripts/init-contracts.sh behaves the same locally as it does in CI:
docker compose upThis starts stellar/quickstart:latest on localhost:8000 with Soroban RPC enabled. Once healthy, run scripts/init-contracts.sh against it as usual.
Whenever contract interfaces change, regenerate the ABI metadata from the sibling COMEBACKHERE repository.
cd ../COMEBACKHERE
make update-abi-snapshotsThis keeps the backend and other protocol components synchronized with the latest contract interfaces.
The project is built using the following toolchain:
| Tool | Version |
|---|---|
| Rust | 1.95.0 |
| Compilation Target | wasm32-unknown-unknown |
| Stellar CLI | 22.8.2 |
The Rust version is pinned in
rust-toolchain.tomlto ensure consistent builds across development environments.
Run the following script to confirm that all required tools are installed and correctly configured:
./scripts/check-tools.shBefore submitting a pull request, make sure to:
- Format the code.
- Run the linter.
- Execute the full test suite.
- Regenerate ABI snapshots if contract interfaces changed.
- Ensure all checks pass successfully.
This project is licensed under the MIT License.