# Complete, Revised Master Design Document (Version 2.10 - No Diagram, Plain Language Data Structures)

**Version:** 2.10
**Date:** October 27, 2023

## 1. Introduction

This document outlines the design for a distributed, shared art experience on Hedera Hashgraph. Users create and collect unique versions of digital art from layered components (traits). An app lets users explore layers and visualize combinations. A "mint wallet" program manages combination statuses. State is stored on Hedera using HCS. The app and mint wallet use a "mirror node." Users interact via their crypto wallet, proving ownership of an "Activation NFT." The User App uses WalletConnect. Art layers are stored as SVG data within HCS messages.

## 2. System Overview (Plain Language Summary)

This system lets users create and collect unique versions of digital art made of layered components called "traits." A user-friendly app allows users to browse these traits, combine them visually, and see what different combinations look like. A separate "mint wallet" program (running on a server) keeps track of which combinations are available, reserved, or have been turned into unique digital collectibles (NFTs).  All the information about available traits, combinations, and collection rules is stored on the Hedera Hashgraph network using a special messaging system called HCS.  Both the app and the mint wallet use a "mirror node" to quickly and easily read this information. Users interact with the system using their Hedera-compatible crypto wallet, and they need to own a special "Activation NFT" to participate.  The user's app never directly changes anything on the Hedera network.  Instead, it uses a secure connection (WalletConnect) to ask the user's wallet to send requests to the mint wallet. The actual images of the art traits are stored directly on the Hedera network as text (SVG format).

## 3. System Architecture

### 3.1. Components:

*   **User App:** Client-side application:
    *   Browse art layers (traits).
    *   Create/visualize combinations (max 24 traits).
    *   Connect to crypto wallet (via WalletConnect).
    *   *Verify Activation NFT ownership* (immediately after connecting).
    *   View combination statuses.
    *   Request actions (reserve, mint, unreserve, *potentially bid*) via WalletConnect.
*   **Mint Wallet:** Server-side application:
    *   Listens for transactions to its Hedera account.
    *   Validates requests and user authorization.
    *   *Maintains list of valid Activation NFT holders (and wallet IDs).*
    *   Manages combination statuses.
    *   Creates NFTs (using HTS).
    *   Updates HCS topics.
    *   *Generates assembled image for NFT metadata.*
    *   Handles IPFS interactions.
    *   *Creates and Manages Mutable Data Topic Snapshots*
*   **Hedera Hashgraph:**
    *   **HCS:** State management, communication, storing trait SVG.
    *   **HTS:** Creating/managing NFTs.
*   **IPFS:** Distributed file storage for NFT metadata.
*   **Mirror Node:** Read-only, queryable view of HCS data.
*   **User Wallet:** Hedera-compatible wallet.

### 3.2. Component Interactions:

*   User App connects to User Wallet via WalletConnect and *immediately verifies Activation NFT*.
*   User App uses Mirror Node to fetch system state.
*   User App, via WalletConnect, instructs User Wallet to send transactions to Mint Wallet (requests in memo).
*   Mint Wallet listens for transactions.
*   Mint Wallet uses Mirror Node to verify information *and checks its internal list*.
*   Mint Wallet interacts with Hedera (HCS, HTS) and IPFS.
*   Trait data (SVGs) are *directly within HCS messages as plain text*.

### 3.3. Data Flow:

1.  **Initialization:** User App starts. User connects wallet. *User App verifies Activation NFT by querying the Mirror Node for the user's account information and checking for the presence of the specific `activationNftId`*.
2.  **Data Fetch:** (If NFT is valid) User App fetches data (Collection Master, Trait Status, Combination Status).
3.  **Combination Creation:** User creates combination (max 24 traits).
4.  **Action Request:** User requests action.
5.  **Transaction:** User App constructs request. Uses WalletConnect; User Wallet signs transaction to Mint Wallet (request in memo).
6.  **Mint Wallet Processing:** Mint Wallet receives transaction.
7.  **Verification:** Mint Wallet verifies Activation NFT (Mirror Node *and internal list*), signature.
8.  **Validation:** Mint Wallet validates request, checks Combination Status (Mirror Node).
9.  **State Update:** Mint Wallet updates HCS topics. *After updating any HCS topic which may impact the list of valid Activation NFT holders, the Mint Wallet queries the Mirror Node to update its internal list.*
10. **NFT Minting (if applicable):** Mint Wallet creates NFT (via HTS), *creates the mutable data topic and posts the initial snapshot*, generates/stores image and metadata on IPFS, updates NFT with IPFS link to mutable topic. *For all subsequent updates to the NFT's mutable metadata, the Mint Wallet creates an immutable snapshot on IPFS, and posts the CID of that snapshot, along with a timestamp, to the mutable data topic.*
11. **Update Polling:** User App queries Mirror Node (every 10 seconds).

