[Azintar]

There was no on-chain way to slow down a live bug: the only defence was telling integrators to stop. This adds a narrow lever instead — a single custodian set by the contract's constructor can block create_escrow and nothing else, so new exposure stops while every existing escrow can still be released, refunded, or timeout-refunded. Blocking outbound paths would have turned a possible loss into a certain lock, which is why the pause deliberately does not read the flag there (and the 16 new tests prove it).

Records the decision in ADR 0005, adds the role to the threat model (T11, invariant I6), and regenerates/bumps the SDK to 0.4.0 for the new pause/unpause/is_paused/get_pause_admin surface.

Closes #35

🤖 Generated with Codebuff

What changed

Which ROADMAP.md item does this close/progress?

(required — see AGENTS.md doc-update rules)

Docs updated in this PR (check all that apply)

• ROADMAP.md
• ARCHITECTURE.md
• ARCHITECTURE_ESSENTIALS.md
• PRD.md
• N/A for this change

[github-actions]

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

[drips-wave]

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

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

[github-actions]

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

[github-actions]

@Azintar This PR now has merge conflicts with main, most likely because #193 (feat(sdk): milestone escrow 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.}

[github-actions]

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

[afeezorobsco-cyber]

@Azintar 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 (Bun), TypeScript SDK (Node 20), TypeScript SDK (Node 24)

src/generated/contract-client.ts(130,8): error TS1005: ',' expected.
src/generated/contract-client.ts(130,14): error TS1005: ',' expected.
src/generated/contract-client.ts(130,19): error TS1005: ',' expected.
src/generated/contract-client.ts(130,23): error TS1005: ',' expected.
src/generated/contract-client.ts(130,30): error TS1005: ',' expected.
src/generated/contract-client.ts(130,35): error TS1005: ',' expected.
src/generated/contract-client.ts(130,40): error TS1005: ',' expected.
src/generated/contract-client.ts(130,57): error TS1005: ',' expected.

Also failing: React hooks package, TypeScript SDK (Node 22), Soroban contract (test + wasm build), TypeScript SDK (Deno), TypeScript SDK (Chromium), SDK bindings match contract WASM.

sdk/src/generated/contract-client.ts is broken at line 130 (invalid characters, probably leftover conflict markers or a hand merge). Don't hand-edit or hand-merge it. Regenerate it:

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

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

[github-actions]

Malware scan: passed, with notes for the reviewer

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

Where	Rule	Why
.github/workflows/sdk-go.yml:59	workflow-change	Changes a CI workflow; a maintainer must review before approving runs.

[github-actions]

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

@Azintar This PR now has merge conflicts with main, most likely because #247 (feat(sdk): add multisig releaser setup helpers with lock-out validation) 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]

@Azintar This PR now has merge conflicts with main, most likely because #254 (feat(contract): batch release and refund for fast settlement of many escrows) 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]

@Azintar I resolved this PR's earlier conflicts with main (commit 1a8e553: docs/threat-model.md, plus SDK bindings regenerated with stellar CLI 28.1.0). Since then #254 (batch settle_many) has merged, and this PR conflicts again, this time in contract code:

README.md
contracts/escrow/src/lib.rs
contracts/escrow/tests/liabilities.rs
sdk/src/generated/contract-client.ts

What's needed:

1. lib.rs: merge your emergency pause with settle_many. Decide whether settle_many's release/refund ops need the same pause rules as single release/refund (per ADR 0011, the pause stops new deposits but must never block outbound paths).
2. CONTRACT_VERSION: main is now 2.2.0 (from feat(contract): batch release and refund for fast settlement of many escrows #254), so this PR needs 2.3.0 or higher.
3. Bindings: regenerate sdk/src/generated/contract-client.ts with stellar CLI 28.1.0 (scripts/check-generated-bindings.sh shows the exact commands), and refresh any test_snapshots/ that change.

Please git pull first so you start from my merge commit, then merge main, run cargo test in contracts/escrow, and push.

[afeezorobsco-cyber]

@Azintar This branch was updated with main through GitHub's web conflict editor (e73f035), and that resolution dropped your three pause error variants from pub enum Error, while the code still uses them. The contract no longer compiles:

error[E0599]: no variant ... named `Paused` found for enum `Error`         --> src/lib.rs:683:31
error[E0599]: no variant ... named `AlreadyPaused` found for enum `Error`  --> src/lib.rs:1699:31
error[E0599]: no variant ... named `NotPaused` found for enum `Error`      --> src/lib.rs:1718:31

Please git pull, then re-add Paused, AlreadyPaused and NotPaused to Error, numbered after the highest code currently on main. Codes are append-only, so don't renumber existing ones. CONTRACT_VERSION must also be above main's current 2.3.0. Then run cargo test in contracts/escrow, regenerate the SDK bindings with stellar CLI 28.1.0, and push.

[afeezorobsco-cyber]

@Azintar 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/35-emergency-pause.md:

   bump: minor
   ---
   Issue #35: 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. Re-add your pause errors with provisional codes: Paused = 3500, AlreadyPaused = 3501, NotPaused = 3502 (issue [Phase E5] ADR + implementation: emergency pause that can only stop new escrows #35 × 100 + n). The web-editor merge I mentioned earlier dropped them, so this fixes that compile error too. The fold assigns the final numbers.

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]

