[Ezekiel146]

Summary

• Use Soroban's fallible token client for outbound release transfers.
• Map failed payouts to Error::Undeliverable while keeping the escrow funded so the releaser can retry or use the existing refund path.
• Add regression tests for an unauthorized SAC trustline and a receiver contract panic.
• Update the generated SDK error map and relevant documentation.

Closes #55

Verification

• cargo test --manifest-path contracts/escrow/Cargo.toml -- --test-threads=1 passes.
• cargo fmt --manifest-path contracts/escrow/Cargo.toml --check passes.

[drips-wave]

@Ezekiel146 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]

@Ezekiel146

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]

@Ezekiel146 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):

test unauthorized_sac_payee_leaves_escrow_funded_and_can_be_retried ... FAILED
thread 'unauthorized_sac_payee_leaves_escrow_funded_and_can_be_retried' (4606) panicked at /home/runner/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/soroban-env-host-27.0.1/src/host.rs:910:9:
HostError: Error(Contract, #2)
test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s

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.

[Ezekiel146]

@afeezorobsco-cyber I merged the latest main, resolved the conflicts, and fixed the failing undeliverable payout fixture. The full escrow Rust test suite and formatting check pass. Please review and merge when ready.

[Ezekiel146]

@afeezorobsco-cyber This branch now includes the latest main and is conflict-free. The full escrow Rust test suite and formatting check pass. Please review and merge when ready.

[github-actions]

@Ezekiel146 This PR now has merge conflicts with main, most likely because #158 (feat(contract): sponsored funding: a funder distinct from the refund …) 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.}

[afeezorobsco-cyber]

@Ezekiel146 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.

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.

[Ezekiel146]

@afeezorobsco-cyber I resolved the merge conflicts against the latest main, preserved this PR’s feature, regenerated the contract bindings, and updated the affected test snapshots. The escrow contract tests pass. Could you please review the update and merge when ready?

[afeezorobsco-cyber]

@Ezekiel146 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.

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

[github-actions]

@Ezekiel146 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.}

[github-actions]

@Ezekiel146 This PR now has merge conflicts with main, most likely because #211 (feat(security): audit-readiness package for the Phase E5 contract features) 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]

@Ezekiel146 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 what the committed snapshots record. Run cargo test in contracts/escrow on top of the latest main, review the diff under contracts/escrow/test_snapshots/, and commit the updated snapshots (including any new .json files).

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]

@Ezekiel146 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.

The Fail if committed test snapshots changed step means your change alters what the committed Soroban snapshots record. Run cargo test in contracts/escrow on top of the latest main, review the diff under contracts/escrow/test_snapshots/, and commit the updated snapshots (including any new .json files).

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

[Ezekiel146]

Note for maintainers: the merge with main moved Undeliverable to error code 35, because main's InvalidReleaser keeps 24. The bindings check was failing on this branch and is regenerated. The GitHub title is 'fix(contract): keep failed releases recoverable', not the one in the review list, so please confirm the intended title. The fork's workflow run needs maintainer approval.

[Ezekiel146]

Brought this up to date with main and addressed the CI feedback.

Update, not a rebase: merged origin/main (28ec877) into fix/issue-55 rather than rebasing, so the already-pushed history stays intact — git merge origin/main → 95f0352.

Conflicts and resolutions

• docs/threat-model.md — the only real conflict. Both sides added a line in the same spot (this PR's Undeliverable note vs. main's unrelated T4 heading moving down). Kept both: the Undeliverable sentence stays, immediately above the T4 intermediate-contract re-entry section header from main.
• ARCHITECTURE_ESSENTIALS.md, contracts/escrow/src/lib.rs — auto-merged cleanly; main's unrelated changes (formal-verification doc comment, #101) and this PR's try_transfer/Undeliverable branch in settle() don't overlap.
• ROADMAP.md — no conflict (this PR had no entry there yet). Added one line under Phase E5 for issue [Phase E5] Undeliverable payee handling: deauthorised trustlines and rejecting contracts #55, and moved the changelog text into changelog.d/55-undeliverable-payee.md per changelog.d/README.md instead of appending to ROADMAP.md's ## Changelog section.

