mirror of https://github.com/zcash/zips.git
Daira Hopwood
GitHub
commit
ebe3839640
|
|
@ -46,7 +46,7 @@ License: MIT</pre>
|
|||
<span class="k">zcashparam </span><span class="err">=</span> <span class="p">[</span> <span class="k">addrparam </span><span class="err">/</span> <span class="k">amountparam </span><span class="err">/</span> <span class="k">memoparam </span><span class="err">/</span> <span class="k">messageparam </span><span class="err">/</span> <span class="k">labelparam </span><span class="err">/</span> <span class="k">reqparam </span><span class="err">/</span> <span class="k">otherparam </span><span class="p">]</span>
|
||||
<span class="k">NONZERO </span><span class="err">=</span> <span class="err">%</span><span class="k">x31-39</span>
|
||||
<span class="k">DIGIT </span><span class="err">=</span> <span class="err">%</span><span class="k">x30-39</span>
|
||||
<span class="k">paramindex </span><span class="err">=</span> <span class="s2">"."</span> <span class="k">NONZERO </span><span class="err">*</span><span class="k">DIGIT</span>
|
||||
<span class="k">paramindex </span><span class="err">=</span> <span class="s2">"."</span> <span class="k">NONZERO 0</span><span class="err">*3</span><span class="k">DIGIT</span>
|
||||
<span class="k">addrparam </span><span class="err">=</span> <span class="s2">"address"</span> <span class="p">[</span> <span class="k">paramindex </span><span class="p">]</span> <span class="s2">"="</span> <span class="k">zcashaddress</span>
|
||||
<span class="k">amountparam </span><span class="err">=</span> <span class="s2">"amount"</span> <span class="p">[</span> <span class="k">paramindex </span><span class="p">]</span> <span class="s2">"="</span> <span class="err">1*</span><span class="k">DIGIT </span><span class="p">[</span> <span class="s2">"."</span> <span class="err">1*8</span><span class="k">DIGIT </span><span class="p">]</span>
|
||||
<span class="k">labelparam </span><span class="err">=</span> <span class="s2">"label"</span> <span class="p">[</span> <span class="k">paramindex </span><span class="p">]</span> <span class="s2">"="</span> <span class="err">*</span><span class="k">qchar</span>
|
||||
|
|
@ -58,11 +58,13 @@ License: MIT</pre>
|
|||
<span class="k">qchar </span><span class="err">=</span> <span class="k">unreserved </span><span class="err">/</span> <span class="k">pct-encoded </span><span class="err">/</span> <span class="k">allowed-delims </span><span class="err">/</span> <span class="s2">":"</span> <span class="err">/</span> <span class="s2">"@"</span>
|
||||
<span class="k">allowed-delims </span><span class="err">=</span> <span class="s2">"!"</span> <span class="err">/</span> <span class="s2">"$"</span> <span class="err">/</span> <span class="s2">"'"</span> <span class="err">/</span> <span class="s2">"("</span> <span class="err">/</span> <span class="s2">")"</span> <span class="err">/</span> <span class="s2">"*"</span> <span class="err">/</span> <span class="s2">"+"</span> <span class="err">/</span> <span class="s2">","</span> <span class="err">/</span> <span class="s2">";"</span></pre>
|
||||
<p>Here, <code>ALPHA</code>, <code>unreserved</code> and <code>pct-encoded</code> are as defined in <a id="id5" class="footnote_reference" href="#rfc3986">3</a>. "base58" is defined as in <a id="id6" class="footnote_reference" href="#base58check">6</a>. "base64url" is defined as in <a id="id7" class="footnote_reference" href="#base64url">7</a> with padding omitted. (Note that this uses a different alphabet to the usual base64; the values 62 and 63 in the alphabet are encoded as <code>-</code> and <code>_</code> respectively.)</p>
|
||||
<p>A ZIP-321 URI represents a request for the construction of a transaction having one or more <em>payments</em>. In the case that only a single payment is being requested, the recipient address MAY be included in the <code>hier-part</code> component of the RFC 3986 URI; otherwise, multiple recipient addresses can be specified using <code>addrparam</code> parameters with different indices.</p>
|
||||
<p>A ZIP-321 URI represents a request for the construction of a transaction having one or more <em>payments</em>. In the case that only a single payment is being requested, the recipient address SHOULD be included in the <code>hier-part</code> component of the RFC 3986 URI; otherwise, multiple recipient addresses can be specified using <code>addrparam</code> parameters with different indices.</p>
|
||||
<p>Addresses, amounts, labels, and messages sharing the same <code>paramindex</code> (including the empty <code>paramindex</code>) are interpreted to be associated with the same payment for the purposes of payment construction. A <code>paramindex</code> MUST NOT have leading zero(s). There is no significance to the ordering of parameters, and <code>paramindex</code> values need not be sequential.</p>
|
||||
<p>Due to fundamental restrictions on transaction construction described in <a id="id8" class="footnote_reference" href="#saplingoutputs">8</a>, there may be no more than 2109 distinct payments requested by a single ZIP-321 URI.</p>
|
||||
<p>A URI of the form <code>zcash:<address>?...</code> MUST be considered equivalent to a URI of the form <code>zcash:?address=<address>&...</code> where <code><address></code> is an instance of <code>zcashaddress</code>.</p>
|
||||
<p>If there are any non-address parameters having a given <code>paramindex</code>, then the URI MUST contain an address parameter having that <code>paramindex</code>. There MUST NOT be more than one occurrence of a given parameter and <code>paramindex</code>.</p>
|
||||
<p>Productions of the form <code>1*x</code> indicate one or more successive instances of the production <code>x</code>. Productions of the form <code><n>*<m>x</code> indicate at least <cite><n></cite> and at most <cite><m></cite> instances of production <code>x</code>.</p>
|
||||
<p>Note that this grammar does not allow percent encoding outside the productions that use <code>qchar</code>, i.e. the values of label, message, <code>reqparam</code>, and <code>otherparam</code> parameters.</p>
|
||||
<section id="transfer-amount"><h3><span class="section-heading">Transfer amount</span><span class="section-anchor"> <a rel="bookmark" href="#transfer-amount"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
|
||||
<p>If an amount is provided, it MUST be specified in decimal ZEC. If a decimal fraction is present then a period (<cite>.</cite>) MUST be used as the separating character to separate the whole number from the decimal fraction, and both the whole number and the decimal fraction MUST be nonempty. No other separators (such as commas for grouping or thousands) are permitted. Leading zeros in the whole number or trailing zeros in the decimal fraction are ignored. There MUST NOT be more than 8 digits in the decimal fraction.</p>
|
||||
<dl>
|
||||
|
|
@ -75,6 +77,7 @@ License: MIT</pre>
|
|||
</ul>
|
||||
</dd>
|
||||
</dl>
|
||||
<p>The amount MUST NOT be greater than 21000000 ZEC (in general, monetary amounts in Zcash cannot be greater than this value).</p>
|
||||
</section>
|
||||
<section id="query-keys"><h3><span class="section-heading">Query Keys</span><span class="section-anchor"> <a rel="bookmark" href="#query-keys"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
|
||||
<dl>
|
||||
|
|
@ -106,13 +109,18 @@ License: MIT</pre>
|
|||
|
||||
zcash:?amount.1=1.234&amount.1=2.345&address.1=tmEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU"</pre>
|
||||
<p>Also invalid; duplicate <code>amount=</code> or <code>amount.1=</code> fields</p>
|
||||
<pre>zcash:tmEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU?amount=1%30
|
||||
zcash:tmEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU?%61mount=1
|
||||
zcash:%74mEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU?amount=1</pre>
|
||||
<p>Invalid; percent encoding is only allowed in <code>qchar</code> productions, which do not include addresses, amounts, or parameter names.</p>
|
||||
</section>
|
||||
</section>
|
||||
<section id="forward-compatibility"><h3><span class="section-heading">Forward compatibility</span><span class="section-anchor"> <a rel="bookmark" href="#forward-compatibility"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
|
||||
<p>Variables which are prefixed with a <code>req-</code> are considered required. If a parser does not recognize any variables which are prefixed with <code>req-</code>, it MUST consider the entire URI invalid. Any other variables that are not recognized, but that are not prefixed with a <code>req-</code>, SHOULD be ignored.</p>
|
||||
</section>
|
||||
<section id="backward-compatibility"><h3><span class="section-heading">Backward compatibility</span><span class="section-anchor"> <a rel="bookmark" href="#backward-compatibility"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h3>
|
||||
<p>As this ZIP is written, several clients already implement a <code>zcash:</code> URI scheme similar to this one, however usually without the additional <code>req-</code> prefix requirement or the facility to specify multiple payments using <code>paramindex</code>. Thus, it is RECOMMENDED that these features not be used in a mission-critical way until a grace period of 6 months from the finalization of this ZIP has passed, in order to allow client developers to release new versions, and users of old clients to upgrade.</p>
|
||||
<p>As this ZIP is written, several clients already implement a <code>zcash:</code> URI scheme similar to this one, however usually without the additional <code>req-</code> prefix requirement or the facility to specify multiple payments using <code>paramindex</code>. These implementations also generally do not support URIs, even with a single payment, where the address is specified as an <code>address=</code> query parameter rather than in the <code>hier-part</code> of the URI. They may also not support the <code>memo</code> parameter, or may not treat it as base64url-encoded.</p>
|
||||
<p>Thus, it is RECOMMENDED that these features not be used in a mission-critical way until a grace period of 6 months from the finalization of this ZIP has passed, in order to allow client developers to release new versions, and users of old clients to upgrade.</p>
|
||||
</section>
|
||||
</section>
|
||||
<section id="references"><h2><span class="section-heading">References</span><span class="section-anchor"> <a rel="bookmark" href="#references"><img width="24" height="24" src="assets/images/section-anchor.png" alt=""></a></span></h2>
|
||||
|
|
@ -172,6 +180,14 @@ zcash:?amount.1=1.234&amount.1=2.345&address.1=tmEZhbWHTpdKMw5it8YDspUXS
|
|||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<table id="saplingoutputs" class="footnote">
|
||||
<tbody>
|
||||
<tr>
|
||||
<th>8</th>
|
||||
<td><a href="https://zips.z.cash/protocol/protocol.pdf#saplingbalance">Restrictions on number of outputs in Zcash transactions</a></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
</section>
|
||||
</body>
|
||||
|
|
|
|||
41
zip-0321.rst
41
zip-0321.rst
|
|
@ -63,6 +63,7 @@ to provide a URI-based format which supports both the trivial use case and
|
|||
the slightly-more-complex situation where a payment may be intended for
|
||||
multiple recipients.
|
||||
|
||||
|
||||
Requirements
|
||||
============
|
||||
|
||||
|
|
@ -71,6 +72,7 @@ The format must be a valid URI.
|
|||
The format must permit the representation of one or more (payment address, amount,
|
||||
memo) tuples.
|
||||
|
||||
|
||||
Specification
|
||||
=============
|
||||
|
||||
|
|
@ -86,7 +88,7 @@ URI Syntax:
|
|||
zcashparam = [ addrparam / amountparam / memoparam / messageparam / labelparam / reqparam / otherparam ]
|
||||
NONZERO = %x31-39
|
||||
DIGIT = %x30-39
|
||||
paramindex = "." NONZERO *DIGIT
|
||||
paramindex = "." NONZERO 0*3DIGIT
|
||||
addrparam = "address" [ paramindex ] "=" zcashaddress
|
||||
amountparam = "amount" [ paramindex ] "=" 1*DIGIT [ "." 1*8DIGIT ]
|
||||
labelparam = "label" [ paramindex ] "=" *qchar
|
||||
|
|
@ -106,7 +108,7 @@ as ``-`` and ``_`` respectively.)
|
|||
|
||||
A ZIP-321 URI represents a request for the construction of a transaction having
|
||||
one or more *payments*. In the case that only a single payment is being
|
||||
requested, the recipient address MAY be included in the ``hier-part`` component
|
||||
requested, the recipient address SHOULD be included in the ``hier-part`` component
|
||||
of the RFC 3986 URI; otherwise, multiple recipient addresses can be specified
|
||||
using ``addrparam`` parameters with different indices.
|
||||
|
||||
|
|
@ -116,6 +118,10 @@ the same payment for the purposes of payment construction. A ``paramindex``
|
|||
MUST NOT have leading zero(s). There is no significance to the ordering of
|
||||
parameters, and ``paramindex`` values need not be sequential.
|
||||
|
||||
Due to fundamental restrictions on transaction construction described in
|
||||
[#saplingoutputs]_, there may be no more than 2109 distinct payments requested
|
||||
by a single ZIP-321 URI.
|
||||
|
||||
A URI of the form ``zcash:<address>?...`` MUST be considered equivalent to a
|
||||
URI of the form ``zcash:?address=<address>&...`` where ``<address>`` is an
|
||||
instance of ``zcashaddress``.
|
||||
|
|
@ -128,6 +134,10 @@ Productions of the form ``1*x`` indicate one or more successive instances of the
|
|||
production ``x``. Productions of the form ``<n>*<m>x`` indicate at least `<n>` and
|
||||
at most `<m>` instances of production ``x``.
|
||||
|
||||
Note that this grammar does not allow percent encoding outside the productions
|
||||
that use ``qchar``, i.e. the values of label, message, ``reqparam``, and
|
||||
``otherparam`` parameters.
|
||||
|
||||
Transfer amount
|
||||
---------------
|
||||
|
||||
|
|
@ -145,6 +155,9 @@ For example,
|
|||
* ``amount=50,000.00`` or ``amount=50,00`` or ``amount=50.`` or ``amount=.5``
|
||||
or ``amount=0.123456789`` are invalid.
|
||||
|
||||
The amount MUST NOT be greater than 21000000 ZEC (in general, monetary amounts
|
||||
in Zcash cannot be greater than this value).
|
||||
|
||||
Query Keys
|
||||
----------
|
||||
|
||||
|
|
@ -215,6 +228,15 @@ forbidden in ``paramindex``.
|
|||
|
||||
Also invalid; duplicate ``amount=`` or ``amount.1=`` fields
|
||||
|
||||
::
|
||||
|
||||
zcash:tmEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU?amount=1%30
|
||||
zcash:tmEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU?%61mount=1
|
||||
zcash:%74mEZhbWHTpdKMw5it8YDspUXSMGQyFwovpU?amount=1
|
||||
|
||||
Invalid; percent encoding is only allowed in ``qchar`` productions, which do
|
||||
not include addresses, amounts, or parameter names.
|
||||
|
||||
Forward compatibility
|
||||
---------------------
|
||||
|
||||
|
|
@ -229,10 +251,16 @@ Backward compatibility
|
|||
As this ZIP is written, several clients already implement a ``zcash:`` URI
|
||||
scheme similar to this one, however usually without the additional ``req-``
|
||||
prefix requirement or the facility to specify multiple payments using
|
||||
``paramindex``. Thus, it is RECOMMENDED that these features not be used in
|
||||
a mission-critical way until a grace period of 6 months from the finalization
|
||||
of this ZIP has passed, in order to allow client developers to release new
|
||||
versions, and users of old clients to upgrade.
|
||||
``paramindex``. These implementations also generally do not support URIs,
|
||||
even with a single payment, where the address is specified as an ``address=``
|
||||
query parameter rather than in the ``hier-part`` of the URI. They may also
|
||||
not support the ``memo`` parameter, or may not treat it as base64url-encoded.
|
||||
|
||||
Thus, it is RECOMMENDED that these features not be used in a mission-critical
|
||||
way until a grace period of 6 months from the finalization of this ZIP has
|
||||
passed, in order to allow client developers to release new versions, and users
|
||||
of old clients to upgrade.
|
||||
|
||||
|
||||
References
|
||||
==========
|
||||
|
|
@ -244,3 +272,4 @@ References
|
|||
.. [#bip-0070] `BIP 70: Payment Protocol <https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki>`_
|
||||
.. [#base58check] `Base58Check encoding <https://en.bitcoin.it/wiki/Base58Check_encoding>`_
|
||||
.. [#base64url] `RFC 4648 section 5: Base64 Encoding with URL and Filename Safe Alphabet <https://tools.ietf.org/html/rfc4648#section-5>`_
|
||||
.. [#saplingoutputs] `Restrictions on number of outputs in Zcash transactions <https://zips.z.cash/protocol/protocol.pdf#saplingbalance>`_
|
||||
|
|
|
|||
Loading…
Reference in New Issue