🧠 Spike 1: Add Soroban Events to Smart Contract for Indexer Integration

📖 Introduction for Newcomers to Stellar/Soroban

If you're new to Stellar, it's a blockchain network focused on fast, low-cost payments and asset issuance. Soroban is Stellar's smart contract platform, built on Rust, allowing developers to create programmable logic like escrows.

This spike focuses on adding events to the Trustless Work Smart Escrow contract. Events in Soroban are like logs or notifications emitted during contract execution—they don't change state but record important actions (e.g., "escrow created"). These events can be indexed (e.g., by tools like SubQuery) to make historical data queryable, powering features like dashboards or viewers without scanning the entire blockchain.

Why add them? The original contract may not emit events, so we're enhancing it for better observability. This is exploratory—test ideas, note challenges, and suggest improvements in your PR. No need to deploy to the blockchain yet; focus on code changes and local testing.

📍 Goal

Modify the Trustless Work Smart Escrow contract to emit Soroban events using env.events().publish() for key lifecycle stages. This will enable tracking escrows (e.g., creation, funding, disputes) via indexers like SubQuery, making data accessible for ecosystem tools like an Escrow Viewer or analytics dashboards.

🛠️ Prerequisites

To work on this, you'll need:

• Rust: Install via rustup.rs (version 1.76+ recommended for Soroban compatibility).
• Soroban CLI: Install with cargo install --locked soroban-cli (see installation guide).
• Git: For cloning the repo.
• Basic Rust knowledge; Soroban contracts are Rust crates with a soroban_sdk dependency.
• Optional: VS Code with Rust extension for better editing.

Test your setup: Run soroban --version to confirm.

📁 Task Steps

1. Clone the Repo:

   • git clone https://github.com/Trustless-Work/Trustless-Work-Smart-Escrow
   • cd Trustless-Work-Smart-Escrow
   • Create a new branch: git checkout -b spike1-add-soroban-events

2. Understand the Contract Structure:

   • The repo provides a permissionless escrow system using Soroban and USDC (a stablecoin on Stellar).
   • Key files (based on standard Soroban setup; confirm by browsing the repo):
     • src/contract.rs: Main contract logic, where functions like initialize_escrow are defined.
     • src/core/: Likely contains core structs or helpers (e.g., Escrow data).
     • src/storage/: Handles persistent storage.
     • Cargo.toml: Dependencies, including soroban_sdk.
   • Open src/contract.rs—this is where you'll add most event emissions, inside the relevant functions.

3. Create a New Folder for Your Changes:

   • mkdir Contract-Events-for-Indexer
   • Copy the original contract files into it: cp -r src/* Contract-Events-for-Indexer/ (adjust if structure differs).
   • Work inside this new folder to keep changes isolated.

4. Add Soroban Events:

   • Import the SDK if needed: Ensure use soroban_sdk::{symbol_short, Env, Symbol, ...}; is at the top of contract.rs.
   • Syntax: env.events().publish((topic1, topic2), payload);
     • Topics: Use symbol_short!() for short, efficient strings (e.g., symbol_short!("escrow")).
     • Payload: A tuple of values (e.g., (id, amount)); can be scalars, vectors, or maps.
   • Add events to the specified functions (locate them in contract.rs or sub-modules).
   • Build the contract to check for errors: soroban contract build (runs from the repo root; outputs a .wasm file).

5. Test Your Changes Locally:

   • Use Soroban CLI to invoke functions and verify events:
     • Example: soroban contract invoke --id <contract_id> -- initialize_escrow ... (use testnet or local sandbox).
     • Check output for emitted events (they appear in the invocation response).
   • Common pitfalls: Ensure payloads match types (e.g., use IntoVal if needed); test on testnet to avoid mainnet risks.

6. Prepare and Submit PR:

   • Commit your changes: git add Contract-Events-for-Indexer && git commit -m "Add Soroban events for indexer integration"
   • Push: git push origin spike1-add-soroban-events
   • Create a PR on GitHub to the main repo branch.
   • Include a README.md in the new folder (see below).

💡 Events to Add

Use the env.events().publish() format. Add these at the end of each function (after state changes, to ensure they reflect success).

Tips:

• Topics are hierarchical (first is category, second is action).
• Payloads should be concise but informative—use contract variables directly.
• If a function doesn't exist, note it in your README and suggest alternatives.

📦 Expected Output

• ✅ New folder: /Contract-Events-for-Indexer with modified contract source files.
• ✅ PR submitted to the main repo (title: "Spike 1: Add Soroban Events for Indexer").
• ✅ README.md or markdown file in the folder, including:
  • Findings: What worked well? Any errors during build/test?
  • Assumptions: E.g., "Assumed escrow struct is in core/; used testnet for invocation."
  • Recommendations: E.g., "Standardize topics with a prefix like 'tw_escrow'; add timestamps to payloads for better indexing."
  • Suggested Template:

    # Spike 1 Findings: Adding Soroban Events
    
    ## Overview
    [Brief summary of changes]
    
    ## Findings
    - [Bullet points on what you discovered, e.g., "Events emit correctly in CLI invokes."]
    
    ## Assumptions
    - [List, e.g., "Function params match existing code."]
    
    ## Recommendations
    - [Suggestions, e.g., "Add error-handling events for failures."]
    

📎 References

• Soroban Events Docs: Events Overview – Details on publishing, with examples like env.events().publish((symbol_short!("transfer"), from), amount);. Best practices: Use up to 4 topics; keep payloads under 1KB; emit after state changes.
• Soroban SDK Reference: Env Interface – Exact syntax and types.
• Getting Started with Soroban: Hello World Tutorial – For beginners.
• Smart Contract Repo: GitHub Repo – README has deployment info.

Feel free to ask questions in the issue or PR comments—happy to clarify Stellar specifics! This spike sets the foundation for decentralized data access in the ecosystem.