docs: add comprehensive API documentation with OpenAPI spec

[HuiNeng6]

Summary

Implements #62 - Create API Documentation with OpenAPI

This PR adds comprehensive API documentation for PrivacyLayer, enabling developers to easily integrate with the protocol.

Documentation Included

OpenAPI Specification (openapi.yaml)

• Complete API specification in OpenAPI 3.1 format
• All endpoints documented with request/response schemas
• Authentication, rate limiting, and error handling documented
• Ready for Swagger UI integration

Postman Collection (postman_collection.json)

• Pre-configured requests for all API endpoints
• Environment variables for easy switching between testnet/mainnet
• Example responses for each endpoint
• Organized by feature area (Pool, Deposit, Withdraw, Proof, Relayer, Events)

Contract ABI Documentation (CONTRACT_ABI.md)

• Complete function signatures with parameters and returns
• Event definitions with field descriptions
• Error codes with explanations
• Cryptographic primitive documentation
• Gas cost estimates
• Security considerations
• Integration examples

Code Examples

• TypeScript deposit flow example
• TypeScript withdrawal flow example
• cURL examples for all API endpoints

API Endpoints Documented

Pool Operations

• GET /v1/pool/info - Get pool state
• GET /v1/pool/denominations - Get supported denominations

Deposit Operations

• POST /v1/deposit/prepare - Prepare deposit transaction
• POST /v1/deposit/estimate - Estimate deposit cost

Withdrawal Operations

• POST /v1/withdraw/prepare - Prepare withdrawal
• POST /v1/withdraw/estimate - Estimate withdrawal cost

Proof Operations

• POST /v1/proof/generate - Generate ZK proof
• GET /v1/merkle/root - Get current root
• GET /v1/merkle/proof/:commitment - Get Merkle proof

Relayer Services

• POST /v1/relayer/submit - Submit via relayer
• GET /v1/relayer/status/:txHash - Check status

Event Queries

• GET /v1/events/deposits - Query deposits
• GET /v1/events/withdrawals - Query withdrawals

Health

• GET /v1/health - Health check

Files Added

• docs/api/openapi.yaml - OpenAPI specification
• docs/api/postman_collection.json - Postman collection
• docs/api/CONTRACT_ABI.md - Contract documentation
• docs/api/examples/README.md - Examples overview
• docs/api/examples/typescript/deposit.ts - Deposit example
• docs/api/examples/typescript/withdraw.ts - Withdraw example
• docs/api/examples/curl/api_calls.sh - cURL examples

Usage

Using with Swagger UI

npx swagger-ui-watcher docs/api/openapi.yaml

Using with Postman

1. Import docs/api/postman_collection.json
2. Set environment variables (base_url, api_key)
3. Start making requests

Using Code Examples

cd docs/api/examples/typescript
npm install
ts-node deposit.ts

---

This documentation provides everything developers need to integrate with PrivacyLayer, from API exploration to production implementation.

[HuiNeng6]

@ANAVHEOBA

📢 Follow-up — Ready for Review (24+ Hours)

This API Documentation PR is ready for review.

Implementation Complete:
✅ MERGEABLE - Clean, ready to merge
✅ OpenAPI spec - Full API specification
✅ Examples - Usage examples for each endpoint

Looking forward to your review! 🙏