Error codes

Checked Error against main's current discriminants (0–34, through InvalidFundingDeadline = 34 from the pooled-escrow work). Undeliverable = 35 is still the next free, append-only slot — no collision, nothing else claimed 35 on main since this PR branched. Left it as-is.

Snapshots

Ran cargo test in contracts/escrow on top of the merge. Two committed snapshots changed because release's payout now goes through try_transfer:

• unauthorized_sac_payee_leaves_escrow_funded_and_can_be_retried.1.json
• rejecting_contract_payee_returns_dedicated_error_without_settling.1.json

Diff reviewed: both additions are a single extra DataKey::Status storage entry (Funded in the first snapshot after the rejected release, Released in the second after the retry succeeds) — that's main's status-read optimization (#260, a separate DataKey::Status entry alongside the escrow record), not a change in this PR's behavior. Committed as f6df6b7.

Also found the same kind of drift in the sibling contracts/releaser-account test snapshot (custom_account_can_be_configured_as_escrow_releaser.1.json) for the same reason — not covered by this PR's change, not enforced by the CI snapshot-drift job (which only checks contracts/escrow/test_snapshots), but stale now that it's merged with #260, so I regenerated and committed it too (61bc57c) rather than leave a known-stale snapshot behind.

Re-ran cargo test once more afterward; git status is clean, so "Fail if committed test snapshots changed" should now pass.

Bindings

./scripts/check-generated-bindings.sh with the pinned stellar 28.1.0 reports the committed sdk/src/generated/contract-client.ts already matches the contract WASM (it already carried error 35 from this PR's earlier work) — no regeneration needed.

Other checks run locally

• cargo test (contracts/escrow): 137 passed, 0 failed.
• cargo test --test model (PROPTEST_CASES=64): 4 passed.
• cargo build --target wasm32v1-none --release: wasm artifact produced.
• cargo test/cargo build --target wasm32v1-none --release for contracts/releaser-account: green.
• python3 scripts/check-resource-baseline.py: OK (13 profiled functions).
• cargo fmt --check: fails, but only on pre-existing formatting drift in files this PR doesn't touch (benches/resource_profile.rs, tests/cancel.rs, tests/malicious_token.rs, tests/model.rs, tests/pooled.rs, and a few spots in src/lib.rs outside this PR's lines) — confirmed pre-existing on main before merging, left alone rather than reformatting unrelated code in this PR.
• cargo clippy --all-targets: warnings only (no CI job actually runs clippy), and all of them are pre-existing — too_many_arguments on the existing create_escrow* entry points, deprecated events().publish, a few needless_borrow/clone_on_copy/dead-code lints in test files this PR doesn't touch. Nothing in tests/undeliverable.rs or the new settle() branch.
• SDK (sdk/): npm ci --ignore-scripts, then npm run typecheck, npm run build, npm run test:offline (64 passed), test:milestones (19 passed), test:unit (56 passed), test:runtime — all green. Didn't run the live-testnet suites (npm test / test:integration), consistent with what CI itself skips.

Diff review

Full diff vs origin/main is 10 files / ~1500 lines, almost all of it the two regenerated test-snapshot JSON files. No unrelated files, no secrets, no generated-file hand-edits, nothing that looks obfuscated.

Final branch head: 61bc57c.

[Ezekiel146]

@afeezorobsco-cyber this is ready for a look whenever you have a moment.

[github-actions]

@Ezekiel146 This PR now has merge conflicts with main, most likely because #153 (feat(contract): expose version and build provenance) 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.}

[zeemscript]

@afeezorobsco-cyber I updated this branch to current main and preserved the undeliverable-payee retry behavior. Full escrow contract tests, generated-binding verification, and resource-baseline checks pass locally; the malware scan also passes. GitHub reports this PR as mergeable. Please review/approve the newly updated head and CI. This PR uses version 2.3.0; #155 is based on it and uses 2.4.0, so please merge #154 before #155 to keep the version sequence.

[afeezorobsco-cyber]

Sweep: malware scan clean, CI green.