Contract: Create On-Chain Analytics Tracker for Platform Metrics

[mftee]

Description:
Build a smart contract that aggregates and stores key platform metrics on-chain, providing transparent, verifiable statistics about platform usage and performance.

Contract Purpose:
Track and aggregate important platform metrics on-chain to provide transparent analytics that anyone can verify, supporting data-driven decision making and platform transparency.

Core Functionality to Implement:

1. Data Structures

PlatformMetrics:

• total_shipments
• total_completed_shipments
• total_active_shipments
• total_cancelled_shipments
• total_users
• total_carriers
• total_shippers
• total_volume_usd (total value of all shipments)
• total_distance_km (sum of all shipment distances)
• total_payments_processed
• last_updated (timestamp)

DailySnapshot:

• date (UNIX timestamp truncated to day)
• new_shipments
• completed_shipments
• new_users
• active_carriers
• volume_usd
• average_delivery_time_hours
• on_time_percentage

CarrierMetrics:

• carrier_address
• total_shipments_completed
• total_shipments_active
• total_revenue
• average_rating
• on_time_deliveries
• late_deliveries
• total_distance_km
• last_updated

ShipperMetrics:

• shipper_address
• total_shipments_created
• total_shipments_completed
• total_spent
• average_cost_per_shipment
• preferred_carriers (array of top 3)
• last_shipment_timestamp

RouteMetrics:

• route_hash (hash of origin + destination)
• origin
• destination
• shipment_count
• average_cost
• average_duration_hours
• most_common_carrier

2. Storage

• PlatformMetrics singleton (one global record)
• Map of date to DailySnapshot
• Map of carrier_address to CarrierMetrics
• Map of shipper_address to ShipperMetrics
• Map of route_hash to RouteMetrics
• Array of last 30 daily snapshots (for quick access)

3. Contract Functions

Record Shipment Created:

• Takes shipment_id, shipper_address, origin, destination, value
• Increments total_shipments
• Increments total_active_shipments
• Updates shipper metrics
• Updates route metrics
• Updates today's snapshot
• Only callable by Shipment contract
• Emits ShipmentRecorded event

Record Shipment Completed:

• Takes shipment_id, carrier_address, shipper_address, final_cost, duration_hours, distance_km, on_time
• Increments total_completed_shipments
• Decrements total_active_shipments
• Updates carrier metrics (completed, revenue, on_time/late)
• Updates shipper metrics (completed, total_spent)
• Updates route metrics
• Adds to total_distance_km
• Updates today's snapshot
• Only callable by Shipment contract
• Emits ShipmentCompletedRecorded event

Record Shipment Cancelled:

• Takes shipment_id
• Increments total_cancelled_shipments
• Decrements total_active_shipments
• Only callable by Shipment contract
• Emits ShipmentCancelledRecorded event

Record User Registered:

• Takes user_address, user_type (Carrier or Shipper)
• Increments total_users
• If Carrier, increment total_carriers
• If Shipper, increment total_shippers
• Initializes CarrierMetrics or ShipperMetrics
• Updates today's snapshot
• Only callable by Access Control contract
• Emits UserRegisteredRecorded event

Record Payment:

• Takes payment_amount
• Increments total_payments_processed
• Adds to total_volume_usd
• Only callable by Escrow contract
• Emits PaymentRecorded event

Get Platform Metrics:

• Returns complete PlatformMetrics struct
• Public read function

Get Daily Snapshot:

• Takes date (timestamp)
• Returns DailySnapshot for that date
• Public read function

Get Carrier Metrics:

• Takes carrier_address
• Returns CarrierMetrics
• Public read function

Get Shipper Metrics:

• Takes shipper_address
• Returns ShipperMetrics
• Public read function

Get Route Metrics:

• Takes origin and destination
• Computes route_hash
• Returns RouteMetrics
• Public read function

Get Top Routes:

• Returns array of top 10 routes by shipment_count
• Public read function

Get Top Carriers:

• Returns array of top 10 carriers by shipments_completed
• Public read function

Get Weekly Summary:

• Aggregates last 7 daily snapshots
• Returns totals and averages for the week
• Public read function

Get Monthly Summary:

• Aggregates last 30 daily snapshots
• Returns totals and averages for the month
• Public read function

Calculate Average Delivery Time:

• Aggregates delivery times from completed shipments
• Returns average in hours
• Public read function

Calculate On-Time Percentage:

• Calculates (on_time_deliveries / total_completed) * 100
• Returns percentage
• Public read function

4. Events

• ShipmentRecorded(shipment_id, shipper, value, timestamp)
• ShipmentCompletedRecorded(shipment_id, carrier, cost, duration, on_time, timestamp)
• ShipmentCancelledRecorded(shipment_id, timestamp)
• UserRegisteredRecorded(user_address, user_type, timestamp)
• PaymentRecorded(amount, timestamp)
• SnapshotCreated(date, new_shipments, completed_shipments, volume, timestamp)

5. Daily Snapshot Creation

• Automatically create new snapshot at midnight UTC
• Triggered by first transaction of new day
• Carries forward cumulative metrics
• Resets daily counters to zero

Aggregation Calculations:

Average Delivery Time:

Total Delivery Hours / Number of Completed Shipments

On-Time Percentage:

(On-Time Deliveries / Total Completed Deliveries) × 100

Average Cost per Route:

Total Cost for Route / Number of Shipments on Route

Carrier Efficiency Score:

(Completed Shipments × Average Rating × On-Time %) / 100

Integration Points:

