Proposal Submission Action¶

Description¶

Proposal Submission Action¶

A Proposal Submission Action is a document which can attempt to either submit a particular version of a proposal into a campaign, or withdraw it.

The last action on the document ts the action which takes effect at the deadline.

For multiple collaborators, multiple submission actions can be posted independently, but none of them will take effect until ALL collaborators have posted equivalent actions.

For example, three collaborators Alice/Bob/Claire can each post one submission action for the same document. Unless they all submit the same version of the proposal the proposal will not be seen as submitted.

The payload is a fixed format.

Validation¶

No validation is required beyond as defined by:

metadata
payload
signers

Business Logic¶

Front End¶

A proposal with collaborators will not be shown as having a confirmed collaborator, unless there exists a draft or final proposal submission from that collaborator.

Any document that lists a collaborator should be highlighted to that collaborator so they can take appropriate action, such as:

Confirm they are a collaborator by submitting this document as draft
Agree to being a collaborator on the final submission by submitting this document as final
Hide themselves from the collaborators list but do not remove themselves by submitting hide
Remove themselves permanently as a collaborator by publishing a new version with them removed.

To eliminate the necessity for collaborators to accept collaboration on every version, they will be considered as agreeing to be a collaborator on any version of the document that lists them, if their latest submission is draft or final.

If their latest submission on a document is hide they should be considered to not have agreed to be a collaborator.

NOTE final status ONLY applies to the exactly referenced document and version.

Back End¶

A Submitted proposal with collaborators MUST have a final submission by ALL listed collaborators. If any collaborator has not submitted a final submission by the deadline, then the proposal is not considered final and will not be considered in the category it was being submitted to.

COSE Header Parameters ¶

content type = application/json
content-encoding = [br]

Metadata¶

`type`¶

Parameter	Value
Required	yes
Format	Document Type
Type	`5e60e623-ad02-4a1b-a1ac-406db978ee48`, `7808d2ba-d511-40af-84e8-c0d1625fdfdc`, `78927329-cfd9-4ea1-9c71-0e019b126a65`

The document TYPE.

Validation¶

MUST be a known document type.

`id`¶

Parameter	Value
Required	yes
Format	UUIDv7

Document ID, created the first time the document is created. This must be a properly created UUIDv7 which contains the timestamp of when the document was created.

Validation¶

IF ver does not == id then a document with id and ver being equal MUST exist.

`ver`¶

Parameter	Value
Required	yes
Format	UUIDv7

The unique version of the document. The first version of the document must set ver == id

Validation¶

The document version must always be >= the document ID.

`ref`¶

Parameter	Value
Required	yes
Format	Document Reference
Multiple References	True
Valid References	Proposal

Reference to a Linked Document or Documents. This is the primary hierarchical reference to a related document.

This is an Array of the format:

[ 1* [ document_id, document_ver, document_locator ] ]

If a reference is defined as required, there must be at least 1 reference specified. Some documents allow multiple references, and they are documented as required.

document_id is the UUIDv7 ID of the Document being referenced.
document_ver is the UUIDv7 Version of the Document being referenced.
document_locator is a content unique locator for the document. This serves two purposes.
It ensures that the document referenced by an ID/Version is not substituted. In other words, that the document intended to be referenced, is actually referenced.
Allow the document to be unambiguously located in decentralized storage systems.

There can be any number of Document Locations in any reference. The currently defined locations are:

cid : A CBOR Encoded IPLD Content Identifier ( AKA an IPFS CID ).
Others may be added when further storage mechanisms are defined.

The value set here does not guarantee that the document is actually stored. It only defines that if it were stored, this is the identifier that that is required to retrieve it.

Validation¶

The following must be true for a valid reference:

The Referenced Document MUST Exist
Every value in the document_locator must consistently reference the exact same document.
The document_id and document_ver MUST match the values in the referenced document.

`category_id`¶

Parameter	Value
Required	yes
Format	Document Reference
Valid References	Category Parameters
Exclusive	`brand_id`
	`campaign_id`

A reference to the Category Parameters Document this document lies under.

Validation¶

In addition to the validation performed for Document Reference type fields:

Any linked referenced document that includes a category_id must match the category_id of the referencing document.
MUST NOT be present in any document that contains brand_id and campaign_id metadata.

Payload¶

The kind of action is controlled by this payload. The Payload is a JSON Document, and must conform to this schema.

States:

final : All collaborators must publish a final status for the proposal to be final.
draft : Reverses the previous final state for a signer and accepts collaborator status to a document.
hide : Requests the proposal be hidden (not final, but a hidden draft). hide is only actioned if sent by the author, for a collaborator it identified that they do not wish to be listed as a collaborator.

Schema :

{
  "$id": "https://raw.githubusercontent.com/input-output-hk/catalyst-libs/refs/heads/main/specs/signed_docs/docs/payload_schemas/proposal_submission_action.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "definitions": {
    "action": {
      "description": "The action being performed on the Proposal.",
      "enum": [
        "final",
        "draft",
        "hide"
      ],
      "type": "string"
    }
  },
  "description": "Structure of the payload of a Proposal Submission Action.",
  "maintainers": [
    {
      "name": "Catalyst Team",
      "url": "https://projectcatalyst.io/"
    }
  ],
  "properties": {
    "action": {
      "$ref": "#/definitions/action"
    }
  },
  "required": [
    "action"
  ],
  "title": "Proposal Submission Action Payload Schema",
  "x-changelog": {
    "2025-03-01": [
      "First Version Created."
    ]
  }
}

Signers¶

The following user roles may sign documents of this type:

Proposer

New versions of this document may be published by:

author
collaborators

Copyright¶

Copyright	2024-2025 IOG Singapore, All Rights Reserved
License	This document is licensed under CC-BY-4.0
Created	2024-12-27
Modified	2025-04-09
Authors	Alex Pozhylenkov alex.pozhylenkov@iohk.io
	Steven Johnson steven.johnson@iohk.io

Changelog¶

0.01 (2025-04-04)¶

First Published Version

Proposal Submission Action¶

Description¶