Merge pull request #56 from MeshJS/hydra-docs-update-new

update hydra-docs

Author: Temasar1

apps/docs/content/docs/hydra/instance.mdx

@@ -14,11 +14,11 @@ The `HydraInstance` is intialized together with `HydraProvider`, for accessing o
 ```tsx
 import { HydraInstance, HydraProvider } from "@meshsdk/hydra";
 
-const hydraProvider = new HydraProvider({
+const provider = new HydraProvider({
   httpUrl: "<hydra-API-URL>",
 });
 
-const hydraInstance = new HydraInstance({
+const instance = new HydraInstance({
   provider: hydraProvider,
   fetcher: "<blockchainProvider>",
   submitter: "<blockchainProvider>",
@@ -31,7 +31,7 @@ If you don't want to commit any funds and only want to receive on layer 2, you c
 to open the head
 
 ```tsx
-const commit = await hydraInstance.commitEmpty();
+const commit = await instance.commitEmpty();
 const submitTx = await wallet.submitTx(commit);
 console.log("submitTx", submitTx);
 ```
@@ -47,15 +47,15 @@ Commits funds to the Hydra head by selecting specific UTxOs to make available on
 **Returns:** The transaction CBOR hex ready to be partially signed
 
 ```tsx
-await commitFunds(txHash: string, outputIndex: number)
+await instance.commitFunds(txHash: string, outputIndex: number)
 ```
 
 ```tsx
 const txHash =
   "00000000000000000000000000000000000000000000000000000000000000000";
 const outputIndex = 0;
 
-const commitTx = await hydraInstance.commitFunds(txHash, outputIndex);
+const commitTx = await instance.commitFunds(txHash, outputIndex);
 const signedTx = await wallet.signTx(commitTx, true);
 const commitTxHash = await wallet.submitTx(signedTx);
 ```
@@ -72,15 +72,15 @@ This is useful for advanced use cases such as commiting `scriptUTxOs`.
 - `hydraTransaction`
 
 ```tsx
