Skip to content

Commit

Permalink
feat: support accepted ipfs uris
Browse files Browse the repository at this point in the history
  • Loading branch information
@satello
satello committed Oct 9, 2018
1 parent ae74d7a commit d90473c
Show file tree
Hide file tree
Showing 15 changed files with 303 additions and 53 deletions.
Binary file modified docs/_build/doctrees/archon.doctree
View file
Binary file not shown.
Binary file modified docs/_build/doctrees/environment.pickle
View file
Binary file not shown.
Binary file modified docs/_build/doctrees/ipfs.doctree
View file
Binary file not shown.
4 changes: 4 additions & 0 deletions docs/_build/html/_sources/archon.rst.txt
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _archon:

======
Archon
======
Expand Down Expand Up @@ -179,6 +181,8 @@ Example
------------------------------------------------------------------------------
.. _set-ipfs-gateway:
archon.setIpfsGateway()
=======================
Expand Down
35 changes: 32 additions & 3 deletions docs/_build/html/_sources/ipfs.rst.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,43 @@ There are several things to keep in mind when using ``IPFS`` with ``Archon``

------------------------------------------------------------------------------

Using ``/ipfs/`` URIs
IPFS Gateways
===============

Most browsers do not currently support interacting with the ``ipfs`` network directly.
Therefore in order to fetch data from the ``ipfs`` network we need to use an IPFS Gateway,
which is an ``http`` protocol address that returns data from the ``ipfs`` network.

It is important that you choose a gateway that you trust, as a malicious gateway can
return invalid data. Please head the warning below:

.. warning:: Archon considers data returned directly from a valid ``ipfs`` URI pre-validated. This is because hash validation is built into the protocol. As we need to use gateways to interact with the ``ipfs`` network at this time, `MAKE SURE YOU SET A GATEWAY THAT YOU TRUST`, or otherwise re-validate your ``ipfs`` hashes yourself.

The default gateway set is ``https://gateway.ipfs.io``. This is the gateway provided by the Protocol Labs staff.

To set a custom gateway, use ``archon.setIpfsGateway(uri)``.
See documentation on setting a gateway :ref:`here <set-ipfs-gateway>`

IPFS URIs
=====================

``IPFS`` URIs are recognized in any of these formats:

1) ``/ipfs/Qm...../foo/bar``
2) ``ipfs:/ipfs/Qm...../foo/bar``
3) ``fs:/ipfs/Qm...../foo/bar``

Gateway URI's == Bad
====================

It is not recommended that you link directly to an ``IPFS`` gateway as the ``fileURI``
in Evidence or MetaEvidence. It will not be able to be verified using Archon without
a custom hashing function. The ``IPFS`` protocol does transformations on the data before hashing,
therefore a hash can not be verified naively using the resulting ``IPFS`` multihash
and the original file contents.
and the original file contents. In addition ``IPFS`` data should be able to be fetched
by any gateway or node in the network, and a user should be able to use any gateway or node
that they trust. Therefore hardcoding a gateway, which may not be trusted by the consumer,
would require additional validation regardless.

Archon treats all ``http(s)://`` URI's the same, and will try to validate the hash
as if they were standard hashes.
Expand Down Expand Up @@ -47,7 +76,7 @@ as if they were standard hashes.
archon.utils.validateFileFromURI(fileURI).then(data => {console.log(data.isValid)})
> true
``Acceptable:``
``Not Recommended:``

.. code-block:: javascript
Expand Down
64 changes: 32 additions & 32 deletions docs/_build/html/archon.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="archon.arbitrable" href="archon-arbitrable.html" />
<link rel="prev" title="IPFS Links and Validation" href="ipfs.html" />
<link rel="prev" title="Evidence Examples" href="evidence.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
Expand All @@ -31,7 +31,7 @@ <h3>Navigation</h3>
<a href="archon-arbitrable.html" title="archon.arbitrable"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="ipfs.html" title="IPFS Links and Validation"
<a href="evidence.html" title="Evidence Examples"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">eth-archon 0.1.0 documentation</a> &#187;</li>
</ul>
Expand All @@ -43,7 +43,7 @@ <h3>Navigation</h3>
<div class="body" role="main">

