mixin_bot 1.4.0 → 2.0.0

data/lib/mixin_bot/api/transfer.rb

@@ -2,18 +2,108 @@
 
 module MixinBot
   class API
+    ##
+    # API methods for creating transfers using the Safe API.
+    #
+    # The Safe API is the recommended way to transfer assets on Mixin Network.
+    # It provides better security, lower fees, and more flexibility than legacy transfers.
+    #
+    # == Transfer Process
+    #
+    # A Safe transfer involves several steps:
+    # 1. Select UTXOs (unspent transaction outputs) as inputs
+    # 2. Build the transaction with outputs
+    # 3. Sign the transaction with spend key
+    # 4. Submit the signed transaction
+    #
+    # This module handles all these steps automatically.
+    #
+    # == Usage
+    #
+    #   # Simple transfer to a single user
+    #   api.create_transfer(
+    #     members: 'user-uuid',
+    #     asset_id: 'asset-uuid',
+    #     amount: '0.01',
+    #     memo: 'Payment'
+    #   )
+    #
+    #   # Multisig transfer
+    #   api.create_transfer(
+    #     members: ['user1-uuid', 'user2-uuid', 'user3-uuid'],
+    #     threshold: 2,
+    #     asset_id: 'asset-uuid',
+    #     amount: '0.01'
+    #   )
+    #
     module Transfer
-      # kwargs:
-      # {
-      #  members: uuid | [ uuid ],
-      #  threshold: integer / nil,
-      #  asset_id: uuid,
-      #  amount: string / float,
-      #  trace_id: uuid / nil,
-      #  request_id: uuid / nil,
-      #  memo: string,
-      #  spend_key: string / nil,
-      # }
+      ##
+      # Creates a Safe API transfer.
+      #
+      # This is the main method for sending assets on Mixin Network.
+      # It handles the complete transfer process including UTXO selection,
+      # transaction building, signing, and submission.
+      #
+      # @param kwargs [Hash] transfer options
+      # @option kwargs [String, Array<String>] :members recipient user ID(s)
+      # @option kwargs [Integer] :threshold multisig threshold (defaults to members.length)
+      # @option kwargs [String] :asset_id the asset UUID to transfer
+      # @option kwargs [String, Float] :amount the amount to transfer
+      # @option kwargs [String] :trace_id unique trace ID (defaults to random UUID)
+      # @option kwargs [String] :request_id alias for trace_id
+      # @option kwargs [String] :memo transaction memo (max 140 characters)
+      # @option kwargs [String] :spend_key spend private key (defaults to config.spend_key)
+      # @option kwargs [Array<Hash>] :utxos specific UTXOs to use (optional, will auto-select if not provided)
+      #
+      # @return [Hash] the transfer result including transaction hash and status
+      #
+      # @raise [ArgumentError] if required parameters are missing or invalid
+      # @raise [InsufficientBalanceError] if balance is insufficient
+      #
+      # @example Simple transfer
+      #   result = api.create_transfer(
+      #     members: '6ae1c7ae-1df1-498e-8f21-d48cb6d129b5',
+      #     asset_id: '965e5c6e-434c-3fa9-b780-c50f43cd955c',
+      #     amount: '0.01',
+      #     memo: 'Test payment'
+      #   )
+      #   puts result['snapshot_id']
+      #
+      # @example Multisig transfer (2-of-3)
+      #   result = api.create_transfer(
+      #     members: [
+      #       '6ae1c7ae-1df1-498e-8f21-d48cb6d129b5',
+      #       '8017d200-7870-4b82-b53f-74bae1d2dad7',
+      #       'e8e8cd79-cd40-4796-8c54-3a13cfe50115'
+      #     ],
+      #     threshold: 2,
+      #     asset_id: '965e5c6e-434c-3fa9-b780-c50f43cd955c',
+      #     amount: '0.01'
+      #   )
+      #
+      def create_transfer(pin = nil, **kwargs)
+        if pin.is_a?(String) && kwargs[:opponent_id].present?
+          create_legacy_transfer(pin, **kwargs)
+        else
+          create_safe_transfer(**(pin.is_a?(Hash) ? pin : kwargs))
+        end
+      end
+
+      def send_transaction(**)
+        create_safe_transfer(**)
+      end
+      alias send_transfer_transaction send_transaction
+      alias send_transaction_with_outputs send_transaction
+
+      def send_transaction_until_sufficient(**)
+        create_safe_transfer(**)
+      end
+
+      def send_transaction_with_change_outputs(**)
+        create_safe_transfer(**)
+      end
+      alias send_transaction_with_utxos_and_change_outputs send_transaction_with_change_outputs
+
       def create_safe_transfer(**kwargs)
         utxos = kwargs[:utxos]
         raise ArgumentError, 'utxos must be array' if utxos.present? && !utxos.is_a?(Array)
