filecoin 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d03183ddc001622fb243e928ca9258cb3c8771439b9dbfdb745146e3d5197b31
-  data.tar.gz: 3f3e4cc8ca7a6bd4eef92dcb0055849147bd8c67ba730648a72a13b51f0410e5
+  metadata.gz: ef27efff91c40a5b52704f6a8aa63f2ede88e1d88e495444e8660e7746483538
+  data.tar.gz: 2ee28c49341b368e2cbab1dc872f72fb156da4217335a6a8e680ed0797a25992
 SHA512:
-  metadata.gz: ccd108d4b698c768f773c912cce6b14802ccd7b3d21e084b75c4ba0ff394b43329c21d7c1c48576ceec70ffee11727dd8debd9413343f1224716415fed3083c8
-  data.tar.gz: 1b736355b8757696ab368d4815bdf263d0a3414c04cbc2c6453a686bf0f1aa1deca77756a8b9f184adee877a5872ecac26bbf52163dbc37d52811fde563b5099
+  metadata.gz: e603609b41f74c9cfa5fd06072ef859036f3d6fb8644283dd4b824098c05db1dc0cfec23e6b140f661629ee84ee04fc4203449e00757172cc48d8725eee4ca10
+  data.tar.gz: d50ba2023ebb16ebc76c03cc064eca582fb1cd40318d594d5d0e567bb535940f0a2a893dc80c3390274b1930f1b04766c324e0a5ffc583c7670147a38989a39d

data/.rubocop.yml

@@ -30,6 +30,9 @@ Metrics/BlockLength:
   Exclude:
     - spec/**/*.rb
 
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
 Naming/PredicateName:
   ForbiddenPrefixes:
     - is_

data/CHANGELOG.md

@@ -10,6 +10,28 @@ The format is based on [Keep a Changelog], and this project adheres to
 Unreleased
 ----------
 
