gasfree_sdk 0.1.0

data/lib/gasfree_sdk/errors.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# GasFree SDK error classes and utilities
+module GasfreeSdk
+  # Base error class for all SDK errors
+  class Error < StandardError
+    attr_reader :code, :reason
+
+    def initialize(message, code: nil, reason: nil)
+      super(message)
+      @code = code
+      @reason = reason
+    end
+  end
+
+  # Authentication related errors
+  class AuthenticationError < Error; end
+
+  # API related errors
+  class APIError < Error; end
+
+  # Invalid signature errors
+  class InvalidSignatureError < APIError; end
+
+  # Deadline exceeded errors
+  class DeadlineExceededError < APIError; end
+
+  # Insufficient balance errors
+  class InsufficientBalanceError < APIError; end
+
+  # Address not found errors
+  class AddressNotFoundError < APIError; end
+
+  # Transfer not found errors
+  class TransferNotFoundError < APIError; end
+
+  class << self
+    # Map error codes to specific error classes
+    ERROR_CODE_MAP = {
+      "INVALID_SIGNATURE" => InvalidSignatureError,
+      "DEADLINE_EXCEEDED" => DeadlineExceededError,
+      "INSUFFICIENT_BALANCE" => InsufficientBalanceError,
+      "ADDRESS_NOT_FOUND" => AddressNotFoundError,
+      "TRANSFER_NOT_FOUND" => TransferNotFoundError
+    }.freeze
+
+    # Factory method to create appropriate error instances
+    # @param code [String] Error code from API
+    # @param reason [String] Error reason from API
+    # @param message [String] Error message from API
+    # @return [Error] Appropriate error instance
+    def build_error(code:, reason:, message:)
+      error_class = determine_error_class(code, reason)
+      error_class.new(message, code: code, reason: reason)
+    end
+
+    private
+
+    def determine_error_class(code, reason)
+      return ERROR_CODE_MAP[code] if ERROR_CODE_MAP.key?(code)
+
+      case reason
+      when /signature/i then InvalidSignatureError
+      when /deadline/i then DeadlineExceededError
+      when /balance/i then InsufficientBalanceError
+      when /not found/i
+        determine_not_found_error(reason)
+      else
+        APIError
+      end
+    end
+
+    def determine_not_found_error(reason)
+      case reason
+      when /address/i then AddressNotFoundError
+      when /transfer/i then TransferNotFoundError
+      else APIError
+      end
+    end
+  end
+end

data/lib/gasfree_sdk/models/gas_free_address.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module GasfreeSdk
+  module Models
+    # Represents an asset in a GasFree account
+    class Asset < Dry::Struct
+      transform_keys(&:to_sym)
+
+      # @!attribute [r] token_address
+      #   @return [String] The token contract address
+      attribute :token_address, Types::Address
+
+      # @!attribute [r] token_symbol
+      #   @return [String] The token symbol
+      attribute :token_symbol, Types::String
+
+      # @!attribute [r] activate_fee
+      #   @return [String] The activation fee in the smallest unit
+      attribute :activate_fee, Types::Amount
+
+      # @!attribute [r] transfer_fee
+      #   @return [String] The transfer fee in the smallest unit
+      attribute :transfer_fee, Types::Amount
+
+      # @!attribute [r] decimal
+      #   @return [Integer] The token's decimal places
+      attribute :decimal, Types::Integer.constrained(gteq: 0)
+
+      # @!attribute [r] frozen
+      #   @return [String] Amount currently frozen in pending transfers
+      attribute :frozen, Types::Amount
+    end
+
+    # Represents a GasFree account
+    class GasFreeAddress < Dry::Struct
+      transform_keys(&:to_sym)
+
+      # @!attribute [r] account_address
+      #   @return [String] The user's EOA address
+      attribute :account_address, Types::Address
+
+      # @!attribute [r] gas_free_address
+      #   @return [String] The GasFree account address
+      attribute :gas_free_address, Types::Address
+
+      # @!attribute [r] active
+      #   @return [Boolean] Whether the account is activated
+      attribute :active, Types::Bool
+
+      # @!attribute [r] nonce
+      #   @return [Integer] The recommended nonce for the next transfer
+      attribute :nonce, Types::Nonce
+
+      # @!attribute [r] allow_submit
+      #   @return [Boolean] Whether new transfers can be submitted
+      attribute :allow_submit, Types::Bool
+
+      # @!attribute [r] assets
+      #   @return [Array<Asset>] List of assets in the account
+      attribute :assets, Types::Array.of(Asset)
+    end
+  end
+end

