sigma_rb 0.1.3 → 0.2.0

data/lib/sigma/secret_key.rb

@@ -3,6 +3,7 @@ require_relative './util.rb'
 require 'ffi-compiler/loader'
 
 module Sigma
+  # Secret key for the prover
   class SecretKey
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -15,12 +16,17 @@ module Sigma
 
     attr_accessor :pointer
 
+    # Generate random key
+    # @return [SecretKey]
     def self.create
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_secret_key_generate_random(pointer)
       init(pointer)
     end
 
+    # Parse dlog secret key from bytes (SEC-1-encoded scalar)
+    # @param bytes [Array<uint8>] Array of 8-bit integers (0-255)
+    # @return [SecretKey]
     def self.from_bytes(bytes)
       pointer = FFI::MemoryPointer.new(:pointer)
       b_ptr = FFI::MemoryPointer.new(:uint8, bytes.size)
@@ -30,16 +36,24 @@ module Sigma
       init(pointer)
     end
 
+    # Takes ownership of an existing SecretKey Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [SecretKey]
     def self.with_raw_pointer(pointer)
       init(pointer)
     end
 
+    # Get address (encoded public image)
+    # @return [Address]
     def get_address
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_secret_key_get_address(self.pointer, pointer)
       Sigma::Address.with_raw_pointer(pointer)
     end
-
+    
+    # Encode to bytes
+    # @return [Array<uint8>] Array of 8-bit integers (0-255)
     def to_bytes
       bytes_len = 32
       b_ptr = FFI::MemoryPointer.new(:uint8, bytes_len) 
@@ -61,6 +75,7 @@ module Sigma
     end
   end
 
+  # An ordered collection of SecretKey
   class SecretKeys
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -73,10 +88,16 @@ module Sigma
 
     attr_accessor :pointer
 
+    # Takes ownership of an existing SecretKeys Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [SecretKeys]
     def self.with_raw_pointer(unread_pointer)
       init(unread_pointer)
     end
 
+    # Create an empty collection
+    # @return [SecretKeys]
     def self.create
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_secret_keys_new(pointer)
@@ -84,14 +105,21 @@ module Sigma
       init(pointer)
     end
 
+    # Get length of collection
+    # @return [Integer]
     def len
       ergo_lib_secret_keys_len(self.pointer)
     end
 
+    # Add to collection
+    # @param secret_key [SecretKey]
     def add(secret_key)
       ergo_lib_secret_keys_add(secret_key.pointer, self.pointer)
     end
 
+    # Get item at specified index or return nil if no item exists
+    # @param index [Integer]
+    # @return [SecretKey, nil]
     def get(index)
       pointer = FFI::MemoryPointer.new(:pointer)
       res = ergo_lib_secret_keys_get(self.pointer, index, pointer)

data/lib/sigma/structs.rb

@@ -4,26 +4,36 @@ module Sigma
   extend FFI::Library
   typedef :pointer, :error_pointer
 
+  # Internal FFI Struct
+  # @see https://github.com/ffi/ffi/wiki/Examples#-structs FFI Struct Documentation
   class ReturnOption < FFI::Struct
     layout :is_some, :bool,
            :error, :error_pointer
   end
 
+  # Internal FFI Struct
+  # @see https://github.com/ffi/ffi/wiki/Examples#-structs FFI Struct Documentation
   class ReturnNumUsize < FFI::Struct
     layout :value, :uint,
            :error, :error_pointer
   end
 
+  # Internal FFI Struct
+  # @see https://github.com/ffi/ffi/wiki/Examples#-structs FFI Struct Documentation
   class ReturnNumI32 < FFI::Struct
     layout :value, :int32,
            :error, :error_pointer
   end
 
+  # Internal FFI Struct
+  # @see https://github.com/ffi/ffi/wiki/Examples#-structs FFI Struct Documentation
   class ReturnNumI64 < FFI::Struct
     layout :value, :int64,
            :error, :error_pointer
   end
 
+  # Internal FFI Struct
+  # @see https://github.com/ffi/ffi/wiki/Examples#-structs FFI Struct Documentation
   class ReturnBool < FFI::Struct
     layout :value, :bool,
            :error, :error_pointer

data/lib/sigma/token.rb

@@ -13,10 +13,17 @@ module Sigma
     attach_function :ergo_lib_token_amount_eq, [:pointer, :pointer], :bool
     attr_accessor :pointer
 
+    # Takes ownership of an existing TokenAmount Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [TokenAmount]
     def self.with_raw_pointer(unread_pointer)
       init(unread_pointer)
     end
 
+    # Create instance from 64-bit Integer with bounds check
+    # @param int [Integer]
+    # @return [TokenAmount]
     def self.with_i64(int)
       ptr = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_token_amount_from_i64(int, ptr)
@@ -25,10 +32,15 @@ module Sigma
       init(ptr)
     end
 
+    # Get value as 64-bit integer
+    # @return [Integer]
     def to_i
       ergo_lib_token_amount_as_i64(self.pointer)
     end
 
+    # Equality check
+    # @param token_amount_two [TokenAmount]
+    # @return [bool]
     def ==(token_amount_two)
       ergo_lib_token_amount_eq(self.pointer, token_amount_two.pointer)
     end
@@ -47,6 +59,7 @@ module Sigma
     end
   end
 
+  # Token id (32-byte digest)
   class TokenId
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -58,10 +71,17 @@ module Sigma
     attach_function :ergo_lib_token_id_to_str, [:pointer, :pointer], :void
     attr_accessor :pointer
 
+    # Takes ownership of an existing TokenId Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [TokenId]
     def self.with_raw_pointer(tid_pointer)
       init(tid_pointer)
     end
 
+    # Create token id from ergo box id (32 byte digest)
+    # @param box_id [BoxId]
+    # @return [TokenId]
     def self.with_box_id(box_id)
       tid_ptr = FFI::MemoryPointer.new(:pointer)
       ergo_lib_token_id_from_box_id(box_id.pointer, tid_ptr)
@@ -69,6 +89,9 @@ module Sigma
       init(tid_ptr)
     end
 
+    # Parse token id (32 byte digest) from base16-encoded string
+    # @param str [String]
+    # @return [TokenId]
     def self.from_base16_encoded_string(str)
       tid_ptr = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_token_id_from_str(str, tid_ptr)
@@ -77,6 +100,8 @@ module Sigma
       init(tid_ptr)
     end
 
+    # Get base16 encoded string
+    # @return [String]
     def to_base16_encoded_string
       s_ptr = FFI::MemoryPointer.new(:pointer, 1)
       ergo_lib_token_id_to_str(self.pointer, s_ptr)
@@ -86,6 +111,9 @@ module Sigma
       str
     end
 
+    # Equality check
+    # @param token_id_two [TokenId]
+    # @return [bool]
     def ==(token_id_two)
       ergo_lib_token_id_eq(self.pointer, token_id_two.pointer)
     end
@@ -104,6 +132,7 @@ module Sigma
     end
   end
 
+  # Token represented with token id paired with its amount
   class Token
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -116,6 +145,10 @@ module Sigma
     attach_function :ergo_lib_token_eq, [:pointer, :pointer], :bool
     attr_accessor :pointer
 
+    # Create a token with given id and amount
+    # @param token_id: [TokenId]
+    # @param token_amount: [TokenAmount]
+    # @return [Token]
     def self.create(token_id:, token_amount:)
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_token_new(token_id.pointer, token_amount.pointer, pointer)
@@ -123,22 +156,33 @@ module Sigma
       init(pointer)
     end
 
+    # Takes ownership of an existing Token Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [Token]
     def self.with_raw_pointer(pointer)
       init(pointer)
     end
 
+    # Get id
+    # @return [TokenId]
     def get_id
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_token_get_id(self.pointer, pointer)
       Sigma::TokenId.with_raw_pointer(pointer)
     end
 
+    # Get amount
+    # @return [TokenAmount]
     def get_amount
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_token_get_amount(self.pointer, pointer)
       Sigma::TokenAmount.with_raw_pointer(pointer)
     end
 
+    # JSON representation according to EIP-12
+    # @return [String]
+    # @see https://github.com/ergoplatform/eips/pull/23 EIP-12
     def to_json_eip12
       s_ptr = FFI::MemoryPointer.new(:pointer, 1)
       error = ergo_lib_token_to_json_eip12(self.pointer, s_ptr)
@@ -149,6 +193,9 @@ module Sigma
       str
     end
 
+    # Equality check
+    # @param token_two [Token]
+    # @return [bool]
     def ==(token_two)
       ergo_lib_token_eq(self.pointer, token_two.pointer)
     end
@@ -167,6 +214,7 @@ module Sigma
     end
   end
 
+  # An ordered collection of Token
   class Tokens
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -178,20 +226,31 @@ module Sigma
     attach_function :ergo_lib_tokens_add, [:pointer, :pointer], :error_pointer
     attr_accessor :pointer
 
+    # Create an empty collection
+    # @return [Tokens]
     def self.create
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_tokens_new(pointer)
       init(pointer)
     end
 
+    # Takes ownership of an existing Tokens Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [Tokens]
     def self.with_raw_pointer(tokens_ptr)
       init(tokens_ptr)
     end
 
+    # Get length of collection
+    # @return [Integer]
     def len
       ergo_lib_tokens_len(self.pointer)
     end
 
+    # Get item at specified index or return nil if no item exists
+    # @param index [Integer]
+    # @return [Tokens, nil]
     def get(index)
       token_pointer = FFI::MemoryPointer.new(:pointer)
       res = ergo_lib_tokens_get(self.pointer, index, token_pointer)
@@ -203,6 +262,8 @@ module Sigma
       end
     end
 
+    # Add to collection. Max capacity of ErgoBox::MAX_TOKENS_COUNT tokens. Will throw error if adding more.
+    # @param token [Token]
     def add(token)
       error = ergo_lib_tokens_add(token.pointer, self.pointer)
       Util.check_error!(error)
@@ -222,4 +283,3 @@ module Sigma
     end
   end
 end
-

data/lib/sigma/transaction.rb

@@ -3,6 +3,15 @@ require_relative './util.rb'
 require 'ffi-compiler/loader'
 
 module Sigma
+
+  # ErgoTransaction is an atomic state transition operation. It destroys Boxes from the state
+  # and creates new ones. If transaction is spending boxes protected by some non-trivial scripts,
+  # its inputs should also contain proof of spending correctness - context extension (user-defined
+  # key-value map) and data inputs (links to existing boxes in the state) that may be used during
+  # script reduction to crypto, signatures that satisfies the remaining cryptographic protection
+  # of the script.
+  # Transactions are not encrypted, so it is possible to browse and view every transaction ever
+  # collected into a block.
   class Transaction
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -19,6 +28,11 @@ module Sigma
     attach_function :ergo_lib_tx_to_json_eip12, [:pointer, :pointer], :error_pointer
     attr_accessor :pointer
 
+    # Create ``Transaction`` from ``UnsignedTransaction`` and an array of proofs in the same order
+    # as `UnsignedTransaction.inputs` with empty proof indicated with empty byte array
+    # @param unsigned_tx: [UnsignedTransaction]
+    # @param proofs: [ByteArrays]
+    # @return [Transaction]
     def self.create_from_unsigned_tx(unsigned_tx:, proofs:)
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_tx_from_unsigned_tx(unsigned_tx.pointer, proofs.pointer, pointer)
@@ -26,6 +40,9 @@ module Sigma
       init(pointer)
     end
 
+    # Parse from JSON. Supports Ergo Node/Explorer API and box values and token amount encoded as strings
+    # @param json [String]
+    # @return [Transaction]
     def self.create_from_json(json)
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_tx_from_json(json, pointer)
@@ -33,40 +50,56 @@ module Sigma
       init(pointer)
     end
 
+    # Takes ownership of an existing Transaction Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [Transaction]
     def self.with_raw_pointer(pointer)
       init(pointer)
     end
 
+    # Get transaction id
+    # @return [TxId]
     def get_tx_id
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_tx_id(self.pointer, pointer)
       Sigma::TxId.with_raw_pointer(pointer)
     end
 
+    # Get inputs
+    # @return [Inputs]
     def get_inputs
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_tx_inputs(self.pointer, pointer)
       Sigma::Inputs.with_raw_pointer(pointer)
     end
 
+    # Get data inputs
+    # @return [DataInputs]
     def get_data_inputs
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_tx_data_inputs(self.pointer, pointer)
       Sigma::DataInputs.with_raw_pointer(pointer)
     end
 
+    # Get output candidates
+    # @return [ErgoBoxCandidates]
     def get_output_candidates
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_tx_output_candidates(self.pointer, pointer)
       Sigma::ErgoBoxCandidates.with_raw_pointer(pointer)
     end
 
+    # Get outputs
+    # @return [ErgoBoxes]
     def get_outputs
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_tx_outputs(self.pointer, pointer)
       Sigma::ErgoBoxes.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_tx_to_json(self.pointer, s_ptr)
@@ -77,6 +110,8 @@ module Sigma
       str
     end
 
+    # JSON representation according to EIP-12 
+    # @see https://github.com/ergoplatform/eips/pull/23 EIP-12
     def to_json_eip12
       s_ptr = FFI::MemoryPointer.new(:pointer, 1)
       error = ergo_lib_tx_to_json_eip12(self.pointer, s_ptr)
@@ -101,6 +136,8 @@ module Sigma
     end
   end
 
+  # A family of hints which are about a correspondence between a public image of a secret image and prover's commitment
+  # to randomness ("a" in a sigma protocol).
   class CommitmentHint
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -108,6 +145,10 @@ module Sigma
     attach_function :ergo_lib_commitment_hint_delete, [:pointer], :void
     attr_accessor :pointer
 
+    # Takes ownership of an existing CommitmentHint Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [CommitmentHint]
     def self.with_raw_pointer(pointer)
       init(pointer)
     end
@@ -126,6 +167,7 @@ module Sigma
     end
   end
 
+  # Collection of hints to be used by prover
   class HintsBag
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -137,24 +179,37 @@ module Sigma
     attach_function :ergo_lib_hints_bag_get, [:pointer, :uint, :pointer], ReturnOption.by_value
     attr_accessor :pointer
 
+    # Create an empty collection
+    # @return [HintsBag]
     def self.create
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_hints_bag_empty(pointer)
       init(pointer)
     end
 
+    # Takes ownership of an existing HintsBag Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [HintsBag]
     def self.with_raw_pointer(pointer)
       init(pointer)
     end
 
+    # Add to collection
+    # @param commitment_hint [CommitmentHint]
     def add_commitment_hint(commitment_hint)
       ergo_lib_hints_bag_add_commitment(self.pointer, commitment_hint.pointer)
     end
 
+    # Get length of collection
+    # @return [Integer]
     def len
       ergo_lib_hints_bag_add_commitment_len(self.pointer)
     end
 
+    # Get item at specified index or return nil if no item exists
+    # @param index [Integer]
+    # @return [CommitmentHint, nil]
     def get_commitment_hint(index)
       pointer = FFI::MemoryPointer.new(:pointer)
       res = ergo_lib_hints_bag_get(self.pointer, index, pointer)
@@ -191,16 +246,30 @@ module Sigma
     attach_function :ergo_lib_transaction_extract_hints, [:pointer, :pointer, :pointer, :pointer, :pointer, :pointer, :pointer], :error_pointer
     attr_accessor :pointer
 
+    # Create empty collection
+    # @return [TransactionHintsBag]
     def self.create
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_transaction_hints_bag_empty(pointer)
       init(pointer)
     end
 
+    # Takes ownership of an existing TransactionHintsBag Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [TransactionHintsBag]
     def self.with_raw_pointer(pointer)
       init(pointer)
     end
 
+    # Extract hints from signed transaction
+    # @param transaction: [Transaction]
+    # @param state_context: [ErgoStateContext]
+    # @param boxes_to_spend: [ErgoBoxes]
+    # @param data_boxes: [ErgoBoxes]
+    # @param real_propositions: [Propositions]
+    # @param simulated_propositions: [Propositions]
+    # @return [TransactionHintsBag]
     def self.extract_hints_from_signed_transaction(transaction:, state_context:, boxes_to_spend:, data_boxes:, real_propositions:, simulated_propositions:)
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_transaction_extract_hints(transaction.pointer, state_context.pointer, boxes_to_spend.pointer, data_boxes.pointer, real_propositions.pointer, simulated_propositions.pointer, pointer)
@@ -208,10 +277,16 @@ module Sigma
       init(pointer)
     end
 
+    # Add hints for input
+    # @param index: [Integer]
+    # @param hints_bag: [HintsBag]
     def add_hints_for_input(index:, hints_bag:)
       ergo_lib_transaction_hints_bag_add_hints_for_input(self.pointer, index, hints_bag.pointer)
     end
 
+    # Get hints corresponding to index
+    # @param index [Integer]
+    # @return [HintsBag]
     def all_hints_for_input(index)
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_transaction_hints_bag_all_hints_for_input(self.pointer, index, pointer)
@@ -232,6 +307,7 @@ module Sigma
     end
   end
 
+  # Unsigned (inputs without proofs) transaction
   class UnsignedTransaction
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -246,6 +322,9 @@ module Sigma
     attach_function :ergo_lib_unsigned_tx_to_json_eip12, [:pointer, :pointer], :error_pointer
     attr_accessor :pointer
 
+    # Parse from JSON. Supports Ergo Node/Explorer API and box values and token amount encoded as strings
+    # @param json [String]
+    # @return [UnsignedTransaction]
     def self.with_json(json)
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_unsigned_tx_from_json(json, pointer)
@@ -253,34 +332,48 @@ module Sigma
       init(pointer)
     end
 
+    # Takes ownership of an existing UnsignedTransaction Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [UnsignedTransaction]
     def self.with_raw_pointer(pointer)
       init(pointer)
     end
 
+    # Get transaction id
+    # @return [TxId]
     def get_tx_id
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_unsigned_tx_id(self.pointer, pointer)
       Sigma::TxId.with_raw_pointer(pointer)
     end
 
+    # Get unsigned inputs
+    # @return [UnsignedInputs]
     def get_unsigned_inputs
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_unsigned_tx_inputs(self.pointer, pointer)
       Sigma::UnsignedInputs.with_raw_pointer(pointer)
     end
 
+    # Get data inputs
+    # @return [DataInputs]
     def get_data_inputs
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_unsigned_tx_data_inputs(self.pointer, pointer)
       Sigma::DataInputs.with_raw_pointer(pointer)
     end
 
+    # Get output candidates
+    # @return [ErgoBoxCandidates]
     def get_output_candidates
       pointer = FFI::MemoryPointer.new(:pointer)
       ergo_lib_unsigned_tx_output_candidates(self.pointer, pointer)
       Sigma::ErgoBoxCandidates.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_unsigned_tx_to_json(self.pointer, s_ptr)
@@ -291,6 +384,8 @@ module Sigma
       str
     end
 
+    # JSON representation according to EIP-12 
+    # @see https://github.com/ergoplatform/eips/pull/23 EIP-12
     def to_json_eip12
       s_ptr = FFI::MemoryPointer.new(:pointer, 1)
       error = ergo_lib_unsigned_tx_to_json_eip12(self.pointer, s_ptr)
@@ -315,6 +410,7 @@ module Sigma
     end
   end
 
+  # Transaction Id
   class TxId
     extend FFI::Library
     ffi_lib FFI::Compiler::Loader.find('csigma')
@@ -325,6 +421,9 @@ module Sigma
   
     attr_accessor :pointer
 
+    # Create from hex-encoded string
+    # @param str [String]
+    # @return [TxId]
     def self.with_string(str)
       pointer = FFI::MemoryPointer.new(:pointer)
       error = ergo_lib_tx_id_from_str(str, pointer)
@@ -333,10 +432,16 @@ module Sigma
       init(pointer)
     end
 
+    # Takes ownership of an existing TxId Pointer.
+    # @note A user of sigma_rb generally does not need to call this function
+    # @param pointer [FFI::MemoryPointer]
+    # @return [TxId]
     def self.with_raw_pointer(unread_pointer)
       init(unread_pointer)
     end
 
+    # Get the TxId as bytes represented with hex-encoded string
+    # @return [String]
     def to_s
       s_ptr = FFI::MemoryPointer.new(:pointer, 1)
       error = ergo_lib_tx_id_to_str(self.pointer, s_ptr)