[inioluwanureni90-cell]

Summary

• Add lifecycle events with each escrow's token and amount, plus a read-only SDK solvency checker that compares token balances against outstanding liabilities.
• Add a cron CLI that reports shortfalls, errors, and incomplete event history.
• Add event reconciliation and clawback shortfall coverage, along with consumer guidance and SDK documentation.

Closes #78

Verification

• solvency_events contract integration test passes.
• Rust formatting and git diff --check pass.
• JavaScript SDK/CLI checks were not run locally; CI covers those packages.

[drips-wave]

@inioluwanureni90-cell 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

[inioluwanureni90-cell]

@afeezorobsco-cyber The solvency checker PR is ready for review; please review and merge once the required checks pass. The current testnet deployment predates lifecycle events, so the CLI reports incomplete history until redeployment or indexing, as documented.

[afeezorobsco-cyber]

@inioluwanureni90-cell fix CI

[afeezorobsco-cyber]

@inioluwanureni90-cell

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]

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

CI is failing. Here's what broke:

Soroban contract (test + wasm build):

error: cannot find attribute `contractevent` in this scope
error: cannot find attribute `topic` in this scope
error[E0599]: no method named `publish` found for struct `EscrowCreated` in the current scope
error[E0599]: no method named `publish` found for struct `EscrowReleased` in the current scope

Please fix these errors and run the same steps locally before pushing (npm run typecheck && npm test && npm run build, or cargo test for contracts).

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.

[github-actions]

✅ Malware scan: clean

The earlier findings are resolved as of ae8b2f1.

[inioluwanureni90-cell]

@afeezorobsco-cyber I resolved the conflicts with main, added the lifecycle events to the current quorum-aware creation and settlement paths, and pushed the update. The focused solvency-events contract test passes. Please review and merge when ready.

[afeezorobsco-cyber]

@inioluwanureni90-cell Thanks for pushing. The malware scan passed, but this PR still has merge conflicts with main, so it can't be merged or reviewed yet. Several escrow PRs merged recently (#183 release callback, #203 M-of-N quorum), so please:

git fetch upstream
git rebase upstream/main
# resolve the conflicts (usually contracts/escrow/src/lib.rs, the create_escrow
# call sites in tests, ROADMAP.md and ARCHITECTURE_ESSENTIALS.md), then:
cargo test                              # commit any updated test_snapshots/
./scripts/check-generated-bindings.sh   # regenerate the SDK bindings if it fails
git push --force-with-lease

Once CI is green and the conflicts are gone, it can be merged.

[inioluwanureni90-cell]

@afeezorobsco-cyber I resolved the conflicts with current main and verified the solvency lifecycle event test passes. The PR description has a standalone Closes #78 reference. Please review and merge when ready.

[github-actions]

@inioluwanureni90-cell This PR now has merge conflicts with main, most likely because #196 (feat(sdk): fee estimation and fee-bump sponsorship helpers) 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 files like ROADMAP.md and ARCHITECTURE*.md. 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.}

[inioluwanureni90-cell]

The branch now includes the latest main and the conflicts are resolved. Settlement preserves both the payee callback and the lifecycle events, and the offline test script retains the solvency test. The PR description still includes Closes #78. @afeezorobsco-cyber, please review the updated PR and merge it once the checks pass.

[afeezorobsco-cyber]

@inioluwanureni90-cell 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 9 arguments but 7 arguments were supplied
error: could not compile `docforum-escrow` (test "solvency_events") due to 2 previous errors

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.)

[inioluwanureni90-cell]

CI fixes pushed: updated the solvency test for the current create_escrow arguments, regenerated the committed Soroban snapshot, and synced the generated SDK bindings. The targeted contract test and generated-binding check pass locally. @afeezorobsco-cyber, please review and merge when ready. Closes #78.

[github-actions]

@inioluwanureni90-cell This PR now has merge conflicts with main, most likely because #174 (feat(indexer): index escrow lifecycle events) 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]

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

Soroban contract (test + wasm build)

cargo test changed committed Soroban snapshots under contracts/escrow/test_snapshots.

Your change alters contract behaviour that the committed Soroban snapshots record. Run cargo test in contracts/escrow, review the diff under contracts/escrow/test_snapshots/, and commit the updated snapshots.

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

[afeezorobsco-cyber]

@inioluwanureni90-cell 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/78-feat-sdk-add-escrow-solvency-checker.md:

   bump: minor
   ---
   Issue #78: 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. 7800) 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.