change: ETCM-9687 Fixes and documentation for util crates (#793)

* change: ETCM-9687 Fixes and documentation for util crates

* allow deprecated

* change deprecation version

* simplify languge

* fix clippy warning

Author: AmbientTea

toolkit/data-sources/db-sync/src/db_model.rs

@@ -328,6 +328,7 @@ FROM block INNER JOIN block as stable_block ON block.block_no - $1 = stable_bloc
 WHERE block.block_no IS NOT NULL
 ORDER BY block.block_no DESC
 LIMIT 1";
+	#[allow(deprecated)]
 	Ok(sqlx::query_as::<_, EpochNumberRow>(sql)
 		.bind(BlockNumber(security_parameter))
 		.fetch_optional(pool)

toolkit/sidechain/primitives/src/lib.rs

@@ -11,7 +11,7 @@ use sidechain_domain::{ScEpochNumber, ScSlotNumber, UtxoId};
 mod tests;
 
 /// Information about current Partner Chain slot and epoch.
-#[deprecated(since = "1.8.0", note = "See deprecation notes for [GetSidechainStatus]")]
+#[deprecated(since = "1.7.0", note = "See deprecation notes for [GetSidechainStatus]")]
 #[derive(TypeInfo, Clone, Encode, Decode)]
 pub struct SidechainStatus {
 	/// current Partner Chain epoch
@@ -65,7 +65,7 @@ mod api_declarations {
 		}
 
 		/// Runtime API for getting information about current Partner Chain slot and epoch
-		#[deprecated(since = "1.8.0", note = "Code that needs this data should define its own runtime API instead.")]
+		#[deprecated(since = "1.7.0", note = "Code that needs this data should define its own runtime API instead.")]
 		pub trait GetSidechainStatus {
 			/// Returns current Partner Chain slot and epoch
 			fn get_sidechain_status() -> SidechainStatus;

toolkit/utils/byte-string-derivation/Cargo.toml

@@ -6,6 +6,7 @@ authors.workspace = true
 edition.workspace = true
 homepage.workspace = true
 repository.workspace = true
+description = "Proc macros for generating conversions for byte string wrapper types"
 
 [lib]
 proc-macro = true

toolkit/utils/byte-string-derivation/src/lib.rs

@@ -1,10 +1,57 @@
+//! Proc macros for generating conversions for byte string wrapper types.
+//! See documentation of [macro@byte_string] for more information.
 use proc_macro::TokenStream;
 use quote::ToTokens;
 use quote::quote;
 use syn::Generics;
 
 extern crate alloc;
 
+/// Proc macro that can generate multiple helper functions and traits for types that wrap an
+/// array, [Vec], or [BoundedVec] of bytes. What code is generated by the macro is controlled
+/// by passing the following arguments:
+/// - `debug`:
+///   implements [Debug] that uses hex to encode the bytes
+/// - `hex_serialize`:
+///   implements `serde::Serialize` that encode the bytes to a hex string as intermediate format.
+///   This implementation is useful for saving bytes in Json and similar formats.
+/// - `hex_deserialize`:
+///   implements `serde::Deserialize` that decodes the type from a string containig hex-encoded
+///   bytes. This implementation is useful for decoding hex data from Json and similar formats.
+/// - `from_num`:
+///   implements [`From<u64>`]
+/// - `from_bytes`:
+///   implements either [`From<&[u8]>`] or [`TryFrom<&[u8]`] depending on whether the the type
+///   can be infallibly ([Vec]) or fallibly (array, [BoundedVec]) cast from a byte slice.
+/// - `decode_hex`:
+///   adds functions `decode_hex` and `decode_hex_unsafe` that decode the type from a [&str]
+///   and a [FromStr] implementation equivalent to calling `decode_hex`.
+/// - `to_hex_string`:
+///   adds a function `to_hex_string` that returns the inner bytes as a hex string.
+/// - `as_ref`: generates [`AsRef<[u8]>`] implementation
+///
+/// _Note_: As the code generated by this macro is meant to be `no_std`-compatible, some of the
+///         options require `alloc` crate to be available in the scope where the code is generated.
+///
+/// # Example
+///
+/// ```rust
+/// extern crate alloc;
+/// use byte_string_derive::byte_string;
+/// use sp_core::{ ConstU32, bounded_vec::BoundedVec };
+///
+/// #[byte_string(debug, hex_serialize, hex_deserialize, from_num, from_bytes, decode_hex, to_hex_string, as_ref)]
+/// pub struct MyArrayBytes([u8; 32]);
+///
+/// #[byte_string(debug, hex_serialize, hex_deserialize, from_num, from_bytes, decode_hex, to_hex_string, as_ref)]
+/// pub struct MyVecBytes(Vec<u8>);
+///
+/// #[byte_string(from_bytes)]
+/// pub struct MyBoundedVecBytes(BoundedVec<u8, ConstU32<32>>);
+/// ```
+///
+/// [BoundedVec]: https://paritytech.github.io/polkadot-sdk/master/sp_core/bounded_vec/struct.BoundedVec.html
+/// [FromStr]: std::str::FromStr
 #[proc_macro_attribute]
 pub fn byte_string(attr: TokenStream, input: TokenStream) -> TokenStream {
 	let ast = syn::parse(input).expect("Cannot parse source");
@@ -182,7 +229,15 @@ fn gen_from_bytes(name: &syn::Ident, ty: &SupportedType, generics: &Generics) ->
 				}
 			}
 		},
-		_ => quote! {
+		SupportedType::BoundedVec(ty) => quote! {
+			impl<'a> TryFrom<&'a [u8]> for #name {
+				type Error = <#ty as TryFrom<Vec<u8>>>::Error;
+				fn try_from(bytes: &'a [u8]) -> Result<Self, Self::Error> {
+					Ok(#name(bytes.to_vec().try_into()?))
+				}
+			}
+		},
+		SupportedType::Vec => quote! {
 			impl #impl_generics From<&[u8]> for #name #ty_generics #where_clause {
 				fn from(bytes: &[u8]) -> Self {
 					#name(bytes.clone().to_vec())

toolkit/utils/db-sync-sqlx/src/lib.rs

@@ -1,3 +1,16 @@
+//! helpers and primitive types for querying Cardano [Db-Sync] data using [sqlx]
+//!
+//! # About
+//!
+//! This crate is meant to provide help when writing queries for data produced by [Db-Sync],
+//! a Cardano blockchain indexer. Db-Sync keeps the indexed data in a Postgre database that
+//! can be queried using SQL. This crate defines primitive types that correspond to column
+//! types used in the [Db-Sync schema], along with some other helpers and casts to types
+//! defined in [sidechain_domain].
+//!
+//! [sqlx]: https://github.com/launchbadge/sqlx
+//! [Db-Sync]: https://github.com/IntersectMBO/cardano-db-sync
+//! [Db-Sync schema]: https://github.com/IntersectMBO/cardano-db-sync/blob/master/doc/schema.md
 use num_traits::ToPrimitive;
 use sidechain_domain::*;
 use sqlx::database::Database;
@@ -6,11 +19,17 @@ use sqlx::error::BoxDynError;
 use sqlx::postgres::PgTypeInfo;
 use sqlx::*;
 
-/// Generates sqlx implementations for an unsigned wrapper of types that are signed.
-/// We expect that values will have always 0 as the most significant bit.
-/// For example TxIndex is in range of [0, 2^15-1], it will be u16 in domain,
-/// but it requires encoding and decoding like i16.
-/// See txindex, word31 and word63 types in db-sync schema definition.
+/// Macro to handle numeric types that are non-negative but are stored by Db-Sync using
+/// signed SQL types.
+///
+/// This macro generates an unsigned numeric domain type and sqlx trait implementation for
+/// decoding it from signed data coming from Db-Sync database. It expects that values will
+/// always have 0 as the most significant bit.
+///
+/// For example because [TxIndex] is in range of \[0, 2^15-1\], it will be [u16] in domain,
+/// but it requires encoding and decoding as i16.
+///
+/// See `txindex`, `word31` `and` word63 types in Db-Sync schema definition.
 #[macro_export]
 macro_rules! sqlx_implementations_for_wrapper {
 	($WRAPPED:ty, $DBTYPE:expr, $NAME:ty, $DOMAIN:ty) => {
@@ -62,28 +81,42 @@ macro_rules! sqlx_implementations_for_wrapper {
 	};
 }
 
+/// Cardano block number
 #[derive(Debug, Copy, Ord, PartialOrd, Clone, PartialEq, Eq)]
 pub struct BlockNumber(pub u32);
 sqlx_implementations_for_wrapper!(i32, "INT4", BlockNumber, McBlockNumber);
 
+/// Cardano epoch number
 #[derive(Debug, Copy, Clone, PartialEq)]
 pub struct EpochNumber(pub u32);
 sqlx_implementations_for_wrapper!(i32, "INT4", EpochNumber, McEpochNumber);
 
+/// Cardano slot number
 #[derive(Debug, Copy, Clone, PartialEq)]
 pub struct SlotNumber(pub u64);
 sqlx_implementations_for_wrapper!(i64, "INT8", SlotNumber, McSlotNumber);
 
+/// Index of a Cardano transaction output
+///
+/// This type corresponds to the following SQL type defined by Db-Sync.
+/// ```sql
 /// CREATE DOMAIN txindex AS smallint CONSTRAINT txindex_check CHECK ((VALUE >= 0));
+/// ```
 #[derive(Debug, Clone, PartialEq)]
 pub struct TxIndex(pub u16);
 sqlx_implementations_for_wrapper!(i16, "INT2", TxIndex, UtxoIndex);
 
+/// Index of a Cardano transaction with its block
 #[derive(Debug, Clone, Copy, PartialOrd, Ord, PartialEq, Eq)]
 pub struct TxIndexInBlock(pub u32);
 sqlx_implementations_for_wrapper!(i32, "INT4", TxIndexInBlock, McTxIndexInBlock);
 
+/// Number of ADA expressed in Lovelace (1 million-th of ADA)
+///
+/// This type corresponds to the following SQL type defined by Db-Sync.
+/// ```sql
 /// CREATE DOMAIN int65type AS numeric (20, 0) CHECK (VALUE >= -18446744073709551615 AND VALUE <= 18446744073709551615);
+/// ```
 #[derive(Debug, Clone, PartialEq)]
 pub struct TxValue(pub i128);
 
@@ -101,7 +134,12 @@ impl<'r> Decode<'r, Postgres> for TxValue {
 	}
 }
 
+/// Number of ADA delegated by a Cardano delegator to a single SPO, expressed in Lovelace (1 million-th of ADA)
+///
+/// This type corresponds to the following SQL type defined by Db-Sync.
+/// ```sql
 /// CREATE DOMAIN "lovelace" AS numeric(20,0) CONSTRAINT flyway_needs_this CHECK (VALUE >= 0::numeric AND VALUE <= '18446744073709551615'::numeric);
+/// ```
 #[derive(Debug, Clone, PartialEq)]
 pub struct StakeDelegation(pub u64);
 
@@ -119,6 +157,7 @@ impl<'r> Decode<'r, Postgres> for StakeDelegation {
 	}
 }
 
+/// Cardano native asset name, typically UTF-8 encoding of a human-readable name
 #[derive(Debug, Clone, sqlx::FromRow, PartialEq)]
 pub struct AssetName(pub Vec<u8>);
 
@@ -128,6 +167,7 @@ impl From<sidechain_domain::AssetName> for AssetName {
 	}
 }
 
+/// Cardano minting policy ID. This value is obtained by hashing the Plutus script of the policy.
 #[derive(Debug, Clone, sqlx::FromRow, PartialEq)]
 pub struct PolicyId(pub Vec<u8>);
 
@@ -137,9 +177,12 @@ impl From<sidechain_domain::PolicyId> for PolicyId {
 	}
 }
 
+/// Full identifier of a Cardano native asset
 #[derive(Debug, Clone, sqlx::FromRow, PartialEq)]
 pub struct Asset {
+	/// Minting policy ID of the asset
 	pub policy_id: PolicyId,
+	/// Asset name
 	pub asset_name: AssetName,
 }
 
@@ -156,15 +199,27 @@ impl From<sidechain_domain::AssetId> for Asset {
 	}
 }
 
-#[derive(Debug, Copy, Clone, sqlx::FromRow, PartialEq)]
-pub struct EpochNumberRow(pub EpochNumber);
-
-impl From<EpochNumberRow> for EpochNumber {
-	fn from(r: EpochNumberRow) -> Self {
-		r.0
+/// Helper row type for querying just epoch number
+#[allow(deprecated)]
+mod epoch_number_row {
+	use super::*;
+	#[deprecated(
+		since = "1.7.0",
+		note = "Deprecated due to not being either a primitive type or a complete Db-Sync table row."
+	)]
+	#[derive(Debug, Copy, Clone, sqlx::FromRow, PartialEq)]
+	pub struct EpochNumberRow(pub EpochNumber);
+
+	#[allow(deprecated)]
+	impl From<EpochNumberRow> for EpochNumber {
+		fn from(r: EpochNumberRow) -> Self {
+			r.0
+		}
 	}
 }
+pub use epoch_number_row::*;
 
+/// Cardano address in human-readable form. Either Base58 for Byron addresses and Bech32 for Shelley.
 #[derive(Debug, Clone, sqlx::FromRow, PartialEq)]
 pub struct Address(pub String);
 
@@ -174,5 +229,8 @@ impl From<MainchainAddress> for Address {
 	}
 }
 