data/lib/gasfree_sdk/models/provider.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module GasfreeSdk
+  module Models
+    # Configuration for a service provider
+    class ProviderConfig < Dry::Struct
+      transform_keys(&:to_sym)
+
+      # @!attribute [r] max_pending_transfer
+      #   @return [Integer] Maximum number of pending transfers allowed
+      attribute :max_pending_transfer, Types::Integer.constrained(gteq: 0)
+
+      # @!attribute [r] min_deadline_duration
+      #   @return [Integer] Minimum deadline duration in seconds
+      attribute :min_deadline_duration, Types::Integer.constrained(gteq: 0)
+
+      # @!attribute [r] max_deadline_duration
+      #   @return [Integer] Maximum deadline duration in seconds
+      attribute :max_deadline_duration, Types::Integer.constrained(gteq: 0)
+
+      # @!attribute [r] default_deadline_duration
+      #   @return [Integer] Default deadline duration in seconds
+      attribute :default_deadline_duration, Types::Integer.constrained(gteq: 0)
+    end
+
+    # Represents a GasFree service provider
+    class Provider < Dry::Struct
+      transform_keys(&:to_sym)
+
+      # @!attribute [r] address
+      #   @return [String] The provider's address
+      attribute :address, Types::Address
+
+      # @!attribute [r] name
+      #   @return [String] The provider's name
+      attribute :name, Types::String
+
+      # @!attribute [r] icon
+      #   @return [String] URL to the provider's icon
+      attribute :icon, Types::String
+
+      # @!attribute [r] website
+      #   @return [String] The provider's website
+      attribute :website, Types::String
+
+      # @!attribute [r] config
+      #   @return [ProviderConfig] The provider's configuration
+      attribute :config, ProviderConfig
+    end
+  end
+end

data/lib/gasfree_sdk/models/token.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module GasfreeSdk
+  module Models
+    # Represents a token supported by GasFree
+    class Token < Dry::Struct
+      transform_keys(&:to_sym)
+
+      # @!attribute [r] token_address
+      #   @return [String] The token contract address
+      attribute :token_address, Types::Address
+
+      # @!attribute [r] created_at
+      #   @return [Time] When the token was added to GasFree
+      attribute :created_at, Types::JSON::Time
+
+      # @!attribute [r] updated_at
+      #   @return [Time] When the token was last updated
+      attribute :updated_at, Types::JSON::Time
+
+      # @!attribute [r] activate_fee
+      #   @return [String] The activation fee in the smallest unit of the token
+      attribute :activate_fee, Types::Amount
+
+      # @!attribute [r] transfer_fee
+      #   @return [String] The transfer fee in the smallest unit of the token
+      attribute :transfer_fee, Types::Amount
+
+      # @!attribute [r] supported
+      #   @return [Boolean] Whether the token is currently supported
+      attribute :supported, Types::Bool
+
+      # @!attribute [r] symbol
+      #   @return [String] The token symbol (e.g., "USDT")
+      attribute :symbol, Types::String
+
+      # @!attribute [r] decimal
+      #   @return [Integer] The token's decimal places
+      attribute :decimal, Types::Integer.constrained(gteq: 0)
+    end
+  end
+end

