mixin_bot 1.4.0 → 2.1.0

data/lib/mvm/bridge.rb

@@ -1,17 +1,63 @@
 # frozen_string_literal: true
 
 module MVM
+  ##
+  # Bridge client for MVM cross-chain operations.
+  #
+  # The Bridge facilitates communication between Mixin Network and MVM,
+  # enabling cross-chain transfers and user registration.
+  #
+  # == Usage
+  #
+  #   bridge = MVM.bridge
+  #   info = bridge.info
+  #   user_info = bridge.user(public_key)
+  #
   class Bridge
+    ##
+    # @return [MVM::Client] the HTTP client for bridge operations
     attr_reader :client
 
+    ##
+    # Initializes a new Bridge instance.
+    #
+    # Creates an HTTP client connected to the MVM bridge service.
+    #
     def initialize
       @client = MVM::Client.new 'bridge.mvm.dev'
     end
 
+    ##
+    # Retrieves bridge service information.
+    #
+    # Returns general information about the bridge service including
+    # supported features, version, and status.
+    #
+    # @return [Hash] bridge information
+    #
+    # @example
+    #   bridge = MVM.bridge
+    #   info = bridge.info
+    #   puts info
+    #
     def info
       client.get '/'
     end
 
+    ##
+    # Retrieves or creates user information on the bridge.
+    #
+    # Registers a user's public key with the bridge service,
+    # enabling them to perform cross-chain operations.
+    #
+    # @param public_key [String] the user's public key
+    # @return [Hash] user information including bridge address
+    #
+    # @example
+    #   bridge = MVM.bridge
+    #   user = bridge.user('0x1234...')
+    #   puts user['contract']
+    #
     def user(public_key)
       path = '/users'
 

data/lib/mvm/client.rb

@@ -1,11 +1,51 @@
 # frozen_string_literal: true
 
 module MVM
+  ##
+  # HTTP client for MVM services.
+  #
+  # Handles HTTP communication with MVM services including:
+  # - Bridge service
+  # - NFT service
+  # - Registry service
+  # - Scan service
+  #
+  # == Features
+  #
+  # - Automatic JSON encoding/decoding
+  # - Request retry on failures
+  # - Error handling with exceptions
+  # - Debug logging
+  #
+  # == Usage
+  #
+  #   client = MVM::Client.new('bridge.mvm.dev')
+  #   response = client.get('/info')
+  #   response = client.post('/users', public_key: '0x...')
+  #
   class Client
+    ##
+    # The HTTPS scheme for all MVM requests.
     SERVER_SCHEME = 'https'
 
+    ##
+    # @return [String] the service host
     attr_reader :host
 
+    ##
+    # Initializes a new MVM Client.
+    #
+    # Sets up HTTP connection with:
+    # - JSON request/response handling
+    # - Automatic retry on failures
+    # - Error raising on HTTP errors
+    # - Debug logging
+    #
+    # @param host [String] the service hostname
+    #
+    # @example
+    #   client = MVM::Client.new('bridge.mvm.dev')
+    #
     def initialize(host)
       @host = host
       @conn = Faraday.new(url: "#{SERVER_SCHEME}://#{host}") do |f|
@@ -17,10 +57,30 @@ module MVM
       end
     end
 
+    ##
+    # Performs a GET request.
+    #
+    # @param path [String] the request path
+    # @param kwargs [Hash] query parameters
+    # @return [Hash] the parsed response body
+    #
+    # @example
+    #   response = client.get('/info')
+    #
     def get(path, **)
       @conn.get(path, **).body
     end
 
+    ##
+    # Performs a POST request.
+    #
+    # @param path [String] the request path
+    # @param kwargs [Hash] request body parameters
+    # @return [Hash] the parsed response body
+    #
+    # @example
+    #   response = client.post('/users', public_key: '0x...')
+    #
     def post(path, **)
       @conn.post(path, **).body
     end

data/lib/mvm/nft.rb

@@ -6,7 +6,8 @@ module MVM
 
     def initialize(rpc_url: MVM::RPC_URL, mirror_address: MVM::MIRROR_ADDRESS)
       @rpc = Eth::Client.create rpc_url
