Skip to content

feat(contract): deploy isolated escrows per integrator - #146

Open
Bkizzy16 wants to merge 12 commits into
DocForum:mainfrom
Bkizzy16:fix/issue-49
Open

Bkizzy16 wants to merge 12 commits into
DocForum:mainfrom
Bkizzy16:fix/issue-49

Conversation

@Bkizzy16

@Bkizzy16 Bkizzy16 commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Add a Soroban factory that pins an escrow WASM hash and deploys one deterministic instance per authorized integrator.
  • Store the integrator-to-instance mapping, expose lookup and address prediction, and reject duplicate deployments.
  • Pass the integrator as non-privileged instance metadata; the factory has no child administration or upgrade path.
  • Add integration coverage for two independent token balances, deterministic addresses, registry lookup, and duplicate rejection.
  • Add a shared Cargo workspace, build/test CI for both contracts, ADR 0008, and update the roadmap and architecture docs.

Closes #49

Verification

  • Workspace contract tests and doctests pass.
  • Escrow WASM release build passes.
  • Generated SDK bindings check passes.

@drips-wave

drips-wave Bot commented Oct 16, 2026

Copy link
Copy Markdown

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

Copy link
Copy Markdown
Contributor

@Bkizzy16

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

Copy link
Copy Markdown
Contributor

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

@github-actions github-actions Bot added the needs-rebase Has merge conflicts with main; the author needs to rebase label Oct 20, 2026
@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

Malware scan: passed, with notes for the reviewer

Nothing malicious was detected in 5679822. These changes touch sensitive areas and should get a careful look before CI is approved:

Where Rule Why
.github/workflows/ci.yml:106 workflow-change Changes a CI workflow; a maintainer must review before approving runs.
.github/workflows/release-contract.yml:31 workflow-change Changes a CI workflow; a maintainer must review before approving runs.
.github/workflows/sdk-go.yml:88 workflow-change Changes a CI workflow; a maintainer must review before approving runs.

@Bkizzy16

Copy link
Copy Markdown
Contributor Author

@afeezorobsco-cyber I resolved the conflicts with current main and updated the factory and escrow integration. The workspace contract tests, doctests, escrow WASM build, and generated SDK binding check pass. The PR description includes Closes #49. Please review and merge when ready.

@github-actions github-actions Bot removed the needs-rebase Has merge conflicts with main; the author needs to rebase label Oct 20, 2026
@afeezorobsco-cyber

Copy link
Copy Markdown
Contributor

@Bkizzy16 CI is failing on this branch (after it was updated with the latest main), so it can't be merged yet. The errors from the latest run:

thread 'legacy_creation_keeps_acceptance_opt_out' (2865) panicked at /home/runner/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/soroban-sdk-27.0.6/src/env.rs:1106:25:
called `Result::unwrap()` on an `Err` value: HostError: Error(Context, InvalidAction)
thread 'required_acceptance_blocks_release_until_payee_accepts' (2866) panicked at /home/runner/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/soroban-sdk-27.0.6/src/env.rs:1106:25:
thread 'acceptance_requires_the_payee_and_only_works_while_funded' (2864) panicked at /home/runner/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/soroban-sdk-27.0.6/src/env.rs:1106:25:
test result: FAILED. 0 passed; 3 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s
error: test failed, to rerun pass `-p docforum-escrow --test payee_acceptance`

All 3 new payee_acceptance tests fail with HostError: Error(Context, InvalidAction). That's usually a missing env.mock_all_auths() or an auth call the contract doesn't expect. Run cargo test -p docforum-escrow --test payee_acceptance locally. CI will re-run on your next push.

@github-actions github-actions Bot added the needs-rebase Has merge conflicts with main; the author needs to rebase label Oct 20, 2026
@github-actions

Copy link
Copy Markdown

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

# Conflicts:
#	ARCHITECTURE_ESSENTIALS.md
#	README.md
#	sdk/src/generated/contract-client.ts
@Bkizzy16

