sigma_rb 0.1.3 → 0.2.0

data/lib/sigma/ergo_box_candidate_builder.rb

@@ -3,6 +3,7 @@ require_relative './util.rb'
 require 'ffi-compiler/loader'
 
 module Sigma
+  # An ErgoBoxCandidate Builder
   class ErgoBoxCandidateBuilder
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -23,7 +24,11 @@ module Sigma
     attach_function :ergo_lib_ergo_box_candidate_builder_add_token, [:pointer, :pointer, :pointer], :void
 
     attr_accessor :pointer
-
+    # Create builder with required box parameters
+    # @param box_value: [BoxValue] amount of money associated with the box
+    # @param contract: [Contract] guarding contract, which should be evaluated to true in order to open(spend) this box
+    # @param creation_height: [Integer] height when a transaction containing the box is created. It should not exceed height of the block, containing the transaction with this box.
+    # @return [ErgoBoxCandidateBuilder]
     def self.create(box_value:, contract:, creation_height:)
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_ergo_box_candidate_builder_new(box_value.pointer, contract.pointer, creation_height, pointer)
@@ -31,32 +36,46 @@ module Sigma
       init(pointer)
     end
 
+    # Set minimal value (per byte of the serialized box size)
+    # @param min_box_value [Uint32] Unsigned 32-bit integer
+    # @return [ErgoBoxCandidateBuilder] updated ErgoBoxCandidateBuilder (self)
     def set_min_box_value_per_byte(min_box_value)
       ergo_lib_ergo_box_candidate_builder_set_min_box_value_per_byte(self.pointer, min_box_value)
       self
     end
 
+    # Get minimal value (per byte of the serialized box size)
+    # @return [Integer]
     def get_min_box_value_per_byte
       ergo_lib_ergo_box_candidate_builder_min_box_value_per_byte(self.pointer)
     end
 
+    # Set new box value
+    # @param box_value [BoxValue]
+    # @return [ErgoBoxCandidate] updated ErgoBoxCandidateBuilder (self)
     def set_value(box_value)
       ergo_lib_ergo_box_candidate_builder_set_value(self.pointer, box_value.pointer)
       self
     end
 
+    # Get box value
+    # @return [BoxValue]
     def get_value
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_ergo_box_candidate_builder_value(self.pointer, pointer)
       Sigma::BoxValue.with_raw_pointer(pointer)
     end
 
+    # Calulate serialized box size (in bytes)
+    # @return [Integer]
     def calc_box_size_bytes
       res = ergo_lib_ergo_box_candidate_builder_calc_box_size_bytes(self.pointer)
       Util.check_error!(res[:error])
       res[:value]
     end
 
+    # Calculate minimal box value for the current box serialized size (in bytes)
+    # @return [BoxValue]
     def calc_min_box_value
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_ergo_box_candidate_calc_min_box_value(self.pointer, pointer)
@@ -64,10 +83,18 @@ module Sigma
       Sigma::BoxValue.with_raw_pointer(pointer)
     end
 
+    # Set register (R4-R9) to the given value
+    # @param register_id [Integer]
+    # @param constant [Constant]
+    # @see REGISTER_ID_ENUM
     def set_register_value(register_id, constant)
       ergo_lib_ergo_box_candidate_builder_set_register_value(self.pointer, register_id, constant.pointer)
     end
 
+    # Gets register value or nil if empty
+    # @param register_id [Integer]
+    # @return [Constant, nil]
+    # @see REGISTER_ID_ENUM
     def get_register_value(register_id)
       pointer = FFI::MemoryPointer.new(:pointer)
       res = ergo_lib_ergo_box_candidate_builder_register_value(self.pointer, register_id, pointer)
@@ -79,11 +106,22 @@ module Sigma
       end
     end
 
+    # Delete register value (make register empty) for the given register id (R4-R9)
+    # @param register_id [Integer]
+    # @return [ErgoBoxCandidate] updated ErgoBoxCandidateBuilder (self)
+    # @see REGISTER_ID_ENUM
     def delete_register_value(register_id)
       ergo_lib_ergo_box_candidate_builder_delete_register_value(self.pointer, register_id)
       self
     end
   
