ReadTheDocs formatted documentation

.readthedocs.yml

@@ -0,0 +1,11 @@
+
+version: 2
+
+sphinx:
+  configuration: doc/conf.py
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+  install:
+    - requirements: doc/.sphinx/requirements.txt

README.rst

@@ -0,0 +1,135 @@
+.. raw:: html
+
+   <p align="center">
+       <a href='https://cardano.readthedocs.io/projects/adrestia/en/latest/?badge=latest'><img src='https://readthedocs.org/projects/cardano-adrestia/badge/?version=latest' alt='Documentation Status' /></a>
+   </p>
+
+Adrestia is a collection of products which makes it easier to integrate
+with Cardano. It comes in different flavours: SDK or high-level APIs.
+Depending on the use-cases you have and the control that you seek, you
+may use any of the components below.
+
+Components
+==========
+
+APIs
+----
+
++--------------------+--------------+----------+-------------+-----------------+
+|    name / link     | description  |  Byron   | Jörmungandr |     Shelley     |
++====================+==============+==========+=============+=================+
+| `cardano-wallet`_  | JSON/REST    | **DONE** | **DONE**    | **IN PROGRESS** |
+|                    | API for      |          |             |                 |
+|                    | managing     |          |             |                 |
+|                    | UTxOs in HD  |          |             |                 |
+|                    | wallets      |          |             |                 |
++--------------------+--------------+----------+-------------+-----------------+
+| `cardano-rest`_    | JSON/HTTP    | **DONE** | **X**       | **IN PROGRESS** |
+|                    | API for      |          |             |                 |
+|                    | browsing     |          |             |                 |
+|                    | on-chain     |          |             |                 |
+|                    | data         |          |             |                 |
++--------------------+--------------+----------+-------------+-----------------+
+| `cardano-graphql`_ |              | **DONE** | **X**       | **IN PROGRESS** |
+|                    | GraphQL/HTTP |          |             |                 |
+|                    | API for      |          |             |                 |
+|                    | browsing     |          |             |                 |
+|                    | on-chain     |          |             |                 |
+|                    | data         |          |             |                 |
++--------------------+--------------+----------+-------------+-----------------+
+
+SDK
+---
+
++------------------------------+----------------+-----------------+---------------------+
+|         Name / Link          |  Description   |     Haskell     |     JavaScript      |
++==============================+================+=================+=====================+
+| `bech32`_                    | Human-friendly | **DONE**        | `bitcoinjs bech32`_ |
+|                              | Bech32 address |                 |                     |
+|                              | encoding       |                 |                     |
++------------------------------+----------------+-----------------+---------------------+
+| `cardano-addresses`_         | Addresses and  | **DONE**        | **IN PROGRESS**     |
+|                              | mnemonic       |                 |                     |
+|                              | manipulation & |                 |                     |
+|                              | derivations    |                 |                     |
++------------------------------+----------------+-----------------+---------------------+
+| `cardano-coin-selection`_    | Coin selection | **DONE**        | **IN PROGRESS**     |
+|                              | and fee        |                 |                     |
+|                              | balancing      |                 |                     |
+|                              | algorithms     |                 |                     |
++------------------------------+----------------+-----------------+---------------------+
+| `cardano-launcher`_          | Shelley        | **X**           | **DONE**            |
+|                              | cardano-node   |                 |                     |
+|                              | and            |                 |                     |
+|                              | cardano-wallet |                 |                     |
+|                              | launcher for   |                 |                     |
+|                              | NodeJS         |                 |                     |
+|                              | applications   |                 |                     |
++------------------------------+----------------+-----------------+---------------------+
+| `cardano-serialization-lib`_ | Binary         | **IN PROGRESS** | **IN PROGRESS**     |
+|                              | serialization  |                 |                     |
+|                              | of on-chain    |                 |                     |
+|                              | data types     |                 |                     |
++------------------------------+----------------+-----------------+---------------------+
+| `cardano-transactions`_      | Transaction    | **DONE**        | **IN PROGRESS**     |
+|                              | construction   |                 |                     |
+|                              | and signing    |                 |                     |
++------------------------------+----------------+-----------------+---------------------+
+
+Formal Specifications
+---------------------
+
++------------------------------+-------------------------------------------------+
+|         Name / Link          |                   Description                   |
++==============================+=================================================+
+| `utxo-wallet-specification`_ | Formal specification for a UTxO wallet encoding |
++------------------------------+-------------------------------------------------+
+
+Internal
+--------
+
+.. warning::
+    Here be dragons. These tools are used internally by other tools and does not benefit from the same care in documentation thanother tools above.
+
+
++-------------------+--------------------------------------------------+
+|    name / link    |                   description                    |
++===================+==================================================+
+| `cardano-js`_     | (experimental) Cardano primitives for ECMAScript |
+|                   | applications                                     |
++-------------------+--------------------------------------------------+
+| `cardano-js-sdk`_ | (experimental) Cardano SDK for ECMAScript        |
+|                   | applications                                     |
++-------------------+--------------------------------------------------+
+| `persistent`_     | Fork of the persistent Haskell library           |
+|                   | maintained for cardano-wallet                    |
++-------------------+--------------------------------------------------+
+
+Building the Documentation
+--------------------------
+
+This documentation may be built with Sphinx:
+
+.. code-block:: console
+  :linenos:
+
+  python -m pip install --upgrade --no-cache-dir pip
+  python -m pip install --upgrade --no-cache-dir Pygments==2.3.1 setuptools==41.0.1 docutils==0.14 mock==1.0.1 pillow==5.4.1 alabaster>=0.7,<0.8,!=0.7.5 commonmark==0.8.1 recommonmark==0.5.0 sphinx<2 sphinx-rtd-theme<0.5 readthedocs-sphinx-ext<1.1
+  python -m pip install --exists-action=w --no-cache-dir -r doc/.sphinx/requirements.txt
+  sphinx-build -T -E -b readthedocs -d _build/doctrees-readthedocs -D language=en . _build/html 
+
+
+.. _cardano-wallet: https://github.com/input-output-hk/cardano-wallet
+.. _cardano-rest: https://github.com/input-output-hk/cardano-rest
+.. _cardano-graphql: https://github.com/input-output-hk/cardano-graphql
+.. _bech32: https://github.com/input-output-hk/bech32
+.. _bitcoinjs bech32: https://github.com/bitcoinjs/bech32
+.. _cardano-addresses: https://github.com/input-output-hk/cardano-addresses
+.. _cardano-coin-selection: https://github.com/input-output-hk/cardano-coin-selection
+.. _cardano-launcher: https://github.com/input-output-hk/cardano-launcher
+.. _cardano-serialization-lib: https://github.com/input-output-hk/cardano-serialization-lib
+.. _cardano-transactions: https://github.com/input-output-hk/cardano-transactions
+.. _utxo-wallet-specification: https://github.com/input-output-hk/utxo-wallet-specification
+.. _cardano-js: https://github.com/input-output-hk/cardano-js
+.. _cardano-js-sdk: https://github.com/input-output-hk/cardano-js-sdk
+.. _persistent: https://github.com/input-output-hk/persistent

