diff --git a/404.html b/404.html index dcaa9f1dd..c3fc92b66 100644 --- a/404.html +++ b/404.html @@ -1 +1 @@ -404 Page not found

Error

Woops. Looks like this page doesn't exist ¯\_(ツ)_/¯.

Go to homepage

Page not found!

\ No newline at end of file +404 Page not found

Error

Woops. Looks like this page doesn't exist ¯\_(ツ)_/¯.

Go to homepage

Page not found!

\ No newline at end of file diff --git a/api/index.html b/api/index.html index 9d2ce50f8..b9c2f6970 100644 --- a/api/index.html +++ b/api/index.html @@ -1,4 +1,4 @@ -WebSocket API Reference (v6.6.*) - Ogmios

WebSocket API Reference (v6.6.*)

\ No newline at end of file diff --git a/api/v5.6/index.html b/api/v5.6/index.html index a1dd4479f..2a290a9f5 100644 --- a/api/v5.6/index.html +++ b/api/v5.6/index.html @@ -1,3 +1,3 @@ -Archive (v5.6.*) - Ogmios

Archive (v5.6.*)

\ No newline at end of file +Archive (v5.6.*) - Ogmios

Archive (v5.6.*)

\ No newline at end of file diff --git a/api/v6.0/index.html b/api/v6.0/index.html index 1aad9804b..00c422df6 100644 --- a/api/v6.0/index.html +++ b/api/v6.0/index.html @@ -1,3 +1,3 @@ -Archive (v6.0.*) - Ogmios

Archive (v6.0.*)

\ No newline at end of file +Archive (v6.0.*) - Ogmios

Archive (v6.0.*)

\ No newline at end of file diff --git a/api/v6.1/index.html b/api/v6.1/index.html index 078654c60..5d6b2c3c8 100644 --- a/api/v6.1/index.html +++ b/api/v6.1/index.html @@ -1,3 +1,3 @@ -Archive (v6.1.*) - Ogmios

Archive (v6.1.*)

\ No newline at end of file +Archive (v6.1.*) - Ogmios

Archive (v6.1.*)

\ No newline at end of file diff --git a/api/v6.2/index.html b/api/v6.2/index.html index 1fccd4a96..dace30f26 100644 --- a/api/v6.2/index.html +++ b/api/v6.2/index.html @@ -1,3 +1,3 @@ -Archive (v6.2.*) - Ogmios

Archive (v6.2.*)

\ No newline at end of file +Archive (v6.2.*) - Ogmios

Archive (v6.2.*)

\ No newline at end of file diff --git a/api/v6.3/index.html b/api/v6.3/index.html index 193c6f33a..199f11cbe 100644 --- a/api/v6.3/index.html +++ b/api/v6.3/index.html @@ -1,3 +1,3 @@ -Archive (v6.3.*) - Ogmios

Archive (v6.3.*)

\ No newline at end of file +Archive (v6.3.*) - Ogmios

Archive (v6.3.*)

\ No newline at end of file diff --git a/api/v6.4/index.html b/api/v6.4/index.html index bc686de32..79827e3b7 100644 --- a/api/v6.4/index.html +++ b/api/v6.4/index.html @@ -1,3 +1,3 @@ -Archive (v6.4.*) - Ogmios

Archive (v6.4.*)

\ No newline at end of file +Archive (v6.4.*) - Ogmios

Archive (v6.4.*)

\ No newline at end of file diff --git a/api/v6.5/index.html b/api/v6.5/index.html index 7c11b18bd..27093a7f1 100644 --- a/api/v6.5/index.html +++ b/api/v6.5/index.html @@ -1,3 +1,3 @@ -Archive (v6.5.*) - Ogmios

Archive (v6.5.*)

\ No newline at end of file +Archive (v6.5.*) - Ogmios

Archive (v6.5.*)

\ No newline at end of file diff --git a/categories/index.html b/categories/index.html index 28389867b..b32d4860b 100644 --- a/categories/index.html +++ b/categories/index.html @@ -1,3 +1,3 @@ -Categories - Ogmios

