filecoin 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef27efff91c40a5b52704f6a8aa63f2ede88e1d88e495444e8660e7746483538
-  data.tar.gz: 2ee28c49341b368e2cbab1dc872f72fb156da4217335a6a8e680ed0797a25992
+  metadata.gz: 51d924d8ec129371f94374405e003a802de0b7952fdeb9ae8eec0df93ed4f2f1
+  data.tar.gz: d3f27b9ee0a0a5b252d6523740be7d3fb2302a89ea528503e9081f7cbcb7d328
 SHA512:
-  metadata.gz: e603609b41f74c9cfa5fd06072ef859036f3d6fb8644283dd4b824098c05db1dc0cfec23e6b140f661629ee84ee04fc4203449e00757172cc48d8725eee4ca10
-  data.tar.gz: d50ba2023ebb16ebc76c03cc064eca582fb1cd40318d594d5d0e567bb535940f0a2a893dc80c3390274b1930f1b04766c324e0a5ffc583c7670147a38989a39d
+  metadata.gz: a6021bf20aa984240b5839418aa29913007e40889f9dbbae25ec9a1a84a74577ba771fe6b9ad548f9312b7088cf957f3f6ec5d8643168a364e876ef64e6ecad3
+  data.tar.gz: d893ffd092e50be52cd458eb0e277897df5305ce670d0134da287a62cf658afd39e8f6dec200e66920dde56b86e53ec29117ce223b916d26488f8b35957610ad

data/.github/workflows/ruby.yml

@@ -0,0 +1,39 @@
+name: Ruby
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.7
+      - name: Install dependencies
+        run: bundle install
+      - name: Run tests
+        run: bundle exec rake lint
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu, macos]
+        ruby: [2.5, 2.6, 2.7, head, debug, jruby, jruby-head, truffleruby, truffleruby-head]
+    runs-on: ${{ matrix.os }}-latest
+    continue-on-error: ${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug' }}
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+    - name: Install dependencies
+      run: bundle install
+    - name: Run tests
+      env:
+        FILECOIN_URL: ${{ secrets.FILECOIN_URL }}
+      run: bundle exec rake spec

data/CHANGELOG.md

@@ -10,7 +10,13 @@ The format is based on [Keep a Changelog], and this project adheres to
 Unreleased
 ----------
 
-_Coming soon_
+- Add optional argument to extract the deal CID automatically from the response
+  when submitting a proposal;
+- Make wallet for deal proposals optional, falling back on the configured
+  default wallet;
+- Add configuration object to set default wallet for deal proposals;
+- Fix defaults overriding provided nil values in `Filecoin::Client`;
+- Add abstraction for deals and their state with client lifecycle helpers.
 
 
 v0.2.0 - 2020-06-12

data/Gemfile

@@ -12,4 +12,6 @@ group :test do
   gem "rubocop", "~> 0.84.0"
   gem "rubocop-performance", "~> 1.6.0"
   gem "rubocop-rspec", "~> 1.39.0"
+  gem "vcr", "~> 6.0"
+  gem "webmock", "~> 3.0"
 end

data/Gemfile.lock

@@ -1,22 +1,57 @@
 PATH
   remote: .
   specs:
-    filecoin (0.2.0)
+    filecoin (0.3.0)
+      dry-struct (~> 1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
     ast (2.4.0)
     concurrent-ruby (1.1.6)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
     diff-lcs (1.3)
+    dry-configurable (0.11.6)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 0.4, >= 0.4.7)
+      dry-equalizer (~> 0.2)
+    dry-container (0.7.2)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 0.1, >= 0.1.3)
+    dry-core (0.4.9)
+      concurrent-ruby (~> 1.0)
+    dry-equalizer (0.3.0)
+    dry-inflector (0.2.0)
+    dry-logic (1.0.6)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 0.2)
+      dry-equalizer (~> 0.2)
+    dry-struct (1.3.0)
+      dry-core (~> 0.4, >= 0.4.4)
+      dry-equalizer (~> 0.3)
+      dry-types (~> 1.3)
+      ice_nine (~> 0.11)
+    dry-types (1.4.0)
+      concurrent-ruby (~> 1.0)
+      dry-container (~> 0.3)
+      dry-core (~> 0.4, >= 0.4.4)
+      dry-equalizer (~> 0.3)
+      dry-inflector (~> 0.1, >= 0.1.2)
+      dry-logic (~> 1.0, >= 1.0.2)
     faker (2.12.0)
       i18n (>= 1.6, < 2)
