Skip to content

Commit fefa9f2

Browse files
authored
Updated crate documentation (#23)
* feat: update documentation
1 parent 8ed57bc commit fefa9f2

23 files changed

+306
-34
lines changed

Cargo.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "omni-transaction"
3-
version = "0.1.3"
3+
version = "0.2.0"
44
authors = ["Proximity Labs Limited"]
55
license = "Apache-2.0"
66
edition = "2021"

src/bitcoin/bitcoin_transaction.rs

Lines changed: 58 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,58 @@ use super::{
1212
},
1313
};
1414

15+
///
16+
/// ###### Example:
17+
///
18+
/// You can create a Bitcoin transaction directly in your NEAR contract or Rust client
19+
/// or you can do it from a JSON.
20+
///
21+
/// ```rust
22+
/// // The first case would be as follows:
23+
/// let omni_tx = BitcoinTransaction {
24+
/// version: Version::One,
25+
/// lock_time: LockTime::from_height(1000000).unwrap(),
26+
/// input: vec![TxIn {
27+
/// previous_output: OutPoint {
28+
/// txid: Txid(Hash::all_zeros()),
29+
/// vout: 0,
30+
/// },
31+
/// script_sig: ScriptBuf::default(),
32+
/// sequence: Sequence::default(),
33+
/// witness: Witness::default(),
34+
/// }],
35+
/// output: vec![TxOut {
36+
/// value: Amount::from_sat(10000),
37+
/// script_pubkey: ScriptBuf::default(),
38+
/// }],
39+
/// };
40+
///
41+
/// // If you prefer to do it from a JSON:
42+
/// let json_value = r#"
43+
/// {
44+
/// "version": "1",
45+
/// "lock_time": "0",
46+
/// "input": [{
47+
/// "previous_output": {
48+
/// "txid": "bc25cc0dddd0a202c21e66521a692c0586330a9a9dcc38ccd9b4d2093037f31a",
49+
/// "vout": 0
50+
/// },
51+
/// "script_sig": [],
52+
/// "sequence": 4294967295,
53+
/// "witness": []
54+
/// }],s
55+
/// "output": [{
56+
/// "value": 1,
57+
/// "script_pubkey": "76a9148356ecd5f1761e60c144dc2f4de6bf7d8be7690688ad"
58+
/// },
59+
/// {
60+
/// "value": 2649,
61+
/// "script_pubkey": "76a9148356ecd5f1761e60c144dc2f4de6bf7d8be7690688ac"
62+
/// }]
63+
/// }
64+
/// "#;
65+
/// let tx = BitcoinTransaction::from_json(json_value).unwrap();
66+
///
1567
#[derive(
1668
Debug,
1769
Clone,
@@ -48,7 +100,7 @@ fn sha256d(data: &[u8]) -> Vec<u8> {
48100
}
49101

