{"id":24551922,"url":"https://github.com/mlabs-haskell/purescript-hydra-sdk","last_synced_at":"2025-07-12T08:05:32.435Z","repository":{"id":257850260,"uuid":"869461614","full_name":"mlabs-haskell/purescript-hydra-sdk","owner":"mlabs-haskell","description":null,"archived":false,"fork":false,"pushed_at":"2025-01-23T17:20:27.000Z","size":341,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-09T11:57:59.799Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlabs-haskell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-08T10:37:20.000Z","updated_at":"2025-01-17T18:15:13.000Z","dependencies_parsed_at":"2024-11-29T16:21:41.645Z","dependency_job_id":"85802403-edcd-4552-a65e-c101c221397a","html_url":"https://github.com/mlabs-haskell/purescript-hydra-sdk","commit_stats":null,"previous_names":["mlabs-haskell/purescript-hydra-sdk"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fpurescript-hydra-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fpurescript-hydra-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fpurescript-hydra-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlabs-haskell%2Fpurescript-hydra-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlabs-haskell","download_url":"https://codeload.github.com/mlabs-haskell/purescript-hydra-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243878408,"owners_count":20362431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-23T01:19:27.480Z","updated_at":"2025-03-16T13:41:30.362Z","avatar_url":"https://github.com/mlabs-haskell.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"# purescript-hydra-sdk\n\n[Cardano Hydra](https://hydra.family/head-protocol/)\nSDK (Software Development Kit) for PureScript. This library offers\nvarious interfaces to facilitate the rapid development\nof Hydra-based applications.\n\n**Table of Contents**\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Compatibility](#compatibility)\n- [Preliminaries](#preliminaries)\n- [Development Workflows](#development-workflows)\n- [Getting Started with Example](#getting-started-with-example)\n- [SDK Core Functionality](#sdk-core-functionality)\n- [SDK Additionals: AppManager](#sdk-additionals-appmanager)\n- [Applications](#applications)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Compatibility\n\n| hydra-sdk   | hydra-node   | cardano-node |\n| ----------- | ------------ | ------------ |\n| **`0.1.0`** | **`0.19.0`** | **`10.1.2`** |\n\n\n## Preliminaries\n\nSince using this SDK implies a certain degree of understanding of the Hydra\nprotocol, it is advisable to get familiar with the [\"Hydra: Fast Isomorphic State Channels\" paper](https://iohk.io/en/research/library/papers/hydra-fast-isomorphic-state-channels/)\nand the [Hydra Head protocol documentation](https://hydra.family/head-protocol/docs/)\nbefore proceeding with the **Getting Started** guide below.\n\n## Development Workflows\n\nBefore executing most of the commands listed below, first enter the Nix\ndevelopment shell by running `nix develop`.\n\n* **Build docs and open them in the browser**: `make docs`\n* **Build the project**: `make build`\n* **Format code**: `make format`\n\n## Getting Started with Example\n\nThe simplest way to get a sense of how this SDK can help build Hydra-based\napplications is to run our minimal example and then adapt or extend it to suit\nyour specific requirements.\n\nGo to `example/minimal` and follow the step-by-step guide below to spin up\na cluster of two nodes, with each node running the minimal example logic.\n\n1. Enter the Nix development environment by running `nix develop` from the root\ndirectory of this repository. This will put you in the shell with all the\nnecessary executables required to continue with the setup procedure.\n\n2. In [example/minimal/docker/cluster/](example/minimal/docker/cluster/) you\ncan find configuration files for both nodes. The only field that needs to be\nupdated here is the `blockfrostApiKey`, which should be set to a valid\nBlockfrost API key **for preprod**.\nVisit the [Blockfrost website](https://blockfrost.io/) to generate a fresh API key.\n\n3. Execute `make gen-keys` to generate the necessary Cardano and Hydra keys\nrequired by the underlying Hydra nodes. Cardano keys are used to authenticate\non-chain transactions, while the Hydra keys are used for multi-signing snapshots\nwithin a Hydra Head. This command will output two Cardano preprod addresses\nthat must be pre-funded with sufficient tADA to run properly functioning Hydra\nnodes.\nUse the [Testnets faucet](https://docs.cardano.org/cardano-testnets/tools/faucet/)\nto request tADA.\n\n4. Finally, execute `make run-example` to launch a Hydra Head\nwith two participants both running the minimal example logic.\n\nNOTE: Hydra nodes require a fully synchronized Cardano node to operate\ncorrectly. No additional setup actions need to be performed to\nconfigure the Cardano node as it is already included in the Docker\nCompose configuration.\nHowever, node synchronization may take several hours on the first run.\nKeep in mind that Hydra nodes are configured to run only once\nthe Cardano node is fully synchronized,\nand the `cardano-node` output is suppressed to not\ninterfere with useful Hydra Head logs.\nAs a result, there will be no output during synchronization.\nInstead, use `docker logs` or run `cardano-cli query tip`\nfrom within the `cardano-node` Docker container\nto track the synchronization progress.\n\n## SDK Core Functionality\n\nThe SDK exposes the following top-level modules which constitus it API which\nis considered to be relatvely stable. You also can use `Internal` modules\nat yor own risk.\n\n* `HydraSdk.Process` module provides an interface for spinning up a hydra-node\nas a Node.js subprocess.\n\n* `HydraSdk.NodeApi` module exports functions for connecting to the Hydra Node\nWebSocket API and sending HTTP requests. The primary function provided by this\nmodule is `mkHydraNodeApiWebSocket`, which establishes a WebSocket connection to\nthe hydra-node, attaches specified handlers for incoming messages, and returns a\n`HydraNodeApiWebSocket` record with type-safe actions for interacting with the\nHydra Node API. It also allows to specify retry strategies for Hydra\ntransactions that may be silently dropped by cardano-node, particularly for\nClose and Contest transactions.\n\n* `HydraSdk.Types` module re-exports various Hydra domain-specific types\n(such as `HydraHeadStatus` and `HydraNodeApi_InMessage`), along with other\nutility types (e.g., `HostPort` and `Network`) used by the components of this\nlibrary.\n\n* Lastly, `HydraSdk.Lib` module contains useful helpers like codecs for many types,\nlogging action and some others.\n\n## SDK Additionals: AppManager\n\nUnder `Extra` folder, modules with additional functionality are located,\ncurrently being the only one for managing multiple app instances.\n\nOriginally the SDK was designed for Hydra applications, where Hydra Heads were\noperated by designated delegates. In that model a delegate can be anyone who wants\nto participate as a provider of computational resources to host Hydra\nnodes. Delegates must form a group upfront to maintain Hydra\nconsensus. Upon forming a group, all members need to specify\ninformation about their peers - such as Hydra node addresses, public\nkeys, etc. That way there exists a strict correspondence between\ndelegate configurations to start a functioning Hydra Head.\n\nEach application instance should monitor its underlying Hydra node and\nhave access to information about other Hydra Head participants.\nAppManager is an opinionated interface for managing multiple app\ninstances within a delegate group. This interface is utilized by\napplications like `hydra-auction-offchain`, enabling delegates to host\nmultiple Layer-2 auctions simultaneously.\n\nAt the core of AppManager is the concept of slots. When delegates\ndecide to form a group, they agree on the configurations for their\nfuture Hydra nodes. Since each delegate have to specify information\nabout their peers (hydra-node address, public keys, etc.), there must\nbe strict correspondence between delegate configurations to start\na working Hydra Head. This is where slots come into play. Each slot\nrepresents a set of delegate configurations sufficient to spin up a\nproperly configured Hydra Head. In hydra-auction-offchain, slot\nnumbers are implicitly derived from the configurations provided to\nthe delegate-server, with the first configuration corresponding to\nslot 0, the second to slot 1, and so forth. Users are expected to\nreserve slots before making an initial Layer-1 commitment, such as\nannouncing an auction. Upon reservation, they receive secrets from\neach delegate, which can later be provided to host a Layer-2\napplication in the reserved slot.\n\nOne clear drawback of this approach is the potential for malicious\nactors to reserve all available slots within a delegate group,\neffectively paralyzing its operations. In real-world applications, a\nflooding detection mechanism should be implemented to prevent this\nscenario, although there seems to be no obvious incentive for anyone\nto carry out such an attack.\n\nComing with the limitations mentioned, this approach simplifies things\nsince it neither requires communication and synchronization between\ndelegates during runtime nor does it rely on a central server to\norchestrate the initialization of Hydra Heads, making it a great fit\nfor hydra-auction-offchain and hopefully other Hydra applications.\n\n## Applications\n\nPlease refer to [hydra-auction-offchain](https://github.com/mlabs-haskell/hydra-auction-offchain)\nfor a full-fledged example that utilizes this SDK.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlabs-haskell%2Fpurescript-hydra-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlabs-haskell%2Fpurescript-hydra-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlabs-haskell%2Fpurescript-hydra-sdk/lists"}