Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introduce ADR 15 for Admin API #237

Closed
wants to merge 3 commits into from
Closed
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions docs/adr/0015-admin-api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# 15. Configure Node through an Admin API

Date: 2022-03-04

## Status

:hammer_and_wrench:

## Context

* Hydra-node currently requires a whole slew of command-line arguments to configure properly its networking layer: `--peer` to connect to each peer, `--cardano-verification-key` and `--hydra-verification-key` to identify the peer on the L1 and L2 respectively.
* This poses significant challenges for operating a _cluster_ of Hydra nodes as one needs to know beforehand everything about the cluster, then pass a large number of arguments to some program or docker-compose file, before any node can be started
* This is a pain that's been felt first-hand for benchmarking and testing purpose
* Having static network configuration is probably not sustainable in the long run, even if we don't add any fancy multihead capabilities to the node, as it would make it significantly harder to have automated creation of Heads.
* There's been an [attempt](https://github.com/input-output-hk/hydra-poc/pull/222) at providing a file-based network configuration but this was deemed unconvincing
* [Hydra paper (sec. 4, p. 13)](https://eprint.iacr.org/2020/299.pdf) explicitly assumes the existence of a _setup_ phase

## Decision

* Hydra-node exposes an _Administrative API_ to enable configuration of the Hydra network using "standard" tools
* API is exposed as a set of HTTP endpoints on some port, consuming and producing JSON data
This conversation was marked as resolved.
Show resolved Hide resolved
* It is documented as part of the User's Guide for Hydra Head
* This API provides _commands_ and _queries_ to:
* Add/remove _peers_ providing their address and keys,
* List currently known peers and their connectivity status,
* Start/stop/reset the Hydra network

## Consequences

* The API must be secured/authorised possibly using standard HTTP mechanisms
This conversation was marked as resolved.
Show resolved Hide resolved
* It's easy to deploy Hydra nodes with some standard configuration, then dynamically configure them
This conversation was marked as resolved.
Show resolved Hide resolved
* It makes it possible to _reconfigure_ a Hydra node with different peers
* The _Client API_ should reflect the state of the network and disable `Init`ing a head if the network layer is not started
* Operational tools could be built easily on top of the API, for command-line or Web-based configuration
1 change: 1 addition & 0 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,4 @@ Here is a list of currently accepted or discussed **Architecture Decision Record
12. [Top-down test-driven design](./0012-testing-strategy.md)
13. [Adversarial Mutation-based Contract Testing](./0013-contract-testing-strategy.md)
14. [Token usage in Hydra scripts](./0014-hydra-script-tokens.md)
15. _[Provide Admin API for Node](./0015-admin-api.md)_