@@ -70,17 +160,54 @@ module MixinBot
           signed_raw
         )
       end
-      alias create_transfer create_safe_transfer
 
+      ##
+      # Builds a UTXO set for a transfer.
+      #
+      # Selects unspent outputs (UTXOs) from the bot's wallet that sum up
+      # to at least the requested amount. This is used internally by
+      # create_safe_transfer but can be called directly if needed.
+      #
+      # The method:
+      # - Fetches unspent outputs for the asset
+      # - Sorts them by amount (smallest first)
+      # - Selects outputs until the amount is reached
+      # - Limits to 256 UTXOs maximum
+      #
+      # @param asset_id [String] the asset UUID
+      # @param amount [String, Float, BigDecimal] the amount needed
+      # @return [Array<Hash>] array of selected UTXOs
+      #
+      # @raise [InsufficientBalanceError] if balance is insufficient
+      #
+      # @example
+      #   utxos = api.build_utxos(
+      #     asset_id: '965e5c6e-434c-3fa9-b780-c50f43cd955c',
+      #     amount: '0.01'
+      #   )
+      #   puts "Selected #{utxos.length} UTXOs"
+      #   puts "Total: #{utxos.sum { |u| u['amount'].to_d }}"
+      #
       def build_utxos(asset_id:, amount:)
+        amount = amount.to_d
         outputs = safe_outputs(state: 'unspent', asset: asset_id, limit: 500)['data'].sort_by { |o| o['amount'].to_d }
 
         utxos = []
         outputs.each do |output|
-          break if utxos.sum { |o| o['amount'].to_d } >= amount
+          break if utxos.size >= 256
 
-          utxos.shift if utxos.size >= 256
           utxos << output
+          break if utxos.sum { |o| o['amount'].to_d } >= amount
+        end
+
+        total_in = utxos.sum { |o| o['amount'].to_d }
+        if total_in < amount
+          raise MixinBot::UtxoInsufficientError.new(
+            'insufficient utxo',
+            total_input: total_in,
+            total_output: amount,
+            output_size: utxos.size
+          )
         end
 
         utxos

data/lib/mixin_bot/api/turn.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module MixinBot
+  class API
+    module Turn
+      def turn_servers(access_token: nil)
+        client.get '/turn', access_token:
+      end
+      alias get_turn_server turn_servers
+    end
+  end
+end

data/lib/mixin_bot/api/user.rb

@@ -2,12 +2,43 @@
 
 module MixinBot
   class API
+    ##
+    # User-related API endpoints: bot/network user lookup, plain network-user
+    # creation, and the full Safe Network registration flow.
+    #
+    # The Safe-network registration mirrors the official Go SDK reference
+    # implementation in +RegisterSafeWithSetupPin+ / +RegisterSafeBareUser+:
+    # https://github.com/MixinNetwork/bot-api-go-client/blob/master/safe_user.go
+    #
     module User
+      # Maximum number of times to retry +safe_register+ when the freshly-set
+      # TIP PIN has not yet propagated through the Mixin server.
+      SAFE_REGISTER_MAX_RETRIES = 3
+
+      # Base seconds to wait between +safe_register+ retries. The wait grows
+      # linearly with the attempt number.
+      SAFE_REGISTER_RETRY_BASE_DELAY = 1
+
+      # Seconds to wait after +update_pin+ before calling +safe_register+, so
+      # the new TIP PIN has time to propagate on the server side.
+      TIP_PIN_PROPAGATION_DELAY = 1
+
       def user(user_id, access_token: nil)
         path = format('/users/%<user_id>s', user_id:)
         client.get path, access_token:
       end
 
