Skip to content

Commit 5a8a46d

Browse files
cong-orcong-or
authored
Merge branch 'main' into feat/hermes-ipfs-transport-enable-methods
2 parents 398a247 + 812c9a8 commit 5a8a46d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+1245
-663
lines changed

‎catalyst-python/src/catalyst_python/signed_doc.py‎

Lines changed: 105 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# ruff: noqa: D100, D101, D102, D103, D107, S603, PLW1510, I001
1+
# ruff: noqa: D100, D101, D102, D103, D107, S603, PLW1510, PLR0913, I001
22

33
from typing import Any, Self
44
from enum import StrEnum
@@ -40,6 +40,20 @@ class DocType(StrEnum):
4040
rep_profile_form_template = "564cbea3-44d3-4303-b75a-d9fdda7e5a80"
4141

4242

43+
class DocumentRef:
44+
def __init__(self, doc_id: str, doc_ver: str) -> None:
45+
self.doc_id = doc_id
46+
self.doc_ver = doc_ver
47+
self.cid = "0x"
48+
49+
def to_json(self) -> dict:
50+
return {
51+
"id": self.doc_id,
52+
"ver": self.doc_ver,
53+
"cid": self.cid,
54+
}
55+
56+
4357
class SignedDocumentBase:
4458
def __init__(
4559
self,
@@ -53,9 +67,12 @@ def __init__(
5367
self.cat_id = cat_id
5468
self.key = key
5569

56-
def new_version(self) -> None:
70+
def doc_ref(self) -> DocumentRef:
71+
return DocumentRef(self.metadata["id"], self.metadata["ver"])
72+
73+
def new_doc_version(self) -> None:
5774
time.sleep(1)
58-
self.metadata["ver"] = uuid_v7()
75+
self.metadata["doc_ver"] = uuid_v7()
5976

6077

6178
class SignedDocument(SignedDocumentBase):
@@ -117,15 +134,19 @@ def build_and_sign(
117134

118135
def proposal_doc(
119136
content: dict[str, Any],
120-
proposal_form_template_doc: SignedDocumentBase,
121-
param_doc: SignedDocumentBase,
137+
proposal_form_template_doc: DocumentRef,
138+
param_ref: DocumentRef,
122139
rbac_chain: RBACChain,
140+
doc_id: str | None = None,
141+
doc_ver: str | None = None,
123142
) -> SignedDocument:
124143
metadata = __create_metadata(
125144
doc_type=DocType.proposal,
126145
content_type="application/json",
127146
template=proposal_form_template_doc,
128-
parameters=[param_doc],
147+
parameters=[param_ref],
148+
doc_id=doc_id,
149+
doc_ver=doc_ver,
129150
)
130151

131152
(cat_id, key) = rbac_chain.cat_id_for_role(RoleID.PROPOSER)
@@ -134,118 +155,171 @@ def proposal_doc(
134155

135156
def proposal_form_template_doc(
136157
content: dict[str, Any],
137-
param_doc: SignedDocumentBase,
158+
param_ref: DocumentRef,
138159
admin_key: AdminKey,
160+
doc_id: str | None = None,
161+
doc_ver: str | None = None,
139162
) -> SignedDocument:
140163
metadata = __create_metadata(
141164
doc_type=DocType.proposal_form_template,
142165
content_type="application/schema+json",
143-
parameters=[param_doc],
166+
parameters=[param_ref],
167+
doc_id=doc_id,
168+
doc_ver=doc_ver,
169+
)
170+
171+
return SignedDocument(metadata, content, admin_key.cat_id(), admin_key.key)
172+
173+
174+
def proposal_comment_form_template_doc(
175+
content: dict[str, Any],
176+
param_ref: DocumentRef,
177+
admin_key: AdminKey,
178+
doc_id: str | None = None,
179+
doc_ver: str | None = None,
180+
) -> SignedDocument:
181+
metadata = __create_metadata(
182+
doc_type=DocType.proposal_comment_form_template,
183+
content_type="application/schema+json",
184+
parameters=[param_ref],
185+
doc_id=doc_id,
186+
doc_ver=doc_ver,
144187
)
145188

146189
return SignedDocument(metadata, content, admin_key.cat_id(), admin_key.key)
147190

148191

149192
def category_parameters_doc(
150193
content: dict[str, Any],
151-
category_parameters_form_template_doc: SignedDocumentBase,
152-
param_doc: SignedDocumentBase,
194+
category_parameters_form_template_doc: DocumentRef,
195+
param_ref: DocumentRef,
153196
admin_key: AdminKey,
197+
doc_id: str | None = None,
198+
doc_ver: str | None = None,
154199
) -> SignedDocumentBase:
155200
metadata = __create_metadata(
156201
doc_type=DocType.category_parameters,
157202
content_type="application/json",
158203
template=category_parameters_form_template_doc,
159-
parameters=[param_doc],
204+
parameters=[param_ref],
205+
doc_id=doc_id,
206+
doc_ver=doc_ver,
160207
)
161208
return SignedDocument(metadata, content, admin_key.cat_id(), admin_key.key)
162209

163210

164211
def category_parameters_form_template_doc(
165212
content: dict[str, Any],
166-
param_doc: SignedDocumentBase,
213+
param_ref: DocumentRef,
167214
admin_key: AdminKey,
215+
doc_id: str | None = None,
216+
doc_ver: str | None = None,
168217
) -> SignedDocumentBase:
169218
metadata = __create_metadata(
170219
doc_type=DocType.category_parameters_form_template,
171220
content_type="application/schema+json",
172-
parameters=[param_doc],
221+
parameters=[param_ref],
222+
doc_id=doc_id,
223+
doc_ver=doc_ver,
173224
)
174225
return SignedDocument(metadata, content, admin_key.cat_id(), admin_key.key)
175226

176227

177228
def campaign_parameters_doc(
178229
content: dict[str, Any],
179-
campaign_parameters_form_template_doc: SignedDocumentBase,
180-
param_doc: SignedDocumentBase,
230+
campaign_parameters_form_template_doc: DocumentRef,
231+
param_ref: DocumentRef,
181232
admin_key: AdminKey,
233+
doc_id: str | None = None,
234+
doc_ver: str | None = None,
182235
) -> SignedDocumentBase:
183236
metadata = __create_metadata(
184237
doc_type=DocType.campaign_parameters,
185238
content_type="application/json",
186239
template=campaign_parameters_form_template_doc,
187-
parameters=[param_doc],
240+
parameters=[param_ref],
241+
doc_id=doc_id,
242+
doc_ver=doc_ver,
188243
)
189244
return SignedDocument(metadata, content, admin_key.cat_id(), admin_key.key)
190245

191246

192247
def campaign_parameters_form_template_doc(
193248
content: dict[str, Any],
194-
param_doc: SignedDocumentBase,
249+
param_ref: DocumentRef,
195250
admin_key: AdminKey,
251+
doc_id: str | None = None,
252+
doc_ver: str | None = None,
196253
) -> SignedDocumentBase:
197254
metadata = __create_metadata(
198255
doc_type=DocType.campaign_parameters_form_template,
199256
content_type="application/schema+json",
200-
parameters=[param_doc],
257+
parameters=[param_ref],
258+
doc_id=doc_id,
259+
doc_ver=doc_ver,
201260
)
202261
return SignedDocument(metadata, content, admin_key.cat_id(), admin_key.key)
203262

204263

205264
def brand_parameters_doc(
206265
content: dict[str, Any],
207-
brand_parameters_form_template_doc: SignedDocumentBase,
266+
brand_parameters_form_template_ref: DocumentRef,
208267
admin_key: AdminKey,
268+
doc_id: str | None = None,
269+
doc_ver: str | None = None,
209270
) -> SignedDocumentBase:
210271
metadata = __create_metadata(
211272
doc_type=DocType.brand_parameters,
212273
content_type="application/json",
213-
template=brand_parameters_form_template_doc,
274+
template=brand_parameters_form_template_ref,
275+
doc_id=doc_id,
276+
doc_ver=doc_ver,
214277
)
215278
return SignedDocument(metadata, content, admin_key.cat_id(), admin_key.key)
216279

217280

218-
def brand_parameters_form_template_doc(content: dict[str, Any], admin_key: AdminKey) -> SignedDocumentBase:
281+
def brand_parameters_form_template_doc(
282+
content: dict[str, Any],
283+
admin_key: AdminKey,
284+
doc_id: str | None = None,
285+
doc_ver: str | None = None,
286+
) -> SignedDocumentBase:
219287
metadata = __create_metadata(
220288
doc_type=DocType.brand_parameters_form_template,
221289
content_type="application/schema+json",
290+
doc_id=doc_id,
291+
doc_ver=doc_ver,
222292
)
223293
return SignedDocument(metadata, content, admin_key.cat_id(), admin_key.key)
224294

225295

226296
def __create_metadata(
227297
doc_type: DocType,
228298
content_type: str,
229-
template: SignedDocumentBase | None = None,
230-
parameters: list[SignedDocumentBase] | None = None,
299+
doc_id: str | None = None,
300+
doc_ver: str | None = None,
301+
template: DocumentRef | None = None,
302+
parameters: list[DocumentRef] | None = None,
231303
) -> dict[str, Any]:
232-
doc_id = uuid_v7()
304+
if doc_id is None and doc_ver is None:
305+
doc_id = uuid_v7()
306+
doc_ver = doc_id
307+
if doc_id is None:
308+
doc_id = uuid_v7()
309+
if doc_ver is None:
310+
doc_ver = uuid_v7()
233311

234312
metadata: dict[str, Any] = {
235313
"content-encoding": "br",
236314
"content-type": content_type,
237315
"id": doc_id,
238-
"ver": doc_id,
316+
"ver": doc_ver,
239317
"type": doc_type,
240318
}
241319

242320
if template is not None:
243-
metadata["template"] = {
244-
"id": template.metadata["id"],
245-
"ver": template.metadata["ver"],
246-
"cid": "0x",
247-
}
321+
metadata["template"] = template.to_json()
248322
if parameters is not None:
249-
metadata["parameters"] = [{"id": p.metadata["id"], "ver": p.metadata["ver"], "cid": "0x"} for p in parameters]
323+
metadata["parameters"] = [p.to_json() for p in parameters]
250324

251325
return metadata

‎docs/src/architecture/08_concepts/signed_doc/docs/brand_parameters.md‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -86,8 +86,13 @@ timestamp of when the document was created.
8686

8787
#### [`id`](../metadata.md#id) Validation
8888

89-
IF [`ver`](../metadata.md#ver) does not == [`id`](../metadata.md#id) then a document with
90-
[`id`](../metadata.md#id) and [`ver`](../metadata.md#ver) being equal *MUST* exist.
89+
The document ID validation is performed based on timestamp thresholds:
90+
91+
* If `future_threshold` is configured,
92+
the document [`id`](../metadata.md#id) cannot be too far in the future from the
93+
current time.
94+
* If `past_threshold` is configured, the document [`id`](../metadata.md#id) cannot be too far in the past from the
95+
current time.
9196

9297
### [`ver`](../metadata.md#ver)
9398

@@ -104,7 +109,15 @@ The first version of the document must set [`ver`](../metadata.md#ver) == [`id`]
104109

105110
#### [`ver`](../metadata.md#ver) Validation
106111

107-
The document version must always be >= the document ID.
112+
1. The document version must always be >= the document ID.
113+
2. IF [`ver`](../metadata.md#ver) does not == [`id`](../metadata.md#id)
114+
then a document with [`id`](../metadata.md#id) and [`ver`](../metadata.md#ver) being equal *MUST* exist.
115+
3. When a document with the same [`id`](../metadata.md#id) already exists,
116+
the new document's [`ver`](../metadata.md#ver) must be greater than
117+
the latest known submitted version for that [`id`](../metadata.md#id).
118+
4. When a document with the same [`id`](../metadata.md#id) already exists,
119+
the new document's [`type`](../metadata.md#type) must be the same as
120+
the latest known submitted document's [`type`](../metadata.md#type) for that [`id`](../metadata.md#id).
108121

109122
### [`template`](../metadata.md#template)
110123

‎docs/src/architecture/08_concepts/signed_doc/docs/brand_parameters_form_template.md‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,13 @@ timestamp of when the document was created.
9191

9292
#### [`id`](../metadata.md#id) Validation
9393

94-
IF [`ver`](../metadata.md#ver) does not == [`id`](../metadata.md#id) then a document with
95-
[`id`](../metadata.md#id) and [`ver`](../metadata.md#ver) being equal *MUST* exist.
94+
The document ID validation is performed based on timestamp thresholds:
95+
96+
* If `future_threshold` is configured,
97+
the document [`id`](../metadata.md#id) cannot be too far in the future from the
98+
current time.
99+
* If `past_threshold` is configured, the document [`id`](../metadata.md#id) cannot be too far in the past from the
100+
current time.
96101

97102
### [`ver`](../metadata.md#ver)
98103

@@ -109,7 +114,15 @@ The first version of the document must set [`ver`](../metadata.md#ver) == [`id`]
109114

110115
#### [`ver`](../metadata.md#ver) Validation
111116

112-
The document version must always be >= the document ID.
117+
1. The document version must always be >= the document ID.
118+
2. IF [`ver`](../metadata.md#ver) does not == [`id`](../metadata.md#id)
119+
then a document with [`id`](../metadata.md#id) and [`ver`](../metadata.md#ver) being equal *MUST* exist.
120+
3. When a document with the same [`id`](../metadata.md#id) already exists,
121+
the new document's [`ver`](../metadata.md#ver) must be greater than
122+
the latest known submitted version for that [`id`](../metadata.md#id).
123+
4. When a document with the same [`id`](../metadata.md#id) already exists,
124+
the new document's [`type`](../metadata.md#type) must be the same as
125+
the latest known submitted document's [`type`](../metadata.md#type) for that [`id`](../metadata.md#id).
113126

114127
## Payload
115128

‎docs/src/architecture/08_concepts/signed_doc/docs/campaign_parameters.md‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -87,8 +87,13 @@ timestamp of when the document was created.
8787

8888
#### [`id`](../metadata.md#id) Validation
8989

90-
IF [`ver`](../metadata.md#ver) does not == [`id`](../metadata.md#id) then a document with
91-
[`id`](../metadata.md#id) and [`ver`](../metadata.md#ver) being equal *MUST* exist.
90+
The document ID validation is performed based on timestamp thresholds:
91+
92+
* If `future_threshold` is configured,
93+
the document [`id`](../metadata.md#id) cannot be too far in the future from the
94+
current time.
95+
* If `past_threshold` is configured, the document [`id`](../metadata.md#id) cannot be too far in the past from the
96+
current time.
9297

9398
### [`ver`](../metadata.md#ver)
9499

@@ -105,7 +110,15 @@ The first version of the document must set [`ver`](../metadata.md#ver) == [`id`]
105110

106111
#### [`ver`](../metadata.md#ver) Validation
107112

108-
The document version must always be >= the document ID.
113+
1. The document version must always be >= the document ID.
114+
2. IF [`ver`](../metadata.md#ver) does not == [`id`](../metadata.md#id)
115+
then a document with [`id`](../metadata.md#id) and [`ver`](../metadata.md#ver) being equal *MUST* exist.
116+
3. When a document with the same [`id`](../metadata.md#id) already exists,
117+
the new document's [`ver`](../metadata.md#ver) must be greater than
118+
the latest known submitted version for that [`id`](../metadata.md#id).
119+
4. When a document with the same [`id`](../metadata.md#id) already exists,
120+
the new document's [`type`](../metadata.md#type) must be the same as
121+
the latest known submitted document's [`type`](../metadata.md#type) for that [`id`](../metadata.md#id).
109122

110123
### [`template`](../metadata.md#template)
111124

‎docs/src/architecture/08_concepts/signed_doc/docs/campaign_parameters_form_template.md‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,13 @@ timestamp of when the document was created.
9191

9292
#### [`id`](../metadata.md#id) Validation
9393

94-
IF [`ver`](../metadata.md#ver) does not == [`id`](../metadata.md#id) then a document with
95-
[`id`](../metadata.md#id) and [`ver`](../metadata.md#ver) being equal *MUST* exist.
94+
The document ID validation is performed based on timestamp thresholds:
95+
96+
* If `future_threshold` is configured,
97+
the document [`id`](../metadata.md#id) cannot be too far in the future from the
98+
current time.
99+
* If `past_threshold` is configured, the document [`id`](../metadata.md#id) cannot be too far in the past from the
100+
current time.
96101

97102
### [`ver`](../metadata.md#ver)
98103

@@ -109,7 +114,15 @@ The first version of the document must set [`ver`](../metadata.md#ver) == [`id`]
109114

110115
#### [`ver`](../metadata.md#ver) Validation
111116

112-
The document version must always be >= the document ID.
117+
1. The document version must always be >= the document ID.
118+
2. IF [`ver`](../metadata.md#ver) does not == [`id`](../metadata.md#id)
119+
then a document with [`id`](../metadata.md#id) and [`ver`](../metadata.md#ver) being equal *MUST* exist.
120+
3. When a document with the same [`id`](../metadata.md#id) already exists,
121+
the new document's [`ver`](../metadata.md#ver) must be greater than
122+
the latest known submitted version for that [`id`](../metadata.md#id).
123+
4. When a document with the same [`id`](../metadata.md#id) already exists,
124+
the new document's [`type`](../metadata.md#type) must be the same as
125+
the latest known submitted document's [`type`](../metadata.md#type) for that [`id`](../metadata.md#id).
113126

114127
### [`parameters`](../metadata.md#parameters)
115128

0 commit comments

Comments
 (0)