+    # Mint token, as defined in EIP-004
+    # @param token: [Token]
+    # @param name: [String] Token name, will be encoded in R4
+    # @param description: [String] Token description, will be encoded in R5
+    # @param num_decimals: [Integer] Number of decimals, will be encoded in R6
+    # @return [ErgoBoxCandidateBuilder] updated ErgoBoxCandidateBuilder (self)
+    # @see https://github.com/ergoplatform/eips/blob/master/eip-0004.md EIP-004
     def mint_token(token:, name:, description:, num_decimals:)
       ergo_lib_ergo_box_candidate_builder_mint_token(
         self.pointer,
@@ -95,11 +133,17 @@ module Sigma
       self
     end
 
+    # Add given token_id and token_amount
+    # @param token_id [TokenId]
+    # @param token_amount [TokenAmount]
+    # @return [ErgoBoxCandidateBuilder] updated ErgoBoxCandidateBuilder (self)
     def add_token(token_id, token_amount)
       ergo_lib_ergo_box_candidate_builder_add_token(self.pointer, token_id.pointer, token_amount.pointer)
       self
     end
 
+    # Build the box candidate
+    # @return [ErgoBoxCandidate]
     def build
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_ergo_box_candidate_builder_build(self.pointer, pointer)

data/lib/sigma/ergo_state_context.rb

@@ -3,6 +3,7 @@ require_relative './util.rb'
 require 'ffi-compiler/loader'
 
 module Sigma
+  # Blockchain state (last headers, etc)
   class ErgoStateContext
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -13,6 +14,10 @@ module Sigma
 
     attr_accessor :pointer
 
+    # Createa new context
+    # @param pre_header [PreHeader]
+    # @param headers [Headers]
+    # @return [ErgoStateContext]
     def self.create(pre_header:, headers:)
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_ergo_state_context_new(pre_header.pointer, headers.pointer, pointer)
@@ -20,6 +25,9 @@ module Sigma
       init(pointer)
     end
 
+    # Equality check
+    # @param esc_two [ErgoStateContext]
+    # @return [bool]
     def ==(esc_two)
       ergo_lib_ergo_state_context_eq(self.pointer, esc.pointer)
     end

data/lib/sigma/ergo_tree.rb

@@ -3,12 +3,14 @@ require_relative './util.rb'
 require 'ffi-compiler/loader'
 
 module Sigma
+  # The root of ErgoScript IR. Serialized instances of this class are self sufficient and can be passed around.
   class ErgoTree
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
     typedef :pointer, :error_pointer
     attach_function :ergo_lib_ergo_tree_delete, [:pointer], :void
     attach_function :ergo_lib_ergo_tree_eq, [:pointer, :pointer], :bool
+    attach_function :ergo_lib_ergo_tree_from_bytes, [:pointer, :uint, :pointer], :error_pointer
     attach_function :ergo_lib_ergo_tree_from_base16_bytes, [:pointer, :pointer], :error_pointer
     attach_function :ergo_lib_ergo_tree_to_base16_bytes, [:pointer, :pointer], :error_pointer
     attach_function :ergo_lib_ergo_tree_to_bytes, [:pointer, :pointer], :error_pointer
@@ -20,10 +22,29 @@ module Sigma
     attach_function :ergo_lib_ergo_tree_get_constant, [:pointer, :uint8, :pointer], ReturnOption.by_value
     attr_accessor :pointer
 
+    # Takes ownership of an existing ErgoTree Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [ErgoTree]
     def self.with_raw_pointer(unread_pointer)
       init(unread_pointer)
     end
 
+    # Decode from encoded serialized ErgoTree
+    # @param bytes [Array<uint8>] Array of unsigned 8-bit integers (0-255)
+    # @return [ErgoTree]
+    def self.from_bytes(bytes)
+      pointer = FFI::MemoryPointer.new(:pointer)
+      b_ptr = FFI::MemoryPointer.new(:uint8, bytes.size)
+      b_ptr.write_array_of_uint8(bytes)
+      error = ergo_lib_ergo_tree_from_bytes(b_ptr, bytes.size, pointer)
+      Util.check_error!(error)
+      init(pointer)
+    end
+
+    # Decode from a base16 encoded serialized ErgoTree
+    # @param encoded_str [String]
+    # @return [ErgoTree]
     def self.from_base16_encoded_string(encoded_str)
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_ergo_tree_from_base16_bytes(encoded_str, pointer)
@@ -32,6 +53,8 @@ module Sigma
       init(pointer)
     end
 
+    # Convert to base16 encoded serialized bytes
+    # @return [String]
     def to_base16_encoded_string
       s_ptr = FFI::MemoryPointer.new(:pointer, 1)
       error = ergo_lib_ergo_tree_to_base16_bytes(self.pointer, s_ptr)
@@ -42,6 +65,8 @@ module Sigma
       str
     end
 
+    # Convert to serialized bytes
+    # @return [Array<uint8>] Array of 8-bit integers (0-255)
     def to_bytes
       res = ergo_lib_ergo_tree_bytes_len(self.pointer)
       Util.check_error!(res[:error])
@@ -52,6 +77,8 @@ module Sigma
       bytes_ptr.read_array_of_uint8(bytes_length)
     end
 
+    #  Serialized proposition expression of SigmaProp type with ConstantPlaceholder nodes instead of Constant nodes.
+    # @return [Array<uint8>] Array of 8-bit integers (0-255)
     def to_template_bytes
       res = ergo_lib_ergo_tree_template_bytes_len(self.pointer)
       Util.check_error!(res[:error])
@@ -62,12 +89,17 @@ module Sigma
       bytes_ptr.read_array_of_uint8(bytes_length)
     end
 
+    # Returns the number of constants stored in the serialized ``ErgoTree`` or throws error if the parsing of constants failed
+    # @return [Integer]
     def constants_length
       res = ergo_lib_ergo_tree_constants_len(self.pointer)
       Util.check_error!(res[:error])
       res[:value]
     end
 
+    # Return constant with given index (as stored in serialized ErgoTree) if it exists. Throws if constant parsing failed. Returns nil if no constant exists at given index
+    # @param index [Integer]
+    # @return [Constant, nil]
     def get_constant(index)
       pointer = FFI::MemoryPointer.new(:pointer)
       res = ergo_lib_ergo_tree_get_constant(self.pointer, index, pointer)
@@ -79,6 +111,10 @@ module Sigma
       end
     end
 
+    # Replace the constant of the ``ErgoTree`` with the given `constant` at position `index`. Throws if no constant exists at `index`.
+    # @param index: [Integer]
+    # @param constant: [Constant]
+    # @return [ErgoTree] ErgoTree with constant replaced (updates self)
     def replace_constant(index:, constant:)
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_ergo_tree_with_constant(self.pointer, index, constant.pointer, pointer)
@@ -89,6 +125,8 @@ module Sigma
       self.class.init(pointer, obj: self)
     end
 
+    # Equality check
+    # @param ergo_tree_two [ErgoTree]
     def ==(ergo_tree_two)
       ergo_lib_ergo_tree_eq(self.pointer, ergo_tree_two.pointer)
     end
@@ -105,7 +143,5 @@ module Sigma
       )
       obj
     end