+      ##
+      # Creates a Mixin network user.
+      #
+      # When +key+ is omitted a fresh Ed25519 keypair is generated. The
+      # response is merged with the hex-encoded session private key under
+      # +:private_key+.
+      #
+      # @param full_name [String] display name for the new user
+      # @param key [String, nil] optional 32-byte Ed25519 seed
+      # @return [Hash] Mixin response merged with the hex-encoded private key
+      #
       def create_user(full_name, key: nil)
         keypair = JOSE::JWA::Ed25519.keypair key
         session_secret = Base64.urlsafe_encode64 keypair[0], padding: false
@@ -37,54 +68,95 @@ module MixinBot
         client.post path, *payload
       end
 
+      ##
+      # Creates a Safe-network user end-to-end.
+      #
+      # Mirrors +RegisterSafeWithSetupPin+ in the Go SDK:
+      #
+      # 1. generate (or accept) a session keypair and a spend keypair
+      # 2. create the network user via {#create_user}
+      # 3. set the user's PIN to the TIP public key derived from the spend key
+      # 4. wait briefly for propagation, then register on the Safe network
+      #    (retrying transient failures)
+      #
+      # The returned keystore is suitable for instantiating a new
+      # +MixinBot::API+ that authenticates as the freshly-registered user.
+      #
+      # @param name [String] display name for the new user
+      # @param private_key [String, nil] optional 32-byte session Ed25519 seed
+      # @param spend_key [String, nil] optional 32-byte spend Ed25519 seed
+      # @return [Hash] keystore with +:app_id+, +:session_id+,
+      #   +:session_private_key+, +:server_public_key+ and +:spend_key+
+      # @raise [MixinBot::Error] when registration ultimately fails. Transient
+      #   PIN/response errors are retried up to {SAFE_REGISTER_MAX_RETRIES}
+      #   times; other errors bubble up immediately.
+      #
       def create_safe_user(name, private_key: nil, spend_key: nil)
-        private_keypair = JOSE::JWA::Ed25519.keypair private_key
-        private_key = private_keypair[1].unpack1('H*')
-
+        session_keypair = JOSE::JWA::Ed25519.keypair private_key
         spend_keypair = JOSE::JWA::Ed25519.keypair spend_key
-        spend_key = spend_keypair[1].unpack1('H*')
 
-        user = create_user name, key: private_keypair[1][...32]
+        spend_key_hex = spend_keypair[1].unpack1('H*')
+
+        user = create_user name, key: session_keypair[1][...32]
+        data = user.fetch('data')
 
         keystore = {
-          app_id: user['data']['user_id'],
-          session_id: user['data']['session_id'],
-          session_private_key: private_key,
-          server_public_key: user['data']['pin_token_base64'],
-          spend_key:
+          app_id: data['user_id'],
+          session_id: data['session_id'],
+          session_private_key: session_keypair[1].unpack1('H*'),
+          server_public_key: data['pin_token_base64'],
+          spend_key: spend_key_hex
         }
-        user_api = MixinBot::API.new(**keystore)
 
-        user_api.update_pin pin: MixinBot.utils.tip_public_key(spend_keypair[0], counter: user['data']['tip_counter'])
+        user_api = MixinBot::API.new(**keystore)
 
-        # wait for tip pin update in server
-        sleep 1
+        tip_pin = MixinBot.utils.tip_public_key spend_keypair[0], counter: data['tip_counter']
+        user_api.update_pin pin: tip_pin
 
-        @__retry__ = 0
-        begin
-          user_api.safe_register keystore[:spend_key]
-        rescue MixinBot::Error => e
-          @__retry__ += 1
-          raise e if @__retry__ > 3
+        # Allow the freshly-set TIP PIN to propagate before registering.
+        sleep TIP_PIN_PROPAGATION_DELAY
 
-          sleep 1 + @__retry__
-          retry
+        with_safe_register_retries do
+          user_api.safe_register spend_key_hex
         end
 
         keystore
       end
 
-      def safe_register(pin, spend_key: nil)
+      ##
+      # Registers an existing user on the Safe network.
+      #
+      # +spend_key+ may be supplied as raw bytes, a hex string, or a
+      # Base64-encoded string. It must encode the user's full Ed25519 spend
+      # private key (or a 32-byte seed).
+      #
+      # @param spend_key [String] the user's spend Ed25519 private key
+      # @return [Hash] Mixin response
+      # @raise [ArgumentError] when +spend_key+ cannot be decoded into at
+      #   least 32 bytes
+      #
+      def safe_register(spend_key)
         path = '/safe/users'
 
