[CT-15] Build cross-contract shipment and escrow validation

[mftee]

Problem

The shipment and escrow contracts are entirely independent. A carrier could call release_funds on the escrow contract while the corresponding on-chain shipment record still shows InTransit, bypassing the delivery confirmation requirement and receiving payment before the goods are received.

Proposed Solution

Create a validator contract inside contracts/package/cross-contract-validator/ that performs atomic cross-contract checks before allowing escrow release.

Note: All work must be done inside the contracts/package/ directory. Do not modify any existing contract files outside this folder.

Acceptance Criteria

• validate_and_release(shipment_id: BytesN<32>, escrow_id: BytesN<32>) function
• Calls the shipment contract to verify shipment status is DELIVERED; returns ShipmentNotDelivered otherwise
• Calls the escrow contract to verify escrow is in FUNDED state; returns EscrowNotFunded otherwise
• Only proceeds with release if both checks pass
• Uses Soroban cross-contract invocation (soroban_sdk invoke_contract)
• Returns a structured result indicating which check failed if the release is blocked
• Unit tests mock both the shipment and escrow contracts using the Soroban test environment

[limxiy]

@limxiy has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

I’d like to work on this issue. I have experience building Soroban smart contracts and cross-contract validation flows, and I can implement the validator contract to enforce atomic shipment and escrow checks before fund release.

Planned implementation:

• Create the cross-contract-validator contract inside contracts/package/
• Implement validate_and_release(shipment_id, escrow_id) using Soroban cross-contract invocation
• Verify shipment status is DELIVERED before release
• Verify escrow status is FUNDED before release
• Return structured failure results for blocked releases
• Only execute escrow release when both validations succeed
• Add unit tests with mocked shipment and escrow contracts using the Soroban test environment

All changes will remain scoped to:

• contracts/package/cross-contract-validator/

ℹ️ Repo Maintainers: To accept this application, review their application or assign @limxiy to this issue.

[drips-wave]

Congratulations, @limxiy! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @limxiy: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