[omoh5]

Closes #114

Summary

Implements dependent escrows, allowing an escrow to require another escrow to reach a specified status before its funds can be released.

This moves release-order enforcement on-chain, making multi-step payment agreements verifiable by both parties.

Changes

• Added optional escrow dependencies at creation.
• Added dependency validation against existing lower-ID escrows.
• Enforced dependency status checks during release.
• Preserved existing refund behavior independently of dependencies.
• Prevented circular dependencies through lower-ID restrictions.
• Added contract tests for satisfied, unsatisfied, and refunded dependencies.
• Updated the README and applicable architecture documentation.
• Added or updated Phase E5 in ROADMAP.md.

Implementation Details

Dependency representation: [Describe actual storage and types.]

Release behavior: [Describe how the required status is verified.]

Cycle prevention: Dependencies reference only existing lower-ID escrows.

Refund behavior: Dependencies do not block otherwise valid refunds.

Compatibility: [Describe contract storage and SDK compatibility decisions.]

Edge Cases

• Unsatisfied dependencies prevent release.
• Refunded dependencies cannot satisfy a required released status.
• Dependent escrows retain their valid refund paths.
• Self-dependencies and forward references are rejected.
• Cross-contract dependencies are not supported.

Testing

Tests cover:

• Escrows without dependencies.
• Satisfied dependencies.
• Unsatisfied dependencies.
• Refunded dependencies.
• Invalid dependency references.
• Chained dependencies.
• Authorization.
• State integrity after failed releases.
• Refund independence.

Verification

From contracts/escrow/:

• cargo test — [Actual result]
• cargo build --target wasm32v1-none --release — [Actual result]

If SDK changes were required:

• npm run typecheck — [Actual result]
• npm run build — [Actual result]
• npm run test:integration — [Actual result, if applicable]

Test output: [Paste actual command output or a concise relevant excerpt.]

Documentation

• Updated README to explain dependent escrow creation and behavior.
• Updated applicable architecture documentation.
• Updated Phase E5 roadmap status and changelog entry.

Scope

This PR is limited to dependent escrow creation, dependency validation, release enforcement, refund safety, required tests, and documentation.

Cross-contract dependencies and unrelated escrow functionality are out of scope.

[drips-wave]

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

[github-actions]

@omoh5 This PR now has merge conflicts with main, most likely because #142 (feat(escrow): add release not-before guard) 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]

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

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

error[E0425]: cannot find value `depends_on` in this scope
error[E0599]: no variant, associated function, or constant named `InvalidDependency` found for enum `Error` in the current scope
error[E0599]: no variant, associated function, or constant named `InvalidDependencyStatus` found for enum `Error` in the current scope
error[E0599]: no variant, associated function, or constant named `DependencyNotFound` found for enum `Error` in the current scope
error[E0599]: no variant, associated function, or constant named `DependencyUnsatisfied` found for enum `Error` in the current scope
error: could not compile `docforum-escrow` (lib) due to 6 previous errors; 3 warnings emitted

Soroban contract (test + wasm build)

error[E0425]: cannot find value `depends_on` in this scope
error[E0599]: no variant, associated function, or constant named `InvalidDependency` found for enum `Error` in the current scope
error[E0599]: no variant, associated function, or constant named `InvalidDependencyStatus` found for enum `Error` in the current scope
error[E0599]: no variant, associated function, or constant named `DependencyNotFound` found for enum `Error` in the current scope
error[E0599]: no variant, associated function, or constant named `DependencyUnsatisfied` found for enum `Error` in the current scope
error: could not compile `docforum-escrow` (lib) due to 6 previous errors; 3 warnings emitted
error: could not compile `docforum-escrow` (lib test) due to 6 previous errors; 3 warnings emitted

The contract code references depends_on and new Error variants that aren't defined, so part of the change seems to be missing from lib.rs, probably lost while resolving a conflict.

[afeezorobsco-cyber]

@omoh5 Thanks for the build fix; the contract compiles and its tests pass now. One check still fails:

SDK bindings match contract WASM: sdk/src/generated/contract-client.ts is out of date.

Your change adds contract functions and errors, so the generated TypeScript client has to be regenerated from the new WASM:

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

Use the Stellar CLI version pinned in scripts/stellar-cli-version; ./scripts/check-generated-bindings.sh runs the same check locally. Commit the regenerated file and push.

[github-actions]

@omoh5 This PR now has merge conflicts with main, most likely because #215 (feat(e6): React hooks, Wallets Kit signer, Go SDK and OTel hooks) 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]

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

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

TypeScript SDK (Deno), TypeScript SDK (Node 20)

