Documentation and test example

examples/async/examples/compose_extrinsic.rs

@@ -28,7 +28,7 @@ use substrate_api_client::{
 		GenericAdditionalParams, SignExtrinsic,
 	},
 	rpc::JsonrpseeClient,
-	Api, GetChainInfo, SubmitAndWatch, XtStatus,
+	Api, GetChainInfo, SubmitAndWatch, TransactionStatusDeterminant, XtStatus,
 };
 
 type AssetExtrinsicSigner = <AssetRuntimeConfig as Config>::ExtrinsicSigner;
@@ -139,7 +139,10 @@ async fn main() {
 
 	println!("[+] Composed Extrinsic:\n {:?}", xt);
 	let hash = api
-		.submit_and_watch_extrinsic_until(xt, XtStatus::InBlock)
+		.submit_and_watch_opaque_extrinsic_until_final(
+			xt.encode().into(),
+			&[TransactionStatusDeterminant::InBlock],
+		)
 		.await
 		.unwrap()
 		.block_hash

src/api/mod.rs

@@ -85,28 +85,17 @@ pub enum UnexpectedTxStatus {
 	Invalid,
 }
 
+/// See `TransactionStatus` for a description of the different enum values
 pub enum TransactionStatusDeterminant {
-	/// Transaction is part of the future queue.
 	Future,
-	/// Transaction is part of the ready queue.
 	Ready,
-	/// The transaction has been broadcast to the given peers.
 	Broadcast,
-	/// Transaction has been included in block with given hash.
 	InBlock,
-	/// The block this transaction was included in has been retracted.
 	Retracted,
-	/// Maximum number of finality watchers has been reached,
-	/// old watchers are being removed.
 	FinalityTimeout,
-	/// Transaction has been finalized by a finality-gadget, e.g GRANDPA
 	Finalized,
-	/// Transaction has been replaced in the pool, by another transaction
-	/// that provides the same tags. (e.g. same (sender, nonce)).
 	Usurped,
-	/// Transaction has been dropped from the pool because of the limit.
 	Dropped,
-	/// Transaction is no longer valid in the current state.
 	Invalid,
 }
 

src/api/rpc_api/author.rs

@@ -213,6 +213,10 @@ pub trait SubmitAndWatch {
 		watch_until: XtStatus,
 	) -> Result<ExtrinsicReport<Self::Hash>>;
 
+	/// Submit the extrinsic and watch it until it reaches one of the `expected_status`.
+	/// The method also returns if the transaction reaches a final state (regardless of contents of `expected_status`)
+	///
+	/// This method is blocking if the sync-api feature is activated
 	async fn submit_and_watch_extrinsic_until_status<Address, Call, Signature, SignedExtra>(
 		&self,
 		extrinsic: UncheckedExtrinsicV4<Address, Call, Signature, SignedExtra>,
@@ -224,6 +228,7 @@ pub trait SubmitAndWatch {
 		Signature: Encode,
 		SignedExtra: Encode;
 
+	/// Query the events for the specified `report` and attach them.
 	async fn populate_events(
 		&self,
 		report: ExtrinsicReport<Self::Hash>,