diff --git a/.config/dictionaries/project.dic b/.config/dictionaries/project.dic index 64a3b5ec5d4..000e86a5f59 100644 --- a/.config/dictionaries/project.dic +++ b/.config/dictionaries/project.dic @@ -15,6 +15,7 @@ Arbritrary ARCHS ARGB Arissara +Arweave asat asmjs asyncio @@ -102,6 +103,7 @@ Eternl EUTXO extn fetchval +Filecoin fmtchk fmtfix fontawesome @@ -133,6 +135,7 @@ Intellij interps inversed iohk +IPFS iphoneos iphonesimulator jdbc diff --git a/docs/src/architecture/08_concepts/domain-models/.pages b/docs/src/architecture/08_concepts/domain-models/.pages new file mode 100644 index 00000000000..c94663a64bc --- /dev/null +++ b/docs/src/architecture/08_concepts/domain-models/.pages @@ -0,0 +1,4 @@ +title: Domain Models +arrange: + - data-attributes.md + - roles_actors.md \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/domain-models/data-attributes.md b/docs/src/architecture/08_concepts/domain-models/data-attributes.md new file mode 100644 index 00000000000..7677c231c95 --- /dev/null +++ b/docs/src/architecture/08_concepts/domain-models/data-attributes.md @@ -0,0 +1,37 @@ +--- +icon: material/details +--- + +# Data Attributes + +## Data Sensitivity Types + +Data sensitivity types categorize data entities based on their content, context, and associated regulatory risks. +These classifications help identify and manage the inherent risks of handling data related to different data categories, ranging +from user-generated content to cryptographic keys and financial data. + +Each data sensitivity type is associated with varying levels of sensitivity and regulatory scrutiny, influenced by frameworks like +GDPR, CCPA, and other global data protection laws. +By organizing data into these types, we can assess our regulatory obligations, implement appropriate safeguards, and address +compliance considerations effectively. +These sensitivity levels are adaptable and can be expanded or refined based on our specific domain and specific regulatory +requirements. + +| Type | Short Description | Risk in Relation to Regulations | +| ---------------------------------- | ---------------------------------------- | ------------------------------------------------------------------- | +| User Content | Data created or shared by users | Moderate; subject to content regulations and copyright laws | +| User Metadata | Information about user activity | High; often falls under data protection laws like GDPR | +| User Activity Data | Behavioral data on platform interactions | High; subject to privacy regulations and data processing laws | +| Identifiable Data | Data directly identifying a user | Very High; core focus of most data protection regulations | +| S/PII | Highly sensitive personal information | Extremely High; strictly regulated under multiple laws | +| Business Data | Proprietary business information | Moderate; subject to trade secret and corporate governance laws | +| Pseudonymous Data | Data linked to aliases or pseudonyms | Moderate; may be subject to data protection laws if re-identifiable | +| Anonymous Data | Data not linkable to individuals | Low; generally less regulated but anonymization must be robust | +| Cryptographic Keys | Private keys for digital asset access | High; subject to financial regulations and cybersecurity laws | +| Transaction Metadata | Details about blockchain transactions | Moderate; may fall under financial regulations and AML laws | +| Decentralized Identity Information | Self-sovereign identity data | High; emerging area with evolving regulatory landscape | +| Tokenized Assets | Digital representations of ownership | High; subject to securities laws and financial regulations | +| Encrypted Communications | Private messages on platforms | Moderate; subject to encryption and data protection laws | +| Governance Data | Voting and proposal information in DAOs | Moderate; may fall under corporate governance regulations | +| Zero-Knowledge Proofs | Cryptographic validation data | Low to Moderate; emerging technology with evolving regulations | +| Finance Data | Financial activity data | Very High; subject to financial regulations | diff --git a/docs/src/architecture/08_concepts/domain-models/diagrams/entity_fund14.d2 b/docs/src/architecture/08_concepts/domain-models/diagrams/entity_fund14.d2 new file mode 100644 index 00000000000..55c09d7f486 --- /dev/null +++ b/docs/src/architecture/08_concepts/domain-models/diagrams/entity_fund14.d2 @@ -0,0 +1,410 @@ +vars: { + d2-config: { + layout-engine: elk + } +} + +classes: { + action: { + style: { + stroke-dash: 3 + fill: green + } + } + template: { + style: { + fill: blue + } + } +} + +RBACAccountRef: { + shape: class + +onchain_ref: ref +} + +Brand: { + shape: class + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +Campaign: { + shape: class + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +Category: { + shape: class + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +Proposal: { + shape: class + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +Comment: { + shape: class + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +Event: { + shape: class + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +Review: { + shape: class + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +Role: { + shape: class + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +Rule: { + shape: class + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +Space: { + shape: class + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +Vote: { + shape: class + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +BrandTemplate: { + shape: class + class: template + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +CampaignTemplate: { + shape: class + class: template + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +CategoryTemplate: { + shape: class + class: template + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +ProposalTemplate: { + shape: class + class: template + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +ProposalTemplateMetaSchema: { + shape: class + class: template + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +ReviewTemplate: { + shape: class + class: template + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +ProposalSubmission: { + shape: class + class: action + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +ProposalRetraction: { + shape: class + class: action + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +ProposalModerationBlock: { + shape: class + class: action + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +DocumentRetraction: { + shape: class + class: action + +id: ULID + +ver: ULID + +ref: ULID + +template: CBOR Array + +reply: CBOR Array + +section: CBOR String + +collabs: CBOR Array +} + +# Relationships +Brand -> BrandTemplate: { + label: "+has" + source-arrowhead: "0..*" + target-arrowhead: "1" +} + +CampaignTemplate -> Campaign: { + label: "+has" + source-arrowhead: "0..*" + target-arrowhead: "1" +} + +CategoryTemplate -> Category: { + label: "+has" + source-arrowhead: "0..*" + target-arrowhead: "1" +} + +ProposalTemplate -> Proposal: { + label: "+has" + source-arrowhead: "0..*" + target-arrowhead: "1" +} + +ReviewTemplate -> Review: { + label: "+has" + source-arrowhead: "0..*" + target-arrowhead: "1" +} + +ProposalTemplateMetaSchema -> ProposalTemplate: { + label: "+has" + source-arrowhead: "0..*" + target-arrowhead: "1" +} + +RBACAccountRef -> Proposal: { + label: "+owns and creates" + source-arrowhead: "1..*" + target-arrowhead: "0..*" +} + +RBACAccountRef -> Comment: { + label: "+owns and creates" + source-arrowhead: "1" + target-arrowhead: "0..*" +} + +RBACAccountRef -> Vote: { + label: "+owns and casts" + source-arrowhead: "1" + target-arrowhead: "0..*" +} + +RBACAccountRef -> Review: { + label: "+owns and creates" + source-arrowhead: "1" + target-arrowhead: "0..*" +} + +RBACAccountRef -> ProposalSubmission: { + label: "+owns and creates" + source-arrowhead: "1" + target-arrowhead: "0..*" +} + +RBACAccountRef -> ProposalRetraction: { + label: "+owns and creates" + source-arrowhead: "1" + target-arrowhead: "0..*" +} + +RBACAccountRef -- Role: { + label: "+has" + source-arrowhead: "1..*" + target-arrowhead: "1..*" +} + +Brand -- Campaign: { + label: "+has" + source-arrowhead: "1" + target-arrowhead: "1..*" +} + +Campaign -- Category: { + label: "+has" + source-arrowhead: "1" + target-arrowhead: "1..*" +} + +Campaign -- Event: { + label: "+has" + source-arrowhead: "1" + target-arrowhead: "1..*" +} + +Campaign -- Rule: { + label: "+has" + source-arrowhead: "1" + target-arrowhead: "0..*" +} + +Proposal -- Comment: { + label: "+has" + source-arrowhead: "1" + target-arrowhead: "0..*" +} + +Proposal -- Vote: { + label: "+has" + source-arrowhead: "1" + target-arrowhead: "0..*" +} + +Proposal -- Review: { + label: "+has" + source-arrowhead: "1" + target-arrowhead: "0..*" +} + +Proposal -- Space: { + label: "+has" + source-arrowhead: "1..*" + target-arrowhead: "0..*" +} + +Proposal -> ProposalSubmission: { + label: "+has" + source-arrowhead: "1" + target-arrowhead: "0..*" +} + +Proposal -> ProposalRetraction: { + label: "+has" + source-arrowhead: "1" + target-arrowhead: "0..*" +} + +Proposal -> ProposalModerationBlock: { + label: "+has" + source-arrowhead: "1" + target-arrowhead: "0..*" +} diff --git a/docs/src/architecture/08_concepts/domain-models/index.md b/docs/src/architecture/08_concepts/domain-models/index.md new file mode 100644 index 00000000000..fcf90c7f952 --- /dev/null +++ b/docs/src/architecture/08_concepts/domain-models/index.md @@ -0,0 +1,62 @@ +--- +## icon: material/view-module +--- + +# Entity Catalog + +| **Entity Name** | **Type** | **Brief Description** | **Details Link** | +| ----------- | ---- | ----------------- | ------------ | +| **Brand** | Instance | Represents an organization or initiative creating campaigns | [Brand Details](./instances/brand/) | +| **Brand Template** | Template | Defines the structure for Brand Parameters Documents | [Brand Template Details](./instances/brand_template/) | +| **Campaign** | Instance | A specific funding initiative within a brand | [Campaign Details](./instances/campaign/) | +| **Campaign Template** | Template | Defines the reusable structure for Campaign Parameters Documents | [Campaign Template Details](./instances/campaign_template/) | +| **Category** | Instance | A grouping for proposals within a campaign | [Category Details](./instances/category/) | +| **Category Template** | Template | Defines the structure for Category Parameters Documents | [Category Template Details](./instances/category_template/) | +| **Comment** | Instance | User feedback on a proposal | [Comment Details](./instances/comment/) | +| **Comment Template** | Template | Defines the reusable structure for Comment Documents | [Comment Template Details](./instances/comment_template/) | +| **Event** | Instance | A time-bound activity within a campaign | [Event Details](./instances/event/) | +| **Proposal** | Instance | A user-submitted application for funding | [Proposal Details](./instances/proposal/) | +| **Proposal Template** | Template | Defines the structure and required elements for proposals | [Proposal Template Details](./instances/proposal_template/) | +| **Proposal Template Meta Schema** | Template | Defines the structure and required elements for proposal templates | [Proposal Template Meta Schema Details](./instances/proposal_template_meta_schema/) | +| **Review** | Instance | An assessment of a proposal | [Review Details](./instances/review/) | +| **Review Template** | Template | Defines the structure and required elements for Review Documents | [Review Template Details](./instances/review_template/) | +| **Role** | Instance | Specific roles with conditions, rules governing allowed actions | [Role Details](./instances/role/) | +| **Rule** | Instance | Defines reusable operational conditions for participation | [Rule Details](./instances/rule/) | +| **Space** | Instance | Represents stages for proposals, e.g., Discovery Space | [Space Details](./instances/space/) | +| **Vote** | Instance | A user's decision on a proposal | [Vote Details](./instances/vote/) | +| **ProposalSubmission** | Action | Stores record of proposal submission action | [Actions Details](./instances/proposal_submission/) | +| **ProposalRetraction** | Action | Stores record of proposal retraction action | [Actions Details](./instances/proposal_retraction/) | +| **DocumentRetraction** (TBD) | Action | Generic retraction action on any document type if specifics are not required | [Actions Details](./instances/document_retraction/) | +| **ProposalModerationBlock** | Action | Stores record of an action taken by a moderator to block a proposal | [Actions Details](./instances/proposal_moderation_block/) | + +## **Categorization** + +* **Instance:** Core documents that represent primary entity instances within Catalyst. +* **Templates:** Define the structure and validation rules for corresponding entity instances. +* **Action:** Action functionalities such as moderation and retraction, managing interactions and data integrity. +* **Specification:** ToDo: proposal template meta defined by spec, rules could be spec + +## Metadata Headers for Entity Identification and References + +### Common metadata attributes + +| **Attribute** | **Required** | **Type** | **Category** | **Description** | **Constraints** | **Notes** | +| ------------- | ------------ | ------------------------ | ------------------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | +| `id` | Yes | UUID | Unprotected header | Unique identifier for the entity | Primary Key | Ensures global uniqueness for the entity. | +| `ver` | Yes | ULID | Unprotected header | Version ID for the Proposal | The initial ver assigned when published will be identical to the `id` | Enables versioning and traceability. | +| `alg` | Yes | String | Unprotected header | Indicates the cryptography algorithm used for the security processing | It must be equal to EdDSA value. | | +| `type` | Yes | ULID or CBOR Array | Unprotected header | Indicates the content type of the COSE payload | Define Media Types from IANA where possible [Reference](https://www.iana.org/assignments/media-types/media-types.xhtml) | | +| `encoding` | Yes | ULID or CBOR Array | Unprotected header | Indicate the content encoding algorithm of the payload | Current supported encoding algorithms: br - Brotli compressed data. | | +| `kid` | Yes | UTF-8 encoded URI string | Protected header | A unique identifier of the signer. | Each Catalyst Signed Document COSE signature must include the following protected header field | | +| `ref` | Optional | ULID or CBOR Array | Reference | References related entities | Linked Record Constraint | `[, ]` format for version linking. | +| `ref_hash` | Optional | ULID or CBOR Array | Security | This is a cryptographically secured reference to another document. | Cryptographically secured Linked Record Constraint | Hash of the referenced document CBOR bytes | +| `template` | Yes | ULID or CBOR Array | Reference | Template guiding the entity structure | Must reference an existing Template entity | `[, ]` ensures traceable references. | +| `reply` | Optional | CBOR Array | Reference | Identifies the entity this is replying to | Optional; `[, ]` format | Typically used for comments or discussions. | +| `section` | Optional | JSON Path | Reference | Links to a specific section of a document | Must comply with valid JSON Path syntax | Useful for granular referencing within payloads. | +| `collabs` | Optional | CBOR Array | Security | Authorized collaborators for the entity | Must be valid collaborator address | Ensures multi party editing is traceable. | + +## Entity Relationship (Work In Progress) + +```d2 +{{ include_file('src/architecture/08_concepts/domain-models/diagrams/entity_fund14.d2') }} +``` diff --git a/docs/src/architecture/08_concepts/domain-models/instances/.pages b/docs/src/architecture/08_concepts/domain-models/instances/.pages new file mode 100644 index 00000000000..0e9790a00af --- /dev/null +++ b/docs/src/architecture/08_concepts/domain-models/instances/.pages @@ -0,0 +1,3 @@ +title: Model Instances +arrange: + - proposal.md \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/domain-models/instances/proposal.md b/docs/src/architecture/08_concepts/domain-models/instances/proposal.md new file mode 100644 index 00000000000..d9158b736c5 --- /dev/null +++ b/docs/src/architecture/08_concepts/domain-models/instances/proposal.md @@ -0,0 +1,384 @@ +--- +icon: material/label +--- + +# **Entity Identity Card** + +--- + +## **Proposal** + +--- + +### **Entity Name & Purpose** + +| **Aspect** | **Description** | +| ---------------- | -------------------------------------------------------------------------------------------------------------------------- | +| **Name** | Proposal | +| **Purpose/Role** | Represents a user-submitted funding proposal containing responses to predefined questions outlined in the proposal schema. | +| **Scope** | User generated and owned data. Owner is required to make the data public in order to participate in a fund | + +--- + +### **Ownership & Control** + +| **Aspect** | **Decision** | **Guidance/Notes** | +| ---------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Data Owner** | User | Users own their Proposal data and retain control over its content | +| **Controller** | User | Users control the cryptographic keys required for Proposal updates, encryption, and access, users must make the data publicly accessible in order to participate in a fund. | +| **Permissions** | Consent Based | Users must explicitly publish their Proposals to make them accessible; drafts remain private unless explicitly shared. | +| **Storage Controller** | User-Determined | Users determine the storage provider. Storage provider must be publicly accessible at all times. | + +--- + +### **Schema & Lifecycle** + +| **Aspect** | **Decision** | **Guidance/Notes** | +| --------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| **Schema Stability** | Fixed per Fund Round | Proposal schema is fixed per funding round, ensuring fairness across all proposal submissions. | +| **Versioning** | Linked Records | Updates to Proposals create new records linked to previous versions, preserving historical integrity. | +| **Version History** | Indefinite | All historical versions remain accessible for transparency and traceability. | +| **Lifecycle Stages** | Draft → Published → Archived | Drafts are private, published Proposals are accessible for evaluation, and archived Proposals remain available for reference. | +| **Validation Rules** | Strict | Validation is enforced via the ProposalSchema, ensuring compliance with predefined question sets and data types. | +| **Required Fields** | Yes | All required fields, as defined by the ProposalSchema, must be completed for a valid submission. | +| **Expected Lifespan** | Long-lived | Proposals exist until the funding round is completed, with archival for historical reference. | +| **Archival Needs** | Indefinite | Archived Proposals remain accessible indefinitely for accountability and future reference. | + +--- + +### **Visibility & Storage** + +| **Aspect** | **Decision** | **Guidance/Notes** | +| ---------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Public vs Private** | Hybrid | Drafts are private, and published Proposals become public on submission, drafts can be made public but then can no longer transition to private. | +| **Storage Location** | User-Determined | Users store Proposals on decentralized storage solutions (e.g., IPFS/Filecoin). For fund 14 Catalyst will provide a storage mechanism for proposal storage | +| **Public Persistence** | Catalyst (Time boxed) | Proposals are made persistent on IPFS or similar decentralized storage systems for long-term availability. For fund 14 Catalyst will provide a storage mechanism for proposal storage | +| **Data Impermanence** | User and dApp share responsibility | Users are responsible for re-pinning data or updating references if storage nodes fail, the dApp should handle unavailable data gracefully. There must be a way to log this type of issue when it happens | + +--- + +### **Access & Security** + +| **Aspect** | **Decision** | **Guidance/Notes** | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| **Encryption** | Optional | Users can choose to encrypt their drafts. Final submissions must remain unencrypted to allow public evaluation. | +| **Encryption Key Owner** | User | Users hold the cryptographic keys for Proposal encryption and access when in draft state. | +| **Consent Rules** | Time-bound | Users must publish their Proposals by the submission deadline to grant access; drafts remain private unless explicitly shared. | +| **Traceability** | Historical Linked Records | Immutable records of all changes are maintained for accountability and transparency. | + +--- + +### **Integration & Rules Enforcement** + +| **Aspect** | **Decision** | **Guidance/Notes** | +| -------------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| **Mandatory Participation Conditions** | Must be public by submission deadline, All mandatory questions must be complete as defined by the schema | Users must publish their Proposals before the deadline to participate in funding rounds. No late submissions will be accepted | +| **Non-Compliance Consequences** | Disqualified from current fund | Proposals not submitted by the deadline or non-compliant with ProposalSchema rules are ignored. | +| **Validation Mechanism** | dApp Enforcement | Proposals are validated against the ProposalSchema and compliance with rules validated by moderators | + +--- + +### **Relationships** + +| **Source Entity** | **Target Entity** | **Relationship Type** | **Cardinality** (Source → Target) | **Cardinality** (Target → Source) | **Description** | +| ----------------- | ----------------- | --------------------- | --------------------------------- | --------------------------------- | -------------------------------------------------------------------------------- | +| Proposal | ProposalSchema | Depends On | 1..1 | 0..* | Each proposal requires one schema. A schema can be used by many proposals. | +| Proposal | Fund | Depends On | 1..1 | 0..* | Each proposal is associated with one fund. A fund can support many proposals. | +| Proposal | Category | Depends On | 1..1 | 0..* | Each proposal belongs to one category. A category can group many proposals. | +| Proposal | Comment | Is Depended By | 0..* | 1..1 | A proposal can have zero or many comments. Each comment is tied to one proposal. | +| Proposal | Vote | Is Depended By | 0..* | 1..1 | A proposal can have zero or many votes. Each vote is tied to one proposal. | + +--- + +### **Regulatory & Compliance Considerations** + +| **Aspect** | **Decision** | **Guidance/Notes** | +| ---------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Data Liability** | User | Users are responsible for ensuring compliance with applicable regulations. Proposal data is referenced by Catalyst, for Fund 14 Catalyst will store the proposals but the long term intention is this is the Owners responsibility | +| **Regulatory Impacts** | Minimal Data Enforced | Only necessary data is collected, minimizing regulatory exposure. | +| **Data Removal** | Append-Only | Data cannot be deleted but can be superseded with updated records to maintain integrity. | + +--- + +### **Financial Considerations** + +| **Aspect** | **Decision** | **Guidance/Notes** | +| ----------------------- | --------------- | ------------------------------------------------------------------------------------------------ | +| **Cost Bearer** | User | Users pay for storage services like IPFS pinning. | +| **Cost Bearer Fund 14** | Catalyst | Catalyst will store the data for fund 14 | +| **Third-Party Storage** | No / Yes | This is not an option for fund 14 but will be in the future so must be considered | +| **Funding Method** | Catalyst / User | Catalyst will fund storage for fund 14, following this it may be the responsibility of the Owner | + +--- + +### **Security and Privacy Handling** + +| **Aspect** | **Description** | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| **Sensitive Data** | Proposals may include personal data or the proposer or confidential business information. | +| **Privacy Measures** | Drafts can be encrypted; public submissions are open and unencrypted. | +| **Risk Mitigation** | Clear user guidelines for key management, data storage responsibilities, and optional encryption should be communicated with proposers. | + +--- + +### **Languages and Localization** + +|**Aspect**|**Description**| +|---|---| +|**Supported Languages**|English, with localization capabilities for additional languages as needed.| +|**Localization Needs**|Users may provide localized content for Proposals; UI localization is supported where feasible.| + +--- + +### **Licensing and Reuse** + +* Proposals are user-owned; currently no conditions for licensing are set by Catalyst, it is the responsibility of the proposer to + ensure they comply with applicable Trademark and Copyright laws. + +--- + +### **Metadata Attributes** + +Metadata Attributes are defined in the header of each document, common metadata attributes can appear on every document, + entity metadata attributes are those which have a specific meaning to the current entity. +While they can share a common name across entities their purpose may differ from entity to entity. + +#### Common metadata attributes + +| **Attribute** | **Required** | **Type** | **Category** | **Description** | **Constraints** | **Notes** | +| ------------- | ------------ | ------------------------ | ------------------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | +| `id` | Yes | UUID | Unprotected header | Unique identifier for the entity | Primary Key | Ensures global uniqueness for the entity. | +| `ver` | Yes | ULID | Unprotected header | Version ID for the Proposal | The initial ver assigned when published will be identical to the `id` | Enables versioning and traceability. | +| `alg` | Yes | String | Unprotected header | Indicates the cryptography algorithm used for the security processing | It must be equal to EdDSA value. | | +| `type` | Yes | ULID or CBOR Array | Unprotected header | Indicates the content type of the COSE payload | Define Media Types from IANA where possible [Reference](https://www.iana.org/assignments/media-types/media-types.xhtml) | | +| `encoding` | Yes | ULID or CBOR Array | Unprotected header | Indicate the content encoding algorithm of the payload | Current supported encoding algorithms: br - Brotli compressed data. | | +| `kid` | Yes | UTF-8 encoded URI string | Protected header | A unique identifier of the signer. | Each Catalyst Signed Document COSE signature must include the following protected header field | | +| `ref` | Optional | ULID or CBOR Array | Reference | References related entities | Linked Record Constraint | `[, ]` format for version linking. | +| `ref_hash` | Optional | ULID or CBOR Array | Security | This is a cryptographically secured reference to another document. | Cryptographically secured Linked Record Constraint | Hash of the referenced document CBOR bytes | +| `template` | Yes | ULID or CBOR Array | Reference | Template guiding the entity structure | Must reference an existing Template entity | `[, ]` ensures traceable references. | +| `reply` | Optional | CBOR Array | Reference | Identifies the entity this is replying to | Optional; `[, ]` format | Typically used for comments or discussions. | +| `section` | Optional | JSON Path | Reference | Links to a specific section of a document | Must comply with valid JSON Path syntax | Useful for granular referencing within payloads. | +| `collabs` | Optional | CBOR Array | Security | Authorized collaborators for the entity | Must be valid collaborator address | Ensures multi party editing is traceable. | + +#### Entity metadata attributes + +| **Attribute** | **Type** | **Category** | **Description** | **Constraints** | **Notes** | +| ------------- | -------- | ----------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------- | +| `campaign_id` | UUID | Additional Fields | Unique identifier of the category the proposal has been published to | Existing UUID of category, category `brand_id` MUST be the same as the proposal `brand_id` | Ensures each proposal is only published to one category | +| `brand_id` | UUID | Additional Fields | Unique identifier of the brand under which the proposal has been submitted | Existing UUID of brand | Used for quick lookups on indexes | + +--- + +### **Attributes** + +Entity specific attributes that will appear in the document body. + +| **Attribute** | **Type** | **Required** | **Description** | **Constraints** | **Notes** | +| ---------------- | -------- | ------------ | ----------------------------- | --------------------------------------- | ------------------------------------- | +| `title` | String | Yes | Display name for the proposal | Max Length: 255 | Shown in interfaces for user context. | +| `description` | String | Optional | Summary of the proposal | Optional, Max Length: 1000 | Displayed as UI/UX content. | +| `requestedFunds` | Yes | Presentation | Requested amount in ADA | Between: 15,000-2,000,000 ADA inclusive | | +| `duration` | Yes | Presentation | Project duration in months | Between 2 and 12 inclusive | | + +--- + +### **Actions** + +This section defines the actions that can be performed on the entity, the entities that can perform the action and any + constraints placed on the action + +| **Operation** | **Action owner** | **Inputs** | **Constraints** | **Expected Output** | **Output Owner** | **Additional Notes** | +| ----------------------- | ------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| **Create** | Proposer (owner) | Register proposer | Proposer must have registered with Catalyst | New proposal document created and assigned a unique ID. (Proposal Document) | Proposal creator now `Owner` | Proposal ownership is initially assigned to the creator; metadata includes creation timestamp. | +| **Proposal Submission** | Proposal owner or collaborator | Proposal ID | Proposal must be complete and pass validation | Proposal becomes visible and active (Proposal Publish Action Document) | Proposal Owner | Transition from draft to public; ensures proposal adheres to all formatting and content guidelines. | +| **Retract** | Proposal owner or collaborator | Proposal ID, reason for retraction | Restricted to owner; may not retract proposals in active voting or funding phases | Proposal is marked as retracted; becomes inactive (Proposal Retraction Action Document) | Proposal Owner | Retracted proposals remain in the system for record keeping but are excluded from future processes. | +| **Comment** | User with role 0 key | Proposal ID, comment text | User must have commenting permissions; content must adhere to community guidelines | Comment linked to the proposal (Comment Document) | Comment creator | Comments are public documents tied to the proposal; responsibility for the lifecycle remains with the commenter. | +| **Vote** | Users who have registered for voting | Proposal ID, vote type (Yes, No, Abstain) | User must belong to an eligible voter group; voting period must be active | (Vote Document) | Voter | Voting results are tied to the proposal; individual votes remain private unless explicitly disclosed. | +| **Review** | Assigned reviewers | Proposal ID, review feedback | User must be assigned as a reviewer; review criteria must be satisfied | Proposal enters reviewed state with feedback (Review Document) | Reviewer | Review documents are tied to the proposal but owned by the reviewer, who is responsible for feedback accuracy. | +| **Approve** | Assigned reviewers | Proposal ID, approval decision | Restricted to authorized reviewers; approval may require a consensus | Proposal is approved and progresses to the next phase (Approved Action Document) | Moderator / Catalyst | | +| **Reject** | Assigned reviewers | Proposal ID, rejection reason | Restricted to authorized reviewers; rejection reason must be provided | Proposal is rejected (Rejected Action Document) | Moderator / Catalyst | Rejected proposals may be revised and resubmitted depending on system fund policies. | +| **Fund** | Funding authority | Proposal ID, funding amount | Proposal must have met all criteria for funding; funding pool must have sufficient balance | Proposal is marked as funded; funds are allocated (Funded Action Document) | Moderator / Catalyst | | +| **Add Collaborator** | Proposal owner | Proposal ID, collaborator ID | Collaborator must have an active account and accept the invitation | Collaborator gains access to the proposal and may contribute (Collaborator Action Document) | Proposal Owner | Added collaborators inherit specific permissions tied to their role in the proposal. | +| **Remove Collaborator** | Proposal owner | Proposal ID, collaborator ID | Collaborator must already be associated with the proposal | Collaborator's access is revoked (Collaborator Revocation Action Document) | Proposal Owner | Removed collaborators can no longer perform actions on the proposal document | + +--- + +### **Workflow** + +1. **Idea Stage** + * Content is private and informal. +2. **Private Draft** + * Fully editable. + * Possible actions: + * Request feedback → Moves to **Published Draft**. + * Submit for review → Moves to **Submitted Proposal**. +3. **Published Draft** + * Proposal is shared publicly for feedback. + * Visible to all users in the Discovery Space. + * Fully editable by authors. + * Possible actions: + * Retract draft → Publish a retraction document. + * Submit for voting → Moves to **Submitted Proposal**. +4. **Submitted Proposal** + * Proposal is finalized and submitted for review. + * Locked for edits. + * Visible to all users. + * Possible actions: + * Retract proposal → Publish a retraction document. + * Possible outcomes: + * **Accepted**: Moves to voting stage. +5. **Voting Stage** + * Accepted proposals are presented for voting. + * Locked and visible to voters. + +```mermaid +graph TD + A[Idea Stage] --> B[Private Draft] + B -->|Request Feedback| C[Published Draft] + B -->|Submit for Review| D[Submitted Proposal] + C -->|Retract Draft| I[Retraction Document Published] + C -->|Submit for Voting| D + D -->|Retract Proposal| J[Retraction Document Published] + D -->|Accepted| E[Voting Stage] + +``` + +--- + +### **Error Handling** + +#### **Submission Errors** + +* **Issue**: Users submit incomplete or invalid Proposals that do not conform to the Proposal Schema. +* **Detection**: + * Validation is performed locally in the Catalyst interface against the Proposal Schema. +* **Handling**: + * Notify users immediately of validation failures with descriptive error messages, e.g., "Field X is missing" or + "Invalid format for Field Y." + * Provide actionable suggestions or links to guidelines. + +#### **Storage Errors** + +* **Issue**: Data becomes inaccessible due to node failure or unpinned content or api issues +* **Detection**: + * Validate the data is accessible on the Catalyst interface. +* **Handling**: + * Notify users of inaccessible data with recommendations. + +#### **Versioning Conflicts** + +* **Issue**: Users inadvertently create conflicting versions of the same Proposal by submitting multiple updates simultaneously. +* **Detection**: + * Conflicts should be detected during submission by comparing version ULID +* **Handling**: + * Notify users of conflicts and provide options to resolve them: + * "Retain most recent version." + * "Merge changes manually." + * "Discard specific updates." + * Implement automatic conflict resolution rules, such as prioritizing updates with the latest timestamp. + +#### **Access / Retrieval Errors** + +* **Issue**: Users or reviewers encounter access issues due to incorrect permissions or expired links. +* **Detection**: + * Catalyst interface should detect access errors as they occur. +* **Handling**: + * Notify users of permission issues with clear instructions on how to proceed. + * Log the issue for operational and audit purposes. + +#### **User-Generated Errors** + +* **Issue**: Users make mistakes such as incorrect data entries or submission of incomplete drafts. +* **Detection**: + * Front end validation catches errors before data is submitted +* **Handling**: + * Auto-save drafts locally with periodic prompts to review and finalize. + +--- + +### **Key Risks and Mitigation Strategies** + +#### **Risk 1: User Loses Encryption Keys** + +* **Issue**: If a user encrypts their Proposal and loses their private key, the Proposal becomes inaccessible. +* **Impact**: + * **Proposal Inaccessibility**: The Proposal cannot be decrypted, effectively rendering it unusable for evaluation or funding. + * **Dependency Impact**: Comments or other entities referencing the Proposal can not reference private drafts and therefore will + have no impact on their context and relevance. +* **Mitigation**: + * **Key Backup**: + * Encourage users to store backup keys securely using a trusted wallet or key management service. + * **Transparent Submission**: + * Enforce public non encrypted final submissions to ensure Proposals are accessible to evaluators. +* **Result**: Reduces total data loss risk while preserving decentralized ownership principles. + +#### **Risk 2: Entity Disappears (Data Loss)** + +* **Issue**: A Proposal stored on decentralized storage becomes permanently inaccessible (e.g., due to node failures or + insufficient pinning). +* **Impact**: + * **Proposal Loss**: Funding decisions cannot be made if Proposals are lost. + * **Dependency Impact**: Comments, reviews, and votes lose their reference, creating orphaned records. +* **Mitigation**: + * **Redundant Storage**: + * Encourage users to pin their Proposal on multiple nodes . + * **Backup References**: + * Maintain metadata logs with Proposal content hashes and alternative storage for recovery. +* **Result**: Minimizes the impact of missing data and ensures continuity for dependent entities. + +#### **Risk 3: User Fails to Pay Storage Costs** + +* **Issue**: If users fail to pay for storage, their Proposal may be deleted or become inaccessible. +* **Impact**: + * **Proposal Inaccessibility**: Without storage, Proposals cannot be evaluated or referenced. + * **Dependency Impact**: Comments and votes referencing the Proposal lose their association. +* **Mitigation**: + * **Cost Transparency**: + * Provide users with clear estimates of storage costs during Proposal creation. + * **User Notifications**: + * Notify users of impending storage expiry and issues. + * **Default Migration**: + * Automatically migrate unpaid Proposals to a shared storage archive with time boxed removal if storage remains unpaid. +* **Result**: Ensures Proposals remain available while balancing user responsibility for cost of ownership. + +#### **Risk 4: Regulatory Non-Compliance** + +* **Issue**: Proposals contain data violating GDPR, CCPA, or other laws or regulations. +* **Impact**: + * **Penalties**: The data owner may face fines or restrictions due to non-compliance with regulations. + * **Operational Risks**: Catalyst risks operational disruptions and loss of trust. +* **Mitigation**: + * **Minimal Data Collection**: + * Restrict Proposals to predefined questions, ensuring compliance with data minimization principles. + * Ensure that any data with a Sensitivity Type defined is owned, stored and controlled by the user. + * **Encryption Options**: + * Allow users to encrypt sensitive data to comply with privacy regulations. + * **Retention and Removal**: + * Implement automated archival processes for expired or retracted Proposals to reduce regulatory exposure. +* **Result**: Ensures that Catalyst remains compliant with global data privacy regulations. + +#### **Risk 5: Non Compliance with Catalyst Rules** + +* **Issue**: Users fail to adhere to Catalyst defined rules (e.g., not publishing their Proposal by the deadline). +* **Impact**: + * **Disqualification**: Non compliant Proposals are excluded from funding consideration. +* **Mitigation**: + * **Early Notifications**: + * Provide users with real time progress tracking and reminders about submission deadlines. + * **Education and Support**: + * Include clear documentation to guide users through the application process. +* **Result**: Encourages compliance while reducing friction in user interactions. + +--- + +## Open Issues + +* N/A + +--- + +### **Iteration Change Log** + +| **Version** | **Date** | **Description of Change** | **Author** | +| ----------- | ---------- | ----------------------------------------------- | -------------- | +| v1.0 | 2024-12-20 | Initial creation of the Proposal Identity Card. | Neil | diff --git a/docs/src/architecture/08_concepts/domain-models/roles_actors.md b/docs/src/architecture/08_concepts/domain-models/roles_actors.md new file mode 100644 index 00000000000..5bfcb8d49b2 --- /dev/null +++ b/docs/src/architecture/08_concepts/domain-models/roles_actors.md @@ -0,0 +1,27 @@ +--- +icon: material/account +--- +# Roles/Actors + +The system defines several roles/actors that interact with entities to achieve various operational goals. +These roles include users and administrative entities that manage, review, or vote on proposals and campaigns. + +| **Role/Actor** | **Description** | **Responsibilities** | +| --------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| **Admin** | Campaign manager responsible for proposal oversight. | Configure campaigns, assign reviewers, moderate content. | +| **Delegator** | Assigns voting power to other users | Has the ability to assign voting power to another role | +| **Moderator** | Oversees moderation tasks within the system. | Classify and address flagged comments or proposals, ensure system integrity. | +| **Proposer** | User who creates and submits proposals. | Draft proposals, respond to campaign questions, manage proposal life cycles. | +| **Reviewer** | Assesses and provides feedback on proposals. | Review proposals, submit ratings, offer detailed feedback. | +| **Role Zero** | Base role for any user who registers with catalyst. | Base features, request additional roles, comment on proposals. | +| Super Admin | `Out of scope?` Oversees system-wide settings, brand, and role management. | Manage the brand, global roles, ensure operational compliance, configure system settings. | +| Tally Committee | `Out of scope?` Group responsible for managing the vote tallying process. | Oversee and ensure accurate tallying for campaigns or events. | +| **Vote Tally** | Automates vote verification and result calculations. | Verify votes, calculate outcomes, generate reports. | +| **Voter** | User who votes on proposals and delegates voting power. | Cast votes, delegate voting power, view voting results. | + +> ❓ Info +> +> * Is the role that can comment on proposals the same as the reviewer or can anyone with role zero comment? +> * Does a reviewer get additional responsibilities and if so do we need separate roles for each type of reviewer +> or can we just have a single role with varying abilities based on reputation or other measure as discussed ? +> \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/domain-models/templates/.pages b/docs/src/architecture/08_concepts/domain-models/templates/.pages new file mode 100644 index 00000000000..e8b6f5aee94 --- /dev/null +++ b/docs/src/architecture/08_concepts/domain-models/templates/.pages @@ -0,0 +1,3 @@ +title: Guidance +arrange: + - guidance_entity_id_card.md \ No newline at end of file diff --git a/docs/src/architecture/08_concepts/domain-models/templates/guidance_entity_id_card.md b/docs/src/architecture/08_concepts/domain-models/templates/guidance_entity_id_card.md new file mode 100644 index 00000000000..1d1fbda3222 --- /dev/null +++ b/docs/src/architecture/08_concepts/domain-models/templates/guidance_entity_id_card.md @@ -0,0 +1,256 @@ +--- +## icon: material/pencil-ruler +--- + +# **Entity Identity Card** + +--- + +## **Sample with guidance** + +--- + +### **Entity Name & Purpose** + +| **Aspect** | **Description** | +| ------ | ----------- | +| **Name** | *Name of the entity (e.g., Proposal, Fund, Comment)* | +| **Purpose/Role** | *Brief description of what this entity represents and its role in the system.* | +| **Scope** | *Define if this entity is user-generated/owned, dApp (catalyst) owned, or system-controlled.* | + +--- + +### **Ownership & Control** + +| **Aspect** | **Decision** | **Guidance/Notes** | +| ------ | -------- | -------------- | +| **Data Owner** | User / dApp | *(Who owns the data? Specify if it's user-generated or operational data owned by the dApp.)* | +| **Controller** | User / dApp / Shared | *(Who controls updates and access? Examples: who controls the cryptographic keys if applicable, potential for multi party control. )* | +| **Permissions** | Consent Based / Implicit | *(Is access explicitly granted by the owner, or implicitly set by system rules?)* | +| **Storage Controller** | User / dApp / Third-Party | *(Who is responsible for storing the data?)* | + +--- + +### **Schema & Lifecycle** + +| **Aspect** | **Decision** | **Guidance/Notes** | +| ------ | -------- | -------------- | +| **Schema Stability** | Fixed / Flexible | *(Is the schema immutable or flexible? If flexible, what governance process governs schema changes and does the dApp define these processes?)* | +| **Versioning** | Linked Records / Overwrite | *(Define if updates create new versions or overwrite existing data. Note: All data stored in public distributed platforms must specify `Linked Records`)* | +| **Version History** | Time-bound / Indefinite | *(Define the rules governing responsibility for the lifecycle of historical versions.)* | +| **Lifecycle Stages** | Draft → Published → Archived | *(Define the entity's progression through different states. Reference external state, sequence and flow diagrams that are relevant.)* | +| **Validation Rules** | Strict / Flexible | *(Are data inputs strictly validated and how are validation rules enforced? Examples: Schema adherence, constraints.)* | +| **Required Fields** | Yes / No | *(Is there a minimum set of fields required for the entity's validity are the detailed in the schema?)* | +| **Expected Lifespan** | Short-lived / Long-lived / Indefinite | *(Expected lifespan of this entity.)* | +| **Archival Needs** | Indefinite / Conditional / None | *(Is archival required post-lifecycle completion? Justify reasoning as there are ownership and cost implications depending on the choice)* | + +--- + +### **Visibility & Storage** + +| **Aspect** | **Decision** | **Guidance/Notes** | +| ------ | -------- | -------------- | +| **Public vs Private** | Public / Private / Hybrid | *(Define access levels throughout lifecycle, e.g., drafts private, submissions public.)* | +| **Storage Location** | User-Determined / Enforced / dApp provided | *(Where is the data stored? Examples: IPFS, Arweave, Filecoin, centralized backend, local disk)* | +| **Public Persistence** | IPFS, Filecoin, or Other | *(Mechanisms ensuring availability, such as decentralized storage redundancy.)* | +| **Data Impermanence** | Handled Gracefully | *(What happens if storage nodes fail? User responsibilities for re-pinning or redundancy.)* | + +--- + +### **Access & Security** + +| **Aspect** | **Decision** | **Guidance/Notes** | +| ------ | -------- | -------------- | +| **Encryption** | Default On / Optional | *(Is encryption required for drafts or optional for published data?)* | +| **Encryption Key Owner** | User / dApp / Shared | *(Who controls the keys required for encryption? Align with section Ownership & Control:Controller)* | +| **Consent Rules** | Time-bound / Conditional | *(Define explicit conditions under which access is granted, revoked, or expired by the owner. Note: unless the data is encrypted it is not possible to withdraw consent from public documents)* | +| **Traceability** | Historical Linked Records / None | *(Is there an immutable audit trail of changes? Helps ensure trust and accountability.)* | + +--- + +### **Integration & Rules Enforcement** + +| **Aspect** | **Decision** | **Guidance/Notes** | +| ------ | -------- | -------------- | +| **Mandatory Participation Conditions** | dApp Enforced / User Choice | *(Rules for submission, access, or interactions, e.g., deadlines or visibility requirements.)* | +| **Non-Compliance Consequences** | Ignored / Flagged | *(Entity impact for dapp rule violations, e.g., Blocked / Flagged / Moderated etc.)* | +| **Validation Mechanism** | Community Moderation / dApp Enforcement / Smart Contract Logic | *(How rules are enforced through available methods.)* | + +--- + +### **Relationships** + +Note: The following table is for illustration purposes only, the content of the relationship table will be determined by the entity +and its use case. + +| **Source Entity** | **Target Entity** | **Relationship Type** | **Cardinality** (Source → Target) | **Cardinality** (Target → Source) | **Description** | +| ----------------- | ----------------- | --------------------- | --------------------------------- | --------------------------------- | -------------------------------------------------------------------------------- | +| Proposal | ProposalSchema | Depends On | 1..1 | 0..* | Each proposal requires one schema. A schema can be used by many proposals. | +| Proposal | Fund | Depends On | 1..1 | 0..* | Each proposal is associated with one fund. A fund can support many proposals. | + +--- + +### **Regulatory & Compliance Considerations** + +| **Aspect** | **Decision** | **Guidance/Notes** | +| ------ | -------- | -------------- | +| **Data Liability** | User / Shared / dApp | *(Who bears compliance responsibility under regulations like GDPR/CCPA?)* | +| **Regulatory Impacts** | Minimal Data Enforced | *(Ensure alignment with regulations via minimal data collection and clear user consent.)* | +| **Data Removal** | Append-Only / Superseded | *(Define mechanisms for marking data obsolete or superseded in immutable systems.)* | + +--- + +### **Financial Considerations** + +| **Aspect** | **Decision** | **Guidance/Notes** | +| ------ | -------- | -------------- | +| **Cost Bearer** | Who is responsible for paying storage costs for this entity’s data? | *(Who pays for storage, e.g., IPFS pinning costs?) Include details if shared.* | +| **Third-Party Storage** | Yes / No | *(Can a third party store and maintain the entity if they wish? )(Yes / No)* | +| **Funding Method** | Wallet / Transaction Fees / Community | *(How is the data storage and lifecycle financially supported?)* | + +--- + +### **Security and Privacy Handling** + +| **Aspect** | **Description** | +| ------ | ----------- | +| **Sensitive Data** | *(Does this entity include sensitive data? If yes, list the types. reference data sensitivity types.)* | +| **Privacy Measures** | *(How is privacy ensured, e.g., anonymization, encryption, limited access.)* | +| **Risk Mitigation** | *(Steps to mitigate privacy/security risks, e.g., GDPR compliance, security audits.)* | + +--- + +### **Languages and Localization** + +| **Aspect** | **Description** | +| ------ | ----------- | +| **Supported Languages** | *(List supported languages for this entity, e.g., English, Spanish.)* | +| **Localization Needs** | *(Specify if localization/customization is required for different regions or jurisdictions.)* | + +--- + +### **Licensing and Reuse** + +* *Specify applicable licenses (e.g., Creative Commons, MIT License) and reuse constraints of the data.* + +--- + +### **Metadata Attributes** + +Note: The following table is for illustration purposes only the content of the attribute table will be determined by the entity +and its use case. + +Metadata Attributes are defined in the header of each document, common metadata attributes can appear on every document, +entity metadata attributes are those which have a specific meaning to the current entity. +While they can share a common name across entities their purpose may differ from entity to entity. + +#### Common metadata attributes + +| **Attribute** | **Required** | **Type** | **Category** | **Description** | **Constraints** | **Notes** | +| ------------- | ------------ | ------------------------ | ------------------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | +| `id` | Yes | UUID | Unprotected header | Unique identifier for the entity | Primary Key | Ensures global uniqueness for the entity. | +| `ver` | Yes | ULID | Unprotected header | Version ID for the Proposal | The initial ver assigned when published will be identical to the `id` | Enables versioning and traceability. | +| `alg` | Yes | String | Unprotected header | Indicates the cryptography algorithm used for the security processing | It must be equal to EdDSA value. | | +| `type` | Yes | ULID or CBOR Array | Unprotected header | Indicates the content type of the COSE payload | Define Media Types from IANA where possible [Reference](https://www.iana.org/assignments/media-types/media-types.xhtml) | | +| `encoding` | Yes | ULID or CBOR Array | Unprotected header | Indicate the content encoding algorithm of the payload | Current supported encoding algorithms: br - Brotli compressed data. | | +| `kid` | Yes | UTF-8 encoded URI string | Protected header | A unique identifier of the signer. | Each Catalyst Signed Document COSE signature must include the following protected header field | | +| `ref` | Optional | ULID or CBOR Array | Reference | References related entities | Linked Record Constraint | `[, ]` format for version linking. | +| `ref_hash` | Optional | ULID or CBOR Array | Security | This is a cryptographically secured reference to another document. | Cryptographically secured Linked Record Constraint | Hash of the referenced document CBOR bytes | +| `template` | Yes | ULID or CBOR Array | Reference | Template guiding the entity structure | Must reference an existing Template entity | `[, ]` ensures traceable references. | +| `reply` | Optional | CBOR Array | Reference | Identifies the entity this is replying to | Optional; `[, ]` format | Typically used for comments or discussions. | +| `section` | Optional | JSON Path | Reference | Links to a specific section of a document | Must comply with valid JSON Path syntax | Useful for granular referencing within payloads. | +| `collabs` | Optional | CBOR Array | Security | Authorized collaborators for the entity | Must be valid collaborator address | Ensures multi party editing is traceable. | + +#### Entity metadata attributes + +| **Attribute** | **Type** | **Category** | **Description** | **Constraints** | **Notes** | +| ------------- | -------- | ----------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------- | +| `campaign_id` | UUID | Additional Fields | Unique identifier of the category the proposal has been published to | Existing UUID of category, category `brand_id` MUST be the same as the proposal `brand_id` | Ensures each proposal is only published to one category | +| `brand_id` | UUID | Additional Fields | Unique identifier of the brand under which the proposal has been submitted | Existing UUID of brand | Used for quick lookups on indexes | + +--- + +### **Attributes** + +Note: The following table is for illustration purposes only the content of the attribute table will be determined by the entity +and its use case. + +Entity specific attributes that will appear in the document body. + +| **Attribute** | **Type** | **Required** | **Description** | **Constraints** | **Notes** | +| ---------------- | -------- | ------------ | ----------------------------- | --------------------------------------- | ------------------------------------- | +| `title` | String | Yes | Display name for the proposal | Max Length: 255 | Shown in interfaces for user context. | +| `description` | String | Optional | Summary of the proposal | Optional, Max Length: 1000 | Displayed as UI/UX content. | +| `requestedFunds` | Yes | Presentation | Requested amount in ADA | Between: 15,000-2,000,000 ADA inclusive | | +| `duration` | Yes | Presentation | Project duration in months | Between 2 and 12 inclusive | | + +--- + +### **Actions** + +Note: The following table is for illustration purposes only the content of the actions table will be determined by the entity +and its use case. + +This section defines the actions that can be performed on the entity, the entities that can perform the action and any constraints + placed on the action + +| **Operation** | **Action owner** | **Inputs** | **Constraints** | **Expected Output** | **Output Owner** | **Additional Notes** | +| ----------------------- | ------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- | +| **Create** | Proposer (owner) | Register proposer | Proposer must have registered with Catalyst | New proposal document created and assigned a unique ID. (Proposal Document) | Proposal creator now `Owner` | Proposal ownership is initially assigned to the creator; metadata includes creation timestamp. | +| **Proposal Submission** | Proposal owner or collaborator | Proposal ID | Proposal must be complete and pass validation | Proposal becomes visible and active (Proposal Publish Action Document) | Proposal Owner | Transition from draft to public; ensures proposal adheres to all formatting and content guidelines. | +| **Retract** | Proposal owner or collaborator | Proposal ID, reason for retraction | Restricted to owner; may not retract proposals in active voting or funding phases | Proposal is marked as retracted; becomes inactive (Proposal Retraction Action Document) | Proposal Owner | Retracted proposals remain in the system for record keeping but are excluded from future processes. | +| **Comment** | User with role 0 key | Proposal ID, comment text | User must have commenting permissions; content must adhere to community guidelines | Comment linked to the proposal (Comment Document) | Comment creator | Comments are public documents tied to the proposal; responsibility for the lifecycle remains with the commenter. | +| **Vote** | Users who have registered for voting | Proposal ID, vote type (Yes, No, Abstain) | User must belong to an eligible voter group; voting period must be active | (Vote Document) | Voter | Voting results are tied to the proposal; individual votes remain private unless explicitly disclosed. | +| **Review** | Assigned reviewers | Proposal ID, review feedback | User must be assigned as a reviewer; review criteria must be satisfied | Proposal enters reviewed state with feedback (Review Document) | Reviewer | Review documents are tied to the proposal but owned by the reviewer, who is responsible for feedback accuracy. | +| **Approve** | Assigned reviewers | Proposal ID, approval decision | Restricted to authorized reviewers; approval may require a consensus | Proposal is approved and progresses to the next phase (Approved Action Document) | Moderator / Catalyst | | +| **Reject** | Assigned reviewers | Proposal ID, rejection reason | Restricted to authorized reviewers; rejection reason must be provided | Proposal is rejected (Rejected Action Document) | Moderator / Catalyst | Rejected proposals may be revised and resubmitted depending on system fund policies. | +| **Fund** | Funding authority | Proposal ID, funding amount | Proposal must have met all criteria for funding; funding pool must have sufficient balance | Proposal is marked as funded; funds are allocated (Funded Action Document) | Moderator / Catalyst | | +| **Add Collaborator** | Proposal owner | Proposal ID, collaborator ID | Collaborator must have an active account and accept the invitation | Collaborator gains access to the proposal and may contribute (Collaborator Action Document) | Proposal Owner | Added collaborators inherit specific permissions tied to their role in the proposal. | +| **Remove Collaborator** | Proposal owner | Proposal ID, collaborator ID | Collaborator must already be associated with the proposal | Collaborator's access is revoked (Collaborator Revocation Action Document) | Proposal Owner | Removed collaborators can no longer perform actions on the proposal document | + +--- + +### **Workflow** + +* \*Step-by-step description of the entity life cycle and work flows, reference external diagrams + +--- + +### **Error Handling** + +* *Description of potential errors or exceptions and how they are handled and by whom.* + +--- + +## Business Rules + +* *List of business rules or logic associated with this entity* + +--- + +## Data Flow + +* *Description of how data moves into, through, and out of this entity* + +--- + +## Security Considerations + +* *Any security-related information specific to this entity* + +--- + +## Open Issues + +* *Any unresolved questions or potential future changes related to this entity* + +--- + +### **Iteration Change Log** + +| **Version** | **Date** | **Description of Change** | **Author** | +| ------- | ---- | --------------------- | ------ | +| *e.g., v1.0* | *2024-12-20* | *Initial creation of the entity identity card.* | *Name or Role* | +| *e.g., v1.1* | *2024-12-25* | *Added a new attribute to enhance functionality.* | *Name or Role* | + +---