input-output-hk · stevenj · Aug 26, 2025 · Aug 26, 2025 · Sep 9, 2025 · Sep 9, 2025
diff --git a/docs/src/architecture/08_concepts/signed_doc/.pages b/docs/src/architecture/08_concepts/signed_doc/.pages
@@ -7,3 +7,4 @@ nav:
   - Document Form Templates: form_templates.md
   - form_template_elements
   - Document Presentation Templates: presentation_template.md
+  - key-derivation
diff --git a/docs/src/architecture/08_concepts/signed_doc/cddl/section_ref.cddl b/docs/src/architecture/08_concepts/signed_doc/cddl/section_ref.cddl
@@ -5,4 +5,5 @@
 section_ref = json_pointer
 
 ; RFC6901 Standard JSON Pointer
+; See: https://datatracker.ietf.org/doc/html/rfc6901
 json_pointer = text
diff --git a/docs/src/architecture/08_concepts/signed_doc/cddl/signed_document.cddl b/docs/src/architecture/08_concepts/signed_doc/cddl/signed_document.cddl
@@ -33,7 +33,7 @@ COSE_Document_Header_Map = {
 ; COSE Standard headers used by a Document
 COSE_Document_Standard_Headers = (
   3 => media_type
-  ?"content-encoding" => http_content_encoding
+  "content-encoding" => http_content_encoding
 )
 
 ; Supported Content Media Types.
@@ -113,6 +113,7 @@ cid = #6.42(bytes)
 section_ref = json_pointer
 
 ; RFC6901 Standard JSON Pointer
+; See: https://datatracker.ietf.org/doc/html/rfc6901
 json_pointer = text
 
 ; Allowed Collaborators on the next subsequent version of a document.

diff --git a/docs/src/architecture/08_concepts/signed_doc/diagrams/all.dot b/docs/src/architecture/08_concepts/signed_doc/diagrams/all.dot
@@ -581,7 +581,7 @@ digraph "All" {
                     <TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
                         <TR>
                             <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">content type</FONT></TD>
-                            <TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Undefined</I></FONT></TD>
+                            <TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>application/json</I></FONT></TD>
                         </TR>
                     </TABLE>
                 </TD>

diff --git a/docs/src/architecture/08_concepts/signed_doc/diagrams/all.dot.svg b/docs/src/architecture/08_concepts/signed_doc/diagrams/all.dot.svg
diff --git a/docs/src/architecture/08_concepts/signed_doc/diagrams/contest_delegation.dot b/docs/src/architecture/08_concepts/signed_doc/diagrams/contest_delegation.dot
@@ -57,7 +57,7 @@ Relationships"
                     <TABLE CELLPADDING="0" CELLSPACING="0" BORDER="0">
                         <TR>
                             <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="200"><FONT COLOR="#7706E5">content type</FONT></TD>
-                            <TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>Undefined</I></FONT></TD>
+                            <TD ALIGN="RIGHT"><FONT COLOR="#7706E5"><I>application/json</I></FONT></TD>
                         </TR>
                     </TABLE>
                 </TD>

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/brand_parameters.md b/docs/src/architecture/08_concepts/signed_doc/docs/brand_parameters.md
@@ -158,7 +158,7 @@ Revoked documents are flagged as no longer valid, and should not be displayed.
 As a special case, if the revocations are set to `true` then all versions of the document
 are revoked, including the latest document.
 
-In this case, when the latest document is revoked, the payload may be empty.
+In this case, when the latest document is revoked, the payload may be `nil`.
 Any older document that has [`revocations`](../metadata.md#revocations) set to `true` is always to be filtered
 and its payload is to be assumed to be invalid.
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/campaign_parameters.md b/docs/src/architecture/08_concepts/signed_doc/docs/campaign_parameters.md
@@ -159,7 +159,7 @@ Revoked documents are flagged as no longer valid, and should not be displayed.
 As a special case, if the revocations are set to `true` then all versions of the document
 are revoked, including the latest document.
 
-In this case, when the latest document is revoked, the payload may be empty.
+In this case, when the latest document is revoked, the payload may be `nil`.
 Any older document that has [`revocations`](../metadata.md#revocations) set to `true` is always to be filtered
 and its payload is to be assumed to be invalid.
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/category_parameters.md b/docs/src/architecture/08_concepts/signed_doc/docs/category_parameters.md
@@ -159,7 +159,7 @@ Revoked documents are flagged as no longer valid, and should not be displayed.
 As a special case, if the revocations are set to `true` then all versions of the document
 are revoked, including the latest document.
 
-In this case, when the latest document is revoked, the payload may be empty.
+In this case, when the latest document is revoked, the payload may be `nil`.
 Any older document that has [`revocations`](../metadata.md#revocations) set to `true` is always to be filtered
 and its payload is to be assumed to be invalid.
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/contest_delegation.md b/docs/src/architecture/08_concepts/signed_doc/docs/contest_delegation.md
@@ -15,14 +15,47 @@ Multiple Delegations must be published if there are multiple
 Contests within a Brand/Campaign or Category.
 
 This is because different Contests may have different rules.
-And not all Representatives will choose to nominate
+And not all Representatives will choose to (or be able to) nominate
 for every Contest.
 
 A Representative ***MAY NOT*** delegate to a different Representative
 for any contest they have nominated for.
 They ***MAY*** however nominate a Representative in any contest they
 have not nominated for.
 
+A Representative is NOT required to delegate to themselves in a contest they are nominated for,
+and in fact, any self-delegation is invalid and ignored.
+A Representative has an implicit 100% voting power delegation to themselves in any contest
+they are nominated.
+The MAY not vote personally, and if they do, that vote will have Zero (0) voting power.
+100% of their voting power is assigned to their delegate vote and can not be split in any way.
+
+A voter MAY choose multiple delegates for a contest, in this case they are listed in priority
+order from highest priority to lowest.
+Priority only affects two aspects of the delegation.
+
+1. Any residual voting power after it is split among all delegates is given to the highest
+   priority delegate (first).
+2. If there is not enough voting power to distribute, then its distributed from highest
+   priority to lowest.
+   This may mean that low priority delegates get zero voting power.
+
+An example:  If a Voter has 100 raw voting power, after quadratic scaling, they have 10.
+If they delegated to 15 delegates equally, then only the first 10 would get 1 voting power
+each.
+Voting power is not fractionally assigned.
+
+The payload MAY contain a [json][RFC8259] document which consists of a single array which can adjust
+the ratio of the delegation.
+Voting power is divided based on the weight of a single delegate over the sum of all
+weights of all delegates.
+This is performed with integer division.
+As a special condition, 0 or any negative value is equivalent to a weight of 1.
+As explained above, if there is not enough voting power to distribute, low priority reps
+will receive 0 voting power from the delegation.
+And if there is any residual after integer division its applied to the representative
+with the highest priority.
+
 <!-- markdownlint-disable max-one-sentence-per-line -->
 
 ```graphviz dot contest_delegation.dot.svg
@@ -37,6 +70,12 @@ have not nominated for.
 * The [`parameters`](../metadata.md#parameters) metadata *MUST* point to the same Contest as the
     Nomination of the Representative.
 * The 'ref' metadata field MUST point to a valid 'Representative Nomination'.
+    IF there are multiple representatives, then any which are not pointing
+    to a valid `Representative Nomination` are excluded.
+    The nomination is only invalid if ALL references `Representative Nomination`
+    references are invalid.
+    This is to prevent a Representative changing their nomination invalidating a
+    delegation with multiple representatives.
 * The payload MUST be nil.
 
 A Representative *MUST* Delegate to their latest Nomination for a Category,
@@ -74,7 +113,8 @@ considered.
 
 ## [COSE Header Parameters][RFC9052-HeaderParameters]
 
-No Headers are defined for this document.
+* [content type](../spec.md#content-type) = `application/json`
+* [content-encoding](../spec.md#content-encoding) = `[br]`
 
 ## Metadata
 
@@ -134,6 +174,7 @@ The document version must always be >= the document ID.
 | --- | --- |
 | Required | yes |
 | Format | [Document Reference](../metadata.md#document-reference) |
+| Multiple References | True |
 | Valid References | [Rep Nomination](rep_nomination.md) |
 <!-- markdownlint-enable MD033 -->
 Reference to a Linked Document or Documents.
@@ -182,7 +223,7 @@ Revoked documents are flagged as no longer valid, and should not be displayed.
 As a special case, if the revocations are set to `true` then all versions of the document
 are revoked, including the latest document.
 
-In this case, when the latest document is revoked, the payload may be empty.
+In this case, when the latest document is revoked, the payload may be `nil`.
 Any older document that has [`revocations`](../metadata.md#revocations) set to `true` is always to be filtered
 and its payload is to be assumed to be invalid.
 
@@ -231,10 +272,83 @@ hierarchy they are all valid.
 
 ## Payload
 
-There is no payload.
-
-This document has no payload.
-It must be encoded as a [CBOR][RFC8949] `null (0xf6)`.
+The Payload is a [JSON][RFC8259] Document, and must conform to this schema.
+
+It consists of an array which defines the weights to be applied to the chosen delegations.
+
+Each valid delegate gets the matching weight from this array.
+The total voting power is split proportionally based on these weights over the
+valid drep nominations.
+
+### Schema
+
+<!-- markdownlint-disable MD013 MD046 max-one-sentence-per-line -->
+??? abstract "Schema: Payload [JSON][RFC8259] Schema"
+
+    The Payload is a [JSON][RFC8259] Document, and must conform to this schema.
+
+    It consists of an array which defines the weights to be applied to the chosen delegations.
+
+    Each valid delegate gets the matching weight from this array.
+    The total voting power is split proportionally based on these weights over the
+    valid drep nominations.
+
+
+    ```json
+    {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "maintainers": [
+        {
+          "name": "Catalyst Team",
+          "url": "https://projectcatalyst.io/"
+        }
+      ],
+      "title": "Contest Delegation Schema",
+      "description": "Structure of the payload of a Contest Delegation.",
+      "type": "object",
+      "properties": {
+        "weights": {
+          "description": "List of weights to apply to each delegate.\nThis list is in the same order as the delegate references.\nIf there are fewer entries than delegates, then the missing weights are set to `1`.\nIf there are more weights, then the extra weights are ignored.  If the payload is missing, OR the array is empty, then the weights assigned is `1`.",
+          "items": {
+            "exclusiveMinimum": 0,
+            "type": "integer"
+          },
+          "minItems": 0,
+          "type": "array"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "weights"
+      ],
+      "x-changelog": {
+        "2025-03-01": [
+          "First Version Created."
+        ]
+      }
+    }
+    ```
+<!-- markdownlint-enable MD013 MD046 max-one-sentence-per-line -->
+
+### Example
+<!-- markdownlint-disable MD013 MD046 max-one-sentence-per-line -->
+??? example "Example: Three Delegation Weights"
+
+    If there are only 1 delegation, then the weights do not matter.
+    If there are two, then the first delegate has a weight of 10/30, and the second has 20/30.
+    If there are 5, then the weights are: `[10,20,30,1,1]`
+
+    ```json
+    {
+      "weights": [
+        10,
+        20,
+        30
+      ]
+    }
+    ```
+
+<!-- markdownlint-enable MD013 MD046 max-one-sentence-per-line -->
 
 ## Signers
 
@@ -264,9 +378,13 @@ New versions of this document may be published by:
 
 * First Published Version
 
+#### 0.1.2 (2025-09-04)
+
+* Allow Multi Delegation
+
 [CBOR-TAG-42]: https://github.com/ipld/cid-cbor/
 [RFC9052-HeaderParameters]: https://www.rfc-editor.org/rfc/rfc8152#section-3.1
 [CC-BY-4.0]: https://creativecommons.org/licenses/by/4.0/legalcode
 [IPFS-CID]: https://docs.ipfs.tech/concepts/content-addressing/#what-is-a-cid
 [RFC9562-V7]: https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-7
-[RFC8949]: https://www.rfc-editor.org/rfc/rfc8949.html
+[RFC8259]: https://www.rfc-editor.org/rfc/rfc8259.html
diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/contest_parameters.md b/docs/src/architecture/08_concepts/signed_doc/docs/contest_parameters.md
@@ -159,7 +159,7 @@ Revoked documents are flagged as no longer valid, and should not be displayed.
 As a special case, if the revocations are set to `true` then all versions of the document
 are revoked, including the latest document.
 
-In this case, when the latest document is revoked, the payload may be empty.
+In this case, when the latest document is revoked, the payload may be `nil`.
 Any older document that has [`revocations`](../metadata.md#revocations) set to `true` is always to be filtered
 and its payload is to be assumed to be invalid.
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/proposal.md b/docs/src/architecture/08_concepts/signed_doc/docs/proposal.md
@@ -167,7 +167,7 @@ Revoked documents are flagged as no longer valid, and should not be displayed.
 As a special case, if the revocations are set to `true` then all versions of the document
 are revoked, including the latest document.
 
-In this case, when the latest document is revoked, the payload may be empty.
+In this case, when the latest document is revoked, the payload may be `nil`.
 Any older document that has [`revocations`](../metadata.md#revocations) set to `true` is always to be filtered
 and its payload is to be assumed to be invalid.
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/proposal_comment.md b/docs/src/architecture/08_concepts/signed_doc/docs/proposal_comment.md
@@ -202,7 +202,7 @@ Revoked documents are flagged as no longer valid, and should not be displayed.
 As a special case, if the revocations are set to `true` then all versions of the document
 are revoked, including the latest document.
 
-In this case, when the latest document is revoked, the payload may be empty.
+In this case, when the latest document is revoked, the payload may be `nil`.
 Any older document that has [`revocations`](../metadata.md#revocations) set to `true` is always to be filtered
 and its payload is to be assumed to be invalid.
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/rep_nomination.md b/docs/src/architecture/08_concepts/signed_doc/docs/rep_nomination.md
@@ -212,7 +212,7 @@ Revoked documents are flagged as no longer valid, and should not be displayed.
 As a special case, if the revocations are set to `true` then all versions of the document
 are revoked, including the latest document.
 
-In this case, when the latest document is revoked, the payload may be empty.
+In this case, when the latest document is revoked, the payload may be `nil`.
 Any older document that has [`revocations`](../metadata.md#revocations) set to `true` is always to be filtered
 and its payload is to be assumed to be invalid.
 

diff --git a/docs/src/architecture/08_concepts/signed_doc/docs/rep_profile.md b/docs/src/architecture/08_concepts/signed_doc/docs/rep_profile.md
@@ -126,7 +126,7 @@ Revoked documents are flagged as no longer valid, and should not be displayed.
 As a special case, if the revocations are set to `true` then all versions of the document
 are revoked, including the latest document.
 
-In this case, when the latest document is revoked, the payload may be empty.
+In this case, when the latest document is revoked, the payload may be `nil`.
 Any older document that has [`revocations`](../metadata.md#revocations) set to `true` is always to be filtered
 and its payload is to be assumed to be invalid.