Copy link
Copy Markdown
Contributor Author

@afeezorobsco-cyber I resolved the current-main conflicts and fixed the payee-acceptance fixture constructor arguments reported by CI. Please review and merge when the checks pass. The PR description still includes Closes #49.

@github-actions github-actions Bot added needs-rebase Has merge conflicts with main; the author needs to rebase and removed needs-rebase Has merge conflicts with main; the author needs to rebase labels Oct 21, 2026
@github-actions

Copy link
Copy Markdown

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

@afeezorobsco-cyber

Copy link
Copy Markdown
Contributor

@Bkizzy16 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 method takes 9 arguments but 8 arguments were supplied
error: could not compile `docforum-escrow-factory` (test "factory_instances") due to 2 previous errors

SDK bindings match contract WASM

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

A create_escrow call in the factory tests (factory_instances) is missing the newest argument. main added refund_to (ADR 0009), so pass it as the last argument.

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.

@github-actions

Copy link
Copy Markdown

@Bkizzy16 This PR now has merge conflicts with main, most likely because #258 (Feat/sdk lifecycle amendments 84) 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

Copy link
Copy Markdown

@Bkizzy16 This PR now has merge conflicts with main, most likely because #143 (feat(contract): add constrained M-of-N releaser account) 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

Copy link
Copy Markdown

@Bkizzy16 This PR now has merge conflicts with main, most likely because #202 (feat(security): formal verification spike for invariants I1–I3) 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

Copy link
Copy Markdown

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

1 similar comment
@github-actions

Copy link
Copy Markdown

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

Copy link
Copy Markdown
Contributor

@Bkizzy16 This PR conflicts with main, so it can't be merged yet. Please rebase onto the latest main:

git fetch upstream
git rebase upstream/main
# fix the conflicts, then
git push --force-with-lease

If the conflict is in ROADMAP.md's changelog, move your entry into a changelog.d/ fragment instead of editing ROADMAP.md.

@github-actions

Copy link
Copy Markdown

@Bkizzy16 This PR now has merge conflicts with main, most likely because #262 (chore(sdk): refresh lockfile to clear axios/follow-redirects advisories) 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

Copy link
Copy Markdown

@Bkizzy16 This PR now has merge conflicts with main, most likely because #210 (feat(ci): futurenet compatibility checks ahead of Stellar protocol upgrades) 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.

1 similar comment
@github-actions

Copy link
Copy Markdown

@Bkizzy16 This PR now has merge conflicts with main, most likely because #210 (feat(ci): futurenet compatibility checks ahead of Stellar protocol upgrades) 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

Copy link
Copy Markdown
Contributor

@Bkizzy16 This PR conflicts with main again after your latest push, so it can't be merged yet. Please rebase onto the latest main:

git fetch upstream
git rebase upstream/main
# fix the conflicts, then
git push --force-with-lease

If the conflict is in ROADMAP.md's changelog, move your entry into a changelog.d/ fragment instead of editing ROADMAP.md.

@github-actions

Copy link
Copy Markdown

@Bkizzy16 This PR now has merge conflicts with main, most likely because #210 (feat(ci): futurenet compatibility checks ahead of Stellar protocol upgrades) 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.

@Bkizzy16

Copy link
Copy Markdown
Contributor Author

Note for maintainers: the ADR was renumbered from 0008 to 0012, because main already uses 0008 and 0011. The contract interface changed (integrator argument). Bindings are regenerated and the drift check passes. Tests pass for the escrow, factory and releaser-account crates.

