mixin_bot 1.4.0 → 2.1.0

data/lib/mixin_bot/api/transaction.rb

@@ -36,7 +36,7 @@ module MixinBot
         recipients.each_with_index do |recipient, index|
           next if recipient[:mix_address].blank?
 
-          if recipient[:members].all?(&->(m) { m.start_with? MixinBot::Utils::Address::MAIN_ADDRESS_PREFIX })
+          if recipient[:members].all?(&->(m) { m.start_with? MixinBot::MAIN_ADDRESS_PREFIX })
             key = JOSE::JWA::Ed25519.keypair
             gk = {
               mask: key[0].unpack1('H*'),
@@ -54,7 +54,7 @@ module MixinBot
 
             ghost_keys[index] = gk.with_indifferent_access
 
-          elsif recipient[:members].none?(&->(m) { m.start_with? MixinBot::Utils::Address::MAIN_ADDRESS_PREFIX })
+          elsif recipient[:members].none?(&->(m) { m.start_with? MixinBot::MAIN_ADDRESS_PREFIX })
             uuid_recipients.push(
               {
                 receivers: recipient[:members],
@@ -88,7 +88,12 @@ module MixinBot
       # }
       SAFE_RAW_TRANSACTION_ARGUMENTS = %i[utxos receivers].freeze
       def build_safe_transaction(**kwargs)
-        raise ArgumentError, "#{SAFE_RAW_TRANSACTION_ARGUMENTS.join(', ')} are needed for build safe transaction" unless SAFE_RAW_TRANSACTION_ARGUMENTS.all? { |param| kwargs.keys.include? param }
+        unless SAFE_RAW_TRANSACTION_ARGUMENTS.all? do |param|
+                 kwargs.keys.include? param
+               end
+          raise ArgumentError,
+                "#{SAFE_RAW_TRANSACTION_ARGUMENTS.join(', ')} are needed for build safe transaction"
+        end
         raise ArgumentError, 'receivers should be an array' unless kwargs[:receivers].is_a? Array
         raise ArgumentError, 'utxos should be an array' unless kwargs[:utxos].is_a? Array
 
@@ -126,10 +131,20 @@ module MixinBot
         end
         raise ArgumentError, 'recipients too many' if recipients.size > 256
 
-        asset = utxos[0]['asset']
+        mixin_asset_for = lambda do |u|
+          h = u.with_indifferent_access
+          next h[:asset] if h[:asset].present?
+
+          aid = h[:asset_id]
+          raise ArgumentError, 'utxo asset_id or asset is required' if aid.blank?
+
+          SHA3::Digest::SHA256.hexdigest(aid)
+        end
+
+        asset = mixin_asset_for.call(utxos[0])
         inputs = []
         utxos.each do |utxo|
-          raise ArgumentError, 'utxo asset not match' unless utxo['asset'] == asset
+          raise ArgumentError, 'utxo asset not match' unless mixin_asset_for.call(utxo) == asset
 
           inputs << {
             hash: utxo['transaction_hash'],
@@ -171,6 +186,17 @@ module MixinBot
         }
       end
 
+      def verify_raw_transaction(requests)
+        requests = Array(requests).map do |r|
+          r = r.with_indifferent_access
+          { request_id: r[:request_id], raw: r[:raw] }
+        end
+        create_safe_transaction_request(requests.first[:request_id], requests.first[:raw]) if requests.one?
+
+        path = '/safe/transaction/requests'
+        client.post path, *requests
+      end
+
       def create_safe_transaction_request(request_id, raw)
         path = '/safe/transaction/requests'
         payload = [{
@@ -181,25 +207,73 @@ module MixinBot
         client.post path, *payload
       end
 
-      def send_safe_transaction(request_id, raw)
+      def send_safe_transaction(request_id, raw = nil, requests: nil)
         path = '/safe/transactions'
-        payload = [{
-          request_id:,
-          raw:
-        }]
+        payload =
+          if requests.present?
+            Array(requests).map { |r| r.with_indifferent_access.slice(:request_id, :raw) }
+          else
+            [{ request_id:, raw: }]
+          end
 
         client.post path, *payload
       end
+      alias send_raw_transaction send_safe_transaction
 
       def safe_transaction(request_id, access_token: nil)
         path = format('/safe/transactions/%<request_id>s', request_id:)
 
         client.get path, access_token:
       end
+      alias get_transaction_by_id safe_transaction
+      alias get_transaction_by_id_with_safe_user safe_transaction
+
+      def estimate_storage_cost(extra)
+        step = BigDecimal(EXTRA_STORAGE_PRICE_STEP)
+        len = extra.to_s.bytesize
+        steps = (len / 1024) + 1
+        step * steps
+      end
+
+      def storage_recipient
+        MixinBot::MixAddress.from_members(
+          members: [MixinBot.utils.burning_address],
+          threshold: 64
+        )
+      end
+
+      def create_object_storage_transaction(extra:, trace_id:, _references: nil, limit: nil, utxos: nil, **transfer_opts)
+        amount = estimate_storage_cost(extra)
+        amount = [amount, BigDecimal(limit.to_s)].max if limit.present?
+        kwargs = {
+          asset_id: XIN_ASSET_ID,
+          amount: amount.to_s('F'),
+          trace_id:,
+          memo: extra.to_s,
+          **transfer_opts
+        }
+        kwargs[:utxos] = utxos if utxos.present?
+        kwargs[:members] = [config.app_id] unless kwargs.key?(:members)
+        create_safe_transfer(**kwargs)
+      end
+
+      def request_ghost_recipients_with_trace_id(recipients, _trace_id)
+        generate_safe_keys(
+          recipients.map do |r|
+            r = r.with_indifferent_access
+            { members: r[:members], threshold: r[:threshold], mix_address: r[:mix_address] }
+          end
+        )
+      end
 
       SIGN_SAFE_TRANSACTION_ARGUMENTS = %i[raw utxos request spend_key].freeze
       def sign_safe_transaction(**kwargs)
-        raise ArgumentError, "#{SIGN_SAFE_TRANSACTION_ARGUMENTS.join(', ')} are needed for sign safe transaction" unless SIGN_SAFE_TRANSACTION_ARGUMENTS.all? { |param| kwargs.keys.include? param }
+        unless SIGN_SAFE_TRANSACTION_ARGUMENTS.all? do |param|
+                 kwargs.keys.include? param
+               end
+          raise ArgumentError,
+                "#{SIGN_SAFE_TRANSACTION_ARGUMENTS.join(', ')} are needed for sign safe transaction"
+        end
 
         raw = kwargs[:raw]
         tx = MixinBot.utils.decode_raw_transaction raw
@@ -265,7 +339,12 @@ module MixinBot
 
       INSCRIBE_TRANSACTION_ARGUMENTS = %i[content collection_hash].freeze
       def build_inscribe_transaction(**kwargs)
-        raise ArgumentError, "#{INSCRIBE_TRANSACTION_ARGUMENTS.join(', ')} are needed for inscribe transaction" unless INSCRIBE_TRANSACTION_ARGUMENTS.all? { |param| kwargs.keys.include? param }
+        unless INSCRIBE_TRANSACTION_ARGUMENTS.all? do |param|
+                 kwargs.keys.include? param
+               end
+          raise ArgumentError,
+                "#{INSCRIBE_TRANSACTION_ARGUMENTS.join(', ')} are needed for inscribe transaction"
+        end
 
         receivers = kwargs[:receivers].presence || [config.app_id]
         receivers_threshold = kwargs[:receivers_threshold] || receivers.length
@@ -283,14 +362,20 @@ module MixinBot
         MixinBot.api.build_object_transaction data.to_json, references: [collection_hash]
       end
 
-      OCCUPY_INSCRIPTION_TRANSACTION_ARGUMENTS = %i[amount inscription_hash utxos].freeze
+      OCCUPY_INSCRIPTION_TRANSACTION_ARGUMENTS = %i[amount inscription_hash sequence utxos].freeze
       def build_occupy_transaction(**kwargs)
-        raise ArgumentError, "#{OCCUPY_INSCRIPTION_TRANSACTION_ARGUMENTS.join(', ')} are needed for occupy NFT transaction" unless OCCUPY_INSCRIPTION_TRANSACTION_ARGUMENTS.all? { |param| kwargs.keys.include? param }
+        unless OCCUPY_INSCRIPTION_TRANSACTION_ARGUMENTS.all? do |param|
+                 kwargs.keys.include? param
+               end
+          raise ArgumentError,
+                "#{OCCUPY_INSCRIPTION_TRANSACTION_ARGUMENTS.join(', ')} are needed for occupy NFT transaction"
+        end
 
         members = kwargs[:members].presence || [config.app_id]
         threshold = kwargs[:threshold] || members.length
         amount = kwargs[:amount]
         inscription_hash = kwargs[:inscription_hash]
+        sequence = kwargs[:sequence]
 
         receivers = [
           {
@@ -302,11 +387,15 @@ module MixinBot
 
         extra = {
           operation: 'occupy',
-          recipient:,
-          content:
+          sequence:
         }.to_json
 
-        MixinBot.api.build_safe_transaction(utxos:, receivers:, extra:, references: [inscription_hash])
+        build_safe_transaction(utxos: kwargs[:utxos], receivers:, extra:, references: [inscription_hash])
+      end
+
+      def send_kernel_transaction_from_account(**_kwargs)
+        raise NotImplementedError,
+              'send_kernel_transaction_from_account requires kernel UTXO signing; use native mixin CLI or build manually'
       end
     end
   end

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