src/generated/contract-client.ts(117,3): error TS1117: An object literal cannot have multiple properties with the same name.
src/index.ts(608,27): error TS2339: Property 'publicKey' does not exist on type 'EscrowSigner'.
src/index.ts(641,29): error TS2339: Property 'get_dependency' does not exist on type 'Client'.
src/index.ts(741,27): error TS2339: Property 'publicKey' does not exist on type 'EscrowSigner'.

SDK bindings match contract WASM

error[E0081]: discriminant value `24` assigned more than once
error: could not compile `docforum-escrow` (lib) due to 1 previous error; 4 warnings emitted

Also failing: TypeScript SDK (Bun), Soroban contract (test + wasm build), TypeScript SDK (Node 22), React hooks package, Reproducible WASM across checkout paths, TypeScript SDK (Chromium), TypeScript SDK (Node 24).

sdk/src/generated/contract-client.ts has a duplicated property (line 117), which suggests the generated file was hand-merged. Take main's version and regenerate it from your contract instead. The SDK also needs get_dependency from the regenerated client, and EscrowSigner has no publicKey on main.

[github-actions]

@omoh5 This PR now has merge conflicts with main, most likely because #152 (feat(contract): payer cancellation window before the payee accepts) 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]

@omoh5 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, Reproducible WASM across checkout paths

error[E0081]: discriminant value `24` assigned more than once
error: could not compile `docforum-escrow` (lib) due to 1 previous error; 4 warnings emitted

TypeScript SDK (all runtimes), React hooks package

src/generated/contract-client.ts(117,3): error TS1117: An object literal cannot have multiple properties with the same name.
src/index.ts(290,14): error TS2304: Cannot find name 'EscrowDependency'.
src/index.ts(579,13): error TS2552: Cannot find name 'CreateDependentEscrowParams'.
src/index.ts(581,5): error TS2304: Cannot find name 'validateDependency'.
src/index.ts(600,26): error TS2304: Cannot find name 'dependencyStatusToGenerated'.
src/index.ts(622,29): error TS2339: Property 'get_dependency' does not exist on type 'Client'.
src/index.ts(722,27): error TS2339: Property 'publicKey' does not exist on type 'EscrowSigner'.

1. Contract: your new Error variant reuses code 24, which main has since assigned. Error codes are append-only, so give yours the next free number.
2. Generated client: sdk/src/generated/contract-client.ts has a duplicated property, which suggests it was hand-merged. Take main's version, then regenerate it from your contract:

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

3. SDK: EscrowDependency, CreateDependentEscrowParams, validateDependency and dependencyStatusToGenerated are used in sdk/src/index.ts but not defined. They were probably lost while resolving the rebase. get_dependency will appear once the client is regenerated. EscrowSigner has no publicKey on main, so use the signer's address accessor instead.

[afeezorobsco-cyber]

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

TypeScript SDK (Deno), TypeScript SDK (Bun), TypeScript SDK (Node 22)

src/generated/contract-client.ts(117,3): error TS1117: An object literal cannot have multiple properties with the same name.
src/index.ts(295,14): error TS2304: Cannot find name 'EscrowDependency'.
src/index.ts(592,13): error TS2552: Cannot find name 'CreateDependentEscrowParams'. Did you mean 'CreateDependentQuorumEscrowParams'?
src/index.ts(594,5): error TS2304: Cannot find name 'validateDependency'.
src/index.ts(613,26): error TS2304: Cannot find name 'dependencyStatusToGenerated'.
src/index.ts(633,50): error TS2304: Cannot find name 'EscrowDependency'.
src/index.ts(635,29): error TS2339: Property 'get_dependency' does not exist on type 'Client'.
src/index.ts(707,5): error TS2304: Cannot find name 'validateDependency'.

Also failing: TypeScript SDK (Chromium), TypeScript SDK (Node 20), React hooks package, TypeScript SDK (Node 24), Reproducible WASM across checkout paths, Soroban contract (test + wasm build), SDK bindings match contract WASM.

These are the same errors as last time: your new Error code reuses 24, the generated client has a duplicated property (regenerate it rather than hand-merging), and the dependency helpers and types are missing from sdk/src/index.ts. See my earlier comment for the steps.

[github-actions]

@omoh5 This PR now has merge conflicts with main, most likely because #180 (feat(sdk): batch create and batch settle support) 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]

@omoh5 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)