+    hashdiff (1.0.1)
     i18n (1.8.2)
       concurrent-ruby (~> 1.0)
+    ice_nine (0.11.2)
     parallel (1.19.1)
     parser (2.7.1.3)
       ast (~> 2.4.0)
     permafrost (1.0.0)
+    public_suffix (4.0.5)
     rainbow (3.0.0)
     rake (12.3.3)
     rexml (3.2.4)
@@ -48,7 +83,13 @@ GEM
     rubocop-rspec (1.39.0)
       rubocop (>= 0.68.1)
     ruby-progressbar (1.10.1)
+    safe_yaml (1.0.5)
     unicode-display_width (1.7.0)
+    vcr (6.0.0)
+    webmock (3.8.3)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
   ruby
@@ -62,6 +103,8 @@ DEPENDENCIES
   rubocop (~> 0.84.0)
   rubocop-performance (~> 1.6.0)
   rubocop-rspec (~> 1.39.0)
+  vcr (~> 6.0)
+  webmock (~> 3.0)
 
 BUNDLED WITH
    2.1.4

data/README.md

@@ -1,6 +1,8 @@
 filecoin-ruby
 =============
 
+![Ruby](https://github.com/subvisual/filecoin-ruby/workflows/Ruby/badge.svg)
+
 Interface to the Filecoin network APIs in Ruby.
 
 
@@ -198,33 +200,106 @@ The state of a deal has a numerical value which links it to a constant in the
 Filecoin Lotus client. At the time of writing, these states are
 ([source][states]):
 
-1. Unknown;
-2. Proposal not found;
-3. Proposal rejected;
-4. Proposal accepted;
-5. Deal staged;
-6. Deal sealing;
-7. Deal is active;
-8. Deal is failing;
-9. Deal not found;
-10. Deal funds ensured — deposited funds as necessary to create a deal,
-    ready to move forward;
-11. Waiting for data request — client is waiting for a request for the
-    deal data;
-12. Deal validating — verifying that deal parameters are good;
-13. Waiting for deal acceptance — deciding whether or not to accept the
-    deal;
-14. Deal transferring — transferring data to the miner;
-15. Waiting for data — for manual transfers;
-16. Verifying transferred data — generate CAR / piece data;
-17. Ensuring provider funds — checking collateral is sufficient;
-18. Ensuring client funds — checking client funds are sufficient;
-19. Waiting for funds to appear in provider balance;
-20. Waiting for funds to appear in client balance;
-21. Publishing deal to chain;
-22. Waiting for deal to appear on chain;
-23. Deal failed with an unexpected error;
-24. Deal completed — the deal has reached the end of its duration.
+| Value | State                    | Description |
+| :---: | :---                     | :--- |
+| 0     | Unknown                  | Status of the deal is undefined. |
+| 1     | Not found                | Deal can not be located. |
+| 2     | Proposal rejected        | Storage miner chose not to accept this deal proposal. |
+| 3     | Proposal accepted        | Storage miner chose to accept this deal proposal. |
+| 4     | Staged                   | Deal has been published and data is ready to be put into a sector. |
+| 5     | Sealing                  | Deal is in sector that's being sealed. |
+| 6     | Active                   | Deal is in a sealed sector and the miner is providing proofs for this deal. |
+| 7     | Expired                  | Deal has passed its final epoch and is expired. |
+| 8     | Slashed                  | Deal was in a sector that got slashed from failing to produce proofs. |
+| 9     | Failing                  | Something has gone wrong in the deal. Data is being cleaned. |
+| 10    | Funds ensured            | The funds necessary to create the deal have been deposited. |
+| 11    | Waiting for data request | Client is waiting for provider to request the deal data. |
+| 12    | Validating               | Storage provider is validating whether the deal parameters are good for a proposal. |
+| 13    | Waiting for acceptance   | Storage provider is running some custom decision logic to decide whether to accept the deal. |
+| 14    | Transferring             | Data is being sent from the client to the storage provider. |
+| 15    | Waiting for data         | Deal is for a manual data transfer, or the storage provider has not yet received a request to transfer data from the client. |
+| 16    | Verifying data           | Data has been transferred and the storage provider is verifying it against the provided piece CID. |
+| 17    | Ensure provider funds    | Storage provider is making sure it has adequate funds for the deal. |
+| 18    | Ensure client funds      | Client is making sure it has adequate funds for the deal. |
+| 19    | Provider is funding      | Storage provider has deposited funds and is waiting for funds to show up in balance. |
+| 20    | Client is funding        | Client has deposited funds and is waiting for funds to show up in balance. |
+| 21    | Publish                  | Deal is ready to be published on chain. |
+| 22    | Publishing               | Deal has been published, currently waiting for it to appear on chain. |
+| 23    | Error                    | Deal has failed due to an error, no further updates will occur. |
+| 24    | Completed                | Deal is active and information for retrieval is recorded. |
+
+The lifecycle of a deal is slightly different from the point-of-view of the
+client (the node proposing a deal) and the miner. Please refer to [the
+storage market technical documentation] for up-to-date diagrams.
+
+This gem provides an abstraction in `Filecoin::Deals::State` of the **client
+deal lifecycle** reducing them to 4 general states for general deal
+health-checks and tracking.
+
+<table>
+  <thead>
+    <tr>
+      <th>Abstract State</th>
+      <th>Description</th>
+      <th>Positive States</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Pending</td>
+      <td>Deal has been proposed and is pending acceptance or rejection.</td>
+      <td>
+        <ul>
+          <li>Ensure client funds</li>
+          <li>Client is funding</li>
+          <li>Funds ensured</li>
+          <li>Waiting for data</li>
+          <li>Transferring</li>
+          <li>Validating</li>
+        </ul>
+      </td>
+    </tr>
+    <tr>
+      <td>Good</td>
+      <td>Deal has been accepted and is active or on its way to become active.</td>
+      <td>
+        <ul>
+          <li>Proposal accepted</li>
+          <li>Sealing</li>
+          <li>Active</li>
+        </ul>
+      </td>
+    </tr>
+    <tr>
+      <td>Bad</td>
+      <td>Something has gone wrong with the deal and it is now invalid.</td>
+      <td>
+        <ul>
+          <li>Failing</li>
+          <li>Error</li>
+        </ul>
+      </td>
+    </tr>
+    <tr>
+      <td>Finished</td>
+      <td>The deal has followed its natural course and is no longer active.</td>
+      <td>
+        <ul>
+          <li>Slashed</li>
+          <li>Expired</li>
+        </ul>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+To make use of this abstraction, initialize `Filecoin::Deal` with the result
+of `Filecoin.ClientGetDealInfo`.
+
+```ruby
+response = Filecoin.client_get_deal_info("bafyreigc4b4fqsval4pjmfncaqdezhe5y3anwavjyzpj4mar73e6n7mvj4")
+deal = Filecoin::Deal.new(response["result"])
+```
 
 
 ### Filecoin.ClientQueryAsk
@@ -266,6 +341,7 @@ start_deal_params = Filecoin::Types::StartDealParams.new(
   # Description of the data the deal refers to
   data: data_ref,
   # Address of the wallet in the node to use to pay for the deal
+  # (optional if `Filecoin.config.default_wallet` is set)
   wallet: "t13nqjc55m3h327646cwcu4lchdx4lkw7ccxnx4ca",
   # Address ot the miner to whom this deal is to be proposed
   miner: "t1234567",
@@ -277,7 +353,7 @@ start_deal_params = Filecoin::Types::StartDealParams.new(
   deal_start_epoch: 1591979600,
 )
 
-Filecoin.client_start_deal(start_deal_params)
+Filecoin.client_start_deal(start_deal_params, extract_response: false)
 ```
 
 ```json
@@ -290,6 +366,10 @@ Filecoin.client_start_deal(start_deal_params)
 }
 ```
 
+This method accepts an optional keyword argument `extract_response`. If truthy,
+the method returns the deal CID directly, or `nil`, instead of the JSON RPC
+full response. Defaults to `false`.
+
 
 ### Filecoin.NetPeers
 
@@ -364,7 +444,8 @@ filecoin-ruby was created and is maintained with :heart: by
 
 [Filecoin Node API]: https://github.com/filecoin-project/lotus/blob/master/api/api_full.go
 [permissions]: https://lotu.sh/en+api#what-authorization-level-should-i-use-21853
-[states]: https://github.com/filecoin-project/go-fil-markets/blob/095b388f830be66ceedc0965e5c7afcb1b96ad60/storagemarket/types.go#L30-L60
+[states]: https://github.com/filecoin-project/go-fil-markets/blob/master/storagemarket/dealstatus.go
+[the storage market technical documentation]: https://github.com/filecoin-project/go-fil-markets/tree/master/storagemarket#technical-documentation
 [license]: ./LICENSE.txt
 [rubygems.org]: https://rubygems.org
 [subvisual]: http://subvisual.com

data/filecoin.gemspec

@@ -38,4 +38,6 @@ Gem::Specification.new do |spec|
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "dry-struct", "~> 1.0"
 end

data/lib/filecoin.rb

@@ -1,4 +1,5 @@
 require "filecoin/client"
+require "filecoin/configuration"
 require "filecoin/types"
 require "filecoin/version"
 require "forwardable"
@@ -7,6 +8,8 @@ module Filecoin
   class << self
     extend Forwardable
 
+    include Configurable
+
     def_delegators :client, *Client::Node.public_instance_methods
 
     def client

data/lib/filecoin/client.rb

@@ -7,23 +7,23 @@ module Filecoin
 
     attr_reader :uri, :token
 
-    def initialize(uri: nil, token: nil)
-      @uri = initialize_uri(uri)
-      @token = initialize_token(token)
+    def initialize(opts = {})
+      @uri = initialize_uri(opts)
+      @token = initialize_token(opts)
     end
 
     private
 
-    def initialize_uri(uri)
-      uri ||= ENV["FILECOIN_URL"]
+    def initialize_uri(opts)
+      uri = opts.fetch(:uri, ENV["FILECOIN_URL"])
 
       return if uri.nil?
 
       URI(uri)
     end
 
-    def initialize_token(token)
-      token || ENV["FILECOIN_TOKEN"]
+    def initialize_token(opts)
+      opts.fetch(:token, ENV["FILECOIN_TOKEN"])
     end
 
     def json_rpc_call(method, *params)

data/lib/filecoin/client/node.rb

@@ -17,14 +17,16 @@ module Filecoin
         json_rpc_call "Filecoin.ClientQueryAsk", peer_id, miner_id
       end
 
-      def client_start_deal(start_deal_params)
+      def client_start_deal(start_deal_params, extract_response: false)
         params = if start_deal_params.is_a?(Hash)
                    start_deal_params
                  else
                    start_deal_params.as_json
                  end
 
-        json_rpc_call("Filecoin.ClientStartDeal", params)
+        response = json_rpc_call("Filecoin.ClientStartDeal", params)
+
+        extract_response ? response.dig("result", "/") : response
       end
 
       def net_peers

data/lib/filecoin/configuration.rb

@@ -0,0 +1,20 @@
+module Filecoin
+  class Configuration
+    attr_writer :default_wallet
+
+    def default_wallet
+      @default_wallet || ENV["FILECOIN_WALLET"]
+    end
+  end
+
+  module Configurable
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    alias config configuration
+
+    def configure
+      yield configuration
+    end
+  end
+end

data/lib/filecoin/deal.rb

@@ -0,0 +1,39 @@
+require "dry-struct"
+require "filecoin/deals/state"
+
+module Filecoin
+  class Deal < Dry::Struct
+    attribute? :deal_id,         Dry::Types["integer"].optional
+    attribute? :duration,        Dry::Types["integer"].optional
+    attribute? :message,         Dry::Types["string"].optional
+    attribute? :piece_cid,       Dry::Types["string"].optional
+    attribute? :price_per_epoch, Dry::Types["string"].optional
+    attribute? :proposal_cid,    Dry::Types["string"].optional
+    attribute? :provider,        Dry::Types["string"].optional
+    attribute? :size,            Dry::Types["integer"].optional
+    attribute? :state,           Dry::Types["integer"].optional
+
+    module ClassMethods
+      def from_deal_info(deal_info) # rubocop:disable Metrics/MethodLength
+        new(
+          deal_id: deal_info["DealID"],
+          duration: deal_info["Duration"],
+          message: deal_info["Message"],
+          piece_cid: deal_info.dig("PieceCID", "/"),
+          price_per_epoch: deal_info["PricePerEpoch"],
+          proposal_cid: deal_info.dig("ProposalCid", "/"),
+          provider: deal_info["Provider"],
+          size: deal_info["Size"],
+          state: deal_info["State"],
+        )
+      end
+    end
+
+    extend ClassMethods
+    include Deals::State
+
+    def initialize(attrs = {})
+      super
+    end
+  end
+end

data/lib/filecoin/deals/state.rb

@@ -0,0 +1,63 @@
+module Filecoin
+  module Deals
+    module State
+      STATES = %i[
+        unknown
+        not_found
+        proposal_rejected
+        proposal_accepted
+        staged
+        sealing
+        active
+        expired
+        slashed
+        failing
+        funds_ensured
+        waiting_for_data_request
+        validating
+        waiting_for_acceptance
+        transferring
+        waiting_for_data
+        verifying_data
+        ensure_provider_funds
+        ensure_client_funds
+        provider_funding
+        client_funding
+        publish
+        publishing
+        error
+        completed
+      ].freeze
+
+      STATES.each_with_index do |state, index|
+        define_method("#{state}?") do
+          self.state == index
+        end
+      end
+
+      GOOD_STATES = %i[proposal_accepted sealing active].freeze
+      BAD_STATES = %i[failing error].freeze
+      PENDING_STATES = %i[
+        ensure_client_funds client_funding funds_ensured
+        waiting_for_data_request transferring validating
+      ].freeze
+      FINISHED_STATES = %i[slashed expired].freeze
+
+      def bad?
+        BAD_STATES.include?(STATES[state])
+      end
+
+      def finished?
+        FINISHED_STATES.include?(STATES[state])
+      end
+
+      def good?
+        GOOD_STATES.include?(STATES[state])
+      end
+
+      def pending?
+        PENDING_STATES.include?(STATES[state])
+      end
+    end
+  end
+end

data/lib/filecoin/types/start_deal_params.rb

@@ -3,9 +3,9 @@ module Filecoin
     class StartDealParams
       attr_reader :data, :wallet, :miner, :epoch_price, :min_blocks_duration, :deal_start_epoch
 
-      def initialize(data:, wallet:, miner:, epoch_price:, min_blocks_duration: nil, deal_start_epoch: nil)
+      def initialize(data:, wallet: nil, miner:, epoch_price:, min_blocks_duration: nil, deal_start_epoch: nil)
         @data = data
-        @wallet = wallet
+        @wallet = wallet || Filecoin.config.default_wallet
         @miner = miner
         @epoch_price = epoch_price
         @min_blocks_duration = min_blocks_duration

data/lib/filecoin/version.rb

@@ -1,3 +1,3 @@
 module Filecoin
-  VERSION = "0.2.0".freeze
+  VERSION = "0.3.0".freeze
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: filecoin
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Pedro Costa
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-06-12 00:00:00.000000000 Z
-dependencies: []
+date: 2020-07-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: |
   Filecoin (https://filecoin.io/) is a distributed storage network based on a
   blockchain mechanism.  Filecoin miners provide storage capacity for the
@@ -29,6 +43,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
@@ -46,6 +61,9 @@ files:
 - lib/filecoin.rb
 - lib/filecoin/client.rb
 - lib/filecoin/client/node.rb
+- lib/filecoin/configuration.rb
+- lib/filecoin/deal.rb
+- lib/filecoin/deals/state.rb
 - lib/filecoin/http.rb
 - lib/filecoin/types.rb
 - lib/filecoin/types/cid.rb