-
-
   end
 end

data/lib/sigma/input.rb

@@ -3,6 +3,7 @@ require_relative './util.rb'
 require 'ffi-compiler/loader'
 
 module Sigma
+  # Signed inputs used in signed transactions
   class Input
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -12,16 +13,24 @@ module Sigma
     attach_function :ergo_lib_input_box_id, [:pointer, :pointer], :void
     attach_function :ergo_lib_input_spending_proof, [:pointer, :pointer], :void
 
+    # Takes ownership of an existing Input Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [Input]
     def self.with_raw_pointer(pointer)
       init(pointer)
     end
 
+    # Get box id
+    # @return [BoxId]
     def get_box_id
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_input_box_id(self.pointer, pointer)
       Sigma::BoxId.with_raw_pointer(pointer)
     end
 
+    # Get spending proof
+    # @return [ProverResult]
     def get_spending_proof
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_input_spending_proof(self.pointer, pointer)
@@ -42,6 +51,7 @@ module Sigma
     end
   end
 
+  # An ordered collectino of Input
   class Inputs
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -54,10 +64,16 @@ module Sigma
 
     attr_accessor :pointer
 
+    # Takes ownership of an existing Inputs Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [Inputs]
     def self.with_raw_pointer(unread_pointer)
       init(unread_pointer)
     end
 