doc/.sphinx/requirements.txt

@@ -0,0 +1,31 @@
+Sphinx==3.1.1
+sphinx-intl==2.0.1
+transifex-client==0.13.10
+testresources==2.0.1
+-e git+https://github.com/input-output-hk/sphinx_rtd_theme.git#egg=sphinx_rtd_theme
+recommonmark==0.6
+## The following requirements were added by pip freeze:
+alabaster==0.7.12
+Babel==2.8.0
+certifi==2020.4.5.2
+chardet==3.0.4
+click==7.1.2
+sphinxcontrib-mermaid==0.4.0
+sphinxemoji==0.1.6
+sphinx_markdown_tables==0.0.15
+CommonMark==0.9.1
+docutils==0.16
+future==0.18.2
+idna==2.9
+imagesize==1.2.0
+Jinja2==2.11.2
+jsonpointer==2.0
+jsonref==0.2
+MarkupSafe==1.1.1
+Pygments==2.6.1
+pytz==2020.1
+requests==2.24.0
+six==1.15.0
+snowballstemmer==2.0.0
+sphinxcontrib-websupport==1.2.2
+urllib3==1.25.9

doc/api-reference.md

@@ -0,0 +1,33 @@
+## API reference
+
+### Components
+
+|           id           |                                                                name                                                                |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| cardano\-wallet        | [https://input\-output\-hk\.github\.io/cardano\-wallet/edge](https://input-output-hk.github.io/cardano-wallet/edge)                |
+| cardano\-submit\-api   | [https://input\-output\-hk\.github\.io/cardano\-rest/submit\-api/](https://input-output-hk.github.io/cardano-rest/submit-api/)     |
+| cardano\-explorer\-api | [https://input\-output\-hk\.github\.io/cardano\-rest/explorer\-api/](https://input-output-hk.github.io/cardano-rest/explorer-api/) |
+| cardano\-graphql       | Available soon                                                                                                                     |
+
+**About cardano-wallet**
+
+Cardano-wallet comes with a command-line interface (CLI) that can be used as a quick alternative to cURL or wget to interact with a server running on localhost. Every endpoint of the API is mapped to a corresponding command that often offers a better user experience than directly interacting with the API as a human (API are for programs, command-lines are for humans).
+
+For example, restoring a wallet goes normally through POST /byron-wallets, or can be done interactively with:
+
+`$ cardano-wallet wallet create MyWallet`
+
+The CLI also provides some useful helpers, such as a command to generate mnemonic sentences, or doing key derivation. For more details, see the wallet command-line user manual.
+
+### Libraries
+
+|         Library          |                                                                   Haskell                                                                    |                     JavaScript                     |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| cardano\-addresses       | [https://input\-output\-hk\.github\.io/cardano\-addresses/haddock/](https://input-output-hk.github.io/cardano-addresses/haddock/)            | Soon available\.                                   |
+| cardano\-transactions    | [https://input\-output\-hk\.github\.io/cardano\-transactions/haddock/](https://input-output-hk.github.io/cardano-transactions/haddock/)      | Soon available\.                                   |
+| cardano\-coin\-selection | [https://input\-output\-hk\.github\.io/cardano\-coin\-selection/haddock/](https://input-output-hk.github.io/cardano-coin-selection/haddock/) | Soon available\.                                   |
+| bech32                   | [https://input\-output\-hk\.github\.io/bech32/haddock/](https://input-output-hk.github.io/bech32/haddock/)                                   | [See bech32](https://github\.com/bitcoinjs/bech32) |
+
+**About cardano-transactions**
+
+In addition to the low-level library, cardano-transactions also provides a CLI (cardano-tx) to construct transactions directly in the terminal. Check out the repository's documentation and examples to see example usage.

doc/architecture.md

@@ -0,0 +1,63 @@
+Architecture
+============
+
+## High-Level Diagram
+
+![High-Level Diagram](high-level-diagram.svg)
+
+## Components
+
+### [cardano-node][cardano-node]
+
+The core [cardano-node][cardano-node], which will support Ouroboros Praos.
+
+**Supported environments**
+-   Linux (64-bit)
+-   MacOS (64-bit)
+-   Windows (64-bit)
+-   Docker
+
+### [cardano-db-sync](https://github.com/input-output-hk/cardano-db-sync)
+
+A necessary middleware to power both [cardano-rest][cardano-rest] and [cardano-graphql][cardano-graphql]. This middleware stores blockchain data fetched from [cardano-node][cardano-node] in an intermediate database to enable higher-level interfaces for blockchain exploration.
+
+**Supported environments**
+-   Linux (64-bit)
+-   MacOS (64-bit)
+-   Docker
+
+### [cardano-wallet](https://github.com/input-output-hk/cardano-wallet)
+
+This is a HTTP REST API recommended for third-party wallets and small exchanges that do not want to manage UTxOs for transactions themselves. Use this API to send and receive payments from hierarchical deterministic wallets on the Cardano blockchain via HTTP REST or a command-line interface.
+
+**Supported environments**
+-   Linux (64-bit)
+-   MacOS (64-bit)
+-   Windows (64-bit)
+-   Docker
+
+### [cardano-rest](https://github.com/input-output-hk/cardano-rest)
+
+cardano-rest is made of two HTTP APIs used to retrieve transactions, addresses, and time periods (epochs and slots) from the [cardano-db-sync](https://github.com/input-output-hk/cardano-db-sync) component and submit an already serialized transaction to the network using [cardano-explorer-api](https://github.com/input-output-hk/cardano-rest) & [cardano-submit-api](https://github.com/input-output-hk/cardano-rest) respectively. The [cardano-submit-api](https://github.com/input-output-hk/cardano-rest) uses the same API as the [cardano-sl:explorer](https://cardanodocs.com/technical/explorer/api/), to ease migration from already integrated clients. New integration should however look into [cardano-graphql](https://github.com/input-output-hk/cardano-graphql).
+
+**Supported environmentss**
+-   Linux (64-bit)
+-   MacOS (64-bit)
+-   Docker
+
+### [cardano-graphql](https://github.com/input-output-hk/cardano-graphql)
+
+HTTP GraphQL API for Cardano. This is a more flexible alternative for blockchain exploration than [cardano-rest](https://github.com/input-output-hk/cardano-rest).
+
+**Supported environments**
+-   Linux (64-bit)
+-   MacOS (64-bit)
+-   Docker
+
+## Choosing the right component
+
+![Choosing the right component](choosing-the-right-component.png)
+
+## Notes
+
+See also [input-output-hk/adrestia][adrestia].

doc/choosing-the-right-component.mmd

@@ -0,0 +1,16 @@
+graph TD
+QMakeTx{Do you need to <br/> make transactions?} 
+QManageUTxO{Do you want to <br/>implement your own wallet?}
+QAlreadyIntegrated{Do you already have<br/>an integration with<br/>cardano-sl?}
+
+GraphQL{cardano-graphql}
+Rest{cardano-rest}
+SDK{SDK}
+Wallet{cardano-wallet}
+
+QMakeTx-->|yes| QManageUTxO
+QMakeTx-->|no| QAlreadyIntegrated
+QAlreadyIntegrated-->|yes| Rest
+QAlreadyIntegrated-->|no| GraphQL
+QManageUTxO-->|yes| SDK
+QManageUTxO-->|no| Wallet

doc/common-use-cases/how-to-create-a-wallet.md

@@ -0,0 +1,26 @@
+How to create a wallet
+======================
+
+> **Difficulty**:  beginner
+
+**Requires:**
+- 📦 cardano-wallet >= `v2020-03-11`
+
+
+The easiest and most common way of managing your funds on the Cardano blockchain is through a [hierarchical-deterministic-wallets](../key-concepts/hierarchical-deterministic-wallets.md). You can create a wallet using the following endpoint of [cardano-wallet](https://github.com/input-output-hk/cardano-wallet):
+
+[`POST /byron-wallets`](https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/postByronWallet)
+
+There are several wallet types available:
+ - Random
+ - Icarus
+ - Trezor
+ - Ledger
+
+The basic difference is that, for a `random` wallet, the user needs to [create new address](how-to-create-addresses.md) manually, whereas for sequential wallets -like `icarus`, `trezor` and `ledger`-, the addresses are [generated automatically](how-to-create-addresses.md#listing-addresses-in-sequential-wallets) by the wallet.
+
+> **DANGER**:  Note that `random` wallets are considered **deprecated** and should _not_ be used by new applications.
+
+Note also that a single `cardano-wallet` server can operate many wallets.
+
+See more on [HD wallets](../key-concepts/hierarchical-deterministic-wallets.md) and [addresses](../key-concepts/addresses-byron.md).

doc/common-use-cases/how-to-create-addresses.md

@@ -0,0 +1,46 @@
+How to "create" addresses
+=========================
+
+> **Difficulty:**:  beginner
+
+**Requires:**
+- 📦 cardano-wallet >= `v2020-04-01`
+
+You can manage your funds once you have a wallet. To receive a transaction, provide the sender with an address associated with your wallet.
+
+## Random wallets (Legacy Byron)
+
+Address creation is only allowed for wallets using random derivation. These are the legacy wallets from _cardano-sl_.
+
+For `random` wallets, you need to invoke the following wallet endpoint to create new addresses:
+
+[`POST /byron-wallets/{walletId}/addresses`](https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/createAddress)
+
+Another endpoint can be used to list existing addresses.
+
+[`GET /byron-wallets/{walletId}/addresses`](https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/listByronAddresses)
+
+
+> **INFO**:
+Alternatively, these endpoints can also be reached from the command-line:
+
+```
+$ cardano-wallet address create WALLET_ID
+$ cardano-wallet address list WALLET_ID
+```
+
+## Sequential wallets (Icarus & Shelley)
+
+Since Icarus, wallets use sequential derivation, which must satisfy very specific rules: a wallet is not allowed to use addresses beyond a certain limit before previously generated addresses have been used, for example. This means that, at a given point in a time, a wallet has both a minimum and a maximum number of possible unused addresses. By default, the maximum number of consecutive unused addresses is set to `20`.
+
+Address management is entirely done by the server, and users are not allowed to interfere with them. The list of available addresses can be fetched from the server at any time via:
+
+[`GET /byron-wallets/{walletId}/addresses`](https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/listByronAddresses)
+
+This list automatically expands when new addresses become available, so there's always `address_pool_gap` consecutive unused addresses available (where `address_pool_gap` can be configured when a wallet is first restored / created).
+
+> **HINT**:  Alternatively, this endpoint can also be reached from the command-line:
+
+```
+$ cardano-wallet address list WALLET_ID
+```