-        spend_key ||= MixinBot.utils.decode_key pin
-        key = JOSE::JWA::Ed25519.keypair spend_key[...32]
-        public_key = key[0].unpack1('H*')
+        spend_key_bytes = MixinBot.utils.decode_key spend_key
+        raise ArgumentError, 'invalid spend_key' if spend_key_bytes.nil? || spend_key_bytes.size < 32
+
+        keypair = JOSE::JWA::Ed25519.keypair spend_key_bytes[...32]
+        public_key = keypair[0].unpack1('H*')
+        # Normalize to a 64-byte signing key in hex so that callers may pass a
+        # 32-byte seed without crashing the downstream signer.
+        signing_key_hex = keypair[1].unpack1('H*')
 
-        hex = SHA3::Digest::SHA256.hexdigest config.app_id
-        signature = Base64.urlsafe_encode64 JOSE::JWA::Ed25519.sign([hex].pack('H*'), key[1]), padding: false
+        # NOTE: the Go SDK's +crypto.Sha256Hash+ is misleadingly named — it
+        # actually computes SHA3-256, so +SHA3::Digest::SHA256+ is the correct
+        # match. See bot-api-go-client safe_user.go +RegisterSafeBareUser+.
+        app_id_hash = SHA3::Digest::SHA256.hexdigest config.app_id
+        signature = Base64.urlsafe_encode64(
+          JOSE::JWA::Ed25519.sign([app_id_hash].pack('H*'), keypair[1]),
+          padding: false
+        )
 
-        pin_base64 = encrypt_tip_pin pin, 'SEQUENCER:REGISTER:', config.app_id, public_key
+        pin_base64 = encrypt_tip_pin signing_key_hex, 'SEQUENCER:REGISTER:', config.app_id, public_key
 
         payload = {
           public_key:,
@@ -95,37 +167,68 @@ module MixinBot
         client.post path, **payload
       end
 
+      ##
+      # Migrates an existing legacy user to the Safe network.
+      #
+      # When the user has not yet upgraded to a TIP PIN, +pin+ must be the
+      # user's current 6-digit PIN so {#update_pin} can rotate it to a TIP
+      # PIN derived from +spend_key+. When the user already has a TIP PIN,
+      # +pin+ may be omitted.
+      #
+      # @param spend_key [String] the user's spend Ed25519 seed or full key
+      # @param pin [String, nil] the user's current PIN (only required when
+      #   the user has not yet upgraded to a TIP PIN)
+      # @return [TrueClass, Hash] +true+ if the user already has Safe enabled,
+      #   otherwise +{ spend_key: <hex> }+
+      # @raise [MixinBot::Error] when registration ultimately fails. Transient
+      #   PIN/response errors are retried up to {SAFE_REGISTER_MAX_RETRIES}
+      #   times; other errors bubble up immediately.
+      #
       def migrate_to_safe(spend_key:, pin: nil)
         profile = me['data']
         return true if profile['has_safe']
 
         spend_keypair = JOSE::JWA::Ed25519.keypair spend_key
-        spend_key = spend_keypair[1].unpack1('H*')
+        spend_key_hex = spend_keypair[1].unpack1('H*')
 
         if profile['tip_key_base64'].blank?
-          new_pin = MixinBot.utils.tip_public_key(spend_keypair[0], counter: profile['tip_counter'])
-          update_pin(pin: new_pin, old_pin: pin)
+          new_pin = MixinBot.utils.tip_public_key spend_keypair[0], counter: profile['tip_counter']
+          update_pin pin: new_pin, old_pin: pin
+        end
+
+        # Allow the freshly-set TIP PIN to propagate before registering.
+        sleep TIP_PIN_PROPAGATION_DELAY
 
-          pin = new_pin
+        with_safe_register_retries do
+          safe_register spend_key_hex
         end
 
-        # wait for tip pin update in server
-        sleep 1
+        { spend_key: spend_key_hex }.with_indifferent_access
+      end
+
+      private
 
-        @__retry__ = 0
+      # Errors that are typically caused by the freshly-set TIP PIN not yet
+      # being visible to the Safe-network sequencer. Anything else (auth,
+      # missing user, validation, balance, ...) should bubble up immediately.
+      RETRIABLE_SAFE_REGISTER_ERRORS = [MixinBot::PinError, MixinBot::ResponseError].freeze
+      private_constant :RETRIABLE_SAFE_REGISTER_ERRORS
+
+      # Yields to the block, retrying transient errors up to
+      # {SAFE_REGISTER_MAX_RETRIES} times with linear backoff. The TIP PIN
+      # set by {#update_pin} can take a moment to propagate, so the first
+      # +safe_register+ attempts often fail.
+      def with_safe_register_retries
+        attempt = 0
         begin
-          safe_register pin, spend_key
-        rescue MixinBot::Error => e
-          @__retry__ += 1
-          raise e if @__retry__ > 3
+          yield
+        rescue *RETRIABLE_SAFE_REGISTER_ERRORS
+          attempt += 1
+          raise if attempt > SAFE_REGISTER_MAX_RETRIES
 
-          sleep 1 + @__retry__
+          sleep(SAFE_REGISTER_RETRY_BASE_DELAY + attempt)
           retry
         end
-
-        {
-          spend_key:
-        }.with_indifferent_access
       end
     end
   end

data/lib/mixin_bot/api/withdraw.rb

@@ -14,38 +14,30 @@ module MixinBot
             label: kwargs[:label]
           }
 