data/lib/gasfree_sdk/models/transfer_request.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module GasfreeSdk
+  module Models
+    # Represents a GasFree transfer request
+    class TransferRequest < Dry::Struct
+      transform_keys(&:to_sym)
+
+      # @!attribute [r] token
+      #   @return [String] The token contract address
+      attribute :token, Types::Address
+
+      # @!attribute [r] service_provider
+      #   @return [String] The service provider's address
+      attribute :service_provider, Types::Address
+
+      # @!attribute [r] user
+      #   @return [String] The user's EOA address
+      attribute :user, Types::Address
+
+      # @!attribute [r] receiver
+      #   @return [String] The recipient's address
+      attribute :receiver, Types::Address
+
+      # @!attribute [r] value
+      #   @return [String] The transfer amount in smallest unit
+      attribute :value, Types::Amount
+
+      # @!attribute [r] max_fee
+      #   @return [String] Maximum fee limit in smallest unit
+      attribute :max_fee, Types::Amount
+
+      # @!attribute [r] deadline
+      #   @return [Integer] Transfer expiration timestamp
+      attribute :deadline, Types::Timestamp
+
+      # @!attribute [r] version
+      #   @return [Integer] Signature version
+      attribute :version, Types::Version
+
+      # @!attribute [r] nonce
+      #   @return [Integer] Transfer nonce
+      attribute :nonce, Types::Nonce
+
+      # @!attribute [r] sig
+      #   @return [String] User's signature
+      attribute :sig, Types::String
+    end
+  end
+end

data/lib/gasfree_sdk/models/transfer_response.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module GasfreeSdk
+  module Models
+    # Represents a GasFree transfer response
+    class TransferResponse < Dry::Struct
+      transform_keys(&:to_sym)
+
+      # @!attribute [r] id
+      #   @return [String] The transfer trace ID
+      attribute :id, Types::String
+
+      # @!attribute [r] created_at
+      #   @return [Time] When the transfer was created
+      attribute :created_at, Types::JSON::Time
+
+      # @!attribute [r] updated_at
+      #   @return [Time] When the transfer was last updated
+      attribute :updated_at, Types::JSON::Time
+
+      # @!attribute [r] account_address
+      #   @return [String] The user's EOA address
+      attribute :account_address, Types::Address
+
+      # @!attribute [r] gas_free_address
+      #   @return [String] The GasFree account address
+      attribute :gas_free_address, Types::Address
+
+      # @!attribute [r] provider_address
+      #   @return [String] The service provider's address
+      attribute :provider_address, Types::Address
+
+      # @!attribute [r] target_address
+      #   @return [String] The recipient's address
+      attribute :target_address, Types::Address
+
+      # @!attribute [r] token_address
+      #   @return [String] The token contract address
+      attribute :token_address, Types::Address
+
+      # @!attribute [r] amount
+      #   @return [String] The transfer amount
+      attribute :amount, Types::Amount
+
+      # @!attribute [r] max_fee
+      #   @return [String] Maximum fee limit
+      attribute :max_fee, Types::Amount
+
+      # @!attribute [r] signature
+      #   @return [String] User's signature
+      attribute :signature, Types::String
+
+      # @!attribute [r] nonce
+      #   @return [Integer] Transfer nonce
+      attribute :nonce, Types::Nonce
+
+      # @!attribute [r] expired_at
+      #   @return [Time] When the transfer expires
+      attribute :expired_at, Types::JSON::Time
+
+      # @!attribute [r] state
+      #   @return [String] Current transfer state
+      attribute :state, Types::State
+
+      # @!attribute [r] estimated_activate_fee
+      #   @return [String] Estimated activation fee
+      attribute? :estimated_activate_fee, Types::Amount
+
+      # @!attribute [r] estimated_transfer_fee
+      #   @return [String] Estimated transfer fee
+      attribute? :estimated_transfer_fee, Types::Amount
+
+      # @!attribute [r] txn_hash
+      #   @return [String] On-chain transaction hash
+      attribute? :txn_hash, Types::Hash
+
+      # @!attribute [r] txn_block_num
+      #   @return [Integer] Block number containing the transaction
+      attribute? :txn_block_num, Types::Integer
+
+      # @!attribute [r] txn_block_timestamp
+      #   @return [Integer] Block timestamp in milliseconds
+      attribute? :txn_block_timestamp, Types::Integer
+
+      # @!attribute [r] txn_state
+      #   @return [String] On-chain transaction state
+      attribute? :txn_state, Types::String.constrained(
+        included_in: %w[INIT NOT_ON_CHAIN ON_CHAIN SOLIDITY ON_CHAIN_FAILED]
+      )
+
+      # @!attribute [r] txn_activate_fee
+      #   @return [String] Actual activation fee
+      attribute? :txn_activate_fee, Types::Amount
+
+      # @!attribute [r] txn_transfer_fee
+      #   @return [String] Actual transfer fee
+      attribute? :txn_transfer_fee, Types::Amount
+
+      # @!attribute [r] txn_total_fee
+      #   @return [String] Total actual fee
+      attribute? :txn_total_fee, Types::Amount
+
+      # @!attribute [r] txn_amount
+      #   @return [String] Actual transferred amount
+      attribute? :txn_amount, Types::Amount
+
+      # @!attribute [r] txn_total_cost
+      #   @return [String] Total cost including fees
+      attribute? :txn_total_cost, Types::Amount
+    end
+  end
+end

