Updated crate documentation (#23)

* feat: update documentation

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "omni-transaction"
-version = "0.1.3"
+version = "0.2.0"
 authors = ["Proximity Labs Limited"]
 license = "Apache-2.0"
 edition = "2021"

src/bitcoin/bitcoin_transaction.rs

@@ -12,6 +12,58 @@ use super::{
     },
 };
 
+///
+/// ###### Example:
+///
+/// You can create a Bitcoin transaction directly in your NEAR contract or Rust client
+/// or you can do it from a JSON.
+///
+/// ```rust
+/// // The first case would be as follows:
+/// let omni_tx = BitcoinTransaction {
+///     version: Version::One,
+///     lock_time: LockTime::from_height(1000000).unwrap(),
+///     input: vec![TxIn {
+///         previous_output: OutPoint {
+///             txid: Txid(Hash::all_zeros()),
+///             vout: 0,
+///         },
+///         script_sig: ScriptBuf::default(),
+///         sequence: Sequence::default(),
+///         witness: Witness::default(),
+///     }],
+///    output: vec![TxOut {
+///        value: Amount::from_sat(10000),
+///         script_pubkey: ScriptBuf::default(),
+///    }],
+/// };
+///
+/// // If you prefer to do it from a JSON:
+/// let json_value = r#"
+/// {
+///     "version": "1",
+///     "lock_time": "0",
+///     "input": [{
+///         "previous_output": {
+///             "txid": "bc25cc0dddd0a202c21e66521a692c0586330a9a9dcc38ccd9b4d2093037f31a",
+///             "vout": 0
+///         },
+///         "script_sig": [],
+///         "sequence": 4294967295,
+///         "witness": []
+///    }],s
+///     "output": [{
+///         "value": 1,
+///         "script_pubkey": "76a9148356ecd5f1761e60c144dc2f4de6bf7d8be7690688ad"
+///     },   
+///     {
+///         "value": 2649,
+///         "script_pubkey": "76a9148356ecd5f1761e60c144dc2f4de6bf7d8be7690688ac"
+///    }]
+/// }
+/// "#;
+/// let tx = BitcoinTransaction::from_json(json_value).unwrap();
+///
 #[derive(
     Debug,
     Clone,
