Structured Contract Events with Indexed Topics across Escrow, Reputation & Loyalty #45

Description

This issue aims to address the implementation of Structured Contract Events with Indexed Topics across Escrow, Reputation & Loyalty.

The core objective is to: Publish a consistent, documented event on every state-changing contract operation, with topics chosen so an off-chain indexer can filter by appointment, worker, or address without scanning every ledger.

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

🟡 Medium

Current state

None of the three contracts publishes a single event — grep -rn "events()" contracts/*/src/lib.rs returns nothing. Escrow funding, completion, cancellation, dispute, reputation submission, and loyalty mint/transfer/burn all mutate state invisibly.

That directly blocks the on-chain ingestion pipeline in #22, which has nothing to ingest, and it means the only way to learn a contract's state today is to poll get_appointment for every id the backend already knows about. Events are the small change that unblocks the larger one.

Tasks

• Review the existing Soroban workspace under soroban-contracts/contracts/
• Implement the contract logic for: Structured Contract Events with Indexed Topics across Escrow, Reputation & Loyalty
• Publish an event from every state-changing entry point in escrow (create, confirm, cancel, dispute, resolve), reputation (review submitted), and loyalty-token (mint, transfer, burn, approve, minter rotation)
• Choose topic tuples deliberately so an indexer can filter by appointment_id, worker address, or account without a full scan — document the topic layout per event
• Follow SEP-41 conventions for the loyalty token's events so standard tooling recognizes them
• Keep event payloads small and typed; do not emit unbounded String data
• Document the full event catalogue (name, topics, data shape) in the contracts README so the backend indexer in On-Chain Event Ingestion Pipeline with Transactional Outbox & Replay #22 can be written against a stable contract
• Write comprehensive unit and integration tests, including adversarial edge cases — assert emitted events via the test env's event recorder, and assert that failed operations emit nothing
• 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: Publish a consistent, documented event on every state-changing contract operation, with topics chosen so an off-chain indexer can filter by appointment, worker, or address without scanning every ledger.
• Every state-changing entry point across all three contracts emits exactly one event
• An operation that fails and returns an Error emits no event
• Topic layout supports filtering by appointment id and by address, demonstrated in tests
• The event catalogue is documented and stable enough for On-Chain Event Ingestion Pipeline with Transactional Outbox & Replay #22 to be implemented against it
• 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

1-2 days