Document the full escrow entrypoint reference and error code catalogue

[mikewheeleer]

Document every escrow entrypoint and EscrowError code

Description

README.md describes the build commands and structure but contains no API reference: the 30+ entrypoints in contracts/escrow/src/lib.rs and the 12 EscrowError codes are undocumented outside inline /// comments. New integrators have no single reference for what the contract exposes or what each error means. This issue produces a complete, accurate reference.

Requirements and context

• Repository scope: Agentpay-Org/Agentpay-contracts only.
• Add docs/escrow/api.md listing every entrypoint with signature, auth requirement, pause behaviour, parameters, return, and the errors it can panic with.
• Add an error-code table mapping each EscrowError variant to its numeric code, trigger condition, and the entrypoints that raise it.
• Cross-check every entry against the source so the docs cannot drift; link the new doc from README.md.
• Note the append-only error-code policy so contributors do not renumber.

Suggested execution

• Fork the repo and create a branch
• git checkout -b docs/contracts-26-api-reference
• Implement changes
  • Write code in: contracts/escrow/src/lib.rs — only minor /// fixes if an inline comment is found inaccurate.
  • Write comprehensive tests in: contracts/escrow/src/test.rs — no new logic; optionally add a doc-aligned smoke assertion if a discrepancy is found.
  • Add documentation: add docs/escrow/api.md and the error table; update README.md.
  • Include NatSpec-style doc comments (///) where any are missing on public entrypoints.
  • Validate security: docs accurately state auth/pause requirements.
• Test and commit

Test and commit

• Run cargo fmt --all -- --check, cargo build, and cargo test.
• Cover edge cases: ensure every public entrypoint is listed exactly once.
• Include the full cargo test output and a short security notes section in the PR description.

Example commit message

docs: add complete escrow entrypoint and error-code reference

Guidelines

• Minimum 95 percent test coverage for impacted modules.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the AgentPay community on Discord for questions, reviews, and faster merges: https://discord.gg/eXvRKkgcv
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.