ic_agent 0.1.4 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 872963d331d311c6a940f64445ef0583397885eb9455464f4d865d325f24ee97
-  data.tar.gz: 8b11f6cc71864468b52e66a6577fb3002bcf14cfde2ce93b1dfb6f819eb1df84
+  metadata.gz: b1bb3c395959ef0b33094ab3e34a6087b061a76287ce34b312286703c568fade
+  data.tar.gz: f71667c7d06d470c89afd7d9e8734bfded8abc2f7d85a89a77d84fa3ce7e210c
 SHA512:
-  metadata.gz: 5ead16aeb03ac87caa4620ee9f813e7d79399f95d9cb2424cbedd2af828f9dd06f14a1f9d200ac596783ea3b47fdd88f500256608e972011e1dae01e69452cf4
-  data.tar.gz: d6ebbda49c03f1e2df8fe3e28ffd2b53424a83e04b386841f8874c6b888f4089d8c0150194930ffdab836e81961cfc657168a6e225e0ddd32c665d03159e1cc3
+  metadata.gz: 437bab4be804cc57aa1098aa91275d88623e79c98f9190129956eb2ceb0447dd5dbd305ec7425b3a3fd7fc945035a79329b6a73052c876bc31118a94387cb61a
+  data.tar.gz: 05adc3829656980d0a833ac495cbfbf67e84fee5474dda75e39d6f94fb538ee22120de034ba7b81c36680ef4444a586409ecb2c6f0f43d53f9cd7aa28b51e394

data/Gemfile

@@ -7,6 +7,7 @@ gemspec
 
 gem 'base32', '~> 0.3.4'
 gem 'bitcoin-ruby', '~> 0.0.20'
+gem 'bls12-381', '~> 0.3.0'
 gem 'byebug', '~> 11.1', '>= 11.1.3'
 gem 'cbor', '~> 0.5.9.6'
 gem 'ctf-party', '~> 2.3'

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    ic_agent (0.1.4)
+    ic_agent (0.2.1)
       base32 (~> 0.3.4)
       bitcoin-ruby (~> 0.0.20)
+      bls12-381 (~> 0.3.0)
       cbor (~> 0.5.9.6)
       ctf-party (~> 2.3)
       ecdsa (~> 1.2)
@@ -23,6 +24,8 @@ GEM
       eventmachine
       ffi
       scrypt
+    bls12-381 (0.3.0)
+      h2c (~> 0.2.0)
     byebug (11.1.3)
     cbor (0.5.9.6)
     coderay (1.1.3)
@@ -34,7 +37,7 @@ GEM
     ecdsa (1.2.0)
     ed25519 (1.3.0)
     eventmachine (1.2.7)
-    faraday (2.7.4)
+    faraday (2.7.10)
       faraday-net_http (>= 2.0, < 3.1)
       ruby2_keywords (>= 0.0.4)
     faraday-net_http (3.0.2)
@@ -42,13 +45,15 @@ GEM
     ffi-compiler (1.0.1)
       ffi (>= 1.0.0)
       rake
-    i18n (1.12.0)
+    h2c (0.2.0)
+      ecdsa (~> 1.2.0)
+    i18n (1.14.1)
       concurrent-ruby (~> 1.0)
     json (2.6.3)
     leb128 (1.0.0)
     method_source (1.0.0)
-    mini_portile2 (2.8.2)
-    pkg-config (1.5.1)
+    mini_portile2 (2.8.4)
+    pkg-config (1.5.2)
     polyglot (0.3.5)
     pry (0.14.2)
       coderay (~> 1.1)
@@ -62,19 +67,19 @@ GEM
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
       rspec-mocks (~> 3.12.0)
-    rspec-core (3.12.1)
+    rspec-core (3.12.2)
       rspec-support (~> 3.12.0)
-    rspec-expectations (3.12.2)
+    rspec-expectations (3.12.3)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
-    rspec-mocks (3.12.5)
+    rspec-mocks (3.12.6)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
-    rspec-support (3.12.0)
+    rspec-support (3.12.1)
     ruby-enum (0.9.0)
       i18n
     ruby2_keywords (0.0.5)