<div class="section" id="archon">
<h1>Archon<a class="headerlink" href="#archon" title="Permalink to this headline"></a></h1>
<span id="id1"></span><h1>Archon<a class="headerlink" href="#archon" title="Permalink to this headline"></a></h1>
<blockquote>
<div>Class</div></blockquote>
<p>This is the main class of Archon.</p>
Expand Down Expand Up @@ -95,12 +95,12 @@ <h2>Archon.version<a class="headerlink" href="#archon-version" title="Permalink
</pre></div>
</div>
<p>Contains the version of the <code class="docutils literal notranslate"><span class="pre">archon</span></code> container object.</p>
<div class="section" id="id1">
<h3>Returns<a class="headerlink" href="#id1" title="Permalink to this headline"></a></h3>
<div class="section" id="id2">
<h3>Returns<a class="headerlink" href="#id2" title="Permalink to this headline"></a></h3>
<p><code class="docutils literal notranslate"><span class="pre">String</span></code>: The current version.</p>
</div>
<div class="section" id="id2">
<h3>Example<a class="headerlink" href="#id2" title="Permalink to this headline"></a></h3>
<div class="section" id="id3">
<h3>Example<a class="headerlink" href="#id3" title="Permalink to this headline"></a></h3>
<div class="highlight-javascript notranslate"><div class="highlight"><pre><span></span><span class="nx">archon</span><span class="p">.</span><span class="nx">version</span><span class="p">;</span>
<span class="o">&gt;</span> <span class="s2">&quot;1.0.0&quot;</span>
</pre></div>
Expand Down Expand Up @@ -132,8 +132,8 @@ <h3>Parameters<a class="headerlink" href="#parameters" title="Permalink to this
<li><code class="docutils literal notranslate"><span class="pre">ipfsGatewayURI</span></code> - <code class="docutils literal notranslate"><span class="pre">String</span></code>: The URI of a trusted <code class="docutils literal notranslate"><span class="pre">IPFS</span></code> gateway for fetching files from the IPFS network.</li>
</ol>
</div>
<div class="section" id="id3">
<h3>Example<a class="headerlink" href="#id3" title="Permalink to this headline"></a></h3>
<div class="section" id="id4">
<h3>Example<a class="headerlink" href="#id4" title="Permalink to this headline"></a></h3>
<p>Instantiate Archon as an object to have access to all initialized modules.</p>
<div class="highlight-javascript notranslate"><div class="highlight"><pre><span></span><span class="kd">var</span> <span class="nx">Archon</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;eth-archon&#39;</span><span class="p">);</span>

Expand Down Expand Up @@ -162,18 +162,18 @@ <h2>archon.setProvider()<a class="headerlink" href="#archon-setprovider" title="
<p class="first admonition-title">Note</p>
<p class="last">If called on the <code class="docutils literal notranslate"><span class="pre">archon</span></code> class it will update the provider for all submodules. <code class="docutils literal notranslate"><span class="pre">archon.arbitrable</span></code>, <code class="docutils literal notranslate"><span class="pre">archon.arbitrator</span></code>, etc.</p>
</div>
<div class="section" id="id4">
<h3>Parameters<a class="headerlink" href="#id4" title="Permalink to this headline"></a></h3>
<div class="section" id="id5">
<h3>Parameters<a class="headerlink" href="#id5" title="Permalink to this headline"></a></h3>
<ol class="arabic simple">
<li><code class="docutils literal notranslate"><span class="pre">myProvider</span></code> - <code class="docutils literal notranslate"><span class="pre">Object|String</span></code>: A provider object or URI.</li>
</ol>
</div>
<div class="section" id="id5">
<h3>Returns<a class="headerlink" href="#id5" title="Permalink to this headline"></a></h3>
<div class="section" id="id6">
<h3>Returns<a class="headerlink" href="#id6" title="Permalink to this headline"></a></h3>
<p><code class="docutils literal notranslate"><span class="pre">Boolean</span></code></p>
</div>
<div class="section" id="id6">
<h3>Example<a class="headerlink" href="#id6" title="Permalink to this headline"></a></h3>
<div class="section" id="id7">
<h3>Example<a class="headerlink" href="#id7" title="Permalink to this headline"></a></h3>
<div class="highlight-javascript notranslate"><div class="highlight"><pre><span></span><span class="kd">var</span> <span class="nx">Archon</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;archon&#39;</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">archon</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Archon</span><span class="p">(</span><span class="s1">&#39;http://localhost:8545&#39;</span><span class="p">);</span>

