Skip to content

Commit 83e1828

Browse files
stevenjstevenj
committed
fix(docs): Add drep registration and delegation process docs
1 parent ad02c93 commit 83e1828

File tree

2 files changed

+194
-1
lines changed

2 files changed

+194
-1
lines changed

‎docs/src/architecture/08_concepts/signed_doc/voting_process/drep_delegation_and_discovery.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ and how these documents are discovered and validated in a decentralized pub/sub
1313

1414
## Documents and Roles
1515

16+
* On‑chain dRep Registration: a chain‑level registration that binds a dRep’s
17+
Catalyst ID to the role of `Representative`.
1618
* Rep Profile: the representative’s global profile under a brand.
1719
See: [Rep Profile](../docs/rep_profile.md).
1820
* Rep Nomination: contest-specific nomination under contest parameters.
@@ -25,6 +27,101 @@ Signers:
2527
* Rep Profile and Rep Nomination: signed by a `Representative`.
2628
* Contest Delegation: signed by a `Registered` user (voter).
2729

30+
## dRep Lifecycle and Contest Participation
31+
32+
### 1. On‑Chain dRep Registration
33+
34+
* A user first registers on‑chain as a dRep, binding their Catalyst ID to the
35+
`Representative` role.
36+
* This on‑chain registration is a prerequisite for publishing any signed‑doc
37+
Rep Profile, Rep Nomination, or Contest Delegation as a representative.
38+
39+
### 2. Global Rep Profile (Brand‑Scoped)
40+
41+
* After on‑chain registration, the dRep creates a [Rep Profile](../docs/rep_profile.md)
42+
anchored to a Brand via [`metadata.parameters`](../metadata.md#parameters).
43+
* This profile is *global* for that Brand:
44+
* It describes who the dRep is and the information they wish to make known.
45+
* It does **not** by itself make them active in any specific contest.
46+
* Contest‑specific nominations reference this global profile via
47+
[`metadata.ref`](../metadata.md#ref).
48+
49+
### 3. Contest Parameters and dRep Eligibility
50+
51+
* [Contest Parameters](../docs/contest_parameters.md) are published under a Category
52+
(and possibly Campaign/Brand) and define:
53+
* Whether dRep representation is enabled for that contest.
54+
* Which anchor level (Brand/Campaign/Category) the contest belongs to.
55+
* Deadlines for dRep nomination and dRep choice (delegation) before voting.
56+
* Only contests whose parameters explicitly enable dReps will have valid
57+
Rep Nominations and Contest Delegations.
58+
59+
### 4. dRep Nomination and Self‑Delegation
60+
61+
* For each contest where a dRep wants to be active, they must:
62+
1. Publish a [Rep Nomination](../docs/rep_nomination.md) anchored to that
63+
contest via [`metadata.parameters`](../metadata.md#parameters), referencing
64+
their Rep Profile via [`metadata.ref`](../metadata.md#ref).
65+
2. Publish a [Contest Delegation](../docs/contest_delegation.md) **as the
66+
delegator**, delegating their own voting power to their latest nomination
67+
for that contest.
68+
* A Representative ***MAY NOT*** delegate to another Representative for any
69+
contest they have nominated for.
70+
They ***MAY*** delegate to a Representative in contests they have not
71+
nominated for.
72+
* A Representative’s nomination in a contest is only valid if:
73+
* Their latest nomination in that contest is not revoked; and
74+
* Their latest Contest Delegation in that contest references their latest
75+
nomination.
76+
* Contest parameters typically define a deadline before voting starts by which:
77+
* dReps must have completed nomination + self‑delegation; and
78+
* Late nominations or self‑delegations are ignored for that contest.
79+
80+
### 5. Voter Delegation to dReps
81+
82+
* Any registered voter can, up to the contest’s dRep choice deadline, publish a
83+
[Contest Delegation](../docs/contest_delegation.md) to one or more dReps who
84+
have valid nominations in that contest.
85+
* Delegations are:
86+
* Contest‑specific (one per contest per delegator, latest takes effect).
87+
* Priority‑ordered, with optional weights, as described in
88+
[Contest Delegation](../docs/contest_delegation.md#description).
89+
* A voter can delegate to a dRep who:
90+
* Has an on‑chain dRep registration;
91+
* Has a valid Rep Profile and Rep Nomination for the contest; and
92+
* Has a valid self‑delegation to their latest nomination for that contest.
93+
94+
### dRep Delegation Flow (Mermaid)
95+
96+
```mermaid
97+
flowchart TD
98+
subgraph Registration_and_Profile["Registration and Global Profile"]
99+
A["On-chain dRep Registration<br/>(Catalyst ID -> Representative role)"]
100+
B["Rep Profile<br/>(Brand-scoped identity)"]
101+
A --> B
102+
end
103+
104+
subgraph Contest_Setup["Contest Setup"]
105+
C["Contest Parameters<br/>(enable dReps, deadlines, anchor)"]
106+
end
107+
108+
subgraph dRep_Activation["dRep Contest Activation"]
109+
D["Rep Nomination<br/>(contest-specific)"]
110+
E["Contest Delegation<br/>(self-delegation to latest nomination)"]
111+
D --> E
112+
end
113+
114+
subgraph Voter_Delegation["Voter Delegation"]
115+
F["Voter Contest Delegation<br/>(to one or more dReps)"]
116+
end
117+
118+
Registration_and_Profile --> C
119+
B --> D
120+
C --> D
121+
C --> F
122+
E --> F
123+
```
124+
28125
## Relationships and Rules
29126

30127
* A Rep Profile is anchored to a Brand via [`metadata.parameters`](../metadata.md#parameters)

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

Lines changed: 97 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ and how these documents are discovered and validated in a decentralized pub/sub
1313

1414
## Documents and Roles
1515

16+
* On‑chain dRep Registration: a chain‑level registration that binds a dRep’s
17+
Catalyst ID to the role of `Representative`.
1618
* Rep Profile: the representative’s global profile under a brand.
1719
See: [Rep Profile](../docs/rep_profile.md).
1820
* Rep Nomination: contest-specific nomination under contest parameters.
@@ -25,6 +27,101 @@ Signers:
2527
* Rep Profile and Rep Nomination: signed by a `Representative`.
2628
* Contest Delegation: signed by a `Registered` user (voter).
2729

30+
## dRep Lifecycle and Contest Participation
31+
32+
### 1. On‑Chain dRep Registration
33+
34+
* A user first registers on‑chain as a dRep, binding their Catalyst ID to the
35+
`Representative` role.
36+
* This on‑chain registration is a prerequisite for publishing any signed‑doc
37+
Rep Profile, Rep Nomination, or Contest Delegation as a representative.
38+
39+
### 2. Global Rep Profile (Brand‑Scoped)
40+
41+
* After on‑chain registration, the dRep creates a [Rep Profile](../docs/rep_profile.md)
42+
anchored to a Brand via [`metadata.parameters`](../metadata.md#parameters).
43+
* This profile is *global* for that Brand:
44+
* It describes who the dRep is and the information they wish to make known.
45+
* It does **not** by itself make them active in any specific contest.
46+
* Contest‑specific nominations reference this global profile via
47+
[`metadata.ref`](../metadata.md#ref).
48+
49+
### 3. Contest Parameters and dRep Eligibility
50+
51+
* [Contest Parameters](../docs/contest_parameters.md) are published under a Category
52+
(and possibly Campaign/Brand) and define:
53+
* Whether dRep representation is enabled for that contest.
54+
* Which anchor level (Brand/Campaign/Category) the contest belongs to.
55+
* Deadlines for dRep nomination and dRep choice (delegation) before voting.
56+
* Only contests whose parameters explicitly enable dReps will have valid
57+
Rep Nominations and Contest Delegations.
58+
59+
### 4. dRep Nomination and Self‑Delegation
60+
61+
* For each contest where a dRep wants to be active, they must:
62+
1. Publish a [Rep Nomination](../docs/rep_nomination.md) anchored to that
63+
contest via [`metadata.parameters`](../metadata.md#parameters), referencing
64+
their Rep Profile via [`metadata.ref`](../metadata.md#ref).
65+
2. Publish a [Contest Delegation](../docs/contest_delegation.md) **as the
66+
delegator**, delegating their own voting power to their latest nomination
67+
for that contest.
68+
* A Representative ***MAY NOT*** delegate to another Representative for any
69+
contest they have nominated for.
70+
They ***MAY*** delegate to a Representative in contests they have not
71+
nominated for.
72+
* A Representative’s nomination in a contest is only valid if:
73+
* Their latest nomination in that contest is not revoked; and
74+
* Their latest Contest Delegation in that contest references their latest
75+
nomination.
76+
* Contest parameters typically define a deadline before voting starts by which:
77+
* dReps must have completed nomination + self‑delegation; and
78+
* Late nominations or self‑delegations are ignored for that contest.
79+
80+
### 5. Voter Delegation to dReps
81+
82+
* Any registered voter can, up to the contest’s dRep choice deadline, publish a
83+
[Contest Delegation](../docs/contest_delegation.md) to one or more dReps who
84+
have valid nominations in that contest.
85+
* Delegations are:
86+
* Contest‑specific (one per contest per delegator, latest takes effect).
87+
* Priority‑ordered, with optional weights, as described in
88+
[Contest Delegation](../docs/contest_delegation.md#description).
89+
* A voter can delegate to a dRep who:
90+
* Has an on‑chain dRep registration;
91+
* Has a valid Rep Profile and Rep Nomination for the contest; and
92+
* Has a valid self‑delegation to their latest nomination for that contest.
93+
94+
### dRep Delegation Flow (Mermaid)
95+
96+
```mermaid
97+
flowchart TD
98+
subgraph Registration_and_Profile["Registration and Global Profile"]
99+
A["On-chain dRep Registration<br/>(Catalyst ID -> Representative role)"]
100+
B["Rep Profile<br/>(Brand-scoped identity)"]
101+
A --> B
102+
end
103+
104+
subgraph Contest_Setup["Contest Setup"]
105+
C["Contest Parameters<br/>(enable dReps, deadlines, anchor)"]
106+
end
107+
108+
subgraph dRep_Activation["dRep Contest Activation"]
109+
D["Rep Nomination<br/>(contest-specific)"]
110+
E["Contest Delegation<br/>(self-delegation to latest nomination)"]
111+
D --> E
112+
end
113+
114+
subgraph Voter_Delegation["Voter Delegation"]
115+
F["Voter Contest Delegation<br/>(to one or more dReps)"]
116+
end
117+
118+
Registration_and_Profile --> C
119+
B --> D
120+
C --> D
121+
C --> F
122+
E --> F
123+
```
124+
28125
## Relationships and Rules
29126

30127
* A Rep Profile is anchored to a Brand via [`metadata.parameters`](../metadata.md#parameters)
@@ -109,4 +206,3 @@ that anchors the document via [`metadata.parameters`](../metadata.md#parameters)
109206
that nomination to remain valid.
110207
* Indexing by (contest, representative) and (contest, delegator) accelerates delegation resolution
111208
and tally preparation.
112-

0 commit comments

Comments
 (0)