mixin_bot 2.4.1 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2015d5166c25f388692121bf3bd697cf87c3ce1533c250aea360592e7d5144b6
-  data.tar.gz: d748e92727a3b7febdb14bf950267d62fc18c3dbb1bd457f27391ae807e63432
+  metadata.gz: ce614b6fab815a9d8dfb1e93914fdaf3ba6b7306b1f5d35ab594efcd0b46fe68
+  data.tar.gz: 70b09c5ba22efc597a43b560a4257e2984b059b8334eee6efa19498934e87407
 SHA512:
-  metadata.gz: 92e232f9d704725e7def1a5457adacc120a5139f7e2b673841d80a46f15b7170f0b06653576d1f44da1e9bbb389de90951d89fb93b4b24ed801cfa43374e73f8
-  data.tar.gz: d45e5bd3310a72468d19d826329d124f47fa220fcf9ff4dfaa17c5f5c01f26fe8d023c8c7a24c6fa2f6123e6b8f4cd6d7d08effcfe1749bf6150011dcbf13040
+  metadata.gz: ab61a3850c702cb36a00794f5cfacb3aa63d18d6fca24104d9be336b97b04332430eb702bba50d6bbaa80f9ad94976fa5aaeefaae69f736bed88b21ffce7f849
+  data.tar.gz: c2a237075b8c9399ef4f90d933d1bac288de35aefa11ff6fa55d3dd4e19a337d0a10f78173a9eef77a16476a63e208fa22b0c3250758ad7c2324490411ffa4b7

data/API_COVERAGE.md

@@ -41,6 +41,7 @@ Status values: `done` | `alias` | `n/a` (CLI-only / config / platform-specific)
 | AssetBalance* | `API#asset_balance` | derived from outputs | done |
 | UserAssetBalance | `API#user_asset_balance` | GET `/safe/outputs` | done |
 | ReadAsset | `API#network_asset` | GET `/network/assets/:id` | done |
+| ReadSafeFees | `API#safe_fees` / `#read_safe_fees` | GET `/safe/fees` | done |
 | ReadAssetTicker* | `API#network_ticker` | GET `/network/ticker` | done |
 | AssetSearch | `API#network_asset_search` | GET `/network/assets/search/:q` | done |
 | ReadNetworkAssets | `API#network_assets` | GET `/network` | done |
@@ -52,6 +53,8 @@ Status values: `done` | `alias` | `n/a` (CLI-only / config / platform-specific)
 | GetChainName | `API#chain_name` | local | done |
 | IsChainId | `API#chain_id?` | local | done |
 | GetFullChains | `API#full_chains` | local | done |
+| ChainId constants (HyperEVM, X Layer, Robinhood, Pearl, corrected Sui) | `CHAIN_NAMES` + `CHAIN_STABLECOIN_ASSET_IDS` / `API#stablecoin_asset_ids` | local | done |
+| USDT/USDC per-chain constants | `MixinBot::API::Chain::USDT_*` / `USDC_*` | local | done |
 | **Outputs / deposits** |
 | ListOutputs / ListUnspentOutputs | `API#safe_outputs` | GET `/safe/outputs` | done |
 | GetOutput | `API#safe_output` | GET `/safe/outputs/:id` | done |
@@ -94,6 +97,10 @@ Status values: `done` | `alias` | `n/a` (CLI-only / config / platform-specific)
 | RotateConversation | `API#rotate_conversation` | POST `.../rotate` | done |
 | UpdateParticipants | `API#add/remove/..._participants` | POST participants | done |
 | PostMessage(s) | `API#send_message` | POST `/messages` | done |
+| MessageRequest.Silent | `API#send_*(silent: true)` | POST `/messages` | done |
+| PostEncryptedMessages | `API#post_encrypted_messages` | POST `/encrypted_messages` + one-shot retry | done |
+| SessionStore / MapSessionStore | `MixinBot::SessionStore` | local | done |
+| EncryptedMessageResponse / EncryptedMessageError | response envelope `data` | per-recipient `state` | done |
 | EncryptMessageData / DecryptMessageData | `API#encrypt_message` / `#decrypt_message` | local | done |
 | BlazeClient send helpers | `API#blaze_send_*` | WebSocket | done |
 | **Inscriptions** |
@@ -139,6 +146,7 @@ Status values: `done` | `alias` | `n/a` (CLI-only / config / platform-specific)
 | CheckRetryableError | `MixinBot::Monitor.check_retryable_error` | local | done |
 | **HTTP config** |
 | Request / SetBaseUri / SetBlazeUri | `MixinBot::Configuration`, `Client` | config | n/a |