Expand All @@ -186,23 +186,23 @@ <h3>Example<a class="headerlink" href="#id6" title="Permalink to this headline">
<span class="nx">archon</span><span class="p">.</span><span class="nx">arbitrator</span><span class="p">.</span><span class="nx">setProvider</span><span class="p">(</span><span class="s1">&#39;https://mainnet.infura.io/&#39;</span><span class="p">)</span>
</pre></div>
</div>
<hr class="docutils" />
</div>
</div>
<hr class="docutils" />
<div class="section" id="archon-setipfsgateway">
<h2>archon.setIpfsGateway()<a class="headerlink" href="#archon-setipfsgateway" title="Permalink to this headline"></a></h2>
<span id="set-ipfs-gateway"></span><h2>archon.setIpfsGateway()<a class="headerlink" href="#archon-setipfsgateway" title="Permalink to this headline"></a></h2>
<div class="highlight-javascript notranslate"><div class="highlight"><pre><span></span><span class="nx">archon</span><span class="p">.</span><span class="nx">setIpfsGateway</span><span class="p">(</span><span class="nx">ipfsGatewayURI</span><span class="p">)</span>
</pre></div>
</div>
<p>Will change the <code class="docutils literal notranslate"><span class="pre">IPFS</span></code> gateway environment variable.</p>
<div class="section" id="id7">
<h3>Parameters<a class="headerlink" href="#id7" title="Permalink to this headline"></a></h3>
<div class="section" id="id8">
<h3>Parameters<a class="headerlink" href="#id8" title="Permalink to this headline"></a></h3>
<ol class="arabic simple">
<li><code class="docutils literal notranslate"><span class="pre">ipfsGatewayURI</span></code> - <code class="docutils literal notranslate"><span class="pre">Object</span></code>: A URI to a trusted IPFS gateway .</li>
</ol>
</div>
<div class="section" id="id8">
<h3>Example<a class="headerlink" href="#id8" title="Permalink to this headline"></a></h3>
<div class="section" id="id9">
<h3>Example<a class="headerlink" href="#id9" title="Permalink to this headline"></a></h3>
<div class="highlight-javascript notranslate"><div class="highlight"><pre><span></span><span class="kd">var</span> <span class="nx">Archon</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;archon&#39;</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">archon</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">Archon</span><span class="p">(</span><span class="s1">&#39;http://localhost:8545&#39;</span><span class="p">);</span>

Expand All @@ -229,34 +229,34 @@ <h3><a href="index.html">Table of Contents</a></h3>
</ul>
</li>
<li><a class="reference internal" href="#archon-version">Archon.version</a><ul>
<li><a class="reference internal" href="#id1">Returns</a></li>
<li><a class="reference internal" href="#id2">Example</a></li>
<li><a class="reference internal" href="#id2">Returns</a></li>
<li><a class="reference internal" href="#id3">Example</a></li>
</ul>
</li>
<li><a class="reference internal" href="#archon-utils">Archon.utils</a></li>
<li><a class="reference internal" href="#new-archon">new Archon()</a><ul>
<li><a class="reference internal" href="#parameters">Parameters</a></li>
<li><a class="reference internal" href="#id3">Example</a></li>
<li><a class="reference internal" href="#id4">Example</a></li>
</ul>
</li>
<li><a class="reference internal" href="#archon-setprovider">archon.setProvider()</a><ul>
<li><a class="reference internal" href="#id4">Parameters</a></li>
<li><a class="reference internal" href="#id5">Returns</a></li>
<li><a class="reference internal" href="#id6">Example</a></li>
<li><a class="reference internal" href="#id5">Parameters</a></li>
<li><a class="reference internal" href="#id6">Returns</a></li>
<li><a class="reference internal" href="#id7">Example</a></li>
</ul>
</li>
<li><a class="reference internal" href="#archon-setipfsgateway">archon.setIpfsGateway()</a><ul>
<li><a class="reference internal" href="#id7">Parameters</a></li>
<li><a class="reference internal" href="#id8">Example</a></li>
<li><a class="reference internal" href="#id8">Parameters</a></li>
<li><a class="reference internal" href="#id9">Example</a></li>
</ul>
</li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
<p class="topless"><a href="ipfs.html"
title="previous chapter">IPFS Links and Validation</a></p>
<p class="topless"><a href="evidence.html"
title="previous chapter">Evidence Examples</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="archon-arbitrable.html"
title="next chapter">archon.arbitrable</a></p>
Expand Down Expand Up @@ -293,7 +293,7 @@ <h3>Navigation</h3>
<a href="archon-arbitrable.html" title="archon.arbitrable"
>next</a> |</li>
<li class="right" >
<a href="ipfs.html" title="IPFS Links and Validation"
<a href="evidence.html" title="Evidence Examples"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">eth-archon 0.1.0 documentation</a> &#187;</li>
</ul>
Expand Down
4 changes: 3 additions & 1 deletion docs/_build/html/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,9 @@ <h1>archon - Ethereum Arbitration Standard API<a class="headerlink" href="#archo
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ipfs.html">IPFS Links and Validation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ipfs.html#using-ipfs-uris">Using <code class="docutils literal notranslate"><span class="pre">/ipfs/</span></code> URIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="ipfs.html#ipfs-gateways">IPFS Gateways</a></li>
<li class="toctree-l2"><a class="reference internal" href="ipfs.html#ipfs-uris">IPFS URIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="ipfs.html#gateway-uri-s-bad">Gateway URI’s == Bad</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="evidence.html">Evidence Examples</a><ul>
Expand Down
Loading

1 comment on commit d90473c

@lidel
Copy link

@lidel lidel commented on d90473c May 16, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check #20

Please sign in to comment.