[docs] Add on-chain contract reference: public interface, roles, events, and error codes

[grantfox-oss]

Summary

The trustlesswork-smart-contract-stellar repository (also known as Trustless-Work-Smart-Escrow) currently documents toolchain setup and deployment in the README, but lacks a contract-level reference for contributors, auditors, and integrators who need to understand what the Soroban escrow actually exposes on-chain.

The Trustless Work product docs cover the REST API and SDK flows well, but there is no in-repo bridge between those flows and the contract's public functions, storage model, events, and error enum.

This issue asks for a focused documentation pass inside the smart-contract repo.

---

Problem

Today, someone cloning the repo must reverse-engineer behavior from Rust source:

• contracts/escrow/src/contract.rs — public entrypoints (initialize_escrow, fund_escrow, release_funds, change_milestone_status, approve_milestone, dispute_escrow, resolve_dispute, etc.)
• contracts/escrow/src/error.rs — 40+ ContractError variants; human-readable descriptions exist only as commented-out Display impl
• contracts/escrow/src/events/handler.rs — on-chain events (InitEsc, FundEsc, DisEsc, MilestoneApproved, …)
• contracts/escrow/src/storage/types.rs — Escrow, roles, milestone shape

The README stops after stellar contract deploy and does not explain:

1. Repository / branch layout (single-release-develop, multi-release branches, factory pattern)
2. Which wallet role must sign each contract call
3. How contract errors map to API error messages
4. How to run and interpret the existing test suite (cargo test in contracts/escrow)

CONTRIBUTORS_GUIDELINE.md also links to outdated paths (Tico4Chain-Coders/Trustless-Work).

---

Proposed deliverable

Add a new doc (suggested path: docs/CONTRACT_REFERENCE.md) and link it from README.md + CONTRIBUTORS_GUIDELINE.md.

1. Contract overview

• Purpose of the escrow factory + instance pattern (tw_new_single_release_escrow)
• High-level lifecycle diagram: deploy → initialize → fund → milestone progress → approve → release / dispute → resolve
• Link to relevant product docs:
  • Escrow lifecycle
  • Roles in Trustless Work

2. Public interface table

For each exported function in EscrowContract, document:

Function	Authorized signer(s)	Preconditions	Emitted event(s)	REST API equivalent (if any)
initialize_escrow	deployer / signer	flags must be false, valid roles	InitEsc	/escrow/single-release/v2/deploy
fund_escrow	funder (signer)	escrow not released/resolved	FundEsc	fund endpoint
…	…	…	…	…

Include admin/TTL helpers (extend_contract_ttl, update_escrow) and dispute paths.

3. Storage & roles

• Document Escrow struct fields and role constraints (e.g. admin must be distinct, max 5 approvers, platform fee ≤ 99%)
• Clarify milestone limits (max 50) and status conventions (pending → in_progress → completed)

4. Error reference

• Generate a table from ContractError in error.rs:
  • numeric code
  • variant name
  • human-readable message (restore/uncomment the existing descriptions)
  • typical trigger / which function returns it
• Cross-link to API docs where the same error surfaces in HTTP responses

5. Events reference

• List each event struct, payload fields, and when it is published
• Note indexer / explorer relevance for downstream tooling

6. Local development

• How to run tests: cargo test (from repo root or contracts/escrow)
• Brief map of test modules (tests/escrow.rs, tests/fund.rs, tests/dispute.rs, …) and what scenario each covers
• Fix broken links in CONTRIBUTORS_GUIDELINE.md to point to this repo's GIT_GUIDELINE.md

---

Acceptance criteria

• docs/CONTRACT_REFERENCE.md (or equivalent) exists and is linked from README
• Every public function in contract.rs is documented with signer, preconditions, and events
• All ContractError variants have a human-readable description in the doc (and optionally uncommented in error.rs)
• Roles, milestone rules, and fee logic match current source — no stale v1-only assumptions
• CONTRIBUTORS_GUIDELINE.md links updated to this repository
• Maintainer review: smart-contract team confirms accuracy

---

Out of scope

• Rewriting the external GitBook / docs.trustlesswork.com site (link out instead)
• Multi-release branch docs beyond a short "see branch X for multi-release variant" note
• New contract features or code changes beyond uncommenting error descriptions if desired

---

References

• Repo: https://github.com/Trustless-Work/trustlesswork-smart-contract-stellar
• Branch reviewed: single-release-develop
• Existing doc issue: testing: Validate full escrow flow using native XLM as trustline #83 (XLM trustline flow validation — complementary, not duplicate)
• Product docs MCP / site: https://docs.trustlesswork.com/trustless-work/v2-en

---

Suggested labels

documentation, good first issue (if the tables are scaffolded by maintainers first)

[Kingvic300]

I would love to work on this issue

[Arome8240]

Hello, I'm a smart contract and full stack developer, open for contributions. contributed to over 20 project on OnlyDust and Drips , with expertise in Solidity, Cairo, JavaScript, TypeScript, and RUST. I am passionate about building secure and scalable blockchain solutions, and I would love the opportunity to contribute my skills toward solving this issue.

[Mosas2000]

Will appreciate working on this issue.

[KevinMB0220]

Hi, I’m Kevin a full-stack and smart contract engineer building on Stellar. I specialize in designing and shipping scalable, secure systems end-to-end, from Soroban smart contracts to production-ready backend infrastructure and user-facing applications.

I’ve worked on complex architectures involving automated agents, cross-chain logic, and data indexing, focusing on reliability, performance, and clean standards. My approach is very product-driven: I don’t just build contracts, I build complete systems that solve real user problems and can scale in production.

I’m especially interested in infrastructure, security, and automation creating tools and frameworks that make it easier for other developers to build safely and efficiently on Stellar.