gasfree_sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20a368c1b6e6f12801569a0874cdef79af724a074f4a31a51843a3f569ca411d
+  data.tar.gz: eab16b631f5d5b4f3a84caa263cd4bfbcdc153f299da52c8d765f6da6ad4da3f
+SHA512:
+  metadata.gz: 1405d5c293cac1560e6c4ee8313be4214e3d51c2ff5e7f80c5d2b83c47b6556bbf188ffedb339c8f21c1914c2a8457e564ae26004d7b1f5623a55062fde086be
+  data.tar.gz: 064c36e078a3ef3de405c09a8d3783e1000bd86dc29064f9735de547aaad6b71658641f30a74224b37b223bc30e292dda0543a98e4d9e6186d696373c1bb2710

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,49 @@
+AllCops:
+  TargetRubyVersion: 3.3
+  SuggestExtensions: false
+  Exclude:
+    - 'vendor/**/*'
+    - 'bin/**/*'
+
+require:
+  - rubocop-rake
+  - rubocop-rspec
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'gasfree_sdk.gemspec'
+    - 'examples/**/*'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'examples/**/*'
+
+Metrics/MethodLength:
+  Max: 15
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+  Exclude:
+    - 'spec/**/*'
+
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'examples/**/*'
+    - 'lib/gasfree_sdk/errors.rb'
+
+RSpec/ExampleLength:
+  Max: 30
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-05-26
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 madmatvey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,149 @@
+# GasfreeSdk
+
+Ruby SDK for interacting with the GasFree.io API, enabling gasless transfers of TRC-20/ERC-20 tokens.
+
+## Features
+
+- Supports gasless transfers of TRC-20/ERC-20 tokens
+- Handles address generation and transaction signing
+- Provides a clean, Ruby-like interface to the GasFree API
+- Built with dry-rb for robust type checking and validation
+- Comprehensive RSpec test coverage
+- Thread-safe configuration
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'gasfree_sdk'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install gasfree_sdk
+```
+
+## Configuration
+
+Configure the SDK with your API credentials:
+
+```ruby
+GasfreeSdk.configure do |config|
+  config.api_key = "your-api-key"
+  config.api_secret = "your-api-secret"
+  config.api_endpoint = "https://open.gasfree.io/tron/" # Optional, defaults to mainnet
+  config.default_chain_id = 1 # Optional, defaults to Ethereum mainnet
+end
+```
+
+## Usage
+
+### Initialize Client
+
+```ruby
+client = GasfreeSdk.client
+```
+
+### Get Supported Tokens
+
+```ruby
+tokens = client.tokens
+tokens.each do |token|
+  puts "Token: #{token.symbol}"
+  puts "Address: #{token.token_address}"
+  puts "Activation Fee: #{token.activate_fee}"
+  puts "Transfer Fee: #{token.transfer_fee}"
+end
+```
+
+### Get Service Providers
+
+```ruby
+providers = client.providers
+providers.each do |provider|
+  puts "Provider: #{provider.name}"
+  puts "Address: #{provider.address}"
+  puts "Max Pending Transfers: #{provider.config.max_pending_transfer}"
+end
+```
+
+### Get GasFree Account Info
+
+```ruby
+account = client.address("0x1234...")
+puts "GasFree Address: #{account.gas_free_address}"
+puts "Active: #{account.active}"
+puts "Nonce: #{account.nonce}"
+
+account.assets.each do |asset|
+  puts "Token: #{asset.token_symbol}"
+  puts "Frozen Amount: #{asset.frozen}"
+end
+```
+
+### Submit GasFree Transfer
+
+```ruby
+request = GasfreeSdk::Models::TransferRequest.new(
+  token: "0x1234...", # Token address
+  service_provider: "0x5678...", # Provider address
+  user: "0x9abc...", # User's EOA address
+  receiver: "0xdef0...", # Recipient address
+  value: "1000000", # Amount in smallest unit
+  max_fee: "100000", # Maximum fee in smallest unit
+  deadline: Time.now.to_i + 180, # 3 minutes from now
+  version: 1,
+  nonce: 0,
+  sig: "0x..." # User's signature
+)
+
+response = client.submit_transfer(request)
+puts "Transfer ID: #{response.id}"
+puts "State: #{response.state}"
+```
+
+### Check Transfer Status
+
+```ruby
+status = client.transfer_status("transfer-id")
+puts "State: #{status.state}"
+puts "Transaction Hash: #{status.txn_hash}" if status.txn_hash
+```
+
+## Error Handling
+
+The SDK provides detailed error classes for different types of errors:
+
+```ruby
+begin
+  client.submit_transfer(request)
+rescue GasfreeSdk::InsufficientBalanceError => e
+  puts "Insufficient balance: #{e.message}"
+rescue GasfreeSdk::DeadlineExceededError => e
+  puts "Deadline exceeded: #{e.message}"
+rescue GasfreeSdk::APIError => e
+  puts "API error (#{e.code}): #{e.message}"
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/madmatvey/gasfree_sdk.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/basic_usage.rb

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "gasfree_sdk"
+require "eth"
+
+# Configure the SDK
+GasfreeSdk.configure do |config|
+  config.api_key = ENV["GASFREE_API_KEY"] || "your-api-key"
+  config.api_secret = ENV["GASFREE_API_SECRET"] || "your-api-secret"
+  config.api_endpoint = ENV["GASFREE_API_ENDPOINT"] || "https://open.gasfree.io/tron/"
+end
+
+# Check if we have real API credentials
+if GasfreeSdk.config.api_key == "your-api-key"
+  puts "WARNING: Using placeholder API credentials. Set GASFREE_API_KEY and " \
+       "GASFREE_API_SECRET environment variables for real usage."
+  puts "This example will demonstrate the SDK structure but API calls will fail.\n\n"
+end
+
+# Initialize client
+client = GasfreeSdk.client
+
+# Get supported tokens
+puts "Supported Tokens:"
+tokens = client.tokens
+tokens.each do |token|
+  puts "  #{token.symbol} (#{token.token_address})"
+  puts "    Activation Fee: #{token.activate_fee}"
+  puts "    Transfer Fee: #{token.transfer_fee}"
+end
+
+# Get service providers
+puts "\nService Providers:"
+providers = client.providers
+providers.each do |provider|
+  puts "  #{provider.name} (#{provider.address})"
+  puts "    Max Pending Transfers: #{provider.config.max_pending_transfer}"
+  puts "    Default Deadline: #{provider.config.default_deadline_duration}s"
+end
+
+# Create a new key pair for testing
+key = Eth::Key.new
+puts "\nTest Account:"
+puts "  Address: #{key.address}"
+
+# Get GasFree account info
+puts "\nGasFree Account Info:"
+begin
+  account = client.address(key.address)
+  puts "  GasFree Address: #{account.gas_free_address}"
+  puts "  Active: #{account.active}"
+  puts "  Nonce: #{account.nonce}"
+  puts "  Assets:"
+  account.assets.each do |asset|
+    puts "    #{asset.token_symbol}: #{asset.frozen} frozen"
+  end
+rescue GasfreeSdk::APIError => e
+  puts "  Error: #{e.message}"
+end
+
+# Example transfer request (this will fail as it's just a demo)
+token = tokens.first
+provider = providers.first
+
+puts "\nSubmitting Transfer Request:"
+begin
+  # Create message to sign
+  message = {
+    token: token.token_address,
+    service_provider: provider.address,
+    user: key.address,
+    receiver: "0x1234567890123456789012345678901234567890",
+    value: "1000000",
+    max_fee: token.transfer_fee,
+    deadline: Time.now.to_i + provider.config.default_deadline_duration,
+    version: 1,
+    nonce: 0
+  }
+
+  # Sign the message
+  sig = key.sign(Eth::Util.keccak256(message.to_json))
+
+  # Create and submit transfer request
+  request = GasfreeSdk::Models::TransferRequest.new(
+    message.merge(sig: sig)
+  )
+
+  response = client.submit_transfer(request)
+  puts "  Transfer ID: #{response.id}"
+  puts "  State: #{response.state}"
+  puts "  Estimated Fees:"
+  puts "    Activation: #{response.estimated_activate_fee}"
+  puts "    Transfer: #{response.estimated_transfer_fee}"
+
+  # Monitor transfer status
+  puts "\nMonitoring Transfer Status:"
+  5.times do
+    status = client.transfer_status(response.id)
+    puts "  State: #{status.state}"
+    puts "  Transaction Hash: #{status.txn_hash}" if status.txn_hash
+    break if %w[SUCCEED FAILED].include?(status.state)
+
+    sleep 2
+  end
+rescue GasfreeSdk::APIError => e
+  puts "  Error (#{e.code}): #{e.message}"
+end