-    rubytree (2.0.0)
+    rubytree (2.0.2)
       json (~> 2.0, > 2.3.1)
     rubyzip (2.3.2)
     scrypt (3.0.7)
@@ -88,6 +93,7 @@ PLATFORMS
 DEPENDENCIES
   base32 (~> 0.3.4)
   bitcoin-ruby (~> 0.0.20)
+  bls12-381 (~> 0.3.0)
   byebug (~> 11.1, >= 11.1.3)
   cbor (~> 0.5.9.6)
   ctf-party (~> 2.3)

data/README.md

@@ -4,6 +4,8 @@
 
 `ic_agent` provides basic modules to interact with canisters on the DFINITY Internet Computer.
 
+[![Gem Version](https://badge.fury.io/rb/ic_agent.svg)](https://badge.fury.io/rb/ic_agent)[![MIT License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)
+
 
 ## Installation
 

data/ic_agent.gemspec

@@ -17,6 +17,7 @@ Gem::Specification.new do |spec|
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = spec.homepage
   spec.metadata['changelog_uri'] = spec.homepage
+  spec.metadata['documentation_uri'] = 'https://tuminfei.github.io/ic_agent.github.com/'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -33,6 +34,7 @@ Gem::Specification.new do |spec|
   # spec.add_dependency "example-gem", "~> 1.0"
   spec.add_dependency 'base32', '~> 0.3.4'
   spec.add_dependency 'bitcoin-ruby', '~> 0.0.20'
+  spec.add_dependency 'bls12-381', '~> 0.3.0'
   spec.add_dependency 'cbor', '~> 0.5.9.6'
   spec.add_dependency 'ctf-party', '~> 2.3'
   spec.add_dependency 'ecdsa', '~> 1.2'

data/lib/ic_agent/agent.rb

@@ -1,8 +1,15 @@
 require 'cbor'
+require 'bls'
 require 'ctf_party'
+require 'bitcoin'
 
 module IcAgent
   class Request
+    # Signs a request with an identity's signature and encodes it using CBOR.
+    #
+    # @param req [Hash] The request to be signed.
+    # @param iden [Identity] The identity used for signing.
+    # @return [Array] The request ID and the encoded signed request.
     def self.sign_request(req, iden)
       req_id = IcAgent::Utils.to_request_id(req)
       msg = IcAgent::IC_REQUEST_DOMAIN_SEPARATOR + req_id
@@ -26,6 +33,13 @@ module IcAgent
   class Agent
     attr_accessor :identity, :client, :ingress_expiry, :root_key, :nonce_factory
 
+    # Initializes a new IC agent.
+    #
+    # @param identity [Identity] The identity associated with the agent.
+    # @param client [Client] The client used for communication with the IC network.
+    # @param nonce_factory [NonceFactory] The factory for generating nonces.
+    # @param ingress_expiry [Integer] The expiration time for ingress requests.
+    # @param root_key [String] The IC root key used for verification.
     def initialize(identity, client, nonce_factory = nil, ingress_expiry = 300, root_key = IcAgent::IC_ROOT_KEY)
       @identity = identity
       @client = client
@@ -34,14 +48,25 @@ module IcAgent
       @nonce_factory = nonce_factory
     end
 
+    # Retrieves the principal associated with the agent's identity.
+    #
+    # @return [Principal] The principal associated with the agent.
     def get_principal
       @identity.sender
     end
 
+    # Calculates the expiration date for ingress requests.
+    #
+    # @return [Integer] The expiration date in nanoseconds.
     def get_expiry_date
       ((Time.now.to_i + @ingress_expiry) * 10**9).to_i
     end
 
+    # Sends a query request to a canister and decodes the response using CBOR.
+    #
+    # @param canister_id [String] The ID of the target canister.
+    # @param data [Hash] The data to be sent in the query request.
+    # @return [Object] The decoded response from the canister.
     def query_endpoint(canister_id, data)
       ret = @client.query(canister_id, data)
       decode_ret = nil
@@ -54,16 +79,34 @@ module IcAgent
       decode_ret
     end
 
+    # Calls a method on a canister and returns the request ID.
+    #
+    # @param canister_id [String] The ID of the target canister.
+    # @param request_id [String] The ID of the request.
+    # @param data [Hash] The data to be sent in the call request.
+    # @return [String] The request ID.
     def call_endpoint(canister_id, request_id, data)
       @client.call(canister_id, request_id, data)
       request_id
     end
 
+    # Reads the state of a canister.
+    #
+    # @param canister_id [String] The ID of the target canister.
+    # @param data [Hash] The data to be sent in the read state request.
+    # @return [Object] The response from the canister.
     def read_state_endpoint(canister_id, data)
-      result = @client.read_state(canister_id, data)
-      result
+      @client.read_state(canister_id, data)
     end
 
+    # Sends a raw query request to a canister and handles the response.
+    #
+    # @param canister_id [String] The ID of the target canister.
+    # @param method_name [String] The name of the method to be called.
+    # @param arg [String] The argument to be passed to the method.
+    # @param return_type [Object] The expected type of the return value.
+    # @param effective_canister_id [String] The effective canister ID (optional).
+    # @return [Object] The decoded response from the canister.
     def query_raw(canister_id, method_name, arg, return_type = nil, effective_canister_id = nil)
       req_canister_id = canister_id.is_a?(String) ? Principal.from_str(canister_id).bytes : canister_id.bytes
       req = {
@@ -92,6 +135,15 @@ module IcAgent
       end
     end
 
+    # Sends a raw update request to a canister and handles the response.
+    #
+    # @param canister_id [String] The ID of the target canister.
+    # @param method_name [String] The name of the method to be called.
+    # @param arg [String] The argument to be passed to the method.
+    # @param return_type [Object] The expected type of the return value.
+    # @param effective_canister_id [String] The effective canister ID (optional).
+    # @param kwargs [Hash] Additional keyword arguments.
+    # @return [Object] The decoded response from the canister.
     def update_raw(canister_id, method_name, arg, return_type = nil, effective_canister_id = nil, **kwargs)
       req_canister_id = canister_id.is_a?(String) ? Principal.from_str(canister_id).bytes : canister_id.bytes
       req = {
@@ -120,7 +172,13 @@ module IcAgent
       end
     end
 
-    def read_state_raw(canister_id, paths)
+    # Sends a raw read state request to a canister and handles the response.
+    #
+    # @param canister_id [String] The ID of the target canister.
+    # @param paths [Array] The paths to read from the canister's state.
+    # @param [TrueClass] bls_verify
+    # @return [Object] The decoded response from the canister.
+    def read_state_raw(canister_id, paths, bls_verify = true)
       req = {
         'request_type' => 'read_state',
         'sender' => @identity.sender.bytes,
@@ -140,9 +198,20 @@ module IcAgent
       rescue StandardError
         raise ValueError, "Unable to decode cbor value: #{ret}"
       end
-      CBOR.decode(d.value['certificate'])
+      cert = CBOR.decode(d.value['certificate'])
+
+      if bls_verify
+        verify(cert, canister_id) ? cert : false
+      else
+        cert
+      end
     end
 
+    # Retrieves the status and certificate of a request from a canister.
+    #
+    # @param canister_id [String] The ID of the target canister.
+    # @param req_id [String] The ID of the request.
+    # @return [Array] The status and certificate of the request.
     def request_status_raw(canister_id, req_id)
       paths = [['request_status', req_id]]
       cert = read_state_raw(canister_id, paths)
@@ -150,6 +219,12 @@ module IcAgent
       [status, cert]
     end
 
+    # Polls a canister for the status of a request.
+    #
+    # @param canister_id [String] The ID of the target canister.
+    # @param req_id [String] The ID of the request.
+    # @param delay [Integer] The delay between each poll attempt (in seconds).
+    # @param timeout [Integer] The maximum timeout for polling.
     def poll(canister_id, req_id, delay = 1, timeout = IcAgent::DEFAULT_POLL_TIMEOUT_SECS)
       status = nil
       cert = nil
@@ -172,5 +247,80 @@ module IcAgent
         [status, _]
       end
     end
+
+    # Verify a BLS signature
+    # The signature must be exactly 48 bytes (compressed G1 element)
+    # The key must be exactly 96 bytes (compressed G2 element)
+    def verify(cert, canister_id)
+      signature_hex = IcAgent::Certificate.signature(cert).str2hex
+      tree = IcAgent::Certificate.tree(cert)
+      delegation = IcAgent::Certificate.delegation(cert)
+      root_hash = IcAgent::Certificate.reconstruct(tree).str2hex
+      msg = IcAgent::IC_STATE_ROOT_DOMAIN_SEPARATOR + root_hash
+      der_key = check_delegation(delegation, canister_id, true)
+      public_key_hash = extract_der(der_key).str2hex
+
+      public_key = BLS::PointG2.from_hex(public_key_hash)
+      signature = BLS::PointG1.from_hex(signature_hex)
+      BLS.verify(signature, msg, public_key)
+    end
+
+    # Check the delegation and return the corresponding root key.
+    def check_delegation(delegation, effective_canister_id, disable_range_check)
+      return @root_key unless delegation
+
+      begin
+        cert = CBOR.decode(delegation['certificate'])
+      rescue CBOR::MalformedFormatError => e
+        raise TypeError, "certificate CBOR::MalformedFormatError: #{delegation['certificate']}"
+      end
+
+      path = ['subnet', delegation['subnet_id'], 'canister_ranges']
+      canister_range =  IcAgent::Certificate.lookup(path, cert)
+
+      begin
+        ranges = []
+        ranges_json = CBOR.decode(canister_range).values[1]
+
+        ranges_json.each do |range_json|
+          range = {}
+          range['low'] = Principal.from_hex(range_json[0])
+          range['high'] = Principal.from_hex(range_json[1])
+          ranges << range
+        end
+
+        if !disable_range_check && !principal_is_within_ranges(effective_canister_id, ranges)
+          raise AgentError 'certificate CERTIFICATE_NOT_AUTHORIZED'
+        end
+      rescue Exception => e
+        raise AgentError "certificate INVALID_CBOR_DATA, canister_range: #{canister_range.to_s}"
+      end
+
+      path = ['subnet', delegation['subnet_id'], 'public_key']
+      IcAgent::Certificate.lookup(path, cert)
+    end
+
+    def principal_is_within_ranges(principal, ranges)
+      ranges.each do |range|
+        return true if range['low'].lt_eq(principal) && range['high'].gt_eq(principal)
+      end
+      false
+    end
+
+    # Extract the BLS public key from the DER buffer.
+    def extract_der(der_buf)
+      bls_der_prefix = OpenSSL::BN.from_hex(IcAgent::BLS_DER_PREFIX).to_s(2)
+      expected_length = bls_der_prefix.bytesize + IcAgent::BLS_KEY_LENGTH
+      if der_buf.bytesize != expected_length
+        raise TypeError, "BLS DER-encoded public key must be #{expected_length} bytes long"
+      end
+
+      prefix = der_buf.byteslice(0, bls_der_prefix.bytesize)
+      if prefix != bls_der_prefix
+        raise TypeError, "BLS DER-encoded public key is invalid. Expect the following prefix: #{bls_der_prefix}, but get #{prefix}"
+      end
+
+      der_buf.byteslice(bls_der_prefix.bytesize..-1)
+    end
   end
 end

data/lib/ic_agent/ast/assembler.rb

@@ -5,24 +5,30 @@ module IcAgent
     class Assembler
       TYPE_MAPPING = {}
 
+      # Builds a single Candid type from a given child type.
       def self.build_single_type(child_type)
         IcAgent::Candid::BaseTypes.send(child_type)
       end
 
+
+      # Builds a Candid blob type.
       def self.build_blob
         IcAgent::Candid::BaseTypes.vec(IcAgent::Candid::BaseTypes.nat8)
       end
 
+      # Builds a Candid optional type from a given child type.
       def self.build_opt(child_type, key_types = {})
         child_type = key_types[child_type].nil? ? build_type(child_type, key_types) : key_types[child_type]
         IcAgent::Candid::BaseTypes.opt(child_type)
       end
 
+      # Builds a Candid vector type from a given child type.
       def self.build_vec(child_type, key_types = {})
         child_type = key_types[child_type].nil? ? build_type(child_type, key_types) : key_types[child_type]
         IcAgent::Candid::BaseTypes.vec(child_type)
       end
 
+      # Builds a Candid record type from a given hash of field names and types.
       def self.build_record(child_hash, multi_types = {}, key_types = {})
         child_types = {}
         child_hash.each_key do |key|
@@ -38,6 +44,7 @@ module IcAgent
         IcAgent::Candid::BaseTypes.record(child_types)
       end
 
+      # Builds a Candid variant type from a given hash of field names and types.
       def self.build_variant(child_hash, multi_types = {}, key_types = {})
         child_types = {}
         child_hash.each_key do |key|
@@ -53,6 +60,7 @@ module IcAgent
         IcAgent::Candid::BaseTypes.variant(child_types)
       end
 
+      # Builds a Candid type based on the given type string.
       def self.build_type(type_str, key_types = {}, multi_types = {})
         opt_code = get_opt_code(type_str)
 
@@ -91,6 +99,7 @@ module IcAgent
         end
       end
 
+      # Replaces the last occurrence of a pattern in a string with the given replacement.
       def self.replace_last_occurrence(string, pattern, replacement)
         last_index = string.rindex(pattern)
         return string unless last_index
@@ -99,18 +108,21 @@ module IcAgent
         string
       end
 
+      # Extracts the content of a Candid record type from the type string.
       def self.get_record_content(record_str)
         record_str = record_str.sub('record', '').sub('{', '')
         record_str = replace_last_occurrence(record_str, '}', '')
         record_str.strip
       end
 
+      # Extracts the content of a Candid variant type from the type string.
       def self.get_variant_content(variant_str)
         variant_str = variant_str.sub('variant', '').sub('{', '')
         variant_str = replace_last_occurrence(variant_str, '}', '')
         variant_str.strip
       end
 
+      # Extracts the key-value pairs from a Candid record item string.
       def self.get_record_key_value(item_str, index_str, key_index = 0)
         first_index = item_str.index(index_str)
         if first_index
@@ -123,16 +135,19 @@ module IcAgent
         return key, value
       end
 
+      # Extracts the Candid code (e.g., "record", "variant", "opt", etc.) from the type string.
       def self.get_opt_code(item_str)
         opt_code = item_str.strip
         opt_code.split(' ')[0]
       end
 
+      # Extracts the child Candid code from the type string.
       def self.get_child_code(item_str, index_str)
         first_index = item_str.index(index_str)
         item_str[(first_index + index_str.size)..].strip
       end
 
+      # Replaces occurrences of Candid record and variant types with unique type names.
       def self.replace_multi_type(type_str)
         replaced_hash = {}
         modified_str = type_str.gsub(/record\s*{[^{}]*}/) do |match|
@@ -152,6 +167,7 @@ module IcAgent
         return modified_str, replaced_hash
       end
 
+      # Gets the refer types used in the type string.
       def self.get_params_refer_values(type_str)
         parser = IcAgent::Ast::StatementParser.new
         parser.parse(type_str)
@@ -159,6 +175,7 @@ module IcAgent
         refer_type
       end
 
+      # Recovers the original type string from the multi_types hash.
       def self.recover_type(type_str, multi_types)
         multi_types.each_key do |key|
           type_str = type_str.gsub(key, multi_types[key])