mixin_bot 1.4.0 → 2.0.0

data/lib/mixin_bot/utils/crypto.rb

@@ -2,7 +2,65 @@
 
 module MixinBot
   module Utils
+    ##
+    # Cryptographic utility methods for Mixin Network operations.
+    #
+    # This module provides essential cryptographic functions including:
+    # - JWT token generation for API authentication
+    # - Ed25519 and RSA key generation
+    # - PIN encryption/decryption
+    # - Transaction signing
+    # - UUID generation and derivation
+    # - Ghost key derivation for Safe API
+    #
+    # == Key Types
+    #
+    # Mixin Network uses several types of cryptographic keys:
+    #
+    # [Session Key] Ed25519 or RSA key for API authentication
+    # [Spend Key] Ed25519 key for signing transactions (Safe API)
+    # [View Key] Ed25519 key for viewing transactions
+    # [PIN Key] For legacy PIN operations
+    #
+    # == Signature Algorithm
+    #
+    # Safe API uses Ed25519 with Blake3 hashing for transaction signing.
+    # This provides quantum-resistant security with compact signatures.
+    #
     module Crypto
+      ##
+      # Generates a JWT access token for API authentication.
+      #
+      # Creates a signed JWT token containing request details and credentials.
+      # The token is used in the Authorization header for API requests.
+      #
+      # Token payload includes:
+      # - uid: user/bot ID
+      # - sid: session ID
+      # - iat: issued at timestamp
+      # - exp: expiration timestamp
+      # - jti: unique token ID
+      # - sig: SHA-256 hash of request (method + uri + body)
+      # - scp: scope (usually 'FULL')
+      #
+      # @param method [String] HTTP method (GET, POST, etc.)
+      # @param uri [String] request URI path
+      # @param body [String] request body (empty for GET)
+      # @param kwargs [Hash] additional options
+      # @option kwargs [Integer] :exp_in (600) token lifetime in seconds
+      # @option kwargs [String] :scp ('FULL') token scope
+      # @option kwargs [String] :app_id bot application ID
+      # @option kwargs [String] :session_id session ID
+      # @option kwargs [String] :private_key session private key
+      #
+      # @return [String] JWT token
+      #
+      # @raise [ConfigurationNotValidError] if private_key is missing
+      #
+      # @example
+      #   token = MixinBot.utils.access_token('GET', '/me', '')
+      #   # Use in request: Authorization: Bearer #{token}
+      #
       def access_token(method, uri, body = '', **kwargs)
         sig = Digest::SHA256.hexdigest(method + uri + body.to_s)
         iat = Time.now.utc.to_i
@@ -37,6 +95,19 @@ module MixinBot
         JOSE::JWT.sign(jwk, jws, jwt).compact
       end
 
+      ##
+      # Generates a new Ed25519 keypair.
+      #
+      # Ed25519 is the recommended key type for Mixin Network.
+      # It provides strong security with compact keys and signatures.
+      #
+      # @return [Hash] hash containing :private_key and :public_key (Base64-encoded)
+      #
+      # @example
+      #   keys = MixinBot.utils.generate_ed25519_key
+      #   puts "Private: #{keys[:private_key]}"
+      #   puts "Public: #{keys[:public_key]}"
+      #
       def generate_ed25519_key
         ed25519_key = JOSE::JWA::Ed25519.keypair
         {
@@ -45,6 +116,18 @@ module MixinBot
         }
       end
 
+      ##
+      # Generates a new RSA keypair.
+      #
+      # RSA keys are supported for backward compatibility but
+      # Ed25519 is recommended for new applications.
+      #
+      # @return [Hash] hash containing :private_key and :public_key (PEM format)
+      #
+      # @example
+      #   keys = MixinBot.utils.generate_rsa_key
+      #   puts keys[:private_key]
+      #
       def generate_rsa_key
         rsa_key = OpenSSL::PKey::RSA.new 1024
         {
@@ -53,10 +136,26 @@ module MixinBot
         }
       end
 