+/// Cardano epoch nonce, ie. random 32 bytes generated by Cardano every epoch.
+///
+/// This value can be used as a tamper-proof randomness seed.
 #[derive(Debug, Clone, sqlx::FromRow, PartialEq)]
 pub struct MainchainEpochNonce(pub Vec<u8>);

toolkit/utils/plutus/src/lib.rs

@@ -1,30 +1,68 @@
+//! Minimal Plutus data types and encoding implementation
+//!
+//! This crate implements the `Data` type used by [Untyped Plutus Core], a low-level language
+//! used by Cardano smart contracts, along with traits for encoding Rust types as Plutus data
+//! and Plutus data CBOR bytes.
+//!
+//! This crate is developed as part of the [Partner Chains toolkit] for use in [no_std] contexts
+//! where existing alternatives ([uplc], [cardano-serialization-lib]) can not be used, and as
+//! such is not intended to be feature-complete for general use.
+//!
+//! [Untyped Plutus Core]: https://plutonomicon.github.io/plutonomicon/uplc
+//! [Partner Chains toolkit]: https://github.com/input-output-hk/partner-chains
+//! [no_std]: https://doc.rust-lang.org/reference/names/preludes.html?highlight=no_std#r-names.preludes.extern.no_std
+//! [uplc]: https://github.com/aiken-lang/aiken/tree/main/crates/uplc
+//! [cardano-serialization-lib]: https://github.com/Emurgo/cardano-serialization-lib
 #![no_std]