+    # Create an empty collection
+    # @return [Inputs]
     def self.create
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_inputs_new(pointer)
@@ -65,14 +81,21 @@ module Sigma
       init(pointer)
     end
 
+    # Get length of collection
+    # @return [Integer]
     def len
       ergo_lib_inputs_len(self.pointer)
     end
 
+    # Add to collection
+    # @param input [Input]
     def add(input)
       ergo_lib_inputs_add(input.pointer, self.pointer)
     end
 
+    # Get item at specified index or return nil if no item exists
+    # @params index [Integer]
+    # @return [Input, nil]
     def get(index)
       pointer = FFI::MemoryPointer.new(:pointer)
       res = ergo_lib_inputs_get(self.pointer, index, pointer)
@@ -98,6 +121,7 @@ module Sigma
     end
   end
 
+  # Proof of correctness for transaction spending
   class ProverResult
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -109,6 +133,8 @@ module Sigma
     attach_function :ergo_lib_prover_result_proof_len, [:pointer], :uint
     attr_accessor :pointer
 
+    # Get proof bytes
+    # @return [Array<uint8>] Array of 8-bit integers [0-255]
     def to_bytes
       proof_len = ergo_lib_prover_result_proof_len(self.pointer)
       b_ptr = FFI::MemoryPointer.new(:uint8, proof_len)
@@ -116,12 +142,16 @@ module Sigma
       b_ptr.get_array_of_uint8(0, proof_len) 
     end
 
+    # Get context extension
+    # @return [ContextExtension]
     def get_context_extension
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_prover_result_context_extension(self.pointer, pointer)
       Sigma::ContextExtension.with_raw_pointer(pointer)
     end
 
+    # JSON representation as text (compatible with Ergo Node/Explorer API, numbers are encoded as numbers)
+    # @return [String]
     def to_json
       s_ptr = FFI::MemoryPointer.new(:pointer, 1)
       error = ergo_lib_prover_result_to_json(self.pointer, s_ptr)
@@ -132,6 +162,10 @@ module Sigma
       str
     end
 
+    # Takes ownership of an existing ProverResult Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [ProverResult]
     def self.with_raw_pointer(pointer)
       init(pointer)
     end
@@ -148,9 +182,9 @@ module Sigma
       )
       obj
     end
-
   end
 
+  # Unsigned inputs used in constructing unsigned transactions
   class UnsignedInput
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -161,16 +195,24 @@ module Sigma
 
     attr_accessor :pointer
     
+    # Takes ownership of an existing UnsignedInput Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [UnsignedInput]
     def self.with_raw_pointer(pointer)
       init(pointer)
     end
 
+    # Get box id
+    # @return [BoxId]
     def get_box_id
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_unsigned_input_box_id(self.pointer, pointer)
       Sigma::BoxId.with_raw_pointer(pointer)
     end
 
+    # Get context extension
+    # @return [ContextExension]
     def get_context_extension
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_unsigned_input_context_extension(self.pointer, pointer)
@@ -191,6 +233,7 @@ module Sigma
     end
   end
 
+  # An ordered collection of UnsignedInput
   class UnsignedInputs
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -203,10 +246,16 @@ module Sigma
 
     attr_accessor :pointer
 
+    # Takes ownership of an existing UnsignedInputs Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [UnsignedInputs]
     def self.with_raw_pointer(unread_pointer)
       init(unread_pointer)
     end
 
+    # Create an empty collection
+    # @return [UnsignedInputs]
     def self.create
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_unsigned_inputs_new(pointer)
@@ -214,14 +263,21 @@ module Sigma
       init(pointer)
     end
 
+    # Get length of collection
+    # @return [Integer]
     def len
       ergo_lib_unsigned_inputs_len(self.pointer)
     end
 
+    # Add to collection
+    # @param unsigned_input [UnsignedInput]
     def add(unsigned_input)
       ergo_lib_unsigned_inputs_add(unsigned_input.pointer, self.pointer)
     end
 
+    # Get item at specified index or return nil if no item exists
+    # @params index [Integer]
+    # @return [UnsignedInput, nil]
     def get(index)
       pointer = FFI::MemoryPointer.new(:pointer)
       res = ergo_lib_unsigned_inputs_get(self.pointer, index, pointer)