+| SetHttpTimeout | `MixinBot.configure` `http_timeout` | config | n/a |
 | NewSafeUser | `MixinBot::Configuration` | config | n/a |
 | cli/*, examples/*, mixin/rpc main | `mixinbot call` / `mixinbot list` | CLI dispatch to `MixinBot::API` | done |
 
@@ -197,6 +205,8 @@ TS-only or Node-first REST surfaces. Ruby methods follow snake_case; aliases mir
 | conversation.* (CRUD/participants) | `API#conversation`, `#create_*`, `#join_*`, etc. | various | done |
 | **Message** |
 | message.sendAcknowledgement(s) | `API#acknowledge_message` / `#acknowledge_messages` | POST `/acknowledgements` | done |
+| message.sendLegacy | `API#send_message(hash)` | POST `/messages` singular body | alias |
+| APP_CARD cover_url / actions | `API#blaze_send_app_card(cover_url:, actions:)` | WebSocket | done |
 | message.sendSticker/Audio/Video/Live/Location/Transfer | `API#send_*_message` | POST `/messages` | done |
 | message.sendText/Image/File/Post/Contact/AppCard/AppButton/Recall | `API#send_*_message` | POST `/messages` | done |
 | **Code** |
@@ -210,6 +220,9 @@ TS-only or Node-first REST surfaces. Ruby methods follow snake_case; aliases mir
 | external.deposits | `API#transactions` (legacy) | GET `/external/transactions` | done |
 | external.checkAddress | `API#check_address` | GET `/external/addresses/check` | done |
 | external.exchangeRates | `API#fiats` | GET `/external/fiats` | done |
+| **Utils** |
+| utils/amount.formatUnits / parseUnits | `MixinBot.utils.format_units` / `#parse_units` | local | done |
+| utils/auth.getChallenge | `MixinBot.utils.oauth_code_challenge` | local | done |
 | **Safe / UTXO / Transfer / Network / etc.** |
 | safe.* / utxo.* / transfer.* / network.* | spread across existing `API` modules | same HTTP paths as TS | done |
 | **Blaze** |

data/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-09-03
+
+### Added
+
+- **Upstream SDK parity (2026 Go/Node releases)** — closes gaps with `bot-api-go-client` v3.25.3 and `bot-api-nodejs-client` v7.5.6.
+- **`API#safe_fees`** (`read_safe_fees` alias) — `GET /safe/fees` global Safe fee schedule.
+- **`API#post_encrypted_messages`** — encrypt-and-send pipeline (`POST /encrypted_messages`) with one-shot retry on expired recipient sessions, per-message `SUCCESS`/`FAILED` state, and a pluggable session cache.
+- **`MixinBot::SessionStore`** — in-memory `MapSessionStore` equivalent; pass any object answering `fetch(user_id)` / `store(user_id, sessions)` as `session_store:` (storing `nil` evicts).
+- **`MixinBot::CacheStoreAdapter`** — wraps any `ActiveSupport::Cache`-style store (`Rails.cache` with Redis/Memcached/solid_cache, or a hand-rolled read/write/delete object) so encrypted-message sessions can be cached across processes with `expires_in:` TTLs.
+- **`MixinBot::Configuration#http_timeout`** — opt-in Faraday request timeout in seconds (nil keeps the default).
+- **`silent:` flag** on REST `send_message` and encrypted REST sends, matching Go `MessageRequest.Silent`.
+- **Chain registry** — HyperEVM, X Layer, Robinhood, and Pearl chain ids, plus a corrected Sui id. `CHAIN_STABLECOIN_ASSET_IDS` map and `API#stablecoin_asset_ids(chain_id)`; per-chain `USDT_*` / `USDC_*` constants.
+- **`MixinBot.utils.format_units` / `#parse_units`** — decimal-safe unit conversion (Node `utils/amount` parity, no `Kernel#Integer` octal/hex surprises).
+- **`MixinBot.utils.oauth_code_challenge`** — PKCE S256 code challenge (RFC 7636).
+- **OAuth PKCE support** — `oauth_token(code, code_verifier:)` and `authorize_code(scope:, code_verifier:)` exchange and emit PKCE authorizations.
+- **`blaze_send_app_card(cover_url:, actions:)`** — APP_CARD parity with the Node SDK.
+
+### Changed
+
+- **`API#post_encrypted_messages`** — encrypted-message checksum now reuses `MixinBot.utils.generate_user_checksum` (the dead MD5 line in `encrypt_message` is gone).
+- **Encrypted-message session store** — default store lives on the API instance so caching persists across calls per process; expired sessions are evicted via `store(id, nil)` (Go `store.Delete` parity).
+- **`MixinBot::Utils` CLI introspection** — `mixinbot utils list` / `utils call` now surface methods extended from submodules (`Address`, `Amount`, `Crypto`, …).
+- **`API::Auth`** — `authorize_code` accepts `String` scopes; `REFRESH_OAUTH_CODE` payload is built from an `oauth_code_params` helper; the dead `@_app_id` ivar is gone.
+
+### Fixed
+
+- **`API#post_encrypted_messages`** — non-String `data` is JSON-encoded (was Ruby `inspect` output); the `silent` flag is honored on all encrypted REST sends; sessions stores that raise or return non-arrays are tolerated (Go `err == nil` semantics); symbol-keyed sessions are normalized; per-message responses are merged across the retry so every message's final state is returned; duplicate `message_id`s are rejected; malformed `/encrypted_messages` payloads raise meaningful errors; kwargs are strictly `access_token` / `exp_in` / `scp`.
+- **`MixinBot::Client`** — `Configuration#api_host` and `#debug` are now applied correctly even when the client is initialized with a different `config` (no more stale Faraday URL when reassigning config).
+- **Encrypted-message test harness** — shared guarded WebMock setup in `test_helper.rb` so `LIVE=1` runs and per-file `setup` methods reset state consistently; encrypted-message stub helpers extracted for reuse.
+
 ## [2.4.1] - 2026-08-08
 
 ### Fixed

data/README.md

@@ -55,6 +55,7 @@ MixinBot.configure do
   # self.pin = self.spend_key        # optional; used where PIN material is required
   # self.api_host = 'api.mixin.one'
   # self.blaze_host = 'blaze.mixin.one'
+  # self.http_timeout = 30          # request timeout in seconds (nil = no timeout)
   # self.debug = true               # Faraday response logging
 end
 ```
@@ -162,7 +163,7 @@ Many convenience methods on `MixinBot::API` still return the **inner `data` hash
 | **Withdraw** | `withdrawals`, `create_withdraw_address`, `check_address`, `withdraw_addresses` |
 | **Conversation** | `conversation`, `create_group_conversation`, `join_conversation`, … |
 | **Message** | `send_message`, `send_plain_messages`, Blaze helpers |
-| **EncryptedMessage** | `send_encrypted_*`, `encrypt_message`, `decrypt_message` |
+| **EncryptedMessage** | `send_encrypted_*`, `post_encrypted_messages`, `encrypt_message`, `decrypt_message` |
 | **Blaze** | `blaze`, `start_blaze_connect`, `blaze_send_plain_text`, … |
 | **Attachment** | `create_attachment`, `upload_attachment` |
 | **Auth** | `oauth_token`, `authorize_code`, `access_token`, `sign_oauth_access_token` |
@@ -175,6 +176,21 @@ Many convenience methods on `MixinBot::API` still return the **inner `data` hash
 
 Top-level helpers on **`MixinBot::API`**: `access_token`, `encode_raw_transaction`, `decode_raw_transaction`, native variants via `mixin` CLI.
 
+### Session caching for encrypted messages
+
+`post_encrypted_messages` resolves recipient sessions through a **session store**: `session_store: session_store_obj` — any object answering `fetch(user_id)` (sessions or `nil`) and `store(user_id, sessions)` (storing `nil` evicts). Without one, a per-API-instance in-memory store is used.
+
+For Rails (or any `ActiveSupport::Cache`-style store — Redis, Memcached, solid_cache), use the built-in adapter for TTLs and cross-process caching:
+
+```ruby
+MixinBot.api.post_encrypted_messages(
+  [{ recipient_id: id, category: 'ENCRYPTED_TEXT', data: 'hello' }],
+  session_store: MixinBot::CacheStoreAdapter.new(Rails.cache, expires_in: 12.hours)
+)
+```
+
+The adapter maps `store(user_id, nil)` to `cache.delete`, so sessions the server reports as expired are evicted, refreshed, and retried automatically.
+
 ### Other libraries
 
 | Area | Description |

data/lib/mixin_bot/api/asset.rb

@@ -116,6 +116,11 @@ module MixinBot
       end
       alias read_asset_fee asset_fee
 
+      def safe_fees(access_token: nil)
+        client.get '/safe/fees', access_token:
+      end
+      alias read_safe_fees safe_fees
+
       def asset_balance(asset_id)
         outputs = safe_outputs(asset: asset_id, state: 'unspent')
         Array(outputs['data']).sum { |o| o['amount'].to_d }

data/lib/mixin_bot/api/auth.rb

@@ -17,13 +17,14 @@ module MixinBot
         )
       end
 
-      def oauth_token(code)
+      def oauth_token(code, code_verifier: nil)
         path = '/oauth/token'
         payload = {
           client_id: config.app_id,
           client_secret: config.client_secret,
           code:
         }
+        payload[:code_verifier] = code_verifier if code_verifier.present?
         client.post path, **payload
       end
 
@@ -37,9 +38,13 @@ module MixinBot
       end
 
       def authorize_code(**kwargs)
+        scope = kwargs[:scope] || ['PROFILE:READ']
+        scope = scope.split if scope.is_a?(String)
+
         data = authorization_data(
           kwargs[:app_id],
-          kwargs[:scope] || ['PROFILE:READ']
+          scope,
+          kwargs[:code_verifier]
         )
 
         path = '/oauth/authorize'
@@ -67,21 +72,22 @@ module MixinBot
       end
       alias revoke_authorize revoke_authorization
 
-      def authorization_data(app_id, scope = ['PROFILE:READ'])
-        @_app_id = app_id
-        @_scope = scope.join(' ')
+      # REFRESH_OAUTH_CODE params for the OAuth authorization handshake.
+      def oauth_code_params(app_id:, scope:, authorization_id: '', code_verifier: nil)
+        {
+          client_id: app_id,
+          scope:,
+          authorization_id:,
+          code_challenge: code_verifier ? MixinBot.utils.oauth_code_challenge(code_verifier) : ''
+        }
+      end
+
+      def authorization_data(app_id, scope = ['PROFILE:READ'], code_verifier = nil)
+        @_code_params = oauth_code_params(app_id:, scope: Array(scope).join, code_verifier:)
         EM.run do
           start_blaze_connect do
             def on_open(websocket, _event) # rubocop:disable Lint/NestedMethodDefinition
-              websocket.send write_ws_message(
-                action: 'REFRESH_OAUTH_CODE',
-                params: {
-                  client_id: @_app_id,
-                  scope: @_scope,
-                  authorization_id: '',
-                  code_challenge: ''
-                }
-              )
+              websocket.send write_ws_message(action: 'REFRESH_OAUTH_CODE', params: @_code_params)
             end
 
             def on_message(websocket, event) # rubocop:disable Lint/NestedMethodDefinition

data/lib/mixin_bot/api/blaze.rb

@@ -101,8 +101,10 @@ module MixinBot
         )
       end
 
-      def blaze_send_app_card(socket, conversation_id:, recipient_id:, title:, description:, action:, icon_url:)
-        data = { title:, description:, action:, icon_url: }.to_json
+      # mirrors the upstream APP_CARD fields
+      def blaze_send_app_card(socket, conversation_id:, recipient_id:, title:, description:, action:, icon_url:, # rubocop:disable Metrics/ParameterLists
+                              cover_url: nil, actions: nil)
+        data = { title:, description:, action:, icon_url:, cover_url:, actions: }.compact.to_json
         socket.send write_ws_message(
           params: {
             conversation_id:,

data/lib/mixin_bot/api/chain.rb

@@ -57,13 +57,30 @@ module MixinBot
         '163a2142-398d-3483-aee3-d47db8da4d10' => 'MarsChain',
         'b12bb04a-1cea-401c-a086-0be61f544889' => 'XDC Network',
         'd2c1c7e1-a1a9-4f88-b282-d93b0a08b42b' => 'Aptos',
-        '2bd97283-2582-33a8-bcba-f4b8ed189572' => 'Sui',
-        'ef660437-d915-4e27-ad3f-632bfb6ba0ee' => 'TON'
+        '3acb25e4-6216-35c3-b1ca-87184269ee08' => 'Sui',
+        'ef660437-d915-4e27-ad3f-632bfb6ba0ee' => 'TON',
+        '36d23d9e-bf4e-3ede-a12d-26f1f1f9fd2f' => 'HyperEVM',
+        '37f5a4d1-905f-3b34-8291-c37438c7dcfc' => 'X Layer',
+        'b304e03d-d004-3102-875b-8266f8407a1a' => 'Robinhood',
+        'e1bf305c-0d49-397d-85bd-55b9eaadafba' => 'Pearl'
       }.freeze
 
       XIN_ASSET_ID = 'c94ac88f-4671-3976-b60a-09064f1811e8'
       VAULTA_ASSET_ID = 'ac2b79f3-ec9c-3d87-b4ca-3e825228dda5'
 
+      # Stablecoin asset ids per chain, mirroring upstream bot-api-go-client asset.go.
+      USDT_HYPEREVM = '3782f986-a053-33ae-b6bf-460abb62ce49'
+      USDT_XLAYER = 'c4d9746a-20be-321c-baca-d378534dd4eb'
+      USDC_HYPEREVM = '1e01fede-51fa-3791-9b06-5c18801b272c'
+      USDC_XLAYER = '8d706a25-514c-3c73-9446-c25fd07d0ae2'
+      USDC_SUI = 'a0f7ad61-3b9f-30f3-a1de-cd831aec33ff'
+
+      CHAIN_STABLECOIN_ASSET_IDS = {
+        '36d23d9e-bf4e-3ede-a12d-26f1f1f9fd2f' => { usdt: USDT_HYPEREVM, usdc: USDC_HYPEREVM }, # HyperEVM
+        '37f5a4d1-905f-3b34-8291-c37438c7dcfc' => { usdt: USDT_XLAYER, usdc: USDC_XLAYER }, # X Layer
+        '3acb25e4-6216-35c3-b1ca-87184269ee08' => { usdc: USDC_SUI } # Sui
+      }.freeze
+
       def network_chain(chain_id)
         path = format('/network/chains/%<chain_id>s', chain_id:)
         client.get path, access_token: ''
@@ -78,6 +95,11 @@ module MixinBot
       def chain_name(chain_id)
         CHAIN_NAMES[chain_id] || 'Not Supported Chain'
       end
+
+      # Stablecoin asset ids for a chain id (nil for chains without a mapping).
+      def stablecoin_asset_ids(chain_id)
+        CHAIN_STABLECOIN_ASSET_IDS[chain_id]
+      end
       alias get_chain_name chain_name
 
       def chain_id?(chain_id)

data/lib/mixin_bot/api/encrypted_message.rb

@@ -80,8 +80,8 @@ module MixinBot
       def base_encrypted_message_params(options)
         data = options[:data].is_a?(String) ? options[:data] : options[:data].to_json
         data_base64 = encrypt_message Base64.urlsafe_encode64(data, padding: false), options[:sessions]
-        session_ids = options[:sessions].map(&->(s) { s['session_id'] }).sort
-        checksum = Digest::MD5.hexdigest session_ids.join
+        session_ids = options[:sessions].map { |s| s['session_id'] || s[:session_id] }.compact.sort
+        checksum = MixinBot.utils.generate_user_checksum(options[:sessions])
 
         {
           conversation_id: options[:conversation_id],
@@ -92,8 +92,9 @@ module MixinBot
           message_id: options[:message_id] || SecureRandom.uuid,
           data_base64:,
           checksum:,
-          recipient_sessions: session_ids.map(&->(s) { { session_id: s } }),
-          silent: false
+          recipient_sessions: session_ids.map { |session_id| { session_id: } },
+          # Go's MessageRequest always serializes `silent`; default stays false
+          silent: (options[:silent] ? true : false)
         }.compact
       end
 
@@ -110,13 +111,149 @@ module MixinBot
         client.post path, *payload
       end
 
+      ##
+      # Encrypt and send messages using each recipient's current sessions.
+      #
+      # Accepts a single options hash or an array of them (same shapes as
+      # +send_encrypted_*_message+). Sessions are resolved through the session
+      # store - +session_store:+, or the per-API-instance default store - and
+      # fetched via +POST /sessions/fetch+ on a cache miss. Messages the server
+      # rejects because a recipient's sessions changed have their sessions
+      # evicted, refreshed, and are retried once. The returned envelope carries
+      # every message's final +state+ (SUCCESS/FAILED).
+      #
+      # @param messages [Hash, Array<Hash>] unencrypted message options
+      # @param session_store [#fetch, #store] session cache; +store(id, nil)+ evicts
+      # @return [MixinBot::Models::ApiEnvelope] per-message responses (+state+ SUCCESS/FAILED)
+      #
+      def post_encrypted_messages(messages = nil, session_store: nil, **kwargs)
+        messages = kwargs.delete(:messages) if messages.nil? && kwargs.key?(:messages)
+        messages = [messages] unless messages.is_a? Array
+        raise ArgumentError, 'messages must not be empty' if messages.empty?
+
+        token_keys = %i[access_token exp_in scp]
+        unknown = kwargs.keys - token_keys
+        raise ArgumentError, "unsupported options: #{unknown.join(', ')}" if unknown.any?
+
+        original = messages.map { |message| message.to_h.transform_keys(&:to_sym) }
+        seen_ids = []
+        pending = original.map do |message|
+          raise ArgumentError, 'recipient_id is required' if message[:recipient_id].blank?
+          if message[:message_id] && seen_ids.include?(message[:message_id])
+            raise ArgumentError,
+                  "duplicate message_id #{message[:message_id]}"
+          end
+
+          message[:message_id] ||= SecureRandom.uuid
+          seen_ids << message[:message_id]
+          message
+        end
+
+        store = session_store || (@session_store ||= MixinBot::SessionStore.new)
+        final_results = {}
+        responses = nil
+
+        2.times do |attempt|
+          recipient_ids = pending.map { |message| message[:recipient_id] }.uniq
+          missing = recipient_ids.reject { |recipient_id| cached_encrypted_sessions(store, recipient_id).present? }
+          fetched = missing.any? ? fetch_encrypted_message_sessions!(missing, store, **kwargs) : {}
+
+          requests = pending.map do |message|
+            sessions = cached_encrypted_sessions(store, message[:recipient_id]) || fetched[message[:recipient_id]]
+            raise ArgumentError, "no sessions found for recipient #{message[:recipient_id]}" if sessions.blank?
+
+            encrypted_message_request(message, sessions)
+          end
+          responses = client.post '/encrypted_messages', *requests, **kwargs
+
+          data = responses['data']
+          data = [data] if data.is_a?(Hash)
+          raise ArgumentError, 'unexpected /encrypted_messages response format' unless data.is_a? Array
+
+          results, failures = encrypted_message_results(pending, data)
+          final_results.merge!(results)
+          break if failures.empty? || attempt.positive?
+
+          pending = failures
+          # the FAILED recipients' sessions are assumed expired: evict + refresh
+          pending.map { |message| message[:recipient_id] }.uniq.each { |recipient_id| store.store recipient_id, nil }
+        end
+
+        responses.to_h['data'] = original.filter_map { |message| final_results[message[:message_id]] }
+        responses
+      end
+
+      # Read a recipient's sessions from the store. Stores that raise (a Redis
+      # outage) or return non-list values count as a cache miss, mirroring the
+      # Go SDK's `if sessions, err := store.Get(...); err == nil` tolerance.
+      def cached_encrypted_sessions(store, recipient_id)
+        cached = begin
+          # block form keeps 1-arity duck-typed stores (Hash included) working
+          store.fetch(recipient_id) { nil } # rubocop:disable Style/RedundantFetchBlock
+        rescue StandardError
+          nil
+        end
+
+        sessions = Array(cached)
+        return nil unless sessions.all?(Hash)
+        return nil if sessions.empty?
+
+        sessions.map(&:stringify_keys)
+      end
+
+      # Fetch sessions for the given recipients and write them to the store.
+      # Returns { recipient_id => sessions } for the resolved recipients.
+      def fetch_encrypted_message_sessions!(recipient_ids, store, **kwargs)
+        return {} if recipient_ids.empty?
+
+        response = fetch_user_sessions(recipient_ids, **kwargs.slice(:access_token, :exp_in, :scp))
+        grouped = {}
+        Array(response['data']).each do |session|
+          owner = session['user_id'].presence
+          owner = recipient_ids.first if owner.blank? && recipient_ids.one?
+          grouped[owner] = (grouped[owner] || []) + [session] if owner.present?
+        end
+
+        recipient_ids.each_with_object({}) do |recipient_id, resolved|
+          sessions = grouped[recipient_id]
+          raise ArgumentError, "no sessions found for recipient #{recipient_id}" if sessions.blank?
+
+          store.store recipient_id, sessions.map(&:stringify_keys)
+          resolved[recipient_id] = sessions.map(&:stringify_keys)
+        end
+      end
+
+      def encrypted_message_request(message, sessions)
+        base_encrypted_message_params message.merge(sessions:, silent: (message[:silent] ? true : false))
+      end
+
+      # Maps each pending message to its server response. Returns
+      # [results_by_message_id, failed_messages]; raises on malformed responses.
+      def encrypted_message_results(messages, responses)
+        by_message_id = responses.to_h { |response| [response['message_id'], response] }
+
+        results = {}
+        failures = []
+        messages.each do |message|
+          response = by_message_id[message[:message_id]]
+          raise ArgumentError, "encrypted message response missing for #{message[:message_id]}" if response.nil?
+
+          results[message[:message_id]] = response
+          case response['state']
+          when 'SUCCESS' then nil
+          when 'FAILED' then failures << message
+          else raise ArgumentError, "encrypted message #{message[:message_id]} returned unknown state #{response['state']}"
+          end
+        end
+        [results, failures]
+      end
+
       def encrypt_message(data, sessions = [], sk: nil, pk: nil) # rubocop:disable Naming/MethodParameterName
         raise ArgumentError, 'Wrong sessions format!' unless sessions.all?(&->(s) { s.key?('session_id') && s.key?('public_key') })
 
         sk ||= config.session_private_key[0...32]
         pk ||= config.session_private_key[32...]
 
-        Digest::MD5.hexdigest sessions.map(&->(s) { s['session_id'] }).sort.join
         encrypter = OpenSSL::Cipher.new('AES-128-GCM').encrypt
         key = encrypter.random_key
         nounce = encrypter.random_iv

data/lib/mixin_bot/api/message.rb

@@ -92,6 +92,8 @@ module MixinBot
           status: 'SENT',
           quote_message_id: options[:quote_message_id],
           message_id: options[:message_id] || SecureRandom.uuid,
+          # opt-in silent delivery; key is omitted unless requested (mirrors Go omitempty)
+          silent: (options[:silent] ? true : nil),
           data: Base64.encode64(data)
         }.compact
       end

data/lib/mixin_bot/api/session.rb

@@ -3,10 +3,10 @@
 module MixinBot
   class API
     module Session
-      def fetch_user_sessions(user_ids, access_token: nil)
+      def fetch_user_sessions(user_ids, access_token: nil, exp_in: 600, scp: 'FULL')
         raise ArgumentError, 'user_ids required' if user_ids.blank?
 
-        client.fetch_post_array '/sessions/fetch', Array(user_ids), access_token:
+        client.fetch_post_array '/sessions/fetch', Array(user_ids), access_token:, exp_in:, scp:
       end
       alias fetch_user_session fetch_user_sessions
     end

data/lib/mixin_bot/cache_store_adapter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module MixinBot
+  ##
+  # Adapter that lets any ActiveSupport::Cache-style store (Rails.cache with a
+  # Redis/Memcached/solid_cache backend, or a hand-rolled read/write/delete
+  # object) back the encrypted-message session cache.
+  #
+  # API#post_encrypted_messages expects a store answering +fetch(user_id)+ and
+  # +store(user_id, sessions)+, where storing +nil+ evicts. ActiveSupport
+  # caches speak read/write/delete instead, so this adapter translates:
+  #
+  #   session_store: MixinBot::CacheStoreAdapter.new(Rails.cache, expires_in: 12.hours)
+  #
+  # The +expires_in:+ option is passed through to +cache.write+ as a TTL; the
+  # pipeline's one-shot expiry retry covers entries that lapse between fetch
+  # and send.
+  #
+  class CacheStoreAdapter
+    KEY_PREFIX = 'mixin_bot/sessions'
+
+    def initialize(cache = nil, expires_in: nil)
+      cache ||= Rails.cache if defined?(Rails)
+      raise ArgumentError, 'a cache store is required' if cache.nil?
+
+      @cache = cache
+      @expires_in = expires_in
+    end
+
+    # Returns the cached session list for the recipient, or nil on a miss.
+    # A block passed by the caller is intentionally ignored: the block form of
+    # Rails' fetch means read-through caching, which is not wanted here.
+    def fetch(user_id)
+      @cache.read("#{KEY_PREFIX}/#{user_id}")
+    end
+
+    # Writes the session list for the recipient; +nil+ evicts the entry.
+    def store(user_id, sessions)
+      key = "#{KEY_PREFIX}/#{user_id}"
+      if sessions.nil?
+        @cache.delete(key)
+      elsif @expires_in
+        @cache.write(key, sessions, expires_in: @expires_in)
+      else
+        @cache.write(key, sessions)
+      end
+    end
+  end
+end

data/lib/mixin_bot/cli/base.rb

@@ -58,7 +58,8 @@ module MixinBot
     end
 
     def utils_callable_methods
-      MixinBot::Utils.singleton_methods(false).sort
+      # include methods from the extend-ed submodules (Address, Amount, Crypto, ...)
+      MixinBot::Utils.singleton_methods.sort
     end
 
     def api_method_owner(method_name)

data/lib/mixin_bot/client.rb

@@ -14,7 +14,7 @@ module MixinBot
     def initialize(config)
       @config = config || MixinBot.config
       @conn = Faraday.new(
-        url: "#{SERVER_SCHEME}://#{config.api_host}",
+        url: "#{SERVER_SCHEME}://#{@config.api_host}",
         headers: {
           'Content-Type' => 'application/json',
           'User-Agent' => "mixin_bot/#{MixinBot::VERSION}"
@@ -23,8 +23,9 @@ module MixinBot
         f.request :json
         f.request :retry, max: 2, interval: 0.5, interval_randomness: 0.5, backoff_factor: 2,
                           exceptions: [Faraday::ConnectionFailed, Faraday::TimeoutError]
+        f.options.timeout = @config.http_timeout if @config.http_timeout
         f.response :json
-        f.response :logger if config.debug
+        f.response :logger if @config.debug
       end
     end
 

data/lib/mixin_bot/configuration.rb

@@ -52,6 +52,7 @@ module MixinBot
       pin
       api_host
       blaze_host
+      http_timeout
       session_private_key_curve25519
       server_public_key_curve25519
       debug
@@ -71,6 +72,7 @@ module MixinBot
     # @option kwargs [String] :pin the PIN (defaults to spend_key if not provided)
     # @option kwargs [String] :api_host ('api.mixin.one') the API host
     # @option kwargs [String] :blaze_host ('blaze.mixin.one') the Blaze WebSocket host
+    # @option kwargs [Numeric] :http_timeout (nil) request timeout in seconds; nil keeps Faraday's default
     # @option kwargs [Boolean] :debug (false) enable debug logging
     #
     # @example
@@ -87,6 +89,11 @@ module MixinBot
       @session_id = kwargs[:session_id]
       @api_host = kwargs[:api_host] || 'api.mixin.one'
       @blaze_host = kwargs[:blaze_host] || 'blaze.mixin.one'
+      @http_timeout = kwargs[:http_timeout]
+      if @http_timeout && (@http_timeout.is_a?(Numeric) ? @http_timeout <= 0 : true)
+        raise ArgumentError, "http_timeout must be a positive number of seconds, got #{@http_timeout.inspect}"
+      end
+
       @debug = kwargs[:debug] || false
 
       self.session_private_key = kwargs[:session_private_key] || kwargs[:private_key]

data/lib/mixin_bot/errors.rb

@@ -28,8 +28,8 @@ module MixinBot
     attr_reader :code, :description, :status, :http_status, :request_id, :server_time,
                 :retry_after, :extra, :path, :verb, :body
 
-    # rubocop:disable Metrics/ParameterLists -- structured API error metadata
-    def initialize(message = nil, code: nil, description: nil, status: nil, http_status: nil,
+    # structured API error metadata
+    def initialize(message = nil, code: nil, description: nil, status: nil, http_status: nil, # rubocop:disable Metrics/ParameterLists
                    request_id: nil, server_time: nil, retry_after: nil, extra: nil,
                    path: nil, verb: nil, body: nil)
       @code = code&.to_i
@@ -45,7 +45,6 @@ module MixinBot
       @body = body
       super(message || formatted_message)
     end
-    # rubocop:enable Metrics/ParameterLists
 
     def client_error?
       c = code.to_i

data/lib/mixin_bot/session_store.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module MixinBot
+  ##
+  # In-memory cache of recipient sessions for encrypted-message sending.
+  #
+  # Mirrors the Go SDK's +MapSessionStore+: +fetch+ returns the cached session
+  # list for a recipient user (or nil on a miss) and +store+ overwrites it;
+  # storing +nil+ evicts the entry (used when sessions expire mid-send).
+  # Any object answering both calls can be passed as +session_store:+ to
+  # API#post_encrypted_messages to plug in custom caching (e.g. Redis, TTLs).
+  #
+  class SessionStore
+    def initialize
+      @sessions = {}
+    end
+
+    def fetch(user_id)
+      @sessions[user_id]
+    end
+
+    def store(user_id, sessions)
+      @sessions[user_id] = sessions
+    end
+  end
+end

data/lib/mixin_bot/utils/amount.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+module MixinBot
+  module Utils
+    ##
+    # Decimal-safe unit conversion between human-readable amounts and decimal
+    # strings, mirroring the Node SDK's utils/amount.ts (BigNumber-based).
+    #
+    module Amount
+      DECIMAL_STRING_PATTERN = /\A[+-]?\d+(\.\d+)?\z/
+
+      ##
+      # Divide an amount by 10**decimals and return the exact decimal string.
+      # Accepts Integers and decimal strings ('7.5'); leading zeros are decimal,
+      # never octal. Mirrors BigNumber(amount).dividedBy(10**unit).
+      #
+      #   MixinBot.utils.format_units(10**17, 18) # => "0.1"
+      #   MixinBot.utils.format_units('010', 18)  # => "0.00000000000000001"
+      #   MixinBot.utils.format_units('7.5', 2)   # => "0.075"
+      #
+      def format_units(amount, decimals)
+        decimals = validated_decimals(decimals)
+        value = validated_amount_string(amount)
+
+        sign = value.start_with?('-') ? '-' : ''
+        whole, fraction = value.delete_prefix('-').delete_prefix('+').split('.')
+        fraction ||= ''
+        digits = "#{whole}#{fraction}".sub(/\A0+(?=\d)/, '')
+        shift = fraction.length + decimals
+
+        formatted =
+          if shift.zero?
+            digits
+          elsif digits.size > shift
+            "#{digits[0...-shift]}.#{digits[-shift..]}"
+          else
+            "0.#{'0' * (shift - digits.size)}#{digits}"
+          end
+
+        "#{sign}#{formatted}".sub(/(\.\d*?)0+\z/, '\1').sub(/\.\z/, '')
+      end
+
+      ##
+      # Multiply a decimal amount string by 10**decimals and return integer
+      # minor units. Values with more precision than +decimals+ round down
+      # (floor), matching the Node SDK; invalid strings raise +ArgumentError+.
+      #
+      #   MixinBot.utils.parse_units('0.1', 18) # => 100000000000000000
+      #
+      def parse_units(amount, decimals)
+        decimals = validated_decimals(decimals)
+        value = validated_amount_string(amount)
+
+        (value.to_d * (10**decimals)).floor
+      end
+
+      private
+
+      def validated_amount_string(amount)
+        value = amount.to_s.strip
+        raise ArgumentError, "invalid amount #{amount.inspect}" unless value.match?(DECIMAL_STRING_PATTERN)
+
+        value
+      end
+
+      # accepts Integers and numeric strings (base-10, so '010' is ten, never octal)
+      def validated_decimals(decimals)
+        decimals = Integer(decimals, 10) if decimals.is_a?(String) && decimals.match?(/\A[+-]?\d+\z/)
+        return decimals if decimals.is_a?(Integer) && decimals >= 0
+
+        raise ArgumentError, "decimals must be a non-negative Integer, got #{decimals.inspect}"
+      end
+    end
+  end
+end

data/lib/mixin_bot/utils/crypto.rb

@@ -95,6 +95,20 @@ module MixinBot
         JOSE::JWT.sign(jwk, jws, jwt).compact
       end
 
+      ##
+      # Derives an OAuth PKCE code challenge (S256) from a code verifier:
+      # base64url(SHA-256(verifier)) without padding.
+      #
+      # @param verifier [String] the PKCE code verifier
+      # @return [String] the code challenge
+      #
+      # @example
+      #   MixinBot.utils.oauth_code_challenge(verifier)
+      #
+      def oauth_code_challenge(verifier)
+        Base64.urlsafe_encode64 Digest::SHA256.digest(verifier), padding: false
+      end
+
       ##
       # Generates a new Ed25519 keypair.
       #

data/lib/mixin_bot/utils.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'utils/address'
+require_relative 'utils/amount'
 require_relative 'utils/crypto'
 require_relative 'utils/decoder'
 require_relative 'utils/encoder'
@@ -53,6 +54,7 @@ module MixinBot
   #
   module Utils
     extend MixinBot::Utils::Address
+    extend MixinBot::Utils::Amount
     extend MixinBot::Utils::Crypto
     extend MixinBot::Utils::Decoder
     extend MixinBot::Utils::Encoder

data/lib/mixin_bot/version.rb

@@ -11,5 +11,5 @@ module MixinBot
   #
   # @see https://semver.org/
   #
-  VERSION = '2.4.1'
+  VERSION = '2.5.0'
 end

data/lib/mixin_bot.rb

@@ -23,6 +23,8 @@ require 'sha3'
 require_relative 'mixin_bot/errors'
 require_relative 'mixin_bot/address'
 require_relative 'mixin_bot/models'
+require_relative 'mixin_bot/session_store'
+require_relative 'mixin_bot/cache_store_adapter'
 require_relative 'mixin_bot/api'
 require_relative 'mixin_bot/bot_auth'
 require_relative 'mixin_bot/cli'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mixin_bot
 version: !ruby/object:Gem::Version
-  version: 2.4.1
+  version: 2.5.0
 platform: ruby
 authors:
 - an-lee
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-08 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -318,6 +318,7 @@ files:
 - lib/mixin_bot/api/user.rb
 - lib/mixin_bot/api/withdraw.rb
 - lib/mixin_bot/bot_auth.rb
+- lib/mixin_bot/cache_store_adapter.rb
 - lib/mixin_bot/cli.rb
 - lib/mixin_bot/cli/api.rb
 - lib/mixin_bot/cli/base.rb
@@ -345,6 +346,7 @@ files:
 - lib/mixin_bot/models/user.rb
 - lib/mixin_bot/monitor.rb
 - lib/mixin_bot/nfo.rb
+- lib/mixin_bot/session_store.rb
 - lib/mixin_bot/transaction.rb
 - lib/mixin_bot/transaction/buffer.rb
 - lib/mixin_bot/transaction/decoder.rb
@@ -352,6 +354,7 @@ files:
 - lib/mixin_bot/url_scheme.rb
 - lib/mixin_bot/utils.rb
 - lib/mixin_bot/utils/address.rb
+- lib/mixin_bot/utils/amount.rb
 - lib/mixin_bot/utils/crypto.rb
 - lib/mixin_bot/utils/decoder.rb
 - lib/mixin_bot/utils/encoder.rb