feat: add market metadata URI field specification - #478
Merged
Mimah97 merged 3 commits intoJun 30, 2026
Conversation
Design specification for optional metadata_uri field on Market struct. Enables markets to reference off-chain metadata stored on IPFS, Arweave, or HTTP endpoints. ## Feature Overview Adds optional metadata_uri: Option<String> field to Market struct that: - References off-chain metadata (IPFS, Arweave, HTTP) - Stores rich market metadata (description, images, rules, credentials) - Validates URI format (non-empty, max 2048 chars) - Emits URI in MarketCreatedEvent for off-chain tracking - Requires storage version bump (v3 → v5, skipping v4 close-deposits) ## Implementation Details ### Type Change - Market struct adds: pub metadata_uri: Option<String> - Optional field enables backward compatibility with existing markets ### API Changes - initialize_market() accepts metadata_uri parameter - get_market() returns market with populated metadata_uri - Future: update_market_metadata() for admin updates ### Validation - Non-empty if Some - Max 2048 characters - Format hints: ipfs://, ar://, https:// - New error code: InvalidMetadataUri = 7 ### Storage - Storage version bumped to 5 (breaking change) - Existing v4 markets require migration - ~32 bytes overhead per market ### Off-Chain Integration - Recommended JSON metadata schema provided - Supports multiple storage backends - No on-chain metadata validation - URI accessibility verified off-chain ## Use Cases ✓ Store market category, tags, detailed description ✓ Reference images/logos via IPFS ✓ Link to market rules and dispute procedures ✓ Include creator credentials and verification status ✓ Enable rich metadata without on-chain storage costs ✓ Support dynamic metadata updates via new URI ## Files - MARKET_METADATA_URI_FEATURE.md: Complete feature specification (389 lines) - Comprehensive design rationale - Full API specification - Validation rules and error handling - Integration examples and test strategy - Migration path from v4 → v5 - Off-chain integration guide ## Testing Strategy Unit Tests: ✓ Valid URI formats (IPFS, Arweave, HTTP) ✓ Empty/None metadata_uri ✓ Boundary conditions (2047, 2048, 2049 chars) ✓ Event emission verification Integration Tests: ✓ Create market with metadata_uri ✓ Create market without metadata_uri ✓ Query and retrieve metadata_uri ✓ Event payload verification ## Implementation Roadmap Phase 1: Design (THIS COMMIT) - Feature specification and design review Phase 2: Implementation (NEXT) - Add metadata_uri field to Market struct - Implement validation and error handling - Update initialize_market() API - Add comprehensive test coverage - Update documentation and migration guide Phase 3: Deployment - Testnet validation and integration testing - Off-chain service updates - Mainnet deployment with migration procedure ## Breaking Changes⚠️ Storage version 5 is breaking: - Old v4 deployments cannot read v5 markets - Requires redeploy and reinitialize on existing deployments - All markets must be recreated with metadata_uri parameter ## Related Features Previous: feat/close-market-to-deposits (storage v3 → v4) Current: feat/market-metadata-uri (design phase, storage v5) ## Summary Comprehensive feature specification for optional market metadata URI field. Enables off-chain storage of rich market metadata while maintaining on-chain efficiency and flexibility. Full API, validation, testing, and migration strategy documented. Ready for implementation phase. Total: 389 lines of detailed specification
Adds optional metadata_uri field to Market struct, enabling markets to reference off-chain metadata stored on IPFS, Arweave, or HTTP endpoints. ## Implementation Details ### Core Changes - Market struct: Added pub metadata_uri: Option<String> field - Validation: New validate_metadata_uri() enforces non-empty, max 2048 chars - Error code: InvalidMetadataUri = 7 in Market Errors section - API: initialize_market() now accepts metadata_uri parameter - Event: MarketCreatedEvent includes metadata_uri field - Storage: Version bumped from 3 → 5 (breaking change) ### Validation Rules ✓ Optional field (None = no metadata) ✓ Non-empty if Some ✓ Maximum 2048 characters ✓ Supports IPFS (ipfs://), Arweave (ar://), HTTP endpoints ### State Persistence ✓ Market struct serialized to Soroban persistent ledger ✓ Storage version 5 ensures schema consistency ✓ Version assertion on all storage operations ✓ Old v3 deployments cannot read v5 markets ### Testing (7 unit tests) ✓ Valid IPFS URI: accepts ipfs:// format ✓ Valid Arweave URI: accepts ar:// format ✓ Valid HTTP URI: accepts https:// format ✓ No metadata: accepts None value ✓ Empty metadata: rejects with error code 7 ✓ Max length (2048): accepts boundary ✓ Too long (2049+): rejects with error code 7 ### Use Cases Enabled ✓ Store market category, tags, detailed description ✓ Reference images/logos via IPFS ✓ Link to market rules and dispute procedures ✓ Include creator credentials and verification status ✓ Enable dynamic metadata updates via new URI ### Files Modified - contracts/market/src/types.rs: Market struct with metadata_uri field - contracts/market/src/validation.rs: validate_metadata_uri() function - contracts/market/src/error.rs: InvalidMetadataUri error code - contracts/market/src/lib.rs: initialize_market() accepts metadata_uri - contracts/market/src/events.rs: MarketCreatedEvent includes field - contracts/market/src/storage.rs: Storage version 5 - contracts/market/src/test.rs: 7 comprehensive unit tests - MARKET_METADATA_URI_IMPLEMENTATION.md: Implementation summary (282 lines) ## Breaking Changes⚠️ Storage version 5 is breaking: - Old v3 deployments cannot read v5 markets - Requires redeploy and reinitialize - All markets must be recreated with metadata_uri parameter ## Migration Path (v3 → v5) 1. Build: stellar contract build 2. Deploy: New WASM to testnet/mainnet 3. Initialize: initialize(admin) sets STORAGE_VERSION = 5 4. Recreate: All markets must include metadata_uri parameter 5. Indexers: Update to read metadata_uri from MarketCreatedEvent ## Summary Complete implementation of optional market metadata URI field with: - Full API integration - Comprehensive validation - Proper state persistence - Event emission for off-chain tracking - 7 unit tests covering all scenarios - Detailed documentation Total: 522 lines added (code + tests + docs) Storage version: 5 Error code: 7 (InvalidMetadataUri) Test coverage: 7 unit tests
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #390
Design specification for optional metadata_uri field on Market struct. Enables markets to reference off-chain metadata stored on IPFS, Arweave, or HTTP endpoints.
Feature Overview
Adds optional metadata_uri: Option field to Market struct that:
Implementation Details
Type Change
API Changes
Validation
Storage
Off-Chain Integration
Use Cases
✓ Store market category, tags, detailed description ✓ Reference images/logos via IPFS
✓ Link to market rules and dispute procedures
✓ Include creator credentials and verification status ✓ Enable rich metadata without on-chain storage costs ✓ Support dynamic metadata updates via new URI
Files
Testing Strategy
Unit Tests:
✓ Valid URI formats (IPFS, Arweave, HTTP)
✓ Empty/None metadata_uri
✓ Boundary conditions (2047, 2048, 2049 chars)
✓ Event emission verification
Integration Tests:
✓ Create market with metadata_uri
✓ Create market without metadata_uri
✓ Query and retrieve metadata_uri
✓ Event payload verification
Implementation Roadmap
Phase 1: Design (THIS COMMIT)
Phase 2: Implementation (NEXT)
Phase 3: Deployment
Breaking Changes
Related Features
Previous: feat/close-market-to-deposits (storage v3 → v4)
Current: feat/market-metadata-uri (design phase, storage v5)
Summary
Comprehensive feature specification for optional market metadata URI field. Enables off-chain storage of rich market metadata while maintaining on-chain efficiency and flexibility. Full API, validation, testing, and migration strategy documented. Ready for implementation phase.
Total: 389 lines of detailed specification