Derive hydra scripts tx-ids (#2019)

v0d1ch · web-flow · commit 7a0af4d52e32 · 2025-06-12T12:32:48.000+02:00
- Since we pre-publish hydra scrips upon each release provide the
`--network` option in order to complement `--hydra-scripts-tx-id` option
and have a nice shortcut.

- We always use the latest published version (user issue seem to imply
that by proposing _default_ argument).

- This new argument is Invoked as  `--network preview` for example.
---

&lt;!-- Consider each and tick it off one way or the other --&gt;
* [x] CHANGELOG updated or not needed
* [x] Documentation updated or not needed
* [x] Haddocks updated or not needed
* [x] No new TODOs introduced or explained herafter
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -48,6 +48,8 @@ changes.
 
 - Add API query (GET /head) to fetch the latest head state by a node and help introspecting the whole internal state.
 
+- Provide `--network` option to hydra-node in order to use pre-published hydra scripts.
+
 ## [0.21.0] - 2025-04-28
 
 - New metric for counting the number of active peers: `hydra_head_peers_connected`
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -156,7 +156,7 @@ To perform a release of the next `<version>`:
 1. Make sure all tests are passing.
 2. Publish Hydra scripts onto `preview`, `preprod`, and `mainnet` using the
    [smoke test][smoke-test] and put the transaction IDs as new `<version>`
-   entries into [networks.json](./networks.json).
+   entries into [networks.json](./hydra-node/networks.json).
 3. Update CHANGELOG.md by replacing `UNRELEASED` with a date in
    [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) and prepare contents.
 4. Run `./release.sh <version>`.
diff --git a/docs/docs/configuration.md b/docs/docs/configuration.md
@@ -52,7 +52,7 @@ Being a protocol parameter, all participants in a head must configure the same `
 
 :::
 
-The default contestation period is _600 seconds_, but it should be tailored to the network conditions, as different networks have varying block production rates. A good rule of thumb is the maximum time you would expect an attacker to launch a withholding attack onto the cardano network you are on. Also, consider the time it takes to propagate a transaction to the network and the time it takes for a block to be produced, and the contestation period should be long enough to accommodate any downtime of the `hydra-node`. 
+The default contestation period is _600 seconds_, but it should be tailored to the network conditions, as different networks have varying block production rates. A good rule of thumb is the maximum time you would expect an attacker to launch a withholding attack onto the cardano network you are on. Also, consider the time it takes to propagate a transaction to the network and the time it takes for a block to be produced, and the contestation period should be long enough to accommodate any downtime of the `hydra-node`.
 
 The contestation deadline decides when a closed head can be fanned out. At worst, this is `(1 + n) * CP` after submitting a `Close` transaction, where `n` is the number of participants in the head. This is because the deadline is pushed forward on each `Contest`. With no contestations which may still be `2 * CP` after `Close` depending on the upper validity set on che close transaction. The `hydra-node` currently picks a blanket 200 seconds as [max grace time](https://hydra.family/head-protocol/haddock/hydra-node/Hydra-Chain-Direct-Handlers.html#v:maxGraceTime).
 
@@ -83,13 +83,21 @@ See the [how-to](./how-to/incremental-commit) and [protocol documentation](./dev
 
 The `hydra-node` uses reference scripts to reduce transaction sizes driving the head's lifecycle. Specify the `--hydra-scripts-tx-id` to reference the correct scripts. The `hydra-node` will verify the availability of these scripts on-chain.
 
+:::important Alternative: use --network
+Since we pre-publish hydra scrips before each release, instead of specifying hydra-scripts using `--hydra-scripts-tx-id`, you can use `--network` together with the network name you would like to run your hydra-node on (e.g. `--network preview`).
+:::
+
+:::warning
+`--network` argument only works with officially released hydra-node versions!
+:::
+
 Check the scripts against which a hydra-node was compiled using:
 
 ```shell
 hydra-node --script-info
 ```
 
-For public [(test) networks](https://book.world.dev.cardano.org/environments.html), we publish Hydra scripts with each new release, listing transaction IDs in the [release notes](https://github.com/cardano-scaling/hydra/releases) and [`networks.json`](https://github.com/cardano-scaling/hydra/blob/master/networks.json).
+For public [(test) networks](https://book.world.dev.cardano.org/environments.html), we publish Hydra scripts with each new release, listing transaction IDs in the [release notes](https://github.com/cardano-scaling/hydra/releases) and [`networks.json`](https://github.com/cardano-scaling/hydra/blob/master/hydra-node/networks.json).
 
 To publish scripts yourself, use the `publish-scripts` command:
 
diff --git a/docs/docs/tutorial/index.md b/docs/docs/tutorial/index.md
@@ -421,7 +421,7 @@ hydra-node \
   --persistence-dir persistence-alice \
   --cardano-signing-key credentials/alice-node.sk \
   --hydra-signing-key credentials/alice-hydra.sk \
-  --hydra-scripts-tx-id $(curl https://raw.githubusercontent.com/cardano-scaling/hydra/master/networks.json | jq -r ".preprod.\"${hydra_version}\"") \
+  --hydra-scripts-tx-id $(curl https://raw.githubusercontent.com/cardano-scaling/hydra/master/hydra-node/networks.json | jq -r ".preprod.\"${hydra_version}\"") \
   --ledger-protocol-parameters protocol-parameters.json \
   --testnet-magic 1 \
   --node-socket node.socket \
@@ -443,7 +443,7 @@ hydra-node \
   --persistence-dir persistence-bob \
   --cardano-signing-key credentials/bob-node.sk \
   --hydra-signing-key credentials/bob-hydra.sk \
-  --hydra-scripts-tx-id $(curl https://raw.githubusercontent.com/cardano-scaling/hydra/master/networks.json | jq -r ".preprod.\"${hydra_version}\"") \
+  --hydra-scripts-tx-id $(curl https://raw.githubusercontent.com/cardano-scaling/hydra/master/hydra-node/networks.json | jq -r ".preprod.\"${hydra_version}\"") \
   --ledger-protocol-parameters protocol-parameters.json \
   --testnet-magic 1 \
   --node-socket node.socket \
diff --git a/hydra-chain-observer/src/Hydra/ChainObserver.hs b/hydra-chain-observer/src/Hydra/ChainObserver.hs
@@ -11,7 +11,7 @@ import Hydra.ChainObserver.NodeClient (ChainObservation, ChainObserverLog (..),
 import Hydra.ChainObserver.Options (Backend (..), Options (..), hydraChainObserverOptions)
 import Hydra.Contract qualified as Contract
 import Hydra.Logging (Verbosity (..), traceWith, withTracer)
-import Hydra.Options (hydraNodeVersion)
+import Hydra.NetworkVersions (hydraNodeVersion)
 import Hydra.Ouroborus.ChainObserver (ouroborusClient)
 import Network.HTTP.Simple (getResponseBody, httpNoBody, parseRequestThrow, setRequestBodyJSON)
 import Network.URI (URI)
diff --git a/hydra-chain-observer/src/Hydra/ChainObserver/Options.hs b/hydra-chain-observer/src/Hydra/ChainObserver/Options.hs
@@ -6,8 +6,8 @@ import Hydra.Prelude
 
 import Data.Version (showVersion)
 import Hydra.Cardano.Api (ChainPoint, NetworkId, SocketPath)
+import Hydra.NetworkVersions (hydraNodeVersion)
 import Hydra.Options (
-  hydraNodeVersion,
   networkIdParser,
   nodeSocketParser,
   startChainFromParser,
diff --git a/hydra-cluster/src/Hydra/Cluster/Faucet.hs b/hydra-cluster/src/Hydra/Cluster/Faucet.hs
@@ -134,8 +134,8 @@ seedFromFaucetBlockfrost receivingVerificationKey lovelace = do
       case eResult of
         Left err -> liftIO $ throwIO $ FaucetBlockfrostError{blockFrostError = show err}
         Right _ -> do
-          void $ Blockfrost.awaitUTxO networkId [changeAddress] (txId signedTx) 100
-          Blockfrost.awaitUTxO networkId [receivingAddress] (txId signedTx) 100
+          void $ Blockfrost.awaitUTxO networkId [changeAddress] (txId signedTx) 200
+          Blockfrost.awaitUTxO networkId [receivingAddress] (txId signedTx) 200
  where
   findUTxO networkId address lovelace' = do
     faucetUTxO <- Blockfrost.queryUTxO networkId [address]
diff --git a/hydra-node/hydra-node.cabal b/hydra-node/hydra-node.cabal
@@ -1,10 +1,10 @@
-cabal-version: 3.0
-name:          hydra-node
-version:       0.22.0
-synopsis:      The Hydra node
-author:        IOG
-copyright:     2022 IOG
-license:       Apache-2.0
+cabal-version:      3.0
+name:               hydra-node
+version:            0.22.0
+synopsis:           The Hydra node
+author:             IOG
+copyright:          2022 IOG
+license:            Apache-2.0
 license-files:
   LICENSE
   NOTICE
@@ -13,6 +13,8 @@ data-files:
   json-schemas/api.yaml
   json-schemas/common.yaml
 
+extra-source-files: networks.json
+
 source-repository head
   type:     git
   location: https://github.com/cardano-scaling/hydra
@@ -86,6 +88,7 @@ library
     Hydra.Network.Authenticate
     Hydra.Network.Etcd
     Hydra.Network.Message
+    Hydra.NetworkVersions
     Hydra.Node
     Hydra.Node.DepositPeriod
     Hydra.Node.EmbedTH
@@ -324,6 +327,7 @@ test-suite tests
     Hydra.ModelSpec
     Hydra.Network.AuthenticateSpec
     Hydra.NetworkSpec
+    Hydra.NetworkVersionsSpec
     Hydra.Node.InputQueueSpec
     Hydra.Node.RunSpec
     Hydra.NodeSpec
diff --git a/hydra-node/networks.json b/hydra-node/networks.json
diff --git a/hydra-node/src/Hydra/API/WSServer.hs b/hydra-node/src/Hydra/API/WSServer.hs
@@ -43,7 +43,7 @@ import Hydra.Chain.Direct.State ()
 import Hydra.HeadLogic (ClosedState (ClosedState, readyToFanoutSent), HeadState, StateChanged)
 import Hydra.HeadLogic.State qualified as HeadState
 import Hydra.Logging (Tracer, traceWith)
-import Hydra.Options qualified as Options
+import Hydra.NetworkVersions qualified as NetworkVersions
 import Hydra.Tx (Party)
 import Hydra.Tx.HeadId (HeadId (..))
 import Network.WebSockets (
@@ -104,7 +104,7 @@ wsApp party tracer history callback headStateP headIdP responseChannel ServerOut
             , headStatus = getHeadStatus headState
             , hydraHeadId
             , snapshotUtxo = getSnapshotUtxo headState
-            , hydraNodeVersion = showVersion Options.hydraNodeVersion
+            , hydraNodeVersion = showVersion NetworkVersions.hydraNodeVersion
             }
 
   Projection{getLatest} = headStateP
diff --git a/hydra-node/src/Hydra/NetworkVersions.hs b/hydra-node/src/Hydra/NetworkVersions.hs
@@ -0,0 +1,48 @@
+{-# LANGUAGE TemplateHaskell #-}
+
+module Hydra.NetworkVersions where
+
+import Hydra.Prelude hiding (encodeUtf8)
+
+import Control.Lens ((^.), (^?))
+import Data.Aeson (Value (..), encode)
+import Data.Aeson.Lens (key, nonNull, _Key)
+import Data.FileEmbed (embedFile, makeRelativeToProject)
+import Data.Text (splitOn)
+import Data.Text.Encoding (encodeUtf8)
+import Data.Version (Version (..), showVersion)
+import Hydra.Cardano.Api (TxId, deserialiseFromRawBytesHex)
+import Hydra.Version (embeddedRevision, gitRevision, unknownVersion)
+import Paths_hydra_node (version)
+
+hydraNodeVersion :: Version
+hydraNodeVersion =
+  version & \(Version semver _) -> Version semver revision
+ where
+  revision =
+    maybeToList $
+      embeddedRevision
+        <|> gitRevision
+        <|> Just unknownVersion
+
+networkVersions :: ByteString
+networkVersions = $(makeRelativeToProject "./networks.json" >>= embedFile)
+
+parseNetworkTxIds :: MonadFail m => Version -> String -> m [TxId]
+parseNetworkTxIds hydraVersion network = do
+  case networkVersions ^? key (network ^. _Key) of
+    Nothing -> fail $ "Unknown network: " <> toString network
+    Just t -> getLastTxId t
+ where
+  getLastTxId t = do
+    case splitOn "-" $ fromString $ showVersion hydraVersion of
+      [] -> fail "Failed to parse hydra-node revision."
+      (rev : _) -> do
+        case encode t ^? key (rev ^. _Key) . nonNull of
+          Just (String s) -> mapM parseToTxId $ splitOn "," s
+          _ -> fail "Failed to find released hydra-node version in networks.json."
+
+  parseToTxId textTxId = do
+    case deserialiseFromRawBytesHex $ encodeUtf8 textTxId of
+      Left _ -> fail $ "Failed to parse string to TxId: " <> toString textTxId
+      Right txid -> pure txid
diff --git a/hydra-node/src/Hydra/Options.hs b/hydra-node/src/Hydra/Options.hs
@@ -19,7 +19,7 @@ import Data.ByteString.Char8 qualified as BSC
 import Data.IP (IP (IPv4), toIPv4, toIPv4w)
 import Data.Text (unpack)
 import Data.Text qualified as T
-import Data.Version (Version (..), showVersion)
+import Data.Version (showVersion)
 import Hydra.Cardano.Api (
   ChainPoint (..),
   File (..),
@@ -38,10 +38,10 @@ import Hydra.Contract qualified as Contract
 import Hydra.Ledger.Cardano ()
 import Hydra.Logging (Verbosity (..))
 import Hydra.Network (Host (..), NodeId (NodeId), PortNumber, WhichEtcd (..), readHost, readPort, showHost)
+import Hydra.NetworkVersions (hydraNodeVersion, parseNetworkTxIds)
 import Hydra.Node.DepositPeriod (DepositPeriod (..))
 import Hydra.Tx.ContestationPeriod (ContestationPeriod, fromNominalDiffTime)
 import Hydra.Tx.HeadId (HeadSeed)
-import Hydra.Version (embeddedRevision, gitRevision, unknownVersion)
 import Options.Applicative (
   Parser,
   ParserInfo,
@@ -78,7 +78,6 @@ import Options.Applicative (
  )
 import Options.Applicative.Builder (str)
 import Options.Applicative.Help (vsep)
-import Paths_hydra_node (version)
 import Test.QuickCheck (elements, listOf, listOf1, oneof, vectorOf)
 
 data Command
@@ -521,7 +520,7 @@ ledgerGenesisFileParser =
 cardanoChainConfigParser :: Parser CardanoChainConfig
 cardanoChainConfigParser =
   CardanoChainConfig
-    <$> (hydraScriptsTxIdsParser <|> many hydraScriptsTxIdParser)
+    <$> ((hydraScriptsTxIdsParser <|> many hydraScriptsTxIdParser) <|> hydraScriptsDefaultParser)
     <*> cardanoSigningKeyFileParser
     <*> many cardanoVerificationKeyFileParser
     <*> optional startChainFromParser
@@ -802,6 +801,22 @@ hydraScriptsTxIdParser =
           \can use the 'publish-scripts' sub-command to publish them yourself."
     )
 
+hydraScriptsDefaultParser :: Parser [TxId]
+hydraScriptsDefaultParser =
+  option
+    (eitherReader validateNetwork)
+    ( long "network"
+        <> metavar "NETWORK"
+        <> help "Uses the last pre-published hydra scripts for the given network."
+    )
+ where
+  validateNetwork arg =
+    case arg of
+      "preview" -> parseNetworkTxIds hydraNodeVersion arg
+      "preprod" -> parseNetworkTxIds hydraNodeVersion arg
+      "mainnet" -> parseNetworkTxIds hydraNodeVersion arg
+      _ -> Left $ "Unknown network: " <> arg
+
 persistenceDirParser :: Parser FilePath
 persistenceDirParser =
   option
@@ -847,16 +862,6 @@ hydraNodeCommand =
       (decodeUtf8 $ encodePretty Contract.scriptInfo)
       (long "script-info" <> help "Dump script info as JSON")
 
-hydraNodeVersion :: Version
-hydraNodeVersion =
-  version & \(Version semver _) -> Version semver revision
- where
-  revision =
-    maybeToList $
-      embeddedRevision
-        <|> gitRevision
-        <|> Just unknownVersion
-
 defaultContestationPeriod :: ContestationPeriod
 defaultContestationPeriod = 600
 
diff --git a/hydra-node/test/Hydra/API/ServerSpec.hs b/hydra-node/test/Hydra/API/ServerSpec.hs
@@ -43,7 +43,7 @@ import Hydra.HeadLogic.StateEvent (StateEvent (..), genStateEvent)
 import Hydra.Ledger.Simple (SimpleTx (..))
 import Hydra.Logging (Tracer, showLogsOnFailure)
 import Hydra.Network (PortNumber)
-import Hydra.Options qualified as Options
+import Hydra.NetworkVersions qualified as NetworkVersions
 import Hydra.Tx.Party (Party)
 import Hydra.Tx.Snapshot (Snapshot (Snapshot, utxo, utxoToCommit))
 import Network.Simple.WSS qualified as WSS
@@ -88,7 +88,7 @@ spec =
                 version <- waitMatch 5 conn $ \v -> do
                   guard $ matchGreetings v
                   v ^? key "hydraNodeVersion"
-                version `shouldBe` toJSON (showVersion Options.hydraNodeVersion)
+                version `shouldBe` toJSON (showVersion NetworkVersions.hydraNodeVersion)
 
     it "sends server outputs to all connected clients" $ do
       queue <- atomically newTQueue
diff --git a/hydra-node/test/Hydra/NetworkVersionsSpec.hs b/hydra-node/test/Hydra/NetworkVersionsSpec.hs
@@ -0,0 +1,36 @@
+module Hydra.NetworkVersionsSpec where
+
+import Hydra.Prelude
+import Test.Hydra.Prelude
+
+import Data.Version (Version, makeVersion)
+import Hydra.NetworkVersions (hydraNodeVersion, parseNetworkTxIds)
+import Test.QuickCheck (Property, counterexample, forAll, property)
+
+spec :: Spec
+spec =
+  describe "NetworkVersions" $ do
+    it "parseNetworkTxIds produces list TxId" $ do
+      let networks = ["mainnet", "preview", "preprod"]
+      let versions = makeVersion . (\v -> [0, v, 0]) <$> [13 .. 21]
+      forM_ networks $ \network ->
+        forM_ versions $ \version -> do
+          case parseNetworkTxIds version network of
+            Left err -> failure $ "Failed to parse network tx ids: " <> err
+            Right txIds -> txIds `shouldSatisfy` not . null
+
+    prop "parseNetworkTxIds works with expected versions and networks" $
+      forAll arbitrary $ \version ->
+        forAll arbitrary $ \network ->
+          propParseNetworkTxIds version network
+
+propParseNetworkTxIds :: Version -> String -> Property
+propParseNetworkTxIds version network = do
+  let varlidNetworks = ["mainnet", "preview", "preprod"]
+  let validVersions = (makeVersion . (\v -> [0, v, 0]) <$> [13 .. 21]) <> [hydraNodeVersion]
+  case parseNetworkTxIds version network of
+    Left err ->
+      if network `elem` varlidNetworks && version `elem` validVersions
+        then property False & counterexample ("error: " <> err)
+        else property True
+    Right txIds -> property $ not (null txIds)
diff --git a/release.sh b/release.sh
@@ -145,7 +145,7 @@ check_networks_is_up_to_date() {
     preview
   )
 
-  local networks_file=networks.json
+  local networks_file=hydra-node/networks.json
 
   for network in "${networks[@]}"; do
     cat ${networks_file} | jq -e ".\"${network}\".\"${version}\"" >/dev/null ||
