Skip to content

Commit a68dfaf

Browse files
stevenjstevenj
committed
docs(docs): WIP Parameters heirarchy and discovery
1 parent 1ac4d63 commit a68dfaf

File tree

1 file changed

+173
-0
lines changed

1 file changed

+173
-0
lines changed

‎specs/generators/pages/signed_doc/voting_process/parameters_hierarchy_and_discovery.md.jinja‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
Title: Parameters Hierarchy and Pub/Sub Discovery
3+
Authors:
4+
- Steven Johnson <steven[email protected]>
5+
Created: 2025-11-05
6+
order: 1
7+
---
8+
9+
## Abstract
10+
11+
Explains how Brand, Campaign, Category, and Contest Parameters relate,
12+
and how clients discover and validate them in a decentralized pub/sub network
13+
using signed documents and content-addressed references.
14+
15+
## Overview
16+
17+
Parameters control the behavior, timelines, and branding for the system at different scopes:
18+
19+
* Brand Parameters: global root for a brand.
20+
See docs: [Brand Parameters](../docs/brand_parameters.md).
21+
* Campaign Parameters: defined under a brand.
22+
See docs: [Campaign Parameters](../docs/campaign_parameters.md).
23+
* Category Parameters: defined under a campaign.
24+
See docs: [Category Parameters](../docs/category_parameters.md).
25+
* Contest Parameters: defined under a brand, campaign, or category.
26+
See docs: [Contest Parameters](../docs/contest_parameters.md).
27+
28+
Each parameters document is a signed document that:
29+
30+
* Uses COSE Sign with a Catalyst ID `kid`.
31+
See: [COSE Header Parameters](../spec.md#content-type).
32+
* Is content-addressed via a `document_ref` locator (CBOR Tag 42 `cid`).
33+
See: [Document Reference](../metadata.md#document-reference).
34+
* Links through `metadata.parameters` to its parent in the hierarchy.
35+
See: [Parameters metadata](../metadata.md#parameters).
36+
* Is validated by its referenced template.
37+
See: [Contest Parameters Form Template](../docs/contest_parameters_form_template.md) and related templates.
38+
39+
## Relationships
40+
41+
* Brand → Campaign → Category form a strict chain via `metadata.parameters`.
42+
* Contest Parameters link to one of the system-scoped parameters (brand/campaign/category) via
43+
`metadata.parameters` and are thus “anchored” to that chain.
44+
* Templates can be defined at any of these levels, provided their own `parameters` link transitive-up
45+
to the same brand root.
46+
See the rules in [Parameters metadata](../metadata.md#parameters).
47+
48+
```mermaid
49+
erDiagram
50+
BRAND_PARAMETERS ||--o{ CAMPAIGN_PARAMETERS : parameters
51+
CAMPAIGN_PARAMETERS ||--o{ CATEGORY_PARAMETERS : parameters
52+
BRAND_PARAMETERS ||--o{ CONTEST_PARAMETERS : anchors
53+
CAMPAIGN_PARAMETERS ||--o{ CONTEST_PARAMETERS : anchors
54+
CATEGORY_PARAMETERS ||--o{ CONTEST_PARAMETERS : anchors
55+
56+
BRAND_PARAMETERS {
57+
uuidv7 id
58+
uuidv7 ver
59+
}
60+
CAMPAIGN_PARAMETERS {
61+
uuidv7 id
62+
uuidv7 ver
63+
ref brand_parameters
64+
}
65+
CATEGORY_PARAMETERS {
66+
uuidv7 id
67+
uuidv7 ver
68+
ref campaign_parameters
69+
}
70+
CONTEST_PARAMETERS {
71+
uuidv7 id
72+
uuidv7 ver
73+
ref brand_or_campaign_or_category
74+
}
75+
```
76+
77+
## Document Identity and Versioning
78+
79+
* `id` and `ver` are UUIDv7 values;
80+
* `id` is created once;
81+
* `ver` increases over time as new versions of the same parameters document are issued.
82+
* See: [`id`](../metadata.md#id) and [`ver`](../metadata.md#ver).
83+
84+
For example a Brand has ONE Parameters `id`, but that document may have multiple versions
85+
over time as `ver` increases.
86+
This defines that specific brand identity while allowing updates to its parameters.
87+
88+
Whereas Campaign, Category, and Contest Parameters each have their own `id` and `ver`,
89+
that is specific to that parameters document.
90+
Such that a Brand may have multiple old or concurrent Campaigns, each with their own `id` and `ver`, etc.
91+
92+
## Pub/Sub Discovery Model
93+
94+
Documents are published in bound topics.
95+
Each Topic collects a subset of documents based on their anchoring parameters document, and optionally their type.
96+
97+
### Global Root
98+
99+
The root of discovery is known as the Global root.
100+
The pub/sub system assumes that valid documents once published will be retained indefinitely.
101+
In order to prevent buildup and bloat the Global root will rotate through time.
102+
It is formed of the path:
103+
`catalyst/signed-docs/<start>/<end>`
104+
Where `<start>` and `<end>` are UTC Timestamps.
105+
106+
* `<start>` is aligned to the UTC Calendar start of the current year, ie (01-01-XX 00:00:00).
107+
* `<end>` is aligned to the UTC Calendar start of the second consecutive year, ie (01-01-XX+1 00:00:00).
108+
109+
Only ACTIVE `Brand` Parameters and associated Template documents are published to the Global root topic.
110+
Because the `<start` is incremented every year, there is a natural rotation of the Global root, and a ` year overlap between two consecutive Global roots.
111+
This means that ACTIVE Brand documents may be co-published in two consecutive Global root topics for a period of up to one year.
112+
113+
This creates a natural sliding window which allows old, unused or revoked Brand documents to age out of the system over time.
114+
115+
The **ONLY** Documents which may be validly published to the Global root topic are `Brand` Parameters documents, which are signed by the appropriate Administration Key.
116+
117+
Any other document type, or documents signed by other keys, published to the Global root topic must be rejected by subscribers.
118+
119+
### Sub Document Topics
120+
121+
Beneath the Global Root exist a hierarchy of topics for each anchoring parameters document, and optionally by document type.
122+
123+
The general format of these topics is:
124+
`catalyst/signed-docs/<doc-id>[/<doc-type>]`
125+
Where:
126+
* `<doc-id>` is the `id` of the anchoring parameters document.
127+
* For Campaign Parameters, this is the Brand's `id`.
128+
* For Category Parameters, this is the Campaign's `id`.
129+
* For Contest Parameters, this is the Brand's, Campaign's, or Category's `id` as appropriate.
130+
* Note this is ONLY the `id` value, NOT the `ver` this means that all versions of documents anchored to that parameters document are published to the same topic.
131+
* `<doc-type>` is optional, and if present only documents of that type may be published to the topic.
132+
133+
Discovery Happens by subscribing to the Global root topic to find ACTIVE Brand Parameters documents.
134+
Once discovered, the subscriber can then subscribe to an appropriate brands topic, which allows discovery of all Campaign or Contest Parameters or any other document type anchored to that brand.
135+
From there, the subscriber can continue down the hierarchy by subscribing to Campaign topics to find Category or Contest Parameters documents anchored to that campaign, and so on.
136+
137+
Producers publish COSE_Sign blobs plus their `document_ref` (CID) on these topics. Consumers:
138+
139+
1. Verify signature (`kid`), content type, and deterministic CBOR/JSON as applicable.
140+
2. Verify `type`, `id`, `ver`, and that `ver ≥ id` (UUIDv7 ordering).
141+
3. Verify `template` exists and the payload validates against that template.
142+
4. Verify `parameters` links to the correct parent in the chain and is consistent transitively up to the brand.
143+
5. Verify the Document is published to the correct Topic according to its anchoring parameters document and type.
144+
6. Apply `revocations` and prefer the latest valid `ver` for each `id`.
145+
7. Optionally follow `chain` for lineage and completeness.
146+
147+
### Entry Points
148+
149+
- Known brand roots (e.g., published by the Brand CA) are typical bootstrap points. From a Brand Parameters `id`:
150+
- Subscribe for its Campaign Parameters.
151+
- For each campaign, subscribe for its Category Parameters.
152+
- For each category, subscribe for any Contest Parameters.
153+
- Also subscribe for Contest Parameters anchored directly to the brand or campaign.
154+
155+
### Content Addressing
156+
157+
- Every `document_ref` includes a CBOR-encoded CID for location in content-addressed storage. See: [CBOR Tag 42](../links.md#CBOR-TAG-42) and [IPFS CID](../links.md#IPFS-CID).
158+
- The locator does not guarantee availability; it guarantees identity. Pub/sub disseminates the bytes; content-addressed stores provide retrieval by CID.
159+
160+
## Validation Summary per Parameters Level
161+
162+
- Brand Parameters: root; template required; `parameters` is excluded at this level.
163+
- Campaign Parameters: must link `parameters` to a Brand Parameters document.
164+
- Category Parameters: must link `parameters` to a Campaign Parameters document.
165+
- Contest Parameters: must link `parameters` to one of Brand/Campaign/Category Parameters for the same chain.
166+
167+
See the per-document pages for full rules and examples: [Brand](../docs/brand_parameters.md), [Campaign](../docs/campaign_parameters.md), [Category](../docs/category_parameters.md), [Contest](../docs/contest_parameters.md).
168+
169+
## Operational Notes
170+
171+
- Consistency: reject documents whose `parameters` do not align transitively to the same brand root as the referencing items (templates, child parameters).
172+
- Freshness: prefer the highest valid `ver` per `id`; handle `revocations` strictly.
173+
- Indexes: index by `(type, id, ver)` and by `(parameters-anchor, type)` to accelerate discovery.

0 commit comments

Comments
 (0)