+#![deny(missing_docs)]
 
 mod cbor;
 
 extern crate alloc;
 
 use crate::Datum::*;
+#[doc(hidden)]
 pub use alloc::{vec, vec::Vec};
 use core::fmt::{Debug, Formatter};
 use num_bigint::BigInt;
 
+/// Plutus datum type
 #[derive(Clone, PartialEq)]
 pub enum Datum {
+	/// Integer value
 	IntegerDatum(BigInt),
+	/// Byte string value
 	ByteStringDatum(Vec<u8>),
-	ConstructorDatum { constructor: u64, fields: Vec<Datum> },
+	/// Constructor value
+	///
+	/// A Plutus constructor datum consists of an ordered list of Plutus field values together
+	/// with numeric constructor ID that marks the constructor variant used. These can only be
+	/// interpreted against an external schema that specifies expected content of `fields` and
+	/// their interpretation.
+	ConstructorDatum {
+		/// Constructor variant number
+		constructor: u64,
+		/// List of field values
+		fields: Vec<Datum>,
+	},
+	/// List of values
 	ListDatum(Vec<Datum>),
+	/// Key-value mapping
 	MapDatum(Vec<MapDatumEntry>),
 }
 
+/// Key-value pair stored in [Datum::MapDatum]
 #[derive(Clone, Debug, PartialEq)]
 pub struct MapDatumEntry {
+	/// Key
 	key: Datum,
+	/// Value
 	value: Datum,
 }
 
