[Mustapha3415]

Summary

• Add typed escrow creation, release, and refund events for off-chain indexing.
• Record the indexing decision and recovery guidance in ADR 0006 and update the architecture and threat model.
• Add contract tests that verify the emitted events and payloads.

Closes #33
Closes #9

Verification

• cargo test passed for the escrow workspace.
• git diff --check passed.

[drips-wave]

@Mustapha3415 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

[afeezorobsco-cyber]

@Mustapha3415

This PR has merge conflicts with main, which has moved on since this branch was created. Please rebase onto the latest main (or merge main into your branch), resolve the conflicts, and push. CI will then re-run, and the PR can be merged once it's conflict-free, CI is green and it's been reviewed. Thanks!

[afeezorobsco-cyber]

@Mustapha3415 Thanks for the PR. It can't be merged yet. To unblock it:

Merge conflicts: this branch conflicts with main. Please rebase onto the latest main (git fetch upstream && git rebase upstream/main), resolve the conflicts (often ROADMAP.md, ARCHITECTURE*.md or prisma/schema.prisma), and force-push.

Push to this same branch and CI will re-run. Once it's green and conflict-free, it'll be reviewed for merge.

[Mustapha3415]

@afeezorobsco-cyber I updated this branch from main and resolved the merge conflicts. Please review and merge when ready.

[github-actions]

@Mustapha3415 This PR now has merge conflicts with main, most likely because #150 (feat(contract): add two-party releaser rotation) was just merged, so it can't be merged until it's rebased:

git fetch upstream            # upstream = https://github.com/DocForum/docforum-escrow.git
git rebase upstream/main
# resolve the conflicts, re-run the tests, then:
git push --force-with-lease

The usual culprits are shared docs like ROADMAP.md and ARCHITECTURE*.md. If the conflict is in the ROADMAP.md changelog, move your entry into a new file under changelog.d/ (see changelog.d/README.md) rather than resolving it in place, so it can't conflict again. CI re-runs when you push, and the needs-rebase label is removed automatically once the conflicts are resolved.

_{Automated message. It won't repeat unless the PR conflicts again after your next push.}

[afeezorobsco-cyber]

@Mustapha3415 CI is failing on this branch against the latest main, so it can't be merged yet. The errors from the latest run:

SDK bindings match contract WASM

sdk/src/generated/contract-client.ts is out of date.

Soroban contract (test + wasm build)

error[E0061]: this method takes 7 arguments but 9 arguments were supplied
error[E0599]: no method named `create_escrow_release_time` found for struct `EscrowContractClient<'a>` in the current scope
error[E0609]: no field `release_not_before` on type `EscrowData`
error: could not compile `docforum-escrow` (test "token_allowlist") due to 2 previous errors
error[E0599]: no variant, associated function, or constant named `ReleaseTooEarly` found for enum `docforum_escrow::Error` in the current scope
error[E0599]: no method named `try_create_escrow_release_time` found for struct `EscrowContractClient<'a>` in the current scope
error[E0599]: no variant, associated function, or constant named `InvalidReleaseNotBefore` found for enum `docforum_escrow::Error` in the current scope
error: could not compile `docforum-escrow` (test "time_locked_release") due to 8 previous errors

The contract tests still call create_escrow with the old argument list and a create_escrow_release_time method that doesn't exist on main. Update them to the current surface (ARCHITECTURE_ESSENTIALS.md → Contract surface), then regenerate the bindings.

sdk/src/generated/contract-client.ts doesn't match the contract any more, because main has changed the contract since your branch was created. Regenerate the bindings against the latest main and commit them:

cd contracts/escrow && cargo build --target wasm32v1-none --release
stellar contract bindings typescript --wasm target/wasm32v1-none/release/docforum_escrow.wasm --output-dir /tmp/escrow-bindings --overwrite
cp /tmp/escrow-bindings/src/index.ts ../../sdk/src/generated/contract-client.ts

(scripts/check-generated-bindings.sh runs the same check locally.)

This PR also conflicts with main again, so please rebase first, then fix the above.

[afeezorobsco-cyber]

@Mustapha3415 Heads-up: #268 just changed how contract PRs work in this repo. Your PR changes contracts/escrow/src/lib.rs, so CI's new "Contract changes use a fragment, not a version bump" step will fail it until you make these changes (details in contract-changes.d/README.md):

1. Don't edit CONTRACT_VERSION when you merge main (currently 2.3.0). Keep main's line as it is.

2. Add a fragment, e.g. contract-changes.d/33-feat-escrow-emit-events-for-off-chain-in.md:

   bump: minor
   ---
   Issue #33: one-paragraph summary of the contract change.

   Use patch for a behaviour fix with no interface change, minor for new entry points, arguments, events or errors, and major for breaking changes.

3. If you add any new Error variants, give them provisional codes (issue number × 100 + n, e.g. 3300) and never renumber existing ones.

This should also make your next merge from main much easier: the version line was the one thing every contract PR conflicted on.