data/lib/gasfree_sdk/models.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "models/token"
+require_relative "models/provider"
+require_relative "models/gas_free_address"
+require_relative "models/transfer_request"
+require_relative "models/transfer_response"
+
+module GasfreeSdk
+  # Models namespace
+  module Models
+  end
+end

data/lib/gasfree_sdk/types.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "dry-types"
+
+module GasfreeSdk
+  # Custom types for the SDK
+  module Types
+    include Dry.Types()
+
+    # Address type with validation
+    Address = Types::String.constrained(format: /\A(0x)?[0-9a-fA-F]{40}\z/)
+
+    # Hash type with validation
+    Hash = Types::String.constrained(format: /\A(0x)?[0-9a-fA-F]{64}\z/)
+
+    # Amount type (string representation of a number)
+    Amount = Types::String.constrained(format: /\A[0-9]+\z/)
+
+    # Timestamp type (Unix timestamp)
+    Timestamp = Types::Integer.constrained(gteq: 0)
+
+    # Chain ID type
+    ChainId = Types::Integer.constrained(gteq: 1)
+
+    # Nonce type
+    Nonce = Types::Integer.constrained(gteq: 0)
+
+    # Version type
+    Version = Types::Integer.constrained(included_in: [1])
+
+    # State type
+    State = Types::String.constrained(included_in: %w[
+                                        WAITING
+                                        INPROGRESS
+                                        CONFIRMING
+                                        SUCCEED
+                                        FAILED
+                                      ])
+  end
+end

data/lib/gasfree_sdk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GasfreeSdk
+  VERSION = "0.1.0"
+end

data/lib/gasfree_sdk.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "dry-configurable"
+require "dry-struct"
+require "dry-types"
+require "dry-validation"
+require "faraday"
+require "faraday/retry"
+require "eth"
+
+require_relative "gasfree_sdk/version"
+require_relative "gasfree_sdk/types"
+require_relative "gasfree_sdk/client"
+require_relative "gasfree_sdk/errors"
+require_relative "gasfree_sdk/models"
+
+# Main module for GasFree SDK
+module GasfreeSdk
+  extend Dry::Configurable
+
+  # Default API endpoint
+  setting :api_endpoint, default: "https://open.gasfree.io/tron/"
+  setting :api_key, default: nil
+  setting :api_secret, default: nil
+  setting :default_chain_id, default: 1 # Ethereum mainnet
+  setting :default_deadline_duration, default: 180 # 3 minutes
+  setting :logger, default: Logger.new($stdout)
+  setting :retry_options, default: {
+    max: 3,
+    interval: 0.5,
+    interval_randomness: 0.5,
+    backoff_factor: 2
+  }
+
+  class << self
+    # Configure the SDK
+    # @yield [config] Configuration block
+    # @example
+    #   GasfreeSdk.configure do |config|
+    #     config.api_key = "your-api-key"
+    #     config.api_secret = "your-api-secret"
+    #     config.api_endpoint = "https://open.gasfree.io/tron/"
+    #   end
+    def configure
+      yield config
+    end
+
+    # Create a new client instance
+    # @return [GasfreeSdk::Client]
+    def client
+      @client ||= Client.new
+    end
+
+    # Reset the client instance
+    # @return [void]
+    def reset_client!
+      @client = nil
+    end
+  end
+
+  # Base error class for all SDK errors
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/sig/gasfree_sdk.rbs

@@ -0,0 +1,4 @@
+module GasfreeSdk
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end