{"id":28435302,"url":"https://github.com/madmatvey/gasfree_sdk","last_synced_at":"2025-08-31T12:14:44.747Z","repository":{"id":295627537,"uuid":"990737288","full_name":"madmatvey/gasfree_sdk","owner":"madmatvey","description":"Ruby SDK for interacting with the GasFree.io API, enabling gasless transfers of TRC-20/ERC-20 tokens.","archived":false,"fork":false,"pushed_at":"2025-07-26T11:28:57.000Z","size":178,"stargazers_count":2,"open_issues_count":21,"forks_count":12,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-28T16:46:04.050Z","etag":null,"topics":["erc20","gasless-sdk","gasless-transactions","gasless-tx","ruby","trc20"],"latest_commit_sha":null,"homepage":"https://gasfree.io/docs/GasFree_specification.html","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/madmatvey.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-26T14:55:26.000Z","updated_at":"2025-07-26T11:29:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"53dbec5b-b848-441f-8311-45cc5b46d9e2","html_url":"https://github.com/madmatvey/gasfree_sdk","commit_stats":null,"previous_names":["madmatvey/gasfree_sdk"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/madmatvey/gasfree_sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madmatvey%2Fgasfree_sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madmatvey%2Fgasfree_sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madmatvey%2Fgasfree_sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madmatvey%2Fgasfree_sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/madmatvey","download_url":"https://codeload.github.com/madmatvey/gasfree_sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madmatvey%2Fgasfree_sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272977971,"owners_count":25025235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["erc20","gasless-sdk","gasless-transactions","gasless-tx","ruby","trc20"],"created_at":"2025-06-05T20:07:56.258Z","updated_at":"2025-08-31T12:14:44.738Z","avatar_url":"https://github.com/madmatvey.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GasFree SDK\n\nRuby SDK for GasFree.io - TRC-20 gasless transfer solution.\n\n## 💬 Support \u0026 Consulting\n\nIf you encounter any issues, feel free to open a discussion or report a bug via the [GitHub Issues](https://github.com/madmatvey/gasfree_sdk/issues) page.\n\nYou can also [hire me as an external consultant](https://madmatvey.github.io/about/#cv) if you need help integrating or customizing the gem for your project.\n\nIf you find this gem useful and want to support further development, you're welcome to [donate here](https://madmatvey.github.io/about/#donate-me).\n\n## Installation\n\nThis gem is published on [RubyGems.org](https://rubygems.org/gems/gasfree_sdk).\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'gasfree_sdk'\n```\n\nAnd then execute:\n\n    $ bundle install\n\nOr install it yourself as:\n\n    $ gem install gasfree_sdk\n\n## Configuration\n\n```ruby\nrequire 'gasfree_sdk'\n\nGasfreeSdk.configure do |config|\n  config.api_key = \"your-api-key\"\n  config.api_secret = \"your-api-secret\"\n  config.api_endpoint = \"https://open.gasfree.io/tron/\"  # TRON endpoint\nend\n\n# Note: The api_endpoint must be a valid http or https URL. If an invalid value is provided,\n# a GasfreeSdk::Error will be raised during configuration.\n```\n\n## Basic Usage\n\n### Initialize Client\n\n```ruby\nclient = GasfreeSdk.client\n```\n\n### Get Supported Tokens\n\n```ruby\ntokens = client.tokens\ntokens.each do |token|\n  puts \"#{token.symbol} (#{token.token_address})\"\n  puts \"  Activation Fee: #{token.activate_fee}\"\n  puts \"  Transfer Fee: #{token.transfer_fee}\"\nend\n```\n\n### Get Service Providers\n\n```ruby\nproviders = client.providers\nproviders.each do |provider|\n  puts \"#{provider.name} (#{provider.address})\"\n  puts \"  Max Pending Transfers: #{provider.config.max_pending_transfer}\"\n  puts \"  Default Deadline: #{provider.config.default_deadline_duration}s\"\nend\n```\n\n### Check Account Information\n\n```ruby\naccount = client.address(\"TYourTronAddress\")\nputs \"GasFree Address: #{account.gas_free_address}\"\nputs \"Active: #{account.active}\"\nputs \"Nonce: #{account.nonce}\"\n\naccount.assets.each do |asset|\n  puts \"#{asset.token_symbol}: #{asset.frozen} frozen\"\nend\n```\n\n## TRON EIP-712 Signature Module\n\nThe SDK includes a comprehensive EIP-712 signature implementation specifically designed for TRON GasFree transfers. This module handles the complex cryptographic operations required for signing structured data according to the EIP-712 standard as implemented by TRON (TIP-712).\n\n### Features\n\n- **Complete EIP-712 Implementation**: Full support for EIP-712 structured data signing\n- **TRON-Specific Adaptations**: Handles TRON address encoding and TIP-712 specifications\n- **Dual Network Support**: Separate configurations for TRON Mainnet and Testnet (Nile)\n- **Flexible Key Handling**: Support for multiple data key formats (camelCase, snake_case)\n- **Built-in Cryptography**: Includes Keccak256 hashing and Base58 encoding for TRON addresses\n\n### Basic Signature Usage\n\n```ruby\n# Example message data\nmessage_data = {\n  token: \"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t\", # USDT TRC-20\n  serviceProvider: \"TGzz8gjYiYRqpfmDwnLxfgPuLVNmpCswVp\",\n  user: \"TYRhsi1fkke2tjdVW9XGYLjf8TgbbutEgY\",\n  receiver: \"TW1dWXfta5ygVN298JBN2UPhaSAUzo2owZ\",\n  value: \"3000000\", # 3 USDT (6 decimals)\n  maxFee: \"2000000\", # 2 USDT max fee\n  deadline: (Time.now.to_i + 300).to_s, # 5 minutes from now\n  version: 1,\n  nonce: 0\n}\n\nprivate_key = \"your_private_key_hex\"\n\n# Sign for TRON Testnet (Nile)\ntestnet_signature = GasfreeSdk::TronEIP712Signer.sign_typed_data_testnet(private_key, message_data)\n\n# Sign for TRON Mainnet\nmainnet_signature = GasfreeSdk::TronEIP712Signer.sign_typed_data_mainnet(private_key, message_data)\n\n# Generic signing with custom domain\nsignature = GasfreeSdk::TronEIP712Signer.sign_typed_data(\n  private_key,\n  message_data,\n  domain: GasfreeSdk::TronEIP712Signer::DOMAIN_TESTNET\n)\n```\n\n### Advanced Usage\n\n#### Custom Domain Configuration\n\n```ruby\ncustom_domain = {\n  name: \"GasFreeController\",\n  version: \"V1.0.0\",\n  chainId: 728_126_428,\n  verifyingContract: \"THQGuFzL87ZqhxkgqYEryRAd7gqFqL5rdc\"\n}\n\nsignature = GasfreeSdk::TronEIP712Signer.sign_typed_data(\n  private_key,\n  message_data,\n  domain: custom_domain,\n  use_ethereum_v: true\n)\n```\n\n#### Individual Cryptographic Operations\n\n```ruby\n# Keccak256 hashing\nhash = GasfreeSdk::TronEIP712Signer.keccac256(\"data to hash\")\nhex_hash = GasfreeSdk::TronEIP712Signer.keccac256_hex(\"data to hash\")\n\n# EIP-712 type encoding\nencoded_type = GasfreeSdk::TronEIP712Signer.encode_type(:PermitTransfer)\n\n# Structured data hashing\nmessage_hash = GasfreeSdk::TronEIP712Signer.hash_struct(:PermitTransfer, message_data)\ndomain_hash = GasfreeSdk::TronEIP712Signer.hash_domain\n```\n\n#### TRON Address Utilities\n\n```ruby\n# Base58 encoding/decoding for TRON addresses\nbinary_data = GasfreeSdk::Base58.base58_to_binary(\"TYRhsi1fkke2tjdVW9XGYLjf8TgbbutEgY\")\nbase58_string = GasfreeSdk::Base58.binary_to_base58(binary_data)\n```\n\n### Domain Constants\n\nThe module provides pre-configured domain constants for both networks:\n\n```ruby\n# TRON Testnet (Nile)\nGasfreeSdk::TronEIP712Signer::DOMAIN_TESTNET\n# =\u003e {\n#   name: \"GasFreeController\",\n#   version: \"V1.0.0\",\n#   chainId: 728_126_428,\n#   verifyingContract: \"THQGuFzL87ZqhxkgqYEryRAd7gqFqL5rdc\"\n# }\n\n# TRON Mainnet\nGasfreeSdk::TronEIP712Signer::DOMAIN_MAINNET\n# =\u003e {\n#   name: \"GasFreeController\",\n#   version: \"V1.0.0\",\n#   chainId: 3_448_148_188,\n#   verifyingContract: \"TFFAMQLZybALaLb4uxHA9RBE7pxhUAjF3U\"\n# }\n```\n\n### Submit Transfer with Signature\n\n```ruby\n# Create and submit a transfer request\ntoken = client.tokens.first\nprovider = client.providers.first\n\nmessage_data = {\n  token: token.token_address,\n  serviceProvider: provider.address,\n  user: \"TYourTronAddress\",\n  receiver: \"TReceiverAddress\",\n  value: \"1000000\", # 1 USDT\n  maxFee: \"500000\",  # 0.5 USDT max fee\n  deadline: (Time.now.to_i + provider.config.default_deadline_duration).to_s,\n  version: 1,\n  nonce: account.nonce\n}\n\n# Sign the message\nsignature = GasfreeSdk::TronEIP712Signer.sign_typed_data_testnet(private_key, message_data)\n\n# Create transfer request\nrequest = GasfreeSdk::Models::TransferRequest.new(\n  token: message_data[:token],\n  service_provider: message_data[:serviceProvider],\n  user: message_data[:user],\n  receiver: message_data[:receiver],\n  value: message_data[:value],\n  max_fee: message_data[:maxFee],\n  deadline: message_data[:deadline].to_i,\n  version: message_data[:version],\n  nonce: message_data[:nonce],\n  sig: signature\n)\n\n# Submit the transfer\nresponse = client.submit_transfer(request)\nputs \"Transfer ID: #{response.id}\"\nputs \"State: #{response.state}\"\n```\n\n### Monitor Transfer Status\n\n```ruby\ntransfer_id = response.id\n\nloop do\n  status = client.transfer_status(transfer_id)\n  puts \"State: #{status.state}\"\n  puts \"Transaction Hash: #{status.txn_hash}\" if status.txn_hash\n\n  break if %w[SUCCEED FAILED].include?(status.state)\n  sleep 2\nend\n```\n\n## Debugging and Logging\n\nThe SDK uses a custom Faraday middleware (`SanitizedLogsMiddleware`) to ensure that **all HTTP request and response logs are automatically sanitized**. Sensitive data is never written to logs, even in debug mode.\n\n### Enable Debug Logging\n\n```bash\nexport DEBUG_GASFREE_SDK=1\n```\n\nWhen this environment variable is set, the SDK will log HTTP requests and responses using only sanitized data. This is handled automatically; you do not need to configure anything extra.\n\n### How It Works\n\n- The SDK integrates `SanitizedLogsMiddleware` into the Faraday stack.\n- This middleware intercepts all HTTP traffic and logs method, URL, headers, and body **with sensitive fields masked** (e.g., `***REDACTED***`).\n- The original data is never mutated, and only masked data is ever written to logs.\n- No other HTTP logging middleware is used, so there is no risk of leaking secrets.\n\n### Example Integration (automatic)\n\n```ruby\nclient = GasfreeSdk.client\n# If DEBUG_GASFREE_SDK=1, all HTTP logs will be sanitized automatically.\n```\n\n### Automatic Data Protection\n\nWhen debug logging is enabled, sensitive fields (private keys, tokens, signatures, etc.) are automatically masked with `***REDACTED***` in all HTTP request/response logs.\n\n**Protected fields include:**\n- Headers: `Authorization`, `Api-Key`, `X-Api-Key`, etc.\n- Body fields: `private_key`, `api_secret`, `signature`, `token`, etc.\n\n### Example\n\n```ruby\n# With DEBUG_GASFREE_SDK=1\nclient = GasfreeSdk.client\ntokens = client.tokens\n# Console output (sensitive data automatically masked):\n# GET https://open.gasfree.io/tron/api/v1/config/token/all\n# Request Headers: {\"Authorization\"=\u003e\"***REDACTED***\", \"Timestamp\"=\u003e\"1703123456\"}\n```\n\n## Error Handling\n\n```ruby\nbegin\n  response = client.submit_transfer(request)\nrescue GasfreeSdk::APIError =\u003e e\n  puts \"API Error (#{e.code}): #{e.message}\"\n\n  case e.message\n  when /insufficient balance/\n    puts \"Solution: Get test tokens or transfer tokens to GasFree address\"\n  when /max fee exceeded/\n    puts \"Solution: Increase maxFee parameter\"\n  when /Invalid signature/\n    puts \"Solution: Check private key and address correspondence\"\n  end\nrescue StandardError =\u003e e\n  puts \"Error: #{e.message}\"\nend\n```\n\n## Examples\n\nSee the `examples/` directory for complete working examples:\n\n- `examples/simple_usage_example.rb` - Basic TronEIP712Signer usage\n\n## Dependencies\n\n- `dry-configurable` - Configuration management\n- `dry-struct` - Data structures\n- `dry-types` - Type system\n- `dry-validation` - Data validation\n- `faraday` - HTTP client\n- `faraday-retry` - HTTP retry logic\n- `eth` - Ethereum utilities\n- `rbsecp256k1` - Cryptographic operations for EIP-712 signatures\n\n## Development\n\nAfter 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.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/madmatvey/gasfree_sdk.\n\n## License\n\nThe gem is available as open source under the terms of the [LGPL v3.0](https://www.gnu.org/licenses/lgpl-3.0.html) © 2025 Eugene Leontev (https://github.com/madmatvey)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadmatvey%2Fgasfree_sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadmatvey%2Fgasfree_sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadmatvey%2Fgasfree_sdk/lists"}