data/examples/demo.rb

@@ -0,0 +1,140 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "gasfree_sdk"
+
+puts "GasFree SDK Demonstration"
+puts "========================="
+
+# Show SDK version
+puts "SDK Version: #{GasfreeSdk::VERSION}"
+
+# Configure the SDK
+GasfreeSdk.configure do |config|
+  config.api_key = "demo-api-key"
+  config.api_secret = "demo-api-secret"
+  config.api_endpoint = "https://demo.gasfree.io/"
+end
+
+puts "Configuration:"
+puts "  API Endpoint: #{GasfreeSdk.config.api_endpoint}"
+puts "  API Key: #{GasfreeSdk.config.api_key[0..3]}..."
+puts "  Chain ID: #{GasfreeSdk.config.default_chain_id}"
+puts ""
+
+# Show client creation
+client = GasfreeSdk.client
+puts "Client created: #{client.class}"
+puts ""
+
+# Demonstrate model creation
+puts "Model Examples:"
+puts "==============="
+
+# Token model
+token = GasfreeSdk::Models::Token.new(
+  token_address: "0x1234567890123456789012345678901234567890",
+  created_at: "2024-01-01T00:00:00Z",
+  updated_at: "2024-01-01T00:00:00Z",
+  activate_fee: "1000000",
+  transfer_fee: "500000",
+  supported: true,
+  symbol: "USDT",
+  decimal: 6
+)
+
+puts "Token:"
+puts "  Symbol: #{token.symbol}"
+puts "  Address: #{token.token_address}"
+puts "  Activation Fee: #{token.activate_fee}"
+puts "  Transfer Fee: #{token.transfer_fee}"
+puts ""
+
+# Provider model
+provider = GasfreeSdk::Models::Provider.new(
+  address: "0x1234567890123456789012345678901234567890",
+  name: "Demo Provider",
+  icon: "",
+  website: "https://demo.provider.com",
+  config: {
+    max_pending_transfer: 1,
+    min_deadline_duration: 60,
+    max_deadline_duration: 600,
+    default_deadline_duration: 180
+  }
+)
+
+puts "Provider:"
+puts "  Name: #{provider.name}"
+puts "  Address: #{provider.address}"
+puts "  Max Pending: #{provider.config.max_pending_transfer}"
+puts "  Default Deadline: #{provider.config.default_deadline_duration}s"
+puts ""
+
+# Transfer request model
+transfer_request = GasfreeSdk::Models::TransferRequest.new(
+  token: token.token_address,
+  service_provider: provider.address,
+  user: "0x1111111111111111111111111111111111111111",
+  receiver: "0x2222222222222222222222222222222222222222",
+  value: "1000000",
+  max_fee: "100000",
+  deadline: Time.now.to_i + 180,
+  version: 1,
+  nonce: 0,
+  sig: "0x#{"a" * 128}"
+)
+
+puts "Transfer Request:"
+puts "  Token: #{transfer_request.token}"
+puts "  Provider: #{transfer_request.service_provider}"
+puts "  User: #{transfer_request.user}"
+puts "  Receiver: #{transfer_request.receiver}"
+puts "  Value: #{transfer_request.value}"
+puts "  Max Fee: #{transfer_request.max_fee}"
+puts "  Deadline: #{Time.at(transfer_request.deadline)}"
+puts "  Version: #{transfer_request.version}"
+puts ""
+
+# Transfer response model
+transfer_response = GasfreeSdk::Models::TransferResponse.new(
+  id: "demo-transfer-id",
+  created_at: "2024-01-01T00:00:00Z",
+  updated_at: "2024-01-01T00:00:00Z",
+  account_address: transfer_request.user,
+  gas_free_address: "0x3333333333333333333333333333333333333333",
+  provider_address: provider.address,
+  target_address: transfer_request.receiver,
+  token_address: token.token_address,
+  amount: transfer_request.value,
+  max_fee: transfer_request.max_fee,
+  signature: transfer_request.sig,
+  nonce: transfer_request.nonce,
+  expired_at: "2024-01-01T00:03:00Z",
+  state: "WAITING"
+)
+
+puts "Transfer Response:"
+puts "  ID: #{transfer_response.id}"
+puts "  State: #{transfer_response.state}"
+puts "  Amount: #{transfer_response.amount}"
+puts "  Expires At: #{transfer_response.expired_at}"
+puts ""
+
+# Show error classes
+puts "Error Classes:"
+puts "=============="
+puts "  Base: #{GasfreeSdk::Error}"
+puts "  Authentication: #{GasfreeSdk::AuthenticationError}"
+puts "  API: #{GasfreeSdk::APIError}"
+puts "  Deadline Exceeded: #{GasfreeSdk::DeadlineExceededError}"
+puts "  Invalid Signature: #{GasfreeSdk::InvalidSignatureError}"
+puts ""
+
+puts "Demo completed successfully!"
+puts ""
+puts "For real usage:"
+puts "1. Set GASFREE_API_KEY and GASFREE_API_SECRET environment variables"
+puts "2. Use examples/basic_usage.rb for a complete workflow example"
+puts "3. See README.md for full documentation"