-      @mirror = Eth::Contract.from_abi name: 'Mirror', address: mirror_address, abi: File.read(File.expand_path('./abis/mirror.json', __dir__))
+      @mirror = Eth::Contract.from_abi name: 'Mirror', address: mirror_address,
+                                       abi: File.read(File.expand_path('./abis/mirror.json', __dir__))
     end
 
     def collection_from_contract(address)
@@ -40,7 +41,8 @@ module MVM
     end
 
     def token_of_owner_by_index(contract, owner, index)
-      contract = Eth::Contract.from_abi name: 'Collectible', address: contract, abi: File.read(File.expand_path('./abis/erc721.json', __dir__))
+      contract = Eth::Contract.from_abi name: 'Collectible', address: contract,
+                                        abi: File.read(File.expand_path('./abis/erc721.json', __dir__))
 
       @rpc.call contract, 'tokenOfOwnerByIndex', owner, index
     rescue IOError

data/lib/mvm/registry.rb

@@ -6,7 +6,8 @@ module MVM
 
     def initialize(rpc_url: MVM::RPC_URL, registry_address: MVM::REGISTRY_ADDRESS)
       @rpc = Eth::Client.create rpc_url
-      @registry = Eth::Contract.from_abi name: 'Registry', address: registry_address, abi: File.read(File.expand_path('./abis/registry.json', __dir__))
+      @registry = Eth::Contract.from_abi name: 'Registry', address: registry_address,
+                                         abi: File.read(File.expand_path('./abis/registry.json', __dir__))
     end
 
     def pid

data/lib/mvm.rb

@@ -9,27 +9,120 @@ require_relative 'mvm/nft'
 require_relative 'mvm/registry'
 require_relative 'mvm/scan'
 
+##
+# = MVM (Mixin Virtual Machine)
+#
+# MVM module provides integration with Mixin Virtual Machine, an Ethereum-compatible
+# virtual machine running on Mixin Network.
+#
+# == Overview
+#
+# MVM enables smart contract execution on Mixin Network with:
+# - EVM compatibility (Ethereum Virtual Machine)
+# - High performance and low cost
+# - Seamless integration with Mixin Network assets
+# - NFT support (ERC-721, ERC-1155)
+# - Bridge functionality for cross-chain operations
+#
+# == Components
+#
+# [MVM::Bridge] Bridge operations for cross-chain transfers
+# [MVM::Client] HTTP client for MVM services
+# [MVM::Nft] NFT operations (ERC-721, ERC-1155)
+# [MVM::Registry] Contract registry operations
+# [MVM::Scan] Blockchain explorer interface
+#
+# == Constants
+#
+# [RPC_URL] The default RPC endpoint for MVM
+# [MIRROR_ADDRESS] The mirror contract address
+# [REGISTRY_ADDRESS] The registry contract address
+#
+# == Usage
+#
+# Access bridge information:
+#
+#   bridge = MVM.bridge
+#   info = bridge.info
+#
+# Work with NFTs:
+#
+#   nft = MVM.nft
+#   # NFT operations...
+#
+# Use the blockchain scanner:
+#
+#   scan = MVM.scan
+#   # Scan operations...
+#
+# Access the registry:
+#
+#   registry = MVM.registry
+#   # Registry operations...
+#
+# == References
+#
+# - {MVM Documentation}[https://mvm.dev]
+#
 module MVM
+  ##
+  # The default RPC URL for Mixin Virtual Machine.
   RPC_URL = 'https://geth.mvm.dev'
+
+  ##
+  # The mirror contract address for cross-chain operations.
   MIRROR_ADDRESS = '0xC193486e6Bf3E8461cb8fcdF178676a5D75c066A'
+
+  ##
+  # The registry contract address for contract management.
   REGISTRY_ADDRESS = '0x3c84B6C98FBeB813e05a7A7813F0442883450B1F'
 
+  ##
+  # Base error class for all MVM errors.
   class Error < StandardError; end
+
+  ##
+  # Raised when HTTP request to MVM service fails.
   class HttpError < Error; end
+
+  ##
+  # Raised when MVM service returns an error response.
   class ResponseError < Error; end
 