-        if pin.length > 6
-          payload[:pin_base64] = encrypt_tip_pin pin, 'TIP:ADDRESS:ADD:', payload[:asset_id], payload[:destination], payload[:tag], payload[:label]
-        else
-          payload[:pin] = encrypt_pin pin
-        end
+        payload.update(
+          tip_or_legacy_pin_payload(pin, 'TIP:ADDRESS:ADD:', payload[:asset_id], payload[:destination], payload[:tag], payload[:label])
+        )
 
         client.post path, **payload
       end
+      alias create_address create_withdraw_address
 
       def get_withdraw_address(address, access_token: nil)
         path = format('/addresses/%<address>s', address:)
 
         client.get path, access_token:
       end
+      alias read_address get_withdraw_address
 
       def delete_withdraw_address(address, **kwargs)
         pin = kwargs[:pin]
 
         path = format('/addresses/%<address>s/delete', address:)
-        payload =
-          if pin.length > 6
-            {
-              pin_base64: encrypt_tip_pin(pin, 'TIP:ADDRESS:REMOVE:', address)
-            }
-          else
-            {
-              pin: encrypt_pin(pin)
-            }
-          end
+        payload = tip_or_legacy_pin_payload(pin, 'TIP:ADDRESS:REMOVE:', address)
 
         client.post path, **payload
       end
+      alias delete_address delete_withdraw_address
 
       def withdrawals(**kwargs)
         address_id = kwargs[:address_id]
@@ -53,7 +45,7 @@ module MixinBot
         amount = format('%.8f', kwargs[:amount].to_d.to_r)
         trace_id = kwargs[:trace_id]
         memo = kwargs[:memo]
-        kwargs[:access_token]
+        access_token = kwargs[:access_token]
 
         path = '/withdrawals'
         payload = {
@@ -63,14 +55,23 @@ module MixinBot
           memo:
         }
 
-        if pin.length > 6
-          fee = '0'
-          payload[:pin_base64] = encrypt_tip_pin pin, 'TIP:WITHDRAW:', address_id, amount, fee, trace_id, memo
-        else
-          payload[:pin] = encrypt_pin pin
-        end
+        fee = '0'
+        payload.update(
+          tip_or_legacy_pin_payload(pin, 'TIP:WITHDRAWAL:CREATE:', address_id, amount, fee, trace_id, memo)
+        )
 
-        client.post path, **payload
+        client.post path, **payload, access_token:
+      end
+      alias send_withdrawal withdrawals
+
+      def withdraw_addresses(asset_id, access_token: nil)
+        path = format('/assets/%<asset_id>s/addresses', asset_id:)
+        client.get path, access_token:
+      end
+      alias get_addresses_by_asset_id withdraw_addresses
+
+      def check_address(asset:, destination:, tag: nil)
+        client.get '/external/addresses/check', asset:, destination:, tag:, access_token: ''
       end
     end
   end