feat(rust/signed-doc): add new type DocType

rust/signed_doc/Cargo.toml

@@ -27,7 +27,8 @@ jsonschema = "0.28.3"
 jsonpath-rust = "0.7.5"
 futures = "0.3.31"
 ed25519-bip32 = "0.4.1" # used by the `mk_signed_doc` cli tool
-
+tracing = "0.1.40"
+thiserror = "2.0.11"
 
 [dev-dependencies]
 base64-url = "3.0.0"

rust/signed_doc/src/decode_context.rs

@@ -0,0 +1,24 @@
+//! Context used to pass in decoder for additional information.
+
+use catalyst_types::problem_report::ProblemReport;
+
+/// Compatibility policy
+#[allow(dead_code)]
+pub(crate) enum CompatibilityPolicy {
+ /// Silently allow obsoleted type conversions or non deterministic encoding.
+ Accept,
+ /// Allow but log Warnings for all obsoleted type conversions or non deterministic
+ /// encoding.
+ Warn,
+ /// Fail and update problem report when an obsolete type is encountered or the data is
+ /// not deterministically encoded.
+ Fail,
+}
+
+/// A context use to pass to decoder.
+pub(crate) struct DecodeContext<'r> {
+ /// Compatibility policy.
+ pub compatibility_policy: CompatibilityPolicy,
+ /// Problem report.
+ pub report: &'r mut ProblemReport,
+}

rust/signed_doc/src/doc_types/mod.rs

@@ -51,3 +51,5 @@ pub const PRIVATE_VOTE_TX_V2_UUID_TYPE: Uuid =
 /// Immutable ledger block `UuidV4` type.
 pub const IMMUTABLE_LEDGER_BLOCK_UUID_TYPE: Uuid =
  Uuid::from_u128(0xD9E7_E6CE_2401_4D7D_9492_F4F7_C642_41C3);
+/// Submission Action `UuidV4` type.
+pub const SUBMISSION_ACTION: Uuid = Uuid::from_u128(0x7892_7329_CFD9_4EA1_9C71_0E01_9B12_6A65);

rust/signed_doc/src/lib.rs

@@ -2,6 +2,7 @@
 
 mod builder;
 mod content;
+mod decode_context;
 pub mod doc_types;
 mod metadata;
 pub mod providers;
@@ -22,7 +23,9 @@ pub use catalyst_types::{
 };
 pub use content::Content;
 use coset::{CborSerializable, Header, TaggedCborSerializable};
-pub use metadata::{ContentEncoding, ContentType, DocumentRef, ExtraFields, Metadata, Section};
+pub use metadata::{
+ ContentEncoding, ContentType, DocType, DocumentRef, ExtraFields, Metadata, Section,
+};
 use minicbor::{decode, encode, Decode, Decoder, Encode};
 pub use signature::{CatalystId, Signatures};
 

rust/signed_doc/src/metadata/doc_type.rs

