Docs: No contract ABI documentation and no API versioning strategy — operators cannot integrate safely

[k-deejah]

Difficulty: Advanced

Problem

1. No machine-readable or human-readable contract interface documentation
docs/api-reference/ covers REST endpoints but has no documentation of the five Soroban contract function signatures, argument types, return types, or error conditions. An operator who wants to call lineproof-queue::enroll_position(identity: Address) -> u32 directly (not via the SDK) must read the Rust source code to understand the calling convention.

2. No API versioning strategy — breaking changes have no deprecation path
All backend REST routes are mounted at /api/queues, /api/enrollments, /api/escrow with no version prefix. There is no /api/v1/ namespace, no Accept: application/vnd.lineproof.v1+json header versioning, and no documented deprecation policy. Any breaking API change silently breaks existing integrations.

3. Research files in research/ are stubs — referenced from the docs but contain no actionable content
research/event-ticketing.md, research/healthcare-waitlists.md, research/product-launches.md, research/university-admissions.md, research/visa-appointment-systems.md are listed in the directory but (from prior analysis) likely contain placeholder stubs. The docs/use-cases.md references these research files as background reading but they contain no actionable technical detail.

Impact: External operators cannot integrate with contracts without reading Rust source. Breaking API changes have no warning mechanism. Research stubs undermine the project's use-case credibility.

Proposed Solution

• Create docs/api-reference/contracts/ with one markdown file per contract documenting each function: signature, arguments with types, return type, error conditions, and example invocation.
• Add /api/v1/ version prefix to all backend routes. Serve current routes under both /api/ (with deprecation warning) and /api/v1/.
• Document API versioning policy in docs/api-reference/versioning.md.
• Expand research files with 3–5 concrete technical requirements per domain (e.g., healthcare: compliance constraints, visa: batch scheduling constraints).

Acceptance Criteria

• docs/api-reference/contracts/lineproof-queue.md created with all function signatures
• docs/api-reference/contracts/lineproof-escrow.md, enrollment.md, identity.md, factory.md created
• Each contract doc includes: function name, parameters, return type, error panics, example
• /api/v1/ prefix added to all backend routes
• Old /api/ routes return Deprecation: true header and forward to v1
• docs/api-reference/versioning.md created with versioning policy
• At least one research file expanded with concrete technical requirements

Contributor Note

If assigned, your PR must show a sample contract interface doc for lineproof-queue and explain the route versioning strategy chosen (URL prefix vs header versioning) and why.

[sanusishafii989]

Hi maintainer,

I would like to take on this issue to document the contract ABI and establish a clear API versioning strategy.

Execution Plan:

Document the contract functions, input parameters, return values, and emitted event signatures in a dedicated ABI documentation guide.

Define a standard API versioning strategy (e.g., /v1/ routes, headers, and deprecation lifecycle) to guide integrations safely.

Add clear integration examples in markdown for external operators.

I am ready to start immediately. Please assign this issue to me.

[ShantelPeters]

I have experience with TypeScript, JavaScript, React/Next.js, blockchain development, and API integrations. I would begin by reviewing the existing contract interfaces, ABI generation process, and API endpoints to identify the documentation and versioning gaps. I would then introduce clear ABI documentation, establish a consistent API versioning strategy, and provide practical integration examples for operators. I would also test the documentation and implementation to ensure the proposed approach is clear, maintainable, and safe for future integrations. I’m confident I can deliver this in a timely manner with a focused PR.

[grantfox-oss]

🦊 GrantFox — @ShantelPeters 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 #195)
2. Your PR will be reviewed by the Stellar-Deejah maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@ShantelPeters's PR #236 was approved and merged by @k-deejah.

🏆 @ShantelPeters: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (659 total points). Track your full progress on GrantFox.

👏 Great work, @ShantelPeters! Keep contributing to Stellar-Deejah.