50102
impl BitcoinTransaction {
51-
// Common
103+
/// Encode the transaction into a vector of bytes
52104
pub fn serialize(&self) -> Vec<u8> {
53105
let mut buffer = Vec::new();
54106

@@ -57,7 +109,7 @@ impl BitcoinTransaction {
57109
buffer
58110
}
59111

60-
// Legacy
112+
/// Encode a legacy transaction into a vector of bytes
61113
pub fn build_for_signing_legacy(&self, sighash_type: EcdsaSighashType) -> Vec<u8> {
62114
let mut buffer = Vec::new();
63115

@@ -69,6 +121,7 @@ impl BitcoinTransaction {
69121
buffer
70122
}
71123

124+
/// Attach a script sig to the transaction
72125
pub fn build_with_script_sig(
73126
&mut self,
74127
input_index: usize,
@@ -90,7 +143,7 @@ impl BitcoinTransaction {
90143
buffer
91144
}
92145

93-
// Segwit
146+
/// Encode the transaction for signing in SegWit format
94147
pub fn build_for_signing_segwit(
95148
&self,
96149
sighash_type: EcdsaSighashType,
@@ -112,6 +165,7 @@ impl BitcoinTransaction {
112165
buffer
113166
}
114167

168+
/// Function to attach a witness to the transaction
115169
pub fn build_with_witness(
116170
&mut self,
117171
input_index: usize,
@@ -206,6 +260,7 @@ impl BitcoinTransaction {
206260
self.input.is_empty()
207261
}
208262

263+
/// Serialise a JSON representation of the transaction into a BitcoinTransaction struct
209264
pub fn from_json(json: &str) -> Result<Self, near_sdk::serde_json::Error> {
210265
let tx: Self = near_sdk::serde_json::from_str(json)?;
211266
Ok(tx)
@@ -437,7 +492,6 @@ mod tests {
437492
};
438493

439494
let serialized = omni_tx.build_for_signing_legacy(OmniSighashType::All);
440-
println!("serialized BTC Omni: {:?}", serialized);
441495

442496
assert_eq!(buffer.len(), serialized.len());
443497
assert_eq!(buffer, serialized);

src/bitcoin/bitcoin_transaction_builder.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
//! Transaction builder for Bitcoin transactions
12
use super::{
23
bitcoin_transaction::BitcoinTransaction,
34
types::{LockTime, TxIn, TxOut, Version},

src/bitcoin/encoding/mod.rs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,5 @@ pub mod utils;
66

77
pub use decode::Decodable;
88
pub use encode::Encodable;
9-
pub use extensions::{ReadExt, WriteExt};
10-
pub use utils::{encode_with_size, ToU64};
9+
pub use extensions::ReadExt;
10+
pub use utils::ToU64;

src/bitcoin/mod.rs

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
1-
pub mod bitcoin_transaction;
2-
pub mod bitcoin_transaction_builder;
3-
pub mod constants;
4-
pub mod encoding;
1+
//! Transaction builder, encoders, types and utilities for Bitcoin.
2+
mod bitcoin_transaction;
3+
mod bitcoin_transaction_builder;
4+
mod constants;
5+
mod encoding;
56
pub mod types;
67
pub mod utils;
8+
9+
/// Bitcoin transaction
10+
pub use bitcoin_transaction::BitcoinTransaction;
11+
/// Bitcoin transaction builder
12+
pub use bitcoin_transaction_builder::BitcoinTransactionBuilder;

src/bitcoin/types/mod.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
/// Minimal required Bitcoin types, inspired by <https://github.com/rust-bitcoin/rust-bitcoin>
1+
//! Minimal required Bitcoin types, inspired by <https://github.com/rust-bitcoin/rust-bitcoin>
22
mod lock_time;
33
mod script_buf;
44
mod sighash;

src/bitcoin/utils.rs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
//! Utility functions for serialization and encoding of Bitcoin data structures
12
fn encode_signature_as_der(signature_bytes: &[u8]) -> Vec<u8> {
23
assert_eq!(
34
signature_bytes.len(),
@@ -32,6 +33,7 @@ fn encode_asn1_integer(bytes: &[u8]) -> Vec<u8> {
3233
result
3334
}
3435

36+
/// Build the scriptSig from the DER signature and the public key
3537
pub fn build_script_sig(der_signature: &[u8], public_key_bytes: &[u8]) -> Vec<u8> {
3638
let mut script_sig = vec![];
3739
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
4345
script_sig
4446
}
4547

48+
/// Serialize the ECDSA signature from the raw bytes and the SIGHASH type
4649
pub fn serialize_ecdsa_signature(signature_bytes: &[u8], sighash_type: u8) -> Vec<u8> {
4750
// 1. Encode the signature as DER format
4851
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
5356
der_signature
5457
}
5558

59+
/// Serialize the ECDSA signature from string representations of big R and S
5660
pub fn serialize_ecdsa_signature_from_str(big_r: &str, s: &str) -> Vec<u8> {
5761
// Generate the signature bytes from the hex strings
5862
let big_r_bytes = hex::decode(big_r).unwrap();

src/evm/evm_transaction.rs

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
//! EVM transaction
12
use near_sdk::serde::{Deserialize, Serialize};
23
use rlp::RlpStream;
34
use schemars::JsonSchema;
@@ -7,6 +8,31 @@ use crate::constants::EIP_1559_TYPE;
78
use super::types::{AccessList, Address, Signature};
89
use super::utils::parse_eth_address;
910

11+
///
12+
/// ###### Example:
13+
///
14+
/// ```rust
15+
/// let nonce: u64 = 0;
16+
/// let to: Address = address!("d8dA6BF26964aF9D7eEd9e03E53415D37aA96045");
17+
/// let value = 10000000000000000u128; // 0.01 ETH
18+
/// let data: Vec<u8> = vec![];
19+
/// let chain_id = 1;
20+
/// let to_address_str = "d8dA6BF26964aF9D7eEd9e03E53415D37aA96045";
21+
/// let to_address = Some(parse_eth_address(to_address_str));
22+
/// // Generate using EVMTransaction
23+
/// let tx = EVMTransaction {
24+
/// chain_id,
25+
/// nonce,
26+
/// to: to_address,
27+
/// value,
28+
/// input: data.clone(),
29+
/// gas_limit: GAS_LIMIT,
30+
/// max_fee_per_gas: MAX_FEE_PER_GAS,
31+
/// max_priority_fee_per_gas: MAX_PRIORITY_FEE_PER_GAS,
32+
/// access_list: vec![],
33+
/// };
34+
/// ```
35+
///
1036
#[derive(Debug, Serialize, Deserialize, JsonSchema)]
1137
#[serde(crate = "near_sdk::serde")]
1238
pub struct EVMTransaction {

src/evm/evm_transaction_builder.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
//! Transaction builder for EVM transactions
12
use crate::transaction_builder::TxBuilder;
23

34
use super::{

src/evm/mod.rs

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
1-
pub mod evm_transaction;
2-
pub mod evm_transaction_builder;
1+
//! Transaction builder, encoders, types and utilities for EVM.
2+
mod evm_transaction;
3+
mod evm_transaction_builder;
34
pub mod types;
45
pub mod utils;
6+
7+
/// EVM transaction
8+
pub use evm_transaction::EVMTransaction;
9+
/// EVM transaction builder
10+
pub use evm_transaction_builder::EVMTransactionBuilder;

0 commit comments

Comments
 (0)