[CT-16] Add on-chain event emission for all shipment state transitions

[mftee]

Problem

The shipment contract changes state without emitting any Soroban events. External indexers, analytics systems, and the FreightFlow backend have no way to react to on-chain state changes without polling every contract state, which is impractical and expensive.

Proposed Solution

Create a new shipment contract inside contracts/package/shipment-events/ that emits a structured Soroban event on every state transition.

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

Acceptance Criteria

• Events emitted for all transitions: ShipmentCreated, ShipmentAccepted, InTransit, Delivered, Completed, Disputed, Cancelled
• Each event payload includes: shipment_id, new_status, actor_address, ledger_timestamp
• Events use env.events().publish() as per the Soroban SDK specification
• Event topic is a (Symbol, BytesN<32>) tuple of (event_name, shipment_id) for efficient indexer filtering
• Unit tests use the Soroban test harness to assert that the correct event is emitted with the correct payload for each transition

[Abusadiq78]

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

I would like to work on this issue please

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

[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 event-driven Soroban contracts and blockchain indexing integrations, and I can implement the shipment event emission system with structured transition events and full test coverage.

Planned implementation:

• Create the new shipment-events contract inside contracts/package/

• Emit structured events for all shipment state transitions:

  • ShipmentCreated
  • ShipmentAccepted
  • InTransit
  • Delivered
  • Completed
  • Disputed
  • Cancelled

• Use env.events().publish() following Soroban SDK conventions

• Structure event topics as (Symbol, BytesN<32>) tuples for efficient indexer filtering

• Include shipment_id, new_status, actor_address, and ledger_timestamp in event payloads

• Add unit tests validating emitted topics and payload contents for every transition

All work will remain scoped to:

• contracts/package/shipment-events/

ℹ️ 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 🌊