+      ##
+      # Derives a public key from a private key.
+      #
+      # Used internally for cryptographic operations.
+      #
+      # @param key [String] the private key (64 bytes)
+      # @return [String] the derived public key
+      #
       def shared_public_key(key)
         (JOSE::JWA::Edwards25519Point.stdbase * scalar_from_bytes(key[...64]).x.to_i).encode
       end
 
+      ##
+      # Converts raw bytes to a scalar for Ed25519 operations.
+      #
+      # Used internally for cryptographic calculations.
+      #
+      # @param raw [String] raw bytes
+      # @return [JOSE::JWA::FieldElement] the scalar value
+      #
       def scalar_from_bytes(raw)
         JOSE::JWA::FieldElement.new(
           # https://github.com/potatosalad/ruby-jose/blob/e1be589b889f1e59ac233a5d19a3fa13f1e4b8a0/lib/jose/jwa/x25519.rb#L122C14-L122C48
@@ -100,6 +199,29 @@ module MixinBot
         MixinBot::UUID.new(raw: cipher).unpacked
       end
 
+      ##
+      # Generates a unique UUID from multiple UUIDs.
+      #
+      # Creates a deterministic UUID by combining multiple UUIDs.
+      # The result is always the same for the same set of input UUIDs,
+      # regardless of order (after sorting).
+      #
+      # This is used for:
+      # - Creating conversation IDs
+      # - Generating multisig addresses
+      # - Creating deterministic identifiers
+      #
+      # @param uuids [Array<String>] array of UUIDs to combine
+      # @return [String] the unique combined UUID
+      #
+      # @example
+      #   uuid = MixinBot.utils.unique_uuid(
+      #     'user1-uuid',
+      #     'user2-uuid',
+      #     'user3-uuid'
+      #   )
+      #   puts uuid  # Always the same for these inputs
+      #
       def unique_uuid(*uuids)
         uuids = uuids.flatten.compact
         uuids.sort
@@ -111,6 +233,28 @@ module MixinBot
         r
       end
 
+      ##
+      # Generates a group conversation ID.
+      #
+      # Creates a deterministic conversation ID for a group based on:
+      # - Owner ID
+      # - Group name
+      # - Participant IDs
+      # - Random ID (optional, for creating different groups with same members)
+      #
+      # @param user_ids [Array<String>] array of participant user IDs
+      # @param name [String] the group name
+      # @param owner_id [String] the group owner's user ID
+      # @param random_id [String, nil] optional random ID for uniqueness
+      # @return [String] the conversation UUID
+      #
+      # @example
+      #   conv_id = MixinBot.utils.generate_group_conversation_id(
+      #     user_ids: ['user1', 'user2', 'user3'],
+      #     name: 'My Group',
+      #     owner_id: 'owner-id'
+      #   )
+      #
       def generate_group_conversation_id(user_ids:, name:, owner_id:, random_id: nil)
         random_id ||= SecureRandom.uuid
 
@@ -129,6 +273,33 @@ module MixinBot
         gid
       end
 
+      def generate_user_checksum(sessions)
+        list = Array(sessions).map do |s|
+          s.is_a?(Hash) ? s['session_id'] || s[:session_id] : s.session_id
+        end.compact.sort
+        return '' if list.empty?
+
+        Digest::MD5.hexdigest(list.join)
+      end
+
+      def chunked(source, size)
+        source.each_slice(size).to_a
+      end
+
+      def make_unique_string_slice(strings)
+        strings.uniq
+      end
+
+      def unique_object_id(*args)
+        md5 = Digest::MD5.new
+        args.flatten.compact.each { |s| md5 << s.to_s }
+        digest = md5.digest
+        digest = digest.dup
+        digest[6] = ((digest[6].ord & 0x0f) | 0x30).chr
+        digest[8] = ((digest[8].ord & 0x3f) | 0x80).chr
+        MixinBot::UUID.new(raw: digest).unpacked
+      end
+
       def generate_trace_from_hash(hash, output_index = 0)
         md5 = Digest::MD5.new
         md5 << hash
@@ -153,7 +324,8 @@ module MixinBot
         decode_cipher.update(cipher)
       end
 
-      # use timestamp(timestamp) for iterator as default: must be bigger than the previous, the first time must be greater than 0. After a new session created, it will be reset to 0.
+      # use timestamp(timestamp) for iterator as default: must be bigger than the previous,
+      # the first time must be greater than 0. After a new session created, it will be reset to 0.
       def encrypt_pin(pin, **kwargs)
         pin = MixinBot.utils.decode_key pin
 

data/lib/mixin_bot/utils/decoder.rb

@@ -6,7 +6,7 @@ module MixinBot
       def decode_key(key)
         return if key.blank?
 
-        if key.match?(/\A[\h]{64,}\z/i)
+        if key.match?(/\A\h{64,}\z/i)
           [key].pack('H*')
         elsif key.match?(/^-----BEGIN RSA PRIVATE KEY-----/)
           key.gsub('\\r\\n', "\n").gsub("\r\n", "\n")

data/lib/mixin_bot/utils/encoder.rb

@@ -37,6 +37,19 @@ module MixinBot
         [int].pack('Q*').bytes.reverse
       end
 
+      ##
+      # Big-endian varint-style encoding for deposit amounts (integer or decimal string).
+      #
+      def bytes_of(amount)
+        int =
+          case amount
+          when Integer then amount
+          when String then Integer(amount, 10)
+          else amount.to_i
+          end
+        encode_int(int)
+      end
+
       def encode_int(int)
         raise ArgumentError, 'not integer' unless int.is_a?(Integer)
 

data/lib/mixin_bot/utils.rb

@@ -6,6 +6,51 @@ require_relative 'utils/decoder'
 require_relative 'utils/encoder'
 
 module MixinBot
+  ##
+  # Utility module providing various helper methods for Mixin Network operations.
+  #
+  # This module aggregates utility methods from several sub-modules:
+  #
+  # == Sub-modules
+  #
+  # [MixinBot::Utils::Address] Address-related utilities
+  #   - Main address handling
+  #   - Ghost key derivation
+  #   - Address validation
+  #
+  # [MixinBot::Utils::Crypto] Cryptographic operations
+  #   - JWT token generation
+  #   - Key generation and management
+  #   - Transaction signing
+  #   - PIN encryption
+  #   - UUID generation
+  #
+  # [MixinBot::Utils::Decoder] Data decoding utilities
+  #   - Integer decoding
+  #   - Transaction decoding
+  #   - Key decoding
+  #
+  # [MixinBot::Utils::Encoder] Data encoding utilities
+  #   - Integer encoding
+  #   - Transaction encoding
+  #   - Binary packing
+  #
+  # == Usage
+  #
+  # Access utilities through the MixinBot.utils shortcut:
+  #
+  #   # Generate a unique UUID
+  #   uuid = MixinBot.utils.unique_uuid(uuid1, uuid2)
+  #
+  #   # Generate access token
+  #   token = MixinBot.utils.access_token('GET', '/me', '')
+  #
+  #   # Encode a transaction
+  #   raw = MixinBot.utils.encode_raw_transaction(txn)
+  #
+  #   # Decode a key
+  #   key = MixinBot.utils.decode_key(encoded_key)
+  #
   module Utils
     extend MixinBot::Utils::Address
     extend MixinBot::Utils::Crypto

data/lib/mixin_bot/uuid.rb

@@ -1,9 +1,66 @@
 # frozen_string_literal: true
 
 module MixinBot
+  ##
+  # Utility class for handling Mixin Network UUID format conversions.
+  #
+  # Mixin Network uses UUIDs extensively for identifying:
+  # - Users and bots
+  # - Assets
+  # - Transactions and traces
+  # - Conversations
+  #
+  # == Format Conversions
+  #
+  # This class handles conversions between:
+  # - Standard UUID format: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (36 chars)
+  # - Packed binary format: 16 bytes
+  # - Hex format without dashes: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" (32 chars)
+  #
+  # == Usage
+  #
+  #   # From hex format to UUID
+  #   uuid = MixinBot::UUID.new(hex: '965e5c6e434c3fa9b780c50f43cd955c')
+  #   uuid.unpacked
+  #   # => "965e5c6e-434c-3fa9-b780-c50f43cd955c"
+  #
+  #   # From UUID to packed binary
+  #   uuid = MixinBot::UUID.new(hex: '965e5c6e-434c-3fa9-b780-c50f43cd955c')
+  #   uuid.packed
+  #   # => "\x96^\\nC<?\xA9\xB7\x80\xC5\x0FC\xCD\x95\\"
+  #
+  #   # From packed binary to UUID
+  #   uuid = MixinBot::UUID.new(raw: binary_data)
+  #   uuid.unpacked
+  #   # => "965e5c6e-434c-3fa9-b780-c50f43cd955c"
+  #
   class UUID
-    attr_accessor :hex, :raw
+    ##
+    # @return [String] the UUID in hex format (with or without dashes)
+    attr_accessor :hex
 
+    ##
+    # @return [String] the UUID in packed binary format (16 bytes)
+    attr_accessor :raw
+
+    ##
+    # Initializes a new UUID instance.
+    #
+    # Provide either :hex or :raw parameter. The other format can be
+    # obtained via #packed or #unpacked methods.
+    #
+    # @param args [Hash] initialization options
+    # @option args [String] :hex the UUID in hex format (with or without dashes)
+    # @option args [String] :raw the UUID in packed binary format (16 bytes)
+    #
+    # @raise [MixinBot::InvalidUuidFormatError] if format is invalid
+    #
+    # @example From hex
+    #   uuid = MixinBot::UUID.new(hex: '965e5c6e-434c-3fa9-b780-c50f43cd955c')
+    #
+    # @example From raw binary
+    #   uuid = MixinBot::UUID.new(raw: binary_string)
+    #
     def initialize(**args)
       args = args.with_indifferent_access
 
@@ -14,6 +71,16 @@ module MixinBot
       raise MixinBot::InvalidUuidFormatError if hex.present? && hex.gsub('-', '').size != 32
     end
 
+    ##
+    # Returns the UUID in packed binary format (16 bytes).
+    #
+    # @return [String] 16-byte binary string
+    #
+    # @example
+    #   uuid = MixinBot::UUID.new(hex: '965e5c6e-434c-3fa9-b780-c50f43cd955c')
+    #   uuid.packed
+    #   # => 16-byte binary string
+    #
     def packed
       if raw.present?
         raw
@@ -22,6 +89,16 @@ module MixinBot
       end
     end
 
+    ##
+    # Returns the UUID in standard format with dashes.
+    #
+    # @return [String] UUID in format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+    #
+    # @example
+    #   uuid = MixinBot::UUID.new(raw: binary_string)
+    #   uuid.unpacked
+    #   # => "965e5c6e-434c-3fa9-b780-c50f43cd955c"
+    #
     def unpacked
       _hex =
         if hex.present?

data/lib/mixin_bot/version.rb

@@ -1,5 +1,15 @@
 # frozen_string_literal: true
 
 module MixinBot
-  VERSION = '1.4.0'
+  ##
+  # Current version of the MixinBot gem.
+  #
+  # Follows Semantic Versioning (SemVer):
+  # - MAJOR version for incompatible API changes
+  # - MINOR version for backwards-compatible functionality additions
+  # - PATCH version for backwards-compatible bug fixes
+  #
+  # @see https://semver.org/
+  #
+  VERSION = '2.0.0'
 end

data/lib/mixin_bot.rb

@@ -20,10 +20,16 @@ require 'openssl'
 require 'rbnacl'
 require 'sha3'
 
+require_relative 'mixin_bot/errors'
 require_relative 'mixin_bot/address'
+require_relative 'mixin_bot/models'
 require_relative 'mixin_bot/api'
+require_relative 'mixin_bot/bot_auth'
 require_relative 'mixin_bot/cli'
+require_relative 'mixin_bot/computer'
 require_relative 'mixin_bot/invoice'
+require_relative 'mixin_bot/monitor'
+require_relative 'mixin_bot/url_scheme'
 require_relative 'mixin_bot/utils'
 require_relative 'mixin_bot/nfo'
 require_relative 'mixin_bot/uuid'
@@ -31,8 +37,134 @@ require_relative 'mixin_bot/transaction'
 require_relative 'mixin_bot/version'
 require_relative 'mvm'
 
+##
+# = MixinBot
+#
+# MixinBot is a Ruby SDK for interacting with the Mixin Network API.
+#
+# == Overview
+#
+# Mixin Network is a free and lightning fast peer-to-peer transactional network
+# for digital assets. MixinBot provides a comprehensive Ruby interface to interact
+# with the Mixin Network, including asset management, transfers, messaging, and more.
+#
+# == Installation
+#
+# Add this line to your application's Gemfile:
+#
+#   gem 'mixin_bot'
+#
+# And then execute:
+#
+#   $ bundle install
+#
+# Or install it yourself as:
+#
+#   $ gem install mixin_bot
+#
+# == Quick Start
+#
+# === Configuration
+#
+# Configure your Mixin bot credentials:
+#
+#   MixinBot.configure do
+#     self.app_id = '25696f85-b7b4-4509-8c3f-2684a8fc4a2a'
+#     self.client_secret = 'd9dc58107bacde671...'
+#     self.session_id = '25696f85-b7b4-4509-8c3f-2684a8fc4a2a'
+#     self.server_public_key = 'b0pjBUKI0Vp9K+NspaL....'
+#     self.session_private_key = '...'
+#   end
+#
+# === Basic Usage
+#
+# Get bot profile:
+#
+#   MixinBot.api.me
+#   # => { "user_id" => "...", "full_name" => "...", ... }
+#
+# Get bot assets:
+#
+#   MixinBot.api.assets
+#   # => [{ "asset_id" => "...", "symbol" => "BTC", ... }, ...]
+#
+# Transfer assets:
+#
+#   MixinBot.api.create_transfer(
+#     '123456',                                              # pin_code
+#     asset_id: '965e5c6e-434c-3fa9-b780-c50f43cd955c',     # CNB
+#     opponent_id: '6ae1c7ae-1df1-498e-8f21-d48cb6d129b5',  # receiver
+#     amount: 0.00000001,
+#     memo: 'test transfer',
+#     trace_id: SecureRandom.uuid
+#   )
+#
+# === Managing Multiple Bots
+#
+# You can manage multiple bots by creating separate API instances:
+#
+#   bot1 = MixinBot::API.new(
+#     app_id: '...',
+#     session_id: '...',
+#     session_private_key: '...',
+#     server_public_key: '...'
+#   )
+#
+#   bot2 = MixinBot::API.new(
+#     app_id: '...',
+#     session_id: '...',
+#     session_private_key: '...',
+#     server_public_key: '...'
+#   )
+#
+#   bot1.me
+#   bot2.me
+#
+# == Main Components
+#
+# [MixinBot::API] Main API interface for interacting with Mixin Network
+# [MixinBot::Configuration] Configuration management for bot credentials
+# [MixinBot::Client] HTTP client for making API requests
+# [MixinBot::Utils] Utility methods for cryptography and encoding
+# [MixinBot::Transaction] Transaction encoding and decoding
+# [MixinBot::MixAddress] Address handling for Mixin Network
+# [MixinBot::Invoice] Invoice creation and parsing
+# [MixinBot::Nfo] NFT memo handling
+# [MixinBot::UUID] UUID utilities for Mixin Network
+# [MVM] Mixin Virtual Machine integration
+#
+# == Error Handling
+#
+# MixinBot defines several custom error classes for different scenarios:
+#
+#   begin
+#     MixinBot.api.create_transfer(...)
+#   rescue MixinBot::InsufficientBalanceError => e
+#     puts "Insufficient balance: #{e.message}"
+#   rescue MixinBot::UnauthorizedError => e
+#     puts "Unauthorized: #{e.message}"
+#   rescue MixinBot::ResponseError => e
+#     puts "API error: #{e.message}"
+#   end
+#
+# == Links
+#
+# - {Mixin Network Documentation}[https://developers.mixin.one/docs]
+# - {GitHub Repository}[https://github.com/an-lee/mixin_bot]
+#
 module MixinBot
   class << self
+    ##
+    # Returns the default API instance using the global configuration.
+    #
+    # This is a singleton instance that will be created on first access.
+    # The API instance provides access to all Mixin Network API endpoints.
+    #
+    #   MixinBot.api.me
+    #   # => { "user_id" => "...", "full_name" => "..." }
+    #
+    # @return [MixinBot::API] the default API instance
+    #
     def api
       return @api if defined?(@api)
 
@@ -40,6 +172,14 @@ module MixinBot
       @api
     end
 
+    ##
+    # Returns the global configuration instance.
+    #
+    # The configuration instance stores bot credentials and settings.
+    # It will be created on first access with default values.
+    #
+    # @return [MixinBot::Configuration] the configuration instance
+    #
     def config
       return @config if defined?(@config)
 
@@ -47,30 +187,44 @@ module MixinBot
       @config
     end
 
+    ##
+    # Configures the global MixinBot settings.
+    #
+    # This method yields the configuration instance to a block where
+    # you can set your bot credentials and other settings.
+    #
+    #   MixinBot.configure do
+    #     self.app_id = '25696f85-b7b4-4509-8c3f-2684a8fc4a2a'
+    #     self.session_id = '25696f85-b7b4-4509-8c3f-2684a8fc4a2a'
+    #     self.session_private_key = '...'
+    #     self.server_public_key = '...'
+    #   end
+    #
+    # @yield [Configuration] the configuration instance
+    # @return [void]
+    #
     def configure(&)
       config.instance_exec(&)
     end
 
+    ##
+    # Returns the Utils module for accessing utility methods.
+    #
+    #   MixinBot.utils.unique_uuid(uuid1, uuid2)
+    #
+    # @return [Module] the Utils module
+    #
     def utils
       MixinBot::Utils
     end
-  end
 
-  class Error < StandardError; end
-  class ArgumentError < StandardError; end
-  class HttpError < Error; end
-  class RequestError < Error; end
-  class ResponseError < Error; end
-  class NotFoundError < Error; end
-  class UserNotFoundError < Error; end
-  class UnauthorizedError < Error; end
-  class ForbiddenError < Error; end
-  class InsufficientBalanceError < Error; end
-  class InsufficientPoolError < Error; end
-  class PinError < Error; end
-  class InvalidNfoFormatError < Error; end
-  class InvalidUuidFormatError < Error; end
-  class InvalidTransactionFormatError < Error; end
-  class ConfigurationNotValidError < Error; end
-  class InvalidInvoiceFormatError < Error; end
+    ##
+    # ActiveSupport deprecation helper for legacy API surfaces.
+    #
+    # @return [ActiveSupport::Deprecation]
+    #
+    def deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new('2.0', 'MixinBot')
+    end
+  end
 end