├── .readthedocs.yml ├── .sphinx ├── _static │ ├── css │ │ ├── custom.css │ │ └── modified-theme.css │ └── js │ │ └── hotjar.js ├── cardano-logo.png └── requirements.txt ├── README.rst ├── cardano-community ├── ambassadors-program.md ├── cardano-improvement-proposals.md ├── community-generated-content.md ├── get-support.md ├── index.rst └── providing-feedback.md ├── components └── ouroboros.md ├── conf.py ├── explainers ├── cardano-explainers │ ├── chain-of-blocks.png │ ├── data-storage.png │ ├── proof-of-stake.md │ ├── smart-contract-exp.md │ ├── types-of-wallets.md │ ├── what-is-a-blockchain.md │ ├── what-is-a-cryptocurrency.md │ └── why-use-cardano.md └── getting-started-with-cardano │ ├── block_summary.png │ ├── cardano-nodes.md │ ├── how-to-delegate.md │ ├── how-to-purchase-ada.md │ ├── latest_epoch_summary.png │ └── tools.md ├── explore-cardano ├── addresses.md ├── cardano-architecture-overview │ ├── Diagram_DB_Sync@2x.png │ ├── about-db-sync-and-its-components.md │ ├── cardano-db-sync-best-practices.md │ ├── cardano_components_version_main@2x.png │ ├── connection-manager.png │ ├── index.rst │ ├── networking-protocol-design.md │ ├── node-to-client-ipc.png │ ├── node-to-node-ipc.png │ ├── smash-handbook.md │ └── working-with-db-sync.md ├── cardano-fee-structure.md ├── cardano-monetary-policy.md ├── cardano-network.md ├── decentralized-p2p.jpg ├── design-rationale.md ├── federated-p2p.jpg ├── further-reading.md ├── glossary.rst ├── hybrid-p2p.jpg ├── keys.md ├── learn-cardano.md ├── node_data_flow.jpg ├── p2p-networking.md ├── peer-discovery.jpg ├── pledge_formula.png ├── proof-of-stake.md ├── release-notes.md ├── relevant-research-papers-and-specifications.md ├── understanding-consensus.md ├── understanding-pledging-and-rewards.md ├── understanding-the-delegation-mechanism.md ├── what-is-a-cardano-node.md ├── what-is-a-hard-fork-combinator.md └── what-is-a-stakepool.md ├── getting-started ├── 3rd-party-integration │ └── index.rst ├── developers │ └── index.md ├── exchanges │ └── index.md ├── guidelines-for-operating-large-stake-pools │ └── index.md └── stake-pool-operators │ ├── SMASH-metadata-management.md │ ├── creating-a-stake-pool.md │ ├── creating-keys-and-operational-certificates.md │ ├── establishing-connectivity-between-the-nodes.md │ ├── index.rst │ ├── metadata-proxy-servers.md │ ├── metadata.md │ ├── network1.png │ ├── public-stakepools-and-metadata-management.md │ ├── stake-pool-performance.md │ └── stake-pool-ranking.md ├── index.rst ├── install ├── install-node.md └── use-cli.md ├── learn ├── Cardano-keys.md ├── chain-confirmation-v-transaction-confirmation.md ├── pledging-and-delegating-options.md └── types-addresses.md ├── marlowe ├── blockly-contracts.png ├── blockly-eight.png ├── blockly-five.png ├── blockly-four.png ├── blockly-seven.png ├── blockly-six.png ├── blockly.png ├── detail-js-contract.png ├── get-started-blockly.md ├── get-started-haskell.md ├── get-started-js.md ├── haskell-escrow-editor.png ├── haskell-first-window.jpg ├── javascript.jpg ├── landing-page.png ├── marlowe-explainer.md ├── marlowe-get-started.md └── marlowe-lang-guide.md ├── native-tokens ├── exercises.md ├── faqs.md ├── getting-started-with-native-tokens.md ├── getting-started-with-native-tokens │ └── getting-started-with-native-tokens.md ├── index.rst ├── learn-about-native-tokens.md ├── learn-about-native-tokens │ └── learn-about-native-tokens.md ├── min-ada.png ├── minimum-ada-value-requirement.md └── using-the-token-registry │ └── token-registry.md ├── release-information ├── comp-dependencies-new.png ├── comp-matrix.md └── release-notes.md ├── rosetta ├── api-calls-rosetta.md ├── contribute-rosetta.md ├── get-started-rosetta.md └── learn-Rosetta.md └── rt-view └── rt-view.md /.readthedocs.yml: -------------------------------------------------------------------------------- 1 | 2 | version: 2 3 | 4 | sphinx: 5 | configuration: conf.py 6 | 7 | # Optionally set the version of Python and requirements required to build your docs 8 | python: 9 | version: 3.7 10 | install: 11 | - requirements: .sphinx/requirements.txt -------------------------------------------------------------------------------- /.sphinx/_static/css/custom.css: -------------------------------------------------------------------------------- 1 | html, body.wy-body-for-nav, .wy-nav-side, .wy-nav-content-wrap{ 2 | background: #f8f8f5; 3 | } 4 | 5 | body { 6 | font-weight: 300; 7 | } 8 | 9 | body, h1, h2, h3, h4, h5, h6 { 10 | font-family: 'Chivo', sans-serif; 11 | letter-spacing: .03rem; 12 | } 13 | 14 | h1, h2, h3, h4, h5, h6 { 15 | letter-spacing: .05rem; 16 | } 17 | 18 | .icon.icon-home, 19 | h1 { 20 | color:#0033AD 21 | } 22 | 23 | 24 | a { 25 | color:#0a38a6; 26 | } 27 | a:visited { 28 | color:#335cbe; 29 | } 30 | p { 31 | line-height: 28px; 32 | font-weight: 300; 33 | } 34 | 35 | .wy-nav-content { 36 | max-width: 70rem; 37 | } 38 | 39 | .wy-menu-vertical a { 40 | color: #444; 41 | } 42 | .wy-menu-vertical a:hover { 43 | color: #444; 44 | background:#ddd; 45 | } 46 | 47 | .rst-footer-buttons { 48 | margin-top:10rem; 49 | padding-top:1.8rem; 50 | border-top:1px solid #eee; 51 | } 52 | .rst-footer-buttons .btn.btn-neutral { 53 | border:0; 54 | background:transparent !important; 55 | box-shadow:0 0 0 transparent; 56 | padding:0; 57 | } 58 | 59 | .rst-content .section ul, .rst-content .toctree-wrapper ul, .wy-plain-list-disc, article ul ,.rst-content .section ul li, .rst-content .toctree-wrapper ul li, .wy-plain-list-disc li, article ul li { 60 | line-height: 33px; 61 | } 62 | 63 | .wy-menu-vertical li.toctree-l1.current > a { 64 | border: 0; 65 | } 66 | .wy-menu-vertical li.current > a, .wy-menu-vertical li.on a, .wy-menu-vertical li.toctree-l1.current > a { 67 | background: #eee; 68 | border: none; 69 | border-left:#5281f7 5px solid !important; 70 | padding-left: 18px; 71 | } 72 | .wy-menu-vertical li.current { 73 | background: transparent; 74 | } 75 | 76 | .wy-nav-top { 77 | background: linear-gradient(145deg, rgba(255,85,83,1) 0%, rgba(0,51,173,1) 100%); 78 | } 79 | .wy-nav-top a{ 80 | color:white 81 | } 82 | 83 | 84 | .rst-content .note .admonition-title, .rst-content .note .wy-alert-title, .rst-content .seealso .admonition-title, .rst-content .seealso .wy-alert-title, .rst-content .wy-alert-info.admonition-todo .admonition-title, .rst-content .wy-alert-info.admonition-todo .wy-alert-title, .rst-content .wy-alert-info.admonition .admonition-title, .rst-content .wy-alert-info.admonition .wy-alert-title, .rst-content .wy-alert-info.attention .admonition-title, .rst-content .wy-alert-info.attention .wy-alert-title, .rst-content .wy-alert-info.caution .admonition-title, .rst-content .wy-alert-info.caution .wy-alert-title, .rst-content .wy-alert-info.danger .admonition-title, .rst-content .wy-alert-info.danger .wy-alert-title, .rst-content .wy-alert-info.error .admonition-title, .rst-content .wy-alert-info.error .wy-alert-title, .rst-content .wy-alert-info.hint .admonition-title, .rst-content .wy-alert-info.hint .wy-alert-title, .rst-content .wy-alert-info.important .admonition-title, .rst-content .wy-alert-info.important .wy-alert-title, .rst-content .wy-alert-info.tip .admonition-title, .rst-content .wy-alert-info.tip .wy-alert-title, .rst-content .wy-alert-info.warning .admonition-title, .rst-content .wy-alert-info.warning .wy-alert-title, .rst-content .wy-alert.wy-alert-info .admonition-title, .wy-alert.wy-alert-info .rst-content .admonition-title, .wy-alert.wy-alert-info .wy-alert-title { 85 | background: #5281f7; 86 | } 87 | .rst-content .note, .rst-content .seealso, .rst-content .wy-alert-info.admonition, .rst-content .wy-alert-info.admonition-todo, .rst-content .wy-alert-info.attention, .rst-content .wy-alert-info.caution, .rst-content .wy-alert-info.danger, .rst-content .wy-alert-info.error, .rst-content .wy-alert-info.hint, .rst-content .wy-alert-info.important, .rst-content .wy-alert-info.tip, .rst-content .wy-alert-info.warning, .wy-alert.wy-alert-info { 88 | background: #ccd6ee; 89 | } 90 | .wy-menu-vertical header, .wy-menu-vertical p.caption { 91 | color: #ff7676; 92 | } 93 | .rst-content .admonition-todo .admonition-title, .rst-content .admonition-todo .wy-alert-title, .rst-content .attention .admonition-title, .rst-content .attention .wy-alert-title, .rst-content .caution .admonition-title, .rst-content .caution .wy-alert-title, .rst-content .warning .admonition-title, .rst-content .warning .wy-alert-title, .rst-content .wy-alert-warning.admonition .admonition-title, .rst-content .wy-alert-warning.admonition .wy-alert-title, .rst-content .wy-alert-warning.danger .admonition-title, .rst-content .wy-alert-warning.danger .wy-alert-title, .rst-content .wy-alert-warning.error .admonition-title, .rst-content .wy-alert-warning.error .wy-alert-title, .rst-content .wy-alert-warning.hint .admonition-title, .rst-content .wy-alert-warning.hint .wy-alert-title, .rst-content .wy-alert-warning.important .admonition-title, .rst-content .wy-alert-warning.important .wy-alert-title, .rst-content .wy-alert-warning.note .admonition-title, .rst-content .wy-alert-warning.note .wy-alert-title, .rst-content .wy-alert-warning.seealso .admonition-title, .rst-content .wy-alert-warning.seealso .wy-alert-title, .rst-content .wy-alert-warning.tip .admonition-title, .rst-content .wy-alert-warning.tip .wy-alert-title, .rst-content .wy-alert.wy-alert-warning .admonition-title, .wy-alert.wy-alert-warning .rst-content .admonition-title, .wy-alert.wy-alert-warning .wy-alert-title { 94 | background: #ff7676; 95 | } 96 | .rst-content .admonition-todo, .rst-content .attention, .rst-content .caution, .rst-content .warning, .rst-content .wy-alert-warning.admonition, .rst-content .wy-alert-warning.danger, .rst-content .wy-alert-warning.error, .rst-content .wy-alert-warning.hint, .rst-content .wy-alert-warning.important, .rst-content .wy-alert-warning.note, .rst-content .wy-alert-warning.seealso, .rst-content .wy-alert-warning.tip, .wy-alert.wy-alert-warning { 97 | background: #FED8D8; 98 | } 99 | 100 | .rst-content blockquote { 101 | margin-left: 0; 102 | background: rgba(200,220,255,.4); 103 | padding:1rem 1.3rem; 104 | } 105 | 106 | .rst-content div[class^="highlight"], .rst-content pre.literal-block { 107 | border:0; 108 | margin: 1px 0 2rem; 109 | } 110 | .highlight { 111 | background:rgba(115,255,160,.3) ; 112 | } 113 | .rst-content div[class^="highlight"] pre { 114 | padding:1rem 1.3rem; 115 | } 116 | .highlight .s1 { 117 | color: #FF4F4F; 118 | } 119 | 120 | .rst-content code.literal, .rst-content tt.literal { 121 | color: #FF4F4F; 122 | } 123 | .rst-content code, .rst-content tt, code { 124 | background:rgba(115,255,160,.3) ; 125 | border: 0 solid #e1e4e5; 126 | border-radius: 3px; 127 | } 128 | 129 | 130 | .rst-versions { 131 | display: none; 132 | } 133 | 134 | 135 | @media (min-width:768px) { 136 | h1 { 137 | font-size:2.4rem; 138 | } 139 | 140 | .wy-grid-for-nav { 141 | position: relative; 142 | max-width: 100rem; 143 | margin:auto; 144 | } 145 | .wy-nav-side { 146 | 147 | } 148 | } 149 | -------------------------------------------------------------------------------- /.sphinx/_static/css/modified-theme.css: -------------------------------------------------------------------------------- 1 | /** css/yourtheme.css **/ 2 | 3 | /* This line is theme specific - it includes the base theme CSS */ 4 | @import 'theme.css'; /* for the Read the Docs theme */ 5 | -------------------------------------------------------------------------------- /.sphinx/_static/js/hotjar.js: -------------------------------------------------------------------------------- 1 | (function(h,o,t,j,a,r){ 2 | h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)}; 3 | h._hjSettings={hjid:1960619,hjsv:6}; 4 | a=o.getElementsByTagName('head')[0]; 5 | r=o.createElement('script');r.async=1; 6 | r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv; 7 | a.appendChild(r); 8 | })(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv='); 9 | -------------------------------------------------------------------------------- /.sphinx/cardano-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/.sphinx/cardano-logo.png -------------------------------------------------------------------------------- /.sphinx/requirements.txt: -------------------------------------------------------------------------------- 1 | Sphinx==3.1.1 2 | sphinx-intl==2.0.1 3 | transifex-client==0.13.10 4 | testresources==2.0.1 5 | -e git+https://github.com/input-output-hk/sphinx_rtd_theme.git#egg=sphinx_rtd_theme 6 | recommonmark==0.6 7 | ## The following requirements were added by pip freeze: 8 | alabaster==0.7.12 9 | Babel==2.8.0 10 | certifi==2020.4.5.2 11 | chardet==3.0.4 12 | click==7.1.2 13 | sphinxcontrib-mermaid==0.4.0 14 | sphinxemoji==0.1.6 15 | sphinx_markdown_tables==0.0.15 16 | CommonMark==0.9.1 17 | docutils==0.16 18 | future==0.18.2 19 | idna==2.9 20 | imagesize==1.2.0 21 | Jinja2==2.11.2 22 | jsonpointer==2.0 23 | jsonref==0.2 24 | MarkupSafe==1.1.1 25 | Pygments==2.6.1 26 | pytz==2020.1 27 | requests==2.24.0 28 | six==1.15.0 29 | snowballstemmer==2.0.0 30 | sphinxcontrib-websupport==1.2.2 31 | urllib3==1.25.9 32 | sphinx-panels==0.4.1 33 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | Cardano Documentation 3 | ===================== 4 | 5 | This repository has been deprecated. please see https://github.com/input-output-hk/cardano-documentation for the source code to https://docs.cardano.org 6 | 7 | .. raw:: html 8 | 9 |

10 | Documentation Status 11 |

