This will help later when versioning docs, because different versions will have different base url.
# API Behavior
This page documents the behavior of a `hydra-node` at the API layer. That is, how the system behaves given [ClientInputs](https://hydra.family/head-protocol/haddock/hydra-node/Hydra-API-ClientInput.html#t:ClientInput) and what [ServerOutputs](https://hydra.family/head-protocol/haddock/hydra-node/Hydra-API-ServerOutput.html#t:ServerOutput) are produced in response to it. See also the [API reference](https://hydra.family/head-protocol/api-reference/) for more details about individual API messages.
This page documents the behavior of a `hydra-node` at the API layer. That is, how the system behaves given [ClientInputs](/haddock/hydra-node/Hydra-API-ClientInput.html#t:ClientInput) and what [ServerOutputs](/haddock/hydra-node/Hydra-API-ServerOutput.html#t:ServerOutput) are produced in response to it. See also the [API reference](/api-reference/) for more details about individual API messages.
The formalism uses [UML statechart](https://en.wikipedia.org/wiki/UML_state_machine) language where transitions are labeled: `input [condition] / output`. When two outputs (e.g. `A` and `B`) are expected we write `A,B`, while `{A,B}` denotes mutual exclusiveness of outputs.
Instead, transactions will need to be constructed and submitted to the Hydra Node in CBOR format. The interface to speak to a Hydra Node is a websocket, and developers must build applications that connect to these websockets in order to send and receive events through them.
The Hydra node will emit several commands through this websocket: the API is defined [here](https://hydra.family/head-protocol/api-reference).
The Hydra node will emit several commands through this websocket: the API is defined [here](/api-reference).
The API reference is divided into two sections: Pub and Sub.
The first one describes the commands that a hydra node will accept, while the second one describes the events that will be emitted through the websocket.
Remember the nodes will always produce output in JSON format, so all the assertions will expect some form of `Aeson.Value` to check against. For example, after we submit a transaction to the node, we can use `waitMatch` to parse the `SnaphotConfirmed` event and extract the transactions present in that snapshot to check if it contains the transaction we just sent.
For more details about the `hydra-cluster` functions (i.e. `waitFor` and `waitMatch`), visit the [haddock](https://hydra.family/head-protocol/haddock/hydra-cluster/HydraNode.html)
For more details about the `hydra-cluster` functions (i.e. `waitFor` and `waitMatch`), visit the [haddock](/haddock/hydra-cluster/HydraNode.html)
+ If you run into this, file an issue and the Hydra team will be able to help
you finalize your head in a manual workaround.
- Not an issue, but a workaround: The internal wallet of `hydra-node` requires a UTXO to be marked as "fuel" to drive the Hydra protocol transactions. See [user manual](https://hydra.family/head-protocol/docs/getting-started/demo/with-docker/#seeding-the-network).
- Not an issue, but a workaround: The internal wallet of `hydra-node` requires a UTXO to be marked as "fuel" to drive the Hydra protocol transactions. See [user manual](/docs/getting-started/demo/with-docker/#seeding-the-network).
### hydra-tui
Now that we are connected, we can use this API to communicate with each Hydra head. For a detailed API reference, see the [documentation](https://hydra.family/head-protocol/api-reference).
Now that we are connected, we can use this API to communicate with each Hydra head. For a detailed API reference, see the [documentation](/api-reference).
To open a head, one of the two parties first has to initialize the state channel. This can be done via the following API call
* a validation that the Hydra plutus scripts validators do check the transaction constraints defined in the Hydra Head specification;
* a review and comment on the mutation-based tests applied to the Hydra plutus scripts and, in particular, any adversarial situation that would not be covered by them but should be.
See the documentation of our [Mutation-Based tests](https://hydra.family/head-protocol/haddock/hydra-node/tests/Hydra-Chain-Direct-Contract-Mutation.html).
See the documentation of our [Mutation-Based tests](/haddock/hydra-node/tests/Hydra-Chain-Direct-Contract-Mutation.html).
See [Common Weaknesses](https://plutus.readthedocs.io/en/latest/reference/writing-scripts/common-weaknesses/index.html) and [Vulnerabilities](https://github.com/Plutonomicon/plutonomicon/blob/main/vulnerabilities.md).
/>
</p>
Client nodes want to be able to interact with each other efficiently, at a low cost, using standard Cardano (L1) transactions. They are willing to trust *at least one* _Operator_ to run a full Hydra and Cardano node on their behalf, in effect trading some trust for efficiency. They interact with other _clients_ in a single head using the Hydra [API](https://hydra.family/head-protocol/api-reference) and retain ownership of signing keys for transactions submitted to the Head.
Client nodes want to be able to interact with each other efficiently, at a low cost, using standard Cardano (L1) transactions. They are willing to trust *at least one* _Operator_ to run a full Hydra and Cardano node on their behalf, in effect trading some trust for efficiency. They interact with other _clients_ in a single head using the Hydra [API](/api-reference) and retain ownership of signing keys for transactions submitted to the Head.
Client nodes, may come and go offline without hampering progress of the Hydra Head. The safety of their funds rely on having at least one honest _Operator_ node with whom they can interact but importantly, they do not relinquish keys for spending funds inside the Head.
# Topologies
Hydra Head is a well-defined Layer 2 consensus protocol as explained in the [Core Concepts](/core-concepts) page, but this is not the end of the story and does not really define _how to use_ this protocol and what _topologies_ are possible. While [example use cases](../use-cases) should help in understanding the former, the _topologies_ below explain some of the various ways in which Hydra Nodes and Hydra Heads could be deployed and interconnected.
Hydra Head is a well-defined Layer 2 consensus protocol as explained in the [Core Concepts](/core-concepts) page, but this is not the end of the story and does not really define _how to use_ this protocol and what _topologies_ are possible. While [example use cases](/use-cases) should help in understanding the former, the _topologies_ below explain some of the various ways in which Hydra Nodes and Hydra Heads could be deployed and interconnected.
As more users implement solutions on top of Hydra, this "catalog" of topologies shall expand to help newcomers find and build the deployment model that suits best their use case.
Includes direct 1:1 wrappers for misc builders (#197) and tx_builder (#210)
Wrappers around custom-written code written earlier for the rust crate.
Previous work on the builders/etc updates rust but introduced things caused the WASM to no longer compile. This updates the WASM bindings as well. Includes genesis module that wasn't pushed before.