data/lib/sigma/merkle_proof.rb

@@ -31,6 +31,10 @@ module Sigma
       init(pointer)
     end
 
+    # Adds a new node and it's hash to the MerkleProof. Hash must be 32 bytes in size
+    # @param hash: [Array<uint8, 32>]
+    # @param side: [Integer]
+    # @see NODE_SIDE_ENUM
     def add_node(hash:, side:)
       b_ptr = FFI::MemoryPointer.new(:uint8, hash.size)
       b_ptr.write_array_of_uint8(hash)
@@ -38,7 +42,9 @@ module Sigma
       Util.check_error!(error)
     end
 
-    # Hash can be an Array(Uint8) or String
+    # Validates the MerkleProof against the provided root hash
+    # @param hash [Array<uint8>, String]
+    # @return [bool]
     def valid(hash)
       if hash.is_a?(Array)
         valid_with_array(hash)

data/lib/sigma/nipopow.rb

@@ -14,6 +14,9 @@ module Sigma
 
     attr_accessor :pointer
 
+    # Parse NiPoPow from json
+    # @param json [String]
+    # @return [NipopowProof]
     def self.with_json(json)
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_nipopow_proof_from_json(json, pointer)
@@ -21,6 +24,9 @@ module Sigma
       init(pointer)
     end
 
+    # Implementation of the ≥ algorithm from [`KMZ17`], see Algorithm 4
+    # @return [bool]
+    # @see https://fc20.ifca.ai/preproceedings/74.pdf KMZ17
     def is_better_than(other_proof)
       pointer = FFI::MemoryPointer.new(:pointer)
       res = ergo_lib_nipopow_proof_is_better_than(self.pointer, other_proof.pointer)
@@ -28,6 +34,8 @@ module Sigma
       res[:value]
     end
 
+    # JSON representation
+    # @return [String]
     def to_json
       s_ptr = FFI::MemoryPointer.new(:pointer, 1)
       error = ergo_lib_nipopow_proof_to_json(self.pointer, s_ptr)
@@ -52,6 +60,8 @@ module Sigma
     end
   end
   
+  # A verifier for PoPoW proofs. During its lifetime, it processes many proofs with the aim of
+  # deducing at any given point what is the best (sub)chain rooted at the specified genesis.
   class NipopowVerifier
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -62,18 +72,25 @@ module Sigma
     attach_function :ergo_lib_nipopow_verifier_process, [:pointer,:pointer], :error_pointer
     attr_accessor :pointer
 
+    # Create new instance
+    # @param genesis_block_id [BlockId]
+    # @return [NipopowVerifier]
     def self.create(genesis_block_id)
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_nipopow_verifier_new(genesis_block_id.pointer, pointer)
       init(pointer)
     end
 
+    # Returns chain of `BlockHeader`s from the best proof.
+    # @return [BlockHeaders]
     def best_chain
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_nipopow_verifier_best_chain(self.pointer, pointer)
       BlockHeaders.with_raw_pointer(pointer)
     end
 
+    # Process given proof
+    # @param proof [NipopowProof]
     def process(proof)
       error = ergo_lib_nipopow_verifier_process(self.pointer, proof.pointer)
       Util.check_error!(error)
@@ -104,6 +121,9 @@ module Sigma
     attach_function :ergo_lib_po_pow_header_eq, [:pointer, :pointer], :bool
     attr_accessor :pointer
 
+    # Create from json
+    # @param json [String]
+    # @return [PoPowHeader]
     def self.with_json(json)
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_popow_header_from_json(json, pointer)
@@ -111,6 +131,8 @@ module Sigma
       init(pointer)
     end
 
+    # JSON representation
+    # @return [String]
     def to_json
       s_ptr = FFI::MemoryPointer.new(:pointer, 1)
       error = ergo_lib_popow_header_to_json(self.pointer, s_ptr)
@@ -121,6 +143,8 @@ module Sigma
       str
     end
 
+    # Get header
+    # @return [BlockHeader]
     def get_header
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_popow_header_get_header(self.pointer, pointer)
@@ -128,6 +152,8 @@ module Sigma
       BlockHeader.with_raw_pointer(pointer)
     end
 