@@ -0,0 +1,333 @@
+//! Document Type.
+
+use std::fmt::{Display, Formatter};
+
+use catalyst_types::{
+ problem_report::ProblemReport,
+ uuid::{CborContext, Uuid, UuidV4},
+};
+use minicbor::{Decode, Decoder, Encode};
+use tracing::warn;
+
+use crate::{
+ decode_context::{CompatibilityPolicy, DecodeContext},
+ doc_types::{
+ COMMENT_DOCUMENT_UUID_TYPE, PROPOSAL_ACTION_DOCUMENT_UUID_TYPE,
+ PROPOSAL_DOCUMENT_UUID_TYPE, SUBMISSION_ACTION,
+ },
+};
+
+/// List of `UUIDv4` document type.
+#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct DocType(Vec<UuidV4>);
+
+/// `DocType` Errors.
+#[derive(Debug, Clone, thiserror::Error)]
+pub enum DocTypeError {
+ /// Invalid UUID.
+ #[error("Invalid UUID: {0}")]
+ InvalidUuid(Uuid),
+ /// `DocType` cannot be empty.
+ #[error("DocType cannot be empty")]
+ Empty,
+}
+
+impl DocType {
+ /// Get a list of `UUIDv4` document types.
+ #[must_use]
+ pub fn doc_types(&self) -> &Vec<UuidV4> {
+ &self.0
+ }
+}
+
+impl From<UuidV4> for DocType {
+ fn from(value: UuidV4) -> Self {
+ DocType(vec![value])
+ }
+}
+
+impl TryFrom<Uuid> for DocType {
+ type Error = DocTypeError;
+
+ fn try_from(value: Uuid) -> Result<Self, Self::Error> {
+ let uuid_v4 = UuidV4::try_from(value).map_err(|_| DocTypeError::InvalidUuid(value))?;
+ Ok(DocType(vec![uuid_v4]))
+ }
+}
+
+impl TryFrom<Vec<Uuid>> for DocType {
+ type Error = DocTypeError;
+
+ fn try_from(value: Vec<Uuid>) -> Result<Self, Self::Error> {
+ if value.is_empty() {
+ return Err(DocTypeError::Empty);
+ }
+
+ let converted = value
+ .into_iter()
+ .map(|u| UuidV4::try_from(u).map_err(|_| DocTypeError::InvalidUuid(u)))
+ .collect::<Result<Vec<UuidV4>, DocTypeError>>()?;
+
+ DocType::try_from(converted)
+ }
+}
+
+impl TryFrom<Vec<UuidV4>> for DocType {
+ type Error = DocTypeError;
+
+ fn try_from(value: Vec<UuidV4>) -> Result<Self, Self::Error> {
+ if value.is_empty() {
+ return Err(DocTypeError::Empty);
+ }
+ Ok(DocType(value))
+ }
+}
+
+impl Display for DocType {
+ fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), std::fmt::Error> {
+ write!(
+ f,
+ "[{}]",
+ self.0
+ .iter()
+ .map(UuidV4::to_string)
+ .collect::<Vec<_>>()
+ .join(", ")
+ )
+ }
+}
+
+// ; Document Type
+// document_type = [ 1* uuid_v4 ]
+// ; UUIDv4
+// uuid_v4 = #6.37(bytes .size 16)
+impl Decode<'_, DecodeContext<'_>> for DocType {
+ fn decode(
+ d: &mut Decoder, decode_context: &mut DecodeContext,
+ ) -> Result<Self, minicbor::decode::Error> {
+ const CONTEXT: &str = "DocType decoding";
+ let parse_uuid = |d: &mut Decoder| UuidV4::decode(d, &mut CborContext::Tagged);
+
+ match d.datatype()? {
+ minicbor::data::Type::Array => {
+ let len = d.array()?.ok_or_else(|| {
+ decode_context
+ .report
+ .other("Unable to decode array length", CONTEXT);
+ minicbor::decode::Error::message(format!(
+ "{CONTEXT}: Unable to decode array length"
+ ))
+ })?;
+
+ if len == 0 {
+ decode_context.report.invalid_value(
+ "array length",
+ "0",
+ "must contain at least one UUIDv4",
+ CONTEXT,
+ );
+ return Err(minicbor::decode::Error::message(format!(
+ "{CONTEXT}: empty array"
+ )));
+ }
+
+ (0..len)
+ .map(|_| parse_uuid(d))
+ .collect::<Result<Vec<_>, _>>()
+ .map(Self)
+ .map_err(|e| {
+ decode_context
+ .report
+ .other(&format!("Invalid UUIDv4 in array: {e}"), CONTEXT);
+ minicbor::decode::Error::message(format!(
+ "{CONTEXT}: Invalid UUIDv4 in array: {e}"
+ ))
+ })
+ },
+ minicbor::data::Type::Tag => {
+ // Handle single tagged UUID
+ match decode_context.compatibility_policy {
+ CompatibilityPolicy::Accept | CompatibilityPolicy::Warn => {
+ if matches!(
+ decode_context.compatibility_policy,
+ CompatibilityPolicy::Warn
+ ) {
+ warn!("{CONTEXT}: Conversion of document type single UUID to type DocType");
+ }
+
+ let uuid = parse_uuid(d).map_err(|e| {
+ let msg = format!("Cannot decode single UUIDv4: {e}");
+ decode_context.report.invalid_value(
+ "Decode single UUIDv4",
+ &e.to_string(),
+ &msg,
+ CONTEXT,
+ );
+ minicbor::decode::Error::message(format!("{CONTEXT}: {msg}"))
+ })?;
+
+ let ids = map_doc_type(uuid.into()).map_err(|e| {
+ decode_context.report.other(&e.to_string(), CONTEXT);
+ minicbor::decode::Error::message(format!("{CONTEXT}: {e}"))
+ })?;
+
+ let doc_type = ids.to_vec().try_into().map_err(|e: DocTypeError| {
+ decode_context.report.other(&e.to_string(), CONTEXT);
+ minicbor::decode::Error::message(format!("{CONTEXT}: {e}"))
+ })?;
+
+ Ok(doc_type)
+ },
+
+ CompatibilityPolicy::Fail => {
+ let msg = "Conversion of document type single UUID to type DocType is not allowed";
+ decode_context.report.other(msg, CONTEXT);
+ Err(minicbor::decode::Error::message(format!(
+ "{CONTEXT}: {msg}"
+ )))
+ },
+ }
+ },
+ other => {
+ decode_context.report.invalid_value(
+ "decoding type",
+ &format!("{other:?}"),
+ "array or tag cbor",
+ CONTEXT,
+ );
+ Err(minicbor::decode::Error::message(format!(
+ "{CONTEXT}: expected array of UUIDor tagged UUIDv4, got {other:?}",
+ )))
+ },
+ }
+ }
+}
+
+/// Map single UUID doc type to new list of doc types
+/// <https://github.com/input-output-hk/catalyst-libs/blob/main/docs/src/architecture/08_concepts/signed_doc/types.md#document-types>
+fn map_doc_type(uuid: Uuid) -> anyhow::Result<&'static [Uuid]> {
+ const PROPOSAL_DOC: &[Uuid] = &[PROPOSAL_DOCUMENT_UUID_TYPE];
+ const PROPOSAL_COMMENT_DOC: &[Uuid] =
+ &[COMMENT_DOCUMENT_UUID_TYPE, PROPOSAL_DOCUMENT_UUID_TYPE];
+ const PROPOSAL_ACTION_DOC: &[Uuid] = &[
+ PROPOSAL_ACTION_DOCUMENT_UUID_TYPE,
+ PROPOSAL_DOCUMENT_UUID_TYPE,
+ SUBMISSION_ACTION,
+ ];
+
+ match uuid {
+ id if id == PROPOSAL_DOCUMENT_UUID_TYPE => Ok(PROPOSAL_DOC),
+ id if id == COMMENT_DOCUMENT_UUID_TYPE => Ok(PROPOSAL_COMMENT_DOC),
+ id if id == PROPOSAL_ACTION_DOCUMENT_UUID_TYPE => Ok(PROPOSAL_ACTION_DOC),
+ _ => anyhow::bail!("Unknown document type: {uuid}"),
+ }
+}
+
+impl Encode<ProblemReport> for DocType {
+ fn encode<W: minicbor::encode::Write>(
+ &self, e: &mut minicbor::Encoder<W>, report: &mut ProblemReport,
+ ) -> Result<(), minicbor::encode::Error<W::Error>> {
+ const CONTEXT: &str = "DocType encoding";
+ if self.0.is_empty() {
+ report.invalid_value("DocType", "empty", "DocType cannot be empty", CONTEXT);
+ return Err(minicbor::encode::Error::message(format!(
+ "{CONTEXT}: DocType cannot be empty"
+ )));
+ }
+
+ e.array(self.0.len().try_into().map_err(|_| {
+ report.other("Unable to encode array length", CONTEXT);
+ minicbor::encode::Error::message(format!("{CONTEXT}, unable to encode array length"))
+ })?)?;
+
+ for id in &self.0 {
+ id.encode(e, &mut CborContext::Tagged).map_err(|_| {
+ report.other("Failed to encode UUIDv4", CONTEXT);
+ minicbor::encode::Error::message(format!("{CONTEXT}: UUIDv4 encoding failed"))
+ })?;
+ }
+ Ok(())
+ }
+}
+
+#[cfg(test)]
+mod tests {
+
+ use minicbor::Encoder;
+
+ use super::*;
+
+ // <https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/types/>
+ // Proposal Submission Action = 37(h'5e60e623ad024a1ba1ac406db978ee48') should map to
+ // [37(h'5e60e623ad024a1ba1ac406db978ee48'), 37(h'7808d2bad51140af84e8c0d1625fdfdc'),
+ // 37(h'78927329cfd94ea19c710e019b126a65')]
+ const PSA: &str = "D825505E60E623AD024A1BA1AC406DB978EE48";
+
+ #[test]
+ fn test_empty_doc_type() {
+ assert!(<DocType as TryFrom<Vec<UuidV4>>>::try_from(vec![]).is_err());
+
+ let mut report = ProblemReport::new("Test empty doc type");
+ let mut decoded_context = DecodeContext {
+ compatibility_policy: CompatibilityPolicy::Accept,
+ report: &mut report,
+ };
+ let mut decoder = Decoder::new(&[]);
+ assert!(DocType::decode(&mut decoder, &mut decoded_context).is_err());
+ }
+
+ #[test]
+ fn test_single_uuid_doc_type_fail_policy() {
+ let mut report = ProblemReport::new("Test single uuid doc type - fail");
+ let data = hex::decode(PSA).unwrap();
+ let decoder = Decoder::new(&data);
+ let mut decoded_context = DecodeContext {
+ compatibility_policy: CompatibilityPolicy::Fail,
+ report: &mut report,
+ };
+ assert!(DocType::decode(&mut decoder.clone(), &mut decoded_context).is_err());
+ }
+
+ #[test]
+ fn test_single_uuid_doc_type_warn_policy() {
+ let mut report = ProblemReport::new("Test single uuid doc type - warn");
+ let data = hex::decode(PSA).unwrap();
+ let decoder = Decoder::new(&data);
+ let mut decoded_context = DecodeContext {
+ compatibility_policy: CompatibilityPolicy::Warn,
+ report: &mut report,
+ };
+ let decoded_doc_type = DocType::decode(&mut decoder.clone(), &mut decoded_context).unwrap();
+ assert_eq!(decoded_doc_type.doc_types().len(), 3);
+ }
+
+ #[test]
+ fn test_single_uuid_doc_type_accept_policy() {
+ let mut report = ProblemReport::new("Test single uuid doc type - accept");
+ let data = hex::decode(PSA).unwrap();
+ let decoder = Decoder::new(&data);
+ let mut decoded_context = DecodeContext {
+ compatibility_policy: CompatibilityPolicy::Accept,
+ report: &mut report,
+ };
+ let decoded_doc_type = DocType::decode(&mut decoder.clone(), &mut decoded_context).unwrap();
+ assert_eq!(decoded_doc_type.doc_types().len(), 3);
+ }
+
+ #[test]
+ fn test_multi_uuid_doc_type() {
+ let uuidv4 = UuidV4::new();
+ let mut report = ProblemReport::new("Test multi uuid doc type");
+ let doc_type_list: DocType = vec![uuidv4, uuidv4].try_into().unwrap();
+ let mut buffer = Vec::new();
+ let mut encoder = Encoder::new(&mut buffer);
+ doc_type_list.encode(&mut encoder, &mut report).unwrap();
+ let mut decoder = Decoder::new(&buffer);
+ let mut decoded_context = DecodeContext {
+ compatibility_policy: CompatibilityPolicy::Accept,
+ report: &mut report.clone(),
+ };
+ let decoded_doc_type = DocType::decode(&mut decoder, &mut decoded_context).unwrap();
+ assert_eq!(decoded_doc_type, doc_type_list);
+ }
+}