lightwalletd/docs/rtd/index.html

1008 lines
29 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html>
<head>
<title>Protocol Documentation</title>
<meta charset="UTF-8">
<link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Ubuntu:400,700,400italic"/>
<style>
body {
width: 60em;
margin: 1em auto;
color: #222;
font-family: "Ubuntu", sans-serif;
padding-bottom: 4em;
}
h1 {
font-weight: normal;
border-bottom: 1px solid #aaa;
padding-bottom: 0.5ex;
}
h2 {
border-bottom: 1px solid #aaa;
padding-bottom: 0.5ex;
margin: 1.5em 0;
}
h3 {
font-weight: normal;
border-bottom: 1px solid #aaa;
padding-bottom: 0.5ex;
}
a {
text-decoration: none;
color: #567e25;
}
table {
width: 100%;
font-size: 80%;
border-collapse: collapse;
}
thead {
font-weight: 700;
background-color: #dcdcdc;
}
tbody tr:nth-child(even) {
background-color: #fbfbfb;
}
td {
border: 1px solid #ccc;
padding: 0.5ex 2ex;
}
td p {
text-indent: 1em;
margin: 0;
}
td p:nth-child(1) {
text-indent: 0;
}
.field-table td:nth-child(1) {
width: 10em;
}
.field-table td:nth-child(2) {
width: 10em;
}
.field-table td:nth-child(3) {
width: 6em;
}
.field-table td:nth-child(4) {
width: auto;
}
.extension-table td:nth-child(1) {
width: 10em;
}
.extension-table td:nth-child(2) {
width: 10em;
}
.extension-table td:nth-child(3) {
width: 10em;
}
.extension-table td:nth-child(4) {
width: 5em;
}
.extension-table td:nth-child(5) {
width: auto;
}
.enum-table td:nth-child(1) {
width: 10em;
}
.enum-table td:nth-child(2) {
width: 10em;
}
.enum-table td:nth-child(3) {
width: auto;
}
.scalar-value-types-table tr {
height: 3em;
}
#toc-container ul {
list-style-type: none;
padding-left: 1em;
line-height: 180%;
margin: 0;
}
#toc > li > a {
font-weight: bold;
}
.file-heading {
width: 100%;
display: table;
border-bottom: 1px solid #aaa;
margin: 4em 0 1.5em 0;
}
.file-heading h2 {
border: none;
display: table-cell;
}
.file-heading a {
text-align: right;
display: table-cell;
}
.badge {
width: 1.6em;
height: 1.6em;
display: inline-block;
line-height: 1.6em;
text-align: center;
font-weight: bold;
font-size: 60%;
color: #89ba48;
background-color: #dff0c8;
margin: 0.5ex 1em 0.5ex -1em;
border: 1px solid #fbfbfb;
border-radius: 1ex;
}
</style>
<link rel="stylesheet" type="text/css" href="stylesheet.css"/>
</head>
<body>
<h1 id="title">Protocol Documentation</h1>
<h2>Table of Contents</h2>
<div id="toc-container">
<ul id="toc">
<li>
<a href="#compact_formats.proto">compact_formats.proto</a>
<ul>
<li>
<a href="#cash.z.wallet.sdk.rpc.CompactBlock"><span class="badge">M</span>CompactBlock</a>
</li>
<li>
<a href="#cash.z.wallet.sdk.rpc.CompactOutput"><span class="badge">M</span>CompactOutput</a>
</li>
<li>
<a href="#cash.z.wallet.sdk.rpc.CompactSpend"><span class="badge">M</span>CompactSpend</a>
</li>
<li>
<a href="#cash.z.wallet.sdk.rpc.CompactTx"><span class="badge">M</span>CompactTx</a>
</li>
</ul>
</li>
<li>
<a href="#service.proto">service.proto</a>
<ul>
<li>
<a href="#cash.z.wallet.sdk.rpc.BlockID"><span class="badge">M</span>BlockID</a>
</li>
<li>
<a href="#cash.z.wallet.sdk.rpc.BlockRange"><span class="badge">M</span>BlockRange</a>
</li>
<li>
<a href="#cash.z.wallet.sdk.rpc.ChainSpec"><span class="badge">M</span>ChainSpec</a>
</li>
<li>
<a href="#cash.z.wallet.sdk.rpc.Duration"><span class="badge">M</span>Duration</a>
</li>
<li>
<a href="#cash.z.wallet.sdk.rpc.Empty"><span class="badge">M</span>Empty</a>
</li>
<li>
<a href="#cash.z.wallet.sdk.rpc.LightdInfo"><span class="badge">M</span>LightdInfo</a>
</li>
<li>
<a href="#cash.z.wallet.sdk.rpc.PingResponse"><span class="badge">M</span>PingResponse</a>
</li>
<li>
<a href="#cash.z.wallet.sdk.rpc.RawTransaction"><span class="badge">M</span>RawTransaction</a>
</li>
<li>
<a href="#cash.z.wallet.sdk.rpc.SendResponse"><span class="badge">M</span>SendResponse</a>
</li>
<li>
<a href="#cash.z.wallet.sdk.rpc.TransparentAddressBlockFilter"><span class="badge">M</span>TransparentAddressBlockFilter</a>
</li>
<li>
<a href="#cash.z.wallet.sdk.rpc.TxFilter"><span class="badge">M</span>TxFilter</a>
</li>
<li>
<a href="#cash.z.wallet.sdk.rpc.CompactTxStreamer"><span class="badge">S</span>CompactTxStreamer</a>
</li>
</ul>
</li>
<li><a href="#scalar-value-types">Scalar Value Types</a></li>
</ul>
</div>
<div class="file-heading">
<h2 id="compact_formats.proto">compact_formats.proto</h2><a href="#title">Top</a>
</div>
<p></p>
<h3 id="cash.z.wallet.sdk.rpc.CompactBlock">CompactBlock</h3>
<p>CompactBlock is a packaging of ONLY the data from a block that's needed to:</p><p>1. Detect a payment to your shielded Sapling address</p><p>2. Detect a spend of your shielded Sapling notes</p><p>3. Update your witnesses to generate new Sapling spend proofs.</p>
<table class="field-table">
<thead>
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<td>protoVersion</td>
<td><a href="#uint32">uint32</a></td>
<td></td>
<td><p>the version of this wire format, for storage </p></td>
</tr>
<tr>
<td>height</td>
<td><a href="#uint64">uint64</a></td>
<td></td>
<td><p>the height of this block </p></td>
</tr>
<tr>
<td>hash</td>
<td><a href="#bytes">bytes</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>prevHash</td>
<td><a href="#bytes">bytes</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>time</td>
<td><a href="#uint32">uint32</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>header</td>
<td><a href="#bytes">bytes</a></td>
<td></td>
<td><p>(hash, prevHash, and time) OR (full header) </p></td>
</tr>
<tr>
<td>vtx</td>
<td><a href="#cash.z.wallet.sdk.rpc.CompactTx">CompactTx</a></td>
<td>repeated</td>
<td><p>compact transactions from this block </p></td>
</tr>
</tbody>
</table>
<h3 id="cash.z.wallet.sdk.rpc.CompactOutput">CompactOutput</h3>
<p></p>
<table class="field-table">
<thead>
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<td>cmu</td>
<td><a href="#bytes">bytes</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>epk</td>
<td><a href="#bytes">bytes</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>ciphertext</td>
<td><a href="#bytes">bytes</a></td>
<td></td>
<td><p> </p></td>
</tr>
</tbody>
</table>
<h3 id="cash.z.wallet.sdk.rpc.CompactSpend">CompactSpend</h3>
<p></p>
<table class="field-table">
<thead>
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<td>nf</td>
<td><a href="#bytes">bytes</a></td>
<td></td>
<td><p> </p></td>
</tr>
</tbody>
</table>
<h3 id="cash.z.wallet.sdk.rpc.CompactTx">CompactTx</h3>
<p>Index and hash will allow the receiver to call out to chain</p><p>explorers or other data structures to retrieve more information</p><p>about this transaction.</p>
<table class="field-table">
<thead>
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<td>index</td>
<td><a href="#uint64">uint64</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>hash</td>
<td><a href="#bytes">bytes</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>fee</td>
<td><a href="#uint32">uint32</a></td>
<td></td>
<td><p>The transaction fee: present if server can provide. In the case of a
stateless server and a transaction with transparent inputs, this will be
unset because the calculation requires reference to prior transactions.
in a pure-Sapling context, the fee will be calculable as:
valueBalance &#43; (sum(vPubNew) - sum(vPubOld) - sum(tOut)) </p></td>
</tr>
<tr>
<td>spends</td>
<td><a href="#cash.z.wallet.sdk.rpc.CompactSpend">CompactSpend</a></td>
<td>repeated</td>
<td><p> </p></td>
</tr>
<tr>
<td>outputs</td>
<td><a href="#cash.z.wallet.sdk.rpc.CompactOutput">CompactOutput</a></td>
<td>repeated</td>
<td><p> </p></td>
</tr>
</tbody>
</table>
<div class="file-heading">
<h2 id="service.proto">service.proto</h2><a href="#title">Top</a>
</div>
<p></p>
<h3 id="cash.z.wallet.sdk.rpc.BlockID">BlockID</h3>
<p>A BlockID message contains identifiers to select a block: a height or a</p><p>hash. Specification by hash is not implemented, but may be in the future.</p>
<table class="field-table">
<thead>
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<td>height</td>
<td><a href="#uint64">uint64</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>hash</td>
<td><a href="#bytes">bytes</a></td>
<td></td>
<td><p> </p></td>
</tr>
</tbody>
</table>
<h3 id="cash.z.wallet.sdk.rpc.BlockRange">BlockRange</h3>
<p>BlockRange specifies a series of blocks from start to end inclusive.</p><p>Both BlockIDs must be heights; specification by hash is not yet supported.</p>
<table class="field-table">
<thead>
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<td>start</td>
<td><a href="#cash.z.wallet.sdk.rpc.BlockID">BlockID</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>end</td>
<td><a href="#cash.z.wallet.sdk.rpc.BlockID">BlockID</a></td>
<td></td>
<td><p> </p></td>
</tr>
</tbody>
</table>
<h3 id="cash.z.wallet.sdk.rpc.ChainSpec">ChainSpec</h3>
<p>Chainspec is a placeholder to allow specification of a particular chain fork.</p>
<h3 id="cash.z.wallet.sdk.rpc.Duration">Duration</h3>
<p>Duration is currently used only for testing, so that the Ping rpc</p><p>can simulate a delay, to create many simultaneous connections. Units</p><p>are microseconds.</p>
<table class="field-table">
<thead>
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<td>intervalUs</td>
<td><a href="#int64">int64</a></td>
<td></td>
<td><p> </p></td>
</tr>
</tbody>
</table>
<h3 id="cash.z.wallet.sdk.rpc.Empty">Empty</h3>
<p>Empty is for gRPCs that take no arguments, currently only GetLightdInfo.</p>
<h3 id="cash.z.wallet.sdk.rpc.LightdInfo">LightdInfo</h3>
<p>LightdInfo returns various information about this lightwalletd instance</p><p>and the state of the blockchain.</p>
<table class="field-table">
<thead>
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<td>version</td>
<td><a href="#string">string</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>vendor</td>
<td><a href="#string">string</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>taddrSupport</td>
<td><a href="#bool">bool</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>chainName</td>
<td><a href="#string">string</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>saplingActivationHeight</td>
<td><a href="#uint64">uint64</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>consensusBranchId</td>
<td><a href="#string">string</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>blockHeight</td>
<td><a href="#uint64">uint64</a></td>
<td></td>
<td><p> </p></td>
</tr>
</tbody>
</table>
<h3 id="cash.z.wallet.sdk.rpc.PingResponse">PingResponse</h3>
<p>PingResponse is used to indicate concurrency, how many Ping rpcs</p><p>are executing upon entry and upon exit (after the delay).</p>
<table class="field-table">
<thead>
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<td>entry</td>
<td><a href="#int64">int64</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>exit</td>
<td><a href="#int64">int64</a></td>
<td></td>
<td><p> </p></td>
</tr>
</tbody>
</table>
<h3 id="cash.z.wallet.sdk.rpc.RawTransaction">RawTransaction</h3>
<p>RawTransaction contains the complete transaction data. It also optionally includes </p><p>the block height in which the transaction was included</p>
<table class="field-table">
<thead>
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<td>data</td>
<td><a href="#bytes">bytes</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>height</td>
<td><a href="#uint64">uint64</a></td>
<td></td>
<td><p> </p></td>
</tr>
</tbody>
</table>
<h3 id="cash.z.wallet.sdk.rpc.SendResponse">SendResponse</h3>
<p>A SendResponse encodes an error code and a string. It is currently used</p><p>only by SendTransaction(). If error code is zero, the operation was</p><p>successful; if non-zero, it and the message specify the failure.</p>
<table class="field-table">
<thead>
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<td>errorCode</td>
<td><a href="#int32">int32</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>errorMessage</td>
<td><a href="#string">string</a></td>
<td></td>
<td><p> </p></td>
</tr>
</tbody>
</table>
<h3 id="cash.z.wallet.sdk.rpc.TransparentAddressBlockFilter">TransparentAddressBlockFilter</h3>
<p>TransparentAddressBlockFilter restricts the results to the given address</p><p>or block range.</p>
<table class="field-table">
<thead>
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<td>address</td>
<td><a href="#string">string</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>range</td>
<td><a href="#cash.z.wallet.sdk.rpc.BlockRange">BlockRange</a></td>
<td></td>
<td><p> </p></td>
</tr>
</tbody>
</table>
<h3 id="cash.z.wallet.sdk.rpc.TxFilter">TxFilter</h3>
<p>A TxFilter contains the information needed to identify a particular</p><p>transaction: either a block and an index, or a direct transaction hash.</p><p>Currently, only specification by hash is supported.</p>
<table class="field-table">
<thead>
<tr><td>Field</td><td>Type</td><td>Label</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<td>block</td>
<td><a href="#cash.z.wallet.sdk.rpc.BlockID">BlockID</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>index</td>
<td><a href="#uint64">uint64</a></td>
<td></td>
<td><p> </p></td>
</tr>
<tr>
<td>hash</td>
<td><a href="#bytes">bytes</a></td>
<td></td>
<td><p> </p></td>
</tr>
</tbody>
</table>
<h3 id="cash.z.wallet.sdk.rpc.CompactTxStreamer">CompactTxStreamer</h3>
<p></p>
<table class="enum-table">
<thead>
<tr><td>Method Name</td><td>Request Type</td><td>Response Type</td><td>Description</td></tr>
</thead>
<tbody>
<tr>
<td>GetLatestBlock</td>
<td><a href="#cash.z.wallet.sdk.rpc.ChainSpec">ChainSpec</a></td>
<td><a href="#cash.z.wallet.sdk.rpc.BlockID">BlockID</a></td>
<td><p>Compact Blocks</p></td>
</tr>
<tr>
<td>GetBlock</td>
<td><a href="#cash.z.wallet.sdk.rpc.BlockID">BlockID</a></td>
<td><a href="#cash.z.wallet.sdk.rpc.CompactBlock">CompactBlock</a></td>
<td><p></p></td>
</tr>
<tr>
<td>GetBlockRange</td>
<td><a href="#cash.z.wallet.sdk.rpc.BlockRange">BlockRange</a></td>
<td><a href="#cash.z.wallet.sdk.rpc.CompactBlock">CompactBlock</a> stream</td>
<td><p></p></td>
</tr>
<tr>
<td>GetTransaction</td>
<td><a href="#cash.z.wallet.sdk.rpc.TxFilter">TxFilter</a></td>
<td><a href="#cash.z.wallet.sdk.rpc.RawTransaction">RawTransaction</a></td>
<td><p>Transactions</p></td>
</tr>
<tr>
<td>SendTransaction</td>
<td><a href="#cash.z.wallet.sdk.rpc.RawTransaction">RawTransaction</a></td>
<td><a href="#cash.z.wallet.sdk.rpc.SendResponse">SendResponse</a></td>
<td><p></p></td>
</tr>
<tr>
<td>GetAddressTxids</td>
<td><a href="#cash.z.wallet.sdk.rpc.TransparentAddressBlockFilter">TransparentAddressBlockFilter</a></td>
<td><a href="#cash.z.wallet.sdk.rpc.RawTransaction">RawTransaction</a> stream</td>
<td><p>t-Address support</p></td>
</tr>
<tr>
<td>GetLightdInfo</td>
<td><a href="#cash.z.wallet.sdk.rpc.Empty">Empty</a></td>
<td><a href="#cash.z.wallet.sdk.rpc.LightdInfo">LightdInfo</a></td>
<td><p>Misc</p></td>
</tr>
<tr>
<td>Ping</td>
<td><a href="#cash.z.wallet.sdk.rpc.Duration">Duration</a></td>
<td><a href="#cash.z.wallet.sdk.rpc.PingResponse">PingResponse</a></td>
<td><p></p></td>
</tr>
</tbody>
</table>
<h2 id="scalar-value-types">Scalar Value Types</h2>
<table class="scalar-value-types-table">
<thead>
<tr><td>.proto Type</td><td>Notes</td><td>C++ Type</td><td>Java Type</td><td>Python Type</td></tr>
</thead>
<tbody>
<tr id="double">
<td>double</td>
<td></td>
<td>double</td>
<td>double</td>
<td>float</td>
</tr>
<tr id="float">
<td>float</td>
<td></td>
<td>float</td>
<td>float</td>
<td>float</td>
</tr>
<tr id="int32">
<td>int32</td>
<td>Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint32 instead.</td>
<td>int32</td>
<td>int</td>
<td>int</td>
</tr>
<tr id="int64">
<td>int64</td>
<td>Uses variable-length encoding. Inefficient for encoding negative numbers if your field is likely to have negative values, use sint64 instead.</td>
<td>int64</td>
<td>long</td>
<td>int/long</td>
</tr>
<tr id="uint32">
<td>uint32</td>
<td>Uses variable-length encoding.</td>
<td>uint32</td>
<td>int</td>
<td>int/long</td>
</tr>
<tr id="uint64">
<td>uint64</td>
<td>Uses variable-length encoding.</td>
<td>uint64</td>
<td>long</td>
<td>int/long</td>
</tr>
<tr id="sint32">
<td>sint32</td>
<td>Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.</td>
<td>int32</td>
<td>int</td>
<td>int</td>
</tr>
<tr id="sint64">
<td>sint64</td>
<td>Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.</td>
<td>int64</td>
<td>long</td>
<td>int/long</td>
</tr>
<tr id="fixed32">
<td>fixed32</td>
<td>Always four bytes. More efficient than uint32 if values are often greater than 2^28.</td>
<td>uint32</td>
<td>int</td>
<td>int</td>
</tr>
<tr id="fixed64">
<td>fixed64</td>
<td>Always eight bytes. More efficient than uint64 if values are often greater than 2^56.</td>
<td>uint64</td>
<td>long</td>
<td>int/long</td>
</tr>
<tr id="sfixed32">
<td>sfixed32</td>
<td>Always four bytes.</td>
<td>int32</td>
<td>int</td>
<td>int</td>
</tr>
<tr id="sfixed64">
<td>sfixed64</td>
<td>Always eight bytes.</td>
<td>int64</td>
<td>long</td>
<td>int/long</td>
</tr>
<tr id="bool">
<td>bool</td>
<td></td>
<td>bool</td>
<td>boolean</td>
<td>boolean</td>
</tr>
<tr id="string">
<td>string</td>
<td>A string must always contain UTF-8 encoded or 7-bit ASCII text.</td>
<td>string</td>
<td>String</td>
<td>str/unicode</td>
</tr>
<tr id="bytes">
<td>bytes</td>
<td>May contain any arbitrary sequence of bytes.</td>
<td>string</td>
<td>ByteString</td>
<td>str</td>
</tr>
</tbody>
</table>
</body>
</html>