### 3.4. Technology Stack:

*   Hedera Hashgraph: HCS, HTS, Transactions
*   IPFS: File storage (self-hosted)
*   WalletConnect: Wallet interaction
*   Mirror Node: Data querying (*Specific provider TBD*)
*   User App: (Language/framework TBD - framework choice should prioritize ease of integration with Hedera SDK and WalletConnect).
*   Mint Wallet: (Language/framework TBD - framework choice should prioritize ease of integration with Hedera SDK).
*   Deployment: (TBD)

### 3.5 Security Overview

*   User authentication is handled by requiring an "Activation NFT".
*   WalletConnect is used for secure wallet interactions.
*   All requests to the mint wallet will be signed and verified.
*   The Mint Wallet will revoke access for wallets exhibiting malicious behavior by updating the Activation NFT's metadata.
*   Explicit Rate Limiting is recommended (details in Security Specification).

## 4. API Specification

### 4.1. User App - Wallet Interaction:

*   Uses WalletConnect.
*   **Initial Activation NFT Check:** *Immediately* after connection, verify: `GET /api/v1/accounts/{accountId}`. Check the `nfts` array in the response for an NFT with the `tokenId` matching the `activationNftId` from the Collection Master Topic.
*   Signing Requests: Requests User Wallet to sign transactions to Mint Wallet (data in memo).

### 4.2. User App - Mirror Node Interaction:

*   Queries: REST API calls.
*   Data Formats: JSON.
*   **Collection Master Query:** `GET /api/v1/topics/{CollectionMasterTopicID}/messages?order=desc&limit=1`
*   **Trait Status Query:** `GET /api/v1/topics/{TraitStatusTopicID}/messages?order=desc&limit=1`
*   **Combination Status Query:** `GET /api/v1/topics/{CombinationStatusTopicID}/messages?order=desc&limit=100&offset=0`
    `GET /api/v1/topics/{CombinationStatusTopicID}/messages?order=desc&limit=100&offset=100`. Offset-based pagination is used by default.
*   **Trait Data Query:** `GET /api/v1/topics/{traitDataPrefix + TraitTopicID}/messages/{MessageID}` Note: The `topicId` from the Trait Status Topic must be prepended with the `traitDataPrefix` from the Collection Master Topic.
*   **NFT Metadata History Query:** `/api/v1/nft/metadata/{mutableDataTopicId}/history` (Internal API - used by Mint Wallet).
*   Polling Interval: 10 seconds.

### 4.3. User App - Mint Wallet Interaction:

*   **Indirect Interaction Only:** Via transactions from User Wallet to Mint Wallet.
*   **Transaction Memo Format:** `[Combination Representation][Action Type]`
    *   Combination Representation: `GroupID``TraitID` (e.g., `01a02b03c`). `GroupID`: two digits (01-99). `TraitID`: one character (a-z, A-Z, 0-9). Max 24 traits. Maximum Length: 96 bytes.
    *   Action Type: `R` (Reserve), `M` (Mint), `U` (Unreserve), `B` (Bid - *If implemented*). Maximum Length: 1 byte.
*   **Response:** No direct response. Changes in HCS topic updates.

### 4.4. Mint Wallet - Mirror Node Interaction: (Similar to User App).

### 4.5. Mint Wallet - Hashgraph Interaction:

*   **HCS Operations:** `submitMessage` (Combination Status, Trait Status, Collection Master).
*   **HTS Operations:** `createToken`, `mintToken`, `updateToken`, `tokenAssociate`, `transferToken`.
*   **Transaction Listening:** Listens for transactions to its account.

### 4.6. Historical NFT Data API:

*   **Endpoint:** `/api/v1/nft/metadata/{mutableDataTopicId}/history` (Internal API)
*   **Request:** `GET /api/v1/nft/metadata/{mutableDataTopicId}/history`
*   **Response:** JSON array of historical metadata (timestamp, IPFS CID).

### 4.7. Error Handling:

*   Handles HTTP errors (Mirror Node).
*   Application-level errors reflected in Combination Status Topic.

#### 4.7.1 Example Error States: Values for `status` field in Combination Status updates.

    *   `combination_already_reserved`
    *   `combination_invalid`
    *   `activation_nft_invalid`
    *   `activation_nft_revoked`
    *   `insufficient_funds`
    *   `bid_too_low` (If bidding)

## 5. Data Model