+  ##
+  # Returns a singleton Bridge instance.
+  #
+  # @return [MVM::Bridge] the bridge instance
+  #
   def self.bridge
     @bridge ||= MVM::Bridge.new
   end
 
+  ##
+  # Returns a singleton or new NFT instance.
+  #
+  # @param params [Hash] optional parameters for NFT operations
+  # @return [MVM::Nft] the NFT instance
+  #
   def self.nft(**params)
     @nft ||= MVM::Nft.new(**params)
   end
 
+  ##
+  # Returns a singleton Scan instance.
+  #
+  # @return [MVM::Scan] the scan instance
+  #
   def self.scan
     @scan ||= MVM::Scan.new
   end
 
+  ##
+  # Returns a singleton or new Registry instance.
+  #
+  # @param params [Hash] optional parameters for registry operations
+  # @return [MVM::Registry] the registry instance
+  #
   def self.registry(**params)
     @registry ||= MVM::Registry.new(**params)
   end

data/lib/tasks/api_coverage.rake

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+namespace :mixin_bot do
+  desc 'Report API_COVERAGE.md missing entries (expects bot-api-go-client checkout)'
+  task :api_coverage do
+    coverage_path = File.expand_path('../../API_COVERAGE.md', __dir__)
+    unless File.exist?(coverage_path)
+      warn "Missing #{coverage_path}"
+      exit 1
+    end
+
+    missing = File.read(coverage_path).scan('| missing |').length
+    if missing.positive?
+      warn "API_COVERAGE: #{missing} entries still missing"
+      exit 1
+    end
+
+    puts 'API_COVERAGE: all entries marked done'
+  end
+end

data/llms.txt