• Shipment contract calls record functions when events happen
• Escrow contract calls record_payment on payment processing
• Access Control contract calls record_user on registration
• All calls are one-way (analytics doesn't affect other contracts)

Access Control:

• Only authorized contracts can record metrics
• All read functions are public
• No manual metric updates (only through contract calls)
• Ensures data integrity and accuracy

Acceptance Criteria:

• Platform metrics initialize correctly
• Shipment creation updates all relevant metrics
• Shipment completion updates carrier and shipper metrics
• Cancellation decrements active shipments
• User registration increments counts correctly
• Payment recording updates totals
• Daily snapshots create automatically
• Get functions return accurate data
• Top routes calculation correct
• Top carriers calculation correct
• Weekly/monthly summaries aggregate correctly
• Average calculations accurate
• All recording restricted to authorized contracts
• All events emit correctly
• Unit tests cover all functions (>80% coverage)
• Gas-optimized (efficient aggregations)

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 200 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

Warning

Only applications submitted via the apply link above will be considered. Please do not apply by commenting on the issue or opening a PR directly.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[nottherealalanturing]

@nottherealalanturing has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I’d like to work on this contract. I’ll design and implement the full on-chain analytics tracker, covering platform, daily, carrier, shipper, and route metrics with gas-efficient storage and aggregation. I’ll ensure all record functions are restricted to authorized contracts, daily snapshots are created automatically, and summary queries return accurate results. Events and unit tests will be included, with a focus on correctness, performance, and clean architecture.

Ready to start once assigned.

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

[GoSTEAN]

@GoSTEAN has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Can i work on this?

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

[Sandijigs]

@Sandijigs has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

hi My name is Sandra.
I have reviewed the issue and understand what needs to be done
I am a fullstack software/ Blockchain Engineer with over 6years of experience web2 experience(Fullstack) and 2 year web3 experience (JavaScript,TypeScript, Rust ,Python, Soroban,Solidity,(Backend, frontend, Mobile and smart contracts) ). I have contributed to several projects in the stellar ecosystem. . please Assign this Issue to me

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

[drips-wave]

Congratulations, @nottherealalanturing! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on January 31, 2026.

🧑‍💻 @nottherealalanturing: 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.

⚠️ Important: When opening a PR, please link it to this issue to ensure it gets tracked accurately.

🤠 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 🌊

[dannyy2000]

@dannyy2000 has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I’d like to take on this issue because transparent, verifiable analytics are foundational to trust in any on-chain logistics platform—especially one coordinating shipments, payments, and multiple participant roles at scale.

This contract sits at an important intersection between protocol observability and economic accountability. By aggregating platform, carrier, shipper, and route-level metrics directly on-chain, we enable stakeholders to independently verify usage, performance, and growth without relying on off-chain dashboards alone. That’s a powerful trust primitive.

My approach would focus on correctness, efficiency, and long-term maintainability. I’ll design the core data structures to minimize redundant writes while still supporting rich analytics (daily snapshots, rolling weekly/monthly summaries, and top-N queries). Snapshot creation will be deterministic and gas-conscious, ensuring metrics remain accurate without introducing unnecessary state bloat.

I’ll also be careful about access control boundaries—ensuring only the appropriate system contracts can mutate analytics state—while keeping all read paths public and composable for dashboards, auditors, and governance tooling. Events will be emitted consistently so off-chain indexers can mirror on-chain analytics without ambiguity.

Overall, my goal is to deliver an analytics tracker that is auditable, performant, and extensible, giving the platform a strong data backbone for governance, optimization, and user trust as FreightFlow scales.

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

[Chucks1093]

@Chucks1093 has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hello, I’m a full stack engineer and I want to work on this issue. I’ll design the contract as a clear analytics layer that exposes simple record functions like recordShipmentCreated, recordShipmentCompleted, and recordPayment, with well-structured storage for platform, carrier, shipper, route, and daily snapshot metrics, strict access control so only authorized contracts can write data, and gas-safe aggregation logic for weekly and monthly summaries while keeping all reads public and verifiable.

This will be delivered within 12–18 hours.

Here are some frontend projects I’ve built that show I can deliver blockchain-related work:

• https://blockchain-tutorial.onrender.com/

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

[pope-h]

@pope-h has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I’d like to apply to work on this issue.

I have strong experience designing analytics-focused smart contracts with structured storage, efficient aggregations, and strict access control between contracts. I’m comfortable implementing metric trackers, snapshot systems, and gas-optimized read/write patterns that support dashboards, transparency tools, and indexers.

I can ensure:

Clean and scalable storage design

Deterministic metric updates (no manual mutation)

Proper authorization between Shipment, Escrow, and Access Control contracts

Accurate aggregation logic for daily, weekly, and monthly analytics

Well-structured events and comprehensive unit tests

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

[mijinummi]

@mijinummi has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hi maintainers

I’d like to work on this Contract task.
I have solid experience with:
Smart contract development and on-chain event design
Emitting and indexing analytics-friendly events
Backend listeners/indexers for aggregating on-chain metrics
Designing metrics that balance on-chain efficiency with off-chain analytics needs

Proposed approach:
Define a clear set of analytics events (usage, transactions, volume, user actions)
Emit lightweight, well-structured events from the contract
Ensure gas efficiency and forward-compatible event schemas
Provide clear documentation for indexers and analytics consumers
I’ll keep the implementation modular, well-tested, and aligned with existing platform conventions.

If approved, I can start immediately and do the PR in less than 12hrs.

Thanks!

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

[martinvibes]

@martinvibes has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I’d like to work on this issue because it aligns with my experience building and contributing to web and blockchain projects. I’m comfortable working across frontend and smart contract codebases and delivering clean, well-structured solutions.

I’ve reviewed the issue and repository and can implement a reliable fix while following the project’s standards. I communicate progress clearly and iterate quickly based on feedback. I’d be happy to take this on and would appreciate being assigned.

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

[ShantelPeters]

@ShantelPeters has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

i would like to work on this issue kindly assign please

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