change: ETCM-9687 document smart-contracts/offchain (#796)

Author: kpinter-iohk

toolkit/partner-chains-cli/src/prepare_configuration/init_governance.rs

@@ -13,7 +13,7 @@ use partner_chains_cardano_offchain::{
 use sidechain_domain::{MainchainKeyHash, McTxHash, UtxoId};
 
 pub(crate) fn run_init_governance<C: IOContext>(
-	retries: FixedDelayRetries,
+	await_tx: FixedDelayRetries,
 	genesis_utxo: UtxoId,
 	payment_key: &CardanoPaymentSigningKey,
 	ogmios_config: &ServiceConfig,
@@ -32,7 +32,7 @@ pub(crate) fn run_init_governance<C: IOContext>(
 		let runtime = tokio::runtime::Runtime::new().map_err(|e| anyhow::anyhow!(e))?;
 		let tx_id = runtime
 			.block_on(offchain.init_governance(
-				retries,
+				await_tx,
 				&multisig_parameters,
 				&payment_key,
 				genesis_utxo,

toolkit/partner-chains-cli/src/setup_main_chain_state/mod.rs

@@ -169,7 +169,7 @@ fn print_on_chain_d_parameter<C: IOContext>(
 }
 
 fn set_candidates_on_main_chain<C: IOContext>(
-	retries: FixedDelayRetries,
+	await_tx: FixedDelayRetries,
 	context: &C,
 	offchain: &C::Offchain,
 	candidates: SortedPermissionedCandidates,
@@ -184,7 +184,7 @@ fn set_candidates_on_main_chain<C: IOContext>(
 		let tokio_runtime = tokio::runtime::Runtime::new().map_err(|e| anyhow::anyhow!(e))?;
 		let result = tokio_runtime
 			.block_on(offchain.upsert_permissioned_candidates(
-				retries,
+				await_tx,
 				genesis_utxo,
 				&candidates.0,
 				&pkey,
@@ -210,7 +210,7 @@ fn set_candidates_on_main_chain<C: IOContext>(
 }
 
 fn set_d_parameter_on_main_chain<C: IOContext>(
-	retries: FixedDelayRetries,
+	await_tx: FixedDelayRetries,
 	context: &C,
 	offchain: &C::Offchain,
 	default_d_parameter: DParameter,
@@ -237,7 +237,7 @@ fn set_d_parameter_on_main_chain<C: IOContext>(
 			sidechain_domain::DParameter { num_permissioned_candidates, num_registered_candidates };
 		let tokio_runtime = tokio::runtime::Runtime::new().map_err(|e| anyhow::anyhow!(e))?;
 		let result = tokio_runtime.block_on(offchain.upsert_d_param(
-			retries,
+			await_tx,
 			genesis_utxo,
 			&d_parameter,
 			&payment_signing_key,

toolkit/smart-contracts/commands/src/assemble_tx.rs

@@ -1,5 +1,5 @@
 use crate::transaction_submitted_json;
-use partner_chains_cardano_offchain::assemble_tx::assemble_tx;
+use partner_chains_cardano_offchain::assemble_and_submit_tx::assemble_and_submit_tx;
 use partner_chains_cardano_offchain::csl::{transaction_from_bytes, vkey_witness_from_bytes};
 use sidechain_domain::{TransactionCbor, VKeyWitnessCbor};
 
@@ -29,8 +29,13 @@ impl AssembleAndSubmitCmd {
 			.map(|w| vkey_witness_from_bytes(w.0.clone().into_iter().skip(2).collect()))
 			.collect::<Result<Vec<_>, _>>()?;
 
-		let tx_hash =
-			assemble_tx(transaction, witnesses, &client, &self.common_arguments.retries()).await?;
+		let tx_hash = assemble_and_submit_tx(
+			transaction,
+			witnesses,
+			&client,
+			&self.common_arguments.retries(),
+		)
+		.await?;
 		Ok(transaction_submitted_json(tx_hash))
 	}
 }

toolkit/smart-contracts/offchain/src/assemble_tx.rs renamed to toolkit/smart-contracts/offchain/src/assemble_and_submit_tx.rs

@@ -1,4 +1,4 @@
-use crate::await_tx::{AwaitTx, FixedDelayRetries};
+use crate::await_tx::AwaitTx;
 use anyhow::anyhow;
 use cardano_serialization_lib::{Transaction, Vkeywitness, Vkeywitnesses};
 use ogmios_client::query_ledger_state::QueryUtxoByUtxoId;
@@ -7,28 +7,8 @@ use ogmios_client::{
 };
 use sidechain_domain::{McTxHash, UtxoId};
 
-pub trait AssembleTx {
-	#[allow(async_fn_in_trait)]
-	async fn assemble_tx(
-		&self,
-		retries: &FixedDelayRetries,
-		transaction: Transaction,
-		witnesses: Vec<Vkeywitness>,
-	) -> anyhow::Result<McTxHash>;
-}
-
-impl<C: QueryLedgerState + QueryNetwork + Transactions + QueryUtxoByUtxoId> AssembleTx for C {
-	async fn assemble_tx(
-		&self,
-		retries: &FixedDelayRetries,
-		transaction: Transaction,
-		witnesses: Vec<Vkeywitness>,
-	) -> anyhow::Result<McTxHash> {
-		assemble_tx(transaction, witnesses, self, retries).await
-	}
-}
-
-pub async fn assemble_tx<
+/// Adds `witnesses` to `transaction` and submits it with `ogmios_client`.
+pub async fn assemble_and_submit_tx<
 	C: QueryLedgerState + QueryNetwork + Transactions + QueryUtxoByUtxoId,
 	A: AwaitTx,
 >(

toolkit/smart-contracts/offchain/src/await_tx.rs

@@ -4,40 +4,46 @@ use sidechain_domain::UtxoId;
 use std::time::Duration;
 use tokio_retry::{Retry, strategy::FixedInterval};
 
+/// Trait for different strategies of waiting for a Cardano transaction to complete.
 pub trait AwaitTx {
 	#[allow(async_fn_in_trait)]
-	async fn await_tx_output<Q: QueryUtxoByUtxoId>(
+	/// This is used for waiting until the output of a submitted transaction can be observed.
+	/// TODO: make this take a Transaction ID instead of a UtxoId
+	async fn await_tx_output<C: QueryUtxoByUtxoId>(
 		&self,
-		query: &Q,
+		client: &C,
 		utxo_id: UtxoId,
 	) -> anyhow::Result<()>;
 }
 
+/// Transaction awaiting strategy that uses fixed number of retries and a fixed delay.
 pub struct FixedDelayRetries {
 	delay: Duration,
 	retries: usize,
 }
 
 impl FixedDelayRetries {
+	/// Constructs [FixedDelayRetries] with `delay` [Duration] and `retries` number of maximum retries.
 	pub fn new(delay: Duration, retries: usize) -> Self {
 		Self { delay, retries }
 	}
 
+	/// Constructs [FixedDelayRetries] that keeps retrying every 5 seconds for 5 minutes.
 	pub fn five_minutes() -> Self {
 		Self { delay: Duration::from_secs(5), retries: 59 }
 	}
 }
 
 impl AwaitTx for FixedDelayRetries {
-	async fn await_tx_output<Q: QueryUtxoByUtxoId>(
+	async fn await_tx_output<C: QueryUtxoByUtxoId>(
 		&self,
-		query: &Q,
+		client: &C,
 		utxo_id: UtxoId,
 	) -> anyhow::Result<()> {
 		let strategy = FixedInterval::new(self.delay).take(self.retries);
 		let _ = Retry::spawn(strategy, || async {
 			log::info!("Probing for transaction output '{}'", utxo_id);
-			let utxo = query.query_utxo_by_id(utxo_id).await.map_err(|_| ())?;
+			let utxo = client.query_utxo_by_id(utxo_id).await.map_err(|_| ())?;
 			utxo.ok_or(())
 		})
 		.await

toolkit/smart-contracts/offchain/src/cardano_keys.rs

@@ -2,33 +2,37 @@ use anyhow::anyhow;
 use cardano_serialization_lib::{PrivateKey, PublicKey};
 use sidechain_domain::MainchainKeyHash;
 
-/// Signing (payment) key abstraction layer. Hides internal crytpo library details.
+/// Signing (payment) wrapper layer. Hides internal crypto library details.
 /// It is either:
-/// * 32 bytes regural private key
+/// * 32 bytes regular private key
 /// * 64 bytes extended private key
 pub struct CardanoPaymentSigningKey(pub(crate) PrivateKey);
 
 impl CardanoPaymentSigningKey {
+	/// Constructs [CardanoPaymentSigningKey] from 128 byte extended payment signing key.
+	/// The 128 bytes of the key are: 64 byte prefix, 32 byte verification key, 32 byte chain code
 	pub fn from_extended_128_bytes(bytes: [u8; 128]) -> anyhow::Result<Self> {
-		// All 128 bytes are: 64 bytes of prefix, 32 bytes of verification key, 32 bytes of chain code
 		let prefix: [u8; 64] = bytes[0..64].try_into().unwrap();
 		Ok(Self(
 			PrivateKey::from_extended_bytes(&prefix)
 				.map_err(|e| anyhow!("Couldn't parse 128 bytes into a BIP32 Private Key: {e}"))?,
 		))
 	}
 
+	/// Constructs [CardanoPaymentSigningKey] from 32 byte payment signing key.
 	pub fn from_normal_bytes(bytes: [u8; 32]) -> Result<Self, anyhow::Error> {
 		Ok(Self(
 			PrivateKey::from_normal_bytes(&bytes)
 				.map_err(|e| anyhow!("Couldn't parse 32 bytes into a Private Key: {e}"))?,
 		))
 	}
 
+	/// Signs `message` with the [CardanoPaymentSigningKey].
 	pub fn sign(&self, message: &[u8]) -> Result<Vec<u8>, anyhow::Error> {
 		Ok(self.0.sign(message).to_bytes())
 	}
 
+	/// Hashes [CardanoPaymentSigningKey] to domain type [MainchainKeyHash].
 	pub fn to_pub_key_hash(&self) -> MainchainKeyHash {
 		MainchainKeyHash(
 			self.0
@@ -41,10 +45,12 @@ impl CardanoPaymentSigningKey {
 		)
 	}
 
+	/// Converts [CardanoPaymentSigningKey] to CSL [PublicKey].
 	pub fn to_csl_pub_key(&self) -> PublicKey {
 		self.0.to_public()
 	}
 
+	/// Returns raw bytes of [CardanoPaymentSigningKey].
 	pub fn to_bytes(&self) -> Vec<u8> {
 		self.0.as_bytes()
 	}
@@ -81,12 +87,18 @@ impl Clone for CardanoPaymentSigningKey {
 
 #[derive(serde::Serialize, serde::Deserialize, Debug, Clone)]
 #[serde(rename_all = "camelCase")]
+/// Type representing Cardano key file.
+///
+/// Note: Field names are used for serialization, do not rename.
 pub struct CardanoKeyFileContent {
+	/// Type of the Cardano key.
 	pub r#type: String,
+	/// CBOR hex of the key.
 	pub cbor_hex: String,
 }
 
 impl CardanoKeyFileContent {
+	/// Parses file to [CardanoKeyFileContent].
 	pub fn parse_file(path: &str) -> anyhow::Result<Self> {
 		let file_content = std::fs::read_to_string(path)
 			.map_err(|e| anyhow!("Could not read Cardano key file at: {path}. Cause: {e}"))?;