-await hydraInstance.commitBlueprint("txHash", outputIndex, {
+await instance.commitBlueprint("txHash", outputIndex, {
   cborHex: "<unsignedTx>",
   description: "commit tx",
   type: "Tx ConwayEra",
 });
 ```
 
 ```tsx
-const commitTx = await hydraInstance.commitBlueprint(txHash, outputIndex, {
+const commitTx = await instance.commitBlueprint(txHash, outputIndex, {
   cborHex: "<unsignedTx>",
   description: "commit tx",
   type: "Tx ConwayEra",
@@ -97,20 +97,19 @@ The time it takes for it top be added after commit depends on the `hydra-node` c
 To read more on incremental commit, see [the Hydra documentation](https://hydra.family/head-protocol/docs/how-to/incremental-commit).
 
 ### incrementalCommitFunds
+
 ```tsx
-await incrementalCommitFunds(txHash: string, outputIndex: number)
+await instance.incrementalCommitFunds(txHash: string, outputIndex: number)
 ```
+
 ### incrementalBlueprintCommit
+
 ```tsx
-await incrementalBlueprintCommit(
-  txHash,
-  outputIndex,
-   {
-    cborHex: "unsignedTx",
-    description: "commit tx",
-    type: "Tx ConwayEra",
-  }
-)
+await instance.incrementalBlueprintCommit(txHash, outputIndex, {
+  cborHex: "unsignedTx",
+  description: "commit tx",
+  type: "Tx ConwayEra",
+});
 ```
 
 ## Basic Workflow
@@ -125,45 +124,65 @@ const provider = new HydraProvider({
   httpUrl: "http://localhost:4001",
 });
 
-const hydraInstance = new HydraInstance({
+const instance = new HydraInstance({
   provider: provider,
   fetcher: "blockchainProvider",
   submitter: "blockchainProvider",
 });
 
 await provider.connect();
-
 await provider.init();
 
-const commitTx = await hydraInstance.commitFunds(txHash, outputIndex);
-const signedTx = await wallet.signTx(commitTx, true);
-await wallet.submitTx(signedTx);
+provider.onMessage((message) => {
+  const status =
+    message.tag === "Greetings"
+      ? { headStatus: message.headStatus }
+      : { tag: message.tag };
+  if (
+    status.tag === "HeadIsInitializing" ||
+    status.headStatus === "Initializing"
+  ) {
+  }
+  const commitTx = await instance.commitFunds(txHash, outputIndex);
+  const signedTx = await wallet.signTx(commitTx, true);
+  await wallet.submitTx(signedTx);
+});
 ```
 
 ### Blueprint Commit
 
 ```tsx
-const txBuilder = new MeshTxBuilder({
-  submitter: "blockchainProvider",
-  fetcher: "blockchainProvider",
-  verbose: true,
-});
-
-const unsignedTx = await txBuilder
-  .txIn(txHash, outputIndex)
-  .txOut(address, [{ unit: "lovelace", quantity: amount }])
-  .setFee("0")
-  .changeAddress(address)
-  .selectUtxosFrom(UTxOs)
-  .complete();
-
-const commitTx = await instance.commitBlueprint(txHash, outputIndex, {
-  type: "Tx ConwayEra",
-  cborHex: unsignedTx,
-  description: "Commit Blueprint",
+provider.onMessage((message) => {
+  const status =
+    message.tag === "Greetings"
+      ? { headStatus: message.headStatus }
+      : { tag: message.tag };
+  if (
+    status.tag === "HeadIsInitializing" ||
+    status.headStatus === "Initializing"
+  ) {
+    const txBuilder = new MeshTxBuilder({
+      submitter: "<blockchainProvider>",
+      fetcher: "<blockchainProvider>",
+      verbose: true,
+    });
+
+    const unsignedTx = await txBuilder
+      .txIn(txHash, outputIndex)
+      .setFee("0")
+      .changeAddress(address)
+      .selectUtxosFrom(UTxOs)
+      .complete();
+
+    const commitTx = await instance.commitBlueprint(txHash, outputIndex, {
+      type: "Tx ConwayEra",
+      cborHex: unsignedTx,
+      description: "Commit Blueprint",
+    });
+
+    const signedTx = await wallet.signTx(commitTx);
+    const commitTxHash = await wallet.submitTx(signedTx);
+    console.log(commitTxHash);
+  }
 });
-
-const signedTx = await wallet.signTx(commitTx);
-const commitTxHash = await wallet.submitTx(signedTx);
-console.log(commitTxHash);
 ```

apps/docs/content/docs/providers/hydra.mdx

@@ -14,7 +14,9 @@ import { HydraProvider } from "@meshsdk/hydra";
 
 // Hydra Head URL and PORT: e.g. http://123.45.67.890:4001
 
-const provider = new HydraProvider("<httpUrl>");
+const provider = new HydraProvider({
+  httpUrl: <hydra-api-url>
+});
 ```
 
 ## connect
@@ -25,6 +27,25 @@ Establishes a connection to a Hydra Head. This is typically managed through the
 await provider.connect();
 ```
 
+## hydra-head messages
+
+Listens to messages from hydra-head
+
+```tsx
+provider.onMessage((message) =>
+  console.log("messages received from hydra", message)
+);
+```
+
+can be used together with connect to Receive Messages after connect
+
+```tsx
+await provider.connect();
+provider.onMessage((message) =>
+  console.log("messages received from hydra", message)
+);
+```
+
 ## disconnect
 
 Closes the active connection to a Hydra Head. This is typically managed through the HydraProvider.
@@ -35,10 +56,10 @@ Parameter (Optional)
 
 ```tsx
 // Disconnect with default timeout (5 minutes)
-await disconnect(timeout);
+await provider.disconnect();
 
 // Disconnect with custom timeout (e.g., 10 minutes)
-await disconnect(10 * 60 * 1000);
+await provider.disconnect(10 * 60 * 1000);
 ```
 
 ## Hydra commands APIs
@@ -81,8 +102,12 @@ The `newTx` method accepts the following arguments:
 - type: Any transaction is tried to decode as a 'ConwayEra' transaction, which mostly is backward compatible to previous eras.
 - description(optional): transaction description
 
+**returns**
+
+- txId(transaction Hash)
+
 ```tsx
-async newTx({
+async provider.newTx({
     cborHex: "<unsignedTx>",
     description: "commit tx",
     type: "Tx ConwayEra",
@@ -172,73 +197,57 @@ Finalize a head UTxOs to L1 after the contestation period passed.
 await provider.fanout();
 ```
 
-```tsx
-provider.onMessage((message) => {
-  if (
-    message.headStatus === "FanoutPossible" ||
-    message.tag === "HeadIsFinalized"
-  ) {
-    provider.fanout();
-  }
-});
-```
-
 ## Hydra Query APIs
 
-### Fetch Address UTxOs
+### Fetch UTxOs
 
-Fetch UTxOs controlled by an address.
+Get UTxOs for a given hash.
+Optionally, you can specify the index of the index output.
 
 ```tsx
-await provider.fetchAddressUTxOs(
-  "addr_test1qpvx0sacufuypa2k4sngk7q40zc5c4npl337uusdh64kv0uafhxhu32dys6pvn6wlw8dav6cmp4pmtv7cc3yel9uu0nq93swx9"
-);
+await provider.fetchUTxOs("txHash");
 ```
 
-Optionally, you can filter UTXOs containing a particular asset by providing `asset`, where it is the concatenation of policy ID and asset.
+### Fetch Address UTxOs
+
+Fetch UTxOs controlled by an address.
+
+Optionally, you can filter UTXOs containing a particular asset by providing `asset`, where it is the concatenation of policy ID and assetname.
 
 ```tsx
-// Assest f.e. d9312da562da182b02322fd8acb536f37eb9d29fba7c49dc172555274d657368546f6b656e
-await fetchAddressUTxOs(address: string, asset?: string)
+await provider.fetchAddressUTxOs(address: string, asset?: string)
 ```
 
-### Fetch Protocol Parameters
+### Fetch Asset Addresses
 
-Fetch the latest protocol parameters.
+Fetches the addresses and quantities for a given Cardano asset.
 
 ```tsx
-await provider.fetchProtocolParameters();
+await provider.fetchAssetAddresses(asset: string):
 ```
 
-Optionally, you can provide an epoch number to fetch the protocol parameters of that epoch.
-
-### Fetch UTxOs
+### Fetch collection Assest
 
-Get UTxOs for a given hash.
+Fetches the list of assets for a given policy ID.
 
 ```tsx
-await provider.fetchUTxOs("txHash");
+await provider.fetchCollectionAssets(policyId: string)
 ```
 
-Optionally, you can specify the index of the index output.
+### Fetch Protocol Parameters
+
+Fetch the latest protocol parameters.
 
 ```tsx
-await provider.fetchUTxOs("txHash", 0);
+await provider.fetchProtocolParameters();
 ```
 
+Optionally, you can provide an epoch number to fetch the protocol parameters of that epoch.`
+
 ### Listens for new messages from Hydra node
 
 Listens for new messages from Hydra node. The callback function will be called with the message as the only argument. Check <Link href="https://hydra.family/head-protocol/api-reference">all events emitted</Link> by the Hydra node.
 
-```tsx
-provider.onMessage((message) => {
-  console.log("HydraProvider received message", message);
-  // do something with the message
-});
-```
-
-The callback function is typed, so you can access the message properties directly.
-
 ```tsx
 provider.onMessage((message) => {
   if (message.tag === "Greetings") {
@@ -252,5 +261,6 @@ provider.onMessage((message) => {
 Submit a serialized transaction to the network.
 
 ```tsx
-await provider.submitTx(signedTx);
+const txHash = await provider.submitTx(signedTx);
+console.log("txHash", txHash);
 ```

apps/docs/data/links-hydra.ts

@@ -11,8 +11,14 @@ export const metaHydraTutorial = {
   link: "/hydra/tutorial",
 };
 
+export const metaHydraInstance = {
+  title: "Hydra Instance",
+  desc: "The HydraInstance is a class interface for interacting with a Hydra head after initialization.",
+  link: "/hydra/instance",
+};
 export const linksHydra = [
   // metaHydraGettingStarted,
+  metaHydraInstance,
   metaHydraProvider,
   metaHydraTutorial,
 ];