diff --git a/README.md b/README.md index 752575d..8fad7ff 100644 --- a/README.md +++ b/README.md @@ -363,3 +363,9 @@ The current public flows are `create_escrow`, `fund_escrow`, `release_escrow`, ` ## License MIT + +## DevEx Task Docs + +- Web3 Dashboard Mock Documentation: `docs/post-task211.md` +- Stellar Explorer Metadata Integration: `docs/post-task213.md` +- Explorer metadata template: `docs/stellar-expert-metadata.json` diff --git a/contracts/marketx/src/lib.rs b/contracts/marketx/src/lib.rs index 8d6b539..a44cdc5 100644 --- a/contracts/marketx/src/lib.rs +++ b/contracts/marketx/src/lib.rs @@ -92,7 +92,7 @@ //! - Reentrancy protection on critical paths //! - Comprehensive input validation -use soroban_sdk::{contract, contractimpl, Address, Bytes, BytesN, Env, Vec}; +use soroban_sdk::{contract, contractimpl, contractmeta, Address, Bytes, BytesN, Env, Vec}; mod errors; mod types; @@ -181,6 +181,24 @@ mod test; /// /// This contract provides secure escrow services on the Stellar network. /// All public methods are available through the contract's public interface. +#[contractmeta(key = "name", val = "MarketX Escrow")] +#[contractmeta( + key = "description", + val = "Soroban escrow contract with milestone releases, dispute handling, and configurable fees." +)] +#[contractmeta( + key = "homepage", + val = "https://github.com/MarketXpress/MarketX-contract" +)] +#[contractmeta( + key = "repository", + val = "https://github.com/MarketXpress/MarketX-contract" +)] +#[contractmeta( + key = "source", + val = "https://github.com/MarketXpress/MarketX-contract/tree/main/contracts/marketx" +)] +#[contractmeta(key = "version", val = "v1.0.0")] #[contract] pub struct Contract; diff --git a/docs/post-task211.md b/docs/post-task211.md new file mode 100644 index 0000000..e0ee40c --- /dev/null +++ b/docs/post-task211.md @@ -0,0 +1,122 @@ +# Web3 Dashboard Mock Documentation +## Task #211 — DevEx & Ecosystem Tooling + +This document provides a stakeholder-friendly dashboard blueprint that maps contract behavior into product-level KPIs. + +--- + +## 1) Purpose + +The MarketX escrow contract already emits enough information for a complete operational dashboard. This mock documentation translates on-chain concepts into business-facing tiles, charts, and workflow views. + +Primary audience: +- Product managers +- Operations / support teams +- Community stakeholders +- Non-technical ecosystem partners + +--- + +## 2) Dashboard Information Architecture + +### A. Executive Header (Top Row) + +1. **Total Escrow Volume (XLM + tokens)** + - Source: Aggregate of `FundsReleasedEvent.amount` +2. **Open Escrows** + - Source: `EscrowStatus == Pending || Disputed` +3. **Settlement Rate** + - Source: `Released / Created` over selected window +4. **Dispute Rate** + - Source: `RefundRequestedEvent` + disputed status transitions + +### B. Activity & Health (Middle Row) + +1. **Escrows Created Over Time** (line chart) + - Source: `EscrowCreatedEvent` +2. **Release vs Refund Mix** (stacked bars) + - Source: `StatusChangeEvent` terminal states +3. **Fee Revenue Trend** (area chart) + - Source: `FeeCollectedEvent`, `FeesWithdrawnEvent` +4. **Median Time to Settlement** + - Source: `created_ledger -> released/refunded ledger` + +### C. Operations Queue (Bottom Row) + +1. **Aging Pending Escrows** + - Highlight by ledger age buckets (0-1d, 1-3d, 3d+) +2. **Disputes Needing Arbiter Attention** + - Source: disputed escrows without terminal resolution +3. **Recently Expired Unfunded Escrows** + - Source: `EscrowExpiredEvent` + +--- + +## 3) Contract Data Mapping (Indexer Specification) + +### Events to index + +- `EscrowCreatedEvent` +- `FundsReleasedEvent` +- `StatusChangeEvent` +- `RefundRequestedEvent` +- `EscrowExpiredEvent` +- `FeeCollectedEvent` +- `FeesWithdrawnEvent` + +### Read methods used for enrichment + +- `get_escrow(escrow_id)` +- `get_escrow_metadata(escrow_id, caller)` +- `resource_profile()` +- `analytics_summary()` (if enabled in deployment profile) + +> Recommendation: keep event ingestion append-only and perform reconciliation jobs with `get_escrow` for any escrow IDs that hit disputed or expired states. + +--- + +## 4) KPI Definitions (Business-safe wording) + +- **Gross Settled Volume**: Sum of released amounts before fee withdrawal events. +- **Protocol Fee Accrual**: Sum of `FeeCollectedEvent.fee_amount` by token. +- **Protocol Fee Realization**: Sum of `FeesWithdrawnEvent.amount` by token. +- **Escrow Completion Rate**: Count(Released) / Count(Created). +- **Dispute Escalation Rate**: Count(Disputed transitions) / Count(Created). +- **Refund Rate**: Count(Refunded) / Count(Created). + +--- + +## 5) Dashboard Mock (Text Wireframe) + +```text +┌──────────────────────────────────────────────────────────────────────────┐ +│ MarketX Protocol Dashboard [7d] [30d] [90d]│ +├───────────────┬───────────────┬───────────────┬──────────────────────────┤ +│ Volume │ Open Escrows │ Settlement % │ Dispute % │ +│ 1,284,331 XLM │ 184 │ 94.2% │ 1.8% │ +├──────────────────────────────────────────────────────────────────────────┤ +│ Escrows Created (line) │ Fee Revenue by Token (stacked) │ +├──────────────────────────────────────────────────────────────────────────┤ +│ Release vs Refund Mix (bars) │ Median Settlement Time │ +├──────────────────────────────────────────────────────────────────────────┤ +│ Aging Pending Escrows │ Disputes Awaiting Resolution │ +└──────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 6) Stakeholder Views + +- **Product View**: growth, completion, dispute trends +- **Support View**: pending/disputed queues, top risky escrows +- **Treasury View**: accrued vs withdrawn fees by token +- **Community View**: transparent protocol health snapshots + +--- + +## 7) Delivery Checklist + +- [x] Data source mapping to real contract events/methods +- [x] KPI definitions for non-technical audiences +- [x] Operational queues for day-to-day monitoring +- [x] Wireframe mock suitable for design handoff diff --git a/docs/post-task213.md b/docs/post-task213.md new file mode 100644 index 0000000..2291388 --- /dev/null +++ b/docs/post-task213.md @@ -0,0 +1,66 @@ +# Integration with Stellar Explorer Metadata +## Task #213 — DevEx & Ecosystem Tooling + +This task improves how the MarketX contract appears on Stellar explorers (including Stellar.expert) by embedding contract metadata in the WASM and documenting optional off-chain metadata publication. + +--- + +## 1) What was integrated + +### A. On-chain contract metadata annotations + +The contract now includes Soroban `#[contractmeta]` entries for: +- Name +- Description +- Homepage URL +- Repository URL +- Source code URL +- Build/version tag + +These values are bundled into the contract artifact and can be consumed by explorer tooling that reads Soroban metadata sections. + +### B. Off-chain explorer profile template + +A companion metadata template is provided at: +- `docs/stellar-expert-metadata.json` + +This gives the ops/devrel team a canonical payload for explorer profiles, registry submissions, or internal metadata services. + +--- + +## 2) Explorer-facing recommendations + +1. Keep `version` aligned with release tags. +2. Keep homepage + repo links stable and publicly accessible. +3. Use a deterministic icon URL (CDN/IPFS with immutable hash when possible). +4. Update metadata alongside every production contract upgrade. + +--- + +## 3) Verification flow + +After deployment, verify that metadata is discoverable: + +1. Build and deploy the updated WASM. +2. Open the contract page on Stellar.expert. +3. Confirm readable project identity fields (name/description/links). +4. Cross-check values against `docs/stellar-expert-metadata.json`. + +--- + +## 4) Operational runbook snippet + +- During release prep: + - bump `version` metadata value + - verify repo/homepage links +- During deploy: + - publish the new WASM +- Post-deploy: + - validate explorer rendering + - publish release note referencing new contract ID + +--- + +## 5) Outcome + +MarketX now exposes cleaner project identity metadata for ecosystem tooling and contract explorers, improving discoverability and trust for non-technical users. diff --git a/docs/stellar-expert-metadata.json b/docs/stellar-expert-metadata.json new file mode 100644 index 0000000..59b67e6 --- /dev/null +++ b/docs/stellar-expert-metadata.json @@ -0,0 +1,15 @@ +{ + "name": "MarketX Escrow", + "description": "Soroban escrow contract for milestone releases, dispute handling, and configurable marketplace fees.", + "homepage": "https://github.com/MarketXpress/MarketX-contract", + "repository": "https://github.com/MarketXpress/MarketX-contract", + "source": "https://github.com/MarketXpress/MarketX-contract/tree/main/contracts/marketx", + "version": "v1.0.0", + "tags": [ + "stellar", + "soroban", + "escrow", + "marketplace" + ], + "icon": "https://raw.githubusercontent.com/MarketXpress/MarketX-contract/main/docs/assets/marketx-icon.png" +}