@@ -48,7 +100,7 @@ fn sha256d(data: &[u8]) -> Vec<u8> {
 }
 
 impl BitcoinTransaction {
-    // Common
+    /// Encode the transaction into a vector of bytes
     pub fn serialize(&self) -> Vec<u8> {
         let mut buffer = Vec::new();
 
@@ -57,7 +109,7 @@ impl BitcoinTransaction {
         buffer
     }
 
-    // Legacy
+    /// Encode a legacy transaction into a vector of bytes
     pub fn build_for_signing_legacy(&self, sighash_type: EcdsaSighashType) -> Vec<u8> {
         let mut buffer = Vec::new();
 
@@ -69,6 +121,7 @@ impl BitcoinTransaction {
         buffer
     }
 
+    /// Attach a script sig to the transaction
     pub fn build_with_script_sig(
         &mut self,
         input_index: usize,
@@ -90,7 +143,7 @@ impl BitcoinTransaction {
         buffer
     }
 
-    // Segwit
+    /// Encode the transaction for signing in SegWit format
     pub fn build_for_signing_segwit(
         &self,
         sighash_type: EcdsaSighashType,
@@ -112,6 +165,7 @@ impl BitcoinTransaction {
         buffer
     }
 
+    /// Function to attach a witness to the transaction
     pub fn build_with_witness(
         &mut self,
         input_index: usize,
@@ -206,6 +260,7 @@ impl BitcoinTransaction {
         self.input.is_empty()
     }
 
+    /// Serialise a JSON representation of the transaction into a BitcoinTransaction struct
     pub fn from_json(json: &str) -> Result<Self, near_sdk::serde_json::Error> {
         let tx: Self = near_sdk::serde_json::from_str(json)?;
         Ok(tx)
@@ -437,7 +492,6 @@ mod tests {
         };
 
         let serialized = omni_tx.build_for_signing_legacy(OmniSighashType::All);
-        println!("serialized BTC Omni: {:?}", serialized);
 
         assert_eq!(buffer.len(), serialized.len());
         assert_eq!(buffer, serialized);

src/bitcoin/bitcoin_transaction_builder.rs

@@ -1,3 +1,4 @@
+//! Transaction builder for Bitcoin transactions
 use super::{
     bitcoin_transaction::BitcoinTransaction,
     types::{LockTime, TxIn, TxOut, Version},

src/bitcoin/encoding/mod.rs

@@ -6,5 +6,5 @@ pub mod utils;
 
 pub use decode::Decodable;
 pub use encode::Encodable;
-pub use extensions::{ReadExt, WriteExt};
-pub use utils::{encode_with_size, ToU64};
+pub use extensions::ReadExt;
+pub use utils::ToU64;

src/bitcoin/mod.rs

@@ -1,6 +1,12 @@
-pub mod bitcoin_transaction;
-pub mod bitcoin_transaction_builder;
-pub mod constants;
-pub mod encoding;
+//! Transaction builder, encoders, types and utilities for Bitcoin.
+mod bitcoin_transaction;
+mod bitcoin_transaction_builder;
+mod constants;
+mod encoding;
 pub mod types;
 pub mod utils;
+
+/// Bitcoin transaction
+pub use bitcoin_transaction::BitcoinTransaction;
+/// Bitcoin transaction builder
+pub use bitcoin_transaction_builder::BitcoinTransactionBuilder;

src/bitcoin/types/mod.rs

@@ -1,4 +1,4 @@
-/// Minimal required Bitcoin types, inspired by <https://github.com/rust-bitcoin/rust-bitcoin>
+//! Minimal required Bitcoin types, inspired by <https://github.com/rust-bitcoin/rust-bitcoin>
 mod lock_time;
 mod script_buf;
 mod sighash;

src/bitcoin/utils.rs

@@ -1,3 +1,4 @@
+//! Utility functions for serialization and encoding of Bitcoin data structures
 fn encode_signature_as_der(signature_bytes: &[u8]) -> Vec<u8> {
     assert_eq!(
         signature_bytes.len(),
@@ -32,6 +33,7 @@ fn encode_asn1_integer(bytes: &[u8]) -> Vec<u8> {
     result
 }
 
+/// Build the scriptSig from the DER signature and the public key
 pub fn build_script_sig(der_signature: &[u8], public_key_bytes: &[u8]) -> Vec<u8> {
     let mut script_sig = vec![];
     script_sig.push(der_signature.len() as u8);
@@ -43,6 +45,7 @@ pub fn build_script_sig(der_signature: &[u8], public_key_bytes: &[u8]) -> Vec<u8
     script_sig
 }
 
+/// Serialize the ECDSA signature from the raw bytes and the SIGHASH type
 pub fn serialize_ecdsa_signature(signature_bytes: &[u8], sighash_type: u8) -> Vec<u8> {
     // 1. Encode the signature as DER format
     let mut der_signature = encode_signature_as_der(signature_bytes);
@@ -53,6 +56,7 @@ pub fn serialize_ecdsa_signature(signature_bytes: &[u8], sighash_type: u8) -> Ve
     der_signature
 }
 
+/// Serialize the ECDSA signature from string representations of big R and S
 pub fn serialize_ecdsa_signature_from_str(big_r: &str, s: &str) -> Vec<u8> {
     // Generate the signature bytes from the hex strings
     let big_r_bytes = hex::decode(big_r).unwrap();

src/evm/evm_transaction.rs

@@ -1,3 +1,4 @@
+//! EVM transaction
 use near_sdk::serde::{Deserialize, Serialize};
 use rlp::RlpStream;
 use schemars::JsonSchema;
@@ -7,6 +8,31 @@ use crate::constants::EIP_1559_TYPE;
 use super::types::{AccessList, Address, Signature};
 use super::utils::parse_eth_address;
 
+///
+/// ###### Example:
+///
+/// ```rust
+/// let nonce: u64 = 0;
+/// let to: Address = address!("d8dA6BF26964aF9D7eEd9e03E53415D37aA96045");
+/// let value = 10000000000000000u128; // 0.01 ETH
+/// let data: Vec<u8> = vec![];
+/// let chain_id = 1;
+/// let to_address_str = "d8dA6BF26964aF9D7eEd9e03E53415D37aA96045";
+/// let to_address = Some(parse_eth_address(to_address_str));
+/// // Generate using EVMTransaction
+/// let tx = EVMTransaction {
+///     chain_id,
+///     nonce,
+///     to: to_address,
+///     value,
+///     input: data.clone(),
+///     gas_limit: GAS_LIMIT,
+///     max_fee_per_gas: MAX_FEE_PER_GAS,
+///     max_priority_fee_per_gas: MAX_PRIORITY_FEE_PER_GAS,
+///     access_list: vec![],
+/// };
+/// ```
+///
 #[derive(Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(crate = "near_sdk::serde")]
 pub struct EVMTransaction {

src/evm/evm_transaction_builder.rs

@@ -1,3 +1,4 @@
+//! Transaction builder for EVM transactions
 use crate::transaction_builder::TxBuilder;
 
 use super::{

src/evm/mod.rs

@@ -1,4 +1,10 @@
-pub mod evm_transaction;
-pub mod evm_transaction_builder;
+//! Transaction builder, encoders, types and utilities for EVM.
+mod evm_transaction;
+mod evm_transaction_builder;
 pub mod types;
 pub mod utils;
+
+/// EVM transaction
+pub use evm_transaction::EVMTransaction;
+/// EVM transaction builder
+pub use evm_transaction_builder::EVMTransactionBuilder;

src/evm/types.rs

@@ -1,3 +1,4 @@
+//! Types used by the EVM transaction builder.
 use near_sdk::serde::{Deserialize, Serialize};
 use schemars::JsonSchema;
 

src/evm/utils.rs

@@ -1,3 +1,4 @@
+//! Utility functions for serialization and encoding of EVM data structures
 use hex;
 
 use super::types::Address;