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

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