Add a factory contract that pins the escrow WASM hash and deploys one
deterministic, immutable escrow per integrator (issue DocForum#49, ADR 0012).
The escrow constructor takes an optional integrator recorded as
informational metadata. Workspace builds, isolation tests, regenerated
bindings, and changelog/changeset entries are included.

Merged origin/main (pooled escrows, payee acceptance, releaser rotation)
and resolved: escrow DataKey and Cargo.toml conflicts, duplicate ADR 0008
renumbered to 0012, error codes unchanged (no new escrow errors).
@github-actions

Copy link
Copy Markdown

@Bkizzy16 This PR now has merge conflicts with main, most likely because #210 (feat(ci): futurenet compatibility checks ahead of Stellar protocol upgrades) 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 github-actions Bot removed the needs-rebase Has merge conflicts with main; the author needs to rebase label Oct 25, 2026
SABA-SOL and others added 2 commits October 26, 2026 09:42
Keep upstream's resource_profile bench target on the escrow crate; the
release profile stays at the new workspace root.
@afeezorobsco-cyber

Copy link
Copy Markdown
Contributor

fix CI. failure

@github-actions github-actions Bot added the needs-rebase Has merge conflicts with main; the author needs to rebase label Oct 27, 2026
@github-actions

Copy link
Copy Markdown

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

@afeezorobsco-cyber

Copy link
Copy Markdown
Contributor

@Bkizzy16 CI is failing.

The Go SDK integration (local quickstart) job fails when deploying the contract:

ℹ️  Simulating transaction…
❌ error: transaction simulation failed: HostError: Error(Context, InternalError)

The deploy step passes constructor arguments that no longer match __constructor in contracts/escrow/src/lib.rs after merging main. Check every constructor parameter (name, type, and order) against the stellar contract deploy ... -- <args> line in .github/workflows/sdk-go.yml. Main passes this job with --allowed_tokens '[]' only.

Please fix and push.

@zeemscript

Copy link
Copy Markdown

@afeezorobsco-cyber The current head still conflicts with main. The reported Go quickstart failure reaches escrow contract deployment and ends with transaction simulation HostError: Error(Context, InternalError); the other current CI jobs pass, including the malware scan. I have not pushed a speculative contract change because the failing deployment needs diagnosis against the updated factory/contract setup. Please advise if there is a current quickstart deployment command or expected contract configuration for this PR.

@Bkizzy16

Copy link
Copy Markdown
Contributor Author

@afeezorobsco-cyber I resolved the current-main conflict on this PR and updated the factory child constructor for the current fee/liability API. The full Rust contract workspace, formatting check, release WASM build, generated-binding check, and resource-baseline check pass locally. PR #146 is currently mergeable, and the refreshed malware scan passed. The Go quickstart deploy failure from the prior run needs a fresh CI result on this head. I added docs/audit/delta-issue-49-escrow-factory.md and request the independent delta review required for this contract change.

@github-actions github-actions Bot removed the needs-rebase Has merge conflicts with main; the author needs to rebase label Oct 28, 2026
@afeezorobsco-cyber

Copy link
Copy Markdown
Contributor

@Bkizzy16 (cc @SABA-SOL) The factory merge looks good. One blocker remains: #154 merged first and moved main's CONTRACT_VERSION to 2.3.0, which is the same value this PR uses. So after updating the branch, the "Require a contract version bump when lib.rs changes" step fails, because the version is unchanged relative to main.

Please bump pub const CONTRACT_VERSION in contracts/escrow/src/lib.rs to 2.4.0 (and update any test that asserts the version, e.g. version_reports_the_contract_semver), regenerate the SDK bindings if they embed it, and push. Pull first: I updated the branch with main (5679822).

@afeezorobsco-cyber

Copy link
Copy Markdown
Contributor

@Bkizzy16 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/49-feat-contract-deploy-isolated-escrows-pe.md:

    bump: minor
    ---
    Issue #49: 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. 4900) 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.

@github-actions github-actions Bot added the needs-rebase Has merge conflicts with main; the author needs to rebase label Nov 1, 2026
@github-actions

github-actions Bot commented Nov 1, 2026

Copy link
Copy Markdown

@Bkizzy16 This PR now has merge conflicts with main, most likely because #271 (chore(contract): fold contract changes into 2.5.0 and fold changelog) 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-rebase Has merge conflicts with main; the author needs to rebase

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Phase E5] Escrow factory contract: deploy isolated escrow instances per integrator

4 participants