Initialize Escrow Storage/Admin & Implement Escrow::deposit

[akargi]

Closes: #67

This PR implements two related pieces of functionality for the escrow Soroban contract:

1. Initialize Escrow Contract Storage & Admin
2. Implement Escrow::deposit logic

These changes move the contract toward safer, auditable initialization and a hardened deposit flow with typed errors and event logging.

---

Summary of changes

• Add typed contract errors and events

  • EscrowError (enum) — typed error codes for common failure modes.
  • EscrowInitializedEvent — emitted once on successful initialize.
  • AgentJudgeUpdatedEvent — emitted when admin updates the agent judge.
  • DepositEvent — emitted on successful deposit.

• Initialize/admin improvements

  • initialize(env, admin, agent_judge) -> Result<(), EscrowError>
    • Prevents double initialization (returns AlreadyInitialized).
    • Validates inputs (admin != agent_judge).
    • Persists Admin and AgentJudge to instance storage.
    • Emits ("escrow", "Initialized") event for off-chain consumers.
  • set_agent_judge(env, new_agent_judge) -> Result<(), EscrowError>
    • Requires admin auth and non-equal addresses.
    • Persists AgentJudge and emits AgentJudgeUpdated event.

• Deposit implementation

  • deposit(env, job_id, amount) -> Result<(), EscrowError>
    • Validates job existence and state (Setup only).
    • Requires caller auth (must be client).
    • Validates amount > 0 and that milestones exist.
    • Verifies that the sum of milestone amounts equals the deposit amount.
    • Transfers tokens from the client to the contract using the token client.
    • Updates job total_amount and transitions job to Funded.
    • Emits ("escrow", "Deposit") event with job and amount.

• Tests

  • Updated unit tests in contracts/escrow/src/lib.rs to use the new Result-based initialize and deposit signatures.
  • Adjustments include unwrapping successful results and asserting error returns in mismatch cases.

• Files changed

  • contracts/escrow/src/lib.rs — core contract logic + tests

---

Rationale

• Typed contract errors enable callers and the backend to respond programmatically to failure cases instead of relying on raw panic messages.
• Event emission provides off-chain observability for important state changes (initialization, agent updates, deposits). This improves debugging and backend workflows (AI judge, indexing, audit logs).
• Validations on deposit (milestone sum check, positive amounts, state checks) reduce the risk of invalid state transitions and possible fund loss.

---

Security considerations

• All auth checks use Address::require_auth() where appropriate.
• Token transfers are performed via token::Client::transfer to leverage Soroban token semantics.
• Numeric additions for milestone summing use saturating_add to guard against overflow in the contract's no_std environment.
• Existing functions still use asserts/panics in some places to preserve behavior and snapshot compatibility; we can convert them to typed errors in a subsequent, larger cleanup PR.

---

Migration & compatibility notes

• The initialize and deposit functions now return Result types. Callers (clients and backend) must handle these return values accordingly.
• Existing test snapshots and any off-chain code expecting panic strings for init-related failures will need to be updated to handle typed errors and event-based logging.

---

How to run tests locally

1. Ensure Rust toolchain is installed (recommended toolchain version is the one pinned in rust-toolchain.toml).
2. From repository root run:

cargo test -p escrow

Note: I attempted to run tests in the current environment but toolchain sync blocked the run; please run locally and paste any failing output and I will iterate fixes.

---

Acceptance criteria checklist

• Code compiles and cargo tests for escrow pass locally.
• Unit tests updated and covering new logic (init and deposit paths) — target >= 90% for core logic.
• Integration test on Testnet verifying deposit transfers tokens and emits Deposit event.
• Backend consumers (event listeners) validated against the new events and error handling.
• At least one senior engineer has reviewed the PR.

---

Notes for reviewers

• Focus review on safety of deposit (token transfer behavior) and initialize (double-init prevention and persistence of admin/judge addresses).
• Consider whether additional EscrowError variants are needed for finer-grained error handling.
• Suggest converting other panic/assert!-based checks to typed errors in a follow-up for consistent API behavior.

---

Closes: #68

[drips-wave]

@akargi Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits