ic_agent 0.1.4 → 0.2.1

data/lib/ic_agent/certificate.rb

@@ -8,10 +8,56 @@ module IcAgent
   end
 
   class Certificate
+    # Performs a lookup operation in the certificate tree based on the given path.
+    #
+    # Parameters:
+    # - path: The path to lookup.
+    # - cert: The certificate object containing the tree.
+    #
+    # Returns: The value found at the specified path in the tree.
     def self.lookup(path, cert)
       lookup_path(path, cert.value['tree'])
     end
 
+    # Retrieves the signature from a certificate.
+    #
+    # Parameters:
+    # - cert: The certificate object.
+    #
+    # Returns: The signature value.
+    def self.signature(cert)
+      cert.value['signature']
+    end
+
+    # Retrieves the delegation from a certificate.
+    #
+    # Parameters:
+    # - cert: The certificate object.
+    #
+    # Returns: The delegation value.
+    def self.delegation(cert)
+      cert.value['delegation']
+    end
+
+    # Retrieves the tree from a certificate.
+    #
+    # Parameters:
+    # - cert: The certificate object.
+    #
+    # Returns: The tree value.
+    def self.tree(cert)
+      cert.value['tree']
+    end
+
+    private
+
+    # Recursive helper method for performing the lookup operation.
+    #
+    # Parameters:
+    # - path: The remaining path to lookup.
+    # - tree: The current tree node to search in.
+    #
+    # Returns: The value found at the specified path in the tree.
     def self.lookup_path(path, tree)
       offset = 0
       if path.length == 0
@@ -29,6 +75,12 @@ module IcAgent
       end
     end
 
+    # Flattens fork nodes in the tree into a single array.
+    #
+    # Parameters:
+    # - t: The tree node to flatten.
+    #
+    # Returns: The flattened array of tree nodes.
     def self.flatten_forks(t)
       if t[0] == NodeId::EMPTY
         []
@@ -42,6 +94,13 @@ module IcAgent
       end
     end
 
+    # Finds a labeled tree node with the specified label in the given array of trees.
+    #
+    # Parameters:
+    # - l: The label to search for.
+    # - trees: The array of trees to search in.
+    #
+    # Returns: The labeled tree node with the matching label, or nil if not found.
     def self.find_label(l, trees)
       trees.each do |t|
         if t[0] == NodeId::LABELED
@@ -51,5 +110,44 @@ module IcAgent
       end
       nil
     end
+
+    # Recursively reconstructs the hash value of a tree node.
+    #
+    # Parameters:
+    # - t: The tree node to reconstruct.
+    #
+    # Returns: The reconstructed hash value of the tree node.
+    def self.reconstruct(t)
+      case t[0]
+      when IcAgent::NodeId::EMPTY
+        domain_sep = domain_sep('ic-hashtree-empty')
+        Digest::SHA256.digest(domain_sep)
+      when IcAgent::NodeId::PRUNED
+        t[1]
+      when IcAgent::NodeId::LEAF
+        domain_sep = domain_sep('ic-hashtree-leaf')
+        Digest::SHA256.digest(domain_sep + t[1])
+      when IcAgent::NodeId::LABELED
+        domain_sep = domain_sep('ic-hashtree-labeled')
+        Digest::SHA256.digest(domain_sep + t[1] + reconstruct(t[2]))
+      when IcAgent::NodeId::FORK
+        domain_sep = domain_sep('ic-hashtree-fork')
+        Digest::SHA256.digest(domain_sep + reconstruct(t[1]) + reconstruct(t[2]))
+      else
+        raise 'unreachable'
+      end
+    end
+
+    # Generates the domain separation prefix for hash computations.
+    #
+    # Parameters:
+    # - s: The domain separation string.
+    #
+    # Returns: The domain separation prefix as a binary string.
+    def self.domain_sep(s)
+      len = [s.bytesize].pack('C')
+      str = s.encode(Encoding::UTF_8)
+      len + str
+    end
   end
 end

data/lib/ic_agent/client.rb

@@ -5,6 +5,10 @@ module IcAgent
     DEFAULT_TIMEOUT = 120
     DEFAULT_TIMEOUT_QUERY = 30
 
+    # Initializes a new instance of the Client class.
+    #
+    # Parameters:
+    # - url: The URL of the IC agent. Defaults to 'https://ic0.app'.
     def initialize(url = 'https://ic0.app')
       @url = url
       @conn = Faraday.new(url: url) do |faraday|
@@ -16,6 +20,13 @@ module IcAgent
       end
     end
 
+    # Sends a query to a canister.
+    #
+    # Parameters:
+    # - canister_id: The ID of the canister to query.
+    # - data: The data to send with the query.
+    #
+    # Returns: The response from the canister as a UTF-8 encoded string.
     def query(canister_id, data)
       endpoint = "/api/v2/canister/#{canister_id}/query"
       ret = @conn.post(endpoint, data)
@@ -23,6 +34,14 @@ module IcAgent
       ret.body
     end
 
+    # Calls a function on a canister.
+    #
+    # Parameters:
+    # - canister_id: The ID of the canister to call.
+    # - req_id: The request ID.
+    # - data: The data to send with the call.
+    #
+    # Returns: The request ID.
     def call(canister_id, req_id, data)
       endpoint = "/api/v2/canister/#{canister_id}/call"
       ret = @conn.post(endpoint, data)
@@ -30,6 +49,13 @@ module IcAgent
       req_id
     end
 
+    # Reads the state of a canister.
+    #
+    # Parameters:
+    # - canister_id: The ID of the canister to read the state from.
+    # - data: The data to send with the read_state request.
+    #
+    # Returns: The response from the canister as a UTF-8 encoded string.
     def read_state(canister_id, data)
       endpoint = "/api/v2/canister/#{canister_id}/read_state"
       ret = @conn.post(endpoint, data)
@@ -37,6 +63,12 @@ module IcAgent
       ret.body
     end
 
+    # Retrieves the status of the IC agent.
+    #
+    # Parameters:
+    # - timeout: The timeout for the status request. Defaults to DEFAULT_TIMEOUT_QUERY.
+    #
+    # Returns: The response from the status endpoint as a UTF-8 encoded string.
     def status(timeout: DEFAULT_TIMEOUT_QUERY)
       endpoint = '/api/v2/status'
       ret = @conn.get(endpoint, timeout: timeout)

data/lib/ic_agent/common/cycles_wallet.rb

@@ -261,6 +261,11 @@ module IcAgent
 
       attr_accessor :identity, :client, :agent, :canister
 
+      # Constructor for the CyclesWallet class.
+      #
+      # Parameters:
+      # - iden: (Optional) An instance of the Identity class.
+      # - wallet_id: The ID of the CyclesWallet.
       def initialize(iden = nil, wallet_id)
         @identity = iden.nil? ? IcAgent::Identity.new : iden
         @client = IcAgent::Client.new

data/lib/ic_agent/common/governance.rb

@@ -355,6 +355,10 @@ module IcAgent
 
       attr_accessor :identity, :client, :agent, :canister
 
+      # Constructor for the Governance class.
+      #
+      # Parameters:
+      # - iden: (Optional) An instance of the Identity class.
       def initialize(iden = nil)
         @identity = iden.nil? ? IcAgent::Identity.new : iden
         @client = IcAgent::Client.new

data/lib/ic_agent/common/ledger.rb

@@ -166,6 +166,10 @@ module IcAgent
 
       attr_accessor :identity, :client, :agent, :canister
 
+      # Constructor for the Ledger class.
+      #
+      # Parameters:
+      # - iden: (Optional) An instance of the Identity class.
       def initialize(iden = nil)
         @identity = iden.nil? ? IcAgent::Identity.new : iden
         @client = IcAgent::Client.new

data/lib/ic_agent/common/management.rb

@@ -182,6 +182,10 @@ module IcAgent
 
       attr_accessor :identity, :client, :agent, :canister
 
+      # Constructor for the Management class.
+      #
+      # Parameters:
+      # - iden: (Optional) An instance of the Identity class.
       def initialize(iden = nil)
         @identity = iden.nil? ? IcAgent::Identity.new : iden
         @client = IcAgent::Client.new

data/lib/ic_agent/identity.rb

@@ -11,6 +11,12 @@ module IcAgent
   class Identity
     attr_reader :privkey, :pubkey, :der_pubkey, :sk, :vk, :key_type
 
+    # Initializes a new instance of the Identity class.
+    #
+    # Parameters:
+    # - privkey: The private key of the identity in hexadecimal format. Defaults to an empty string.
+    # - type: The key type of the identity. Defaults to 'ed25519'.
+    # - anonymous: A flag indicating whether the identity is anonymous. Defaults to false.
     def initialize(privkey = '', type = 'ed25519', anonymous = false)
       privkey = [privkey].pack('H*')
       @anonymous = anonymous
@@ -37,6 +43,12 @@ module IcAgent
       end
     end
 
+    # Creates a new Identity instance from a seed phrase (mnemonic).
+    #
+    # Parameters:
+    # - mnemonic: The seed phrase (mnemonic) used to generate the identity.
+    #
+    # Returns: The Identity instance.
     def self.from_seed(mnemonic)
       seed = Bitcoin::Trezor::Mnemonic.to_seed(mnemonic)
       privkey = seed[0..63]
@@ -44,6 +56,9 @@ module IcAgent
       Identity.new(privkey = privkey, type = key_type)
     end
 
+    # Returns the sender Principal associated with the Identity.
+    #
+    # Returns: The sender Principal.
     def sender
       if @anonymous
         IcAgent::Principal.anonymous
@@ -52,6 +67,12 @@ module IcAgent
       end
     end
 
+    # Signs a message using the Identity.
+    #
+    # Parameters:
+    # - msg: The message to sign.
+    #
+    # Returns: An array containing the DER-encoded public key and the signature.
     def sign(msg)
       if @anonymous
         [nil, nil]
@@ -65,6 +86,13 @@ module IcAgent
       end
     end
 
+    # Verifies a message signature using the Identity.
+    #
+    # Parameters:
+    # - msg: The message to verify.
+    # - sig: The signature to verify.
+    #
+    # Returns: `true` if the signature is valid, otherwise `false`.
     def verify(msg, sig)
       if @anonymous
         false
@@ -73,6 +101,9 @@ module IcAgent
       end
     end
 
+    # Returns the PEM-encoded private key of the Identity.
+    #
+    # Returns: The PEM-encoded private key.
     def to_pem
       der = @key_type == 'secp256k1' ? "#{IcAgent::IC_PUBKEY_SECP_DER_HERD}#{@sk.data.unpack1('H*')}".hex2str : "#{IcAgent::IC_PUBKEY_ED_DER_HEAD}#{@sk.to_bytes.unpack1('H*')}".hex2str
       b64 = Base64.strict_encode64(der)
@@ -92,20 +123,41 @@ module IcAgent
   class DelegateIdentity
     attr_reader :identity, :delegations, :der_pubkey
 
+    # Initializes a new instance of the DelegateIdentity class.
+    #
+    # Parameters:
+    # - identity: The Identity associated with the DelegateIdentity.
+    # - delegation: The delegation JSON object containing the delegated keys.
     def initialize(identity, delegation)
       @identity = identity
       @delegations = delegation['delegations'].map { |d| d }
       @der_pubkey = [delegation['publicKey']].pack('H*')
     end
 
+    # Signs a message using the DelegateIdentity.
+    #
+    # Parameters:
+    # - msg: The message to sign.
+    #
+    # Returns: An array containing the DER-encoded public key and the signature.
     def sign(msg)
       @identity.sign(msg)
     end
 
+    # Returns the sender Principal associated with the DelegateIdentity.
+    #
+    # Returns: The sender Principal.
     def sender
       Principal.self_authenticating(@der_pubkey)
     end
 
+    # Creates a new DelegateIdentity instance from JSON representations of the Identity and delegation.
+    #
+    # Parameters:
+    # - ic_identity: The JSON representation of the Identity.
+    # - ic_delegation: The JSON representation of the delegation.
+    #
+    # Returns: The DelegateIdentity instance.
     def self.from_json(ic_identity, ic_delegation)
       parsed_ic_identity = JSON.parse(ic_identity)
       parsed_ic_delegation = JSON.parse(ic_delegation)

data/lib/ic_agent/principal.rb

@@ -7,16 +7,21 @@ module IcAgent
   MAX_LENGTH_IN_BYTES = 29
 
   class PrincipalSort
-    OpaqueId = 1
-    SelfAuthenticating = 2
-    DerivedId = 3
-    Anonymous = 4
+    OPAQUE_ID = 1
+    SELF_AUTHENTICATING = 2
+    DERIVED_ID = 3
+    ANONYMOUS = 4
     # Unassigned
   end
 
+  # Base class for Principal.
   class Principal
     attr_reader :len, :bytes, :is_principal, :hex
 
+    # Initializes a new instance of the Principal class.
+    #
+    # Parameters:
+    # - bytes: The bytes representing the principal. Defaults to an empty string.
     def initialize(bytes: ''.b)
       @len = bytes.length
       @bytes = bytes
@@ -24,23 +29,41 @@ module IcAgent
       @is_principal = true
     end
 
+    # Creates a new Principal instance representing the management canister.
+    #
+    # Returns: The Principal instance representing the management canister.
     def self.management_canister
       Principal.new
     end
 
+    # Creates a new self-authenticating Principal.
+    #
+    # Parameters:
+    # - pubkey: The public key associated with the self-authenticating Principal.
+    #
+    # Returns: The self-authenticating Principal instance.
     def self.self_authenticating(pubkey)
       # check pubkey.size for is ed25519 or secp256k1
       pubkey = [pubkey].pack('H*') if pubkey.size != 44 && pubkey.size != 88
 
       hash_ = OpenSSL::Digest::SHA224.digest(pubkey)
-      hash_ += [PrincipalSort::SelfAuthenticating].pack('C')
+      hash_ += [PrincipalSort::SELF_AUTHENTICATING].pack('C')
       Principal.new(bytes: hash_)
     end
 
+    # Creates a new anonymous Principal.
+    #
+    # Returns: The anonymous Principal instance.
     def self.anonymous
       Principal.new(bytes: "\x04".b)
     end
 
+    # Creates a new Principal from a string representation.
+    #
+    # Parameters:
+    # - s: The string representation of the Principal.
+    #
+    # Returns: The Principal instance.
     def self.from_str(s)
       s1 = s.delete('-')
       pad_len = ((s1.length / 8.0).ceil * 8) - s1.length
@@ -53,10 +76,19 @@ module IcAgent
       p
     end
 
+    # Creates a new Principal from a hexadecimal string representation.
+    #
+    # Parameters:
+    # - s: The hexadecimal string representation of the Principal.
+    #
+    # Returns: The Principal instance.
     def self.from_hex(s)
       Principal.new(bytes: [s].pack('H*'))
     end
 
+    # Converts the Principal to a string representation.
+    #
+    # Returns: The string representation of the Principal.
     def to_str
       checksum = Zlib.crc32(@bytes) & 0xFFFFFFFF
       b = ''
@@ -71,6 +103,12 @@ module IcAgent
       ret + s
     end
 
+    # Converts the Principal to an AccountIdentifier.
+    #
+    # Parameters:
+    # - sub_account: The sub-account identifier. Defaults to 0.
+    #
+    # Returns: The AccountIdentifier instance.
     def to_account_id(sub_account = 0)
       AccountIdentifier.generate(self, sub_account)
     end
@@ -78,17 +116,70 @@ module IcAgent
     def to_s
       to_str
     end
+
+    # Compares the Principal with another Principal.
+    #
+    # Parameters:
+    # - other: The other Principal to compare with.
+    #
+    # Returns: The comparison result as a string ('lt', 'eq', or 'gt').
+    def compare_to(other)
+      (0...[self.bytes.length, other.bytes.length].min).each do |i|
+        if self.bytes[i] < other.bytes[i]
+          return 'lt'
+        elsif self.bytes[i] > other.bytes[i]
+          return 'gt'
+        end
+      end
+
+      if self.bytes.length < other.bytes.length
+        'lt'
+      elsif self.bytes.length > other.bytes.length
+        'gt'
+      else
+        'eq'
+      end
+    end
+
+    # Utility method checking whether a provided Principal is less than or equal to the current one using the `compare_to` method.
+    #
+    # Parameters:
+    # - other: The other Principal to compare with.
+    #
+    # Returns: `true` if the current Principal is less than or equal to the provided Principal, otherwise `false`.
+    def lt_eq(other)
+      cmp = compare_to(other)
+      %w[lt eq].include?(cmp)
+    end
+
+    # Utility method checking whether a provided Principal is greater than or equal to the current one using the `compare_to` method.
+    #
+    # Parameters:
+    # - other: The other Principal to compare with.
+    #
+    # Returns: `true` if the current Principal is greater than or equal to the provided Principal, otherwise `false`.
+    def gt_eq(other)
+      cmp = compare_to(other)
+      %w[gt eq].include?(cmp)
+    end
   end
 
   class AccountIdentifier
     attr_reader :bytes
 
+    # Initializes a new instance of the AccountIdentifier class.
+    #
+    # Parameters:
+    # - hash: The hash representing the AccountIdentifier.
     def initialize(hash)
       raise 'Invalid hash length' unless hash.length == 32
 
       @bytes = hash
     end
 
+    # Converts the AccountIdentifier to a string representation.
+    #
+    # Returns: The string representation of the AccountIdentifier.
     def to_str
       '0x' + @bytes.unpack1('H*')
     end
@@ -97,12 +188,19 @@ module IcAgent
       to_str
     end
 
+    # Generates a new AccountIdentifier from a Principal.
+    #
+    # Parameters:
+    # - principal: The Principal associated with the AccountIdentifier.
+    # - sub_account: The sub-account identifier. Defaults to 0.
+    #
+    # Returns: The AccountIdentifier instance.
     def self.generate(principal, sub_account = 0)
       sha224 = OpenSSL::Digest::SHA224.new
       sha224 << "\naccount-id"
       sha224 << principal.bytes
       format_sub_account = "%08d" % sub_account
-      sub_account = format_sub_account.chars.map {|c| c.to_i}.pack('N*')
+      sub_account = format_sub_account.chars.map { |c| c.to_i }.pack('N*')
       sha224 << sub_account
       hash = sha224.digest
       checksum = Zlib.crc32(hash) & 0xFFFFFFFF

data/lib/ic_agent/system_state.rb

@@ -5,6 +5,13 @@ require 'cbor'
 
 module IcAgent
   class SyetemState
+    # Retrieves the system time from a canister's state.
+    #
+    # Parameters:
+    # - agent: The IcAgent::Client instance.
+    # - canister_id: The ID of the canister.
+    #
+    # Returns: The system time as a timestamp.
     def self.time(agent, canister_id)
       cert = agent.read_state_raw(canister_id, [['time']])
       timestamp = Certificate.lookup(['time'], cert)
@@ -12,6 +19,14 @@ module IcAgent
       LEB128.decode_signed(str_io)
     end
 
+    # Retrieves the public key of a subnet from a canister's state.
+    #
+    # Parameters:
+    # - agent: The IcAgent::Client instance.
+    # - canister_id: The ID of the canister.
+    # - subnet_id: The ID of the subnet.
+    #
+    # Returns: The public key of the subnet in hexadecimal format.
     def self.subnet_public_key(agent, canister_id, subnet_id)
       path = ['subnet', Principal.from_str(subnet_id).bytes, 'public_key']
       cert = agent.read_state_raw(canister_id, [path])
