polarloop 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 337da4304503c173f43227da0bbe06c0a0e8b6f2638ad906cd909fd78db86d3b
+  data.tar.gz: 6c28562afb905de9c8fe5fe47b75856ef4c4fb4b0b677e8981e8739f9d4f3763
+SHA512:
+  metadata.gz: c38b666ad7a4258379b5cb770e887b904b46718516934c6c98f18d36bce410a7422654f1c4faf0558355e1eac8198225f6aed7cede03859346a227a835f6ff44
+  data.tar.gz: d104fef27a6e96af8c80b1c9959f82299abd0e5b81453bc4feec263d484c3889de14ed94a8a57eca5ce3c3e89c39be69fb7257670bbbc94a42ddaf05f7f242f6

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 2026-06-30 00:00 — Release 1.0.0 on RubyGems.org
+
+- Bump version to 1.0.0 (first public release)
+- Add MIT LICENSE file (copyright Pontifi)
+- gemspec: set author to Pontifi, homepage to RubyGems gem page, MIT metadata (allowed_push_host, homepage_uri); include CHANGELOG.md in packaged files
+- README: replace internal GitLab install instructions with `gem install polarloop`
+
+## 2026-03-15 07:00 — Initial gem implementation
+
+- Project skeleton: gemspec, Gemfile, Rakefile, .rspec, .gitignore
+- Type structs: Mandate, BatchResult, ChargeReadyResult, TxResult, Event types
+- ABI loading from Hardhat artifact with event topic hashes and error decoding
+- Configuration with multi-chain registration (ChainConfig)
+- BIP-44 wallet derivation from mnemonic (single key per config)
+- Gas strategy: auto-detect EIP-1559 vs Legacy per chain via eth_feeHistory
+- ContractCaller: low-level eth.rb wrapper with eth_call dry-run + eth_estimateGas
+- EventParser: eth_getLogs with MandateCreated/Charged/Revoked decoding
+- Client: full public API — charge, batch_charge, revoke, sign_create_mandate, events, views
+- Manager: multi-chain client registry with cached Client instances
+- Net::HTTP patch for eth.rb (HTTPX hangs on some RPC endpoints)
+- Contract revert decoding: standard Error(string), Panic(uint256), and custom ABI errors
+- Unit tests: 21 specs covering wallet, client, and event parser (WebMock)
+- Verified on BSC Testnet: charge, view calls, event parsing all working

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pontifi
+
+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,223 @@
+# PolarLoop-rb
+
+Ruby gem для взаимодействия со смарт-контрактом PolarLoop на EVM-чейнах. Управление мандатами, списание, парсинг событий и генерация подписи оператора для бэкенда AWB.
+
+## Оглавление
+
+- [Установка](#установка)
+- [Конфигурация](#конфигурация)
+- [Использование](#использование)
+  - [View-методы (без газа)](#view-методы-без-газа)
+  - [Write-методы (отправка транзакций)](#write-методы-отправка-транзакций)
+  - [Подпись оператора (off-chain, без газа)](#подпись-оператора-off-chain-без-газа)
+  - [События](#события)
+  - [Адрес кошелька](#адрес-кошелька)
+- [Обработка ошибок](#обработка-ошибок)
+- [Мульти-чейн](#мульти-чейн)
+- [Разработка](#разработка)
+- [Лицензия](#лицензия)
+
+## Установка
+
+```bash
+gem install polarloop
+```
+
+Или добавить в Gemfile:
+
+```ruby
+gem "polarloop"
+```
+
+## Конфигурация
+
+```ruby
+PolarLoop.configure do |c|
+  c.mnemonic = "your twelve word mnemonic phrase here ..."
+  c.index = 0  # BIP-44 индекс деривации (m/44'/60'/0'/0/N)
+
+  c.register(:bsc,
+    rpc_url: "https://bsc-dataseed.binance.org",
+    contract_address: "0x...",
+    chain_id: 56,
+    gas_multiplier: 1.2  # опционально, по умолчанию 1.2
+  )
+
+  c.register(:polygon,
+    rpc_url: "https://polygon-rpc.com",
+    contract_address: "0x...",
+    chain_id: 137
+  )
+end
+```
+
+## Использование
+
+```ruby
+client = PolarLoop.client(:bsc)
+```
+
+### View-методы (без газа)
+
+```ruby
+# Получить мандат по ID
+mandate = client.get_mandate("0xabc...")
+mandate.payer        # => "0x..."
+mandate.amount       # => 1000000
+mandate.interval     # => 86400
+mandate.active       # => true
+mandate.reference_id # => "0x..."
+
+# Получить мандат по вашему reference ID
+mandate_id, mandate = client.get_mandate_by_reference_id("0xref...")
+
+# Проверить готовность к списанию
+result = client.charge_ready?("0xabc...")
+result.ready   # => true
+result.reason  # => ""
+
+# Пакетная проверка
+results = client.batch_charge_ready?(["0xabc...", "0xdef..."])
+
+# Все мандаты плательщика
+ids = client.get_payer_mandates("0xpayer...")
+
+# Состояние контракта
+client.min_interval  # => 86400
+client.paused?       # => false
+```
+
+### Write-методы (отправка транзакций)
+
+```ruby
+# Списание по мандату
+result = client.charge("0xabc...")
+result.tx_hash      # => "0x..."
+result.block_number # => 12345678
+result.gas_used     # => 71356
+result.status       # => true
+
+# Пакетное списание
+result = client.batch_charge(["0xabc...", "0xdef..."])
+result.batch_results[0].mandate_id # => "0xabc..."
+result.batch_results[0].success    # => true
+result.batch_results[1].mandate_id # => "0xdef..."
+result.batch_results[1].success    # => false
+result.batch_results[1].reason     # => "Interval not elapsed"
+
+# Отзыв мандата
+result = client.revoke_mandate("0xabc...")
+result = client.batch_revoke_mandate(["0xabc...", "0xdef..."])
+
+# Админские методы
+client.pause
+client.unpause
+client.grant_operator_role("0xaddress...")
+client.revoke_operator_role("0xaddress...")
+client.rescue_eth
+client.rescue_erc20("0xtoken...", amount)
+```
+
+### Подпись оператора (off-chain, без газа)
+
+Генерация ECDSA-подписи для `createMandate` на фронтенде:
+
+```ruby
+signature = client.sign_create_mandate(
+  payer: "0xpayer...",
+  merchant: "0xmerchant...",
+  token: "0xtoken...",
+  amount: 1_000_000,
+  interval: 86_400,
+  max_total_amount: 10_000_000,
+  reference_id: "0xref..."
+)
+# => "abcdef1234..." (hex-подпись для dApp)
+```
+
+### События
+
+```ruby
+# MandateCreated — создание мандата
+events = client.mandate_created_events(from_block: 1000, to_block: "latest")
+events.each do |e|
+  e.mandate_id   # => "0x..."
+  e.payer        # => "0x..."
+  e.merchant     # => "0x..."
+  e.token        # => "0x..."
+  e.amount       # => 1000000
+  e.interval     # => 86400
+  e.max_total_amount # => 10000000
+  e.reference_id # => "0x..."
+  e.block_number # => 12345
+  e.tx_hash      # => "0x..."
+end
+
+# MandateCharged — списание по мандату
+events = client.mandate_charged_events(from_block: 1000)
+events.each do |e|
+  e.mandate_id   # => "0x..."
+  e.payer        # => "0x..."
+  e.merchant     # => "0x..."
+  e.amount       # => 1000000
+  e.timestamp    # => 1773521124
+  e.block_number # => 12345
+  e.tx_hash      # => "0x..."
+end
+
+# MandateRevoked — отзыв мандата
+events = client.mandate_revoked_events(from_block: 1000)
+events.each do |e|
+  e.mandate_id   # => "0x..."
+  e.payer        # => "0x..."
+  e.block_number # => 12345
+  e.tx_hash      # => "0x..."
+end
+
+# События конкретной транзакции
+events = client.events_for_tx("0xtxhash...")
+```
+
+### Адрес кошелька
+
+```ruby
+PolarLoop.address  # => "0x..." (из мнемоники + индекса)
+```
+
+## Обработка ошибок
+
+```ruby
+begin
+  client.charge("0xabc...")
+rescue PolarLoop::ContractRevertError => e
+  # Контракт отклонил вызов — декодированная ошибка из ABI
+  # например: "AccessControlUnauthorizedAccount(0x..., 0x...)"
+  # например: "Interval not elapsed"
+  puts e.message
+rescue PolarLoop::RpcError => e
+  # Ошибка соединения или протокола RPC
+  puts e.message
+end
+```
+
+## Мульти-чейн
+
+Регистрируйте несколько чейнов и получайте отдельные клиенты:
+
+```ruby
+bsc_client = PolarLoop.client(:bsc)
+polygon_client = PolarLoop.client(:polygon)
+```
+
+Один и тот же адрес кошелька на всех EVM-чейнах (BIP-44 деривация).
+
+## Разработка
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## Лицензия
+
+MIT