Cross-Contract Settlement Router with Auth-Chained Escrow → Reputation → Loyalty Atomicity

[meshackyaro]

Description

This issue aims to address the implementation of Cross-Contract Settlement Router with Auth-Chained Escrow → Reputation → Loyalty Atomicity.

The core objective is to: Introduce a settlement router contract that atomically drives escrow release, reputation attestation, and loyalty emission in a single authorized invocation, so a completed appointment settles as one indivisible on-chain unit instead of three racing calls.

By completing this feature, we will ensure that the GuildWorkman protocol maintains its high standards for security, usability, and decentralized logic. This issue requires careful attention to the Smart Contract architecture and adherence to the existing project conventions.

When picking up this issue, please ensure you document any new dependencies or architectural decisions made during development.

Component

Smart Contracts (Soroban)

Difficulty

⚫ Very Hard

Current state

The three contracts in soroban-contracts/contracts/ are today completely disconnected from one another:

• escrow::confirm_completion moves funds and sets Status::Completed — and stops there.
• reputation::submit_review accepts any appointment_id with no proof that the appointment exists, was funded, or was completed.
• loyalty-token::mint is gated only on a single Minter address (the backend service account), so reward points are minted on the backend's word rather than on settled on-chain state.

That means a client can review a worker for an appointment that never happened, and loyalty points are only as trustworthy as the backend's private key. A router that owns the settlement sequence closes both holes.

Tasks

• Review the existing Soroban workspace under soroban-contracts/contracts/
• Implement the contract logic for: Cross-Contract Settlement Router with Auth-Chained Escrow → Reputation → Loyalty Atomicity
• Add a new settlement-router crate to the workspace members in soroban-contracts/Cargo.toml
• Wire cross-contract calls with correct require_auth / sub-invocation auth chaining so the router — not the backend — is the authority that lets reputation and loyalty accept a settlement
• Make settlement idempotent per appointment_id: a replayed settle call must be a no-op, never a double mint or double release
• Define the failure semantics explicitly (a panicking sub-invocation reverts the whole invocation — document what that means for partially-configured deployments and for a missing/paused sub-contract)
• Restrict reputation::submit_review and loyalty-token::mint to settlement paths the router authorizes, and migrate the existing minter model accordingly
• Write comprehensive unit and integration tests, including adversarial edge cases (replayed settles, unauthorized direct calls to the sub-contracts, mismatched appointment/worker pairs)
• Add caching for cargo dependencies in CI
• Run cargo fmt --check and cargo clippy -- -D warnings
• Run cargo test and soroban contract build to verify the optimized WASM build

Acceptance Criteria

• Feature accurately implements the objective: Introduce a settlement router contract that atomically drives escrow release, reputation attestation, and loyalty emission in a single authorized invocation, so a completed appointment settles as one indivisible on-chain unit instead of three racing calls.
• A completed appointment settles in one transaction: funds released, review slot unlocked, loyalty minted — or none of it happens
• A review can no longer be submitted for an appointment that was never funded and completed on-chain
• Loyalty points can no longer be minted without a corresponding settled appointment
• Settlement is idempotent: calling settle twice for the same appointment_id leaves balances and reputation unchanged after the first call
• Any PR that introduces compiler or clippy warnings is automatically blocked
• Contract logic is covered by tests exercising success, failure, and attack paths
• Storage layout and authorization are documented and reviewed for safety
• Code is properly reviewed and approved by codeowners

Estimated Time

4-6 days

[Just-Bamford]

I’d tackle this by first mapping the existing escrow, reputation, and loyalty contracts and defining the router as the single authorized settlement entry point. I’d implement the cross-contract calls with Soroban auth chaining so escrow completion authorizes the downstream reputation and loyalty actions, while enforcing appointment/worker consistency and making settlement idempotent to prevent replayed releases or mints.

Then I’d migrate the existing direct authorization paths, add the router workspace crate and required storage, and explicitly document atomic rollback behavior when any sub-call fails or a contract is unavailable. I’d finish with integration and adversarial tests covering successful settlement, replay attacks, unauthorized direct calls, mismatched appointments, and failure rollback, then run cargo test, cargo fmt --check, Clippy with warnings denied, and the optimized Soroban build.

[Sparexonzy95]

I’m interested in taking this issue. I have experience working with Stellar/Soroban smart contracts and understand the requirements around cross-contract authorization, atomic settlement, idempotency, and secure contract-to-contract calls. I can implement the settlement router, tighten reputation and loyalty authorization, cover replay and unauthorized-call scenarios with comprehensive tests, and submit a solid PR within 2-3 days.

[DeborahOlaboye]

I’d like to take on this issue. I have experience building smart contracts and working with blockchain applications, including cross-contract interactions, authorization, and end-to-end integrations. I’m particularly interested in the security and atomicity requirements of this feature.

I can implement the settlement router with Soroban authorization chaining, ensuring escrow completion is the source of truth for reputation and loyalty actions. I’ll also enforce appointment/worker consistency and make settlement idempotent so replayed calls cannot cause duplicate releases, reviews, or loyalty minting.

I’ll cover the migration of the existing authorization paths and add comprehensive unit and integration tests for successful settlement, rollback on failed sub-invocations, unauthorized direct calls, replay attempts, and mismatched appointment data. I’ll also document the failure semantics and storage/authorization decisions and verify the implementation with formatting, Clippy, tests, and the optimized Soroban build.

I’m comfortable taking ownership of the feature end-to-end and delivering it with a strong focus on security, correctness, and maintainability.

[grantfox-oss]

🦊 GrantFox — @DeborahOlaboye has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #38)
2. Your PR will be reviewed by the workman-labs maintainers

Good luck! Track your progress on GrantFox.