@@ -0,0 +1,30 @@
+# MixinBot
+
+> Ruby SDK and CLI for Mixin Network: Safe UTXO transfers, REST API, Blaze messaging, transaction crypto, optional MVM helpers. Ruby >= 3.2. Gem version 2.1.0.
+
+Important notes:
+
+- Prefer Safe API (`create_safe_transfer`) over legacy `POST /transfers`
+- Safe transfers require `spend_key` in config/keystore
+- Blaze WebSocket is interactive — use Ruby API, not CLI
+
+## Docs
+
+- [README](README.md): Install, config, API overview, CLI summary
+- [API coverage vs Go/Node SDKs](API_COVERAGE.md): Method parity matrix
+- [CLI for agents](docs/agent/cli.md): Structured output, schema, examples
+- [Agent cookbook](docs/agent/cookbook.md): Common tasks (auth, transfer, messaging)
+- [Changelog](CHANGELOG.md): Breaking changes
+- [AGENTS.md](AGENTS.md): Repository layout and development workflows for coding agents
+
+## Examples
+
+- [Blaze WebSocket example](examples/blaze.rb): EventMachine + Blaze handlers
+- [Config template](examples/config.yml.example): Keystore fields
+
+## Optional
+
+- [Mixin official docs](https://developers.mixin.one/docs): External API reference
+- [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client): Go parity reference
+- [bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client): Node parity reference
+- [Generated RDoc](doc/index.html): Full API reference (local)

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mixin_bot
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 2.1.0
 platform: ruby
 authors:
 - an-lee
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -65,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: blake3-rb
   requirement: !ruby/object:Gem::Requirement
@@ -97,16 +112,22 @@ dependencies:
   name: eth
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: 0.5.17
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.17
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -233,7 +254,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-description: An API wrapper for Mixin Nexwork
+description: An API wrapper for Mixin Network
 email:
 - an.lee.work@gmail.com
 executables:
@@ -241,8 +262,16 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
+- API_COVERAGE.md
+- CHANGELOG.md
 - MIT-LICENSE
+- README.md
 - bin/mixinbot
+- docs/agent/cli.md
+- docs/agent/cookbook.md
+- examples/blaze.rb
+- examples/config.yml.example
 - lib/mixin_bot.rb
 - lib/mixin_bot/address.rb
 - lib/mixin_bot/api.rb
@@ -252,8 +281,15 @@ files:
 - lib/mixin_bot/api/attachment.rb
 - lib/mixin_bot/api/auth.rb
 - lib/mixin_bot/api/blaze.rb
+- lib/mixin_bot/api/chain.rb
+- lib/mixin_bot/api/circle.rb
+- lib/mixin_bot/api/code.rb
+- lib/mixin_bot/api/computer_api.rb
 - lib/mixin_bot/api/conversation.rb
+- lib/mixin_bot/api/deposit.rb
 - lib/mixin_bot/api/encrypted_message.rb
+- lib/mixin_bot/api/external.rb
+- lib/mixin_bot/api/fiat.rb
 - lib/mixin_bot/api/inscription.rb
 - lib/mixin_bot/api/legacy_collectible.rb
 - lib/mixin_bot/api/legacy_multisig.rb
@@ -262,28 +298,58 @@ files:
 - lib/mixin_bot/api/legacy_snapshot.rb
 - lib/mixin_bot/api/legacy_transaction.rb
 - lib/mixin_bot/api/legacy_transfer.rb
+- lib/mixin_bot/api/legacy_user.rb
 - lib/mixin_bot/api/me.rb
 - lib/mixin_bot/api/message.rb
 - lib/mixin_bot/api/multisig.rb
+- lib/mixin_bot/api/network.rb
+- lib/mixin_bot/api/network_asset.rb
 - lib/mixin_bot/api/output.rb
 - lib/mixin_bot/api/payment.rb
 - lib/mixin_bot/api/pin.rb
+- lib/mixin_bot/api/pin_payload.rb
 - lib/mixin_bot/api/rpc.rb
+- lib/mixin_bot/api/session.rb
 - lib/mixin_bot/api/snapshot.rb
 - lib/mixin_bot/api/tip.rb
 - lib/mixin_bot/api/transaction.rb
 - lib/mixin_bot/api/transfer.rb
+- lib/mixin_bot/api/turn.rb
 - lib/mixin_bot/api/user.rb
 - lib/mixin_bot/api/withdraw.rb
+- lib/mixin_bot/bot_auth.rb
 - lib/mixin_bot/cli.rb
 - lib/mixin_bot/cli/api.rb
+- lib/mixin_bot/cli/base.rb
+- lib/mixin_bot/cli/call.rb
+- lib/mixin_bot/cli/errors.rb
 - lib/mixin_bot/cli/node.rb
+- lib/mixin_bot/cli/output.rb
+- lib/mixin_bot/cli/schema.rb
+- lib/mixin_bot/cli/schema_command.rb
 - lib/mixin_bot/cli/utils.rb
 - lib/mixin_bot/client.rb
+- lib/mixin_bot/client/error_mapper.rb
+- lib/mixin_bot/computer.rb
 - lib/mixin_bot/configuration.rb
+- lib/mixin_bot/errors.rb
 - lib/mixin_bot/invoice.rb
+- lib/mixin_bot/models.rb
+- lib/mixin_bot/models/address.rb
+- lib/mixin_bot/models/api_envelope.rb
+- lib/mixin_bot/models/asset.rb
+- lib/mixin_bot/models/ghost_keys.rb
+- lib/mixin_bot/models/output.rb
+- lib/mixin_bot/models/safe_multisig_request.rb
+- lib/mixin_bot/models/sequencer_transaction_request.rb
+- lib/mixin_bot/models/user.rb
+- lib/mixin_bot/monitor.rb
 - lib/mixin_bot/nfo.rb
 - lib/mixin_bot/transaction.rb
+- lib/mixin_bot/transaction/buffer.rb
+- lib/mixin_bot/transaction/decoder.rb
+- lib/mixin_bot/transaction/encoder.rb
+- lib/mixin_bot/url_scheme.rb
 - lib/mixin_bot/utils.rb
 - lib/mixin_bot/utils/address.rb
 - lib/mixin_bot/utils/crypto.rb
@@ -302,11 +368,14 @@ files:
 - lib/mvm/nft.rb
 - lib/mvm/registry.rb
 - lib/mvm/scan.rb
+- lib/tasks/api_coverage.rake
+- llms.txt
 homepage: https://github.com/an-lee/mixin_bot
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -321,7 +390,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
-summary: A Ruby SDK for Mixin Nexwork
+summary: A Ruby SDK for Mixin Network
 test_files: []