data/lib/gasfree_sdk/client.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+require "time"
+
+module GasfreeSdk
+  # Client for interacting with the GasFree API
+  class Client
+    # @return [Faraday::Connection] The HTTP client
+    attr_reader :connection
+
+    # Initialize a new GasFree client
+    def initialize
+      @connection = Faraday.new(url: GasfreeSdk.config.api_endpoint) do |f|
+        f.request :json
+        f.request :retry, GasfreeSdk.config.retry_options
+        f.response :json
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    # Get all supported tokens
+    # @return [Array<Token>] List of supported tokens
+    def tokens
+      response = get("/api/v1/config/token/all")
+      response.dig("data", "tokens").map { |token| Models::Token.new(token) }
+    end
+
+    # Get all service providers
+    # @return [Array<Provider>] List of service providers
+    def providers
+      response = get("/api/v1/config/provider/all")
+      response.dig("data", "providers").map { |provider| Models::Provider.new(provider) }
+    end
+
+    # Get GasFree account info
+    # @param account_address [String] The user's EOA address
+    # @return [GasFreeAddress] The GasFree account info
+    def address(account_address)
+      response = get("/api/v1/address/#{account_address}")
+      Models::GasFreeAddress.new(response["data"])
+    end
+
+    # Submit a GasFree transfer
+    # @param request [TransferRequest] The transfer request
+    # @return [TransferResponse] The transfer response
+    def submit_transfer(request)
+      response = post("/api/v1/gasfree/submit", request.to_h)
+      Models::TransferResponse.new(response["data"])
+    end
+
+    # Get transfer status
+    # @param trace_id [String] The transfer trace ID
+    # @return [TransferResponse] The transfer status
+    def transfer_status(trace_id)
+      response = get("/api/v1/gasfree/#{trace_id}")
+      Models::TransferResponse.new(response["data"])
+    end
+
+    private
+
+    # Make a GET request
+    # @param path [String] The API path
+    # @param params [Hash] Query parameters
+    # @return [Hash] The response data
+    def get(path, params = {})
+      timestamp = Time.now.to_i
+      response = connection.get(path, params) do |req|
+        sign_request(req, "GET", path, timestamp)
+      end
+      handle_response(response)
+    end
+
+    # Make a POST request
+    # @param path [String] The API path
+    # @param body [Hash] Request body
+    # @return [Hash] The response data
+    def post(path, body)
+      timestamp = Time.now.to_i
+      response = connection.post(path) do |req|
+        req.body = body
+        sign_request(req, "POST", path, timestamp)
+      end
+      handle_response(response)
+    end
+
+    # Sign an API request
+    # @param request [Faraday::Request] The request to sign
+    # @param method [String] HTTP method
+    # @param path [String] Request path
+    # @param timestamp [Integer] Request timestamp
+    def sign_request(request, method, path, timestamp)
+      api_key = GasfreeSdk.config.api_key
+      api_secret = GasfreeSdk.config.api_secret
+
+      raise AuthenticationError, "API key and secret are required" if api_key.nil? || api_secret.nil?
+
+      message = "#{method}#{path}#{timestamp}"
+      signature = Base64.strict_encode64(
+        OpenSSL::HMAC.digest("SHA256", api_secret, message)
+      )
+
+      request.headers["Timestamp"] = timestamp.to_s
+      request.headers["Authorization"] = "ApiKey #{api_key}:#{signature}"
+    end
+
+    # Handle API response
+    # @param response [Faraday::Response] The API response
+    # @return [Hash] The response data
+    # @raise [APIError] If the response indicates an error
+    def handle_response(response)
+      data = response.body
+
+      return data if data["code"] == 200
+
+      raise GasfreeSdk.build_error(
+        code: data["code"],
+        reason: data["reason"],
+        message: data["message"]
+      )
+    end
+  end
+end