+_Coming soon_
+
+
+v0.2.0 - 2020-06-12
+-------------------
+
+- Expose the methods of `Filecoin::Client::Node` in `Filecoin` using its
+  default constructor (loads from environment variables);
+- Add support for `Filecoin.ClientGetDealInfo` through
+  `Filecoin::Client#client_get_deal_info`;
+- Add support for token authenticated API interaction;
+- Add support for `Filecoin.ClientStartDeal` through
+  `Filecoin::Client#client_start_deal`;
+- Add types for storage deal creation;
+- Add support for `Filecoin.ClientQueryAsk` through
+  `Filecoin::Client#client_query_ask`;
+- Add support for `Filecoin.NetPeers` through `Filecoin::Client#net_peers`.
+
+
+v0.1.0 - 2020-06-04
+-------------------
+
 - Add `Filecoin::Client` with `#chain_head` matching the `Filecoin.ChainHead`
   method in the Filecoin Lotus Node API.
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    filecoin (0.1.0)
+    filecoin (0.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -10,7 +10,7 @@ Installation
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "filecoin", "~> 0.1.0"
+gem "filecoin", "~> 0.2.0"
 ```
 
 And then execute:
@@ -25,6 +25,19 @@ Or install it yourself as:
 Usage
 -----
 
+```ruby
+# FILECOIN_URL="https://filecoin.example.com:1234"
+# FILECOIN_TOKEN="asdfghjkl"
+Filecoin.chain_head
+```
+
+`Filecoin` exposes all the API methods for applications that prefer to load
+configuration from environment variables. These methods are implemented by
+`Filecoin::Client` which is abstracted away in this case.
+
+
+### Client
+
 Clients are initialized with the URI to the target API server. This URI can be
 provided as a `URI` object, or as a `String`. If omitted, `Filecoin::Client`
 defaults to the value of the `FILECOIN_URL` environment variable.
@@ -40,18 +53,268 @@ Filecoin::Client.new(uri: "https://filecoin.example.com:1234")
 Filecoin::Client.new
 ```
 
-For each available method in the [Filecoin Node API] use the respective method
-in `Filecoin::Client`. For instance, to call `Filecoin.ChainHead` use
-`Filecoin::Client#chain_head`.
+Some methods in the [Filecoin Node API] require special [permissions]. To use
+any such method, you'll have to provide your authentication token to the
+client, either on initialization or through the `FILECOIN_TOKEN` environment
+variable.
 
 ```ruby
-client = Filecoin::Client.new
-client.chain_head # => => {"jsonrpc"=>"2.0", "result"=>{...}, ...}
+# with a token String
+Filecoin::Client.new(token: "asdfghjkl")
+
+# from the FILECOIN_TOKEN environment variable
+Filecoin::Client.new
 ```
 
+For each supported method of the [Filecoin Node API] there is a respective
+method in `Filecoin::Client`. For instance, to call `Filecoin.ChainHead` use
+`Filecoin::Client#chain_head`.
+
+Some methods require their parameters to follow a hard-to-describe structure.
+In such cases, use the respective type class to make things simpler.
+
 All methods return the server's JSON parsed response as a plain `Hash`.
 
 
+### Supported Filecoin Node API methods
+
+- [x] `Filecoin.ChainHead`
+- [x] `Filecoin.ClientGetDealInfo`
+- [x] `Filecoin.ClientQueryAsk`
+- [x] `Filecoin.ClientStartDeal`
+- [x] `Filecoin.NetPeers`
+
+
+### Filecoin.ChainHead
+
+Returns the current head of the chain.
+
+```ruby
+Filecoin.chain_head
+```
+
+```json
+{
+  "jsonrpc": "2.0",
+  "result": {
+    "Cids": [
+      {
+        "/": "bafy2bzaceabs2fnv5xehoibdik3bp3flze3v3mbxdprsu2yt5urpz3sd4sysk"
+      }
+    ],
+    "Blocks": [
+      {
+        "Miner": "t01100",
+        "Ticket": {
+          "VRFProof": "koRyPdBso5iROYfkkLLS8BbkYkziPmao/DJsVTGWRC7gHz/RPSKG/LCjvcOylI+IEzCghQAHantaG96rUAwc5m08FBhYp9/zx/eZSce42ktfIGfO6lF1ymya3Tlzn2Xd"
+        },
+        "ElectionProof": {
+          "VRFProof": "qMwlLzao8BJn38wJ5/kxcorBNr1IGMpOedLYHV7y7g71vK5suKHIZsC66jtxvCLdFlqWKGsgBifbJkAo38NIPCD4cTiDBz5J3PzDLVAy8f0x3JV7BoaQVmmUr57BCiG+"
+        },
+        "BeaconEntries": [
+          {
+            "Round": 125398,
+            "Data": "hRPhxVhoujTf7wZoZ4zk/bucunZeEpF5Oi7O1Es1gnnYNBzHlesNhZ8GHfjsULTHFvOVngrawT5Y3P5u7sx2f7ysVfuh16jo1CFJu3KSFfilBXCmjRCKG6rC6KRhQVMO"
+          }
+        ],
+        "WinPoStProof": [
+          {
+            "RegisteredProof": 15,
+            "ProofBytes": "srmO6BOqe4lEh4RbVybhkEtH3wDV4QFl/h599QG3K5DZN2yZF77gy0Apaybjr/UgqUVoPPELOkW7HcZLLgSRXwbQ6dmKPnb5rC58ucK4tcab5tKbz6xk3jjoYkHC8tbjEETOmRYlOyvYFSmkkRbdT0aixosSRiecQv94SyiSTWwZ2hNrnDW6tsbqNd8WGTqCjbhvMvHFxFATXv2xu8ndQ+YjYrpuaY/HRz3NfLq0Gj1niqXawkAw2UgKh4aod79A"
+          }
+        ],
+        "Parents": [
+          {
+            "/": "bafy2bzacec6osar3i62fr3u4dlw4bxns3sc4ycipjbo4u6u4tbgh6f7hwhypi"
+          },
+          {
+            "/": "bafy2bzaceblqc4nzzneqg5sd5ik23jnt77fhizm7mqj5ulcyxwlu6p7cftoam"
+          }
+        ],
+        "ParentWeight": "1584010805",
+        "Height": 99565,
+        "ParentStateRoot": {
+          "/": "bafy2bzacecolsvk4s2pn7eeso7eobseqxs2x6vkkcenjyd6ikbk4hanmmr6oe"
+        },
+        "ParentMessageReceipts": {
+          "/": "bafy2bzaced3qvpgmcwl4qyxq2rwgmeduqhtnhdunwdisvyejup7vcqxi5cor2"
+        },
+        "Messages": {
+          "/": "bafy2bzaceavnr75wltzlp5eqi4er7u2f5c4halukuetqk2vmbqd7ltcms5cjs"
+        },
+        "BLSAggregate": {
+          "Type": 2,
+          "Data": "sXWOH7SeDDQeMTKIBewRGdNYlRGPchtj2iJlXNwZrRV/ukmlcl2yLA24fQhNy1lDDlKNZ+juGq6TyhYGimRMLCaAjCc50jfxOGEk1+uTpxb3QzxknpopWoDHEhCpPz59"
+        },
+        "Timestamp": 1591983325,
+        "BlockSig": {
+          "Type": 2,
+          "Data": "krAlrTcpd3QFNETCn2sTsXuqlIHCsmwss+iUziCE/F6mVs6UxZ/f43uyHjKRBojwFZRJKsdZV3JWfg+HrWcj51x5qBAwNwReCCOpJUBwEbLcdrUDyrGIzJ203g6r6YS7"
+        },
+        "ForkSignaling": 0
+      }
+    ],
+    "Height": 99565
+  },
+  "id": 3
+}
+```
+
+
+### Filecoin.ClientGetDealInfo
+
+Get the information on a specific deal.
+
+```ruby
+Filecoin.client_get_deal_info("bafyreigc4b4fqsval4pjmfncaqdezhe5y3anwavjyzpj4mar73e6n7mvj4")
+```
+
+```json
+{
+  "jsonrpc": "2.0",
+  "result": {
+    "ProposalCid": {
+      "/": "bafyreigc4b4fqsval4pjmfncaqdezhe5y3anwavjyzpj4mar73e6n7mvj4"
+    },
+    "State": 5,
+    "Message": "",
+    "Provider": "t0239463",
+    "PieceCID": {
+      "/": "bafk4chzaw4zjxdl3d6vd7shbr23ps4nygl77ywogasvzskvn7jszur3tpetq"
+    },
+    "Size": 2080768,
+    "PricePerEpoch": "500000000",
+    "Duration": 1492,
+    "DealID": 2725
+  },
+  "id": 3
+}
+```
+
+
+#### Understanding Deal State
+
+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.
+
+
+### Filecoin.ClientQueryAsk
+
+```ruby
+Filecoin.client_query_ask(
+  # ID of the peer to query
+  "0003KooWBhDJkzmK1QKQqp7hRDAA9cLBNsneaYn2TBGdUSKXzoc8",
+  # ID of the miner to query about
+  "t1234567",
+)
+```
+
+
+### Filecoin.ClientStartDeal
+
+This method requires the aid of some type classes due to the complex structure
+of the payload. Make use of `Filecoin::Types::DataRef` to represent the data to
+transfer for this deal, and then pass it on to
+`Filecoin::Types::StartDealParams` to describe the deal to propose.
+
+If successful, the response contains the CID of the proposed deal. Use
+`Filecoin.ClientGetDealInfo` to query the network about its evolution.
+
+```ruby
+data_ref = Filecoin::Types::DataRef.new(
+  # (Optional) Define how the data will be transferred. Must be "graphsync" or
+  # "manual". Defaults to "graphsync".
+  transfer_type: "manual",
+  # CID of the file to transfer
+  root: "bafkreicomazccnbsql4nvtp6jfrk5qwys63ktakp4hkdt3ncl2hvhemwde",
+  # (Optional) Piece CID. Required for "manual" transfer deals.
+  piece_cid: "bafk4chzak7ieup5a3aup2vzavfzlnmbxxx4bpi3kpykhbkn4cdemdmk3aeaa",
+  # (Optional) Piece size. Required for "manual" transfer deals.
+  piece_size: 532_676_608,ClientGetDealInfo
+)
+
+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
+  wallet: "t13nqjc55m3h327646cwcu4lchdx4lkw7ccxnx4ca",
+  # Address ot the miner to whom this deal is to be proposed
+  miner: "t1234567",
+  # Price per block in attoFIL to propose for this deal
+  epoch_price: 500_000_000,
+  # (Optional) Duration of the deal in blocks
+  min_blocks_duration: 1572,
+  # (Optional) Unix timestamp stating the moment the deal starts
+  deal_start_epoch: 1591979600,
+)
+
+Filecoin.client_start_deal(start_deal_params)
+```
+
+```json
+{
+  "jsonrpc": "2.0",
+  "result": {
+    "/": "bafyreihdss5rlzmft3lzez2n5jyxqo5znhewdvpbcnhbnairkc2yl6zk6e"
+  },
+  "id": 3
+}
+```
+
+
+### Filecoin.NetPeers
+
+Get the peers the node is connected to.
+
+```ruby
+Filecoin.net_peers
+```
+
+```json
+{
+  "jsonrpc": "2.0",
+  "result": [
+    {
+      "Addrs": [
+        "/ip4/54.212.151.167/tcp/40817"
+      ],
+      "ID": "12D3KooWGBxkba5Havy4wiGvLVmqPBCPjs7xPQPtqNr1HRq6RaVM"
+    }
+  ],
+  "id": 3
+}
+```
+
+
 Development
 -----------
 
@@ -71,6 +334,15 @@ Contributing
 Bug reports and pull requests are welcome on GitHub at
 https://github.com/subvisual/filecoin-ruby.
 
+This project was created to provide a Ruby interface for projects we at
+Subvisual are actively working on. We are not aiming to provide an exaustive
+interface for the time being, and will focus our development efforts as needed.
+
+We welcome anyone interested in helping the development of this project to
+contribute directly with a pull request. Otherwise, please feel free to request
+any features you feel are missing in an issue. We will do our best to comply,
+within reason and the limits of our own availability.
+
 
 License
 -----
@@ -90,6 +362,9 @@ filecoin-ruby was created and is maintained with :heart: by
 [![Subvisual][subvisual-logo]][subvisual]
 
 
+[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
 [license]: ./LICENSE.txt
 [rubygems.org]: https://rubygems.org
 [subvisual]: http://subvisual.com

data/lib/filecoin.rb

@@ -1,4 +1,16 @@
+require "filecoin/client"
+require "filecoin/types"
 require "filecoin/version"
+require "forwardable"
 
 module Filecoin
+  class << self
+    extend Forwardable
+
+    def_delegators :client, *Client::Node.public_instance_methods
+
+    def client
+      Client.new
+    end
+  end
 end

data/lib/filecoin/client.rb

@@ -5,10 +5,11 @@ module Filecoin
   class Client
     include Filecoin::Client::Node
 
-    attr_reader :uri
+    attr_reader :uri, :token
 
-    def initialize(uri: nil)
+    def initialize(uri: nil, token: nil)
       @uri = initialize_uri(uri)
+      @token = initialize_token(token)
     end
 
     private
@@ -21,6 +22,10 @@ module Filecoin
       URI(uri)
     end
 
+    def initialize_token(token)
+      token || ENV["FILECOIN_TOKEN"]
+    end
+
     def json_rpc_call(method, *params)
       @json_rpc_call_id ||= 0
       @json_rpc_call_id += 1
@@ -32,7 +37,7 @@ module Filecoin
         id: @json_rpc_call_id,
       }
 
-      Http.post(uri, body)
+      Http.post(uri, token, body)
     end
   end
 end

data/lib/filecoin/client/node.rb

@@ -1,9 +1,35 @@
+require "filecoin/types/cid"
+
 module Filecoin
   class Client
     module Node
       def chain_head
         json_rpc_call "Filecoin.ChainHead"
       end
+
+      def client_get_deal_info(deal_id)
+        params = Types::Cid.new(deal_id).as_json
+
+        json_rpc_call "Filecoin.ClientGetDealInfo", params
+      end
+
+      def client_query_ask(peer_id, miner_id)
+        json_rpc_call "Filecoin.ClientQueryAsk", peer_id, miner_id
+      end
+
+      def client_start_deal(start_deal_params)
+        params = if start_deal_params.is_a?(Hash)
+                   start_deal_params
+                 else
+                   start_deal_params.as_json
+                 end
+
+        json_rpc_call("Filecoin.ClientStartDeal", params)
+      end
+
+      def net_peers
+        json_rpc_call "Filecoin.NetPeers"
+      end
     end
   end
 end

data/lib/filecoin/http.rb

@@ -4,11 +4,12 @@ require "net/http"
 module Filecoin
   module Http
     module ClassMethods
-      def post(uri, data)
+      def post(uri, token, data)
         return if uri.nil?
 
         req = Net::HTTP::Post.new(uri)
         req["Content-Type"] = "application/json"
+        req["Authorization"] = "Bearer #{token}" unless token.nil?
         req.body = data.to_json
 
         response = request(req)

data/lib/filecoin/types.rb

@@ -0,0 +1,3 @@
+require "filecoin/types/cid"
+require "filecoin/types/data_ref"
+require "filecoin/types/start_deal_params"

data/lib/filecoin/types/cid.rb

@@ -0,0 +1,28 @@
+module Filecoin
+  module Types
+    class Cid
+      attr_reader :target
+
+      def self.new(target)
+        return nil if target.nil?
+        return target if target.is_a?(Cid)
+
+        super
+      end
+
+      def initialize(target)
+        @target = target
+      end
+
+      def valid?
+        !target.nil? && !target.empty?
+      end
+
+      def as_json
+        {
+          "/" => target,
+        }
+      end
+    end
+  end
+end

data/lib/filecoin/types/data_ref.rb

@@ -0,0 +1,28 @@
+require "filecoin/types/cid"
+
+module Filecoin
+  module Types
+    class DataRef
+      attr_reader :transfer_type, :root, :piece_cid, :piece_size
+
+      def initialize(transfer_type: nil, root:, piece_cid: nil, piece_size: nil)
+        @transfer_type = transfer_type
+        @root = Cid.new(root)
+        @piece_cid = Cid.new(piece_cid)
+        @piece_size = piece_size
+      end
+
+      def as_json
+        hash = {
+          "Root" => root.as_json,
+        }
+
+        hash["TransferType"] = transfer_type unless transfer_type.nil?
+        hash["PieceCID"] = piece_cid.as_json unless piece_cid.nil?
+        hash["PieceSize"] = piece_size unless piece_size.nil?
+
+        hash
+      end
+    end
+  end
+end

data/lib/filecoin/types/start_deal_params.rb

@@ -0,0 +1,30 @@
+module Filecoin
+  module Types
+    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)
+        @data = data
+        @wallet = wallet
+        @miner = miner
+        @epoch_price = epoch_price
+        @min_blocks_duration = min_blocks_duration
+        @deal_start_epoch = deal_start_epoch
+      end
+
+      def as_json
+        hash = {
+          "Data" => data.as_json,
+          "Wallet" => wallet,
+          "Miner" => miner,
+          "EpochPrice" => epoch_price.to_s,
+        }
+
+        hash["MinBlocksDuration"] = min_blocks_duration unless min_blocks_duration.nil?
+        hash["DealStartEpoch"] = deal_start_epoch unless deal_start_epoch.nil?
+
+        hash
+      end
+    end
+  end
+end

data/lib/filecoin/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: filecoin
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Pedro Costa
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-06-04 00:00:00.000000000 Z
+date: 2020-06-12 00:00:00.000000000 Z
 dependencies: []
 description: |
   Filecoin (https://filecoin.io/) is a distributed storage network based on a
@@ -47,6 +47,10 @@ files:
 - lib/filecoin/client.rb
 - lib/filecoin/client/node.rb
 - lib/filecoin/http.rb
+- lib/filecoin/types.rb
+- lib/filecoin/types/cid.rb
+- lib/filecoin/types/data_ref.rb
+- lib/filecoin/types/start_deal_params.rb
 - lib/filecoin/version.rb
 homepage: https://github.com/subvisual/filecoin-ruby
 licenses: []
@@ -54,7 +58,7 @@ metadata:
   homepage_uri: https://github.com/subvisual/filecoin-ruby
   source_code_uri: https://github.com/subvisual/filecoin-ruby
   changelog_uri: https://github.com/subvisual/filecoin-ruby/blob/master/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -70,7 +74,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Interact with the Filecoin network
 test_files: []