error[E0061]: this function takes 14 arguments but 13 arguments were supplied
error[E0599]: no variant, associated function, or constant named `InvalidDependency` found for enum `Error` in the current scope
error[E0599]: no variant, associated function, or constant named `InvalidDependencyStatus` found for enum `Error` in the current scope
error[E0599]: no variant, associated function, or constant named `DependencyNotFound` found for enum `Error` in the current scope
error[E0599]: no variant, associated function, or constant named `DependencyUnsatisfied` found for enum `Error` in the current scope
error: could not compile `docforum-escrow` (lib test) due to 6 previous errors; 4 warnings emitted
error: could not compile `docforum-escrow` (lib) due to 6 previous errors; 4 warnings emitted

TypeScript SDK (Node 24), TypeScript SDK (Deno)

src/index.ts(524,14): error TS2304: Cannot find name 'EscrowDependency'.
src/index.ts(821,13): error TS2552: Cannot find name 'CreateDependentEscrowParams'. Did you mean 'CreateDependentQuorumEscrowParams'?
src/index.ts(823,5): error TS2304: Cannot find name 'validateDependency'.
src/index.ts(842,26): error TS2304: Cannot find name 'dependencyStatusToGenerated'.
src/index.ts(862,50): error TS2304: Cannot find name 'EscrowDependency'.
src/index.ts(864,29): error TS2339: Property 'get_dependency' does not exist on type 'Client'.
src/index.ts(936,5): error TS2304: Cannot find name 'validateDependency'.
src/index.ts(964,27): error TS2339: Property 'publicKey' does not exist on type 'EscrowSigner'.

Also failing: TypeScript SDK (Bun), Reproducible WASM across checkout paths, SDK bindings match contract WASM, React hooks package, TypeScript SDK (Node 20), TypeScript SDK (Node 22), TypeScript SDK (Chromium).

The tests call create_escrow with 13 arguments, but it takes 14 on main. The InvalidDependency, InvalidDependencyStatus, DependencyNotFound and DependencyUnsatisfied error variants also aren't in the contract's Error enum. Add them with new, append-only codes.

[github-actions]

@omoh5 This PR now has merge conflicts with main, most likely because #257 (feat(contract): pooled escrows funded by multiple payers with pro-rata refunds) 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]

@omoh5 This PR now has merge conflicts with main, most likely because #260 (feat(perf): profile and optimize status reads) 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]

@omoh5 This PR now has merge conflicts with main, most likely because #244 (feat(sdk): token-aware amount parsing and formatting) 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]

@omoh5 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/<issue>-feat-contract-add-dependent-escrows-with.md:

   bump: minor
   ---
   Issue #NN: 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. NN00) 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.

[afeezorobsco-cyber]

@omoh5 The new contract check (#268, see my earlier comment) fails this PR: contracts/escrow/src/lib.rs changed, but no fragment was added under contract-changes.d/. Add contract-changes.d/<issue>-<slug>.md (bump: minor, ---, one-paragraph summary). Also regenerate sdk/src/generated/contract-client.ts with stellar CLI 28.1.0, because the "SDK bindings match contract WASM" job reports it out of date. Don't edit CONTRACT_VERSION. Then push.

[afeezorobsco-cyber]

@omoh5 CI on 53f69fa fails, and the cause looks like the merge rather than the feature. contracts/escrow/src/lib.rs now differs from main by only 12 added lines (the EscrowDependency struct, DataKey::Dependency and peek_next_id), so the create_*_dependency entry points and the release checks are gone from the contract, while the SDK and tests/dependencies.rs still use them.

The SDK build fails on that:

src/generated/contract-client.ts(714,366): error TS2304: Cannot find name 'EscrowDependency'.
src/index.ts(1279,29): error TS2339: Property 'get_dependency' does not exist on type 'Client'.
src/index.ts(1351,5): error TS2304: Cannot find name 'validateDependency'.
src/index.ts(1379,27): error TS2339: Property 'publicKey' does not exist on type 'EscrowSigner'.
src/index.ts(1391,26): error TS2304: Cannot find name 'dependencyStatusToGenerated'.

The contract job also still reports the missing fragment:

error: contracts/escrow/src/lib.rs changed, but no fragment was added under contract-changes.d/.

To fix it:

1. Restore the dependency logic in lib.rs. It was lost gradually over your merges of main: 07af032 (10-22) is the fullest version, 6eee66b (10-25) has part of it, and it's gone from 7dd5b29 (10-29) onward.
2. Restore the SDK helpers (validateDependency, dependencyStatusToGenerated) and use the current EscrowSigner shape, which has no publicKey.
3. Add contract-changes.d/<issue>-<slug>.md.
4. Regenerate sdk/src/generated/contract-client.ts with stellar CLI 28.1.0 from the fixed contract.