@Azintar This PR now has merge conflicts with main, most likely because #199 (feat(contract): payee rights transfer: payee reassigns future payout to a new address) 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]

@Azintar Thanks for repairing the pause merge. The contract checks now pass. What's left is sdk/src/generated/contract-client.ts, which was merged by hand and is no longer valid TypeScript. Line 606 ends get_pause_admin, and the /** that should open the next doc comment (for transfer_payee) is missing, so every SDK job fails:

src/generated/contract-client.ts(607,4): error TS1131: Property or signature expected.
src/generated/contract-client.ts(607,16): error TS1005: ';' expected.
...

Don't fix it by hand. Regenerate the file from your merged contract with stellar CLI 28.1.0:

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   # must print OK

Then push. Everything else on this PR is green.

[Azintar]

@afeezorobsco-cyber
Awaiting review sir

[afeezorobsco-cyber]

@Azintar The latest merge from main broke two things:

1. sdk/src/generated/contract-client.ts is malformed at line 607, where the /** opening the transfer_payee doc comment was lost, so every TypeScript SDK job fails to compile:

   src/generated/contract-client.ts(607,4): error TS1131: Property or signature expected.
   

   Don't hand-merge this file. Regenerate it from the contract WASM with scripts/check-generated-bindings.sh (stellar CLI pinned in scripts/stellar-cli-version) so "SDK bindings match contract WASM" passes too.
2. contracts/escrow/tests/events.rs (from main) doesn't pass pause_admin: it still registers the contract with (Vec::<Address>::new(&env),), so the constructor fails (Error(WasmVm, InvalidAction)) and all 7 event tests panic. Update those env.register(...) calls (lines 88, 166, 340, 488, 550) to pass a pause admin, as you did in the other test files.

[Azintar]

@afeezorobsco-cyber please review
I applied the requested fix

[afeezorobsco-cyber]

@Azintar Thanks, that fixed it: the contract tests, the events.rs constructor calls and all TypeScript SDK jobs now pass. One check is still red, SDK bindings match contract WASM. When you resolved the contract-client.ts conflict, the PayeeRefunded event spec entry ("AAAABQAAAEJJZGVudGlmaWVzIHZvbHVudGFyeSByZWZ1bmRz…", from #40) ended up in the wrong position in the ContractSpec([...]) list:

@@ -757,12 +757,12 @@
-        "AAAABQAAAEJJZGVudGlmaWVzIHZvbHVudGFyeSByZWZ1bmRzIH…   (committed: before the function entries)
         "AAAAAAAAAftCbG9ja3MgbmV3IGRlcG9zaXRzIChgY3JlYXRlX2…
         …
         "AAAAAAAAAHVBZGRzIGZ1bmRzIHRvIGEgZnVuZGVkIGVzY3Jvdy…
+        "AAAABQAAAEJJZGVudGlmaWVzIHZvbHVudGFyeSByZWZ1bmRzIH…   (generated: here)

Please don't reorder it by hand. Regenerate the file with the pinned CLI (scripts/stellar-cli-version, 28.1.0) using the steps that scripts/check-generated-bindings.sh prints, and commit the result. This is the last failing check; once it's green the PR can merge.

[Azintar]

@afeezorobsco-cyber pr is now mergeable

[afeezorobsco-cyber]

Malware scan clean, all checks green, bindings regenerated. Thanks!