+    # Get interlinks
+    # @return [BlockIds]
     def get_interlinks
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_popow_header_get_interlinks(self.pointer, pointer)
@@ -135,6 +161,9 @@ module Sigma
       BlockIds.with_raw_pointer(pointer)
     end
 
+    # Equality check
+    # @param other_header [PoPowHeader]
+    # @return [bool]
     def ==(other_header)
       ergo_lib_po_pow_header_eq(self.pointer, other_header.pointer)
     end

data/lib/sigma/pre_header.rb

@@ -3,6 +3,7 @@ require_relative './util.rb'
 require 'ffi-compiler/loader'
 
 module Sigma
+  # Block header with the current `spendingTransaction`, that can be predicted by a miner before its formation
   class PreHeader
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -12,12 +13,18 @@ module Sigma
     attach_function :ergo_lib_pre_header_eq, [:pointer, :pointer], :bool
     attr_accessor :pointer
 
+    # Create using data from block_header
+    # @param block_header [BlockHeader]
+    # @return [PreHeader]
     def self.with_block_header(block_header)
       pointer = FFI::MemoryPointer.new(:pointer) 
       ergo_lib_preheader_from_block_header(block_header.pointer, pointer)
       init(pointer) 
     end
 
+    # Equality check
+    # @param ph_two [PreHeader]
+    # @return [bool]
     def ==(ph_two)
       ergo_lib_pre_header_eq(self.pointer, ph_two.pointer)
     end

data/lib/sigma/reduced_transaction.rb

@@ -3,6 +3,13 @@ require_relative './util.rb'
 require 'ffi-compiler/loader'
 
 module Sigma
+  # Represent `reduced` transaction, i.e. unsigned transaction where each unsigned input
+  # is augmented with ReducedInput which contains a script reduction result.
+  # After an unsigned transaction is reduced it can be signed without context.
+  # Thus, it can be serialized and transferred for example to Cold Wallet and signed
+  # in an environment where secrets are known.
+  # see EIP-19 for more details
+  # @see https://github.com/ergoplatform/eips/blob/f280890a4163f2f2e988a0091c078e36912fc531/eip-0019.md EIP-19
   class ReducedTransaction
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -12,6 +19,13 @@ module Sigma
     attach_function :ergo_lib_reduced_tx_unsigned_tx, [:pointer, :pointer], :void
     attr_accessor :pointer
 
+    # Create `reduced` transaction, i.e. unsigned transaction where each unsigned input
+    # is augmented with ReducedInput which contains a script reduction result.
+    # @param unsigned_tx: [UnsignedTransaction]
+    # @param boxes_to_spend: [ErgoBoxes]
+    # @param data_boxes: [ErgoBoxes]
+    # @param state_context: [ErgoStateContext]
+    # @return [ReducedTransaction]
     def self.from_unsigned_tx(unsigned_tx:, boxes_to_spend:, data_boxes:, state_context:)
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_reduced_tx_from_unsigned_tx(
@@ -25,10 +39,16 @@ module Sigma
       init(pointer)
     end
 
+    # Takes ownership of an existing ReducedTransaction Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [ReducedTransaction]
     def self.with_raw_pointer(pointer)
       init(pointer)
     end
 
+    # Get unsigned transaction
+    # @return [UnsignedTransaction]
     def get_unsigned_transaction
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_reduced_tx_unsigned_tx(self.pointer, pointer)
@@ -49,6 +69,7 @@ module Sigma
     end
   end
 
+  # Propositions list (public keys)
   class Propositions
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -58,12 +79,16 @@ module Sigma
     attach_function :ergo_lib_propositions_add_proposition_from_bytes, [:pointer, :pointer, :uint], :error_pointer
     attr_accessor :pointer
 
+    # Create an empty collection
+    # @return [Propositions]
     def self.create
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_propositions_new(pointer)
       init(pointer)
     end
 
+    # Add a proposition
+    # @param bytes [Array<uint8>] Array of 8-bit integers (0-255)
     def add_proposition(bytes)
       b_ptr = FFI::MemoryPointer.new(:uint8, bytes.size)
       b_ptr.write_array_of_uint8(bytes)