feat(stellar): route locks, Soroban compatibility, simulation diffs, and pre-exec safety

[p3ris0n]

Summary

This PR ships four related Stellar/Soroban pre-execution guards as one change set. Together they pin the route the user selected, confirm the on-chain contract matches BridgeWise’s expected interface, surface material simulation drift when a tx or route changes, and block signing unless a full safety pipeline passes.

---

Why

During preparation, quotes can refresh and routes can be recalculated. Without a lock, the user can sign a different path than the one they picked. Independently, Soroban deployments can drift in methods or arguments, simulation results can change after parameter tweaks, and several safety checks currently live as separate concerns that are easy to skip before signing.

---

#997 — Stellar bridge route lock

Problem: Concurrent quote refreshes or route recalculations can cause the user to sign a different route from the one originally selected.

Solution: StellarBridgeRouteLockService (src/routing/locks/stellar/) associates a lock with an execution ID.

Behavior

• Acquire a lock for executionId + selected route (provider, assets, quoted in/out).
• Configurable duration (default 120s); clock is injectable for tests.
• Route identity is a fingerprint of route id, provider, assets, and quoted amounts.
• While active, a different route is rejected (guardRouteUpdate / re-acquire). The same route can be re-acquired (idempotent).
• Release after execution (releaseAfterExecution) or when the TTL expires (sweepExpired / lazy purge on read).
• Execution-layer re-export: src/execution/route-lock.ts.

Acceptance

• Route locking implemented
• Locked routes cannot be replaced unexpectedly
• Lock expiration supported
• Locks released after execution

Tests: tests/routing/locks/stellar-bridge-route-lock.spec.ts

---

#998 — Soroban contract compatibility checker

Problem: Contract deployments can differ in methods, arguments, or supported behavior versus the BridgeWise interface.

Solution: Expected capabilities live in src/contracts/metadata/bridgewise-interface.ts. SorobanContractCompatibilityChecker (src/soroban/compatibility/) compares resolved ContractInterfaceMetadata against that spec.

Expected interface (defaults)

• bridge(source_chain, target_chain, amount, recipient)
• quote(source_chain, target_chain, amount)
• cancel(operation_id)
• Metadata must include address, network, and a functions list; unusable metadata status is rejected.

Result shape

Returns compatible, issues[] (codes such as MISSING_METHOD, ARGUMENT_COUNT_MISMATCH, ARGUMENT_NAME_MISMATCH, ARGUMENT_TYPE_MISMATCH, METADATA_MISSING), plus verifiedMethods / missingMethods. Incompatible contracts are rejected (compatible: false).

Acceptance

• Compatibility checker implemented
• Required methods verified
• Incompatible contracts rejected
• Compatibility results exposed

Tests: tests/soroban/compatibility/soroban-contract-compatibility-checker.spec.ts

---

#996 — Soroban transaction simulation diff

Problem: Changes to transaction parameters can significantly alter resource usage or expected outcomes, and those shifts are hard to see without a structured before/after.

Solution: SorobanSimulationDiffService (src/soroban/simulation/diff/) compares two simulation snapshots.

Compared

• Resources: CPU instructions, memory, ledger read/write bytes, fee (numeric delta; material if |delta| ≥ threshold)
• Expected output: stable JSON serialization
• Events: added / removed / unchanged by type, topics, and data

Configurable MaterialDifferenceThresholds (default: any change of 1+ is material). Result includes hasChanges, hasMaterialDifferences, resourceChanges, outputChanged, eventChanges, and a human-readable summary.

Re-exported from src/soroban/simulation.

Acceptance

• Simulation diff service implemented
• Resource changes detected
• Output changes detected
• Material differences reported

Tests: tests/soroban/simulation/soroban-simulation-diff.spec.ts

---

#999 — Stellar bridge pre-execution safety pipeline

Problem: Multiple independent checks need to be coordinated before the user signs.

Solution: StellarPreExecutionSafetyPipeline (src/execution/safety/stellar/) always runs the full set of validators in src/execution/validation/. Any error blocks signing. Failures include code, reason, and an actionable action string.

Checks (all executed)

Check	What it validates
Quote freshness	Quoted-at + TTL vs now; stale quotes must be refreshed
Destination account	G/C StrKey shape, exists, funded
Asset balance	Transfer amount and fee vs available balances
Trustlines	Required destination assets have trustlines
Minimum output	Quoted output ≥ min accepted
Transaction resources	Simulated CPU / memory / fee vs limits
Contract compatibility	BridgeWise-compatible contract (feeds #998)

Consolidated result: safe, blocked, checkedAt, per-check results, and a flat failures list.

Acceptance

• Pre-execution safety pipeline implemented
• All required validation checks executed
• Unsafe transactions blocked before signing
• Validation failures include actionable reasons
• Pipeline tests cover success and failure scenarios

Tests: tests/execution/safety/stellar-pre-execution-safety-pipeline.spec.ts

---

How these pieces fit

select route → lock (#997)
            → simulate & diff if params changed (#996)
            → compatibility check (#998)
            → safety pipeline (#999)
            → sign only if safe && lock still holds the same route

The pipeline can consume compatibility output; the lock should still be held through signing so a late quote refresh cannot swap the route.

---

Test plan

• Route lock: acquire by execution ID, reject a conflicting route, allow the same route, expire after TTL, release after execution
• Compatibility: matching metadata passes; missing methods / argument mismatches / missing metadata fail
• Simulation diff: CPU/resource deltas, output changes, event add/remove, identical snapshots have no material diff
• Safety pipeline: all-green context is safe; stale quote, missing trustline, low output, incompatible contract, insufficient balance, and resource overruns set blocked with actionable failures
• Confirm Nest/API build still uses apps/api/tsconfig.json (this PR does not change app wiring; services are standalone and can be composed at the execution layer)

Closes #996
Closes #997
Closes #998
Closes #999

[drips-wave]

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