### 5.1. Art Layer Structure:

*   **Base Image:** Foundational image.
*   **Trait Groups:** Categories (e.g., Hat). Max 99 groups.
*   **Traits:** Variations (e.g., Top Hat). Max 62 traits/group.
*   **Trait Representation:** `GroupID``TraitID` (e.g., `01a`).

### 5.2. Combination Representation: Concatenation (e.g., `01a02h03e`). Max 96 bytes.

### 5.3. Central Registry Topic Message Structure:

A single HCS message containing a JSON object:

*   `traitStatusTopic`: (String) HCS Topic ID for Trait Status.
*   `combinationStatusTopic`: (String) HCS Topic ID for Combination Status.
*   `mintWalletAccount`: (String) Account ID for Mint Wallet.
*   `collectionMasterTopic`: (String) HCS Topic ID for Collection Master.
*   `version`: (String) Version of the registry structure.

Each message is a complete update. Only the Mint Wallet can update this topic.

### 5.4. Trait Status Topic Message Structure:

A single HCS message containing a JSON array. Each element is a JSON object representing a trait:

*   `groupId`: (Integer) Two-digit group ID (01-99).
*   `traitId`: (String) Single character trait ID (a-z, A-Z, 0-9).
*   `topicId`: (String) HCS Topic ID where trait's SVG is stored.
*   `messageId`: (String) Message ID within `topicId` with SVG.
*   `name`: (String) Human-readable trait name.
*   `groupName`: (String) Human-readable trait group name.

Each message is a complete list. Only the Mint Wallet can update this topic.

### 5.5. Trait Data (HCS Message):

The message body contains the raw SVG data as a *plain text string*.

### 5.6. Combination Status Topic Message Structure:

A single HCS topic. Each message is a JSON object representing the status of all combinations. Keys are combination representations (e.g., "01a02b03c"). Values are JSON objects:

*   `status`: (String) "available," "reserved," "minted," or an error state.
*   `walletId`: (String) If `status` is "reserved". Hedera account ID.
*   `nftId`: (String) If `status` is "minted". Hedera NFT ID.
*   `mintTransactionId`: (String) If `status` is "minted". Hedera transaction ID.

Only the Mint Wallet can update this topic.

### 5.7. NFT Metadata Structure (Mutable, IPFS):

Stored as JSON on IPFS.

*   `name`: (String) NFT name.
*   `description`: (String) NFT description.
*   `image`: (String) IPFS link to assembled image (Mint Wallet generates).
*   `attributes`: (Array) Array of trait info objects. Each object has:
    *   `trait_type`: (String) Trait group name.
    *   `value`: (String) Trait name.
    *   `trait_group_id`: (String) Two-digit `GroupID`.
    *   `trait_id`: (String) Single-character `TraitID`.
    *   `trait_topic_id`: (String) HCS Topic ID for the trait SVG
    *   `trait_message_id`: (String) HCS Message ID for trait SVG
*   `mutableDataTopic`: (String) HCS Topic ID for metadata history.
*   `mintTransactionId`: (String) Hedera transaction ID.

### 5.8 Collection Master Topic Message Structure:

A single HCS message containing a JSON object:

*   `feeAmount`: (Long) Minting fee (tinybars).
*   `feeAccount`: (String) Hedera account for fees.
*   `reserveTimeLimit`: (Long) Reservation time limit (seconds).
*   `biddingEnabled`: (Boolean) `true` or `false`.
*   `activationNftId`: (String) Token ID of the Activation NFT.
*   `traitDataPrefix`: (String) Prefix added to trait data `topicId` values.
*   `name`: (String) Human readable name.
*   `description`: (String) Descriptive words.

Only the Mint Wallet can update this topic.

### 5.9. Historical NFT Data (HCS Topic):

Stored as HCS messages on the topic specified by `mutableDataTopic` in the NFT metadata. Each message contains a JSON object with:

*   `metadataCID`: The IPFS CID of the immutable metadata snapshot
*   `timestamp`: The timestamp of the snapshot.

## 6. Bidding System (Placeholder)

*This section will contain the complete specification for the bidding system, if it is included.*

## 7. Assumptions and Constraints

*   Reliable Mirror Node available.
*   Hedera network operational.
*   IPFS gateway used is reliable.
*   Max transaction memo length: 100 bytes.
*   Max traits in a combination: 24.
*   User's wallet supports WalletConnect and can sign Hedera transactions.
*   Mint Wallet Account has sufficient Hbar.
*   Mirror Node will not lag behind the main net by an unacceptable amount.
*   Initial topic and account setup is performed manually.