+/// Trait for types that can be encoded as a Plutus [Datum].
 pub trait ToDatum {
+	/// Encodes `self` to [Datum].
 	fn to_datum(&self) -> Datum;
 }
 
@@ -81,6 +119,7 @@ impl Datum {
 		IntegerDatum(BigInt::from(value))
 	}
 
+	/// Returns byte content if `self` is a [Datum::ByteStringDatum] and [None] otherwise.
 	pub fn as_bytestring(&self) -> Option<&Vec<u8>> {
 		match self {
 			ByteStringDatum(bytes) => Some(bytes),
@@ -118,9 +157,13 @@ impl Debug for Datum {
 	}
 }
 
-// tip: this function accepts Option<T> for any T: Datum
-//      so it's better to call it with explicit type to avoid hard to
-//      find bugs when types change
+/// Encodes a message as a Plutus [Datum] and returns [CBOR] encoding of this datum.
+///
+/// tip: this function accepts `Option<T>` for any `T: Datum`
+///      so it's better to call it with explicit type to avoid hard to
+///      find bugs when types change
+///
+/// [CBOR]: https://cbor.io
 pub fn to_datum_cbor_bytes<T: ToDatum>(msg: T) -> Vec<u8> {
 	minicbor::to_vec(msg.to_datum()).expect("Infallible error type never fails")
 }