12 | 13 | Welcome to the central hub for Cardano documentation, here you will find content that describes and supports the components and features that are live on Cardano mainnet. 14 | 15 | If you are interested in developing on Cardano, experimenting with the Cardano testnet, or other test development environments, please visit `Cardano Developers `_. 16 | 17 | **Cardano explained** 18 | 19 | Cardano is a decentralized third-generation proof-of-stake blockchain platform and home to the ada cryptocurrency. It is the first blockchain platform to evolve out of a scientific philosophy and a research-first driven approach. 20 | 21 | The Cardano platform has been designed from the ground up and verified by an industry-leading combination of top engineers and academic experts in the fields of blockchain and cryptography. It has a strong focus on sustainability, scalability, and transparency. It is a fully open source project that aims to deliver an inclusive, fair, and resilient infrastructure for financial and social applications on a global scale. One of its primary goals is to bring reliable, secure financial services to those people who do not currently have access. 22 | 23 | Cardano has been designed with security as one of its founding principles. It is written in Haskell, a functional programming language. In a functional language like Haskell, building your system using pure functions is encouraged, which leads to a design where components are conveniently testable in isolation. Furthermore, advanced features of Haskell enable us to employ a whole range of powerful methods for ensuring correctness of the code, such as basing the implementation on formal and executable specifications, extensive property-based testing, and running tests in simulation. 24 | 25 | Cardano is developing a smart contract platform which seeks to deliver more advanced features than any protocol previously developed and will serve as a stable and secure platform for the development of enterprise-level dApps. In the near future, Cardano will use a democratic governance system that allows the project to evolve over time, and fund itself in a sustainable way through a visionary treasury system. 26 | 27 | You can read more about Cardano on the `official Cardano website `_ and watch a summary of the mission of Cardano in this `explainer video `_. If you are looking for a user-friendly wallet for Cardano, please take a look at `Daedalus`_ for a desktop wallet or `Yoroi`_ for a mobile wallet. 28 | 29 | .. note:: 30 | 31 | 32 | .. _Daedalus: https://daedaluswallet.io 33 | .. _Yoroi: https://yoroi-wallet.com 34 | -------------------------------------------------------------------------------- /cardano-community/ambassadors-program.md: -------------------------------------------------------------------------------- 1 | # Ambassadors program 2 | 3 | The Cardano community is privileged to have committed members of our [Ambassadors Program](https://www.cardano.org/ambassadors/) which was established in 2018, and aims to drive the adoption of Cardano, promote awareness, and educate the wider community. If you would like to join this program, please send us an [email](mailto:community@cardanofoundation.org). 4 | -------------------------------------------------------------------------------- /cardano-community/cardano-improvement-proposals.md: -------------------------------------------------------------------------------- 1 | # Cardano Improvement Proposals (CIPs) 2 | 3 | Individuals with improvement proposals for Cardano can structure those thoughts into CIPs (Cardano Improvement Proposals). 4 | 5 | A *CIP* has an expected format: the proposals structure is templated so as to facilitate discussion and reviewing. This makes it so that other community members can jump in and discuss specific improvement proposals or points in a proposal. The proposals and their history are also publicly available and maintained on the Cardano Foundation [CIPs' Github repository](https://github.com/cardano-foundation/CIPs). 6 | For the non-GitHub crowd: an auto-generated companion site *is being worked on* at [cips.cardano.org](https://cips.cardano.org) 7 | 8 | CIPs themselves go through semi-formal processing: CIP Editors (IOHK/CF/EM/Community) hold regular meetings to discuss and review proposals. The meeting notes are [public](https://github.com/cardano-foundation/CIPs/tree/master/BiweeklyMeetings), meetings biweekly. Authors are invited to participate and provide feedback while conversations often happen asynchronously in the Cardano forum [CIPs section](https://forum.cardano.org/c/english/cips/122) and/or in the Github pull requests themselves. 9 | 10 | Think of the CIP repository as a collection of helpful tools - there might be multiple hammers, screwdrivers... maybe some work well together, some do the same things, and some just won't work together: You get to choose which CIPs your implementation aligns with. We expect the community will gravitate towards some more than other, and propose new ones they want to share, and some naturally cluster - emerging behaviors and decentralization! 11 | Keep in mind: A CIP merged into the repository does not constitute any kind of endorsement beyond structural and apparent well-meaning. 12 | 13 | ## In Summary 14 | The CIP process exist to enable, promote and facilitate structured public discussions for **Process**, **Standard** or **Informational** Cardano proposals in a source-controlled, Foundation-managed, GitHub repository. By creating an open-source collection of CIPs with and for the community, we work to empower current and upcoming implementations, and the overall Cardano ecosystem. 15 | For more details, please refer to [CIP1](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0001/CIP-0001.md/). 16 | 17 | 18 | -------------------------------------------------------------------------------- /cardano-community/community-generated-content.md: -------------------------------------------------------------------------------- 1 | # Community content 2 | 3 | Community collaboration is central to the success of Cardano. This page provides some community-generated content that we have gathered and deemed complementary to the content we are producing. As these materials were not produced by IOHK, we cannot verify that their content is fully accurate or completely up-to-date. 4 | 5 | * [CoinCashew Guide: How to build a Cardano Stake Pool](https://www.coincashew.com/coins/overview-ada/guide-how-to-build-a-haskell-stakepool-node) 6 | * [Guild operators guide](https://cardano-community.github.io/guild-operators/#/) 7 | * [big pey's stake pool video tutorials](https://www.youtube.com/playlist?list=PLyThQPJpttTJ4r9wUdlWi1DMty4nAT85d) 8 | * [creating a private testnet using Docker](https://github.com/ItFlyingStart/shelley-private-testnet) 9 | * [useful setup scripts](https://github.com/gitmachtl/scripts/tree/master/cardano) 10 | * [video guide: How to create a Cardano stake pool](https://www.youtube.com/playlist?list=PLyThQPJpttTJ4r9wUdlWi1DMty4nAT85d) 11 | * [building a Cardano stake pool using CNTools](https://www.youtube.com/watch?v=UN4rSRr7LDk&feature=youtu.be) 12 | 13 | 14 | If you have produced material and would like to contribute your content for inclusion on this page, please click "Edit in Github" in the upper-right hand corner and submit an issue or PR. 15 | -------------------------------------------------------------------------------- /cardano-community/get-support.md: -------------------------------------------------------------------------------- 1 | # Getting support 2 | 3 | Your feedback is important because it helps us improve Cardano. We have an active Telegram channel and a dedicated [support page](https://iohk.zendesk.com/) to help you with your issues and questions. 4 | 5 | We are also creating documentation with the support of our pioneers, a small group of stake pool operators. As that documentation is completed, we will add it to the sections on this website. Please remember to check back regularly. 6 | 7 | ## Telegram Channel: Cardano Developers 8 | 9 | You can reach the developers of Cardano directly on the Telegram website. Just join the [@CardanoStakePoolWorkgroup channel](https://t.me/CardanoStakePoolWorkgroup). 10 | 11 | ## Where can I get technical support? 12 | 13 | To contact IOHK Technical Support, please submit a request using the [Submit a request form](https://iohk.zendesk.com/hc/en-us/requests/new). You can also click the Support button at the bottom right of your screen. The request form is better if you have a lot to write. 14 | -------------------------------------------------------------------------------- /cardano-community/index.rst: -------------------------------------------------------------------------------- 1 | =================================== 2 | Contribute to the Cardano Community 3 | =================================== 4 | 5 | .. toctree:: 6 | :maxdepth: 3 7 | :titlesonly: 8 | 9 | providing-feedback 10 | ambassadors-program 11 | community-generated-content -------------------------------------------------------------------------------- /cardano-community/providing-feedback.md: -------------------------------------------------------------------------------- 1 | # Providing feedback 2 | 3 | User feedback is an invaluable and critical aspect of Cardano. Regardless of your experience level, we want to hear about any bugs or usability issues you encounter, or any suggestions for improvement you may have. 4 | 5 | Please raise an issue in the relevant component respository to provide feedback, including as much detail as possible to help our team understand what went wrong or what we could do better. 6 | 7 | We cannot guarantee that feedback provided by other means such as Twitter, Telegram, or the Cardano Forums will be received or actioned, due to the high volume of activity on these channels. 8 | -------------------------------------------------------------------------------- /components/ouroboros.md: -------------------------------------------------------------------------------- 1 | The Ouroboros network component provides the API and documentation describing various levels of the networking layer of the Cardano Shelley implementation. 2 | 3 | > For more information, go to the [GitHub repo ](https://github.com/input-output-hk/ouroboros-network/#ouroboros-network) -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | 2 | 3 | import sys 4 | import os 5 | import sphinx_rtd_theme 6 | import recommonmark 7 | 8 | from recommonmark.transform import AutoStructify 9 | from os.path import abspath, join, dirname 10 | 11 | sys.path.insert(0, abspath(join(dirname(__file__)))) 12 | 13 | # -- RTD configuration ------------------------------------------------ 14 | 15 | on_rtd = os.environ.get("READTHEDOCS", None) == "True" 16 | 17 | # This is used for linking and such so we link to the thing we're building 18 | rtd_version = os.environ.get("READTHEDOCS_VERSION", "latest") 19 | if rtd_version not in ["stable", "latest"]: 20 | rtd_version = "stable" 21 | 22 | # -- Project information ----------------------------------------------------- 23 | 24 | project = 'Cardano Documentation' 25 | copyright = '2020, IOHK' 26 | author = 'IOHK' 27 | 28 | # The full version, including alpha/beta/rc tags 29 | release = '1.0.0' 30 | 31 | 32 | # -- General configuration --------------------------------------------------- 33 | master_doc = 'index' 34 | # Add any Sphinx extension module names here, as strings. They can be 35 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 36 | # ones. 37 | 38 | extensions = [ 39 | "sphinx_rtd_theme", 40 | 'recommonmark', 41 | 'sphinx_markdown_tables', 42 | 'sphinxemoji.sphinxemoji', 43 | "sphinx.ext.autodoc", 44 | "sphinx.ext.autosummary", 45 | "sphinx.ext.intersphinx", 46 | "sphinx.ext.viewcode", 47 | 'sphinx_panels', 48 | ] 49 | 50 | # Add any paths that contain templates here, relative to this directory. 51 | templates_path = ['.sphinx/_templates'] 52 | html_static_path = ['.sphinx/_static'] 53 | 54 | source_suffix = { 55 | '.rst': 'restructuredtext', 56 | '.md': 'markdown', 57 | } 58 | 59 | intersphinx_mapping = { 60 | "cardano-node": ( 61 | "https://cardano.readthedocs.io/projects/cardano-node/en/%s/" 62 | % rtd_version, 63 | None, 64 | ), 65 | } 66 | 67 | # List of patterns, relative to source directory, that match files and 68 | # directories to ignore when looking for source files. 69 | # This pattern also affects html_static_path and html_extra_path. 70 | exclude_patterns = [] 71 | 72 | 73 | # -- Options for HTML output ------------------------------------------------- 74 | 75 | # The theme to use for HTML and HTML Help pages. See the documentation for 76 | # a list of builtin themes. 77 | # 78 | html_theme = "sphinx_rtd_theme" 79 | 80 | html_js_files = [ 81 | 'js/hotjar.js', 82 | ] 83 | 84 | html_theme_options = { 85 | 'logo_only': False, 86 | 'display_version': False, 87 | 'prev_next_buttons_location': 'bottom', 88 | 'style_external_links': False, 89 | 'style_nav_header_background': '#f8f8f5', 90 | # Toc options 91 | 'collapse_navigation': True, 92 | 'sticky_navigation': True, 93 | 'navigation_depth': 4, 94 | 'includehidden': True, 95 | 'titles_only': False 96 | } 97 | 98 | # Add any paths that contain custom static files (such as style sheets) here, 99 | # relative to this directory. They are copied after the builtin static files, 100 | # so a file named "default.css" will overwrite the builtin "default.css". 101 | 102 | html_logo = ".sphinx/cardano-logo.png" 103 | 104 | html_css_files = [ 105 | 'https://fonts.googleapis.com/css2?family=Chivo:wght@300;400;700&display=swap', 106 | 'css/custom.css', 107 | ] 108 | 109 | html_context = { 110 | "display_github": True, # Add 'Edit on Github' link instead of 'View page source' 111 | "github_user": "cardano-foundation", 112 | "github_repo": "docs-cardano-org", 113 | "github_version": "main", 114 | "conf_py_path": "/", 115 | "source_suffix": source_suffix, 116 | } 117 | 118 | # -- Custom Document processing ---------------------------------------------- 119 | 120 | def setup(app): 121 | app.add_config_value('recommonmark_config', { 122 | 'enable_auto_doc_ref': False, 123 | 'enable_auto_toc_tree': False, 124 | }, True) 125 | app.add_transform(AutoStructify) 126 | -------------------------------------------------------------------------------- /explainers/cardano-explainers/chain-of-blocks.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explainers/cardano-explainers/chain-of-blocks.png -------------------------------------------------------------------------------- /explainers/cardano-explainers/data-storage.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explainers/cardano-explainers/data-storage.png -------------------------------------------------------------------------------- /explainers/cardano-explainers/proof-of-stake.md: -------------------------------------------------------------------------------- 1 | # Proof of stake # 2 | 3 | Proof of stake (PoS) is a type of consensus mechanism or protocol that uses the amount of stake (or value) that is held in the system to determine consensus. In essence, a consensus protocol is what controls the laws and parameters that govern the behavior of blockchains, like a type of ruleset to which each network participant adheres. As blockchains are not controlled by any single, central authority, a consensus protocol is used instead to allow distributed network participants to agree on the history of the network captured on the blockchain – to reach consensus on what has happened, and continue from a single source of truth. 4 | 5 | Cardano is built on the ground-breaking proof of stake consensus protocol [Ouroboros](https://iohk.io/en/blog/posts/2020/03/23/from-classic-to-hydra-the-implementations-of-ouroboros-explained/), and the first blockchain consensus protocol to be developed through peer-reviewed research. At the heart of this PoS protocol are stake pools, reliable server nodes that are run by a stake pool operator to which ada holders can delegate their stake. Stake pools are used to ensure that everyone can participate in the protocol, regardless of technical experience or availability to keep a node running. These stake pools focus on maintenance and hold the combined stake of various stakeholders in a single entity. 6 | 7 | ## How does proof of stake compare to proof of work protocols? ## 8 | In contrast, proof of work (PoW) is a synchronous protocol that encourages miners to compete to be the first who can solve any problems within the block. A rewards system is used to incentivize this problem solving. However, this approach comes at a cost, with increased electricity usage and longer time spans to solve problems within the chain. These factors can slow the network down significantly and means it is costly to maintain. 9 | 10 | ## Features of proof of stake ## 11 | One of the key features of PoS is that as a user's value increases, the opportunity to maintain the ledger also increases. This means that the chance to produce new blocks that can be added to the blockchain and timestamped accordingly. The creator of a new block is chosen based on a combination of random selection and a determination of their stake, or wealth. A type of leader election occurs within the chain. It is worth remembering that within a proof of stake protocol, participants accumulate the transaction fees thereby adding to their wealth as they go. This approach encourages steady and stable growth of the blockchain and reduces the instances of stalled transactions that can prevent chain growth. 12 | 13 | ## Primary advantages of proof of stake ## 14 | Some of the primary advantages of PoS over PoW include: 15 | - rigorous security protocols are incorporated into a proof of stake protocol. 16 | - reduced centralization - the risk of centralization is reduced by issuing penalties for selfish practices within the network 17 | - energy efficiency - energy consumption is extremely efficient as a smaller amount of electricity, as well as hardware resources, are needed to produce and run the blockchain. 18 | - cost efficiencies - proof of stake currencies are far more cost effective than those operating on proof of work protocols. 19 | 20 | -------------------------------------------------------------------------------- /explainers/cardano-explainers/smart-contract-exp.md: -------------------------------------------------------------------------------- 1 | ## What is a smart contract? ## 2 | A smart contract is an automated digital agreement, written in code, that tracks, verifies, and executes the binding transactions of a contract between various parties. The transactions of the contract are automatically executed by the smart contract code when predetermined conditions are met. Essentially, a smart contract is a short program whose inputs and outputs are transactions on a blockchain. 3 | 4 | Smart contracts are self executing and reliable and do not require the actions or presence of third parties. The smart contract code is stored on, and distributed across, a decentralised blockchain network, making it transparent and irreversible. 5 | 6 | In summary, smart contracts are immutable as a contract cannot be changed, they are distributable and tamper-proof, fast and cost effective, as there is no middle man which saves money and time, and is safe due to encryption. 7 | 8 | Cardano is introducing smart contract support in 2021. As a multi-functional environment, Cardano will support the development and deployment of smart contracts using such programming languages as: 9 | 10 | - **Plutus** — a purpose-built smart contract development and execution platform. Plutus contracts consist of parts that run on the blockchain (on-chain code) and parts that run on a user’s machine (off-chain or client code). Plutus draws from modern language research to provide a safe, full-stack programming environment based on Haskell, the leading functional programming language. 11 | - **Marlowe** — a domain-specific language (DSL) for writing and executing financial contracts that allows building contracts visually as well as in more traditional code. Financial institutions can use it to develop and deploy custom instruments for their customers and clients, for example. The Marlowe language itself is now embedded in both JavaScript and Haskell offering a choice of editors depending on developers’ preference and skillset. 12 | - **Glow** — a new domain specific language (DSL) for developing decentralized applications (DApps) on blockchain. With [Glow](https://glow-lang.org/), users can write secure DApps ensuring that smart contracts run safely in an adversarial environment. 13 | 14 | #### *Related Topics* 15 | - [Marlowe explainer](https://docs.cardano.org/en/latest/marlowe/marlowe-explainer.html) 16 | -------------------------------------------------------------------------------- /explainers/cardano-explainers/what-is-a-blockchain.md: -------------------------------------------------------------------------------- 1 | ## What is a blockchain? 2 | 3 | A blockchain is a type of database or ledger that is duplicated and distributed to all participants within the blockchain network. It is made up of a set of interconnected nodes that store data or items of value in blocks. These blocks are verified by transactions and linked to each other in chronological order in a chain. Details of these transactions are permanently inscribed in the block and cannot be altered. 4 | 5 | Blockchain technology, otherwise known as distributed ledger technology (DLT), provides a decentralized and accessible data structure for various records. Such records might include financial payment and transaction details, as well as other types of information – from commerce to internet of things (IoT) records. 6 | 7 | As a blockchain stores data in a decentralized manner, it is independent of centralized, controlling entities, or middlemen. This provides enhanced transparency of data storage and its management. An important feature of blockchain is that it stores records immutably, which means that they cannot be changed, forged, or deleted, as this will break the chain of records. 8 | 9 | Blockchain can be compared to a book of permanent records, where every page acts as an information holder. 10 | 11 | ![chain-of-blocks](chain-of-blocks.png) 12 | 13 | Let’s take a closer look at existing data storage solutions to understand the difference between these systems: 14 | 15 | ![data-storage](data-storage.png) 16 | 17 | + **Centralized systems** — all data entries and activities are usually managed using one central server. This increases the risk of a single point of failure, and also means that the controlling entity (such as banks or government institutions, for example) act as decision-makers. 18 | + **Decentralized systems** — generally rely on multiple server nodes, each of which serves a subset of the total end clients. 19 | + **Distributed systems** — all data and records of transactions are encrypted and stored not in one server, but in a system of interconnected, independent nodes and terminals. This ensures independence from centralized entities, transparency, and security. 20 | 21 | Finally, blockchains not only provide an immutable and secure database but also act as a functional environment to transact funds, create digital currencies, and process complex deals using digital agreements ([smart contracts](https://docs.cardano.org/en/latest/explainers/cardano-explainers/smart-contract-exp.html)). 22 | -------------------------------------------------------------------------------- /explainers/cardano-explainers/what-is-a-cryptocurrency.md: -------------------------------------------------------------------------------- 1 | ## What is a cryptocurrency? 2 | 3 | A *cryptocurrency* is a digital asset, which is stored on the ledger and is designed to serve as a medium of exchange for goods or services. It is otherwise called *crypto*. 4 | 5 | Blockchain ledgers serve as the underlying technology for cryptocurrency creation in a decentralized environment. Blockchain protocols use rigorous cryptography techniques to enable the minting (creation) of cryptocurrency and to secure and verify crypto ownership and fund movement records. The price of cryptocurrency is not controlled by a government or centralized financial institution. It is defined by its value, correlation to real-world figures, and is driven by market supply and demand. 6 | 7 | Addresses are used when sending cryptocurrency payments. They are unique identifiers and are represented by a string of numbers and letters that are obtained from the user's public keys. 8 | 9 | ### Ada - the native currency of Cardano 10 | 11 | Each blockchain ledger has its underlying cryptocurrency or native currency. Ada is the native, or principal currency on Cardano. This means that ada is the main payment unit on Cardano; it is accepted as fee-payment, to make deposits, and is also the only currency in which rewards are distributed. 12 | 13 | Lovelace is the smallest denomination of ada. One ada = 1,000,000 lovelaces. Ada has six decimal places, which makes it easily divisible into smaller fractions. 14 | 15 | ### Native tokens ### 16 | 17 | Cardano also supports the creation of native tokens ‒ digital assets that are created for specific purposes. This means that users, developers, and businesses can use the Cardano blockchain to create tokens that represent a footprint of value (whether defined by the community, market state, or self-governed entity). A token can be fungible (replaced) or non-fungible (unique), and act as a payment unit, reward, trading asset, or information holder. 18 | 19 | #### *Related Topics* 20 | - [Cardano monetary policy](https://docs.cardano.org/en/latest/explore-cardano/cardano-monetary-policy.html) 21 | - [Learn about native tokens](https://docs.cardano.org/en/latest/native-tokens/learn-about-native-tokens.html#) 22 | -------------------------------------------------------------------------------- /explainers/getting-started-with-cardano/block_summary.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explainers/getting-started-with-cardano/block_summary.png -------------------------------------------------------------------------------- /explainers/getting-started-with-cardano/cardano-nodes.md: -------------------------------------------------------------------------------- 1 | ## Cardano nodes 2 | 3 | The *Cardano node* is the top-level component within the network. Network nodes connect to each other within the networking layer, which is the driving force for delivering information exchange requirements. This includes new block diffusion and transaction information for establishing a better data flow. Cardano nodes maintain connections with peers that have been chosen via a custom peer selection process. By running a Cardano node, you are participating in and contributing to the network. 4 | 5 | ### How does it work? 6 | 7 | *Stake pools* use the Cardano node to validate how the pool interacts with the network and are responsible for transaction processing and block production. They act as reliable server nodes that hold and maintain the combined stake of various stakeholders in a single entity. 8 | 9 | **Producing a block** 10 | 11 | The goal of blockchain technology is the production of an independently-verifiable and cryptographically-linked chain of records (blocks). A network of block producers works to collectively advance the blockchain. A consensus protocol provides transparency and decides which candidate blocks should be used to extend the chain. 12 | 13 | Submitted valid transactions might be included in any new block. A block is cryptographically signed by its producer and linked to the previous block in the chain. This makes it impossible to delete transactions from a block, alter the order of the blocks, remove a block from the chain (if it already has a number of other blocks following it), or to insert a new block into the chain without alerting all the network participants. This ensures the integrity and transparency of the blockchain expansion. 14 | 15 | **Slots and epochs** 16 | 17 | The Cardano blockchain uses the Ouroboros Praos protocol to facilitate consensus on the chain. Ouroboros Praos divides time into epochs. Each Cardano epoch consists of a number of slots, where each slot lasts for one second. A Cardano epoch currently includes 432,000 slots (5 days). In any slot, zero or more block-producing nodes might be nominated to be the slot leader. On average, one node is expected to be nominated every 20 seconds, for a total of 21,600 nominations per epoch. If randomly elected slot leaders produce blocks, one of them will be added to the chain. Other candidate blocks will be discarded. 18 | 19 | **Slot leader election** 20 | 21 | The Cardano network consists of a number of stake pools that control the aggregated stake of their owners and other delegators, also known as stakeholders. Slot leaders are elected randomly from among the stake pools. The more stake the pool controls, the greater the chance it has of being elected as a slot leader to produce a new block that is accepted into the blockchain. This is the concept of proof-of-stake (PoS). 22 | 23 | **Transaction validation** 24 | 25 | When validating a transaction, a slot leader needs to ensure that the sender has included enough funds to pay for that transaction and must also ensure that the transaction’s parameters are met. Assuming that the transaction meets all these requirements, the slot leader will record it as a part of a new block, which will then be connected to other blocks in the chain. 26 | 27 | #### *Related topics*: 28 | 29 | - [Cardano node](https://docs.cardano.org/en/latest/explore-cardano/what-is-a-cardano-node.html) 30 | - [About the Cardano network](https://docs.cardano.org/en/latest/explore-cardano/cardano-network.html) 31 | - [Operating a stake pool](https://docs.cardano.org/en/latest/getting-started/stake-pool-operators/index.html) 32 | -------------------------------------------------------------------------------- /explainers/getting-started-with-cardano/how-to-delegate.md: -------------------------------------------------------------------------------- 1 | ## How to delegate and earn rewards? 2 | 3 | Ada that is held on Cardano represents its holder’s stake in the protocol. The size of the stake is proportional to the amount of ada held. Users who hold a stake in Cardano can earn passive rewards for validating blocks. 4 | 5 | Since not everyone has the time, knowledge, or resources to run a stake pool, ada holders can delegate their stake to a preferred pool and let an operator maintain their stake on their behalf. This allows everyone to participate in the consensus and earn rewards without having to continuously run the node online. The higher the stake is in a pool, the more rewards will be assigned to its owners. 6 | 7 | > **Note** that you can spend your ada at any time, regardless of how you delegated it. 8 | 9 | Ada holders can delegate their stake using Daedalus or Yoroi wallets. Here are some useful articles to review: 10 | 11 | - [How to choose a stake pool](https://iohk.zendesk.com/hc/en-us/articles/900002174303-How-to-choose-a-stake-pool) 12 | - [How safe is it to delegate to a stake pool?](https://iohk.zendesk.com/hc/en-us/articles/900002046123-How-safe-is-it-to-delegate-to-a-stake-pool-) 13 | - [How to delegate to a stake pool](https://iohk.zendesk.com/hc/en-us/articles/900005718683-How-to-Delegate-to-a-stake-pool) using Daedalus 14 | - [Staking and delegating for beginners](https://forum.cardano.org/t/staking-and-delegating-for-beginners-a-step-by-step-guide/36681) (Daedalus) 15 | - [How to delegate from the Yoroi wallet](https://forum.cardano.org/t/cardano-shelley-how-to-delegate-from-the-yoroi-wallet/38230) 16 | -------------------------------------------------------------------------------- /explainers/getting-started-with-cardano/how-to-purchase-ada.md: -------------------------------------------------------------------------------- 1 | ## How to purchase ada? 2 | 3 | > **Note**: we are not making any investment advice. Please consider conducting your own research and due diligence, or consult your financial advisor before making any investment decisions. 4 | 5 | Like any other cryptocurrency, ada can be purchased using one of the available exchanges. 6 | 7 | We do not recommend any particular exchange, as there are many great options. However, you can find [a list of exchanges listing ADA on Cardano markets.](https://coinmarketcap.com/currencies/cardano/markets/) 8 | 9 | ### Step 1: Download a wallet 10 | 11 | 1. First, you need to download and install a [cryptocurrency wallet](https://docs.cardano.org/en/latest/explainers/cardano-explainers/types-of-wallets.html#where-to-store-ada) that supports ada. 12 | 2. Create a new wallet and name it. 13 | 3. Then, activate your new wallet and ensure to write down your new passwords. Note that your passwords are the only way you can access your wallet; keep them in a safe place and don’t lose them. You will have a spending password (which is the one used for transacting), and a 12- or 24-word passphrase depending on the wallet you chose. 14 | 4. Recreate your passphrase and accept the terms and conditions. The wallet should be now all set. 15 | 5. Click ‘Receive’ and copy a wallet address or download a PDF file with the QR code. You will need to use this address to receive your cryptocurrency later. 16 | 17 | ### Step 2: Choose an exchange 18 | 19 | 1. Explore cryptocurrency exchanges and choose the one that supports ada. 20 | 2. Create an account. To create an account, exchanges typically require such personal information as: 21 | - full name 22 | - address 23 | - email address and phone number 24 | - payment method (to fund your account) 25 | - a document that identifies your personality (passport, driver’s license, ID, etc) 26 | 27 | We recommend setting up 2FA verification for enhanced security and funds safety. It usually takes from several minutes to several days for an account to be activated. This depends on the chosen exchange. 28 | 29 | ### Step 3: Purchase ada 30 | 31 | 1. Sign in to your exchange account. 32 | 2. Select a Buy/Sell option, which is usually at the top menu. 33 | 3. Click Buy, enter ADA (Cardano) as the cryptocurrency you wish to purchase. 34 | 4. Indicate the amount of ada you would like to purchase and select a payment method (whether it is a wire transfer, credit or debit card). Each exchange will offer you available options, please read them carefully and follow the outlined steps. 35 | 5. Confirm your purchase. You will typically have to confirm it via email and enter the 2FA code (in case you have set it up). You will then receive your ada on the exchange account. 36 | 6. Withdraw ada to your personal wallet. If this is the first time you are making a withdrawal, try smaller amounts to verify that everything works. Note that it is highly **not recommended** to store ada (or any other cryptocurrency) on the exchange account. To transfer your ada, choose the ‘Withdraw’ option, paste your wallet address (the one you copied earlier from your wallet) and submit your transfer. 37 | 7. Check you have received your funds. Go to your wallet and check the balance. You can also track recent transactions using different [explorer tools](https://docs.cardano.org/en/latest/explainers/getting-started-with-cardano/tools.html). 38 | 39 | You can now store ada in your personal wallet, transact between different addresses, receive more ada as payment for services (for example), or delegate it to earn rewards. 40 | -------------------------------------------------------------------------------- /explainers/getting-started-with-cardano/latest_epoch_summary.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explainers/getting-started-with-cardano/latest_epoch_summary.png -------------------------------------------------------------------------------- /explainers/getting-started-with-cardano/tools.md: -------------------------------------------------------------------------------- 1 | ## Cardano tracking tools 2 | 3 | Since Cardano is a public blockchain ledger, it is possible to easily track all recent transactions, block details, and epoch data using different tools. 4 | 5 | ### Exploring transactions and blocks 6 | 7 | **Cardano Explorer** 8 | 9 | [Cardano Explorer](https://explorer.cardano.org/en) is a user-oriented tool that fetches data from the main database and reflects it in a straightforward and convenient web interface. 10 | 11 | The Explorer shows the latest epoch details. You can click the latest epoch and see: 12 | 13 | - a number of blocks produced during this epoch 14 | - time the epoch started 15 | - time of last produced block 16 | - number of processed transactions 17 | - total output in ada 18 | 19 | ![epoch_summary](latest_epoch_summary.png) 20 | 21 | Figure 1. Latest epoch summary 22 | 23 | By choosing a specific block, you can explore it in more detail to see its ID, size, epoch and block details, number of included transactions and confirmations: 24 | 25 | ![block_summary](block_summary.png) 26 | 27 | Figure 2. Block summary 28 | 29 | You can also search for specific epochs, transactions or blocks by pasting their IDs in the search field. 30 | 31 | Here is a list of other explorers to consider: 32 | 33 | - [AdaEx](https://adaex.org/) 34 | - [Adatools](https://adatools.io/transactions) 35 | - [Cardanoscan](https://cardanoscan.io/transactions) 36 | - [AdaStat](https://adastat.net/transactions) 37 | 38 | ### Exploring assets 39 | 40 | Cardano supports multi-asset creation and management. To see a list of created assets and tokens, you can use these tools: 41 | 42 | - [Cardano Assets](https://cardanoassets.com/) 43 | - [AdaStat (tokens)](https://adastat.net/tokens) 44 | - [Adatools (tokens)](https://adatools.io/tokens) 45 | - [Cardanoscan (tokens)](https://cardanoscan.io/tokens) 46 | 47 | ### Exploring stake pools 48 | 49 | To find a list of all registered stake pools, their tickers, pool names, and IDs, you can use these tools: 50 | 51 | - [Cardano PoolTool](https://pooltool.io/) 52 | - [ADAtainment](https://www.adatainment.com/index.php?page=home&lang=en) 53 | - [POOLSTATS](https://poolstats.org/#) 54 | - [Adatools (pools)](https://adatools.io/pools) 55 | - [Cardanoscan (pools)](https://cardanoscan.io/pools) 56 | 57 | > Note: IOHK has developed a [stake pool metadata aggregation server](https://docs.cardano.org/en/latest/getting-started/stake-pool-operators/SMASH-metadata-management.html) (SMASH) to provide the community with a list of verified stake pools with valid metadata. Smash is integrated with the Daedalus wallet, and users can see a list of valid stake pools in the delegation center tab. 58 | -------------------------------------------------------------------------------- /explore-cardano/addresses.md: -------------------------------------------------------------------------------- 1 | # Types of addresses 2 | 3 | The addresses are a blake2b-256 hash of the relevant verifying/public keys concatenated with some metadata that can be stored on the Cardano blockchain. Shelley introduces four different types of addresses: 4 | 5 | * Base addresses. 6 | * Pointer addresses. 7 | * Enterprise addresses. 8 | * Reward account addresses. 9 | 10 | In addition to those new addresses, Shelley continues to support bootstrap addresses and script addresses as introduced in Byron. But only the new base and pointer addresses carry stake rights. Therefore, addresses consist of some serialized data specified in the ledger specification that are stored in the blockhain's blocks, e.g. an UtxO address. The serialized data (address) contains the following two parts: 11 | 12 | * Metadata, that is used for interpreting. 13 | * Payload: the raw or encoded data. 14 | 15 | ## Base Addresses 16 | 17 | A base address directly specifies the staking key that should control the stake for the address. The staking rights associated with funds held in this address may be exercised by the owner of the staking key. Base addresses can be used in transactions without registering the staking key in advance. 18 | 19 | The stake rights can only be exercised by registering the stake key and delegating to a stake pool. Once the stake key is registered, the stake rights can be exercised for base addresses used in transactions before or after the key registration. 20 | 21 | ## Pointer Addresses 22 | 23 | A pointer address indirectly specifies the staking key that should control the stake for the address. It references a stake key by a stake key pointer which is a location on the blockchain of the stake key registration certificate for that key. Pointer addresses can be used in transactions even if their target is *not* an active stake key registration. This covers the scenario where the key was unregistered after (or indeed before), the transaction, and also covers pointers to targets that are plainly invalid. The reason for allowing such invalid targets is so that nodes only need to track the currently active stake keys. 24 | 25 | The pointer can be considerably shorter than the hash used in base addresses. There is a subtlety with pointer addresses: 26 | 27 | It might happen that a stake key registration certificate that is referenced by a pointer address might be lost due to a rollback. This should not lead to a loss of funds. To prevent that, the system considers pointer addresses with an invalid pointer to be valid for the purpose of using funds stored therein as inputs for transactions (but ignores them for the purpose of PoS participation). Optionally, a wallet might refuse to create transactions to pointer addresses before the referenced certificate has become immutable, in order to prevent funds from being excluded from the PoS, in the case of rollbacks. 28 | 29 | ## Enterprise Addresses 30 | 31 | Enterprise addresses carry no stake rights and thus using them means that you are opting out of participation in the proof of stake protocol. 32 | 33 | Exchanges or other organizations that control large amounts of ada – but hold it on behalf of other users – may wish to follow a policy of not exercising stake rights. By using enterprise addresses, exchanges can demonstrate that they follow this policy. Since enterprise addresses are not associated with any staking key, they are automatically excluded from the mechanisms that influence the slot leadership schedule. Note that using addresses with no stake rights effectively decreases the total amount of stake, which plays into the hands of the adversary. 34 | 35 | ## Reward Account Addresses 36 | 37 | A reward address is a cryptographic hash of the public staking key of the address. Reward account addresses are used to distribute rewards for participating in the PoS protocol (either directly or via delegation). They have the following properties: 38 | 39 | * account-style accounting is used, not UTxO-style. 40 | * funds cannot be received via transactions. Instead, their balance is only increased when rewards are distributed. 41 | * a one-to-one correspondence exists between registered staking keys and reward account addresses. 42 | 43 | This key is used whenever funds are withdrawn from the address. Furthermore, stake associated with funds in the address contributes to the stake of this key. Just as in the case of enterprise addresses, the staking object for a reward address does not need to contain information. 44 | -------------------------------------------------------------------------------- /explore-cardano/cardano-architecture-overview/Diagram_DB_Sync@2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explore-cardano/cardano-architecture-overview/Diagram_DB_Sync@2x.png -------------------------------------------------------------------------------- /explore-cardano/cardano-architecture-overview/about-db-sync-and-its-components.md: -------------------------------------------------------------------------------- 1 | # About Cardano DB Sync and its components 2 | 3 | [Cardano DB Sync](https://docs.cardano.org/projects/cardano-db-sync/en/latest/) is one of the core components of the Cardano architecture, as it provides a convenient way to find and query historical information from the Cardano blockchain through the use of a Structured Query Language (SQL) relational database. Db Sync connects to the local node as a client and synchronizes with the on-chain activity. The PostgreSQL database then maps the on-chain information to the relational model. 4 | 5 | DB Sync can be used by Cardano users and developers who wish to find out specific details in regards to block production and recent transactions. These details include block information that enables users to follow the chain and explore transactions within blocks, but exclude cryptographic signatures. 6 | 7 | ## Architecture of Cardano DB Sync 8 | 9 | Cardano-db-sync consists of a set of components: 10 | 11 | - `cardano-db` – defines common data types and functions used by any application that needs to interact with the database from Haskell. In particular, it defines the database schema. 12 | - `cardano-db-tool` – a tool used to manage cardano-db-sync databases (create, run, validate and analyze migrations). 13 | - `cardano-db-sync` – acts as a Cardano node, following the chain and inserting data from the chain into a PostgreSQL database. 14 | - `cardano-db-sync-extended` – a relatively simple extension to cardano-db-sync, which maintains an extra table containing epoch data. 15 | - `db-sync-node` – designed to work with a locally running Cardano Node to store data in the PostgreSQL database. 16 | 17 | The two versions `cardano-db-sync` and `cardano-db-sync-extended` are fully compatible and use identical database schemas. The only difference is that the extended version maintains an `Epoch` table, which the non-extended version will also create but *not* maintain. 18 | 19 | The `db-sync-node` is written in a highly modular fashion to allow it to be as flexible as possible. It connects to a locally running cardano-node (i.e. the one connected to other nodes in the Cardano network over the internet with TCP/IP) using a Unix domain socket. Db-sync-node retrieves blocks, updates its internal ledger state, and stores parts of each block in a local PostgreSQL database. 20 | 21 | ### PostgreSQL 22 | 23 | [PostgreSQL](https://www.postgresql.org/) is a generic relational database used for the mapping of on-chain information to a relational model. It addresses specific user needs and requirements using the normalization technique to store relational data without duplication. 24 | 25 | The following diagram outlines the interaction between the system components: 26 | ![db-sync-architecture](Diagram_DB_Sync@2x.png) 27 | 28 | GraphQL and REST API export an interface to the data stored in the database to be accessed from spreadsheets, for example. [Frontend explorer](https://explorer.cardano.org/en) is the most user-oriented tool; it fetches data from the main database and reflects it in a straightforward and convenient web interface. Another component, the [SMASH](https://docs.cardano.org/en/latest/getting-started/stake-pool-operators/SMASH-metadata-management.html) server, aggregates stake pool metadata and provides pool operators and delegators with a list of valid stake pools with verified metadata. 29 | 30 | ### GraphQL API Server (Apollo) 31 | 32 | The GraphQL API provides a query interface to all the blockchain data via GraphQL, which is a convenient choice for client applications based on web technologies (applications written in JavaScript, or any other browser-based languages, for example) that use HTTP/REST APIs to talk to other services. It is an alternative to the database SQL interface. Application developers can choose between SQL and GraphQL for accessing the chain data. 33 | 34 | The implementation of the API is based on the Apollo Server, an open-source, spec-compliant GraphQL server that's compatible with any GraphQL client (including the Apollo Client). 35 | 36 | ### REST API Components 37 | 38 | There are two Cardano components that provide an HTTP REST API for interacting with a local node: 39 | 40 | * A dedicated transaction submission component, which has a single endpoint for submitting transactions. 41 | * A query component to access blockchain data. This is a legacy component provided to aid migration from the Byron era. Any applications currently using it should plan to migrate to the GraphQL API or the SQL interface. 42 | 43 | The rationale for this is that the REST API is deprecated, so there is no reason for new applications to use it for querying chain data. The submission API is, for now, the only HTTP based API for tx submission, as GraphQL does not yet support tx submission, so any application authors that want to use web-tech APIs (rather than scripting APIs or low level or Haskell APIs) can use the REST API for tx submission. 44 | 45 | ### Stake Pool Metadata Aggregation Server (SMASH) 46 | 47 | The purpose of the Stake Pool Metadata Aggregation Server (SMASH) is to aggregate off-chain metadata that stake pools provide when they register on the Cardano blockchain. This metadata includes the name of the stake pool, its ticker name, web homepage, and so on. 48 | 49 | The rationale for a metadata aggregation server in the Cardano architecture is two-fold: 50 | 51 | 1. To keep the stake pool metadata stored off-chain; and 52 | 2. To retain the ability to moderate stake pool metadata, without any centralized censor. 53 | 54 | The metadata is hosted off-chain and referred to from the on-chain pool registration. SMASH collects the off-chain data to make it more convenient, performant, and reliable for wallets and other applications to access it. 55 | 56 | The SMASH server also addresses the desire to moderate the content of stake pool metadata without a centralized censoring entity. For example, most wallet users and stake pool operators would like to have the ability to treat stake pool ticker names as if they were unique trademarks. It would be too complex to have a fair, on-chain system to resolve ticker name disputes. Instead of enforcing uniqueness on chain, this can optionally be enforced by filtering as part of metadata aggregation. Multiple aggregation services can be run by different organizations following different policies on filtering stake pool metadata. This enables wallet users and other consumers of stake pool metadata to choose which policy to follow, if any. 57 | 58 | SMASH can be configured with policies to filter out metadata based on block lists or reserved ticker names. Daedalus can be configured to use any SMASH server. 59 | -------------------------------------------------------------------------------- /explore-cardano/cardano-architecture-overview/cardano-db-sync-best-practices.md: -------------------------------------------------------------------------------- 1 | ## Cardano DB Sync Best Practices 2 | 3 | This section outlines some best practices for using the Cardano DB Sync component. 4 | 5 | ### Purpose of Cardano DB Sync 6 | 7 | The cardano-db-sync component is designed to work with a locally running Cardano node. The purpose of Cardano DB Sync is to follow the Cardano chain and fetch information from the chain and an internally-maintained copy of ledger state. Data is then extracted from the chain and inserted into a PostgreSQL database. SQL queries can then be written directly against the database schema or as queries embedded in any language with libraries for interacting with an SQL database. 8 | 9 | Here are some examples of what you can do with a Cardano DB Sync instance on a specific network: 10 | 11 | + Look up details of any block, transaction, address, or stake pool on that network, usually by the hash that identifies that item or the index into another table. 12 | + Get the balance of any stake address for a specific epoch. 13 | + Check the amount of ada that is delegated to each stake pool for a specific epoch. 14 | 15 | For details of sample queries, see [Sample Cardano DB Sync queries](https://docs.cardano.org/en/latest/explore-cardano/cardano-architecture-overview/working-with-db-sync.html#useful-queries). 16 | 17 | **Recommended Hardware for Cardano DB Sync** 18 | 19 | We recommend the following hardware for cardano-db-sync (with both db-sync and the node running on the same machine): 20 | 21 | + A Linux distribution (for example: Debian, Ubuntu, RHEL, CentOS, Arch) 22 | + 8 Gigabytes of RAM 23 | + 2 CPU cores 24 | + 50 Gigabytes or more of disk storage 25 | 26 | The recommended configuration is to have the db-sync and the PostgreSQL server on the same machine. During syncing (where historical data is retrieved from the blockchain) there is a huge amount of data traffic between db-sync and the database. Traffic to a local database is significantly faster than traffic to a database on the local area network (LAN) or remotely to another location. 27 | 28 | To run cardano-db-sync, you first need to have a locally-running cardano-node. For more information, see the [building and running instructions](https://docs.cardano.org/projects/cardano-db-sync/en/latest/getting-started/building-running.html). 29 | 30 | **Sample Cardano DB Sync queries** 31 | 32 | We have compiled a list of sample SQL queries that can be run against the db-sync database. 33 | 34 | These queries are run using the psql executable that is distributed with PostgreSQL. You can connect to the database from the cardano-db-sync git checkout using: 35 | 36 | ``` 37 | PGPASSFILE=config/pgpass-mainnet psql cexplorer 38 | ``` 39 | 40 | Some of these queries have Haskell and Esqueleto equivalents in the file Query.hs and where they exist, the names of those queries are included in parentheses. 41 | 42 | You can find the sample queries in [Working with Cardano DB Sync section](https://docs.cardano.org/en/latest/explore-cardano/cardano-architecture-overview/working-with-db-sync.html#useful-queries). 43 | 44 | 45 | -------------------------------------------------------------------------------- /explore-cardano/cardano-architecture-overview/cardano_components_version_main@2x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explore-cardano/cardano-architecture-overview/cardano_components_version_main@2x.png -------------------------------------------------------------------------------- /explore-cardano/cardano-architecture-overview/connection-manager.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explore-cardano/cardano-architecture-overview/connection-manager.png -------------------------------------------------------------------------------- /explore-cardano/cardano-architecture-overview/node-to-client-ipc.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explore-cardano/cardano-architecture-overview/node-to-client-ipc.png -------------------------------------------------------------------------------- /explore-cardano/cardano-architecture-overview/node-to-node-ipc.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explore-cardano/cardano-architecture-overview/node-to-node-ipc.png -------------------------------------------------------------------------------- /explore-cardano/cardano-fee-structure.md: -------------------------------------------------------------------------------- 1 | ## Cardano transaction fee structure 2 | 3 | Cardano uses a transaction fee system that covers the processing and long term storage cost of transactions. 4 | 5 | The Cardano environment is unique in the way it handles fees, as fees do not go directly to the block producer. Instead, they are pooled and then distributed to all pools that created blocks during an epoch. 6 | 7 | There currently are no fees for the memory cost of tracking the accumulated chain state, in particular UTxO. 8 | 9 | ### Preventing economic attacks 10 | 11 | The Shelley hard fork event meant that the Cardano blockchain moved from federated to a fully decentralized environment, which might increase the incentive for malicious actors to perpetrate economic attacks. 12 | 13 | An economic attack might occur where the costs incurred by the operators of a system are not covered by fees on the users of a given system. These situations allow users to impose costs on operators without paying the full cost themselves, which could potentially lead to a severe drop in operator participation, and might ultimately lead to the collapse of the system itself. 14 | 15 | To prevent this situation from arising, it is crucially important to address both the existing unaccounted operator costs and the new costs. 16 | 17 | Cardano's fee structure is quite simple. 18 | 19 | Fees are constructed around two constants (a and b). The formula for calculating minimal fees for a transaction (tx) is a * size(tx) + b, where: 20 | 21 | - a/b are protocol parameters 22 | - size(tx) is the transaction size in bytes 23 | 24 | ### Protocol parameters (a and b) 25 | 26 | Protocol parameters are values that can be altered by Cardano's update system to react and adapt to changes in transaction volume, hardware prices, and ada valuation. Changing these parameters constitutes a hard fork, since it influences which transactions are accepted by the system. 27 | 28 | **Protocol parameter a** 29 | 30 | Parameter a reflects the dependence of the transaction cost on the size of the transaction. The larger the transaction, the more resources are needed to store and process it. 31 | 32 | **Protocol parameter b** 33 | 34 | The value of b is a payable fee, regardless of the size of the transaction. This parameter was primarily introduced to prevent Distributed-Denial-of-Service (DDoS) attacks. b makes such attacks prohibitively expensive, and eliminates the possibility of an attacker generating millions of small transactions to flood and crash the system. 35 | 36 | **Protocol parameter x** 37 | 38 | x represents the size of the transaction in bytes. 39 | -------------------------------------------------------------------------------- /explore-cardano/cardano-monetary-policy.md: -------------------------------------------------------------------------------- 1 | ## Cardano monetary policy 2 | 3 | Cardano aims to achieve true decentralization with the introduction of the Voltaire era later in 2020. Voltaire will include decentralized voting and treasury systems to empower the community to influence Cardano's evolution, and provide a funding mechanism to transform Cardano into a self-funded, self-sustainable environment. 4 | 5 | True decentralization does come with its own set of challenges, as factors such as security, performance, stability, sustainability, fairness, and crucially, economic viability come into play. 6 | 7 | Maintaining, developing, and improving a blockchain project requires ongoing monetary support. When Voltaire is implemented, the Treasury will perform this function, and funding for new features, improvements, etc. will be allocated through a decentralized voting system. 8 | 9 | ### Stake Pools 10 | 11 | The principles of decentralization and fairness drive Cardano's development. Cardano wants to offer equal opportunities to anyone who wishes to become part of the network by running a stake pool. But the very freedom to participate opens up the possibility of unfair advantage posed by larger stake pool operators. This presents the challenge of maintaining the integrity of the chain while incentivizing people to create pools and support the chain. 12 | 13 | ### Incentives Mechanism 14 | 15 | Cardano's monetary expansion relies on a long-term commitment by stake pool operators to provide ongoing support for the chain. This commitment requires a solid and stable incentivization mechanism for the operators, so this mechanism must ensure that the incentive system does not significantly change in time in a way that might adversely affect the operators’ income. 16 | 17 | Cardano's incentive system for stake pool operators is designed to balance k fully saturated pools (where k is the number of desired pools), so this equilibrium means that rewards will be optimal for everybody when all stake is delegated uniformly to the k most attractive pools. 18 | 19 | ### Monetary Policy 20 | 21 | Cardano's monetary policy addresses two issues: 22 | 23 | - The necessity to offer rewards for people who participate in the network 24 | - Funding the treasury 25 | 26 | **Rewards** 27 | 28 | The expansion and future improvement of the Cardano blockchain will be greatly influenced by its community, who need to be incentivized through rewards to participate in Cardano’s development. 29 | 30 | Staking rewards for delegators and stake pool operators come from two sources: 31 | 32 | - Transaction fees - fees from every transaction from all blocks produced during every epoch go into a virtual 'pot'. A fixed percentage (ρ) of the remaining ada reserves is added to that pot. 33 | - Monetary expansion - a certain percentage (τ) of the pot is sent to the treasury, and the rest is used as epoch rewards. 34 | 35 | This system is designed to ensure that the portion of rewards taken from the reserves is high at the beginning, when transaction numbers are still relatively low. This incentivizes early adopters to move quickly to benefit from high initial rewards. Over time, and as the number of transactions increases, additional fees will compensate for smaller reserves. 36 | 37 | This mechanism also ensures that available rewards are predictable and do not vary dramatically. Instead, rewards change gradually. The fixed percentage taken from remaining reserves every epoch guarantees a smooth exponential decline. 38 | 39 | **Funding the Treasury** 40 | 41 | The Treasury's goal is the provision of funds to develop Cardano activities through a voting process. This necessitates a process whereby funds are regularly sent to the Treasury to ensure that funds are always available. 42 | 43 | ### Policy Rationale for the ρ and τ values 44 | 45 | A lot of thought was put into determining what the values for ρ (fixed percentage) and τ (funds going into the Treasury) should be. 46 | 47 | **Calculating ρ** 48 | 49 | While searching for the right ρ value, the team faced a quandary: A higher value would mean higher rewards for everybody initially, and the Treasury would fill faster. But higher values of ρ would also mean that the reserves would deplete faster. Paying high rewards and incentivizing early adopters is a crucial consideration, but so is to offer a long term perspective for all stakeholders. Therefore, the solution to this quandary requires a tradeoff between these two issues. 50 | 51 | Adopting an exponential decay approach to prevent Cardano’s reserve from running out makes sense in this situation. 52 | 53 | Calculating the 'reserve half life' (that is, the time that it takes for half of the reserve to be used up) visualizes the impact of choosing a specific value of ρ over another. This was the subject of much discussion, and eventually, the value assigned was 0.3%. The reason why is that mathematical projections showed that a ρ (the fixed percentage of ada going into the virtual pot every epoch) value of 0.3% would mean a reserve half-life of four to five years. In simple terms, just half of the remaining reserve would be used every four to five years. 54 | 55 | **Choosing τ** 56 | 57 | Determining the right value for τ (the percentage of unclaimed rewards automatically going to the reserves every epoch) was equally challenging. Following discussions, deliberations, and projections, the value chosen was 20%, which means that, initially, 20% of the monetary expansion and the transaction fees are sent to the treasury after each epoch. 58 | -------------------------------------------------------------------------------- /explore-cardano/decentralized-p2p.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explore-cardano/decentralized-p2p.jpg -------------------------------------------------------------------------------- /explore-cardano/design-rationale.md: -------------------------------------------------------------------------------- 1 | ## Cardano design rationale 2 | Cardano has been built as a resilient and sustainable blockchain using the core principles of security, scalability, and interoperability. Fundamentally, it was designed as a proof of stake system which means it is undoubtedly more efficient, by orders of magnitude, than proof of work. Crucially, our ground-breaking proof-of-stake consensus protocol [Ouroboros](https://iohk.io/en/blog/posts/2020/06/23/the-ouroboros-path-to-decentralization/) is proven to have the same security guarantees that proof of work has. 3 | 4 | Formal methods, such as mathematical specifications, property-based tests, and proofs, are the best way to deliver high assurance software systems and give confidence to users for the management of digital funds. Cardano has been built using formal methods to get strong guarantees on the functional correctness of core components of the system. 5 | 6 | Security is one of the founding principles of Cardano. It is written in Haskell, a secure functional programming language. A functional language like Haskell encourages building a system using pure functions, which leads to a design where components are conveniently testable in isolation. Furthermore, advanced features of Haskell enable us to employ a whole range of powerful methods for ensuring correctness of the code, such as basing the implementation on formal and executable specifications, extensive property-based testing, and running tests in simulation. 7 | 8 | For Cardano to deliver a resilient infrastructure on a global scale, it needs to be able to scale on par with legacy financial systems. Even though we have designed Cardano with resource efficiency in mind, scaling remains a fundamental problem for blockchain systems of all kinds. To get towards a solution of the scaling problem, our researchers have invented our scalability solution [Hydra](https://eprint.iacr.org/2020/299.pdf), a protocol that can be executed on top of Cardano, allowing transaction and smart contract processing off the main chain. This will multiply the capacity of the overall system by a multitude. 9 | 10 | Performance engineering was used to assess whether design decisions helped us move closer to the resilience, performance and scalability targets. Distributed systems performance engineering was applied to anticipate and mitigate issues associated with long-term, continuous and scalable operations in a real-world open environment. 11 | 12 | Another major aim in the design of Cardano is to reduce centralization while actively working against economic incentives that would drive the system towards centralization. As soon as you have stake pools, you have an economic incentive for these pools to grow, so it was important to make it less attractive for a stake pool to become too big. It is more cost-efficient to have a small number of large pools, than a large number of small pools. Cardano was designed to work against the economic incentive where large pools dominate the system, by making it less attractive for a pool to become too big. This was achieved by changing the reward formula. In a naive system, the total rewards for a pool would be proportional to its stake, so the bigger it gets, the better. In Cardano, if a pool attracts more stake than a certain threshold (1/k, where k is a configurable parameter), its reward will no longer increase. So, if everyone acts in their own self-interest to maximize their rewards, you expect *k* pools of roughly equal size. 13 | 14 | The ability to interact with other systems, or interoperability, is a fundamental design feature of Cardano. One of the current design innovations in Cardano is the use of sidechains, which means that you can compartmentalize the system and enable interoperability within the blockchain platform. Data can be kept off the main chain in what is called a sidechain. Multiple sidechains can run concurrently, so if one part fails, the rest of the system does not fail, as it is maintained separately. This results in greater assurance and reliability within the blockchain. By using sidechains you can transfer assets between parallel blockchains that operate in different rules, mechanisms or languages and ways of utilizing the network. 15 | 16 | Governance is also central to the design of Cardano to ensure system sustainability and adaptability. A well-developed governance strategy will enable effective, democratic funding for Cardano’s long-term development. The Cardano treasury system is currently being designed as a sustainable funding mechanism to maintain Cardano. It will be controlled by the community and will enable a decentralized, collaborative decision-making process to sustain Cardano’s development and maintenance. Various potential funding sources will be used to refill the treasury on a constant basis, such as the aggregation of newly-minted coins, a percentage of stake pool rewards, transaction fees, and donations or charity. With funds being accumulated in an iterative process, it will be possible to fund the project development and pay for improvement proposals. In addition, Cardano Improvement Proposals (CIPs), will also be delivered to foster and formalize discussions around new features and their development within the community. 17 | 18 | Central to the treasury is a democratized voting mechanism where ada holders will themselves decide how funds are allocated by voting on funding proposals. This will ensure that decisions are made by a democratic vote rather than by just a handful of stakeholders. This voting system will influence decisions such as funding initiatives, authorizing updates to the protocol, and rolling out any constitutional updates such as changes to the decision-making process, or the minting of new tokens. 19 | 20 | 21 | -------------------------------------------------------------------------------- /explore-cardano/federated-p2p.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explore-cardano/federated-p2p.jpg -------------------------------------------------------------------------------- /explore-cardano/further-reading.md: -------------------------------------------------------------------------------- 1 | # Resources 2 | 3 | You may find these web materials and videos useful: 4 | * [Learn about stake pools and delegating stake](https://staking.cardano.org/) 5 | * [What is delegation?](https://youtu.be/BapcrB8xSeI) 6 | * [Proof of stake delegation](https://www.youtube.com/watch?v=Um9RaJVxl6o) 7 | * [Delegation defined](https://www.youtube.com/watch?v=BapcrB8xSeI&feature=youtu.be) 8 | * [What is Ouroboros?](https://www.cardano.org/en/ouroboros/) 9 | * [About Ouroboros and stake pools](https://www.youtube.com/watch?v=ur1lttBXAGM) 10 | * [Incentives in Cardano Presentation](https://static.iohk.io/docs/extra/Incentives-in-Cardano-Presentation.pdf) 11 | * [Understanding Incentives](https://youtu.be/C6DlCL6p_UE) 12 | * [Shelley testnet tutorials](https://github.com/input-output-hk/cardano-tutorials) 13 | 14 | 15 | Blog posts 16 | IOHK’s researchers and engineers often post on [our blog](https://iohk.io/blog). Here are a couple of posts about stake pools and the Shelley testnet which you may find helpful: 17 | * _[From Byron to Shelley: Part one, the testnets](https://iohk.io/en/blog/posts/2020/04/29/from-byron-to-shelley-part-one-the-testnets/)_ - By Kevin Hammond, software engineer at IOHK 18 | * _[From Byron to Shelley: Part two, the journey to mainnet](https://iohk.io/en/blog/posts/2020/05/11/from-byron-to-shelley-part-two-the-journey-to-the-mainnet/)_ - By Kevin Hammond, software engineer at IOHK 19 | * _[How Pledging will keep Cardano healthy](https://iohk.io/en/blog/posts/2020/05/12/how-pledging-encourages-a-healthy-decentralized-cardano-ecosystem/)_ - By Lars Brünjes, director of education at IOHK 20 | * _[Architecting Shelley](https://iohk.io/en/blog/posts/2020/04/07/architecting-shelley-an-interview-with-duncan-coutts-1/)_ - An interview with Duncan Coutts, chief technical architect at IOHK 21 | * _[Stake pools in Cardano](https://iohk.io/en/blog/posts/2018/10/23/stake-pools-in-cardano/)_ - By Professor Aggelos Kiayias, chief scientist at IOHK 22 | * _[What the Byron reboot means for Cardano](https://iohk.io/en/blog/posts/2020/03/30/what-the-byron-reboot-means-for-cardano/)_ - By Tim Harrison, director of communications at IOHK 23 | * _[Ouroboros explained](https://iohk.io/en/blog/posts/2020/03/23/from-classic-to-hydra-the-implementations-of-ouroboros-explained/)_ - By Kieran Costello, technical writer at IOHK 24 | * _[Stake pools in Cardano](https://iohk.io/blog/stake-pools-in-cardano/)_ - By Professor Aggelos Kiayias, chief scientist at IOHK 25 | * _[How Cardano's transaction fees work](https://iohk.io/blog/how-cardanos-transaction-fees-work/)_ - By Lars Brünjes, director of education at IOHK 26 | 27 | related links 28 | - - [Relevant Research Papers and Specifications](relevant-research-papers-and-specifications.md) 29 | -------------------------------------------------------------------------------- /explore-cardano/hybrid-p2p.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explore-cardano/hybrid-p2p.jpg -------------------------------------------------------------------------------- /explore-cardano/keys.md: -------------------------------------------------------------------------------- 1 | # How Keys are used in Cardano 2 | 3 | Keys are asymmetric cryptography key pairs that are used for: 4 | 5 | - Signing and validating payments and staking certificates 6 | - Identifying and defining addresses on the Cardano blockchain. 7 | 8 | ## Types of keys 9 | 10 | There are two main type of keys in Shelley: 11 | * Node keys 12 | * Address keys 13 | 14 | ### Node keys 15 | 16 | Node keys represent the security of the blockchain and consist of the following keys: 17 | * Operator/operational key, operator's offline key pair with cert counter for new certificates. 18 | * Hot KES key, operator's hot KES key pair. 19 | * Block signing key, operational VRF key pair, it participates in the right to create and sign the block for the specific slot. 20 | 21 | ### Address keys 22 | 23 | Address keys represent the functions of the addresses derived from the keys for identifying funds on the blockchain that consist of the following keys: 24 | 25 | Payment key, single address key pair usually used for generating UtxO addresses. 26 | Staking key, stake/reward address key pair usually used for generating account/reward addresses. 27 | -------------------------------------------------------------------------------- /explore-cardano/learn-cardano.md: -------------------------------------------------------------------------------- 1 | Cardano is a third-generation proof-of-stake blockchain platform and home to the ada cryptocurrency that can be used to send and receive digital funds. It is a decentralized platform that is built based on peer-reviewed academic research and designed for sustainability, with security, interoperability, and scalability as its core principles. Cardano has been designed from the ground up and verified by an industry-leading combination of top engineers and academic experts in the fields of blockchain and cryptography. 2 | 3 | Cardano is a fully open source project that aims to deliver an inclusive, fair, and resilient infrastructure for financial and social applications on a global scale. It will augment traditional financial systems and bring reliable, secure financial services to those people who do not currently have access. 4 | -------------------------------------------------------------------------------- /explore-cardano/node_data_flow.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explore-cardano/node_data_flow.jpg -------------------------------------------------------------------------------- /explore-cardano/peer-discovery.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explore-cardano/peer-discovery.jpg -------------------------------------------------------------------------------- /explore-cardano/pledge_formula.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/explore-cardano/pledge_formula.png -------------------------------------------------------------------------------- /explore-cardano/proof-of-stake.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: What is proof of stake? 3 | description: About 4 | parent: 2020-05-04_05-00-00_about-en.md 5 | order: 2 6 | last_updated: "2020-06-26T09:00:00+01:00" 7 | --- 8 | ## What is proof of stake? 9 | Proof of stake is a type of consensus mechanism used to reach agreement on records in the blockchain. It ensures distributed consensus based on the stake, or wealth, that is held by participants in the system. This stake is used as the main resource to determine the participant’s power in the system for maintaining the ledger. 10 | 11 | Ada held on the Cardano network represents a stake in the network, with the size of the stake proportional to the amount of ada held. As a user's value increases, the opportunity to maintain the ledger by producing new blocks also increases. The creator of a new block is chosen randomly, where the probability of a user being chosen is determined by their stake. 12 | 13 | Proof of stake is undoubtedly more efficient, by orders of magnitude, than proof of work as it uses less electricity and computing power. Crucially, our ground-breaking proof-of-stake consensus protocol [Ouroboros](https://iohk.io/en/blog/posts/2020/06/23/the-ouroboros-path-to-decentralization/) is proven to have the same security guarantees that proof of work has. This protocol determines how individual nodes assess the current state of the ledger system and reach a consensus. Rigorous security guarantees are established by Ouroboros and it was delivered with several peer-reviewed papers that were presented in top-tier conferences and publications in the area of cybersecurity and cryptography. Different [implementations of Ouroboros](https://iohk.io/en/blog/posts/2020/03/23/from-classic-to-hydra-the-implementations-of-ouroboros-explained/) have been developed. For further details on each flavour of Ouroboros, you can read the technical specifications for [Classic](https://iohk.io/en/research/library/papers/ouroborosa-provably-secure-proof-of-stake-blockchain-protocol/), [Byzantine Fault Tolerance (BFT)](https://iohk.io/en/research/library/papers/ouroboros-bfta-simple-byzantine-fault-tolerant-consensus-protocol/), [Genesis](https://iohk.io/en/research/library/papers/ouroboros-genesiscomposable-proof-of-stake-blockchains-with-dynamic-availability/), [Praos](https://iohk.io/en/research/library/papers/ouroboros-praosan-adaptively-securesemi-synchronous-proof-of-stake-protocol/), and more recently the scalability solution [Hydra](https://eprint.iacr.org/2020/299.pdf). 14 | 15 | To be secure, Ouroboros requires a good number of ada holders to be online and maintain sufficiently good network connectivity at any given time. A core feature of Cardano are stake pools, operational nodes that are committed to run the protocol 24/7, on behalf of the contributing ada holders who have organized themselves into a combined pool. These reliable block-producing server nodes hold the combined stake of the group of stakeholders in a single entity, the stake pool. Delegation in Cardano is designed in such a way that members of a stake pool retain full control over spending their ada at all times. Stake pools are responsible for processing transactions and producing new blocks and are managed by stake pool operators, who earn rewards in return for their commitment and effort. Stake pool members also receive rewards for contributing to the pool by delegating their stake. 16 | 17 | 18 | -------------------------------------------------------------------------------- /explore-cardano/release-notes.md: -------------------------------------------------------------------------------- 1 | # Release Notes 2 | 3 | The release notes for Cardano releases can be found in the [Updates](https://iohk.zendesk.com/hc/en-us/sections/360002160134-Updates) section of the IOHK support desk. 4 | 5 | ## Latest Cardano component releases 6 | 7 | Name | Version | Release Date 8 | -|-|- 9 | [Cardano Node](https://github.com/input-output-hk/cardano-node) | [1.21.1](https://github.com/input-output-hk/cardano-node/releases/tag/1.21.1) | 7 October 2020 10 | [Cardano DB Sync](https://github.com/input-output-hk/cardano-db-sync/releases) | [5.0.3](https://github.com/input-output-hk/cardano-db-sync/releases/tag/5.0.3) | 22 October 2020 11 | [Smash](https://github.com/input-output-hk/smash) | [1.1.0](https://github.com/input-output-hk/smash/releases/tag/1.1.0) | 10 September 2020 12 | [Cardano Rest](https://github.com/input-output-hk/cardano-rest) | [2.1.3](https://github.com/input-output-hk/cardano-rest/releases/tag/2.1.3) | 5 August 2020 13 | [Cardano GraphQL](https://github.com/input-output-hk/cardano-graphql) | [2.2.0](https://github.com/input-output-hk/cardano-graphql/releases/tag/2.2.0) | 24 September 2020 14 | [Cardano Explorer](https://github.com/input-output-hk/cardano-explorer-app) | [1.2.0](https://github.com/input-output-hk/cardano-explorer-app/releases/tag/1.2.0) | 30 September 2020 15 | [Cardano Transactions](https://github.com/input-output-hk/cardano-transactions) | [1.0.0](https://github.com/input-output-hk/cardano-transactions/releases/tag/1.0.0) | 21 April 2020 16 | [Cardano Addresses](https://github.com/input-output-hk/cardano-addresses) | [2.1.0](https://github.com/input-output-hk/cardano-addresses/releases/tag/2.1.0) | 29 September 2020 17 | [Cardano Coin Selection](https://github.com/input-output-hk/cardano-coin-selection) | [1.0.1](https://github.com/input-output-hk/cardano-coin-selection/releases/tag/v1.0.1) | 13 May 2020 18 | [Bech32](https://github.com/input-output-hk/bech32) | [1.1.0](https://github.com/input-output-hk/bech32/releases/tag/v1.1.0) | 8 July 2020 19 | [Cardano Wallet](https://github.com/input-output-hk/cardano-wallet) | [2020.10.13](https://github.com/input-output-hk/cardano-wallet/releases/tag/v2020-10-13) | 14 October 2020 20 | -------------------------------------------------------------------------------- /explore-cardano/relevant-research-papers-and-specifications.md: -------------------------------------------------------------------------------- 1 | ## Relevant research papers and specifications 2 | 3 | Cardano is a third-generation blockchain platform that aims to provide the community with more advanced features than any protocol yet developed. As a proof-of-stake blockchain, it is built with the rigor of high-assurance formal development methods and aims to achieve the scalability, interoperability, and sustainability needed for real-world applications. Cardano is the first platform to evolve out of scientific philosophy based on discovery, peer review, and cryptographic research. 4 | 5 | Building a strong foundation in the blockchain industry, Cardano has an ethos of openness and transparency. All the [research and technical specifications](https://iohk.io/en/research/library/) that underpin Cardano are publicly published and available to the community. 6 | 7 | Cardano’s development roadmap is divided into 5 eras that focus on the foundation, decentralization, smart-contract and multi-asset ledger deployment, scalability, and governance of a pioneering blockchain environment. Relevant research papers and specifications according to the Cardano development roadmap are outlined below. 8 | 9 | ### Byron 10 | 11 | A period dedicated to building a foundational federated network that enabled the purchase and sale of ada. The network ran the proof-of-stake Ouroboros consensus protocol. 12 | 13 | **Relevant research papers:** 14 | 15 | [Ouroboros: A Provably Secure Proof-of-Stake Blockchain Protocol](https://eprint.iacr.org/2016/889.pdf) 16 | 17 | [Ouroboros-BFT: A Simple Byzantine Fault Tolerant Consensus Protocol](https://eprint.iacr.org/2018/1049.pdf) 18 | 19 | **Relevant specifications:** 20 | 21 | [A Formal Specification of the Cardano Ledger](https://hydra.iohk.io/build/793054/download/1/ledger-spec.pdf) 22 | 23 | [Specification of the Blockchain Layer](https://hydra.iohk.io/build/761704/download/1/blockchain-spec.pdf) 24 | 25 | [Formal Specification for a Cardano Wallet](https://iohk.io/en/research/library/papers/formal-specification-for-a-cardano-wallet/) 26 | 27 | [Cardano on-the-wire Specification](https://hydra.iohk.io/build/3156433/download/1/binary.pdf) 28 | 29 | [Small Step Semantics for Cardano](https://hydra.iohk.io/build/3156322/download/1/small-step-semantics.pdf) 30 | 31 | ### Shelley 32 | 33 | A period of growth and development for the network focused on ensuring greater decentralization, which will lead to enhanced security and a more robust environment once the majority of nodes are run by network participants. 34 | 35 | **Relevant research papers:** 36 | 37 | [Ouroboros Praos: An adaptively-secure, semi-synchronous proof-of-stake blockchain](https://eprint.iacr.org/2017/573.pdf) 38 | 39 | [Ouroboros Genesis: Composable Proof-of-Stake Blockchains with Dynamic Availability](https://eprint.iacr.org/2018/378.pdf) 40 | 41 | [Stake-Bleeding Attacks on Proof-of-Stake Blockchains](https://eprint.iacr.org/2018/248.pdf) 42 | 43 | [Reward Sharing Schemes for Stake Pools](https://arxiv.org/ftp/arxiv/papers/1807/1807.11218.pdf) 44 | 45 | [Account Management in Proof of Stake Ledgers](https://eprint.iacr.org/2020/525.pdf) 46 | 47 | [Flexible Formality: Practical Experience with Agile Formal Methods](https://iohk.io/en/research/library/papers/flexible-formalitypractical-experience-with-agile-formal-methods/) 48 | 49 | [Coalition-Safe Equilibria with Virtual Payoffs](https://arxiv.org/pdf/2001.00047.pdf) 50 | 51 | **Relevant specifications:** 52 | 53 | [Engineering Design Specification for Delegation and Incentives in Cardano–Shelley](https://hydra.iohk.io/build/790053/download/1/delegation_design_spec.pdf) 54 | 55 | [A Specification of the Non-Integral Calculations in the Shelley Ledger](https://hydra.iohk.io/build/3156326/download/1/non-integer-calculations.pdf) 56 | 57 | ### Goguen 58 | 59 | The Goguen era will introduce smart-contract functionality to build decentralized applications while supporting multi-functional assets, fungible, and non-fungible token standards. 60 | 61 | **Relevant research papers:** 62 | 63 | [The Extended UTXO Model](https://iohk.io/en/research/library/papers/the-extended-utxo-model/) 64 | 65 | [UTXOma: UTXO with Multi-Asset Support](https://iohk.io/en/research/library/papers/utxoma-utxo-with-multi-asset-support/) 66 | 67 | [Native Custom Tokens in the Extended UTXO Model](https://iohk.io/en/research/library/papers/native-custom-tokens-in-the-extended-utxo-model/) 68 | 69 | [Functional Blockchain Contracts](https://iohk.io/en/research/library/papers/functional-blockchain-contracts/) 70 | 71 | [Scripting Smart Contracts for Distributed Ledger Technology](https://eprint.iacr.org/2016/1156.pdf) 72 | 73 | [Marlowe: financial contracts on blockchain](https://iohk.io/en/research/library/papers/marlowefinancial-contracts-on-blockchain/) 74 | 75 | [Marlowe: implementing and analysing financial contracts on blockchain](https://iohk.io/en/research/library/papers/marloweimplementing-and-analysing-financial-contracts-on-blockchain/) 76 | 77 | [Unraveling recursion: compiling an IR with recursion to System F](https://iohk.io/en/research/library/papers/unraveling-recursioncompiling-an-ir-with-recursion-to-system-f/) 78 | 79 | [System F in Agda, for fun and profit](https://iohk.io/en/research/library/papers/system-f-in-agdafor-fun-and-profit/) 80 | 81 | ### Basho 82 | 83 | An era of optimization, improving the scalability and interoperability of the network. Enhancing the network performance, Basho will introduce *sidechains*, new blockchains, interoperable with the main Cardano chain, with immense potential to extend the network’s capabilities. 84 | 85 | **Relevant research papers:** 86 | 87 | [Hydra: Fast Isomorphic State Channels](https://eprint.iacr.org/2020/299.pdf) 88 | 89 | [Parallel Chains: Improving Throughput and Latency of Blockchain Protocols via Parallel Composition](https://eprint.iacr.org/2018/1119.pdf) 90 | 91 | [Proof-of-Stake Blockchain Protocols with Near-Optimal Throughput](https://eprint.iacr.org/2020/037.pdf) 92 | 93 | [Ledger Combiners for Fast Settlement](https://eprint.iacr.org/2020/675.pdf) 94 | 95 | [Proof-of-Stake Sidechains](https://eprint.iacr.org/2018/1239.pdf) 96 | 97 | ### Voltaire 98 | 99 | A development era enabling the Cardano network to become a self-sustaining system. Voltaire will introduce a voting and treasury system that will enable network participants to use their stake and voting rights to influence the future development of the blockchain. 100 | 101 | **Relevant research papers:** 102 | 103 | [A Treasury System for Cryptocurrencies: Enabling Better Collaborative Intelligence](https://eprint.iacr.org/2018/435.pdf) 104 | 105 | [Updatable Blockchains](https://eprint.iacr.org/2020/887.pdf) 106 | 107 | -------------------------------------------------------------------------------- /explore-cardano/understanding-consensus.md: -------------------------------------------------------------------------------- 1 | ## Consensus 2 | 3 | Consensus is the process by which a majority opinion is reached by everyone who is involved in running the blockchain. Agreement must be made on which blocks to produce, which chain to adopt, and to determine the single state of the network. The consensus protocol determines how individual nodes assess the current state of the ledger system and reach a consensus. It has three main responsibilities; to perform a leader check and decide if a block should be produced, to handle chain selection, and to verify blocks that are produced. 4 | 5 | Blockchains create consensus by allowing participants to bundle transactions that others have submitted to the system in *blocks*, and add them to their *chain* (sequence of blocks). Determining who is allowed to produce a block when, and what to do in case of conflicts, (such as two participants adding different blocks at the same point of the chain), is the purpose of the different consensus protocols. Our ground-breaking proof-of-stake consensus protocol [Ouroboros](https://iohk.io/en/blog/posts/2020/06/23/the-ouroboros-path-to-decentralization/) is proven to have the same security guarantees that proof of work has. Rigorous security guarantees are established by Ouroboros and it was delivered with several peer-reviewed papers that were presented in top-tier conferences and publications in the area of cybersecurity and cryptography. Different [implementations of Ouroboros](https://iohk.io/en/blog/posts/2020/03/23/from-classic-to-hydra-the-implementations-of-ouroboros-explained/) have been developed. For further details on each flavour of Ouroboros, you can read the technical specifications for [Classic](https://iohk.io/en/research/library/papers/ouroborosa-provably-secure-proof-of-stake-blockchain-protocol/), [Byzantine Fault Tolerance (BFT)](https://iohk.io/en/research/library/papers/ouroboros-bfta-simple-byzantine-fault-tolerant-consensus-protocol/), [Genesis](https://iohk.io/en/research/library/papers/ouroboros-genesiscomposable-proof-of-stake-blockchains-with-dynamic-availability/), [Praos](https://iohk.io/en/research/library/papers/ouroboros-praosan-adaptively-securesemi-synchronous-proof-of-stake-protocol/), and more recently the scalability solution [Hydra](https://eprint.iacr.org/2020/299.pdf). 6 | -------------------------------------------------------------------------------- /explore-cardano/understanding-pledging-and-rewards.md: -------------------------------------------------------------------------------- 1 | ## Pledging and rewards 2 | 3 | Pledging is an important mechanism that encourages the growth of a healthy ecosystem within the Cardano blockchain. When you register a stake pool you can choose to pledge some, or all, of your ada to the pool, to make it more attractive to people that want to delegate. Although pledging is not required when setting up a stake pool, it can make the stake pool more attractive to delegators, as the higher the amount of ada that is pledged, the higher the rewards that will be paid out. The a0 protocol parameter defines the influence of the pledge on the pool reward. 4 | 5 | ## Distributing rewards ## 6 | During each epoch, rewards are distributed amongst all stakeholders who have delegated to a stake pool, either to their own stake pool, or another pool. These rewards are auto-generated by the protocol itself, and are not managed by the stake pool operators. Rewards come from two sources: 7 | * All transaction fees: collated from the set of transactions included in a block that was minted during that epoch. 8 | * Monetary expansion: involves distinguishing between the total supply of ada and the maximal supply of ada. The total supply consists of all ada currently in circulation, as well as the ada in the treasury. The maximal supply is the maximal amount of ada that can ever exist. The difference between these two figures is called the reserve. During each epoch, a fixed, (but parameterizable) percentage of the remaining reserve is taken from the reserve and used for epoch rewards and treasury, where the amount being sent to the treasury is a fixed percentage of the amount taken from the reserve. 9 | 10 | Learn more about rewards sharing in the [Rewards sharing and pledge on Cardano video](https://www.youtube.com/watch?v=EAzyN3H8MOA&t=7s). 11 | 12 | The following formula outlines how the rewards mechanism works. The available rewards amount, transaction fees, plus monetary expansion, is denoted by R. 13 | First, the share of all available rewards that a specific pool can receive is determined, as follows: 14 | 15 | ![pledge formula](pledge_formula.png) 16 | 17 | These elements are defined as follows: 18 | * R - total available rewards for this epoch 19 | * a0 - pledge influence factor (can be between 0 and infinity) 20 | * z0 - relative pool saturation size, i.e. 0.5% based on a number of desired pools (k=200) 21 | * σ - stake delegated to the pool (including stake pledged by the owners and stake delegated by others) 22 | * σ’ = min(σ, z0) - as σ, but capped at z0 23 | * s - stake pledged by the owners 24 | * s’ = min(s, z0) - as s, but capped at z0 25 | 26 | Note that z0, σ and s are all relative, so they are fractions of the total supply, as they all lie between zero and one. 27 | 28 | Two important considerations are: 29 | 1. Rewards increase with σ, but stop increasing once σ reaches z0, that is. once the pool becomes saturated. 30 | 2. If a0, (the pledge influence,) is zero, this formula simply becomes R·σ’, 31 | so it is proportional to pool stake, up to the point of saturation. For larger values of a0, the pledge s becomes more important. 32 | 33 | Remember that the pledge is declared during pool registration, (alongside the cost and margin values), 34 | and has to be honored by the pool owners who are delegating to the pool: 35 | If they collectively delegate less than the declared pledge, pool rewards for that epoch will be zero. Note that the pool will be public, if its operator margin is set to less than 100%. 36 | 37 | The rewards that are produced by this formula are now adjusted by pool performance: 38 | We multiply by β/σ, where β is the fraction of all blocks produced by the pool during the epoch. 39 | 40 | For a perfectly performing pool, one that produces all blocks that it can produce, this factor will be one, on average. The actual value will fluctuate due to the stochastic nature, or random process of the Ouroboros Praos consensus algorithm. 41 | 42 | After pool rewards have been calculated and adjusted for pool performance, they are distributed amongst the pool operator and the pool members, or people who delegated part, or all of their stake, to the pool. This happens in several steps: 43 | 44 | * First, the declared costs are subtracted and given to the pool operator. 45 | * Next, the declared margin is subtracted and given to the pool operator. 46 | * Finally the remainder is split fairly (proportional to delegated stake), amongst all people who delegated to the pool, including the pool owners. 47 | 48 | A pledging calculator is available to use for estimation purposes. The rewards predicted by this calculator *are only an estimate*. The actual amount of ada received in rewards may vary, and will depend on a number of factors including; the actual stake pool performance, that is, the number of blocks a stake pool is observed to produce in a given epoch, versus the number it was expected to produce. Changes to network parameters may also affect rewards. 49 | 50 | The annualized equivalent returns given by this calculator assume that stake is delegated to the same stake pool for a 365-day period, and that stake pool performance and other settings are consistent over that timeframe. IOHK accepts no responsibility for any discrepancy between estimated and actual rewards. 51 | 52 | Disclaimer: this calculator is provided for guidance only. 53 | -------------------------------------------------------------------------------- /explore-cardano/understanding-the-delegation-mechanism.md: -------------------------------------------------------------------------------- 1 | # Delegation 2 | 3 | As Cardano is a proof-of-stake system, owning ada not only allows you to buy goods or services, but also confers upon you the right and obligation to participate in the protocol and create blocks. Delegation of stake is a mechanism inherent in the Cardano proof of stake (PoS) protocol that allows the protocol to scale even in a setting where the set of stakeholders is highly fragmented. 4 | 5 | Anyone who owns ada can participate in the delegation of stake process while retaining their spending power. Note that you can spend your ada normally at any time, regardless of how you delegated it. This mechanism will enable stakeholders to participate in the slot leader election process in each epoch. 6 | 7 | Stake delegation gives rise to “stake pools” that act in the similar way to mining pools in the Bitcoin protocol. Stake pool operators must be online in order to generate blocks when they are selected as slot leaders. 8 | 9 | ## Stake delegation requirements 10 | 11 | Delegating stake requires posting two certificates to the chain: a staking address registration, and a delegation certificate. Posting certificates requires funds, so a user setting up their first wallet will need a bootstrapping mechanism. This mechanism relies on the possibility of base addresses using a staking key before posting the registration certificate for that key. Note that the stake address can be based either on a single key or on a script such as multi-sig. 12 | 13 | ## Delegation scheme 14 | 15 | With the concept of delegation, any stakeholder can allow a stake pool to generate blocks for the Cardano network and then the rewards will be paid by the protocol for all participants including the fees for the stake pool operators. A stake holder delegates to a particular pool ID, which is the hash of the operator's verification key. 16 | 17 | In order to limit the delegate’s block generation power to a certain range of epochs and slots, the stakeholder can limit the proxy signing key’s valid message space to strings ending with a slot number in a specific range of values. This simple scheme is secure due to the verifiability and prevention of misuse properties of proxy signature schemes. This ensures that any stakeholder can verify that a proxy signing key was actually issued by a specific stakeholder to a specific delegate and that the delegate can only use these keys to sign messages inside the key’s valid message space, respectively. 18 | 19 | The funds belonging to one staking key of a user’s wallet requires posting a single transaction, containing a delegation certificate. This will only incur the usual transaction fees. In particular, a stake holder needs to pay a deposit for registering a stake address and not for the stake delegation itself. Once a stake address is registered, the stake holder wiil only pay fees to set the delegation choice. 20 | 21 | Note that the stake holder's stake will count for the pool's stake during the reward calculation. 22 | 23 | ## Stake delegation scenario 24 | 25 | Imagine a user who is about to receive their first ada,for example through redemption, from a trade on an exchange, or some other source. They will set up a new wallet, and create an address to receive those funds. This address will be a base address, using a staking key that is generated by the wallet, but not yet registered on the chain. 26 | 27 | After receiving the initial funds, the user can then participate in staking, by posting a staking key registration certificate, as well as a delegation certificate for their staking key. Once the key is registered, newly created addresses can be pointer addresses to the staking key registration certificate. 28 | -------------------------------------------------------------------------------- /explore-cardano/what-is-a-cardano-node.md: -------------------------------------------------------------------------------- 1 | # Cardano node 2 | 3 | The Cardano node is the core component that underpins the network and enables you to participate in the Cardano decentralised blockchain. Ultimately, a blockchain network is just a collection of interconnected nodes, all working together to validate transactions and blocks by means of consensus. The definition of consensus for any given network varies, but for the Cardano network it is defined by the Ouroboros protocol. By running a Cardano node, you are participating in and contributing to the network. 4 | 5 | This [cardano-node](https://github.com/input-output-hk/cardano-node) is the top level component for the node and aggregates a number of other components from other packages: consensus, ledger and networking, configuration, CLI, as well as logging and monitoring. Note that cardano-node no longer incorporates wallet or explorer functionality. The wallet backend and explorer backend are separate components that run in separate external processes that communicate with the node via local IPC. 6 | 7 | -------------------------------------------------------------------------------- /explore-cardano/what-is-a-hard-fork-combinator.md: -------------------------------------------------------------------------------- 1 | ## About hard forks 2 | 3 | The term hard fork is used to describe a radical change in the blockchain, for example, a change from one protocol to another. In most blockchains, a hard fork indicates block changes or a change to their interpretation. Traditionally, when conducting a hard fork, the current protocol would stop operating, new rules and changes would be implemented, and the chain would restart. It is important to note that a hard-forked chain *will be different* from the previous version and that the history of the pre-forked blockchain will no longer be available. 4 | 5 | The Cardano blockchain has recently hard forked from a Byron federated model to a Shelley decentralized one. However, this hard fork was unique. Instead of implementing radical changes, we ensured a smooth transition to a new protocol while saving the history of the previous blocks. This means that the chain did not change radically, instead, it contains Byron blocks, and after a transition period, adds Shelley blocks. There was no fundamental restart point that erased the history of previous activities. 6 | 7 | ### What is a hard fork combinator? 8 | 9 | A combinator is a technical term used to indicate the combination of certain processes or things. In the case of Cardano, a hard fork combinator combines protocols, thereby enabling the Byron-to-Shelley transition without system interruption or restart. It ensures that Byron and Shelley ledgers appear as one ledger. Shifting from BFT to Ouroboros Praos does not require all nodes to update simultaneously. Instead, nodes can update gradually, in fact, some can run Byron blocks, others - Shelley blocks. 10 | 11 | The hard fork combinator is designed to enable the combination of several protocols, without having to make significant adjustments. The current Cardano chain combines Byron and Shelley blocks, and after future transitions, it will also combine Goguen, Basho, and Voltaire blocks - all as a single property. This combinator facilitates the transition from Shelley to Goguen and beyond by simplifying the previous Byron-to-Shelley evolution. 12 | 13 | ### Moving from Byron Ouroboros Classic to Shelley Ouroboros Praos 14 | 15 | Cardano Byron mainnet ran on the Ouroboros *Classic* consensus protocol. Cardano Shelley mainnet, which is the current development era, transitions to a decentralized network running on the new Ouroboros *Praos* consensus protocol, which allows for more extended capabilities while also supporting the staking process with monetary rewards for ada holders and stake pool owners. 16 | 17 | To enable orderly transitions in Cardano without any diversions in the system, it was necessary to update the code to support the new protocol’s conditions. Doing so in a single update might have caused a range of complexities, so Cardano decided to take a two-stage approach, using the Ouroboros *Byzantine Fault Tolerance* (BFT) protocol as an intermediary. 18 | 19 | A shift from Ouroboros Classic to BFT (that happened on February 20, 2020) is the only traditional hard fork within the Cardano blockchain. This forking event restarted the Byron mainnet to run the BFT protocol and enable a smoother transition to Ouroboros Praos without any further chain interruptions. The BFT protocol was carefully designed so that blockchain history would remain unchanged, and the blockchain would appear as a single entity. 20 | 21 | ### Token locking: Shelley protocol update 22 | 23 | *Token locking* is a new feature that is being added to the Shelley protocol to enable various kinds of smart contract use cases, including creating and transacting with multi-asset tokens, as well as establishing support for the Voltaire voting mechanism. Token locking is the process of ‘reserving’ a certain amount of assets and committing not to dispose of them for a specified period of time. This feature is enabled in the *Allegra* (token locking) upgrade and will allow recording of that a specific token is being used for a certain purpose during the *Mary* (multi-asset support) upgrade. The *token* can represent an item that is accounted for by the blockchain ledger, including ada, but soon will include other custom token types. 24 | 25 | **Token locking use cases** 26 | 27 | Support for token locking is crucial to enable complex deal settlement and funds accounting. It can be used in the following scenarios: 28 | 29 | + **Contractual agreement** - when someone enters into a contractual agreement, to sell a property, for instance, it is important to promise that this property will not be sold to another person – only to the person who actually pays the money. In this case, the token can represent the property and the ‘promise’ – the actual token locking. If the property is sold to a different third party, then the contract becomes void. 30 | + **Vote registry** - within the Voltaire voting mechanism, token locking will enable users to lock a certain amount of their tokens to represent their voting rights. Ada holders who participate in the voting process will be required to ‘lock’ their tokens. This will represent their voting rights, according to the stake that they hold, and eliminate the risks associated with scenarios such as double-counting votes, allocating more votes than possible, contradictory votes, or vote duplication. 31 | + **Multi-asset tokens** - Cardano will soon provide support for multi-asset tokens, where the ledger will support the creation and use of multiple custom token types, besides ada. Token locking will allow ada tokens to be ‘locked’, for example, to create another custom asset of equivalent value. 32 | 33 | **How does it affect the community?** 34 | 35 | The introduction of token locking will not negatively affect general ada holders, since wallets such as Daedalus and Yoroi will update automatically without requiring any action from ada holders. 36 | 37 | All the nodes that are involved in the network maintenance will have to ‘agree’ on this transition to a new protocol, that is, they will need to reach a consensus. Stake pool operators and exchanges that are running nodes will simply have to download the new version of the node software and verify its operation on the Cardano testnet. 38 | 39 | 40 | 41 | 42 | -------------------------------------------------------------------------------- /explore-cardano/what-is-a-stakepool.md: -------------------------------------------------------------------------------- 1 | # Stake pools 2 | 3 | A stake pool is a reliable server node that focuses on ledger maintenance and holds the combined resources, or stake of various stakeholders in a single entity. Stake pools are responsible for processing transactions that will be placed in the ledger, as well as producing new blocks, and are at the core of [Ouroboros](https://iohk.io/en/blog/posts/2020/03/23/from-classic-to-hydra-the-implementations-of-ouroboros-explained/), the Cardano proof-of-stake protocol. 4 | 5 | To be secure, Ouroboros requires a good number of stakeholders to be online and maintain sufficiently good network connectivity at any given time. This is why Ouroboros relies on stake pools, entities that are committed to run the protocol 24/7, on behalf of the contributing stakeholders that hold ada. The idea is that these resource holders can pool their resources, or stake, together and form a pool, where typically one holder is the operator of the pool and the rest are delegators. Typically, the stake pool operator installs and runs the software that is compatible with the platform (the server node), while others are more passive and delegate their resources, or stake, to the pool. 6 | 7 | While Ouroboros is cheaper to run than a proof of work protocol, running Ouroboros still incurs some costs. Therefore, stake pool operators are rewarded for running the protocol in the form of incentives that come from the transaction fees and from inflation of the circulating supply of ada. 8 | -------------------------------------------------------------------------------- /getting-started/3rd-party-integration/index.rst: -------------------------------------------------------------------------------- 1 | Integrating with third parties 2 | ========================================== 3 | 4 | **Note:** Exchanges that are currently listing, or interesting in listing ada, must support a Shelley-supported version of Cardano. 5 | 6 | 7 | **Warning:** Old components like **cardano-sl:node**, **cardano-sl:explorer**, or **cardano-sl:wallet** are no longer supported. 8 | 9 | Only the following components are Shelley compliant and support both the Byron 10 | and Shelley eras: 11 | 12 | - `cardano-node`_ - the latest cardano-node, which supports Ouroboros 13 | Praos. 14 | 15 | - `cardano-db-sync`_ - a necessary middleware to power both 16 | cardano-rest and cardano-graphql. This middleware stores blockchain 17 | data fetched from cardano-node in an intermediate database to enable 18 | higher-level interfaces for blockchain exploration. 19 | 20 | - `cardano-wallet`_ - this API is recommended for 3rd party wallets and 21 | exchanges who do not want to manage UTxOs for transactions 22 | themselves. Use it to send and receive payments from hierarchical 23 | deterministic wallets on the Cardano blockchain via HTTP REST or a 24 | command-line interface. 25 | 26 | - `cardano-rest`_ - is made of two HTTP APIs that are used to retrieve 27 | transactions, addresses, and time periods (epochs and slots) from the 28 | cardano-db-sync component and submit an already serialized 29 | transaction to the network using cardano-explorer-api & 30 | cardano-submit-api respectively. The cardano-submit-api uses the same 31 | API as the cardano-sl:explorer to ease migration from already 32 | integrated clients. New integration should, however, look into 33 | cardano-graphql. 34 | 35 | - `cardano-graphql`_ - the HTTP GraphQL API for Cardano. A more flexible 36 | alternative for blockchain exploration than cardano-rest. 37 | 38 | - `Adrestia libraries`_ - is recommended for larger exchanges who wish to 39 | construct their own wallet scheme and manage UTXOs themselves. This 40 | consists of the following: 41 | 42 | - `cardano-coin-selection`_ 43 | - `cardano-addresses`_ 44 | - `cardano-transactions`_ 45 | - `cardano-serialization-lib`_ 46 | - `bech32`_ 47 | 48 | The only currently available language target is Haskell, although 49 | support for JavaScript is being worked on and should be available soon. 50 | 51 | **Warning:** Adrestia’s components and their respective repositories are also listed on `Github`_. 52 | 53 | .. _cardano-node: https://github.com/input-output-hk/cardano-node 54 | .. _cardano-db-sync: https://github.com/input-output-hk/cardano-db-sync 55 | .. _cardano-wallet: https://github.com/input-output-hk/cardano-wallet 56 | .. _cardano-rest: https://github.com/input-output-hk/cardano-rest 57 | .. _cardano-graphql: https://github.com/input-output-hk/cardano-graphql 58 | .. _Adrestia libraries: https://github.com/input-output-hk/adrestia 59 | .. _cardano-coin-selection: https://github.com/input-output-hk/cardano-coin-selection 60 | .. _cardano-addresses: https://github.com/input-output-hk/cardano-addresses 61 | .. _cardano-transactions: https://github.com/input-output-hk/cardano-transactions 62 | .. _cardano-serialization-lib: https://github.com/Emurgo/cardano-serialization-lib 63 | .. _bech32: https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki 64 | .. _Github: https://github.com/input-output-hk/adrestia/ 65 | -------------------------------------------------------------------------------- /getting-started/developers/index.md: -------------------------------------------------------------------------------- 1 | Getting Started for Developers 2 | ============================== 3 | 4 | Adrestia is a collection of products which makes it easier to integrate with Cardano. It comes in different flavours: SDK or high-level APIs. 5 | 6 | * [Adrestia documentation](../cardano-components/adrestia/README.md) 7 | -------------------------------------------------------------------------------- /getting-started/stake-pool-operators/SMASH-metadata-management.md: -------------------------------------------------------------------------------- 1 | ## SMASH Metadata Management 2 | 3 | SMASH is a metadata aggregation server that manages metadata for stake pools. The functionality provided by SMASH supports stake pool operations and the delegation ecosystem with its standardized framework for listing valid stake pools with verified metadata. 4 | 5 | Each stake pool that participates in the network includes metadata that helps users to make a rational delegation choice. This metadata contains owner details, pool name, pool ticker, homepage, and a short description. It is crucial to ensure that registered stake pools are valid, that they do not duplicate ticker names or trademarks, and do not feature content that users are likely to find offensive. SMASH was designed to improve visibility on verified stake pool information for Cardano users, as well as to enable convenient navigation options. 6 | 7 | A SMASH server can aggregate stake pool metadata, fetch it, and store it in a semi-centralized environment. The server is typically owned by a specific operator, who is then responsible for its maintenance, and can curate and review stake pool metadata. Importantly, it makes it possible to resolve disputes over offending or duplicated stake pool ticker names and delist operators if they are proven to be bad actors. 8 | 9 | The SMASH server code is open source and anyone can deploy it and become an operator. In the due course, Daedalus will allow users to configure any server of their choice and browse custom stake pool lists. 10 | 11 | > If you want to install and run the SMASH server, you can use [these instructions](https://docs.cardano.org/projects/smash/en/latest/getting-started/how-to-install-smash.html). 12 | 13 | ### How does the IOHK SMASH server work? 14 | 15 | The first generation of SMASH is initially deployed by IOHK and is used in the Daedalus delegation center, where it provides the ability to view available stake pools with verified names, ticker symbols, and websites. 16 | 17 | Below is a step-by-step description of actions that can be taken when you identify a pool with a duplicated ticker name or offensive content. Please note that this applies to the SMASH server that is run and maintained by IOHK. 18 | 19 | **Stake pool delisting reasons** 20 | 21 | First, please ensure that there is a reason for a stake pool to be delisted. There are certain reasons that influence the decision for a stake pool to be delisted. These include: 22 | 23 | + **illegal or malicious content**: a stake pool that features any illegal, abusive, or malicious content as part of the stake pool metadata (for example via the link to the SPO’s homepage). 24 | + **impersonation**: stake pools that attempt to impersonate other individuals, groups, or organizations in a manner that misleads, confuses, or deceives others. For example, a successful stake pool called POOL being obviously impersonated by another called P00L (by linking to the same website). 25 | + **previous ‘claim’**: ticker names can be registered by SPOs on a ‘first come - first served’ basis, however, a ticker name which was registered on the Incentivized Testnet (ITN), may only be registered on the Cardano mainnet by the same SPO that registered such a ticker on the ITN. Ticker names that were registered on the ITN but were not re-registered on the Cardano mainnet by 19th June 2020 will be released and available for registration on the Cardano mainnet. 26 | + **an inappropriate ticker name**: a ticker name that is obscene, sexually explicit, offensive, hurtful, profane, or otherwise inappropriate. This is a subjective judgment in some cases, so best efforts will always be made. 27 | + **intellectual property rights (IPR) violations**: SPOs that violate the intellectual property rights of others including copyright and trademarks, where proof can be supplied. 28 | + **inactive or retired pools**: stake pools that are retired or have not produced blocks in a long time, or whose SPO cannot be contacted. Retired pools on the mainnet have a limit of six months within which to make a request for their ticker name to be reregistered. 29 | 30 | **How to request a delisting** 31 | 32 | 1. When you identify a stake pool that you believe should be delisted, you can send an official request for delisting to smash@iohk.io. Please include your rationale and any proof of why this stake pool should be delisted. In particular, state one of the above reasons and provide a detailed explanation. Stake pools impersonating trademarks should be reported by the trademark holder or their authorized representative. 33 | 2. After your request, you will receive an email that acknowledges that your request is taken into consideration. 34 | 3. A SMASH operator will review the request to ensure that the reasoning and proofs are accurate and will make a decision whether or not to delist the stake pool. It may also be determined that further arbitration or community consultation may be required. However, the ultimate decision will always be reserved by the entity operating the SMASH server in question. 35 | 4. When a decision is made, you will receive an email outlining whether the stake pool will be delisted or whether the ticker listing will be allowed to remain. In either case, we shall always provide an explanation or justification for the choice. Please note that in some cases, a stake pool can be delisted proactively - whether temporarily or permanently. With delisting applied, the stake pool will not be visible on SMASH and its operator will need to make a case if they want the decision reversed. 36 | 5. If a stake pool operator believes that delisting of their stake pool has happened by mistake, they can submit an appeal by emailing to smash@iohk.io. 37 | 38 | IOHK’s SMASH operator is constantly reviewing all requests from the Cardano community and SPOs to ensure that all the stake pool information is tracked and managed accurately. A request is usually processed in 7 working days. 39 | 40 | It is important to note that delisting refers *only* to the display of metadata and listing with SMASH. As a decentralized network, at no point, will stake pool operations themselves be affected. For more information or any clarifications, you can email smash@iohk.io, contact @benohanlon in Telegram, or reach out to @benohanlon directly on Twitter. 41 | 42 | 43 | -------------------------------------------------------------------------------- /getting-started/stake-pool-operators/creating-a-stake-pool.md: -------------------------------------------------------------------------------- 1 | ## Creating a stake pool 2 | 3 | ### Prerequisites for stake pool operators 4 | 5 | As a stake pool operator for Cardano, you will typically have the following abilities: 6 | 7 | * operational knowledge of how to set up, run and maintain a Cardano node continuously 8 | * a commitment to maintain your node 24/7/365 9 | * system operation skills 10 | * server administration skills (operational and maintenance). 11 | * experience of development and operations (DevOps) would be very useful 12 | 13 | **Hardware requirements** 14 | 15 | In terms of hardware, you should ensure you have the following: 16 | 17 | * 8 GB of RAM 18 | * 24 GB of hard disk space 19 | * a good network connection and about 1 GB of bandwidth per hour 20 | * a public IP4 address 21 | 22 | Note that processor speed is not a significant factor for running a stake pool. 23 | 24 | ### Stake pool installation instructions 25 | 26 | To learn how to set up your own stake pool, follow the [installing the node from source instructions](https://docs.cardano.org/projects/cardano-node/en/latest/getting-started/install.html). 27 | 28 | You can then proceed with the following operational tasks for managing your stake pool: 29 | 30 | - [Getting configuration files](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/getConfigFiles_AND_Connect.html) 31 | - [Creating keys and addresses](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/keys_and_addresses.html) 32 | - [Creating a simple transaction](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/simple_transaction.html) 33 | - [Registering stake address on the blockchain](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/register_key.html) 34 | - [Generating stake pool keys](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/node_keys.html) 35 | - [Creating an operational certificate with key evolving signature (KES)](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/KES_period.html) 36 | - [Configuring topology files for block-producing and relay nodes](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/core_relay.html) 37 | - [Registering a stake pool with metadata](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/register_stakepool.html) 38 | - [Starting a node](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/start_your_nodes.html) 39 | - [Withdrawing rewards](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/withdraw-rewards.html) 40 | - [Retiring a stake pool](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/retire_stakepool.html) 41 | -------------------------------------------------------------------------------- /getting-started/stake-pool-operators/creating-keys-and-operational-certificates.md: -------------------------------------------------------------------------------- 1 | ## Creating keys and operational certificates 2 | 3 | ### About stake pool operator keys 4 | 5 | It is the responsibility of the operator to manage both the hot (online), and cold (offline) keys for the pool. Cold keys must be secure and should not reside on a device that has internet connectivity. It is recommended that you have multiple backups of your cold keys. 6 | 7 | The keys that you need as a stake pool operator are: 8 | 9 | * stake pool cold key 10 | * stake pool hot key (KES key) 11 | * stake pool VRF key 12 | 13 | The KES key, or hot key as mentioned above, is a node operational key that authenticates who you are. You specify the validity of the KES key using the start time and key period parameters and this KES key needs to be updated every 90 days. The VRF key is a signing verification key and is stored within the operational certificate. You can read more information on these crypto scheme keys in the [Shelley ledger specification](https://hydra.iohk.io/build/5096921/download/1/ledger-spec.pdf). 14 | 15 | >Instructions to create and manage stake pool operation keys: 16 | >- [Creating keys and addresses](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/keys_and_addresses.html) 17 | >- [Creating KES key pair](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/KES_period.html) 18 | >- [Generating stake pool keys](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/node_keys.html) 19 | 20 | ### Creating an operational certificate 21 | 22 | Stake pool operators must provide an operational certificate to verify that the pool has the authority to run. The certificate includes the operator’s signature and important information about the pool (addresses, keys, etc.). 23 | 24 | Operational certificates represent the link between the operator’s offline key and their operational key. A certificate’s job is to check whether or not an operational key is valid, to prevent malicious interference. The certificate identifies the current operational key, and is signed by the offline key. 25 | 26 | Certificates are generated with an issue counter number and included in the header of each block the node generates. This mechanism enables nodes to verify whether a certificate is current, or has already been superseded by a newer one. Certificates include a kes-period (start date), which indicates the time span within which the certificate is valid before you need to create another one. 27 | 28 | >Instructions to work with operational certificates: 29 | >- [Registering stake address and creating a registration certificate](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/register_key.html) 30 | >- [Generating a stake pool registration certificate](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/register_stakepool.html#generate-stake-pool-registration-certificate) 31 | 32 | The counter becomes significant when an attacker has compromised the KES key, in which case the owner of the cold keys can create a new KES key and a new certificate with a higher issue number. If a node sees two blocks claiming to originate from the same cold key, but using different KES keys, the higher issue counter trumps the lower one. 33 | 34 | Certificates are generated on the offline machine using the offline/cold keys, before being copied over to the node to validate the KES keys used to sign the blocks. 35 | 36 | 37 | 38 | 39 | -------------------------------------------------------------------------------- /getting-started/stake-pool-operators/establishing-connectivity-between-the-nodes.md: -------------------------------------------------------------------------------- 1 | ## Establishing connectivity between the nodes 2 | 3 | Nodes connect to each other within the Cardano networking layer, and this connection is essential for information exchange about transactions and new block creation. 4 | 5 | ### Cardano networking 6 | 7 | With Byron, federated nodes were wholly responsible for managing block production and network connections. The Byron network consisted of a set of federated core nodes - static nodes that produced blocks and maintained the Cardano network. With the launch of Shelley, the network runs in a hybrid mode with federated nodes operated by IOG (which configure connections between different stake pool operators) and nodes operated by the SPO community. The percentage of blocks produced by decentralized nodes is constantly growing while federated nodes gradually stop operating, which evenly spreads the network maintenance across all the stake pool operators. Over the lifetime of the Shelley system, the network will transition into full decentralization using continuous automatic discovery and selection of peers. 8 | 9 | During the initial phase, nodes connect to other nodes by means of a static configuration, defined in a topology file. To avoid a situation when relay nodes go offline, which causes the block-producing nodes to be inaccessible, it is crucial to connect to reliable relay nodes. Currently, IOG offers [a list of all registered relays categorized by geographical location](https://explorer.cardano-mainnet.iohk.io/relays/topology.json) for SPOs to consider for connection purposes. It is also recommended that SPOs generate a configuration that uses 20 other SPOs as peers. In practice, many SPOs can use more than 20 peers for connection purposes. The list allows to select peers that are both nearby and far away so that there is strong inter-region connectivity. 10 | 11 | Before the network is moved from federated to fully decentralized, the node’s network layer will be switched to use continuous automatic discovery and peer selection. This will be achieved through upgrades to the network stack. Initially, this will enable improved automation of connecting SPO relays to each other so that less static configuration is needed. Ultimately it will enable a full peer-to-peer (P2P) topology for all Cardano nodes, which will make the network less reliant on IOG-run relays. 12 | 13 | Please follow this link to read more about the [Cardano network](https://docs.cardano.org/en/latest/explore-cardano/cardano-network.html), communication between the nodes, and mini-protocols that enable this functionality. 14 | 15 | ### Connecting core and relay nodes 16 | 17 | As a stake pool operator, you will have two types of nodes: core nodes and relay nodes. Each core node must be accompanied by one or more relay nodes. 18 | 19 | The difference between the two types is that core nodes are responsible for producing blocks, while relays are responsible for communicating with other relays in the network and broadcasting blocks. This difference determines how they are configured and how they are connected to the network. 20 | 21 | A core node is configured with various key-pairs and an operational certificate needed for block generation. It only connects to its relay nodes. 22 | 23 | >Instructions to configure a node and create an operational certificate: 24 | >- [About node configuration files](https://docs.cardano.org/projects/cardano-node/en/latest/getting-started/understanding-config-files.html) 25 | >- [Configuring topology files for block-producing and relay nodes](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/core_relay.html) 26 | >- [Creating an operational certificate with key evolving signature (KES)](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/KES_period.html) 27 | 28 | >Further reading: 29 | >- [Creating keys and operational certificates](https://docs.cardano.org/en/latest/getting-started/stake-pool-operators/creating-keys-and-operational-certificates.html) 30 | 31 | A relay node doesn’t need any keys and will therefore be unable to produce blocks. It is connected to its core node, other relays, and external nodes. 32 | 33 | Each node should run on a dedicated server, and the core node server’s firewall should be configured to only allow incoming connections from its relays. 34 | 35 | ![network](network1.png) 36 | -------------------------------------------------------------------------------- /getting-started/stake-pool-operators/index.rst: -------------------------------------------------------------------------------- 1 | Operating a stake pool 2 | ------------------------------------------ 3 | 4 | This section includes an overview of stake pool operations and explains the ways of creating and managing your own stake pool. 5 | 6 | About stake pools, operators, and owners 7 | ======================================== 8 | 9 | A `stake pool `_ is a reliable server node that holds and maintains the combined stake of various stakeholders in a single entity. Stake pools use the Cardano node to validate how the pool interacts with the network and are responsible for transaction processing and block production. 10 | 11 | Successfully operating a stake pool includes the roles of a stake pool operator and one or more stake pool owner(s). It is important to note that there is a conceptual difference between these two roles: 12 | 13 | + **Stake pool operator** — a person who is assigned responsibility for setting up and keeping the stake pool running, which means that they own or rent a server, hold the key of the stake pool, and hold responsibility for running and monitoring the node. With their key, a stake pool operator can sign blocks, register, re-register, or retire a stake pool, and post updated certificates. A stake pool operator is also empowered to exclude some stake pool owners during re-registration. 14 | + **Stake pool owner** — a person who pledges their stake to the pool to increase the pool’s reward earning capacity and desirability. The ability of the owner to `pledge stake`_ provides protection against Sybil attacks. 15 | 16 | .. _pledge stake: https://docs.cardano.org/en/latest/explore-cardano/understanding-pledging-and-rewards.html 17 | 18 | Usually, the stake pool operator and the owner is the same person, however, a stake pool can also have multiple owners, who pledge their stake to form one larger pool to ensure it is competitive. Even in this case, there is still only one stake pool operator who is responsible for stake pool processes. 19 | 20 | It is essential that all stake pool owners trust a stake pool operator. All operators’ and owners’ rewards are paid out into a single shared reward account associated with the reward address of the pool, and are distributed by the protocol amongst the owner accounts. The reason for this is that otherwise, everyone could choose to become a co-owner of a stake pool instead of delegating, which would render the mechanism of pledging stake ineffective. 21 | 22 | This makes it clear to all parties that an agreement is needed to define when and how the accumulated rewards in a shared account should be split. For example, they can agree to have the operator control the shared account, or they could choose to use a multisig account. 23 | 24 | To run a pool effectively, a bi-directional relationship and trust are crucial. If this trust is broken, other parties can lose in regards to accumulated or potential rewards, or reputation for the operator. 25 | 26 | *Note that to eliminate such a case, it is beneficial for owners and operators to consider entering into contractual arrangements.* 27 | 28 | Setting up and operating a stake pool 29 | ===================================== 30 | 31 | Stake pools are a key part of a decentralized Cardano, supporting the mechanisms that ensure the long-term health and liveness of the network. By running a stake pool, stake pool operators enable other users to participate in the protocol and gain rewards without a need to continuously run an online node. 32 | 33 | .. toctree:: 34 | :maxdepth: 1 35 | :titlesonly: 36 | 37 | creating-a-stake-pool 38 | establishing-connectivity-between-the-nodes 39 | creating-keys-and-operational-certificates 40 | public-stakepools-and-metadata-management 41 | SMASH-metadata-management 42 | stake-pool-performance 43 | stake-pool-ranking 44 | 45 | You can also find out more about `pledging and delegating stake options here. `_ 46 | 47 | 48 | 49 | -------------------------------------------------------------------------------- /getting-started/stake-pool-operators/metadata-proxy-servers.md: -------------------------------------------------------------------------------- 1 | ## Metadata proxy servers 2 | 3 | Wallets do not retrieve metadata from each stake pool at every individual URL, as this could lead to malicious exploitation. For instance, third parties could slow down wallet communication by intentionally delaying the server's response time. To avoid this scenario, metadata uses proxy servers that query the URL included in the registration certificate, and cache the metadata using the pool's secret key. Wallets will simply query these proxy servers to retrieve the metadata for the pools it needs to display, instead of sending a request to each of the pool’s metadata URLs. If the content hash listed on the certificate does not match the content hash of the cached metadata, the cache will be invalidated. 4 | 5 | Proxy servers provide an additional level of security by filtering malicious entries. For example, it is possible to embed malicious content in the metadata, typically in the link to the stake pool’s homepage. If a pool hosts dangerous or illegal content, maintainers of a metadata proxy server can filter that entry and not provide it to wallets. This is a clear advantage over writing the metadata directly to the chain, where there would be no way to protect wallet users from visiting malicious sites directly from their wallet. 6 | 7 | While proxy servers do offer effective protection against malicious interference, they could become a point of centralisation. To avoid this, we will provide third parties (stake pools, community members, etc.) with code and binaries so they can run their own proxy servers and prevent centralization. 8 | -------------------------------------------------------------------------------- /getting-started/stake-pool-operators/metadata.md: -------------------------------------------------------------------------------- 1 | ## Stake pool metadata 2 | 3 | In addition to posting a registration certificate to the blockchain, setting up a stake pool for delegation also involves the provision of metadata, (additional information about the pool). 4 | 5 | The registration certificate contains all the necessary information for the execution of the protocol (public key hashes, cost, margin, relays, and pledge), and also contains a hash of the metadata. 6 | 7 | If metadata is provided, the end users' wallet will display the stake pool. If metadata is not supplied, the stake pool is considered private, and will not be displayed in a user's wallet. 8 | 9 | ### Public stake pools 10 | 11 | If the registration certificate sent by stake pool operators contains metadata, the stake pool is considered to be public. 12 | 13 | Referring to, or pointing to metadata in the stake pool certificate is optional. The certificate might contain a URL of up to 64 bytes in length that points to a JSON object with the following content: 14 | 15 | - A ticker of 3-5 characters, for a compact display of stake pools in a wallet. 16 | - Title/name of up to 50 characters. 17 | - Short textual description 18 | - URL to a homepage with additional information about the pool (optional). 19 | 20 | These are important considerations to note about the metadata: 21 | 22 | - Metadata information is encoded in UTF-8, and will never exceed 512 bytes 23 | - The content hash of the JSON object referenced in the URL (if present), should match the content hash in the registration certificate. If there is a mismatch, the pool will not be displayed in a wallet. 24 | - For the wallet to display the pool, the following conditions must be met: the registration certificate must refer to the metadata, the metadata must be valid and have the - correct content hash, and be available at the URL. It must be possible to get the metadata and validate it. If this process fails, the wallet will not show the pool. 25 | 26 | If a stake pool operator changes the metadata, they must post a new stake pool registration certificate with the new content hash. 27 | 28 | ### Metadata proxy servers 29 | 30 | Wallets do not retrieve metadata from each stake pool at every individual URL, as this could lead to malicious exploitation. For instance, third parties could slow down wallet communication by intentionally delaying the server's response time. To avoid this scenario, metadata uses proxy servers that query the URL included in the registration certificate, and cache the metadata using the pool's sks as key. Wallets will simply query these proxy servers to retrieve the metadata for the pools it needs to display, instead of sending a request to each of the pool's metadata URLs. If the content hash listed on the certificate does not match the content hash of the cached metadata, the cache will be invalidated. 31 | 32 | Proxy servers provide an additional level of security by filtering malicious entries. For example, it is possible to embed malicious content in the metadata, typically in the link to the stake pool's homepage. If a pool hosts dangerous or illegal content, maintainers of a metadata proxy server can filter that entry and not provide it to wallets. This is a clear advantage over writing the metadata directly to the chain, where there would be no way to protect wallet users from visiting malicious sites directly from their wallet. 33 | 34 | While proxy servers do offer effective protection against malicious interference, they could become a point of centralisation. To avoid this, we will provide third parties (stake pools, community members, etc.) with code and binaries so they can run their own proxy servers and prevent centralization. 35 | 36 | ### Interacting with stake pool metadata 37 | 38 | Stake pool operators should follow these steps to register their stake pool's metadata: 39 | 40 | 1. Build a JSON file for the stake pool metadata: 41 | 42 | ``` 43 | { 44 | 45 | "name": "mypool", 46 | "description": "My stake pool", 47 | "ticker": "POOL1", 48 | "homepage": "https://mystakepool.com" 49 | 50 | } 51 | ``` 52 | 53 | Note: The metadata must be hosted in a URL that is maintained by the stake pool operator. This could be their own personal website, a GitHub raw gist file, etc. The URL cannot be longer than 64 bytes long. 54 | 55 | 2. Use the node CLI to register or re-register the stake pool on the blockchain. 56 | 57 | The registration information **must** include: 58 | 59 | - Relay information 60 | - Metadata URL 61 | - Metadata hash 62 | - Cost parameters 63 | 64 | cardano-cli shelley stake-pool registration-certificate 65 | --metadata-url https://mystakepool.com/mypool.json \ 66 | --metadata-hash \ 67 | f97a632341f642f5ac1e15bd182d0c9599c3767230aa9bfb48b120f1c30538eb \ 68 | --pool-relay-port 3001 --pool-relay-ipv4 76.54.23.45 \ 69 | ... 70 | 71 | 3. Obtain the stake pool ID 72 | 73 | Use this code to obtain the stake pool id and obtain all the information required to register the pool in the SMASH database: 74 | 75 | cardano-cli shelley stake-pool id --verification-key-file pool.vkey 76 | > 77 | 78 | **Note**: You can check if the on-chain registration was succeeded by using this code: 79 | 80 | cardano-cli shelley query ledger-state --testnet-magic 42 81 | | jq '._delegationState._pstate._pParams.' 82 | 83 | 4. Submit a PR [here](https://github.com/input-output-hk/cardano-ops/blob/master/topologies/ff-peers.nix) to add your pool's data. 84 | 85 | Note that you will need to provide your IP address or host name, and port. 86 | 87 | ``` 88 | { 89 | operator = "name"; 90 | poolId = ""; 91 | metadataUrl = "https://yourpool.com/pool.json" 92 | meatadataHash = "yourpoolhash"; 93 | addr = "relay.kevinspool.org"; 94 | port = 3001; 95 | } 96 | ``` 97 | 98 | **Important**: Registering your IP address with IOHK will make it "public", so please follow good security practices by running firewalls and other online security methods. 99 | -------------------------------------------------------------------------------- /getting-started/stake-pool-operators/network1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/getting-started/stake-pool-operators/network1.png -------------------------------------------------------------------------------- /getting-started/stake-pool-operators/public-stakepools-and-metadata-management.md: -------------------------------------------------------------------------------- 1 | ## Public stake pools and metadata management 2 | 3 | If the registration certificate that is sent by a stake pool operator contains metadata, the stake pool is considered to be public. 4 | 5 | Referring to, or pointing to metadata, in the stake pool certificate is optional. The certificate might contain a URL of up to 64 bytes in length that points to a JSON object with the following content: 6 | 7 | * a ticker of 3-5 characters, for a compact display of stake pools in a wallet. 8 | * title/name of up to 50 characters. 9 | * short textual description 10 | * URL to a homepage with additional information about the pool (optional). 11 | 12 | These are important considerations to note about the metadata: 13 | 14 | * metadata information is encoded in UTF-8, and will never exceed 512 bytes 15 | * the content hash of the JSON object referenced in the URL (if present), should match the content hash in the registration certificate. If there is a mismatch, the pool will not be displayed in a wallet. 16 | * for the wallet to display the pool, the following conditions must be met - the registration certificate must refer to the metadata, the metadata must be valid and have the correct content hash, and be available at the URL. It must be possible to get the metadata and validate it. If this process fails, the wallet will not display the pool. 17 | * if a stake pool operator changes the metadata, they must post a new stake pool registration certificate with the new content hash. 18 | 19 | ## Metadata proxy servers 20 | 21 | Wallets do not retrieve metadata from each stake pool at every individual URL, as this could lead to malicious exploitation. For instance, third parties could slow down wallet communication by intentionally delaying the server's response time. To avoid this scenario, metadata uses proxy servers that query the URL included in the registration certificate, and cache the metadata using the pool's secret key. Wallets will simply query these proxy servers to retrieve the metadata for the pools it needs to display, instead of sending a request to each of the pool’s metadata URLs. If the content hash listed on the certificate does not match the content hash of the cached metadata, the cache will be invalidated. 22 | 23 | Proxy servers provide an additional level of security by filtering malicious entries. For example, it is possible to embed malicious content in the metadata, typically in the link to the stake pool’s homepage. If a pool hosts dangerous or illegal content, maintainers of a metadata proxy server can filter that entry and not provide it to wallets. This is a clear advantage over writing the metadata directly to the chain, where there would be no way to protect wallet users from visiting malicious sites directly from their wallet. 24 | 25 | While proxy servers do offer effective protection against malicious interference, they could become a point of centralisation. To avoid this, we will provide third parties (stake pools, community members, etc.) with code and binaries so they can run their own proxy servers and prevent centralization. 26 | 27 | ## How to obtain stake pool information 28 | 29 | After a successful stake pool registration and its further operation, SPOs might be interested in obtaining certain information about their pools’ activity. Information about those pools that are operating on mainnet can be fetched using a [pooltool.io](https://pooltool.io/), which provides verified stake pool details. 30 | 31 | In certain cases, exchanges and stake pool operators, in particular, are looking for in-depth information about their mainnet *and* testnet pools. To access data that is stored on the Cardano blockchain, we recommend using [cardano-node](https://github.com/input-output-hk/cardano-node), [cardano-db-sync](https://github.com/input-output-hk/cardano-db-sync), and a [cardano-graphql](https://github.com/input-output-hk/cardano-graphql). 32 | 33 | Each of the above integration components can be installed and easily deployed using Docker. 34 | 35 | Another available option – which is often useful by exchanges and stake pool operators who wish to test stake pool operations on testnet – is the public [Cardano Explorer](https://explorer.cardano.org/en) which also functions based on the cardano-graphql instance. 36 | 37 | Below are some queries that you may find useful in obtaining *testnet* stake pool information. The same query can be used on the mainnet by substituting the relevant URL: 38 | 39 | **Show the pool ID assigned to the stake address:** 40 | 41 | ``` 42 | curl -X POST -H "Content-Type: application/json" -d '{"query": "query getStake_address($address: StakeAddress!){ activeStake(limit: 1 where: { address: { _eq: $address } }) { address stakePoolId }}","variables":{"address":”$My_stake_address_here"}}' https://explorer.cardano-testnet.iohkdev.io/graphql: | jq 43 | ``` 44 | 45 | **Show the amount of active stake in the staking address:** 46 | 47 | ``` 48 | curl -X POST -H "Content-Type: application/json" -d '{"query": "query get_active_stake($address: StakeAddress!){ activeStake(limit: 1 where: { address: { _eq: $address } }) { address amount }}","variables":{"address":"$My_stake_address_here"}}' https://explorer.cardano-testnet.iohkdev.io/graphql: 49 | ``` 50 | 51 | **Check that pool ID has been registered on the chain:** 52 | 53 | ``` 54 | curl -X POST -H "Content-Type: application/json" -d '{"query": "query getStake_pool($id: StakePoolID!){ stakePools(limit: 1 where: { id: { _eq: $id } }){ id } }","variables":{"id":”$My_Pool_id_here"}}' https://explorer.cardano.org/graphql: 55 | ``` 56 | 57 | **Fetch pool information:** 58 | 59 | ``` 60 | curl -X POST -H "Content-Type: application/json" -d '{"query": "query getStake_pool($id: StakePoolID!){ stakePools(limit: 1 where: { id: { _eq: $id } }){ id pledge fixedCost hash margin metadataHash} }","variables":{"id":"$My_Pool_id_here"}}' https://explorer.cardano-testnet.iohkdev.io/graphql: | jq 61 | ``` 62 | 63 | **Check rewards:** 64 | 65 | ``` 66 | curl -X POST -H "Content-Type: application/json" -d '{"query": "query getStake_address($address: StakeAddress!){ rewards(limit: 10 where: { address: { _eq: $address } }) { amount address } }", "variables":{"address":"$My_stake_address_here"}}' https://explorer.cardano.org/graphql: | jq 67 | ``` 68 | 69 | **Check rewards in more detail:** 70 | 71 | ``` 72 | curl -X POST -H "Content-Type: application/json" -d '{"query": "query getStake_pool($id: StakePoolID!){ stakePools(limit: 1 where: { id: { _eq: $id } }){ id rewards{address amount stakePool{id}} } }","variables":{"id":"$My_Pool_id_here"}}' https://explorer.cardano.org/graphql: | jq 73 | ``` 74 | 75 | **See rewards earned in a certain epoch:** 76 | 77 | ``` 78 | curl -X POST -H "Content-Type: application/json" -d '{"query": "query getStake_address($address: StakeAddress!){ rewards(limit: 1 where: { address: { _eq: $address } }) { amount address earnedIn{blocks{epochNo}} stakePool{id} } }","variables":{"address":"$My_stake_address_here"}}' https://explorer.cardano-testnet.iohkdev.io/graphql: | jq 79 | ``` 80 | 81 | -------------------------------------------------------------------------------- /getting-started/stake-pool-operators/stake-pool-performance.md: -------------------------------------------------------------------------------- 1 | ## Stake Pool Performance 2 | 3 | A stake pool elected as a slot leader is responsible for producing new blocks for the Cardano network. If the stake pool does not produce a block, the slot will remain empty and the blockchain will *not* be extended. The Cardano blockchain can tolerate a number of missing blocks, but the majority of blocks expected to be produced (at least 50% + 1) must be generated during an epoch. 4 | 5 | Although occasionally missed blocks don’t affect the extension of the blockchain as a whole, an unresponsive elected stake pool decreases the overall performance of the network, which is undesirable. 6 | 7 | Stake pool performance is calculated according to its expected activity as the ratio of a number of blocks a stake pool produces in a given epoch versus the number it was capable to produce. For instance, if the stake pool could produce 100 blocks (based on its stake and the chance to be elected) in an epoch, but it actually produced just 50 blocks, its performance would be 50%. 8 | 9 | Poor stake pool performance decreases the number of rewards that a pool and its members receive, thereby decreasing its attractiveness to delegators. To improve its performance, a stake pool should have good network connectivity, be run on a reliable system, and actively participate in block production and verification. 10 | 11 | The higher the pool’s performance, the more attractive it will be to delegators since it will offer higher rewards and incentives. 12 | -------------------------------------------------------------------------------- /getting-started/stake-pool-operators/stake-pool-ranking.md: -------------------------------------------------------------------------------- 1 | ## Stake Pool Ranking 2 | 3 | In the Daedalus wallet and Cardano Explorer, stake pools are ranked based on the amount of rewards that users will receive if they choose to delegate to those pools. Ranking shows pool saturation level, simplifying the pool choice. From a delegator's perspective, once a pool reaches a certain saturation point, it will no longer be beneficial to delegate to it. The most attractive stake pools are displayed first and ordered from the top down. 4 | 5 | The ranking system is designed to provide users with the ability to choose the most suitable stake pool for a higher return on investment (ROI), so reliable stake pool operators can maintain and support the system and maximize decentralization. 6 | 7 | ### Ranking Parameters 8 | 9 | A pool's ranking is based on several parameters: cost and margin, the pool's performance, and the amount of stake that the pool has already accumulated. These factors promote reliable stake pools that are not yet saturated and provide low cost and margin. 10 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | .. include:: README.rst 2 | 3 | .. toctree:: 4 | :maxdepth: 3 5 | :caption: Get started 6 | :titlesonly: 7 | :hidden: 8 | 9 | Installing the Cardano node 10 | Using the command line reference 11 | Operating a stake pool 12 | Guidelines for operating large stake pools 13 | Integrating with third parties 14 | Running stake pools and delegation for exchanges 15 | 16 | .. toctree:: 17 | :maxdepth: 3 18 | :caption: New to Cardano? 19 | :titlesonly: 20 | :hidden: 21 | 22 | What is a blockchain? 23 | What is a cryptocurrency? 24 | Why use Cardano? 25 | Proof of stake 26 | Cardano nodes 27 | Cardano tracking tools 28 | How to purchase ada? 29 | Types of wallets 30 | How to delegate 31 | What is a smart contract? 32 | 33 | .. toctree:: 34 | :maxdepth: 3 35 | :caption: Learn 36 | :titlesonly: 37 | :hidden: 38 | 39 | explore-cardano/what-is-a-cardano-node 40 | Stake pools 41 | explore-cardano/understanding-the-delegation-mechanism 42 | explore-cardano/understanding-pledging-and-rewards 43 | Pledging and delegation options 44 | Consensus explained 45 | How keys are used in Cardano 46 | Types of addresses 47 | About hard forks 48 | Chain confirmation v transaction confirmation 49 | 50 | .. toctree:: 51 | :maxdepth: 3 52 | :caption: Explore Cardano 53 | :titlesonly: 54 | :hidden: 55 | 56 | Cardano design rationale 57 | Cardano architecture overview 58 | explore-cardano/cardano-network 59 | explore-cardano/p2p-networking 60 | explore-cardano/how-are-new-blocks-produced 61 | explore-cardano/cardano-monetary-policy 62 | explore-cardano/cardano-fee-structure 63 | explore-cardano/further-reading 64 | explore-cardano/relevant-research-papers-and-specifications 65 | Cardano Explorer 66 | 67 | .. toctree:: 68 | :caption: Cardano components 69 | :titlesonly: 70 | :hidden: 71 | 72 | cardano-node 73 | cardano-graphql 74 | cardano-rosetta 75 | cardano-ledger-specs 76 | cardano-db-sync 77 | cardano-wallet 78 | smash 79 | ouroboros-network 80 | rt-view/rt-view 81 | 82 | .. toctree:: 83 | :maxdepth: 3 84 | :caption: Native Tokens 85 | :titlesonly: 86 | :hidden: 87 | 88 | Learn about native tokens 89 | Minimum ada value requirement 90 | Getting started with native tokens 91 | Cardano token registry 92 | Exercises 93 | FAQs 94 | Resources 95 | 96 | 97 | .. toctree:: 98 | :maxdepth: 3 99 | :caption: Marlowe 100 | :titlesonly: 101 | :hidden: 102 | 103 | Learn about Marlowe 104 | Getting started with the Marlowe Playground 105 | Marlowe language guide 106 | Writing Marlowe with Blockly 107 | Using the Haskell editor 108 | Using the JavaScript editor 109 | 110 | 111 | .. toctree:: 112 | :maxdepth: 3 113 | :caption: Rosetta 114 | :titlesonly: 115 | :hidden: 116 | 117 | Learn about Rosetta 118 | Getting started with Rosetta 119 | Contribute to Rosetta 120 | 121 | 122 | .. toctree:: 123 | :maxdepth: 3 124 | :caption: Release information 125 | :titlesonly: 126 | :hidden: 127 | 128 | Release notes 129 | Compatibility matrix 130 | 131 | 132 | 133 | .. toctree:: 134 | :maxdepth: 3 135 | :caption: Cardano community 136 | :titlesonly: 137 | :hidden: 138 | 139 | cardano-community/cardano-improvement-proposals 140 | cardano-community/providing-feedback 141 | cardano-community/ambassadors-program 142 | cardano-community/community-generated-content 143 | cardano-community/get-support 144 | 145 | .. toctree:: 146 | :caption: Tools 147 | :titlesonly: 148 | :hidden: 149 | 150 | bech32 151 | cardano-addresses 152 | cardano-cli 153 | cardano-serialization-lib 154 | 155 | .. toctree:: 156 | :caption: Glossary 157 | :titlesonly: 158 | :hidden: 159 | 160 | explore-cardano/glossary 161 | -------------------------------------------------------------------------------- /install/install-node.md: -------------------------------------------------------------------------------- 1 | # Installing the Cardano node # 2 | 3 | You can install the [Cardano node](https://docs.cardano.org/en/latest/explainers/getting-started-with-cardano/cardano-nodes.html) using [pre-compiled executable files](https://github.com/input-output-hk/cardano-node#linux-executable) for your platform. 4 | 5 | Alternatively, if you want to build the from source, there are two options available to you. Depending on your build tool preference, you can build from the source code using either of the following: 6 | - [cabal: building the node](https://github.com/input-output-hk/cardano-node/blob/master/doc/getting-started/install.md/) 7 | - [Nix: building the node](https://github.com/input-output-hk/cardano-node/blob/master/doc/getting-started/building-the-node-using-nix.md/) 8 | 9 | Once you have installed the node, you need to [specify the configuration parameters](https://github.com/input-output-hk/cardano-node/blob/master/doc/getting-started/understanding-config-files.md/). 10 | 11 | #### *Related Topics* 12 | - [Using the command line interface]() 13 | -------------------------------------------------------------------------------- /install/use-cli.md: -------------------------------------------------------------------------------- 1 | # Using the command line interface # 2 | The `cardano-cli` command line interface (CLI) is installed as part of the node installation process. This CLI provides a collection of tools for generating keys, constructing transactions, creating certificates, and other important tasks. 3 | 4 | It is organized in a hierarchy of subcommands, and each level comes with its own built-in documentation of command syntax and options. For more details, read the [CLI command reference](https://github.com/input-output-hk/cardano-node/blob/master/doc/reference/cardano-node-cli-reference.md/). 5 | 6 | To access the top level help, type the following command (without arguments): 7 | 8 | `cardano-cli` 9 | 10 | All the available sub-subcommands are displayed, one of which is `node`. To continue drilling down the hierarchy, type the following command: 11 | 12 | `cardano-cli node` 13 | 14 | To learn about the sub-sub-subcommand `key-gen`, type the following command: 15 | 16 | `cardano-cli node key-gen` 17 | 18 | The parameters that this command takes are displayed. To generate a key-pair of offline keys and a file for the issue counter, type the following command: 19 | ``` 20 | cardano-cli node key-gen \ 21 | --cold-verification-key-file cold.vkey \ 22 | --cold-signing-key-file cold.skey \ 23 | --operational-certificate-issue-counter-file cold.counter 24 | ``` 25 | -------------------------------------------------------------------------------- /learn/Cardano-keys.md: -------------------------------------------------------------------------------- 1 | 2 | ## How keys are used in Cardano 3 | 4 | Keys are asymmetric cryptography key pairs that are used for: 5 | 6 | - Signing and validating payments and staking certificates 7 | 8 | - Identifying and defining addresses on the Cardano blockchain. 9 | 10 | ### Types of keys 11 | There are two main type of keys: 12 | 13 | #### Node keys 14 | Node keys represent the security of the blockchain and consist of the following keys: 15 | 16 | - Operator/operational key, operator’s offline key pair with cert counter for new certificates. 17 | 18 | - Hot KES key, operator’s hot KES key pair. 19 | 20 | - Block signing key, operational VRF key pair, it participates in the right to create and sign the block for the specific slot. 21 | 22 | #### Address keys 23 | 24 | Address keys represent the functions of the addresses derived from the keys for identifying funds on the blockchain that consist of the following keys: 25 | 26 | Payment key, single address key pair usually used for generating UtxO addresses. Staking key, stake/reward address key pair usually used for generating account/reward addresses. 27 | -------------------------------------------------------------------------------- /learn/chain-confirmation-v-transaction-confirmation.md: -------------------------------------------------------------------------------- 1 | ## Chain confirmation versus transaction confirmation 2 | 3 | When discussing Cardano, often-repeated questions are *what is Cardano’s transaction time?*, and *how many network confirmations does Cardano require before a transaction goes through?* The answers to these questions require a deeper look at the concepts of chain confirmation and transaction confirmation, and how these relate to the protocol. 4 | 5 | **Chain confirmation** 6 | 7 | This is the point beyond which *the chain is guaranteed by protocol not to alter any further because of randomness, or random events*. 8 | 9 | Chain confirmation occurs at some point in the future, after an x amount of future blocks have been minted. The time between now and the point when chain confirmation for a particular transaction occurs is called the *stability window* (that is, the number of slots required for a block to become *stable*, where *stable* is defined as a block that cannot be rolled back). The formula to calculate this window is 3k/f (where k is the parameter that limits a pool's growth by decreasing its rewards yield beyond a certain threshold, and f is the parameter that defines a pool's maximum reward yield.) 10 | 11 | **Transaction confirmation** 12 | 13 | This is the point in time when a transaction is accepted into the chain and becomes immutable. The concepts of block depth and settlement window come into play here. 14 | 15 | A transaction can be considered confirmed if the block that contains it is deep enough in the chain. 'Deep enough' is a relative concept: the depth of a block indicates how many more blocks have been added to the chain since that particular block was appended to it. And because blocks have depth, so do the transactions contained in them. 16 | 17 | If the depth of a particular block is greater than a pre-defined threshold, the transaction is considered to be confirmed, and the assets in that transaction can be used 'safely' (i.e., the protocol guarantees that the transaction has become immutable, so the assets can be traded, exchanged, etc.) 18 | 19 | The time period that elapses between the point when a transaction is confirmed, and when the transaction's assets can be used to exchange with other assets is called the settlement window. 20 | 21 | ### Likelihood of immutability 22 | 23 | Another way of determining whether or not a transaction is confirmed is by considering the transaction's *likelihood* of immutability. The probability of a transaction being immutable depends on how many blocks have been added to the chain since that transaction was accepted into the chain. The more blocks added, the higher the probability that the transaction *will* become immutable. 24 | 25 | A transaction becomes immutable as soon as its depth is greater than 3k/f slots (that is, 129600 slots on current mainnet, or 36 hours). If this transaction is inserted into a block at slot 10 for instance, it will only become truly immutable at slot 129600. This is guaranteed by the [Ouroboros Praos protocol](https://eprint.iacr.org/2017/573.pdf). 26 | 27 | However, 3k/f slots normally exceed the requirements in most situations, so a more practical approach is to consider the *probability* for a transaction to become immutable. In this case, we consider that a transaction is confirmed if the probability for it to become immutable is *high enough*. 28 | -------------------------------------------------------------------------------- /learn/pledging-and-delegating-options.md: -------------------------------------------------------------------------------- 1 | ## Pledging and delegation options 2 | 3 | Ada that is held on the Cardano network represents a user’s stake in the protocol, the size of which is proportional to the amount of ada held. Users who hold a stake in Cardano can earn passive rewards for validating blocks. The amount of rewards they can earn is proportional to the amount of ada they pledge or delegate to a stake pool. 4 | 5 | There are three options ada holders can consider for delegating their stake: 6 | 7 | 1. Run their own stake pool 8 | 2. Agree with a third party to run a private stake pool for them 9 | 3. Delegate to other stake pools 10 | 11 | To create and register a stake pool, see the [create transaction instructions](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/simple_transaction.html#) explaining how to pledge and delegate to earn rewards. 12 | 13 | Stake pools must maintain **high-availability**, which means that they should always be online and available to validate and create new blocks. The rewards a stake pool can earn is directly proportional to the amount of ada that is pledged or delegated, and the number of blocks the stake pool can create in a given epoch. Ouroboros (the protocol that runs on Cardano) elects the slot leader that grants the permissions to validate transactions and create new blocks, based on the above criteria. 14 | 15 | > Note: It is strongly recommended to test all stake pool functionality on the testnet prior to any mainnet deployment. 16 | 17 | ### Pledging 18 | 19 | The pledge is the amount of ada that the stake pool operator ‘delegates’ to their own pool when it is created. This pledge represents the commitment of the operator to maintain their pool and support network activity. Making a pledge is not required, however, it is recommended to pledge some ada to the stake pool prior to running it. The more ada that is pledged, the higher the pool rewards, which are dependent on the pool’s level of uptime and its [performance](https://docs.cardano.org/en/latest/getting-started/stake-pool-operators/stake-pool-performance.html). 20 | 21 | > **Further reading:** 22 | > - [Pledging and rewards](https://docs.cardano.org/en/latest/explore-cardano/understanding-pledging-and-rewards.html) 23 | > - [Delegation and pledging advice for large SPOs](https://docs.cardano.org/en/latest/getting-started/guidelines-for-operating-large-stake-pools/index.html#delegation-and-pledging-advice) 24 | 25 | ### Delegation 26 | 27 | Ada holders who do not have technical expertise in maintaining a stake pool can earn rewards by delegating to any stake pool available on the network. The Daedalus wallet provides a convenient user-friendly interface that allows users to easily start delegating to any registered stake pool. 28 | 29 | > Note: ada holders and SPOs who pledge or delegate will always have access to their ada. If the delegated ada is spent or removed from the pool, the rewards decrease respectively. 30 | 31 | > **Related documentation:** 32 | > - [Registering a stake pool](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/register_stakepool.html#) 33 | > - [Creating a delegation certificate](https://github.com/cardano-community/guild-operators/blob/alpha/docs/Staking/Delegates.md#create-a-delegation-certificate-and-submit-to-the-network) 34 | 35 | > **Further reading:** 36 | > - [Advice for Stakeholders - Delegators and Stake Pool Operators](https://iohk.io/en/blog/posts/2020/11/13/the-general-perspective-on-staking-in-cardano/) 37 | 38 | ### Rewards 39 | 40 | Delegators earn rewards for participating in staking (either pledging or delegating) and these rewards are automatically distributed between the participants according to the rewards scheme. The rewards scheme in Cardano is designed to be decentralized, which means that there is no single controlling party. 41 | 42 | > **Related documentation:** 43 | > - [Withdrawing rewards](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/withdraw-rewards.html) 44 | > - [Understanding pledging and rewards](https://docs.cardano.org/en/latest/explore-cardano/understanding-pledging-and-rewards.html) 45 | 46 | ### FAQs 47 | 48 | 1. **Q: How do I create and register a stake pool?** 49 | 50 | **A**: Please review the steps in the documentation [here.](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/getConfigFiles_AND_Connect.html) 51 | 52 | 2. **Q: How do I generate staking addresses?** 53 | 54 | **A**: Please review the steps in the documentation [here.](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/register_key.html) 55 | 56 | 3. **Q: How do I determine an optimal amount of ada to pledge to each pool?** 57 | 58 | **A**: This is a personal preference, the more you pledge the higher the rewards. 59 | 60 | 4. **Q: How do I know if my pool is oversaturated?** 61 | 62 | **A**: If the amount of ada delegated to the pool is over 32 million, the pool is oversaturated. 63 | 64 | 5. **Q: How do I know who has delegated to my pool?** 65 | 66 | **A**: You can query the ledger state. 67 | 68 | 6. **Q: How can I calculate rewards?** 69 | 70 | **A**: This is calculated automatically by the Ouroboros protocol. 71 | 72 | 7. **Q: How can I verify whether my pool was successfully registered on mainnet?** 73 | 74 | **A**: You can check [pooltool.io](https://pooltool.io/) or run the following curl command: 75 | ``` 76 | curl -X POST -H "Content-Type: application/json" -d '{"query": "query getStake_pool($id: StakePoolID!){ stakePools(limit: 1 where: { id: { _eq: $id } }){ id } }","variables":{"id":"$My_Pool_id_here"}}' https://explorer.cardano.org/graphql: 77 | ``` 78 | 79 | 80 | 81 | 82 | -------------------------------------------------------------------------------- /learn/types-addresses.md: -------------------------------------------------------------------------------- 1 | 2 | ## Types of Addresses 3 | The addresses are a blake2b-256 hash of the relevant verifying/public keys concatenated with some metadata that can be stored on the Cardano blockchain. Shelley introduces four different types of addresses: 4 | 5 | - Base addresses. 6 | 7 | - Pointer addresses. 8 | 9 | - Enterprise addresses. 10 | 11 | - Reward account addresses. 12 | 13 | In addition to those new addresses, Shelley continues to support bootstrap addresses and script addresses as introduced in Byron. But only the new base and pointer addresses carry stake rights. Therefore, addresses consist of some serialized data specified in the ledger specification that are stored in the blockhain’s blocks, e.g. an UtxO address. The serialized data (address) contains the following two parts: 14 | 15 | - Metadata: that is used for interpreting. 16 | 17 | - Payload: the raw or encoded data. 18 | 19 | ### Base Addresses 20 | A base address directly specifies the staking key that should control the stake for the address. The staking rights associated with funds held in this address may be exercised by the owner of the staking key. Base addresses can be used in transactions without registering the staking key in advance. 21 | 22 | The stake rights can only be exercised by registering the stake key and delegating to a stake pool. Once the stake key is registered, the stake rights can be exercised for base addresses used in transactions before or after the key registration. 23 | 24 | ### Pointer Addresses 25 | A pointer address indirectly specifies the staking key that should control the stake for the address. It references a stake key by a stake key pointer which is a location on the blockchain of the stake key registration certificate for that key. Pointer addresses can be used in transactions even if their target is not an active stake key registration. This covers the scenario where the key was unregistered after (or indeed before), the transaction, and also covers pointers to targets that are plainly invalid. The reason for allowing such invalid targets is so that nodes only need to track the currently active stake keys. 26 | 27 | The pointer can be considerably shorter than the hash used in base addresses. There is a subtlety with pointer addresses: 28 | 29 | It might happen that a stake key registration certificate that is referenced by a pointer address might be lost due to a rollback. This should not lead to a loss of funds. To prevent that, the system considers pointer addresses with an invalid pointer to be valid for the purpose of using funds stored therein as inputs for transactions (but ignores them for the purpose of PoS participation). Optionally, a wallet might refuse to create transactions to pointer addresses before the referenced certificate has become immutable, in order to prevent funds from being excluded from the PoS, in the case of rollbacks. 30 | 31 | ### Enterprise Addresses 32 | Enterprise addresses carry no stake rights and thus using them means that you are opting out of participation in the proof of stake protocol. 33 | 34 | Exchanges or other organizations that control large amounts of ada – but hold it on behalf of other users – may wish to follow a policy of not exercising stake rights. By using enterprise addresses, exchanges can demonstrate that they follow this policy. Since enterprise addresses are not associated with any staking key, they are automatically excluded from the mechanisms that influence the slot leadership schedule. Note that using addresses with no stake rights effectively decreases the total amount of stake, which plays into the hands of the adversary. 35 | 36 | ### Reward Account Addresses 37 | A reward address is a cryptographic hash of the public staking key of the address. Reward account addresses are used to distribute rewards for participating in the PoS protocol (either directly or via delegation). They have the following properties: 38 | 39 | - Account-style accounting is used, not UTxO-style. 40 | 41 | - Funds cannot be received via transactions. Instead, their balance is only increased when rewards are distributed. 42 | 43 | - A one-to-one correspondence exists between registered staking keys and reward account addresses. 44 | 45 | This key is used whenever funds are withdrawn from the address. Furthermore, stake associated with funds in the address contributes to the stake of this key. Just as in the case of enterprise addresses, the staking object for a reward address does not need to contain information. 46 | -------------------------------------------------------------------------------- /marlowe/blockly-contracts.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/marlowe/blockly-contracts.png -------------------------------------------------------------------------------- /marlowe/blockly-eight.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/marlowe/blockly-eight.png -------------------------------------------------------------------------------- /marlowe/blockly-five.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/marlowe/blockly-five.png -------------------------------------------------------------------------------- /marlowe/blockly-four.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/marlowe/blockly-four.png -------------------------------------------------------------------------------- /marlowe/blockly-seven.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/marlowe/blockly-seven.png -------------------------------------------------------------------------------- /marlowe/blockly-six.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/marlowe/blockly-six.png -------------------------------------------------------------------------------- /marlowe/blockly.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/marlowe/blockly.png -------------------------------------------------------------------------------- /marlowe/detail-js-contract.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/marlowe/detail-js-contract.png -------------------------------------------------------------------------------- /marlowe/get-started-blockly.md: -------------------------------------------------------------------------------- 1 | ## Writing Marlowe with Blockly 2 | You can write Marlowe code directly as Marlowe text, or alternatively use the Blockly visual interface to piece together the parts of the contract. This is a very useful tool for those users who may not have experience in programming editors, and want to build the contracts visually. 3 | 4 | To use Blockly follow these steps: 5 | 1. Open the [Marlowe Playground](https://alpha.marlowe.iohkdev.io/#/). 6 | 7 | You will see a window like this: 8 | ![landing page](landing-page.png) 9 | 2. Click the **Start coding!** button on the bottom left and then select **Blockly** from the menu. 10 | 11 | You will see a window like this: 12 | ![Blockly](blockly.png) 13 | 3. You can build contracts by adding components to the *Contract* block. 14 | 15 | You will see a list of options for forming a contract by clicking **Contracts** in the menu. 16 | ![Blockly](blockly-contracts.png) 17 | 4. Click **Contracts** and select a block. 18 | 5. Drag it into the building pane and then fit it into the top-level slot. 19 | 20 | The following example shows how to construct a contract starting with `When` as its main construct. 21 | ![Blockly](blockly-four.png) 22 | 6. Continue building the contract. To build a contract with `When`, it needs to include one or more actions that trigger the contract. These can be chosen from the **Actions** menu item. 23 | ![Blockly](blockly-five.png) 24 | The following example shows how to construct a *Deposit* action and fit it into the first gap in the contract that you are building. 25 | ![Blockly](blockly-six.png) 26 | 7. Next, insert the following information: 27 | 28 | - who is making the deposit (the party) 29 | - the value and currency (token) of the deposit 30 | - whose account it should be deposited to (the recipient). 31 | 32 | ![Blockly](blockly-seven.png) 33 | 8. You can add other actions. For this, choose actions, add them, and fill out information. Respective action will require different types of information. Add the *Close* tab after *Continue as* so that the contract closes after making the deposit. 34 | 35 | 9. Finally, when all actions are inserted and conditions are added, you can complete your contract by adding a *Close* tab to the main contract. This shows how the contract should behave in case the deposit is not made before the specified timeout. 36 | ![Blockly](blockly-eight.png) 37 | -------------------------------------------------------------------------------- /marlowe/get-started-haskell.md: -------------------------------------------------------------------------------- 1 | ## Using the Haskell Editor 2 | As an experienced Haskell developer you can use the Haskell editor to render Marlowe code. Marlowe is written as a Haskell data type, and thus it is straightforward to generate Marlowe smart contracts using Haskell. 3 | 4 | To use the Haskell editor follow these steps: 5 | 1. Open the [Marlowe Playground](https://alpha.marlowe.iohkdev.io/#/). 6 | 2. Click **Start coding!** 7 | 3. Select the Haskell version from the menu. 8 | 9 | You will see a window like this: 10 | ![Haskell](haskell-first-window.jpg) 11 | 4. Now you can start coding in Haskell. 12 | 13 | Alternatively, you can use some example contracts to work with. 14 | 5. Describe a contract in the editor. For this, define a top-level value contract of type `Contract`, add conditions, and close the contract. 15 | 16 | The following window will open for an Escrow contract. 17 | ![Escrow](haskell-escrow-editor.png) 18 | 6. Click **Compile** to convert this value from Haskell into Marlowe. 19 | 7. Then, click **Send to Simulator**. 20 | 21 | The Simulator allows you to simulate Marlowe contracts transaction by transaction. You can find more instructions on how to use the Haskell editor in the [Marlowe tutorial](https://cardano--3120.org.readthedocs.build/projects/plutus/en/3120/marlowe/tutorials/embedded-marlowe.html#). 22 | -------------------------------------------------------------------------------- /marlowe/get-started-js.md: -------------------------------------------------------------------------------- 1 | ## Using the Javascript Editor 2 | You can use the embedded JavaScript editor to write Marlowe code. 3 | 4 | To use the editor follow these steps: 5 | 6 | 1. Open the Marlowe Playground. 7 | 2. Click **Start coding!** and select **Javascript** from the menu. 8 | 9 | You will see a window like this: 10 | ![Java Script](javascript.jpg) 11 | 3. You can import values and functions from the provided library written in TypeScript. They can be used to generate Marlowe smart contracts from TypeScript or JavaScript. 12 | 4. Describe a contract in the editor, alternatively, you can upload an example written in JavaScript. The last expression in the file needs to be of type `Contract`: below we define the top-level constant `contract` to be of that type. 13 | ![JS](detail-js-contract.png) 14 | 5. Click **Compile** to convert this contract from Javascript into Marlowe. 15 | 6. Then click **Send to Simulator** in the top right-hand corner. 16 | 17 | You can also find more details about using the JavaScript editor in the [Marlowe tutorial](https://alpha.marlowe.iohkdev.io/doc/marlowe/tutorials/javascript-embedding.html). 18 | -------------------------------------------------------------------------------- /marlowe/haskell-escrow-editor.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/marlowe/haskell-escrow-editor.png -------------------------------------------------------------------------------- /marlowe/haskell-first-window.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/marlowe/haskell-first-window.jpg -------------------------------------------------------------------------------- /marlowe/javascript.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/marlowe/javascript.jpg -------------------------------------------------------------------------------- /marlowe/landing-page.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/marlowe/landing-page.png -------------------------------------------------------------------------------- /marlowe/marlowe-explainer.md: -------------------------------------------------------------------------------- 1 | ## Learn about Marlowe 2 | Marlowe offers financial contracts for blockchain that everyone can code. It is a domain-specific language (DSL) for writing and executing financial contracts that allows users to apply their domain expertise to write and manage contracts conveniently, without the steep learning curve associated with software development, blockchain, or smart contracts. With Marlowe you can learn how to model financial products using this easy-to-learn language. It is a platform for decentralized finance (DeFi) that supports direct, peer-to-peer lending, contracts for difference (CFD), and other similar instruments. Marlowe contracts are straightforward as they are optimized for financial transactions, development platforms, and ensure a fast track for financial service providers to build expertise in smart contracts and blockchain technology. 3 | 4 | As it is a special-purpose language, it is easier to read, write and understand Marlowe contracts. It is also safer: some sorts of errors are impossible to write, and we can completely analyse contract behaviour without having to run a contract. 5 | 6 | ### Who can use Marlowe? 7 | Marlowe has been designed so that it can be used by someone who is an expert in the field of financial contracts or business, but does not have programming skills and experience, because it allows you to build contracts visually as well as in more traditional code. Financial institutions can use it to develop and deploy custom instruments for their customers and clients, for example. 8 | 9 | The Marlowe language itself is now embedded in both [JavaScript](https://www.javascript.com/) and [Haskell](https://www.haskell.org/) offering you a choice of editors depending on your preference and skillset. Javascript offers flexibility and speed of use with a thriving ecosystem, while Haskell is a functional programming language with its own established ecosystem and solid testing framework. 10 | 11 | Marlowe can interact with real-world data – such as oracles – and the participants in the contract make choices within the contract flow to determine what happens on the chain and off the chain, such as in a wallet. Marlowe is blockchain-agnostic: it enables the expression of smart contacts on top of an account-based model, such as Ethereum, as well as on the extended unspent transaction output (EUTXO) model of Cardano. 12 | 13 | Marlowe has been designed as an industry-scale solution and embodies examples from the [ACTUS](https://www.actusfrf.org/) taxonomy and standard for financial contracts. Contracts written in Marlowe can be integrated on Cardano or an alternative blockchain. 14 | 15 | ### What does the Marlowe language look like? 16 | Marlowe is a small language, with a handful of different constructs that, for each contract, describe behaviour involving a fixed, finite set of roles. These roles are fulfilled by the participants in the contract. 17 | 18 | Contracts can be built by putting together a small number of these constructs that in combination can be used to describe and model many different kinds of financial contracts. Some examples include a running contract that can make a payment to a role or to a public key, a contract that can wait for an action by one of the roles, such as a deposit of currency, or a choice from a set of options. Crucially, a contract cannot wait indefinitely for an action: if no action has been initiated by a given time (the timeout), then the contract will continue with an alternative behavior, for example, take a remedial action like refunding any funds in the contract. 19 | 20 | Depending on the current state of a contract, it may make a choice between two alternative future courses of action, which are themselves contracts. When no further actions are required, the contract will close, and any remaining currency in the contract will be refunded. 21 | 22 | When a contract is run, the roles it involves are fulfilled by participants, which are identities on the blockchain. Each role is represented by a token on the chain and roles can be transferred during contract execution, meaning that they can essentially be traded. 23 | 24 | ### How can I use the Marlowe Playground? 25 | The [Marlowe Playground](https://alpha.marlowe.iohkdev.io/) is available to use so that you can develop, simulate, and test the process of writing smart contracts in a sandbox environment. Its purpose is to encourage all types of developers, even if you don’t have prior Haskell or Javascript experience, to build financial products on Cardano. A set of [tutorials](https://alpha.marlowe.iohkdev.io/doc/marlowe/tutorials/index.html) is available that outlines example contracts and overview information on Marlowe and how contracts should be modelled. 26 | 27 | The Marlowe Playground is the medium for end-to-end financial smart contract development. It provides a means for developers to not only write smart contract code, but to also perform preliminary iterative design using simulations, ability to formally verify, and ability to test smart contracts. These capabilities, paired with a purpose-built DSL for finance ensures that the contracts are easy and straightforward to build, secure, verifiable, and rigorously tested. 28 | 29 | ### What is next for Marlowe? 30 | As a part of the Goguen rollout, we will be completing the implementation of Marlowe on Cardano, giving users and organizations the opportunity to execute DeFi contracts they have written themselves or downloaded from a contract repository, transferring crypto assets according to the contract terms. Marlowe will run first of all on the Cardano blockchain, but it is not tied to Cardano, and could run on other blockchains in the future. 31 | 32 | Smart contracts running on Cardano will be able to access external data values, such as the exchange rate between ada and bitcoin, through oracles. In some ways, an oracle is just like a participant that makes a choice, and we plan to support oracle values as part of the implementation, allowing contracts to access values directly from a stock market ‘ticker’ or a popular data feed such as Coinbase. 33 | 34 | #### *Related Topics* 35 | - [Getting started with the Marlowe Playground?]() 36 | -------------------------------------------------------------------------------- /marlowe/marlowe-get-started.md: -------------------------------------------------------------------------------- 1 | ## Getting Started with the Marlowe Playground 2 | The [Marlowe Playground](https://alpha.marlowe.iohkdev.io/) is the medium for end-to-end financial smart contract development. It provides a means for developers to not only write smart contract code, but to also perform preliminary iterative design using simulations, ability to formally verify, and ability to test smart contracts. These capabilities, paired with a purpose-built DSL for finance ensures that the contracts are easy and straightforward to build, secure, verifiable, and rigorously tested. 3 | 4 | The playground is available to use so that you can develop, simulate, and test the process of writing smart contracts in a sandbox environment. Its purpose is to encourage all types of developers, even if you don’t have prior Haskell or Javascript experience, to build financial products. Marlowe is in the process of deployment on Cardano, however, the Marlowe Playground already provides an environment, where users can try out its functionality in advance of the full deployment. A set of [tutorials](https://alpha.marlowe.iohkdev.io/doc/marlowe/tutorials/index.html) is available that outlines example contracts and overview information on Marlowe and how contracts should be modelled. 5 | 6 | There are three options that you can choose from when using the Marlowe Playground. You can write directly in Marlowe text, but also use the visual Blockly visual programming tool to create contracts by fitting together blocks that represent the different components. 7 | 8 | Or you can choose to use either the embedded Haskell or Javascript editors to help you describe Marlowe contracts more readably and succinctly if you prefer. Once a contract is written, you can analyse its behaviour, such as checking whether any payments made by the contract could conceivably fail. You can also step through how a contract will behave, simulating the actions of the participants. 9 | 10 | #### *Related Topics* 11 | - [Learn about Marlowe](marlowe-explainer.md) 12 | - [Writing Marlowe with Blockly](get-started-blockly.md) 13 | - [Using the Haskell Editor](get-started-haskell.md) 14 | - [Using the Java Script Editor](get-started-js.md) 15 | -------------------------------------------------------------------------------- /native-tokens/exercises.md: -------------------------------------------------------------------------------- 1 | ## Native Tokens Exercises 2 | 3 | ### Prerequisites 4 | 5 | 1. You should be familiar with setting up and operating a Cardano node. 6 | 2. Read the explainer about multi-asset tokens, documentation on how to work with the Cardano node, and operations with multi-asset tokens in the sections above. 7 | 3. Checkout and build the `github` sources for the `cardano-node` that have been tagged with `mary`. 8 | 4. Start a Cardano node that you can submit commands to. 9 | 10 | ### Objectives 11 | 12 | This set of exercises is aimed to ensure that you can: 13 | 14 | 1. Manage existing native tokens; 15 | 2. Create new native tokens; 16 | 3. Submit transactions that include native tokens on the Cardano blockchain. 17 | 18 | Please report any bugs or improvements through the `cardano-node` github repository. 19 | 20 | ### Exercises 21 | 22 | 1. Create a set of private/public signing keys, *shelley*, and three *addresses* *(ada, mary and percy)*. Fund *ada* from the *faucet*. Request some **Wollstonecraft** tokens from the token owner to fund your *mary* address. Verify that both addresses have the expected values. What do you observe about the *mary* values? 23 | 2. Send 100 **ada** from *ada* to *mary*, and 10 **Wollstonecraft** from *mary* to *percy*. Check the values of all three addresses before and after the transactions. 24 | 3. Define a *minting policy script* for the **KingOfKings** currency that allows *shelley* to create new **Ozymandian** tokens. 25 | 4. Mint 1000 new **Ozymandians** in the *percy* address. Check that they have been successfully minted. Note that you might need to fund the *percy* address with additional **ada**. 26 | 5. What is the least amount of **ada** that you need to keep in each of your addresses? What is the least amount of **Ozymandians** or **Wollstonecraft** that you can keep in an address? 27 | 6. You want to *redeem* some of your **Wollstonecraft** tokens. How do you do this? Similarly, how do you redeem your **Ozymandians**? What happens to your **ada** balances when you redeem your tokens? 28 | 7. Create a new *minting policy script* that allows *shelley* to create **Wollstonecraft**, **ada** and **Ozymandian** tokens. Mint new tokens of each type and send them to *mary* and *percy*. Check that they have been successfully received. What do you observe about the balances on each of the addresses? 29 | 8. Create five new signing addresses: *athena*, *zeus*, *hera*, *poseidon* and *dionysus*. Create a *minting policy script* that allows any majority of the five Olympians to mint **Platinum**, **Gold**, **Silver** and **Bronze** medals. Send *percy* one new **Gold** medal, and send *mary* one new **Platinum** medal, two **Gold** medals, and four **Silver** medals. Check the balances for each of your addresses. Now transfer one **Gold** medal and one **Silver** medal from *mary* to *percy* and check the balances again. 30 | 31 | **Optional exercises** 32 | 33 | 9. Set up a number of “mints” that each produce coins of a specific type. The values of each of the coins is given below. 34 | 35 | | Coin | Value | 36 | | ------------- | ------------- | 37 | | Pound | 20 shillings | 38 | | Merk | 13 shillings and 4 pence | 39 | | Noble | 6 shillings and 8 pence | 40 | | Shilling | 12 pence | 41 | | Bawbee | 6 pence | 42 | | Groat | 4 pence | 43 | | Penny | 1 pence | 44 | 45 | Each mint may produce new coins to match the value of any coins that are sent to a specific address. For example, if the **Bawbee** address is sent three **Groats**, two new **Bawbees** may be minted. Coins can be minted up to the value that has been received. Any excess is lost. So if the **Noble** mint address is sent 8 **Shilling** coins, then one new **Noble** coin is minted in exchange. 46 | 47 | > Please note that until we have Plutus scripts, there is no way to enforce these conversion rates on-chain, and you will need to do them manually. 48 | 49 | 10. Set up a “coin exchange” with one or more colleagues. Each of you is responsible for one or more “mints”. You should each set up an exchange address and fund it with newly minted coins that are worth precisely twenty-one shillings. Now practice sending coins and changing them for ones of equivalent value. For example, if someone sends you two **Merk** coins, you might return one **Pound** coin and one **Noble** coin, or any other equivalent value that you like. Use transaction metadata to record the coin exchanges on-chain. If you cannot give the exact change, give the closest value that you can. 50 | 51 | 11. Adapt your exchanges so that you charge a fee of 10% for each transaction. Record this in a separate account. Exchange coins until one of you can no longer make change. 52 | 53 | Thank you for completing the exercises! 54 | -------------------------------------------------------------------------------- /native-tokens/index.rst: -------------------------------------------------------------------------------- 1 | Overview 2 | ========== 3 | 4 | Native Tokens is the name of Cardano's Multi-Asset (MA) support feature, which enables users to transact with ada, and an unlimited number of user-defined (custom) tokens natively. 5 | 6 | Native support offers distinct advantages for developers: there is no need to create smart contracts to handle custom tokens, for example, which removes a layer of added complexity and potential for manual errors since the ledger handles all token-related functionality. 7 | 8 | The Native Tokens feature extends the existing accounting infrastructure defined in the ledger model (originally designed for processing ada-only transactions) to accommodate transactions using a range of assets. These assets include ada and a variety of user-defined custom token types. 9 | 10 | We’ll be expanding these pages over the weeks and months ahead; take our short survey to be kept informed of the latest updates. 11 | 12 | Collecting Test Tokens 13 | To get ada for testing in the pre-production environment, you will need to submit a request by filling out `this form. `_ 14 | 15 | This method will be available for a limited time until a regular faucet is released. 16 | 17 | .. toctree:: 18 | :maxdepth: 1 19 | :titlesonly: 20 | :hidden: 21 | 22 | learn-about-native-tokens 23 | getting-started-with-native-tokens 24 | using-the-token-registry 25 | exercises 26 | faqs 27 | resources 28 | -------------------------------------------------------------------------------- /native-tokens/min-ada.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/native-tokens/min-ada.png -------------------------------------------------------------------------------- /native-tokens/minimum-ada-value-requirement.md: -------------------------------------------------------------------------------- 1 | ## Minimum ada value requirement 2 | 3 | UTXOs on the ledger may contain a heterogeneous collection of tokens, including ada, which is a limited resource in the Cardano system. Requiring some amount of ada to be included in every UTXO (where that amount is based on the size of the UTXO, in bytes), limits the maximum total size taken up by UTXO entries on the ledger at any given time. 4 | 5 | The maximum possible UTXO size (the sum of the sizes of all UTXO entries) is implicitly adjusted by raising and lowering the `min-ada-value` parameter. In this way, the constraint protects the Cardano ledger from growing beyond a certain size. A ledger without a size bound is vulnerable to being populated by so much data that users will be unable to process it (or run a node) with machines meeting the recommended specifications for running a node. 6 | 7 | #### The ada-only case 8 | 9 | Because of the `min-ada-value` constraint, a guaranteed bound on the number of entries in an ada-only UTXO is: 10 | 11 | `max No. UTxOs <= (total ada in circulation) / (minimum ada value)` 12 | 13 | This formula bounds the number of UTXO entries, but says nothing about adjusting for the size of each entry, because all UTXO entries that contain only ada are (close enough to) the same size. The size of the UTXO set is bounded by: 14 | 15 | `max UTxO size <= (max No. UTxOs) * (max UTxO entry size) + overhead` 16 | 17 | In the multi-asset Cardano ledger, UTXO entries will have different sizes. In particular, any entries containing a non-ada asset contain records of the Policy IDs, asset names, and quantities of each of the non-ada assets. To maintain the max UTXO size bound on the UTXO stored on the ledger with variable entry sizes, we must adjust the minimum ada value for each UTXO entry, based on its size. 18 | 19 | Below, we present a calculation and a more detailed justification for this adjustment. 20 | 21 | #### Min-ada-value calculation 22 | 23 | The minimum ada amount required to be contained in every ada-only UTXO with no additional data (i.e., a UTXO containing only the address and ada amount) is a protocol parameter of the Cardano system, called : `minUTxOValue` 24 | 25 | The size of such a UTXO has an upper bound : `adaOnlyUTxOSize` 26 | 27 | We can calculate the upper bound size of a UTXO *u* containing non-ada tokens : `sizeBound (u)` 28 | 29 | We want to calculate the min-ada required to be contained in *u* : `minAda (u)` 30 | 31 | A `minUTxOValue` amount of ada pays for `adaOnlyUTxOSize` bytes of UTXO storage on the ledger. To make the `min-ada-value` proportional for all UTXOs, the following proportion must be satisfied: 32 | 33 | `minUTxOValue / adaOnlyUTxOSize = minAda (u) / sizeBound (u)` 34 | 35 | The `min-ada` calculation for any UTXO approximates the above formula. This uses the constants: 36 | 37 | `coinSize = 0` (note: this is an implementation error, and will be changed to the correct value, *2*, in the next fork. This will decrease the minimum ada value by a small percentage) 38 | 39 | `utxoEntrySizeWithoutVal = 27` 40 | 41 | `adaOnlyUTxOSize = utxoEntrySizeWithoutVal + coinSize = 27` 42 | 43 | The functions used in the formula below are: 44 | 45 | `quot a b` is the quotient of `(a, b)`, i.e., `quot 11 5 = 2` because `11 = 5 * 2 + 1` 46 | 47 | `numAssets`: the number of distinct AssetIDs in `B`, e.g. if `B = [(policyID1, myAssetNameSBS, 10), (policyID1, yourAssetNameSBS, 5), (policyID2, someAssetNameSBS, 250), (policyID3, someAssetNameSBS, 43)]` then `numAssets B = 4` 48 | 49 | `numPIDs`: the number of distinct PolicyIDs in `B` e.g. if `B` is as above, `numPIDs B = 3` (which are `policyID1, policyID2, policyID3`) 50 | 51 | `sumAssetNameLengths`: the sum of the length of the ByteStrings representing distinct asset names e.g., if `B` is as above, 52 | 53 | `sumAssetNameLengths B = length myAssetNameSBS + length yourAssetNameSBS + length someAssetNameSBS` 54 | 55 | `pidSize`: the length of the hash of a policy (i.e., the length of the PolicyID). These lengths are the same for all policies, and are dictated by the current hashing algorithm used to compute payment and staking address hashes. 56 | 57 | `pidSize B = 28` currently (also, in the next era) 58 | 59 | `roundupBytesToWords` converts bytes to 8-byte long words, rounding up `roundupBytesToWords b = quot (b + 7) 8` 60 | 61 | `size B` is the size of the token bundle `B` in 8-byte long words: `size B = 6 + roundupBytesToWords (((numAssets B) * 12) + (sumAssetNameLengths B) + ((numPids B) * pidSize))` 62 | 63 | For a UTXO containing a token bundle `B` the `min-ada-value` calculation is as follows : 64 | 65 | - **Case 1**: Token bundle B in the UTXO `u` contains only ada (no other tokens) `minAda (u) = minUTxOValue` 66 | - **Case 2**: Token bundle B in the UTXO `u` contains ada as well as other tokens `minAda (u) = max (minUTxOValue, (quot (minUTxOValue, adaOnlyUTxOSize)) * (utxoEntrySizeWithoutVal + (size B)))` 67 | 68 | As a consequence of this design, 69 | 70 | - It is impossible to make outputs containing only custom tokens. 71 | - The number of each kind of token in an output does not affect the `min-ada-value` of the output, but the number of types of tokens contained in an output increases the min-value. 72 | - The reason for this is that the names and policy IDs of each of the types of tokens take up additional space in the output. 73 | - Sending custom tokens to an address always involves sending the `min-ada-value` of ada to that address alongside the custom tokens (by including the ada in the same output). If the address is not spendable by the user sending the tokens, the ada sent alongside the tokens no longer belongs to the sender. 74 | - Before transferring custom tokens, users may choose to use off-chain communication to negotiate who supplies the ada to cover the `min-ada-value` in the output made by the transferring transaction. 75 | - To recover the ada stored alongside custom tokens in an output *O*, the user must either:\ 76 | a) Spend the output *O*, and burn the custom tokens stored therein\ 77 | b) Spend an output *O* and an output *O’*, and consolidate the tokens therein with the same collection of types of custom tokens stored in another output (spent within the same transaction)\ 78 | E.g., `(CryptoDoggiesPolicy, poodle, 1)` contained in *O* can be consolidated with `(CryptoDoggiesPolicy, poodle, 3)` in *O’*, for a total of `(CryptoDoggiesPolicy, poodle, 4)` in a new output made by the consolidating transaction. 79 | 80 | - Splitting custom tokens into more outputs than they were contained in before the transaction getting processed requires using, in total, more ada to cover the `min-ada-value`, as ada is needed in the additional outputs. 81 | 82 | ![Minimum ada value](min-ada.png) 83 | -------------------------------------------------------------------------------- /release-information/comp-dependencies-new.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cardano-foundation/docs-cardano-org/c8fe0251d9bfb1e79c36eed289c9c2c2ae2545f0/release-information/comp-dependencies-new.png -------------------------------------------------------------------------------- /release-information/comp-matrix.md: -------------------------------------------------------------------------------- 1 | ## Component Compatibility with Cardano Node 2 | This Cardano components compatibility matrix shows the runtime Cardano component dependencies on a particular version of [cardano-node](https://github.com/input-output-hk/cardano-node/releases). (It does not reflect any stacks.) The compatibility matrix should be read in conjunction with the [Cardano component dependencies definition](https://docs.cardano.org/en/latest/release-information/comp-matrix.html#cardano-component-dependencies). 3 | 4 | Please note that Cardano Rest has been deprecated and replaced with Rosetta and [node version 1.25.1](https://github.com/input-output-hk/cardano-node/releases/tag/1.25.1) is the only node version that will work following the token locking Cardano update. 5 | 6 | | [Cardano Node](https://github.com/input-output-hk/cardano-node/releases) | [Cardano DB Sync](https://github.com/input-output-hk/cardano-db-sync/releases) | [Smash](https://github.com/input-output-hk/smash/releases) | [Cardano Rest](https://github.com/input-output-hk/cardano-rest/releases) | [Cardano GraphQL](https://github.com/input-output-hk/cardano-graphql/releases) | [Cardano Explorer](https://github.com/input-output-hk/cardano-explorer-app/releases) | [Cardano Wallet](https://github.com/input-output-hk/cardano-wallet/releases) | 7 | |---|---|---|---|---|---|---| 8 | | __[1.27](https://github.com/input-output-hk/cardano-node/releases/tag/1.27.0)__ | | | | | |[2021-06-11](https://github.com/input-output-hk/cardano-wallet/releases/tag/v2021-06-11) | 9 | | __[1.26.2](https://github.com/input-output-hk/cardano-node/releases/tag/1.26.2)__ | | | | | |[2021-04-28](https://github.com/input-output-hk/cardano-wallet/releases/tag/v2021-04-28) | 10 | | __[1.25.1](https://github.com/input-output-hk/cardano-node/releases/tag/1.25.1)__ | [8.0.0](https://github.com/input-output-hk/cardano-db-sync/releases/tag/8.0.0), [9.0.0](https://github.com/input-output-hk/cardano-db-sync/releases/tag/9.0.0) | [1.4.0](https://github.com/input-output-hk/smash/releases/tag/v1.4.0) | [3.1.2](https://github.com/input-output-hk/cardano-rest/releases/tag/3.1.2) | [3.2.0](https://github.com/input-output-hk/cardano-graphql/releases/tag/3.2.0) | [1.4.0](https://github.com/input-output-hk/cardano-explorer-app/releases/tag/1.4.0) | [2021.02.12](https://github.com/input-output-hk/cardano-wallet/releases/tag/v2021-02-12), [2021.02.15](https://github.com/input-output-hk/cardano-wallet/releases/tag/v2021-02-15) | 11 | | __[1.24.2](https://github.com/input-output-hk/cardano-node/releases/tag/1.24.2)__ | [7.1.0](https://github.com/input-output-hk/cardano-db-sync/releases/tag/7.1.0) | [1.3.0](https://github.com/input-output-hk/smash/releases/tag/1.3.0) | [3.1.1](https://github.com/input-output-hk/cardano-rest/releases/tag/3.1.1) | [3.1.1](https://github.com/input-output-hk/cardano-graphql/releases/tag/3.1.1) | [1.2.1](https://github.com/input-output-hk/cardano-explorer-app/releases/tag/1.2.1) | [2020.12.21](https://github.com/input-output-hk/cardano-wallet/releases/tag/v2020-12-21), [2020.01.12](https://github.com/input-output-hk/cardano-wallet/releases/tag/v2021-01-12) | 12 | | __[1.21.1](https://github.com/input-output-hk/cardano-node/releases/tag/1.21.1)__ | [5.0.2](https://github.com/input-output-hk/cardano-db-sync/releases/tag/5.0.2), [5.0.3](https://github.com/input-output-hk/cardano-db-sync/releases/tag/5.0.3), [6.0.0](https://github.com/input-output-hk/cardano-db-sync/releases/tag/6.0.0) | [1.2.0](https://github.com/input-output-hk/smash/releases/tag/1.2.0) | | [2.2.1](https://github.com/input-output-hk/cardano-graphql/releases/tag/2.2.1) | | [2020.10.13](https://github.com/input-output-hk/cardano-wallet/releases/tag/v2020-10-13) | 13 | | __[1.20.0](https://github.com/input-output-hk/cardano-node/releases/tag/1.20.0)__ | [5.0.1](https://github.com/input-output-hk/cardano-db-sync/releases/tag/5.0.1), [5.0.3](https://github.com/input-output-hk/cardano-db-sync/releases/tag/5.0.3) | | | [2.2.0](https://github.com/input-output-hk/cardano-graphql/releases/tag/2.2.0) | [1.2.0](https://github.com/input-output-hk/cardano-explorer-app/releases/tag/1.2.0) | [2020.9.22](https://github.com/input-output-hk/cardano-wallet/releases/tag/v2020-09-22), [2020.9.30](https://github.com/input-output-hk/cardano-wallet/releases/tag/v2020-09-30) | 14 | | __[1.19.1](https://github.com/input-output-hk/cardano-node/releases/tag/1.19.1)__ | [5.0.0](https://github.com/input-output-hk/cardano-db-sync/releases/tag/5.0.0), [5.0.1](https://github.com/input-output-hk/cardano-db-sync/releases/tag/5.0.1), [5.0.3](https://github.com/input-output-hk/cardano-db-sync/releases/tag/5.0.3) | | | [2.1.0](https://github.com/input-output-hk/cardano-graphql/releases/tag/2.1.0) | [1.1.0](https://github.com/input-output-hk/cardano-explorer-app/releases/tag/1.1.0) | [2020.9.11](https://github.com/input-output-hk/cardano-wallet/releases/tag/v2020-09-11) | 15 | | __[1.19.0](https://github.com/input-output-hk/cardano-node/releases/tag/1.19.0)__ | []() | [1.1.0](https://github.com/input-output-hk/smash/releases/tag/1.1.0) | | | | | 16 | | __[1.18.0](https://github.com/input-output-hk/cardano-node/releases/tag/1.18.0)__ | [4.0.0](https://github.com/input-output-hk/cardano-db-sync/releases/tag/4.0.0) | []() | | | | | 17 | | __[1.18.0](https://github.com/input-output-hk/cardano-node/releases/tag/1.18.0)__ | [3.1.0](https://github.com/input-output-hk/cardano-db-sync/releases/tag/3.1.0) |[1.0.1](https://github.com/input-output-hk/smash/releases/tag/1.0.1) | [2.1.3](https://github.com/input-output-hk/cardano-rest/releases/tag/2.1.3) | [2.0.0](https://github.com/input-output-hk/cardano-graphql/releases/tag/2.0.0) | [1.0.1](https://github.com/input-output-hk/cardano-explorer-app/releases/tag/1.0.1) | [2020.8.3](https://github.com/input-output-hk/cardano-wallet/releases/tag/v2020-08-03) | 18 | 19 | 20 | The following diagram outlines the various component dependencies: 21 | 22 | ![component dependencies](comp-dependencies-new.png) 23 | 24 | 25 | 26 | 27 | 28 | 29 | -------------------------------------------------------------------------------- /release-information/release-notes.md: -------------------------------------------------------------------------------- 1 | # Release Notes 2 | 3 | Here is the latest release information for the Cardano components. 4 | Component dependencies and compatibility information can be found in the [compatibility matrix](https://docs.cardano.org/en/latest/release-information/comp-matrix.html). 5 | Release notes for Cardano can be found in the [Cardano platform > Updates](https://iohk.zendesk.com/hc/en-us/sections/360002160134-Updates) section of the IOHK support desk. 6 | 7 | ## Latest Cardano component releases 8 | 9 | **Note**: *Cardano Rest has been deprecated and replaced with Rosetta. 10 | 11 | Name | Version | Release Date 12 | -|-|- 13 | [Cardano Node](https://github.com/input-output-hk/cardano-node) | [1.27.0](https://github.com/input-output-hk/cardano-node/releases/tag/1.27.0) | 13 May 2021 14 | [Cardano RTView](https://github.com/input-output-hk/cardano-rt-view) | [0.3.0](https://github.com/input-output-hk/cardano-rt-view/releases/tag/0.3.0) | 15 Janurary 2021 15 | [Cardano DB Sync](https://github.com/input-output-hk/cardano-db-sync/releases) | [9.0.0](https://github.com/input-output-hk/cardano-db-sync/releases/tag/9.0.0) | 24 March 2021 16 | [Smash](https://github.com/input-output-hk/smash) | [1.4.0](https://github.com/input-output-hk/smash/releases/tag/v1.4.0) | 29 January 2021 17 | [*Cardano Rest](https://github.com/input-output-hk/cardano-rest) | [3.1.2](https://github.com/input-output-hk/cardano-rest/releases/tag/3.1.2) | 1 February 2021 18 | [Cardano GraphQL](https://github.com/input-output-hk/cardano-graphql) | [4.0.0](https://github.com/input-output-hk/cardano-graphql/releases/tag/4.0.0) | 30 March 2021 19 | [Cardano Explorer](https://github.com/input-output-hk/cardano-explorer-app) | [1.5.0](https://github.com/input-output-hk/cardano-explorer-app/releases/tag/1.5.0) | 6 April 2021 20 | [Cardano Transactions](https://github.com/input-output-hk/cardano-transactions) | [1.0.0](https://github.com/input-output-hk/cardano-transactions/releases/tag/1.0.0) | 21 April 2020 21 | [Cardano Addresses](https://github.com/input-output-hk/cardano-addresses) | [3.4.0](https://github.com/input-output-hk/cardano-addresses/releases/tag/3.4.0) | 30 April 2021 22 | [Cardano Coin Selection](https://github.com/input-output-hk/cardano-coin-selection) | [1.0.1](https://github.com/input-output-hk/cardano-coin-selection/releases/tag/v1.0.1) | 13 May 2020 23 | [Bech32](https://github.com/input-output-hk/bech32) | [1.1.0](https://github.com/input-output-hk/bech32/releases/tag/v1.1.0) | 8 July 2020 24 | [Cardano Wallet](https://github.com/input-output-hk/cardano-wallet) | [2021.04.28](https://github.com/input-output-hk/cardano-wallet/releases/tag/v2021-04-28) | 30 April 2021 25 | 26 | 27 | -------------------------------------------------------------------------------- /rosetta/api-calls-rosetta.md: -------------------------------------------------------------------------------- 1 | ## API Calls ## 2 | This section outlines the available Rosetta API calls: 3 | 4 | **Get brief information about transactions** 5 | ``` 6 | $ curl -X POST '$BASEURL/block' \ 7 | -H "Content-Type: application/json" \ 8 | -d '{ "network_identifier": {"blockchain": "cardano", "network": "mainnet" }, "metadata": {}, "block_identifier": {"index": "5264122" }}' 9 | ``` 10 | **Get block’s summary information** 11 | ``` 12 | $ curl -X POST '$BASEURL/block' \ 13 | -H "Content-Type: application/json" \ 14 | -d '{ "network_identifier": {"blockchain": "cardano", "network": "mainnet" }, "metadata": {}, "block_identifier": {"index": "5264122" }}' 15 | ``` 16 | 17 | **Get information about the N latest transactions** 18 | ``` 19 | # Get the current block identifier 20 | $ curl -X POST '$BASEURL/network/status' \ 21 | -H "Content-Type: application/json" \ 22 | -d '{ "network_identifier": { "blockchain": "cardano", "network": "mainnet" }, "metadata": {} }' | jq .current_block_identifier.index 23 | 5264122 24 | 25 | # Fetch information from it 26 | $ curl -X POST '$BASEURL/block' \ 27 | -H "Content-Type: application/json" \ 28 | -d '{ "network_identifier": {"blockchain": "cardano", "network": "mainnet" }, "metadata": {}, "block_identifier": {"index": "5264122" }}' 29 | ``` 30 | **Get summary information about a transaction** 31 | ``` 32 | $ curl $BASEURL/api/txs/summary/382a5274ebf102910c6c923a8b11f108e79ecedb5d7433cd0dd15a8a443f0fa5 33 | Get summary information about an address 34 | $ curl -X POST '$BASEURL/account/balance' \ 35 | -H "Content-Type: application/json" \ 36 | -d '{ "network_identifier": { "blockchain": "cardano", "network": "mainnet" }, "metadata": {}, "account_identifier": { "address": "DdzFFzCqrhsqKd92VGNM9Ts1Ms62J2FaSRmf8t1bQa1VugDmcUJzeU8TRFnGDDUR6f1m9VaJJG1GfnzxVjKGBbBAVGT9sPBseREYzP3E" }, "metadata": {}}' 37 | ``` 38 | 39 | **Get address information specific to a block** 40 | ``` 41 | $ curl -X POST '$BASEURL/account/balance' \ 42 | -H "Content-Type: application/json" \ 43 | -d '{ "network_identifier": { "blockchain": "cardano", "network": "mainnet" }, "metadata": {}, "account_identifier": { "address": "DdzFFzCqrhsqKd92VGNM9Ts1Ms62J2FaSRmf8t1bQa1VugDmcUJzeU8TRFnGDDUR6f1m9VaJJG1GfnzxVjKGBbBAVGT9sPBseREYzP3E" }, "metadata": {}, "block_identifier": {"index": "5264122","hash": "b5426334221805b3c161ec07b02722728ced7b5c38a9cc60962e819620ecbf9a" },"currencies": {"symbol": "ada", "decimals": 8 }}' 44 | ``` -------------------------------------------------------------------------------- /rosetta/contribute-rosetta.md: -------------------------------------------------------------------------------- 1 | 2 | ### Contribute to Rosetta ### 3 | If you have produced material on the Rosetta project and would like to contribute your content for inclusion on this page, please click **Edit on Github** in the upper-right hand corner and submit an issue or PR. We will review your suggestions, and be in touch! 4 | -------------------------------------------------------------------------------- /rosetta/learn-Rosetta.md: -------------------------------------------------------------------------------- 1 | ## Learn about Rosetta ## 2 | 3 | Rosetta is an open source specification and set of tools that help you to integrate with blockchains. Serving as a general-purpose integration framework, Rosetta provides a high-level interface that can be customized to work with any chain. The goal of Rosetta is to make the integration process easier, faster, and more reliable so that you can build once and integrate your blockchain everywhere. 4 | 5 | We have created our unique `cardano-rosetta` implementation to simplify the process of integration with Cardano. To put this into context and illustrate the different implementations of Rosetta, bitcoin-rosetta and ethereum-rosetta also exist. The commonality between all implementations is that they all share the same interface. 6 | 7 | The rationale for integrating with Rosetta is that a single interface can interact seamlessly with all the blockchains that have implemented that interface. This is particularly useful for exchanges, for instance, since they can interact with the Cardano chain using the same interface that they might already be using to interact with other chains (Bitcoin, for example.) [Blockchain-specific operations](https://www.rosetta-api.org/docs/1.4.4/models/Operation.html) are interpreted to support the various chain implementations. 8 | 9 | You can read more on the [official Rosetta website](https://www.rosetta-api.org/). 10 | 11 | ### Rosetta Use Cases ### 12 | Typical use cases for using Rosetta include: 13 | - [Sending transactions](https://github.com/input-output-hk/cardano-rosetta/tree/master/examples#transaction-sending) 14 | - [Staking key registration and delegation](https://github.com/input-output-hk/cardano-rosetta/tree/master/examples#staking-key-registration-and-delegation) 15 | - [Withdrawals](https://github.com/input-output-hk/cardano-rosetta/tree/master/examples#withdrawals) 16 | - [Sending transactions with single multi assets](https://github.com/input-output-hk/cardano-rosetta/tree/master/examples#sending-transactions-with-single-multi-assets) 17 | -------------------------------------------------------------------------------- /rt-view/rt-view.md: -------------------------------------------------------------------------------- 1 | ## Cardano RTView 2 | [RTView](https://github.com/input-output-hk/cardano-rt-view/blob/master/doc/getting-started/install.md/) is a real time monitoring program that provides visibility on the state of running [Cardano nodes](https://github.com/input-output-hk/cardano-node/). It supports multiple node monitoring, even if the nodes work on different machines. 3 | 4 | RTView enables developers, testers, and general users who are running nodes that are connected to the real cluster to see what is going on and how the nodes are performing. It gives visibility on: how much memory and CPU is being used, the state of the blockchain, how many blocks have been forged by a particular node, how many transactions have been processed, and so on. 5 | 6 | It is a cross-platform tool compatible with Windows, Linux, and macOS, and has a web-based user interface so you can use any browser that you want. 7 | 8 | The main benefit of RTView is simplicity. It is simple to install, technically there is no installation, you just unpack an archive and run an executable. It is also simple to configure as it provides an interactive dialog for its configuration and shows particular changes the user should make in the node configuration files. It is also simple to view with any browser. 9 | 10 | RTView replaces the LiveView-mode feature in Cardano node and solves any previous LiveView limitations. Following the next release, LiveView will be removed from the node which will make the node much simpler and lighter, in terms of dependencies. 11 | 12 | ### How to set up RTView 13 | To set up RTView follow the [installation steps](https://github.com/input-output-hk/cardano-rt-view/blob/master/doc/getting-started/install.md/) to download, unpack, and run the tool. After you have completed these steps, RTView will be launched and ready to use. 14 | --------------------------------------------------------------------------------