-
<!doctype html><html lang=en class="js csstransforms3d"><head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=generator content="Hugo 0.76.5"><meta name=description content="User manual for Ogmios, a lightweight protocol translation service for Cardano."><meta name=author content="KtorZ <[email protected]>"><link rel=icon href=/images/favicon.png type=image/png><title>F.A.Q - Ogmios</title><link href=/css/nucleus.css?1675760323 rel=stylesheet><link href=/css/fontawesome-all.min.css?1675760323 rel=stylesheet><link href=/css/hybrid.css?1675760323 rel=stylesheet><link href=/css/featherlight.min.css?1675760323 rel=stylesheet><link href=/css/perfect-scrollbar.min.css?1675760323 rel=stylesheet><link href=/css/auto-complete.css?1675760323 rel=stylesheet><link href=/css/atom-one-dark-reasonable.css?1675760323 rel=stylesheet><link href=/css/theme.css?1675760323 rel=stylesheet><link href=/css/tabs.css?1675760323 rel=stylesheet><link href=/css/hugo-theme.css?1675760323 rel=stylesheet><link href=/css/theme-mine.css?1675760323 rel=stylesheet><script src=/js/jquery-3.3.1.min.js?1675760323></script><style>:root #header+#content>#left>#rlblock_left{display:none!important}</style></head><body data-url=/faq/><nav id=sidebar><div id=header-wrapper><div id=header><a href=/><img alt=ogmios src=/ogmios-logo-white.png></a></div><div class=searchbox><label for=search-by><i class="fas fa-search"></i></label><input data-search-input id=search-by type=search placeholder=Search...>
-
<span data-search-clear><i class="fas fa-times"></i></span></div><script type=text/javascript src=/js/lunr.min.js?1675760323></script><script type=text/javascript src=/js/auto-complete.js?1675760323></script><script type=text/javascript>var baseurl="https:\/\/ogmios.dev";</script><script type=text/javascript src=/js/search.js?1675760323></script></div><div class=highlightable><ul class=topics><li data-nav-id=/getting-started/ title="Getting Started" class=dd-item><a href=/getting-started/><b>1. </b>Getting Started</a><ul><li data-nav-id=/getting-started/docker/ title=Docker class=dd-item><a href=/getting-started/docker/>Docker</a></li><li data-nav-id=/getting-started/building/ title=Building class=dd-item><a href=/getting-started/building/>Building</a></li><li data-nav-id=/getting-started/testing/ title=Testing class=dd-item><a href=/getting-started/testing/>Testing</a></li><li data-nav-id=/getting-started/monitoring/ title=Monitoring class=dd-item><a href=/getting-started/monitoring/>Monitoring</a></li><li data-nav-id=/getting-started/basics/ title=Basics class=dd-item><a href=/getting-started/basics/>Basics</a></li></ul></li><li data-nav-id=/mini-protocols/ title="Ouroboros Mini-Protocols" class=dd-item><a href=/mini-protocols/><b>2. </b>Ouroboros Mini-Protocols</a><ul><li data-nav-id=/mini-protocols/local-chain-sync/ title="Local Chain Sync" class=dd-item><a href=/mini-protocols/local-chain-sync/>Local Chain Sync</a></li><li data-nav-id=/mini-protocols/local-state-query/ title="Local State Query" class=dd-item><a href=/mini-protocols/local-state-query/>Local State Query</a></li><li data-nav-id=/mini-protocols/local-tx-submission/ title="Local Tx Submission" class=dd-item><a href=/mini-protocols/local-tx-submission/>Local Tx Submission</a></li><li data-nav-id=/mini-protocols/local-tx-monitor/ title="Local Tx Monitor" class=dd-item><a href=/mini-protocols/local-tx-monitor/>Local Tx Monitor</a></li></ul></li><li data-nav-id=/typescript-client/ title=Clients class=dd-item><a href=/typescript-client/><b>3. </b>Clients</a><ul><li data-nav-id=/typescript-client/overview/ title=Overview class=dd-item><a href=/typescript-client/overview/>Overview</a></li><li data-nav-id=/typescript-client/chain-sync/ title="ChainSync Client" class=dd-item><a href=/typescript-client/chain-sync/>ChainSync Client</a></li><li data-nav-id=/typescript-client/state-query/ title="StateQuery Client" class=dd-item><a href=/typescript-client/state-query/>StateQuery Client</a></li><li data-nav-id=/typescript-client/tx-submission/ title="TxSubmission Client" class=dd-item><a href=/typescript-client/tx-submission/>TxSubmission Client</a></li><li data-nav-id=/typescript-client/tx-monitor/ title="TxMonitor Client" class=dd-item><a href=/typescript-client/tx-monitor/>TxMonitor Client</a></li></ul></li><li data-nav-id=/api/ title="API Reference" class=dd-item><a href=/api/><b>4. </b>API Reference</a></li><li data-nav-id=/changelog/ title=Changelog class=dd-item><a href=/changelog/><b>5. </b>Changelog</a></li><li data-nav-id=/faq/ title=F.A.Q class="dd-item
+
<!doctype html><html lang=en class="js csstransforms3d"><head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=generator content="Hugo 0.76.5"><meta name=description content="User manual for Ogmios, a lightweight protocol translation service for Cardano."><meta name=author content="KtorZ <[email protected]>"><link rel=icon href=/images/favicon.png type=image/png><title>F.A.Q - Ogmios</title><link href=/css/nucleus.css?1679765034 rel=stylesheet><link href=/css/fontawesome-all.min.css?1679765034 rel=stylesheet><link href=/css/hybrid.css?1679765034 rel=stylesheet><link href=/css/featherlight.min.css?1679765034 rel=stylesheet><link href=/css/perfect-scrollbar.min.css?1679765034 rel=stylesheet><link href=/css/auto-complete.css?1679765034 rel=stylesheet><link href=/css/atom-one-dark-reasonable.css?1679765034 rel=stylesheet><link href=/css/theme.css?1679765034 rel=stylesheet><link href=/css/tabs.css?1679765034 rel=stylesheet><link href=/css/hugo-theme.css?1679765034 rel=stylesheet><link href=/css/theme-mine.css?1679765034 rel=stylesheet><script src=/js/jquery-3.3.1.min.js?1679765034></script><style>:root #header+#content>#left>#rlblock_left{display:none!important}</style></head><body data-url=/faq/><nav id=sidebar><div id=header-wrapper><div id=header><a href=/><img alt=ogmios src=/ogmios-logo-white.png></a></div><div class=searchbox><label for=search-by><i class="fas fa-search"></i></label><input data-search-input id=search-by type=search placeholder=Search...>
+
<span data-search-clear><i class="fas fa-times"></i></span></div><script type=text/javascript src=/js/lunr.min.js?1679765034></script><script type=text/javascript src=/js/auto-complete.js?1679765034></script><script type=text/javascript>var baseurl="https:\/\/ogmios.dev";</script><script type=text/javascript src=/js/search.js?1679765034></script></div><div class=highlightable><ul class=topics><li data-nav-id=/getting-started/ title="Getting Started" class=dd-item><a href=/getting-started/><b>1. </b>Getting Started</a><ul><li data-nav-id=/getting-started/docker/ title=Docker class=dd-item><a href=/getting-started/docker/>Docker</a></li><li data-nav-id=/getting-started/building/ title=Building class=dd-item><a href=/getting-started/building/>Building</a></li><li data-nav-id=/getting-started/testing/ title=Testing class=dd-item><a href=/getting-started/testing/>Testing</a></li><li data-nav-id=/getting-started/monitoring/ title=Monitoring class=dd-item><a href=/getting-started/monitoring/>Monitoring</a></li><li data-nav-id=/getting-started/basics/ title=Basics class=dd-item><a href=/getting-started/basics/>Basics</a></li></ul></li><li data-nav-id=/mini-protocols/ title="Ouroboros Mini-Protocols" class=dd-item><a href=/mini-protocols/><b>2. </b>Ouroboros Mini-Protocols</a><ul><li data-nav-id=/mini-protocols/local-chain-sync/ title="Local Chain Sync" class=dd-item><a href=/mini-protocols/local-chain-sync/>Local Chain Sync</a></li><li data-nav-id=/mini-protocols/local-state-query/ title="Local State Query" class=dd-item><a href=/mini-protocols/local-state-query/>Local State Query</a></li><li data-nav-id=/mini-protocols/local-tx-submission/ title="Local Tx Submission" class=dd-item><a href=/mini-protocols/local-tx-submission/>Local Tx Submission</a></li><li data-nav-id=/mini-protocols/local-tx-monitor/ title="Local Tx Monitor" class=dd-item><a href=/mini-protocols/local-tx-monitor/>Local Tx Monitor</a></li></ul></li><li data-nav-id=/typescript-client/ title=Clients class=dd-item><a href=/typescript-client/><b>3. </b>Clients</a><ul><li data-nav-id=/typescript-client/overview/ title=Overview class=dd-item><a href=/typescript-client/overview/>Overview</a></li><li data-nav-id=/typescript-client/chain-sync/ title="ChainSync Client" class=dd-item><a href=/typescript-client/chain-sync/>ChainSync Client</a></li><li data-nav-id=/typescript-client/state-query/ title="StateQuery Client" class=dd-item><a href=/typescript-client/state-query/>StateQuery Client</a></li><li data-nav-id=/typescript-client/tx-submission/ title="TxSubmission Client" class=dd-item><a href=/typescript-client/tx-submission/>TxSubmission Client</a></li><li data-nav-id=/typescript-client/tx-monitor/ title="TxMonitor Client" class=dd-item><a href=/typescript-client/tx-monitor/>TxMonitor Client</a></li></ul></li><li data-nav-id=/api/ title="API Reference" class=dd-item><a href=/api/><b>4. </b>API Reference</a></li><li data-nav-id=/changelog/ title=Changelog class=dd-item><a href=/changelog/><b>5. </b>Changelog</a></li><li data-nav-id=/faq/ title=F.A.Q class="dd-item
-
active"><a href=/faq/><b>6. </b>F.A.Q</a></li></ul><section id=shortcuts><h3>More</h3><ul><li><a class=padding href=https://github.com/cardanosolutions/ogmios><i class="fab fa-github"></i>Source code</a></li><li><a class=padding href=https://github.com/cardanosolutions/ogmios/issues><i class="fab fa-solid fa-bullseye"></i>Issues Tracking</a></li><li><a class=padding href=https://discord.gg/ZeyDn65t5v><i class="fab fa-discord"></i>Discord (#ogmios)</a></li><li><a class=padding href=https://github.com/CardanoSolutions/ogmios/tree/master/architectural-decisions/accepted><i class="fab fa-solid fa-file-code"></i>Architectural Decisions Record</a></li></ul></section><section id=footer><style>i.fa-solid{margin-left:-2px!important;margin-right:-2px!important}</style></section></div></nav><section id=body><div id=overlay></div><div class="padding highlightable"><div><div id=top-bar><div id=breadcrumbs itemscope itemtype=http://data-vocabulary.org/Breadcrumb><span id=sidebar-toggle-span><a href=# id=sidebar-toggle data-sidebar-toggle><i class="fas fa-bars"></i></a></span><span id=toc-menu><i class="fas fa-list-alt"></i></span><span class=links><a href=/>Overview</a> > F.A.Q</span></div><div class=progress><div class=wrapper><nav id=TableOfContents><ul><li><ul><li></li></ul></li></ul></nav></div></div></div></div><div id=head-tags></div><div id=body-inner><h1>F.A.Q</h1><h4 id=can-you-explain-ogmios-in-one-three-sentences>Can you explain Ogmios in <del>one</del> three sentences?</h4><p>Ogmios is a lightweight bridge interface for <a href=https://github.com/input-output-hk/cardano-node/>cardano-node</a>. It offers a WebSockets API that enables local clients to speak <a href=https://hydra.iohk.io/build/1070091/download/1/network.pdf#chapter.3>Ouroboros' mini-protocols</a> via JSON/RPC. Ogmios is a fast and lightweight solution that can be deployed alongside relays to create entry points on the Cardano network for various types of applications (e.g. wallets, explorers, chatbots, dashboards…)</p><h4 id=can-you-explain-ogmios-to-me-like-im-five>Can you explain Ogmios to me like I’m five?</h4><p>To understand what Ogmios is, you must first understand where it fits in Cardano landscape. Cardano is a network of programs (a.k.a nodes) connected to each other and exchanging messages to run the Cardano blockchain. A Cardano node has an interface that allows for other programs to interact with it (very much like buttons on a remote to control the TV). However, that interface relies on novel communication methods, that were designed in-house by the networking team at IOG. To this day, the only tooling that fully implement those unique communication methods is written in Haskell<sup>*</sup> (as if all the buttons on the remote control were in Chinese, but you only speak French). So to interact with a Cardano node, one has no other choice than to write a Haskell program, which is a bummer for many application developers.</p><p>This is where Ogmios comes into play. Ogmios is written in Haskell, so it can speak with Cardano nodes just fine. But it also translates all the interfaces provided by the node using communication methods that are more common and accessible to the vast majority of developers (namely, WebSockets & JSON). Ogmios is a sort of translator; instead of speaking to a Cardano node directly, applications can speak to Ogmios using a language they know, and Ogmios translates it to the node and back to the applications.</p><blockquote><p>(*) Since 2022, <a href=https://github.com/txpipe/pallas#readme>Pallas</a> now provides most of the primitives also in Rust.</p></blockquote><h4 id=where-does-the-name-come-from>Where does the name come from?</h4><p>Ogmios is a <a href=https://en.wikipedia.org/wiki/Ogmios>celtic deity of eloquence</a>, language and learning. This relates to the way this project helps users communicate with Cardano. And while it doesn’t translate languages, it translates protocols to protocols.</p><h4 id=why-do-i-care>Why do I care?</h4><p>Well, it depends. In essence, Ogmios doesn’t do much more than what the node itself does. It’s pretty much as low-level as things can get with the Cardano network. For many applications, this is too low in the abstraction layer and they would be better off using higher-level services like <a href=https://github.com/input-output-hk/cardano-graphql>cardano-graphql</a>, <a href=https://www.rosetta-api.org/>Rosetta</a>, or <a href=https://blockfrost.io/>Blockfrost</a>.</p><p>However, building such services demands to be able to interact with the blockchain using a more direct interface. This interface can be Ogmios. Currently, the choices given to services like these are limited: talk directly to the node using the Haskell client library, or use cardano-db-sync which is a component that talks to the node and dumps blockchain data in a PostgreSQL database. For those who don’t write Haskell, the choice is even more limited; down to a single option. Plus, like any solution, it comes with trade-offs. Deploying a cardano-db-sync instance can be quite heavy, requires extra space, and already forces applications to operate in some specific ways. Ogmios gives a lightweight alternative that is also much closer to what the node offers. It would be possible for example to re-implement cardano-db-sync in a different programming language using Ogmios.</p><p>So in the end, if you’re writing a DApp or an application that needs to interact with the Cardano blockchain only at a high level using pre-defined abstractions, then you probably don’t care. However, if you’re doing some low-level work, and need to access every bit of the protocol or, if you’re building a service on top of Cardano for which the blockchain itself is the right level of abstraction, then Ogmios is most likely a good fit for you.</p><h4 id=can-i-build-x-using-ogmios>Can I build X using Ogmios?</h4><p>The short answer is: if you can build X with a Cardano node, then yes. Ogmios is as capable as the client interface for Cardano nodes. Can I build a wallet with Ogmios? Yes. Can I build an explorer with Ogmios? Yes. Can I build a smart-contract application backend with Ogmios? Yes. Anything available on-chain is available through Ogmios which has so far also transitioned through the 4 eras of Cardano. Ogmios' first release was a bit before the Shelley hard-fork, and its development followed the on-chain upgrades and protocol updates.</p><h4 id=whats-the-overhead-from-running-ogmios>What’s the overhead from running Ogmios?</h4><p>Almost none. Ogmios runs within a handful of megabytes of memory and its CPU usage is very much driven by whatever application you’ll be connecting to it. That is if your application is syncing the entire blockchain and sending thousands of messages per second to the underlying node, then of course your CPU will get pretty busy; not from Ogmios itself, however, but mostly from the underlying node and your client. In between, Ogmios acts as a bridge and passes messages around. Once a message has been passed, Ogmios forgets about it. That makes the memory footprint of Ogmios quite low, and its resource usages tightly linked to whatever application consumes data from it.</p><p>We secretly keep a hope that someday, many operators will deploy Ogmios alongside their relays. Enabling many application developers to interact with the Cardano blockchain seamlessly by connecting to a relay close to them.</p><h4 id=is-there-any-client-for-ogmios>Is there any client for Ogmios?</h4><p>As a matter of fact, there is. A <a href=https://github.com/cardanosolutions/ogmios/tree/master/clients/TypeScript#cardano-ogmios-typescript-client-packages>TypeScript client library and REPL</a> is available on the same repository. This client is also a first-class citizen within this user-guide so make sure to check out the <a href=/typescript-client/>TypeScript Client</a> section.</p><p>Since then, there has been other clients built by the community:</p><ul><li><a href=https://github.com/projectNEWM/kogmios>Kogmios (Kotlin)</a></li><li><a href=https://github.com/savaki/ogmigo/>Ogmigo (Go)</a></li></ul><p>Besides, it goes without saying that as an open-source project Ogmios welcomes contributions; especially on the client library and/or around tools built on top. Should you be working on a new client, let us know, we’re happy to help.</p><h4 id=does-ogmios-require-the-pab-plutus-application-backend-to-work>Does Ogmios require the PAB (Plutus Application Backend) to work?</h4><p>No it does not. The PAB is an application framework which provides DApp developers with an extra interface for running smart-contracts on Cardano; Ogmios is not a DApp, nor does it require any DApp functionality. Ogmios does however require a full cardano-node to work for it is merely an interface on top of it.</p><h4 id=can-i-use-ogmios-in-a-remote-setup>Can I use Ogmios in a remote setup?</h4><p>Yes. The easiest way is probably by using a reverse-proxy like <a href=https://www.nginx.com/>NGINX</a> to also promote the WebSocket connection to a secure connection. A more interesting question however is: should you? Ogmios is an interface for the so-called <strong>local</strong> client protocols which are, by design, intended to be used in a local setup: where Ogmios and cardano-node are on the same host. It would be ill-advised to expose the server to many clients without any restriction as each client can drain a quite large amount of resources from the local node. This is however totally acceptable in a controlled environment, where for example, your own stack would leverage a single Ogmios instance to power few remote services.</p><h4 id=why-do-ogmios-returns-json-with-integers-larger-than-max_safe_integer>Why do Ogmios returns JSON with integers larger than <code>MAX_SAFE_INTEGER</code>?</h4><p>JSON does support large integers by design. The default JavaScript JSON parser does not however. Thus, it is not a problem which lies on the server-side, but rather on “naive” JavaScript clients. For more details, have a look at this <a href=https://github.com/CardanoSolutions/ogmios/blob/master/architectural-decisions/accepted/typescript-client-bigint-parsing.md>architectural decision record</a> which explains how we handle large integers in the TypeScript client.</p><h4 id=is-ogmios-production-ready>Is Ogmios production ready?</h4><p>Ogmios is an open-source project which is being worked on in small steps when time allows. Its development started in 2020 and it has undergone several updates and iterations. We’ve got a mad passion for software quality and we put extensive efforts into making Ogmios of the highest quality. The server follows a well-known architecture and abides by battle-tested Haskell coding practices. As it should, Ogmios is of course deeply tested at several levels via <strong>continuous integration</strong><sup><a href=https://github.com/CardanoSolutions/ogmios/actions>1</a></sup>.</p><p>Tests for the server include <strong>property-based testing</strong> of the core protocols<sup><a href=https://github.com/CardanoSolutions/ogmios/blob/master/server/test/unit/Ogmios/App/Protocol/StateQuerySpec.hs>2</a></sup> <sup><a href=https://github.com/CardanoSolutions/ogmios/blob/master/server/test/unit/Ogmios/App/Protocol/StateQuerySpec.hs>3</a></sup>, property-based testing of the entire JSON interface validated against a JSON-schema specification<sup><a href=https://github.com/CardanoSolutions/ogmios/blob/master/server/test/unit/Ogmios/Data/JsonSpec.hs>4</a></sup>. Note that property tests all use generators which comes directly from the <a href=https://github.com/input-output-hk/ouroboros-network/>ouroboros-network</a> and <a href=https://github.com/input-output-hk/cardano-ledger-specs>cardano-ledger-specs</a> to ensure that Ogmios is <strong>always up-to-date</strong> with the Cardano eco-system. There are also various<sup><a href=https://github.com/CardanoSolutions/ogmios/blob/master/server/test/unit/Ogmios/App/OptionsSpec.hs>5</a></sup> unit<sup><a href=https://github.com/CardanoSolutions/ogmios/blob/master/server/test/unit/Ogmios/Data/MetricsSpec.hs>6</a></sup> tests<sup><a href=https://github.com/CardanoSolutions/ogmios/blob/master/server/test/unit/Ogmios/Data/HealthSpec.hs>7</a></sup> to cover basic functionalities.</p><p>On the other hand, the TypeScript client is used to perform <strong>end-to-end tests</strong> with tests running against the Cardano testnet<sup><a href=https://github.com/CardanoSolutions/ogmios/tree/master/clients/TypeScript/packages/client/test>8</a></sup>. The tests are executed both in a Node.js and browser context and the synchronization with the network is done via a <a href=https://github.com/CardanoSolutions/gh-action-cardano-node-ogmios-docker-sync>Github action which leverages Ogmios' server</a>.</p><p>Beside, Ogmios also comes with <strong>structured logging and monitoring</strong> out of the box. Putting any monitoring solution on top like Prometheus is trivial.</p><p>Finally, if you ventured through this page and user-guide, you have also noticed that the project is <strong>well-documented</strong>. And this includes the <a href=/api>API reference</a>, the <a href=/changelog>ChangeLog</a> as well as the <a href=https://github.com/CardanoSolutions/ogmios/tree/master/architectural-decisions>architectural decisions</a> going over rationales for decisions we made along the way.</p><p>Thus, is Ogmios production-ready? <strong>Yes</strong>. At least, this is as good as it gets for an open-source project. We’ve been incorporating feedback from various users over the past year which has been great so far. For the rest, everything is open-source licensed under <a href=https://choosealicense.com/licenses/mpl-2.0/>MPL-2.0</a> and <strong>you’re the best judge.</strong></p><h4 id=are-there-any-projectscompanies-using-it>Are there any projects/companies using it?</h4><p>We’ve heard of a handful happy users! And it keeps growing! To name a few…:</p><ul><li><a href=https://blockfrost.io/>https://blockfrost.io/</a></li><li><a href=https://eternl.io/>https://eternl.io/</a></li><li><a href=https://www.sundaeswap.finance/>https://www.sundaeswap.finance/</a></li><li><a href=https://jpeg.store/>https://jpeg.store/</a></li><li><a href=https://spacebudz.io/>https://spacebudz.io/</a></li><li><a href=https://www.tangocrypto.com/>https://www.tangocrypto.com/</a></li><li><a href=https://projectnewm.io/>https://projectnewm.io/</a></li><li><a href=https://github.com/input-output-hk/cardano-graphql>https://github.com/input-output-hk/cardano-graphql</a></li><li><a href=https://mlabs.city/>https://mlabs.city/</a></li><li><a href=https://gimbalabs.com/>https://gimbalabs.com/</a></li><li><a href=https://www.f2lb.org/>https://www.f2lb.org/</a></li></ul><div class="notices note"><p>Are you using Ogmios for a project? <a href="https://github.com/CardanoSolutions/ogmios/issues/new?assignees=&labels=&template=project.md">Let us know on Github!</a></p></div><footer class=footline></footer></div></div><div id=navigation><a class="nav nav-prev" href=/changelog/ title=Changelog><i class="fa fa-chevron-left"></i></a><a class="nav nav-next" href=/getting-started/ title="Getting Started" style=margin-right:0><i class="fa fa-chevron-right"></i></a></div></section><div style=left:-1000px;overflow:scroll;position:absolute;top:-1000px;border:none;box-sizing:content-box;height:200px;margin:0;padding:0;width:200px><div style=border:none;box-sizing:content-box;height:200px;margin:0;padding:0;width:200px></div></div><script src=/js/clipboard.min.js?1675760323></script><script src=/js/perfect-scrollbar.min.js?1675760323></script><script src=/js/perfect-scrollbar.jquery.min.js?1675760323></script><script src=/js/jquery.sticky.js?1675760323></script><script src=/js/featherlight.min.js?1675760323></script><script src=/js/highlight.pack.js?1675760323></script><script>hljs.initHighlightingOnLoad();</script><script src=/js/modernizr.custom-3.6.0.js?1675760323></script><script src=/js/learn.js?1675760323></script><script src=/js/hugo-learn.js?1675760323></script></body></html>
\ No newline at end of file
+
active"><a href=/faq/><b>6. </b>F.A.Q</a></li></ul><section id=shortcuts><h3>More</h3><ul><li><a class=padding href=https://github.com/cardanosolutions/ogmios><i class="fab fa-github"></i>Source code</a></li><li><a class=padding href=https://github.com/cardanosolutions/ogmios/issues><i class="fab fa-solid fa-bullseye"></i>Issues Tracking</a></li><li><a class=padding href=https://discord.gg/ZeyDn65t5v><i class="fab fa-discord"></i>Discord (#ogmios)</a></li><li><a class=padding href=https://github.com/CardanoSolutions/ogmios/tree/master/architectural-decisions/accepted><i class="fab fa-solid fa-file-code"></i>Architectural Decisions Record</a></li></ul></section><section id=footer><style>i.fa-solid{margin-left:-2px!important;margin-right:-2px!important}</style></section></div></nav><section id=body><div id=overlay></div><div class="padding highlightable"><div><div id=top-bar><div id=breadcrumbs itemscope itemtype=http://data-vocabulary.org/Breadcrumb><span id=sidebar-toggle-span><a href=# id=sidebar-toggle data-sidebar-toggle><i class="fas fa-bars"></i></a></span><span id=toc-menu><i class="fas fa-list-alt"></i></span><span class=links><a href=/>Overview</a> > F.A.Q</span></div><div class=progress><div class=wrapper><nav id=TableOfContents><ul><li><ul><li></li></ul></li></ul></nav></div></div></div></div><div id=head-tags></div><div id=body-inner><h1>F.A.Q</h1><h4 id=can-you-explain-ogmios-in-one-three-sentences>Can you explain Ogmios in <del>one</del> three sentences?</h4><p>Ogmios is a lightweight bridge interface for <a href=https://github.com/input-output-hk/cardano-node/>cardano-node</a>. It offers a WebSockets API that enables local clients to speak <a href=https://hydra.iohk.io/build/1070091/download/1/network.pdf#chapter.3>Ouroboros' mini-protocols</a> via JSON/RPC. Ogmios is a fast and lightweight solution that can be deployed alongside relays to create entry points on the Cardano network for various types of applications (e.g. wallets, explorers, chatbots, dashboards…)</p><h4 id=can-you-explain-ogmios-to-me-like-im-five>Can you explain Ogmios to me like I’m five?</h4><p>To understand what Ogmios is, you must first understand where it fits in Cardano landscape. Cardano is a network of programs (a.k.a nodes) connected to each other and exchanging messages to run the Cardano blockchain. A Cardano node has an interface that allows for other programs to interact with it (very much like buttons on a remote to control the TV). However, that interface relies on novel communication methods, that were designed in-house by the networking team at IOG. To this day, the only tooling that fully implement those unique communication methods is written in Haskell<sup>*</sup> (as if all the buttons on the remote control were in Chinese, but you only speak French). So to interact with a Cardano node, one has no other choice than to write a Haskell program, which is a bummer for many application developers.</p><p>This is where Ogmios comes into play. Ogmios is written in Haskell, so it can speak with Cardano nodes just fine. But it also translates all the interfaces provided by the node using communication methods that are more common and accessible to the vast majority of developers (namely, WebSockets & JSON). Ogmios is a sort of translator; instead of speaking to a Cardano node directly, applications can speak to Ogmios using a language they know, and Ogmios translates it to the node and back to the applications.</p><blockquote><p>(*) Since 2022, <a href=https://github.com/txpipe/pallas#readme>Pallas</a> now provides most of the primitives also in Rust.</p></blockquote><h4 id=where-does-the-name-come-from>Where does the name come from?</h4><p>Ogmios is a <a href=https://en.wikipedia.org/wiki/Ogmios>celtic deity of eloquence</a>, language and learning. This relates to the way this project helps users communicate with Cardano. And while it doesn’t translate languages, it translates protocols to protocols.</p><h4 id=why-do-i-care>Why do I care?</h4><p>Well, it depends. In essence, Ogmios doesn’t do much more than what the node itself does. It’s pretty much as low-level as things can get with the Cardano network. For many applications, this is too low in the abstraction layer and they would be better off using higher-level services like <a href=https://github.com/input-output-hk/cardano-graphql>cardano-graphql</a>, <a href=https://www.rosetta-api.org/>Rosetta</a>, or <a href=https://blockfrost.io/>Blockfrost</a>.</p><p>However, building such services demands to be able to interact with the blockchain using a more direct interface. This interface can be Ogmios. Currently, the choices given to services like these are limited: talk directly to the node using the Haskell client library, or use cardano-db-sync which is a component that talks to the node and dumps blockchain data in a PostgreSQL database. For those who don’t write Haskell, the choice is even more limited; down to a single option. Plus, like any solution, it comes with trade-offs. Deploying a cardano-db-sync instance can be quite heavy, requires extra space, and already forces applications to operate in some specific ways. Ogmios gives a lightweight alternative that is also much closer to what the node offers. It would be possible for example to re-implement cardano-db-sync in a different programming language using Ogmios.</p><p>So in the end, if you’re writing a DApp or an application that needs to interact with the Cardano blockchain only at a high level using pre-defined abstractions, then you probably don’t care. However, if you’re doing some low-level work, and need to access every bit of the protocol or, if you’re building a service on top of Cardano for which the blockchain itself is the right level of abstraction, then Ogmios is most likely a good fit for you.</p><h4 id=can-i-build-x-using-ogmios>Can I build X using Ogmios?</h4><p>The short answer is: if you can build X with a Cardano node, then yes. Ogmios is as capable as the client interface for Cardano nodes. Can I build a wallet with Ogmios? Yes. Can I build an explorer with Ogmios? Yes. Can I build a smart-contract application backend with Ogmios? Yes. Anything available on-chain is available through Ogmios which has so far also transitioned through the 4 eras of Cardano. Ogmios' first release was a bit before the Shelley hard-fork, and its development followed the on-chain upgrades and protocol updates.</p><h4 id=whats-the-overhead-from-running-ogmios>What’s the overhead from running Ogmios?</h4><p>Almost none. Ogmios runs within a handful of megabytes of memory and its CPU usage is very much driven by whatever application you’ll be connecting to it. That is if your application is syncing the entire blockchain and sending thousands of messages per second to the underlying node, then of course your CPU will get pretty busy; not from Ogmios itself, however, but mostly from the underlying node and your client. In between, Ogmios acts as a bridge and passes messages around. Once a message has been passed, Ogmios forgets about it. That makes the memory footprint of Ogmios quite low, and its resource usages tightly linked to whatever application consumes data from it.</p><p>We secretly keep a hope that someday, many operators will deploy Ogmios alongside their relays. Enabling many application developers to interact with the Cardano blockchain seamlessly by connecting to a relay close to them.</p><h4 id=is-there-any-client-for-ogmios>Is there any client for Ogmios?</h4><p>As a matter of fact, there is. A <a href=https://github.com/cardanosolutions/ogmios/tree/master/clients/TypeScript#cardano-ogmios-typescript-client-packages>TypeScript client library and REPL</a> is available on the same repository. This client is also a first-class citizen within this user-guide so make sure to check out the <a href=/typescript-client/>TypeScript Client</a> section.</p><p>Since then, there has been other clients built by the community:</p><ul><li><a href=https://github.com/projectNEWM/kogmios>Kogmios (Kotlin)</a></li><li><a href=https://github.com/savaki/ogmigo/>Ogmigo (Go)</a></li></ul><p>Besides, it goes without saying that as an open-source project Ogmios welcomes contributions; especially on the client library and/or around tools built on top. Should you be working on a new client, let us know, we’re happy to help.</p><h4 id=does-ogmios-require-the-pab-plutus-application-backend-to-work>Does Ogmios require the PAB (Plutus Application Backend) to work?</h4><p>No it does not. The PAB is an application framework which provides DApp developers with an extra interface for running smart-contracts on Cardano; Ogmios is not a DApp, nor does it require any DApp functionality. Ogmios does however require a full cardano-node to work for it is merely an interface on top of it.</p><h4 id=can-i-use-ogmios-in-a-remote-setup>Can I use Ogmios in a remote setup?</h4><p>Yes. The easiest way is probably by using a reverse-proxy like <a href=https://www.nginx.com/>NGINX</a> to also promote the WebSocket connection to a secure connection. A more interesting question however is: should you? Ogmios is an interface for the so-called <strong>local</strong> client protocols which are, by design, intended to be used in a local setup: where Ogmios and cardano-node are on the same host. It would be ill-advised to expose the server to many clients without any restriction as each client can drain a quite large amount of resources from the local node. This is however totally acceptable in a controlled environment, where for example, your own stack would leverage a single Ogmios instance to power few remote services.</p><h4 id=why-do-ogmios-returns-json-with-integers-larger-than-max_safe_integer>Why do Ogmios returns JSON with integers larger than <code>MAX_SAFE_INTEGER</code>?</h4><p>JSON does support large integers by design. The default JavaScript JSON parser does not however. Thus, it is not a problem which lies on the server-side, but rather on “naive” JavaScript clients. For more details, have a look at this <a href=https://github.com/CardanoSolutions/ogmios/blob/master/architectural-decisions/accepted/typescript-client-bigint-parsing.md>architectural decision record</a> which explains how we handle large integers in the TypeScript client.</p><h4 id=is-ogmios-production-ready>Is Ogmios production ready?</h4><p>Ogmios is an open-source project which is being worked on in small steps when time allows. Its development started in 2020 and it has undergone several updates and iterations. We’ve got a mad passion for software quality and we put extensive efforts into making Ogmios of the highest quality. The server follows a well-known architecture and abides by battle-tested Haskell coding practices. As it should, Ogmios is of course deeply tested at several levels via <strong>continuous integration</strong><sup><a href=https://github.com/CardanoSolutions/ogmios/actions>1</a></sup>.</p><p>Tests for the server include <strong>property-based testing</strong> of the core protocols<sup><a href=https://github.com/CardanoSolutions/ogmios/blob/master/server/test/unit/Ogmios/App/Protocol/StateQuerySpec.hs>2</a></sup> <sup><a href=https://github.com/CardanoSolutions/ogmios/blob/master/server/test/unit/Ogmios/App/Protocol/StateQuerySpec.hs>3</a></sup>, property-based testing of the entire JSON interface validated against a JSON-schema specification<sup><a href=https://github.com/CardanoSolutions/ogmios/blob/master/server/test/unit/Ogmios/Data/JsonSpec.hs>4</a></sup>. Note that property tests all use generators which comes directly from the <a href=https://github.com/input-output-hk/ouroboros-network/>ouroboros-network</a> and <a href=https://github.com/input-output-hk/cardano-ledger-specs>cardano-ledger-specs</a> to ensure that Ogmios is <strong>always up-to-date</strong> with the Cardano eco-system. There are also various<sup><a href=https://github.com/CardanoSolutions/ogmios/blob/master/server/test/unit/Ogmios/App/OptionsSpec.hs>5</a></sup> unit<sup><a href=https://github.com/CardanoSolutions/ogmios/blob/master/server/test/unit/Ogmios/Data/MetricsSpec.hs>6</a></sup> tests<sup><a href=https://github.com/CardanoSolutions/ogmios/blob/master/server/test/unit/Ogmios/Data/HealthSpec.hs>7</a></sup> to cover basic functionalities.</p><p>On the other hand, the TypeScript client is used to perform <strong>end-to-end tests</strong> with tests running against the Cardano testnet<sup><a href=https://github.com/CardanoSolutions/ogmios/tree/master/clients/TypeScript/packages/client/test>8</a></sup>. The tests are executed both in a Node.js and browser context and the synchronization with the network is done via a <a href=https://github.com/CardanoSolutions/gh-action-cardano-node-ogmios-docker-sync>Github action which leverages Ogmios' server</a>.</p><p>Beside, Ogmios also comes with <strong>structured logging and monitoring</strong> out of the box. Putting any monitoring solution on top like Prometheus is trivial.</p><p>Finally, if you ventured through this page and user-guide, you have also noticed that the project is <strong>well-documented</strong>. And this includes the <a href=/api>API reference</a>, the <a href=/changelog>ChangeLog</a> as well as the <a href=https://github.com/CardanoSolutions/ogmios/tree/master/architectural-decisions>architectural decisions</a> going over rationales for decisions we made along the way.</p><p>Thus, is Ogmios production-ready? <strong>Yes</strong>. At least, this is as good as it gets for an open-source project. We’ve been incorporating feedback from various users over the past year which has been great so far. For the rest, everything is open-source licensed under <a href=https://choosealicense.com/licenses/mpl-2.0/>MPL-2.0</a> and <strong>you’re the best judge.</strong></p><h4 id=are-there-any-projectscompanies-using-it>Are there any projects/companies using it?</h4><p>We’ve heard of a handful happy users! And it keeps growing! To name a few…:</p><ul><li><a href=https://blockfrost.io/>https://blockfrost.io/</a></li><li><a href=https://eternl.io/>https://eternl.io/</a></li><li><a href=https://www.sundaeswap.finance/>https://www.sundaeswap.finance/</a></li><li><a href=https://jpeg.store/>https://jpeg.store/</a></li><li><a href=https://spacebudz.io/>https://spacebudz.io/</a></li><li><a href=https://www.tangocrypto.com/>https://www.tangocrypto.com/</a></li><li><a href=https://projectnewm.io/>https://projectnewm.io/</a></li><li><a href=https://github.com/input-output-hk/cardano-graphql>https://github.com/input-output-hk/cardano-graphql</a></li><li><a href=https://mlabs.city/>https://mlabs.city/</a></li><li><a href=https://gimbalabs.com/>https://gimbalabs.com/</a></li><li><a href=https://www.f2lb.org/>https://www.f2lb.org/</a></li></ul><div class="notices note"><p>Are you using Ogmios for a project? <a href="https://github.com/CardanoSolutions/ogmios/issues/new?assignees=&labels=&template=project.md">Let us know on Github!</a></p></div><footer class=footline></footer></div></div><div id=navigation><a class="nav nav-prev" href=/changelog/ title=Changelog><i class="fa fa-chevron-left"></i></a><a class="nav nav-next" href=/getting-started/ title="Getting Started" style=margin-right:0><i class="fa fa-chevron-right"></i></a></div></section><div style=left:-1000px;overflow:scroll;position:absolute;top:-1000px;border:none;box-sizing:content-box;height:200px;margin:0;padding:0;width:200px><div style=border:none;box-sizing:content-box;height:200px;margin:0;padding:0;width:200px></div></div><script src=/js/clipboard.min.js?1679765034></script><script src=/js/perfect-scrollbar.min.js?1679765034></script><script src=/js/perfect-scrollbar.jquery.min.js?1679765034></script><script src=/js/jquery.sticky.js?1679765034></script><script src=/js/featherlight.min.js?1679765034></script><script src=/js/highlight.pack.js?1679765034></script><script>hljs.initHighlightingOnLoad();</script><script src=/js/modernizr.custom-3.6.0.js?1679765034></script><script src=/js/learn.js?1679765034></script><script src=/js/hugo-learn.js?1679765034></script></body></html>
\ No newline at end of file
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4&s=80)