category :: -Categories

    \ No newline at end of file +Categories - Ogmios

    category :: +Categories

      \ No newline at end of file diff --git a/changelog/index.html b/changelog/index.html index 4875a0ee0..29007006a 100644 --- a/changelog/index.html +++ b/changelog/index.html @@ -1,7 +1,7 @@ -Changelog - Ogmios

      Changelog

      [6.6.1] - 2024-09-01

      Added

      • N/A

      Changed

      • Fixed "babbage" being reported as the block era for Conway blocks.

      Removed

      • N/A

      [6.6.0] - 2024-08-15

      Added

      • Add missing treasury.value and treasury.donation for Conway transactions.

      • Add missing protocolParametersUpdate.security thresholds to stake pools voting thresholds in Conway governance actions.

      • Add missing ancestor to various governance actions, pointing to the previous action of the same group.

      • Add a new from field to objects referring to stake credential. The field allows to distinguish between verification key and script credentials.

      • TypeScript The stakePools method on the LedgerStateQueryClient now supports an extra filter. The filters were available on th standalone query but not via the client somehow.

      Changed

      • Fix upgradability of Alonzo/Babbage transactions into Conway transactions. Before, Babbage transaction submitted for evaluation that spent Plutus V3 Scripts while using a Babbage serialization format would failed to upgrade into Conway transactions due to incompatibility at the binary level. The translation has been fixed, except for truly incompatible transactions (e.g. those containing MIR or duplicate certificates).

      • Refresh embedded configuration files to match those expected by cardano-node==9.1.0 (in particular, genesis files for mainnet, preview and preprod).

      • Only return OverlappingAdditionalUtxo error during transaction simulation when overlapping utxo differ from the ones fetched from the ledger.

      Removed

      • ø

      [6.5.0] - 2024-07-12

      Added

      • Integrated with cardano-node==9.0.0.

      • New ledger-state query: queryLedgerState/treasuryAndReserves to retrieve the current Ada values of the treasury and reserves.

      • New protocol parameters in Conway:

        • maximumReferenceScriptsSize which indicates the maximum total number of bytes of scripts referenced by a transaction.
        • minFeeReferenceScripts with three sub fields: range, base and multiplier that now intervenes in the minimum fee calculation. Note that, starting in the Conway era, the min fee calculation is given by the following formula:

      $$ minFee = A + B + C $$

      $$ \begin{array}{lll} @@ -41,4 +41,4 @@ Ogmios will omit fields such as witnesses, proofs and signatures from responses to make responses smaller.

    • Provide missing documentation / JSON-schema for:
      • JSON-WSP faults
      • Allegra & Mary SubmitTx failures:

        • Allegra:

          • expiredUtxo is replaced by outsideOfValidityInterval
          • new error triesToForgeAda

          Mary:

          • valueNotConserved.consumed is now a Value (instead of a DeltaCoin)
          • valueNotConserved.produced is now a Value (instead of a DeltaCoin)
          • outputTooSmall items are now of type TxOut[Mary]
          • new error tooManyAssetsInOutput
    • Continuous integration job checking for code style and lint on the server source code.
    • The /health endpoint now returns two additional pieces of information:
      • A networkSynchronization percentage to indicate how far Ogmios / the node is from the network.
      • A currentEra value to indicate the corresponding Cardano era Ogmios / the node is currently running in.
    • Nix support for building Ogmios (this also include a cabal.project to enable cabal support as well).

      • Changed

      • Rework Docker setup to not require an external snapshot image. Everything is now built in a single Dockerfile, but cache from DockerHub can be leveraged to reduce overall build time when building from scratch.
      • Fixed typo in the JSON-schema w.r.t to the ‘Acquire’ request (points → point), and introduce more automated test -to catch this kind of errors more easily.

      Removed

      ø

      [3.1.0] - 2021-04-04

      Added

      • Extend the local-state query protocol with support for ‘GetCompactGenesis’.
      • Extend the local-state query protocol with support for ‘GetFilteredDelegationsAndRewards’.
      • Add missing mint field to transaction’s body (added since mary).
      • The documentation is now hosted on https://ogmios.dev.

      Changed

      • Use ‘contentEncoding’ over ‘format’ in appropriate part of the JSON schema.
      • Fix various errors in the JSON-schema definition & extend test suite coverage in consequence.
      • Implement a ‘fast-bech32’ encoding library, to speed-up Ogmios serialization of blocks beyond the Shelley era.
      • Use faster (and recommended) JSON encoding techniques to speed up overall JSON serialization.
      • Improve generated documentation from JSON schema by:
        • Providing titles to ‘oneOf’ items
        • Adding descriptions to top-level definitions
        • Adding examples to top-level definitions
      • Customized API reference’s stylesheet to enhance readability.
      • Upgrade dependency and code to work with GHC-8.10.4 (from GHC 8.6.5)
      • Handle more gracefully unknown exceptions (avoid infinite fast loop of retries on errors).
      • Handle more gracefully network mismatches (e.g. connecting Ogmios in testnet mode to a mainnet network)
      • Repository reorganization:
        • ‘ogmios-server’ renamed into ‘server’
        • move Haskell-specific dotfiles and configuration files under ‘server’
        • move ‘modules’ under ‘server’
        • move ‘Dockerfile’ and ‘snapshot.Dockerfile’ under ‘server’

      Removed

      • Support for GHC-8.6.5
      • The docker image no longer shows git revision / version on ‘–version’

      [3.0.0] – 2021-02-26

      Added

      • Support for the Allegra era on the chain-sync, tx submission and state query protocols.
      • Support for the Mary era on the chain-sync, tx submission and state query protocols.
      • Support for multi-era state queries, or said differently, Ogmios can survive a hard-fork without being restarted or re-compiled.
      • Allow clients to also make state queries based on the node’s tip (instead of passing an explicit point to acquire).
      • Interactive dashboard leveraging Ogmios health’s endpoint and local state query protocol to show metrics in real-time.
      • Automated smoke sanity tests executed on a running instance, running queries and chain-syncs across all eras.
      • Various internal optimization, in particular with rewards to the chain-sync protocol (~14.000 blocks/s in Byron, ~2500 block/s in Shelley and beyond).
      • Additional metrics for monitoring: current heap size, total messages, total unrouted messages and start time.
      • Configurable HTTP server timeout from the command-line, with sensible defaults.

      Changed

      • Improve error responses to invalid clients' requests (instead of generic error messages).
      • Fixed various typos and clumsy wording in the user manual.
      • Reworked internal architecture as a Three-Layer Haskell Cake.
      • Changed internal dependencies for base16 and base64 encoding for better performances.
      • Upgraded internal dependencies to the Cardano eco-system working with cardano-node@1.25.1
      • Improved error handling of the Ogmios server, in particular in case of connections lost with the underlying node.
      • The server now returns an explicit client error when interleaving ‘FindIntersect’ messages in-between pipelined ‘RequestNext’.
      • Revised default compilation flags .

      Removed

      N/A

      [2.0.0-beta] – 2020-10-31

      Added

      • Support for the Shelley chain in the local-chain-sync protocol.
      • Support for the local-state-query protocol.
      • Health / Heartbeat endpoint for monitoring.
      • Runtime and application metrics measured and served on endpoint (/health).
      • Ogmios now includes an HTTP static server hosting both the WSP definition and, a /benchmark.html to run some quick benchmark / smoke test.
      • Added additional configuration options via command-line or environment.
      • Revised user manual with detailed step-by-step examples.

      Changed

      • Several JSON fields renamed to increase consistency between Shelley and Byron.
      • Improved logging, more messages and with more context.
      • Improved error handling with regards to connection of websocket clients.

      Removed

      N/A

      Changed

      N/A

      [1.0.0-beta] – 2020-04-04

      Added

      • Initial release and support for:

        • Chain Synchronization (no pipelining between cardano-node & ogmios)
        • Local Transaction Submission

      • JSON-WSP version 1.0, full support with reflection.

      • Full docker stack via docker-compose.

      • Basic command-line and logging.

      Changed

      N/A

      Removed

      N/A

      \ No newline at end of file +to catch this kind of errors more easily.

      Removed

      ø

      [3.1.0] - 2021-04-04

      Added

      Changed

      Removed

      [3.0.0] – 2021-02-26

      Added

      Changed

      Removed

      N/A

      [2.0.0-beta] – 2020-10-31

      Added

      Changed

      Removed

      N/A

      Changed

      N/A

      [1.0.0-beta] – 2020-04-04

      Added

      Changed

      N/A

      Removed

      N/A

      \ No newline at end of file diff --git a/clients/index.html b/clients/index.html index ae3493ec9..cd9ba4ad1 100644 --- a/clients/index.html +++ b/clients/index.html @@ -1,4 +1,4 @@ -Clients - Ogmios

      Clients

      There exists a variety of clients for Ogmios. Initially, the TypeScript client was developed alongside the server as a proof-of-concept. Over time, amazing community members have developed new clients in their favorite languages:

      Logo:TypeScript
      TypeScript      		Logo:Go
      Go      		Logo:Kotlin
      Kotlin      		Logo:Java
      Java      		Logo:Python
      Python      		Logo:Elixir
      Elixir      		Logo:C++
      C++

      In this manual, we cover some usage of the TypeScript client. For other clients, please refer to their respective projects and maintainers.

      \ No newline at end of file diff --git a/faq/index.html b/faq/index.html index 8b34ae2fa..3e40badfa 100644 --- a/faq/index.html +++ b/faq/index.html @@ -1,4 +1,4 @@ -F.A.Q - Ogmios

      F.A.Q

      Can you explain Ogmios in one three sentences?

      Ogmios is a lightweight bridge interface for cardano-node. It offers a WebSockets API that enables local clients to speak Ouroboros' mini-protocols 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…)

      Can you explain Ogmios to me like I’m five?

      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* (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.

      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.

      (*) Since 2022, Pallas now provides most of the primitives also in Rust.

      Where does the name come from?

      Ogmios is a celtic deity of eloquence, 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.

      Why do I care?

      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 cardano-graphql, Rosetta, or Blockfrost.

      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.

      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.

      Can I build X using Ogmios?

      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.

      What’s the overhead from running Ogmios?

      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.

      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.

      Is there any client for Ogmios?

      As a matter of fact, there is. A TypeScript client library and REPL 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 TypeScript Client section.

      Since then, there has been other clients built by the community:

      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.

      Does Ogmios require the PAB (Plutus Application Backend) to work?

      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.

      Can I use Ogmios in a remote setup?

      Yes. The easiest way is probably by using a reverse-proxy like NGINX 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 local 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.

      Why do Ogmios returns JSON with integers larger than MAX_SAFE_INTEGER?

      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 architectural decision record which explains how we handle large integers in the TypeScript client.

      Is Ogmios production ready?

      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 continuous integration1.

      Tests for the server include property-based testing of the core protocols2 3, property-based testing of the entire JSON interface validated against a JSON-schema specification4. Note that property tests all use generators which comes directly from the ouroboros-network and cardano-ledger-specs to ensure that Ogmios is always up-to-date with the Cardano eco-system. There are also various5 unit6 tests7 to cover basic functionalities.

      On the other hand, the TypeScript client is used to perform end-to-end tests with tests running against the Cardano testnet8. The tests are executed both in a Node.js and browser context and the synchronization with the network is done via a Github action which leverages Ogmios' server.

      Beside, Ogmios also comes with structured logging and monitoring out of the box. Putting any monitoring solution on top like Prometheus is trivial.

      Finally, if you ventured through this page and user-guide, you have also noticed that the project is well-documented. And this includes the API reference, the ChangeLog as well as the architectural decisions going over rationales for decisions we made along the way.

      Thus, is Ogmios production-ready? Yes. 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 MPL-2.0 and you’re the best judge.

      Are there any projects/companies using it?

      We’ve heard of a handful happy users! And it keeps growing!

      (Known) projects/companies using Ogmios
      FiveBinariesSundae LabsInput Output GlobalJpg.storeNEWMMLabsMinswap
      EternlRayNetworkDCSparkSpacebudzCardano FoundationTxPipeKora Labs
      MaestroBlinklabsPool.pmBloxBeanWing RidersLiqwid LabsGimbalabs
      Genius YieldRosen BridgeEMURGOIndigo ProtocolVacuumLabsMutant NFTDex Hunter
      NescrowDanogoVeralidityMultichainTosiDropWayup
      (Known) open source projects using Ogmios
      • Blockfrost: An API service providing abstraction between you and Cardano blockchain data, taking away the burden of complexity, so you can focus on what really matters - developing your applications.
      • Cardano-transaction-lib: A Purescript library for building smart contract transactions on Cardano
      • Lucid: A library for creating Cardano transactions and off-chain code for Plutus contracts in JavaScript, Deno and Node.js.
      • Nebula: A Cardano NFT marketplace contract including chain indexer and event listener for individual projects.
      • Mesh: An open-source library to advance Web3 development on Cardano.
      • PyCardano: A lightweight Cardano SDK in Python.
      • Cardano-js-sdk: JavaScript SDK for interacting with Cardano, providing various key management options, with support for popular hardware wallets.
      • Cardano (Java) client lib: A client library for Cardano in Java. This library simplifies the interaction with Cardano blockchain from a Java application.
      • Yaci DevKit: A set of dev tools for development on Cardano.
      • Lace: A light-wallet for Cardano.
      • Marlowe (marlowe-runner): A smart-contract DSL for Cardano.
      • Naumachia: Naumachia is a framework for writing Smart Contracts on the Cardano Blockchain using Rust!
      • DenoSync: Deno WebSocket Chainsync client on top of Ogmios.
      • NodeRunner: Tooling for setting up stacks of Cardano services.
      • Translucent: A library for creating Cardano transactions and off-chain code for Plutus contracts in JavaScript.

      Are you using Ogmios for a project? Let us know on Github!

      \ No newline at end of file diff --git a/getting-started/basics/index.html b/getting-started/basics/index.html index 9cbd1d91e..75012191a 100644 --- a/getting-started/basics/index.html +++ b/getting-started/basics/index.html @@ -1,5 +1,5 @@ -Using: JSON-RPC basics - Ogmios