diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..5853a2b --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..32a733e --- /dev/null +++ b/README.rst @@ -0,0 +1,135 @@ +.. raw:: html + +

+ Documentation Status +

+ +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 diff --git a/doc/.sphinx/cardano-logo.png b/doc/.sphinx/cardano-logo.png new file mode 100755 index 0000000..4e88af1 Binary files /dev/null and b/doc/.sphinx/cardano-logo.png differ diff --git a/doc/.sphinx/requirements.txt b/doc/.sphinx/requirements.txt new file mode 100644 index 0000000..271738b --- /dev/null +++ b/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 diff --git a/doc/api-reference.md b/doc/api-reference.md new file mode 100644 index 0000000..944cb94 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/architecture.md b/doc/architecture.md new file mode 100644 index 0000000..1693bc1 --- /dev/null +++ b/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]. diff --git a/doc/choosing-the-right-component.mmd b/doc/choosing-the-right-component.mmd new file mode 100644 index 0000000..1445ac7 --- /dev/null +++ b/doc/choosing-the-right-component.mmd @@ -0,0 +1,16 @@ +graph TD +QMakeTx{Do you need to
make transactions?} +QManageUTxO{Do you want to
implement your own wallet?} +QAlreadyIntegrated{Do you already have
an integration with
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 \ No newline at end of file diff --git a/doc/choosing-the-right-component.png b/doc/choosing-the-right-component.png new file mode 100644 index 0000000..6d85b79 Binary files /dev/null and b/doc/choosing-the-right-component.png differ diff --git a/doc/common-use-cases/how-to-create-a-wallet.md b/doc/common-use-cases/how-to-create-a-wallet.md new file mode 100644 index 0000000..1752ff5 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/doc/common-use-cases/how-to-create-addresses.md b/doc/common-use-cases/how-to-create-addresses.md new file mode 100644 index 0000000..b4db67c --- /dev/null +++ b/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 +``` diff --git a/user-guide/content/docs/common-use-cases/how-to-make-a-transaction.md b/doc/common-use-cases/how-to-make-a-transaction.md similarity index 51% rename from user-guide/content/docs/common-use-cases/how-to-make-a-transaction.md rename to doc/common-use-cases/how-to-make-a-transaction.md index d4cf713..7abebf6 100644 --- a/user-guide/content/docs/common-use-cases/how-to-make-a-transaction.md +++ b/doc/common-use-cases/how-to-make-a-transaction.md @@ -1,53 +1,38 @@ ---- -weight: 4 -title: How to make a transaction ---- -{{}} +How to make a transaction +========================= -{{}} -{{}} -**Difficulty:** beginner +> **Difficulty:**: beginner **Requires:** - 📦 cardano-wallet >= `v2020-04-01` -{{}} Assuming you have already created a wallet, you can send a transaction by using the following endpoint: [`POST /v2/byron-wallets/{walletId}/transactions`](https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/postByronTransaction) -Behind the scene, the wallet engine will select necessary inputs from the wallet, generate a change address within the wallet, sign and submit the transaction. A transaction can have multiple outputs, possibly to the same address. Note that in Byron, addresses are necessarily base58-encoded (as an enforced convention). +The wallet engine will select the necessary inputs from the wallet, generate a change address within the wallet, and sign and submit the transaction. A transaction can have multiple outputs, which might be to the same address. In Byron, addresses are necessarily base58-encoded as an enforced convention. -Once submitted through the wallet, a can be tracked via: +Once submitted through the wallet, a transaction can be tracked via: [`GET /v2/byron-wallets/{walletId}/transactions`](https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/listByronTransactions) -Which returns a list of all transactions for this particular wallet. Optional range filters can be provided. A transaction will go through a succession of states, starting as “Pending”. If a transaction stays pending for too long (because rejected by a mempool, or because lost in translation due to multiple chain switches), users may decide to forget it using: +This returns a list of all transactions for this particular wallet. Optional range filters can be provided. A transaction will go through a succession of states, starting as “Pending”. If a transaction stays pending for too long (because rejected by a mempool, or because lost in translation due to multiple chain switches, for example), users can decide to forget it using: [`DELETE /v2/byron-wallets/{walletId}/transactions/{transactionId}`](https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/deleteByronTransaction) -For more information about transactions lifecycle, have a look at this [wiki page](https://github.com/input-output-hk/cardano-wallet/wiki/About-Transactions-Lifecycle). -{{}} +For more information about a transaction's lifecycle, see this [wiki page](https://github.com/input-output-hk/cardano-wallet/wiki/About-Transactions-Lifecycle) - -{{}} - -{{}} -**Difficulty:** advanced +> **Difficulty:** advanced **Requires:** - 📦 cardano-transactions >= `1.0.0` - 📦 cardano-submit-api >= `2.0.0` OR cardano-wallet >= `v2020-04-01` -{{}} -Alternatively, `cardano-wallet` and `cardano-submit-api` allows clients to submit already signed and serialized transactions as a raw bytes blob. This can be done by submitting such serialized data as an `application/octet-stream` to either of: +Alternatively, `cardano-wallet` and `cardano-submit-api` allow clients to submit already signed and serialized transactions as a raw bytes blob. This can be done by submitting such serialized data as an `application/octet-stream` to either: - cardano-wallet: [`POST /v2/proxy/transactions`](https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/postExternalTransaction) - cardano-submit-api: [`POST /api/submit/tx`](https://input-output-hk.github.io/cardano-rest/submit-api/#operation/postTransaction) In this scenario, the server engine will verify that the transaction is structurally well-formed and forward it to its associated node. If the transaction belongs to a known wallet, it will eventually show up in the wallet your wallet. -Such transactions can be constructed from raw data using either [cardano-transactions library or command-line interface](https://github.com/input-output-hk/cardano-transactions). Examples and documentation excerpts are available on the corresponding Github repository. -{{}} - -{{}} +Such transactions can be constructed from raw data using either [cardano-transactions library or command-line interface](https://github.com/input-output-hk/cardano-transactions). Examples and documentation excerpts are available on the corresponding Github repository. \ No newline at end of file diff --git a/user-guide/content/docs/common-use-cases/how-to-manage-wallets.md b/doc/common-use-cases/how-to-manage-wallets.md similarity index 88% rename from user-guide/content/docs/common-use-cases/how-to-manage-wallets.md rename to doc/common-use-cases/how-to-manage-wallets.md index cfbfa47..6b275e2 100644 --- a/user-guide/content/docs/common-use-cases/how-to-manage-wallets.md +++ b/doc/common-use-cases/how-to-manage-wallets.md @@ -1,14 +1,10 @@ ---- -weight: 2 -title: How to manage wallets ---- +How to manage wallets +===================== -{{}} -**Difficulty:** beginner +> **Difficulty:** beginner **Requires:** - 📦 cardano-wallet >= `v2020-04-01` -{{}} Once you created a wallet you can manage it with `cardano-wallet` endpoints. There are several operations available. @@ -27,7 +23,7 @@ Once you created a wallet you can manage it with `cardano-wallet` endpoints. The ### Get wallet UTxO [`GET /v2/byron-wallets/{walletId}/statistics/utxos`](https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/getByronUTxOsStatistics) -See more about [UTxO]({{< ref "utxo.md" >}}). +See more about [UTxO](../key-concepts/utxo.md). ### Delete wallet [`DELETE /v2/byron-wallets/{walletId}`](https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/deleteByronWallet) diff --git a/doc/common-use-cases/index.rst b/doc/common-use-cases/index.rst new file mode 100644 index 0000000..8fcd563 --- /dev/null +++ b/doc/common-use-cases/index.rst @@ -0,0 +1,11 @@ +================ +Common Use Cases +================ + +.. toctree:: + :maxdepth: 3 + + how-to-create-a-wallet + how-to-create-addresses + how-to-make-a-transaction + how-to-manage-wallets \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..37fbc8c --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,118 @@ + + +import sys +import os +import sphinx_rtd_theme +import recommonmark + +from recommonmark.transform import AutoStructify +from os.path import abspath, join, dirname + +sys.path.insert(0, abspath(join(dirname(__file__)))) + +# -- RTD configuration ------------------------------------------------ + +on_rtd = os.environ.get("READTHEDOCS", None) == "True" + +# This is used for linking and such so we link to the thing we're building +rtd_version = os.environ.get("READTHEDOCS_VERSION", "latest") +if rtd_version not in ["stable", "latest"]: + rtd_version = "stable" + +# -- Project information ----------------------------------------------------- + +project = 'cardano-adrestia Documentation' +copyright = '2020, IOHK' +author = 'IOHK' + +# The full version, including alpha/beta/rc tags +release = '1.0.0' + + +# -- General configuration --------------------------------------------------- +master_doc = 'index' +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. + +extensions = [ + "sphinx_rtd_theme", + 'recommonmark', + 'sphinx_markdown_tables', + 'sphinxemoji.sphinxemoji', + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", + "sphinx.ext.mathjax", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['.sphinx/_templates'] +html_static_path = ['.sphinx/_static'] + +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} + +intersphinx_mapping = { + "commandsv1": ( + "https://robotpy.readthedocs.io/projects/commands-v1/en/%s/" + % rtd_version, + None, + ), +} + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +html_theme_options = { + 'logo_only': False, + 'display_version': True, + 'prev_next_buttons_location': 'bottom', + 'style_external_links': False, + 'vcs_pageview_mode': '', + 'style_nav_header_background': '#0635a7', + # Toc options + 'collapse_navigation': True, + 'sticky_navigation': True, + 'navigation_depth': 4, + 'includehidden': True, + 'titles_only': False +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". + +html_logo = ".sphinx/cardano-logo.png" + +html_context = { + "display_github": True, # Add 'Edit on Github' link instead of 'View page source' + "source_suffix": source_suffix, +} + +# -- Custom Document processing ---------------------------------------------- + +def setup(app): + app.add_config_value('recommonmark_config', { + 'enable_auto_doc_ref': False, + 'enable_auto_toc_tree': False, + }, True) + app.add_transform(AutoStructify) + +mathjax_config = { + 'extensions': ['tex2jax.js'], + 'jax': ['input/TeX', 'output/HTML-CSS'], +} \ No newline at end of file diff --git a/user-guide/content/docs/faq.md b/doc/faq.md similarity index 76% rename from user-guide/content/docs/faq.md rename to doc/faq.md index 7d20d8c..97643c7 100644 --- a/user-guide/content/docs/faq.md +++ b/doc/faq.md @@ -1,39 +1,33 @@ ---- -weight: 999 -title: FAQ ---- +FAQ +=== -{{}} +## Why aren't my unused addresses imported when I restore a wallet? This is by virtue of the blockchain. An unused address is by definition unused. Meaning that is doesn't exist on the chain and only exists locally, in the context of the software that has generated it. Different software may use different rules to generate addresses. For example in the past, _cardano-sl_ wallets used a method called random derivation where addresses were created from a root seed and a random index stored within the address itself. Because these indexes were random, it was not possible to restore randomly generated addresses which hadn't been used on chain yet! More recently, `cardano-wallet` has been using sequential derivation which follows a very similar principle with the major difference that indexes are derived in sequence, starting from 0. Following this method, wallets aren't allowed to pre-generate too many addresses in advance. As a consequence, it is now possible to restore a wallet across many machines while keeping a very consistent state. -{{}} -{{}} + +## I’ve noticed that other blockchains create accounts for wallets? There are two sides to this question. Either, you are referring to accounts as in Ethereum accounts, or you may refer to accounts of hierarchical deterministic wallets. In the first scenario, assets in the form of accounts are only supported in the Shelley era of Cardano and only for a specific use-case: rewards. Rewards are indeed implicitely published on the blockchain to mitigate the risk of flooding the network at the end of every epoch with rewards payouts! Hence, each core node keeps track of the current value of each reward account in a Ledger. Money can be withdrawn from this account and is then turned as a UTxO. Please note that funds can never be manually sent to a reward account. The creation of a reward account is done when registering a staking key, via a specific type of transaction. -In the second case, please refer to the [HD wallets]({{< ref "hierarchical-deterministic-wallets.md" >}}) section in the _Key concepts_. Cardano wallets typically follow an HD tree of derivation as described in this section. -{{}} +In the second case, please refer to the [HD wallets](key-concepts/hierarchical-deterministic-wallets.md) section in the _Key concepts_. Cardano wallets typically follow an HD tree of derivation as described in this section. -{{}} +## "It seems like I have to install and configure many APIs and libraries, what is the fastest and most simple way to do this at once? 🐳 [docker](https://docs.docker.com/) is your friend here! Every component is packaged as docker images. Releases are tagged and the very edge is always accessible. See the various docker guides on the components' repository, and also how to compose services using [docker-compose](https://docs.docker.com/compose/). -{{}} -{{}} + +## Is there a reason why I would have to build from src? If you intend to contribute to Cardano by making code changes to one of the core components, then yes. We recommend using [stack](https://docs.haskellstack.org/en/stable/README/) for a better developer experience. If you only intend to use the services as-is then, using either the pre-compiled release artifacts for your appropriate platform or a pre-packaged docker image is preferable. -{{}} -{{}} +## Where is the faucet and do I get test ADA? - On Byron, have a look at: https://testnets.cardano.org/en/cardano/byron/tools/faucet - On Shelley, this is coming soon. - -{{}} diff --git a/doc/high-level-diagram.mmd b/doc/high-level-diagram.mmd new file mode 100644 index 0000000..ce33faa --- /dev/null +++ b/doc/high-level-diagram.mmd @@ -0,0 +1,9 @@ +erDiagram + CARDANO-NODE ||--o{ CARDANO-WALLET : sends-blocks-and-receives-txs + CARDANO-NODE ||--o{ CARDANO-DB-SYNC : sends-blocks + CARDANO-NODE ||--o{ CARDANO-SUBMIT-API : receives-txs + + CARDANO-DB-SYNC ||--|| POSTGRESQL : dumps-into + + POSTGRESQL ||--|| CARDANO-GRAPHQL : is-queried + POSTGRESQL ||--|| CARDANO-EXPLORER-API : is-queried \ No newline at end of file diff --git a/doc/high-level-diagram.svg b/doc/high-level-diagram.svg new file mode 100644 index 0000000..19b1e56 --- /dev/null +++ b/doc/high-level-diagram.svg @@ -0,0 +1,563 @@ +CARDANO-NODECARDANO-WALLETCARDANO-DB-SYNCCARDANO-SUBMIT-APIPOSTGRESQLCARDANO-GRAPHQLCARDANO-EXPLORER-APIsends-blocks-and-receives-txssends-blocksreceives-txsdumps-intois-queriedis-queried \ No newline at end of file diff --git a/doc/icon/check-circle.svg b/doc/icon/check-circle.svg new file mode 100644 index 0000000..265ff25 --- /dev/null +++ b/doc/icon/check-circle.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/doc/icon/dash-circle-fill.svg b/doc/icon/dash-circle-fill.svg new file mode 100644 index 0000000..9f2d6dc --- /dev/null +++ b/doc/icon/dash-circle-fill.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/doc/icon/hammer.svg b/doc/icon/hammer.svg new file mode 100644 index 0000000..8651cf3 --- /dev/null +++ b/doc/icon/hammer.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..14aef5a --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,24 @@ +======== +adrestia +======== + +.. include:: ../README.rst + +.. toctree:: + :titlesonly: + :hidden: + + Go Back to Cardano Documentation + +.. toctree:: + :maxdepth: 3 + :caption: Understanding Adrestia + :titlesonly: + + architecture + installation + common-use-cases/index + key-concepts/index + migrating-from-sl + api-reference + faq diff --git a/doc/installation.md b/doc/installation.md new file mode 100644 index 0000000..05c1778 --- /dev/null +++ b/doc/installation.md @@ -0,0 +1,76 @@ +Installation Instructions +========================= + +## Using Docker (recommended) + +Docker images are continuously built and deployed on [dockerhub](https://hub.docker.com/u/inputoutput) under specific tags. Using docker provides **the fastest** and **easiest** user experience for setting up the Cardano stack. This is the preferred solution. + + +The following images are available for each component of the Adrestia architecture: + +| Repository | Tags | Documentation | +| ------------------------------------------------------------------------------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------- | +| [inputoutput/cardano-node](https://hub.docker.com/r/inputoutput/cardano-node) | `master`, `MAJ.MIN.PATCH`, `latest` | [link](https://github.com/input-output-hk/cardano-node/blob/master/nix/docker.nix#L1-L25) | +| [inputoutput/cardano-db-sync](https://hub.docker.com/r/inputoutput/cardano-db-syncnputoutput-cardano-db-sync) | `master`, `MAJ.MIN.PATCH`, `latest` | [link](https://github.com/input-output-hk/cardano-db-sync/blob/master/nix/docker.nix#L1-L35) | +| [inputoutput/cardano-graphql](https://hub.docker.com/r/inputoutput/cardano-graphql) | `master`, `MAJ.MIN.PATCH`, `latest` | [link](https://github.com/input-output-hk/cardano-graphql/wiki/Docker) | +| [inputoutput/cardano-explorer-api](https://hub.docker.com/r/inputoutput/cardano-explorer-api) | `master`, `MAJ.MIN.PATCH`, `latest` | [link](https://github.com/input-output-hk/cardano-rest/wiki/Docker) | +| [inputoutput/cardano-submit-api](https://hub.docker.com/r/inputoutput/cardano-submit-api) | `master`, `MAJ.MIN.PATCH`, `latest` | [link](https://github.com/input-output-hk/cardano-rest/wiki/Docker) | +| [inputoutput/cardano-wallet](https://hub.docker.com/r/inputoutput/cardano-wallet) | `byron`, `YYYY.MM.DD-byron`, `latest` | [link](https://github.com/input-output-hk/cardano-wallet/wiki/Docker) | + +### Semantic + +| Tag | Semantic | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `latest` | Points to the latest __stable__ image for the corresponding component. This is also the tag to which `docker` defaults when pulling without an explicit tag. These typically points to latest known release that happens at the end of an iteration cycle. Depending on the project / component, the iteration cycle may vary from 1 to 2 weeks. | +| `MAJ.MIN.PATCH` or `YYYY.MM.DD-byron` | Must match actual releases of the corresponding component. Refer to each of the component's release notes to know which release tags are available. | +| `master` | Points to the very tip of the development branch. This is therefore __not recommended__ for production but can be useful to try out features before they are officially released. | +| `byron` | A special tag pointing to the very tip of the development branch on `cardano-wallet`. `cardano-wallet` does support both `jörmungandr` and `cardano-node` at the same time, but corresponding images are packaged separately. The `byron` tag therefore points to a version of `cardano-wallet` compatible with cardano-node in OBFT mode. | + +### Examples + +For example, to use `cardano-node@1.10.0`, you can run: + +``` +docker pull inputoutput/cardano-node:1.10.0 +``` + +Similarly, one can pull `cardano-wallet@v2020-04-07` with: + +``` +docker pull inputoutput/cardano-wallet:v2020.4.7-byron +``` + +> **HINT** _About version compatibility_ + +For version compatibility between components, refer to the compatibility matrix on each component's main page (For instance, [cardano-wallet#latest-releases](https://github.com/input-output-hk/cardano-wallet#latest-releases)). + +### Docker compose + +Some components also provide example setup via [docker-compose](https://docs.docker.com/compose/). Those are useful for a quick start or as a baseline for development. See for example [cardano-wallet](https://github.com/input-output-hk/cardano-wallet/blob/master/docker-compose.yml), [cardano-graphql](https://github.com/input-output-hk/cardano-graphql/blob/master/docker-compose.yml) or [cardano-rest](https://github.com/input-output-hk/cardano-rest/blob/master/docker-compose.yml). + +## Pre-compiled Artifacts / Building From Sources + +If you prefer using raw binary, some components provide pre-compiled release artifacts for each release. These can be downloaded directly from the github servers, via the UI, or using a command-line tool like `wget` or `cURL`. For example, you can download a pre-packaged linux binary for `cardano-wallet@v2020-04-07` via: + +``` +curl -L https://github.com/input-output-hk/cardano-wallet/releases/download/v2020-04-07/cardano-wallet-v2020-04-07-linux64.tar.gz | tar xz + +./cardano-wallet-byron-linux64/cardano-wallet --help +The CLI is a proxy to the wallet server, which is required for most commands. +Commands are turned into corresponding API calls, and submitted to an +up-and-running server. Some commands do not require an active server and can be +run offline (e.g. 'mnemonic generate'). + +[...] +``` + +If you want to compile everything from sources, refer to each repository's documentation. As a pre-requisite, you may want to install and configure [Nix](https://nixos.org/), [stack](https://docs.haskellstack.org/en/stable/README/) or [cabal](https://www.haskell.org/cabal/) depending on your preferences. Build instructions are available on each repository's main README. + + Repository | Releases | Linux | MacOS | Windows +----------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----- | ----- | ------- +[cardano-node](https://github.com/input-output-hk/cardano-node) | [releases](https://github.com/input-output-hk/cardano-node/releases) | ✔️ | ✔️ | ✔️ +[cardano-db-sync](https://github.com/input-output-hk/cardano-db-sync) | [releases](https://github.com/input-output-hk/cardano-db-sync/releases) | ✔️ | ✔️ | ❌ +[cardano-submit-api](https://github.com/input-output-hk/cardano-rest) | [releases](https://github.com/input-output-hk/cardano-rest/releases) | ✔️ | ✔️ | ❌ +[cardano-explorer-api](https://github.com/input-output-hk/cardano-rest) | [releases](https://github.com/input-output-hk/cardano-rest/releases) | ✔️ | ✔️ | ❌ +[cardano-graphql](https://github.com/input-output-hk/cardano-graphql) | [releases](https://github.com/input-output-hk/cardano-graphql/releases) | ✔️ | ✔️ | ❌ +[cardano-wallet](https://github.com/input-output-hk/cardano-wallet) | [releases](https://github.com/input-output-hk/cardano-wallet/releases) | ✔️ | ✔️ | ✔️ diff --git a/user-guide/content/docs/key-concepts/addresses-byron.md b/doc/key-concepts/addresses-byron.md similarity index 73% rename from user-guide/content/docs/key-concepts/addresses-byron.md rename to doc/key-concepts/addresses-byron.md index b7f3ee9..74203d3 100644 --- a/user-guide/content/docs/key-concepts/addresses-byron.md +++ b/doc/key-concepts/addresses-byron.md @@ -1,7 +1,5 @@ ---- -weight: 3 -title: Addresses Format (Byron) ---- +Addresses Format (Byron) +======================== ## Internal Structure @@ -43,31 +41,30 @@ title: Addresses Format (Byron) ``` -1. CRC: [Cyclic Redundancy Check](https://computer.howstuffworks.com/encryption7.htm); - sort of checksum, a bit (pun intended) more reliable. +1. [Cyclic Redundancy Check](https://computer.howstuffworks.com/encryption7.htm)(CRC). This +is a more reliable type of checksum operation. -2. ASD: Address Spending Data; Some data that are bound to an address. It's - an extensible object with payload which identifies one of the three elements: - - A Public Key (Payload is thereby a PublicKey) - - A Script (Payload is thereby a script and its version) - - A Redeem Key (Payload is thereby a RedeemPublicKey) +2. Address Spending Data (ASD); This is data bound to an address. It's + an extensible object with payload that identifies one of the three elements: + - A Public Key (payload is a PublicKey) + - A Script (payload is a script and its version) + - A Redeem Key (payload is a RedeemPublicKey) -3. Derivation Path: Note that there's no derivation path for Redeem nor - Scripts addresses! +3. Derivation Path: There's no derivation path for Redeem or Scripts addresses. 4. ChaChaPoly: Authenticated Encryption with Associated Data; See [RFC - 7539](https://datatracker.ietf.org/doc/rfc7539) We use it as a way to cipher + 7539](https://datatracker.ietf.org/doc/rfc7539) Used to cipher the derivation path using a passphrase (the root public key). ## Example 1: Yoroi Address - Byron Mainnet -Let's take an arbitrary Yoroi base58-encoded address of the Byron mainNet: +This is an arbitrary Yoroi base58-encoded address of the Byron mainNet: ``` Ae2tdPwUPEZFRbyhz3cpfC2CumGzNkFBN2L42rcUc2yjQpEkxDbkPodpMAi ``` -Now, this address could be represented as a raw bytestring by decoding from +This address could be represented as a raw bytestring by decoding from base58: ``` @@ -78,8 +75,7 @@ base58: ``` In this representation, bytes are in a structured format called [CBOR](https://tools.ietf.org/html/rfc7049). -Some bytes are actually tags which carry a particular semantic, and some are values. -We can re-shuffle the bytes as follows to make things a bit clearer: +Some bytes are actually tags carrying a particular semantic, and some are values. Re-shuffling the bytes as follows makes things a bit clearer: ``` 82 # array (2) @@ -88,12 +84,12 @@ We can re-shuffle the bytes as follows to make things a bit clearer: 1A 9026DA5B # unsigned(2418465371) [CRC] ``` -So, a Byron address is basically formed of two top-level elements: +A Byron address is formed with two top-level elements: - A tagged bytestring; `24` means that the bytes represent another CBOR-encoded structure. - A CRC of the inner tagged bytestring -Now, if we also interpret the inner bytestring as a CBOR structure, we obtain: +Interpreting the inner bytestring as a CBOR structure produces this result: ``` 83 # array(3) @@ -103,20 +99,19 @@ Now, if we also interpret the inner bytestring as a CBOR structure, we obtain: ``` An address type of `0` refers to a spending address for which the address root -contains a hash of a public spending key. This address payload has no attribute -for the initial address was a Yoroi's address on MainNet which follows a BIP-44 -derivation scheme and therefore, does not require any attributes. +contains a hash of a public spending key. This address payload has no attribute, +as the initial address was a Yoroi's address on MainNet, which follows a BIP-44 +derivation scheme so it does not require any attributes. ## Example 2: Daedalus Address - Byron TestNet -Let's take an arbitrary Daedalus base58-encoded address of a Byron testNet: +This is arbitrary Daedalus base58-encoded address of a Byron testNet: ``` 37btjrVyb4KEB2STADSsj3MYSAdj52X5FrFWpw2r7Wmj2GDzXjFRsHWuZqrw7zSkwopv8Ci3VWeg6bisU9dgJxW5hb2MZYeduNKbQJrqz3zVBsu9nT ``` -Now, this address could be represented as a raw bytestring by decoding from -base58: +This address could be represented as a raw bytestring by decoding from base58: ``` 0X82 0XD8 0X18 0X58 0X49 0X83 0X58 0X1C 0X9C 0X70 0X85 0X38 0XA7 0X63 0XFF 0X27 @@ -128,8 +123,8 @@ base58: ``` In this representation, bytes are in a structured format called [CBOR](https://tools.ietf.org/html/rfc7049). -Some bytes are actually tags which carry a particular semantic, and some are values. -We can re-shuffle the bytes as follows to make things a bit clearer: +Some bytes are actually tags carrying a particular semantic, and some are values. +Re-shuffling the bytes as follows makes things a bit clearer: ``` 82 # array(2) @@ -138,12 +133,12 @@ We can re-shuffle the bytes as follows to make things a bit clearer: 1A 6979126C # unsigned(1769542252) [CRC] ``` -So, a Byron address is basically formed of two top-level elements: +A Byron address is formed with two top-level elements: - A tagged bytestring; `24` means that the bytes represent another CBOR-encoded structure. - A CRC of the inner tagged bytestring -Now, if we also interpret the inner bytestring as a CBOR structure, we obtain: +Interpreting the inner bytestring as a CBOR structure produces this result: ``` 83 # array(3) @@ -157,7 +152,7 @@ Now, if we also interpret the inner bytestring as a CBOR structure, we obtain: ``` An address type of `0` refers to a spending address for which the address root -contains a hash of a public spending key. In addition, we can see that this -address has 2 attributes identified by two tags `01` for the derivation path, -and `02` for the network magic. The derivation path is an encrypted bytestring -which holds two derivation indexes for the account and address paths. +contains a hash of a public spending key. We can see that this address has 2 attributes, which +are identified by two tags: `01` for the derivation path, and `02` for the network magic. +The derivation path is an encrypted bytestring that holds two derivation indexes (for the account +and address paths). diff --git a/user-guide/content/docs/key-concepts/hierarchical-deterministic-wallets.md b/doc/key-concepts/hierarchical-deterministic-wallets.md similarity index 64% rename from user-guide/content/docs/key-concepts/hierarchical-deterministic-wallets.md rename to doc/key-concepts/hierarchical-deterministic-wallets.md index 79bf529..a66fa39 100644 --- a/user-guide/content/docs/key-concepts/hierarchical-deterministic-wallets.md +++ b/doc/key-concepts/hierarchical-deterministic-wallets.md @@ -1,21 +1,19 @@ ---- -weight: 2 -title: HD Wallets ---- +HD Wallets +========== ## Recovery Phrases ### Motivation -We define a way for easily entering and writing down arbitrary binary seeds using a simple dictionary of known words (available in many different languages). +Recovery phrases (or backup, or seed phrases) are unique and randomly generated sets of 12 words that enable the user to recover their wallet at anytime. -The motivation here is to have sentence of words easy to read and write for humans, which map uniquely back and forth to a sized binary data (harder to remember). +Seed phrases map to binary data that in turns generates the wallet's private key. Since binary data would be impossible to memorize by a human, programmers use easy-to-read, understandable language to create binary seeds using a simple dictionary of known words. This is available in multiple languages. ### Encoding -The process describing how to encode recovery phrases is described in [BIP-0039](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) section "Generating the mnemonic". Below is a reformulation of this specification. +The process describing the encoding of recovery phrases is described in [BIP-0039](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki), in the "Generating the mnemonic" section. Below is a reformulation of this specification. -We call _Entropy_ an arbitrary sequence of bytes that has been generated through high quality randomness methods. The allowed size of _Entropy_ is 96-256 bits and is necessarily a multiple of 32 bits (4 bytes). +We call _Entropy_ an arbitrary sequence of bytes that has been generated through high quality randomization methods. The allowed size of _Entropy_ is 96-256 bits, and is necessarily a multiple of 32 bits (4 bytes). A checksum is appended to the initial entropy by taking the first `ENT / 32` bits of the `SHA256` hash of it, where `ENT` designates the _Entropy_ size in bits. @@ -40,11 +38,11 @@ Cardano uses the same dictionaries as defined in [BIP-0039](https://github.com/b ### Motivation -In Cardano, hierarchical deterministic (abbrev. HD) wallets are similar to those described in [BIP-0032](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#motivation). +In Cardano, hierarchical deterministic (HD) wallets are similar to those described in [BIP-0032](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#motivation). -Deterministic wallets and elliptic curve mathematics permit schemes where one can calculate a wallet public keys without revealing its private keys. This permits for example a webshop business to let its webserver generate fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds). However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. +Deterministic wallets and elliptic curve mathematics permit schemes where one can calculate a wallet's public keys without revealing its private keys. This allows for example a webshop business to let its webserver generate fresh addresses (public key hashes) for each order or for each customer, without giving the web server access to the corresponding private keys (which are required for spending the received funds). However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. -However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root. +However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a web shop, the web server does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root. ### Notation @@ -52,11 +50,16 @@ Conceptually, HD derivation can be seen as a tree with many branches, where keys For deriving new keys from parent keys, we use the same approach as defined in [BIP32-Ed25519: Hierarchical Deterministic Keys over a Non-linear Keyspace](/adrestia/user-guide/Ed25519_BIP.pdf). + + We note {{}}CKD_{priv}{{}} the derivation of a private child key from a parent private key such that: -{{}} +```eval_rst +.. math:: + CKD_{prv}((k^P, c^P), i) → (k_i, c_i) -{{}} + +``` We note {{< katex >}}CKD_{pub}{{}} the derivation of a public child key from a parent public key such that: @@ -64,9 +67,7 @@ We note {{< katex >}}CKD_{pub}{{}} the derivation of a public child key i < 2^{31}: CKD_{pub}((A^P, c^P), i) → (A_i, c_i) {{}} -{{}} -This is only possible for so-called "soft" derivation indexes, smaller than {{}}2^{31}{{}}. -{{}} +> **HINT** This is only possible for so-called "soft" derivation indexes, smaller than {{}}2^{31}{{}}. We note {{}}N{{}} the public key corresponding to a private key such that: @@ -99,30 +100,28 @@ m / purpose_H / coin\_type_H / account_H / account\_type / address\_index - `0` if the {{}}account\_type{{}} is `2` - Anything between 0 and 231 otherwise -{{}} -In the _Byron_ era, sequential wallets used in Yoroi (a.k.a Icarus wallets) have been using `purpose = 44_H` according to standard BIP-44 wallets. -The _Shelley_ era introduces however an extension to BIP-44, and therefore, uses a different `purpose` number. -{{}} +> **WARNING** In the _Byron_ era, sequential wallets used in Yoroi (also known as Icarus wallets) have been using `purpose = 44_H` according to standard BIP-44 wallets. +> The _Shelley_ era introduces an extension to BIP-44, and therefore uses a different `purpose` number. ### Account Discovery > What follows is taken from the "Account Discovery" section from [BIP-0044](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki#account-discovery) -When the master seed is imported from an external source the software should start to discover the accounts in the following manner: +When the master seed is imported from an external source, the software should start to discover the accounts in the following manner: -- derive the first account's node (index = 0) -- derive the external chain node of this account -- scan addresses of the external chain; respect the gap limit described below -- if no transactions are found on the external chain, stop discovery -- if there are some transactions, increase the account index and go to step 1 +- Derive the first account's node (index = 0) +- Derive the external chain node of this account +- Scan addresses of the external chain; respect the gap limit described below +- If no transactions are found on the external chain, stop discovery +- If there are some transactions, increase the account index and go to step 1 -For the algorithm to be successful, software should disallow creation of new accounts if previous one has no transaction history. +For the algorithm to be successful, software should disallow the creation of a new accounts if the previous one has no transaction history. -Please note that the algorithm works with the transaction history, not account balances, so you can have an account with 0 total coins and the algorithm will still continue with discovery. +Please note that the algorithm works with the transaction history, not account balances, so you can have an account with 0 total coins and the algorithm will still continue with the discovery. ### Address gap limit -Address gap limit is currently set to 20. If the software hits 20 unused addresses in a row, it expects there are no used addresses beyond this point and stops searching the address chain. We scan just the external chains, because internal chains receive only coins that come from the associated external chains. +Address gap limit is currently set to 20. If the software hits 20 unused addresses in a row, it assumes that there are no used addresses beyond this point and stops searching the address chain. We scan just the external chains, because internal chains receive only coins that come from the associated external chains. Wallet software should warn when the user is trying to exceed the gap limit on an external chain by generating a new address. @@ -131,8 +130,7 @@ Wallet software should warn when the user is trying to exceed the gap limit on a ### History -Throughout the years, Cardano has been using different styles of HD wallets. -We categorize these wallets in the following terms: +Cardano has used different styles of HD wallets, which cane be categorized as: Wallet Style | Compatible Products --- | --- @@ -140,18 +138,18 @@ Byron | Daedalus, Yoroi Icarus | Yoroi, Trezor Ledger | Ledger -Each wallet is based on Ed25519 elliptic curves though differs in subtle ways -highlighted in the next sections. +Each wallet is based on Ed25519 elliptic curves, though there are subtle differences, +which are highlighted in the next sections. ### Overview -The master key generation is the mean by which on turns an initial entropy into -a secure cryptographic key. Child keys can be derived from a master key to produce -an HD structure as outlined above. Child key derivation is explored in next sections. +The master key generation turns an initial entropy into a secure cryptographic key. +Child keys can be derived from a master key to produce a HD structure as outlined above. +Child key derivation is explored in next sections. -In Cardano, the master key generation is different depending on which style of wallet -one is considering. In each case however, the generation is a function from an initial -seed to an extended private key (abbrev. XPrv) composed of: +In Cardano, the master key generation is different, depending on the style of wallet. +In each case however, the generation is a function from an initial seed to an extended private key +(XPrv) composed of: - 64 bytes: an extended Ed25519 secret key composed of: - 32 bytes: Ed25519 curve scalar from which few bits have been tweaked (see below) @@ -165,10 +163,9 @@ seed to an extended private key (abbrev. XPrv) composed of: > - [BIP 0039](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) > - [RFC 8032](https://tools.ietf.org/html/rfc8032#section-5.1.5) -### Pseudo-code +## Pseudo-code -{{}} -{{}} +### Byron ```js function generateMasterKey(seed) { return hashRepeatedly(seed, 1); @@ -201,13 +198,12 @@ function tweakBits(data) { return data; } ``` -{{}} -{{}} +### Icarus _Icarus_ master key generation style supports setting an extra password as an arbitrary byte array of any size. This password acts as a second factor applied to cryptographic key retrieval. When the seed comes from an encoded recovery phrase, the password can therefore -be used to add extra protection in case where the recovery phrase were to be exposed. +be used to add extra protection in cases where the recovery phrase might be exposed. ```js function generateMasterKey(seed, password) { @@ -238,8 +234,9 @@ function tweakBits(data) { > For a detailed analysis of the cryptographic choices and the above requirements, > have a look at: [Wallet Cryptography and Encoding](https://github.com/input-output-hk/chain-wallet-libs/blob/master/doc/CRYPTO.md#master-key-generation-to-cryptographic-key) -{{}} -{{}} + +### Ledger + ```js function generateMasterKey(seed, password) { let data = PBKDF2 @@ -285,6 +282,4 @@ function tweakBits(data) { return data; } -``` -{{}} -{{}} +``` \ No newline at end of file diff --git a/doc/key-concepts/index.rst b/doc/key-concepts/index.rst new file mode 100644 index 0000000..c64b777 --- /dev/null +++ b/doc/key-concepts/index.rst @@ -0,0 +1,10 @@ +============ +Key Concepts +============ + +.. toctree:: + :maxdepth: 3 + + addresses-byron + hierarchical-deterministic-wallets + utxo \ No newline at end of file diff --git a/user-guide/content/docs/key-concepts/utxo.md b/doc/key-concepts/utxo.md similarity index 60% rename from user-guide/content/docs/key-concepts/utxo.md rename to doc/key-concepts/utxo.md index 7e3e643..ffd143c 100644 --- a/user-guide/content/docs/key-concepts/utxo.md +++ b/doc/key-concepts/utxo.md @@ -1,7 +1,5 @@ ---- -weight: 1 -title: UTxO ---- +UTxO +==== ## UTxO @@ -32,20 +30,20 @@ In a standard payment, outputs are a combination of: {{< hint warning >}} _About address encoding_ -We usually represent addresses as encoded text strings. An address has a structure -and a binary representation that is defined by the underlying blockchain. Yet, since +Addresses are represented as encoded text strings. An address has a structure +and a binary representation defined by the underlying blockchain. Yet, since they are often used in user-facing interfaces, addresses are usually encoded in a -human-friendly format to be easily shared between users. +human-friendly format facilitate sharing between users. {{< /hint >}} -An _address_ **does not** uniquely identify an output. As a matter of fact, multiple -transactions could send funds to a same output address! We can however uniquely identify -an output by: +An _address_ **does not** uniquely identify an output. Multiple transactions +could send funds to a same output address, for example. It is possible, however, +to uniquely identify an output by: - Its host transaction id - Its index within that transaction -This combination is also called an **input**. Said differently, inputs are +This combination is also called an **input**. In other words, inputs are outputs of previous transactions. @@ -64,31 +62,31 @@ outputs of previous transactions. Therefore, new transactions spend outputs of previous transactions, and produce new outputs that can be consumed by future transactions. An unspent transaction -output (i.e. not used as an input of any transaction) is called a **UTxO** (as -in **U**nspent **Tx** **O**utput) and represents an amount of money owned by a -participant. +output (i.e., not used as an input of any transaction) is called a **UTxO** (**U**nspent +**Tx** **O**utput). UTxO represents an amount of money owned by a participant. ## FAQ -{{}} +### Where does the money come from? How do I make the first transaction? + When bootstrapping a blockchain, some initial funds can be distributed among an initial set of stakeholders. This is usually the result of an **I**nitial -**C**oin **O**ffering or, an agreement between multiple parties. In practice -it means that, the genesis block of a blockchain may already contain some +**C**oin **O**ffering or an agreement between multiple parties. In practice, +this means that the genesis block of a blockchain may already contain some UTxOs belonging to various stakeholders. -Beside, core nodes running the protocol and producing blocks are allowed to -insert in every block minted (resp. mined) called a **coinbase** transaction. -This transaction has no inputs but follows specific rules fixed by the -protocol and is used as an incentive to encourage participants to engage in +Core nodes running the protocol and producing blocks are allowed to +insert in every block minted ('mined') called a **coinbase** transaction. +This transaction has no inputs, and follows specific rules determined by the +protocol. This transaction is used as an incentive to encourage participants to engage in the protocol. -{{}} -{{}} -In a very simple system that would only support payment transactions, public key -could be substituted for addresses. In practice, addresses are meant to hold some +### What is the difference between an address and a public key? + +In a simple system that would only support payment transactions, public keys +could be substituted for _addresses_. In practice, addresses are meant to hold extra pieces of information that are useful for other aspects of the protocol. -For instance, in Cardano in the Shelley era, addresses may also contain: +For instance, in the Cardano-Shelley era, addresses may also contain: - A network discriminant tag, to distinguish addresses between a testNet and the MainNet and avoid unfortunate mistakes. @@ -99,13 +97,12 @@ Addresses may also be used to trigger smart contracts, in which case, they'll refer to a particular script rather than a public key. In a nutshell, a public key is a piece of information that enables a stakeholder to -prove one owns a particular UTxO. Whereas an address is a data-structure which contain various -pieces of information, for example, a (reference to a) public key. -{{}} +prove ownership of a particular UTxO, whereas an address is a data-structure that contain various +pieces of information. A reference to a public key, for example. + +### What are Cardano addresses made of? -{{}} See: - [About Address Format - Byron](https://github.com/input-output-hk/cardano-wallet/wiki/About-Address-Format---Byron) - [About Address Format - Shelley](https://github.com/input-output-hk/implementation-decisions/blob/master/text/0001-address.md) -{{}} diff --git a/doc/migrating-from-sl.md b/doc/migrating-from-sl.md new file mode 100644 index 0000000..0e61197 --- /dev/null +++ b/doc/migrating-from-sl.md @@ -0,0 +1,54 @@ +Migrating From SL +================= + +This section provides practical tips for migrating from SL. + +## I am using _explorer_ from _cardano-sl_, what should I do? + +The API from the old explorer has been ported identically to [cardano-submit-api](https://github.com/input-output-hk/cardano-rest). This component is part of [cardano-rest](https://github.com/input-output-hk/cardano-rest). Source code dealing with the _explorer_ API from _cardano-sl_ should be straightforward to migrate. See the installation instructions and documentation available on [cardano-rest](https://github.com/input-output-hk/cardano-rest) for more details. + +The setup is slightly different. With _cardano-sl_, the explorer is mounted directly on the core node as one monolith, and can be turned on and off. These components have been split off one another and use an extra middleware to communicate. The "infrastructure" is slightly more complex, but enables greater flexibility and robustness. + +> **INFORMATION**: It is possible to automatically migrate an existing blockchain database from _cardano-sl_ into its new format compatible with _cardano-node_. For this, have a look at the [db-converter][db-converter] and in particular, the `convert` command: + +``` +$ db-converter convert --help +Usage: db-converter convert --epochDir STRING --dbDir STRING --epochSlots WORD64 + +Available options: + -h,--help Show this help text + --epochDir STRING Path to the directory containing old epoch files + --dbDir STRING Path to the new database directory + --epochSlots WORD64 Slots per epoch +``` + +> **INFORMATION**: On Byron, the number of slots per epoch is fixed to `21600`. + +This can save you an hour of time downloading the blockchain from the network! + +Build it with [Nix](https://nixos.org/download.html) as follows: + +``` +$ git clone https://github.com/input-output-hk/ouroboros-network +$ cd ouroboros-network +$ nix-build -A haskellPackages.ouroboros-consensus-byron.components.exes.db-converter -o db-converter +$ ./db-converter/bin/db-converter --help +``` + +[db-converter]: https://github.com/input-output-hk/ouroboros-network/tree/master/ouroboros-consensus-byron + +## I am using _wallet V1_ from _cardano-sl_, what should I do? + +A new `V2` API is now available on [cardano-wallet](https://github.com/input-output-hk/cardano-wallet). In a similar fashion to _cardano-rest_, this component used to be mounted directly on the core node, but it is now an independent process. The _cardano-wallet_ is nothing more than a webserver that connects to a local core node through a domain socket. + +There are some variations between the `V2` and `V1` APIs, but both APIs follow a very similar approach and are still very resource-centric (a.k.a ReST). _cardano-wallet_ is a large component that covers multiple networks and node backends. If you're coming from sl, you're most likely interested in _cardano-wallet-byron_ at the moment, since it is integrated with a Byron-reboot OBFT _cardano-node_. Follow the setup instructions on _cardano-wallet_'s README and Wiki. + +The API documentation is available in [API References](api-reference.md). Note that only the _Legacy_ sub-part of the API matters at this stage. The _Shelley_ part is not available on the Byron integration but can be looked up as a reference for future integration. + +> **WARNING**: _cardano-sl_ had the concept of "accounts" inside wallets. This concepts is now entirely gone. If you need multiple accounts, use multiple wallets. + +## I am using _wallet V0_ from _cardano-sl_, what should I do? + +If you use wallet V0, it will be harder to migrate to _cardano-wallet_. The gaps between `V0` and `V2` are larger, but everything from the previous section applies. + +More questions? Have a look at the [FAQ](faq.md) or else, reach out on [Github](https://github.com/input-output-hk/adrestia/issues/new/choose)! diff --git a/user-guide/README.md b/user-guide/README.md index 7208d3f..85366f2 100644 --- a/user-guide/README.md +++ b/user-guide/README.md @@ -1,18 +1,17 @@ # README -This website is generated using [hugo](https://gohugo.io/). It uses the [book](https://themes.gohugo.io//theme/hugo-book/) theme which provides some -nice constructs on top of raw markdown. +This website is generated using [hugo](https://gohugo.io/). It uses the [book](https://themes.gohugo.io//theme/hugo-book/) theme, which provides some nice constructs on top of raw markdown. # Getting Started 1. Install [hugo_extended_0.68.0](https://github.com/gohugoio/hugo/releases/tag/v0.68.0). - :warning: Make sure to pick the **extended** version!! + :warning: Pick the **extended** version!! 2. Run `hugo server -t book` - This spins up a server with live-reloading that compiles and serves the static website on http://localhost:1313/adrestia/user-guide. + This creates a live-reloading server that compiles and serves the static website on http://localhost:1313/adrestia/user-guide. # Deploying -The static website is automatically built and deploy by a continuous integration environment when merged into the `master` branch. +The static website is automatically built and deployed by a continuous integration environment when merged into the `master` branch. diff --git a/user-guide/content/_index.md b/user-guide/content/_index.md index 4a602e1..b7e48c7 100644 --- a/user-guide/content/_index.md +++ b/user-guide/content/_index.md @@ -15,10 +15,10 @@ As reflected on the [roadmap][roadmap], the Cardano platform is going through th BYRON | SHELLEY | GOGUEN | BASHO | VOLTAIRE

-Themes are being developed in parallel. So far only _Byron_ , which provides the foundation for the platform has made it into the mainnet. The primary purpose of Byron was to release a provably secure proof of stake consensus protocol that is energy efficient and cost effective known as [Ouroboros][ouroboros]. _Shelley_ is the next theme to be released soon; it'll bring decentralization and delegations of assets into _Byron_. +Themes are being developed in parallel. So far only _Byron_ , which provides the foundation for the platform, has made it into the mainnet. The primary purpose of Byron was to release an energy-efficient, cost-effective, provably secure proof of stake consensus protocol known as [Ouroboros][ouroboros]. _Shelley_ is the next theme to be released; it'll bring decentralization and delegation of assets into _Byron_. {{< hint info >}} -An implementation of the protocol is [here][ouroboros-network] and is realized through [cardano-node][cardano-node], deployed as core and relay nodes to form the Cardano network. +An implementation of the protocol, realized through [cardano-node][cardano-node], can be found [here][ouroboros-network]. It is deployed as core and relay nodes to form the Cardano network. [ouroboros-network]: https://github.com/input-output-hk/ouroboros-network [cardano-node]: https://github.com/input-output-hk/cardano-node @@ -30,7 +30,7 @@ On top of this, Adrestia provides a set of services to interact with the Cardano - [cardano-submit-api][cardano-rest]: HTTP API for submitting signed transactions. - [cardano-graphql][cardano-graphql]: HTTP GraphQL API for exploring the blockchain. -As well as an SDK split into several low-level libraries on various topics: +It also provides an SDK, split into several low-level libraries on various topics: - [cardano-addresses][cardano-addresses]: Address generation, derivation & mnemonic manipulation. - [cardano-coin-selection][cardano-coin-selection]: Algorithms for coin selection and fee balancing. @@ -42,10 +42,10 @@ The only currently available language target is _Haskell_, although support for {{< hint danger >}} **IMPORTANT NOTE** -The Byron reboot era is **soon to end by early summer** when the Shelley hard fork shall occur. This **will break ALL existing** exchange integrations. Cardano-sl shall no longer be maintained or supported. **Adrestia** tooling **will support** all integrations **moving forward for Shelley**. +The Byron reboot era **will end by early summer** when the Shelley hard fork occurs. This **will break ALL existing** exchange integrations. Cardano-sl will no longer be maintained or supported. **Adrestia** tooling **will support** all integrations **moving forward for Shelley**. {{< /hint >}} -In the diagram below, components in red are non-Shelley compliant and will not be available after the hard fork, while the components in green are Shelley compliant and will be supported during and after the hard-fork. +In the diagram below, components in red are non-Shelley compliant and will _not_ be available after the hard fork. The components in green are Shelley-compliant and _will_ be supported during _and_ after the hard-fork. diff --git a/user-guide/content/docs/api-references.md b/user-guide/content/docs/api-references.md deleted file mode 100644 index 6f74f8d..0000000 --- a/user-guide/content/docs/api-references.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -weight: 998 -title: API References ---- - -## Components - -Component | Link ---- | --- -[cardano-wallet][cardano-wallet] | https://input-output-hk.github.io/cardano-wallet/api/edge -[cardano-submit-api][cardano-rest] | https://input-output-hk.github.io/cardano-rest/submit-api/ -[cardano-explorer-api][cardano-rest] | https://input-output-hk.github.io/cardano-rest/explorer-api/ -[cardano-graphql][cardano-graphql] | _Soon available._ - - -{{}} -_About cardano-wallet_ - -Cardano-wallet comes with a command-line interface 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 which 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 command line also provides some useful helpers like 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][cardano-addresses] | https://input-output-hk.github.io/cardano-addresses/haddock/ | _Soon available._ -[cardano-transactions][cardano-transactions] | https://input-output-hk.github.io/cardano-transactions/haddock/ | _Soon available._ -[cardano-coin-selection][cardano-coin-selection] | https://input-output-hk.github.io/cardano-coin-selection/haddock/ | _Soon available._ -[bech32][bech32] | https://input-output-hk.github.io/bech32/haddock/ | See https://github.com/bitcoinjs/bech32 - -{{}} -_About cardano-transactions_ - -In addition to the low-level library, cardano-transactions also provides a command-line interface (`cardano-tx`) to construct transactions directly in the terminal. -Check out the repository's documentation and examples to see example usage. -{{}} - -[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 - -[cardano-coin-selection]: https://github.com/input-output-hk/cardano-coin-selection -[cardano-addresses]: https://github.com/input-output-hk/cardano-addresses -[cardano-transactions]: https://github.com/input-output-hk/cardano-transactions -[bech32]: https://github.com/input-output-hk/bech32 diff --git a/user-guide/content/docs/architecture.md b/user-guide/content/docs/architecture.md deleted file mode 100644 index 8e2990d..0000000 --- a/user-guide/content/docs/architecture.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -weight: 1 -title: Architecture ---- - -## High-Level Diagram - -{{< mermaid >}} -erDiagram - CARDANO-NODE ||--o{ CARDANO-WALLET : sends-blocks-and-receives-txs - CARDANO-NODE ||--o{ CARDANO-DB-SYNC : sends-blocks - CARDANO-NODE ||--o{ CARDANO-SUBMIT-API : receives-txs - - CARDANO-DB-SYNC ||--|| POSTGRESQL : dumps-into - - POSTGRESQL ||--|| CARDANO-GRAPHQL : is-queried - POSTGRESQL ||--|| CARDANO-EXPLORER-API : is-queried - -{{< /mermaid >}} - -## Components - -### [cardano-node][cardano-node] - -The core [cardano-node][cardano-node], which will support Ouroboros Praos. - -{{}} -Supported environments: Linux (64-bits), MacOS (64-bits), Windows (64-bits), Docker -{{< /hint >}} - -### [cardano-db-sync][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-bits), MacOS (64-bits), Docker -{{< /hint >}} - -### [cardano-wallet][cardano-wallet] - -[cardano-wallet][cardano-wallet] An HTTP REST API is recommended for 3rd party wallets and small exchanges who do not want to manage UTxOs for transactions themselves. Use it 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-bits), MacOS (64-bits), Windows (64-bits), Docker -{{< /hint >}} - -### [cardano-rest][cardano-rest] - -[cardano-rest][cardano-rest] is made of two HTTP APIs that are used to retrieve transactions, addresses, and time periods (epochs and slots) from the [cardano-db-sync][cardano-db-sync] component and submit an already serialized transaction to the network using [cardano-explorer-api][cardano-rest] & [cardano-submit-api][cardano-rest] respectively. The [cardano-submit-api][cardano-rest] uses the same API as the [cardano-sl:explorer][cardano-sl-explorer] to ease migration from already integrated clients. New integration should however look into [cardano-graphql][cardano-graphql]. - -{{}} -Supported environments: Linux (64-bits), MacOS (64-bits), Docker -{{< /hint >}} - -### [cardano-graphql][cardano-graphql] - -HTTP GraphQL API for Cardano. A more flexible alternative for blockchain exploration than [cardano-rest][cardano-rest]. - -{{}} -Supported environments: Linux (64-bits), MacOS (64-bits), Docker -{{< /hint >}} - -## Choosing the right component - -{{}} -graph TD -QMakeTx{Do you need to
make transactions?} -QManageUTxO{Do you want to
implement your own wallet?} -QAlreadyIntegrated{Do you already have
an integration with
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 -{{}} - -## Notes - -See also [input-output-hk/adrestia][adrestia]. - -[adrestia]: https://github.com/input-output-hk/adrestia -[cardano-graphql]: https://github.com/input-output-hk/cardano-graphql -[cardano-db-sync]: https://github.com/input-output-hk/cardano-db-sync -[cardano-node]: https://github.com/input-output-hk/cardano-node -[cardano-rest]: https://github.com/input-output-hk/cardano-rest -[cardano-sl-explorer]: https://cardanodocs.com/technical/explorer/api/ -[cardano-wallet]: https://github.com/input-output-hk/cardano-wallet diff --git a/user-guide/content/docs/common-use-cases/_index.md b/user-guide/content/docs/common-use-cases/_index.md deleted file mode 100644 index 22366b4..0000000 --- a/user-guide/content/docs/common-use-cases/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -weight: 4 -title: Common Use-Cases ---- diff --git a/user-guide/content/docs/common-use-cases/how-to-create-a-wallet.md b/user-guide/content/docs/common-use-cases/how-to-create-a-wallet.md deleted file mode 100644 index 64f30fc..0000000 --- a/user-guide/content/docs/common-use-cases/how-to-create-a-wallet.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -weight: 1 -title: 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 wallet]({{< ref "hierarchical-deterministic-wallets.md" >}}). One 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 between them is that for a `random` wallet user needs to [create new address]({{< ref "how-to-create-addresses.md" >}}) manually, whereas for sequential wallets like `icarus`, `trezor` and `ledger` addresses are [generated automatically]({{< ref "how-to-create-addresses.md#listing-addresses-in-sequential-wallets" >}}) by the wallet. - -{{}} -Please note that `random` wallets are considered **deprecated** and should not be used by new applications. -{{}} - -Note also that you can have many wallets being operated by a single `cardano-wallet` server. - -See more on [HD wallets]({{< ref "hierarchical-deterministic-wallets.md" >}}) and [addresses]({{< ref "addresses-byron.md" >}}). diff --git a/user-guide/content/docs/common-use-cases/how-to-create-addresses.md b/user-guide/content/docs/common-use-cases/how-to-create-addresses.md deleted file mode 100644 index 38fdeb5..0000000 --- a/user-guide/content/docs/common-use-cases/how-to-create-addresses.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -weight: 3 -title: How to "create" addresses ---- - -{{}} - -{{}} -{{}} -**Difficulty:** beginner - -**Requires:** -- 📦 cardano-wallet >= `v2020-04-01` -{{}} - -Once you have a wallet you can manage your funds. In order to receive a transaction you need to provide an address associated with your wallet to the sender. - -## 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 user needs 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) - -In order to list existing addresses another endpoint can be used. - -[`GET /byron-wallets/{walletId}/addresses`](https://input-output-hk.github.io/cardano-wallet/api/edge/#operation/listByronAddresses) - - -{{}} -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) {#listing-addresses-in-sequential-wallets} - -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. 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`. - -Therefore, address management is entirely done by the server and users aren't allowed to fiddle 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 that there's always `address_pool_gap` consecutive unused addresses available (where `address_pool_gap` can be configured when a wallet is first restored / created). -{{}} - -{{}} -Alternatively, this endpoint can also be reached from the command-line: - -``` -$ cardano-wallet address list WALLET_ID -``` -{{}} - - -{{}} -Coming soon. -{{}} - -{{}} diff --git a/user-guide/content/docs/installation.md b/user-guide/content/docs/installation.md deleted file mode 100644 index e8f0a3c..0000000 --- a/user-guide/content/docs/installation.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -weight: 3 -title: Installation Instructions ---- - -## Using Docker (recommended) - -Docker images are continuously built and deployed on [dockerhub](https://hub.docker.com/u/inputoutput) under specific tags. Using docker provides **the fastest** and **easiest** user experience for setting up the Cardano stack. You should prefer this solution over building from sources unless you have really good reasons not to. The following images are available for each component of the Adrestia architecture: - -| Repository | Tags | Documentation | -| :--- | :---: | :---: | -| [inputoutput/cardano-node][inputoutput-cardano-node] | `master`, `MAJ.MIN.PATCH`, `latest` | [link][doc-cardano-node] | -| [inputoutput/cardano-db-sync][inputoutput-cardano-db-sync] | `master`, `MAJ.MIN.PATCH`, `latest` | [link][doc-cardano-db-sync] | -| [inputoutput/cardano-graphql][inputoutput-cardano-graphql] | `master`, `MAJ.MIN.PATCH`, `latest` | [link][doc-cardano-graphql] | -| [inputoutput/cardano-explorer-api][inputoutput-cardano-explorer-api] | `master`, `MAJ.MIN.PATCH`, `latest` | [link][doc-cardano-rest] | -| [inputoutput/cardano-submit-api][inputoutput-cardano-submit-api] | `master`, `MAJ.MIN.PATCH`, `latest` | [link][doc-cardano-rest] | -| [inputoutput/cardano-wallet][inputoutput-cardano-wallet] | `byron`, `YYYY.MM.DD-byron`, `latest` | [link][doc-cardano-wallet] | - -### Semantic - - -| Tag | Semantic | -| --- | --- | -| `latest` | Points to the latest __stable__ image for the corresponding component. This is also the tag to which `docker` defaults when pulling without an explicit tag. These typically points to latest known release which happens at the end of an iteration cycle. Depending on which project / component, the iteration cycle may vary from 1 to 2 weeks. -| `MAJ.MIN.PATCH` or `YYYY.MM.DD-byron` | Must match actual releases of the corresponding component. Refer to each component release notes to know which release tags are available. | -| `master` | Points to the very tip of the development branch. This is therefore __not recommended__ for production but can be useful to try out features before they are officially released. | -| `byron` | A special tag pointing to the very tip of the development branch on `cardano-wallet`. `cardano-wallet` does support both `jörmungandr` and `cardano-node` at the same time, but corresponding images are packaged separately. The `byron` tag therefore points to a version of `cardano-wallet` compatible with cardano-node in OBFT mode. | - -### Examples - -For example, in order to use `cardano-node@1.10.0`, one can simply run: - -``` -docker pull inputoutput/cardano-node:1.10.0 -``` - -Similarly, one can pull `cardano-wallet@v2020-04-07` with: - -``` -docker pull inputoutput/cardano-wallet:v2020.4.7-byron -``` - -{{}} -ℹ️ _About version compatibility_ - -For version compatibility between components, please refer to compatibility matrix on each component main page (e.g. [cardano-wallet#latest-releases](https://github.com/input-output-hk/cardano-wallet#latest-releases)). -{{}} - -### Docker compose - -Some components also provide example setup via [docker-compose](https://docs.docker.com/compose/). Those are useful for a quick start or as a baseline for development. See for example [cardano-wallet](https://github.com/input-output-hk/cardano-wallet/blob/master/docker-compose.yml), [cardano-graphql](https://github.com/input-output-hk/cardano-graphql/blob/master/docker-compose.yml) or [cardano-rest](https://github.com/input-output-hk/cardano-rest/blob/master/docker-compose.yml). - -## Pre-compiled Artifacts / Building From Sources - -In case you prefer using raw binary instead, some components do provide pre-compiled release artifacts for each release. These can be downloaded directly from the github servers, via the UI or using a command-line tool like `wget` or `cURL`. For example, one can download a pre-packaged linux binary for `cardano-wallet@v2020-04-07` via: - -``` -curl -L https://github.com/input-output-hk/cardano-wallet/releases/download/v2020-04-07/cardano-wallet-v2020-04-07-linux64.tar.gz | tar xz - -./cardano-wallet-byron-linux64/cardano-wallet --help -The CLI is a proxy to the wallet server, which is required for most commands. -Commands are turned into corresponding API calls, and submitted to an -up-and-running server. Some commands do not require an active server and can be -run offline (e.g. 'mnemonic generate'). - -[...] -``` - -If you feel brave enough and want to compile everything from sources, please refer to each repository's documentation. As a pre-requisite, you may want to install and configure [Nix](https://nixos.org/), [stack](https://docs.haskellstack.org/en/stable/README/) or [cabal](https://www.haskell.org/cabal/) depending on your weapon of choice. Build instructions are available on each repository's main README. - -Repository | Releases | Linux | MacOS | Windows | ---- | --- | --- | -- | --- | -[cardano-node][cardano-node] | [releases][release-cardano-node] | ✔️ | ✔️ | ✔️ | -[cardano-db-sync][cardano-db-sync] | [releases][release-cardano-db-sync] | ✔️ | ✔️ | ❌ | -[cardano-submit-api][cardano-rest] | [releases][release-cardano-rest] | ✔️ | ✔️ | ❌ | -[cardano-explorer-api][cardano-rest] | [releases][release-cardano-rest] | ✔️ | ✔️ | ❌ | -[cardano-graphql][cardano-graphql] | [releases][release-cardano-graphql] | ✔️ | ✔️ | ❌ | -[cardano-wallet][cardano-wallet] | [releases][release-cardano-wallet] | ✔️ | ✔️ | ✔️ | - -[cardano-node]: https://github.com/input-output-hk/cardano-node -[cardano-db-sync]: https://github.com/input-output-hk/cardano-db-sync -[cardano-rest]: https://github.com/input-output-hk/cardano-rest -[cardano-graphql]: https://github.com/input-output-hk/cardano-graphql -[cardano-wallet]: https://github.com/input-output-hk/cardano-wallet - -[release-cardano-node]: https://github.com/input-output-hk/cardano-node/releases -[release-cardano-db-sync]: https://github.com/input-output-hk/cardano-db-sync/releases -[release-cardano-rest]: https://github.com/input-output-hk/cardano-rest/releases -[release-cardano-graphql]: https://github.com/input-output-hk/cardano-graphql/releases -[release-cardano-wallet]: https://github.com/input-output-hk/cardano-wallet/releases - -[cardano-node]: https://github.com/input-output-hk/cardano-node -[cardano-db-sync]: https://github.com/input-output-hk/cardano-db-sync -[cardano-explorer-api]: https://github.com/input-output-hk/cardano-rest -[cardano-submit-api]: https://github.com/input-output-hk/cardano-rest -[cardano-graphql]: https://github.com/input-output-hk/cardano-graphql -[cardano-wallet]: https://github.com/input-output-hk/cardano-wallet - -[doc-cardano-node]: https://github.com/input-output-hk/cardano-node/blob/master/nix/docker.nix#L1-L25 -[doc-cardano-db-sync]: https://github.com/input-output-hk/cardano-db-sync/blob/master/nix/docker.nix#L1-L35 -[doc-cardano-rest]: https://github.com/input-output-hk/cardano-rest/wiki/Docker -[doc-cardano-graphql]: https://github.com/input-output-hk/cardano-graphql/wiki/Docker -[doc-cardano-wallet]: https://github.com/input-output-hk/cardano-wallet/wiki/Docker -[inputoutput-cardano-node]: https://hub.docker.com/r/inputoutput/cardano-node -[inputoutput-cardano-db-sync]: https://hub.docker.com/r/inputoutput/cardano-db-sync -[inputoutput-cardano-graphql]: https://hub.docker.com/r/inputoutput/cardano-graphql -[inputoutput-cardano-submit-api]: https://hub.docker.com/r/inputoutput/cardano-submit-api -[inputoutput-cardano-explorer-api]: https://hub.docker.com/r/inputoutput/cardano-explorer-api -[inputoutput-cardano-wallet]: https://hub.docker.com/r/inputoutput/cardano-wallet diff --git a/user-guide/content/docs/key-concepts/_index.md b/user-guide/content/docs/key-concepts/_index.md deleted file mode 100644 index 7d104ce..0000000 --- a/user-guide/content/docs/key-concepts/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Key Concepts -weight: 5 ---- diff --git a/user-guide/content/docs/migrating-from-sl.md b/user-guide/content/docs/migrating-from-sl.md deleted file mode 100644 index 27b50cf..0000000 --- a/user-guide/content/docs/migrating-from-sl.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -weight: 5 -title: Migrating From SL ---- - -## I am using _explorer_ from _cardano-sl_, what should I do? - -The API from the old explorer has been ported identically to _cardano-submit-api_. This component is part of [cardano-rest]. Source code that is dealing with the _explorer_ API from _cardano-sl_ should be straightforward to migrate. See the installation instructions and documentation available on _cardano-rest_ for more details. - -The setup is here a bit different. With _cardano-sl_, the explorer is mounted directly on the core node as one monolith and can be turned on and off. Now, these components have been split off one another and are using an extra middleware to communicate. So the "infrastructure" is slightly more complex but enables greater flexibility and robustness. - -{{}} -It is possible to automatically migrate an existing blockchain database from _cardano-sl_ into its new format compatible with _cardano-node_. For this, have a look at the [db-converter][db-converter] and in particular, the `convert` command: - -``` -$ db-converter convert --help -Usage: db-converter convert --epochDir STRING --dbDir STRING --epochSlots WORD64 - -Available options: - -h,--help Show this help text - --epochDir STRING Path to the directory containing old epoch files - --dbDir STRING Path to the new database directory - --epochSlots WORD64 Slots per epoch -``` - -> ℹ️ On Byron, the number of slots per epoch is fixed to `21600`. - -This can save you an hour of time downloading the blockchain from the network! - -Build it with [Nix](https://nixos.org/download.html) as follows: - -``` -$ git clone https://github.com/input-output-hk/ouroboros-network -$ cd ouroboros-network -$ nix-build -A haskellPackages.ouroboros-consensus-byron.components.exes.db-converter -o db-converter -$ ./db-converter/bin/db-converter --help -``` - -[db-converter]: https://github.com/input-output-hk/ouroboros-network/tree/master/ouroboros-consensus-byron -{{}} - - -## I am using _wallet V1_ from _cardano-sl_, what should I do? - -A new `V2` API is now available on [cardano-wallet][cardano-wallet]. In a similar fashion to _cardano-rest_, this component used to be mounted directly on the core node but is now an independent process. The _cardano-wallet_ is nothing more than a webserver that connects to a local core node through a domain socket. - -There are some variations between the `V2` and `V1` APIs of course, but they follow a very similar approach and are still very resource-centric (a.k.a ReST). _cardano-wallet_ is however a quite large component, that covers multiple networks and node backends. If you're coming from sl, you're most likely interested in _cardano-wallet-byron_ at the moment which is integrated with a Byron-reboot OBFT _cardano-node_. Follow setup instructions on _cardano-wallet_'s README and Wiki. - -The API documentation is available in [API References]({{< ref "api-references.md" >}}). Note that only the _Legacy_ sub-part of the API matters at this stage. The _Shelley_ part is not available on the Byron integration but can be looked up as a reference for future integration. - -{{}} -_cardano-sl_ had the concept of "accounts" inside wallets. This concepts is now entirely gone. If you need multiple accounts, use multiple wallets. -{{}} - -## I am using _wallet V0_ from _cardano-sl_, what should I do? - -You are going to have a harder time migrating to _cardano-wallet_. The gaps between `V0` and `V2` are obviously bigger, but everything from the previous section applies. **Good luck**. - ---- - -

- More questions? Have a look at the }}">FAQ or else, reach out on Github! -

- -[cardano-rest]: https://github.com/input-output-hk/cardano-rest -[cardano-wallet]: https://github.com/input-output-hk/cardano-wallet