@@ -19,6 +34,14 @@ module IcAgent
       pubkey.str2hex
     end
 
+    # Retrieves the canister ranges of a subnet from a canister's state.
+    #
+    # Parameters:
+    # - agent: The IcAgent::Client instance.
+    # - canister_id: The ID of the canister.
+    # - subnet_id: The ID of the subnet.
+    #
+    # Returns: An array of canister ranges, where each range is represented as an array of Principal instances.
     def self.subnet_canister_ranges(agent, canister_id, subnet_id)
       path = ['subnet', Principal.from_str(subnet_id).bytes, 'canister_ranges']
       cert = agent.read_state_raw(canister_id, [path])
@@ -26,6 +49,13 @@ module IcAgent
       CBOR.decode(ranges).value.map { |range| range.map { |item| Principal.new(bytes: item) } }
     end
 
+    # Retrieves the module hash of a canister from a canister's state.
+    #
+    # Parameters:
+    # - agent: The IcAgent::Client instance.
+    # - canister_id: The ID of the canister.
+    #
+    # Returns: The module hash of the canister in hexadecimal format.
     def self.canister_module_hash(agent, canister_id)
       path = ['canister', Principal.from_str(canister_id).bytes, 'module_hash']
       cert = agent.read_state_raw(canister_id, [path])
@@ -33,6 +63,13 @@ module IcAgent
       module_hash.str2hex
     end
 
+    # Retrieves the controllers of a canister from a canister's state.
+    #
+    # Parameters:
+    # - agent: The IcAgent::Client instance.
+    # - canister_id: The ID of the canister.
+    #
+    # Returns: An array of Principal instances representing the controllers of the canister.
     def self.canister_controllers(agent, canister_id)
       path = ['canister', Principal.from_str(canister_id).bytes, 'controllers']
       cert = agent.read_state_raw(canister_id, [path])

data/lib/ic_agent/utils.rb

@@ -3,6 +3,12 @@ require 'leb128'
 
 module IcAgent
   module Utils
+    # Encodes a list of items into a binary string.
+    #
+    # Parameters:
+    # - l: The list of items to encode.
+    #
+    # Returns: The binary string representation of the encoded list.
     def self.encode_list(l)
       ret = ''
       l.each do |item|
@@ -21,7 +27,12 @@ module IcAgent
       ret
     end
 
-    # used for sort record by key
+    # Computes a hash value for sorting records by key.
+    #
+    # Parameters:
+    # - s: The key to hash.
+    #
+    # Returns: The computed hash value.
     def self.label_hash(s)
       if s =~ /(^_\d+_$)|(^_0x[0-9a-fA-F]+_$)/
         num = s[1..-2]
@@ -41,6 +52,12 @@ module IcAgent
       idl_hash(s)
     end
 
+    # Computes a hash value for an IDL string.
+    #
+    # Parameters:
+    # - s: The IDL string to hash.
+    #
+    # Returns: The computed hash value.
     def self.idl_hash(s)
       h = 0
       s.bytes.each do |c|
@@ -49,6 +66,12 @@ module IcAgent
       h
     end
 
+    # Converts a data structure into a request ID.
+    #
+    # Parameters:
+    # - d: The data structure to convert.
+    #
+    # Returns: The request ID as a binary string.
     def self.to_request_id(d)
       return nil unless d.is_a?(Hash)
 
@@ -67,9 +90,14 @@ module IcAgent
       Digest::SHA256.digest(s)
     end
 
+    # Decodes a binary blob into a string.
+    #
+    # Parameters:
+    # - blob_bytes: The binary blob to decode.
+    #
+    # Returns: The decoded string.
     def self.decode_blob(blob_bytes)
       blob_bytes.pack('C*')
     end
   end
 end
-

data/lib/ic_agent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IcAgent
-  VERSION = '0.1.4'
+  VERSION = '0.2.1'
 end