feat: add grpcurl samples to modules and update the specs (#31)

utxorpc · Nov 13, 2024 · 217a1e7 · 217a1e7
1 parent 7eb8dc7
commit 217a1e7
Show file tree

Hide file tree

Showing 8 changed files with 691 additions and 84 deletions.
diff --git a/pages/query/intro.mdx b/pages/query/intro.mdx
@@ -1,15 +1,199 @@
 import { Callout } from "nextra-theme-docs";
+import { Tabs, Tab } from 'nextra-theme-docs'
+
 
 # Query Module
 
 The _Query_ module provides an interface for querying the state of the ledger with the main goal of constructing new transactions.
 
 ## Operations
 
-- `ReadParams`: Read chain-wide parameters. 
-- `ReadUtxos`: Read specific UTxOs by reference. 
-- `SearchUtxos`: Search for UTxO based on a pattern. 
-- `ReadData`: Read specific data (plural of datum) by hash.
+<Callout type="info">
+  **Important**: All byte fields in grpcurl examples (like hashes, addresses, assets) must be base64 encoded.
+  For more details and installation of grpcurl, refer to the [grpcurl guide](/grpcurl).
+</Callout>
+
+<Callout type="note">
+    The following code samples assume that the UTxORPC node is running locally on `localhost:50051`. If your node is hosted remotely or on a different server, replace `"http://localhost:50051"` with the appropriate server URL and port for your environment. 
+
+    For more details on configuring your node, refer to the [UTxORPC Ecosystem Servers Documentation](/servers).
+</Callout>
+
+### ReadParams
+Retrieves the current protocol parameters for the chain, including important values like fees, epoch information, and other consensus settings.
+
+<Tabs items={['grpcurl']}>
+  <Tab>
+    ```bash
+    grpcurl -plaintext \
+      localhost:50051 \
+      utxorpc.v1alpha.query.QueryService.ReadParams
+    ```
+  </Tab>
+</Tabs>
+
+### ReadUtxos 
+Fetches specific UTXOs by their transaction reference (hash and index). Useful when you need to look up known UTXOs directly.
+
+<Tabs items={['grpcurl']}>
+  <Tab>
+    ```bash
+    grpcurl -plaintext \
+      -d '{
+        "keys": [{
+          "hash": "p4WAOb31UfCR2qsqVlBLiUrsVwZoGPVOmYOjavDuEPs=",
+          "index": 0
+        }]
+      }' \
+      localhost:50051 \
+      utxorpc.v1alpha.query.QueryService.ReadUtxos
+    ```
+  </Tab>
+</Tabs>
+
+### SearchUtxos
+Search for UTXOs using various filtering patterns. The following search methods are available:
+
+#### By Address
+Search for all UTXOs controlled by a specific Cardano address. The address must be base64 encoded.
+
+<Tabs items={['grpcurl']}>
+  <Tab>
+    ```bash
+    grpcurl -plaintext \
+      -d '{
+        "predicate": {
+          "match": {
+            "cardano": {
+              "address": {
+                "exact_address": "AJs7DC2gQcMrCyDdI49iEvCVlVjxfyrYvmj76rLmODCCS9vyMxgygxirZgrESIt1j2tbOSqOku8e"
+              }
+            }
+          }
+        }
+      }' \
+      localhost:50051 \
+      utxorpc.v1alpha.query.QueryService.SearchUtxos
+    ```
+  </Tab>
+</Tabs>
+
+#### By Address Payment Part 
+Search for UTXOs by just the payment credential part of an address. Useful when you want to find UTXOs regardless of stake credential.
+
+<Tabs items={['grpcurl']}>
+  <Tab>
+    ```bash
+    grpcurl -plaintext \
+      -d '{
+        "predicate": {
+          "match": {
+            "cardano": {
+              "address": {
+                "payment_part": "mzsMLaBBwysLIN0jj2IS8JWVWPF/Kti+aPvqsg=="
+              }
+            }
+          }
+        }
+      }' \
+      localhost:50051 \
+      utxorpc.v1alpha.query.QueryService.SearchUtxos
+    ```
+  </Tab>
+</Tabs>
+
+#### By Address Delegation Part
+Search for UTXOs by just the stake credential (delegation part) of an address. Helps find all UTXOs delegated to a specific stake key.
+
+<Tabs items={['grpcurl']}>
+  <Tab>
+    ```bash
+    grpcurl -plaintext \
+      -d '{
+        "predicate": {
+          "match": {
+            "cardano": {
+                "address": {
+                    "delegation_part": "5jgwgkvb8jMYMoMYq2YKxEiLdY9rWzkqjpLvHg=="
+                }
+            }
+          }
+        }
+      }' \
+      localhost:50051 \
+      utxorpc.v1alpha.query.QueryService.SearchUtxos
+    ```
+  </Tab>
+</Tabs>
+
+#### By Asset Policy
+Search for UTXOs containing tokens from a specific policy ID. The policy ID must be base64 encoded.
+
+<Tabs items={['grpcurl']}>
+  <Tab>
+    ```bash
+    grpcurl -plaintext \
+      -d '{
+        "predicate": {
+          "match": {
+            "cardano": {
+              "asset": {
+                "policy_id": "BH4PkSxCYP5mriceWuSU3NX3ljW7uxOGvhlfTg=="
+              }
+            }
+          }
+        }
+      }' \
+      localhost:50051 \
+      utxorpc.v1alpha.query.QueryService.SearchUtxos
+    ```
+  </Tab>
+</Tabs>
+
+#### By Specific Asset 
+Search for UTXOs containing a specific token, identified by both policy ID and asset name (combined and base64 encoded).
+
+<Tabs items={['grpcurl']}>
+  <Tab>
+    ```bash
+    grpcurl -plaintext \
+      -d '{
+        "predicate": {
+          "match": {
+            "cardano": {
+              "asset": {
+                "asset_name": "BH4PkSxCYP5mriceWuSU3NX3ljW7uxOGvhlfTkFMTEVZS0FUWjAwMDYw"
+              }
+            }
+          }
+        }
+      }' \
+      localhost:50051 \
+      utxorpc.v1alpha.query.QueryService.SearchUtxos
+    ```
+  </Tab>
+</Tabs>
+
+### ReadData 
+Read specific data (plural of datum) by hash.
+<Callout type="warning">
+  This operation is yet to be implemented in Dolos and is still getting worked on.
+</Callout>
+<Tabs items={['grpcurl']}>
+  <Tab>
+    ```bash
+    grpcurl -plaintext \
+      -d '{
+        "keys": [
+          "/u066600mYdRq1Xjf3d1UOSguQ8umzvtplb6DymjDeA="
+        ]
+      }' \
+      localhost:50051 \
+      utxorpc.v1alpha.query.QueryService.ReadData
+    ```
+  </Tab>
+</Tabs>
+
 
 <Callout type="info">
   The schema details can be found in the [spec reference](spec).

diff --git a/pages/query/spec.mdx b/pages/query/spec.mdx
@@ -2,14 +2,14 @@
 
 <a name="utxorpc-v1alpha-query-AnyChainDatum"></a>
 
-## AnyChainDatum
+### AnyChainDatum
 An evenlope that holds a datum for any of the compatible chains
 
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
+| native_bytes | [bytes](#bytes) |  | Original bytes as defined by the chain |
 | key | [bytes](#bytes) |  |  |
-| native_bytes | [bytes](#bytes) |  | An opaque bytestring corresponding to native representation in the source chain. |
 | cardano | [utxorpc.v1alpha.cardano.PlutusData](#utxorpc-v1alpha-cardano-PlutusData) |  | A cardano UTxO |
 
 
@@ -19,7 +19,7 @@ An evenlope that holds a datum for any of the compatible chains
 
 <a name="utxorpc-v1alpha-query-AnyChainParams"></a>
 
-## AnyChainParams
+### AnyChainParams
 An evenlope that holds parameter data from any of the compatible chains
 
 
@@ -34,14 +34,14 @@ An evenlope that holds parameter data from any of the compatible chains
 
 <a name="utxorpc-v1alpha-query-AnyUtxoData"></a>
 
-## AnyUtxoData
+### AnyUtxoData
 An evenlope that holds an UTxO from any of compatible chains
 
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
+| native_bytes | [bytes](#bytes) |  | Original bytes as defined by the chain |
 | txo_ref | [TxoRef](#utxorpc-v1alpha-query-TxoRef) |  | Hash of the previous transaction. |
-| native_bytes | [bytes](#bytes) |  | An opaque bytestring corresponding to native representation in the source chain. |
 | cardano | [utxorpc.v1alpha.cardano.TxOutput](#utxorpc-v1alpha-cardano-TxOutput) |  | A cardano UTxO |
 
 
@@ -51,7 +51,7 @@ An evenlope that holds an UTxO from any of compatible chains
 
 <a name="utxorpc-v1alpha-query-AnyUtxoPattern"></a>
 
-## AnyUtxoPattern
+### AnyUtxoPattern
 An evenlope that holds an UTxO patterns from any of compatible chains
 
 
@@ -66,7 +66,7 @@ An evenlope that holds an UTxO patterns from any of compatible chains
 
 <a name="utxorpc-v1alpha-query-ChainPoint"></a>
 
-## ChainPoint
+### ChainPoint
 Represents a specific point in the blockchain.
 
 
@@ -82,7 +82,7 @@ Represents a specific point in the blockchain.
 
 <a name="utxorpc-v1alpha-query-ReadDataRequest"></a>
 
-## ReadDataRequest
+### ReadDataRequest
 Request to get data (as in plural of datum)
 
 
@@ -98,7 +98,7 @@ Request to get data (as in plural of datum)
 
 <a name="utxorpc-v1alpha-query-ReadDataResponse"></a>
 
-## ReadDataResponse
+### ReadDataResponse
 Response containing data (as in plural of datum)
 
 
@@ -114,7 +114,7 @@ Response containing data (as in plural of datum)
 
 <a name="utxorpc-v1alpha-query-ReadParamsRequest"></a>
 
-## ReadParamsRequest
+### ReadParamsRequest
 Request to get the chain parameters
 
 
@@ -129,7 +129,7 @@ Request to get the chain parameters
 
 <a name="utxorpc-v1alpha-query-ReadParamsResponse"></a>
 
-## ReadParamsResponse
+### ReadParamsResponse
 Response containing the chain parameters
 
 
@@ -145,7 +145,7 @@ Response containing the chain parameters
 
 <a name="utxorpc-v1alpha-query-ReadUtxosRequest"></a>
 
-## ReadUtxosRequest
+### ReadUtxosRequest
 Request to get specific UTxOs
 
 
@@ -161,7 +161,7 @@ Request to get specific UTxOs
 
 <a name="utxorpc-v1alpha-query-ReadUtxosResponse"></a>
 
-## ReadUtxosResponse
+### ReadUtxosResponse
 Response containing the UTxOs associated with the requested addresses.
 
 
@@ -177,14 +177,16 @@ Response containing the UTxOs associated with the requested addresses.
 
 <a name="utxorpc-v1alpha-query-SearchUtxosRequest"></a>
 
-## SearchUtxosRequest
-Reques to search for UTxO based on a pattern.
+### SearchUtxosRequest
+Request to search for UTxO based on a pattern.
 
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | predicate | [UtxoPredicate](#utxorpc-v1alpha-query-UtxoPredicate) |  | Pattern to match UTxOs by. |
 | field_mask | [google.protobuf.FieldMask](#google-protobuf-FieldMask) |  | Field mask to selectively return fields. |
+| max_items | [int32](#int32) |  | The maximum number of items to return. |
+| start_token | [string](#string) |  | The next_page_token value returned from a previous request, if any. |
 
 
 
@@ -193,14 +195,15 @@ Reques to search for UTxO based on a pattern.
 
 <a name="utxorpc-v1alpha-query-SearchUtxosResponse"></a>
 
-## SearchUtxosResponse
+### SearchUtxosResponse
 Response containing the UTxOs that match the requested addresses.
 
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
 | items | [AnyUtxoData](#utxorpc-v1alpha-query-AnyUtxoData) | repeated | List of UTxOs. |
 | ledger_tip | [ChainPoint](#utxorpc-v1alpha-query-ChainPoint) |  | The chain point that represent the ledger current position. |
+| next_token | [string](#string) |  | Token to retrieve the next page of results, or empty if there are no more results. |
 
 
 
@@ -209,7 +212,7 @@ Response containing the UTxOs that match the requested addresses.
 
 <a name="utxorpc-v1alpha-query-TxoRef"></a>
 
-## TxoRef
+### TxoRef
 Represents a reference to a transaction output
 
 
@@ -225,7 +228,7 @@ Represents a reference to a transaction output
 
 <a name="utxorpc-v1alpha-query-UtxoPredicate"></a>
 
-## UtxoPredicate
+### UtxoPredicate
 Represents a simple utxo predicate that can composed to create more complex ones
 
 
@@ -249,7 +252,7 @@ Represents a simple utxo predicate that can composed to create more complex ones
 
 <a name="utxorpc-v1alpha-query-QueryService"></a>
 
-## QueryService
+### QueryService
 Service definition for querying the state of the chain.
 
 | Method Name | Request Type | Response Type | Description |
@@ -258,5 +261,3 @@ Service definition for querying the state of the chain.
 | ReadUtxos | [ReadUtxosRequest](#utxorpc-v1alpha-query-ReadUtxosRequest) | [ReadUtxosResponse](#utxorpc-v1alpha-query-ReadUtxosResponse) | Read specific UTxOs by reference. |
 | SearchUtxos | [SearchUtxosRequest](#utxorpc-v1alpha-query-SearchUtxosRequest) | [SearchUtxosResponse](#utxorpc-v1alpha-query-SearchUtxosResponse) | Search for UTxO based on a pattern. |
 | ReadData | [ReadDataRequest](#utxorpc-v1alpha-query-ReadDataRequest) | [ReadDataResponse](#utxorpc-v1alpha-query-ReadDataResponse) | Read specific datum by hash |
-
-