From 6eb253094050623051fa754d3cbc14d679fb4825 Mon Sep 17 00:00:00 2001 From: John Quinnvic Taboada <116705833+johnquinnvictaboada@users.noreply.github.com> Date: Tue, 17 Dec 2024 19:52:56 +0800 Subject: [PATCH] fix: update logo path and enhance docs (#32) --- pages/blaze.mdx | 10 +++-- pages/deno.mdx | 14 ++++--- pages/dotnet.mdx | 10 +++-- pages/nodejs.mdx | 16 +++++--- pages/query/intro.mdx | 72 +++++++++++++++++---------------- pages/submit/intro.mdx | 53 ++++++++++++------------ pages/sync/intro.mdx | 63 +++++++++++++++-------------- pages/watch/intro.mdx | 91 ++++++++++++++++++++++-------------------- theme.config.jsx | 2 +- 9 files changed, 179 insertions(+), 152 deletions(-) diff --git a/pages/blaze.mdx b/pages/blaze.mdx index eca07ff..c243ea3 100644 --- a/pages/blaze.mdx +++ b/pages/blaze.mdx @@ -1,3 +1,5 @@ +import { Callout } from "nextra-theme-docs"; + # Blaze UTxORPC Provider This provides instructions on using the **UTxORPC (u5c)** provider for the [Blaze](https://github.com/butaneprotocol/blaze-cardano) library. @@ -47,9 +49,11 @@ import { U5C } from "@utxorpc/blaze-provider"; ``` ### Step 2: Create a New U5C Provider -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). + + 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). + Here's how to create the U5C Provider: ```javascript diff --git a/pages/deno.mdx b/pages/deno.mdx index 57588db..6652022 100644 --- a/pages/deno.mdx +++ b/pages/deno.mdx @@ -1,3 +1,5 @@ +import { Callout } from "nextra-theme-docs"; + # Deno with Node.js SDK The UTxORPC SDK, an npm package for interacting with UTxORPC-compatible nodes, is also compatible with Deno thanks to the latest 'Deno 2' update. This allows you to fetch blocks, submit transactions, and synchronize with the latest blocks seamlessly using Deno's now native npm package support. @@ -63,9 +65,11 @@ The SDK includes three primary clients for interacting with UTxORPC nodes: ## Usage -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). + + 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). + Below are examples of how to use each of the clients in the SDK. @@ -118,7 +122,7 @@ fetchBlockExample().catch(console.error); ### 2. CardanoQueryClient -`CardanoQueryClient` lets you query blockchain data, read protocol parameters, and search UTXOs. +`CardanoQueryClient` lets you query blockchain data, read protocol parameters, and search UTxOs. #### Example: Reading Blockchain Parameters @@ -137,7 +141,7 @@ async function readParamsExample() { readParamsExample().catch(console.error); ``` -#### Example: Searching UTXOs by Address +#### Example: Searching UTxOs by Address ```typescript import { CardanoQueryClient } from "npm:@utxorpc/sdk"; diff --git a/pages/dotnet.mdx b/pages/dotnet.mdx index 86b727a..d647671 100644 --- a/pages/dotnet.mdx +++ b/pages/dotnet.mdx @@ -1,3 +1,5 @@ +import { Callout } from "nextra-theme-docs"; + ## .NET SDK ### Overview @@ -12,13 +14,15 @@ dotnet add package Utxorpc.Sdk ``` ### Getting Started + + 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). + Here’s how you can start using the `SyncServiceClient` to interact with the UTxORPC. #### 1. Initialize the Client -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). Here's how to initialize the client: ```csharp diff --git a/pages/nodejs.mdx b/pages/nodejs.mdx index 6b480ed..d9b6391 100644 --- a/pages/nodejs.mdx +++ b/pages/nodejs.mdx @@ -1,3 +1,5 @@ +import { Callout } from "nextra-theme-docs"; + # Node.js SDK This SDK allows you to interact with UTxORPC compatible nodes, enabling operations such as fetching blocks, submitting transactions, and syncing with the latest blocks. @@ -27,9 +29,11 @@ The SDK provides three primary clients for interacting with UTxORPC: ## Usage -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). + + 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). + Below are examples of how to use each of the clients in the SDK. @@ -85,7 +89,7 @@ fetchBlockExample().catch(console.error); ### 2. CardanoQueryClient -The `CardanoQueryClient` allows you to query blockchain data, including reading protocol parameters and searching UTXOs. +The `CardanoQueryClient` allows you to query blockchain data, including reading protocol parameters and searching UTxOs. #### Example: Reading Blockchain Parameters @@ -104,7 +108,7 @@ async function readParamsExample() { readParamsExample().catch(console.error); ``` -#### Example: Searching UTXOs by Address +#### Example: Searching UTxOs by Address ```javascript import { CardanoQueryClient } from "@utxorpc/sdk"; @@ -152,4 +156,4 @@ submitTxExample().catch(console.error); ## Conclusion -This SDK is designed to streamline the process of interacting with UTxORPC using Node.js. Whether you're syncing with the latest blockchain data, querying UTXOs, or submitting transactions, this SDK provides the necessary tools to build robust blockchain applications with ease. +This SDK is designed to streamline the process of interacting with UTxORPC using Node.js. Whether you're syncing with the latest blockchain data, querying UTxOs, or submitting transactions, this SDK provides the necessary tools to build robust blockchain applications with ease. diff --git a/pages/query/intro.mdx b/pages/query/intro.mdx index 1a9b3a5..08ca301 100644 --- a/pages/query/intro.mdx +++ b/pages/query/intro.mdx @@ -6,6 +6,35 @@ import { Tabs, Tab } from 'nextra-theme-docs' The _Query_ module provides an interface for querying the state of the ledger with the main goal of constructing new transactions. +## Sequence Example + +The following diagram describes the message exchange between a client and service where the client queries protocol parameters, reads UTxOs, and queries UTxOs. + + +```mermaid +%%{init: { 'theme': 'dark' } }%% +sequenceDiagram + actor Client + participant QueryService + + Note over Client,QueryService: query params to define fees / other criteria + Client->>+QueryService: ReadParams (field_mask) + QueryService-->>-Client: [] + + Note over Client,QueryService: read UTxO by ref to resolve tx inputs + Client->>+QueryService: ReadUtxos (refs) + QueryService-->>-Client: ReadUtxos (utxos) + + Note over Client,QueryService: query UTxO by address to balance tx + Client->>+QueryService: SearchUtxos (address_pattern) + QueryService-->>-Client: SearchUtxos (utxos) + + Note over Client,QueryService: query UTxO by token used as beacon + Client->>+QueryService: SearchUtxos (token_pattern) + QueryService-->>-Client: SearchUtxos (utxos) +``` + + ## Operations @@ -33,7 +62,7 @@ Retrieves the current protocol parameters for the chain, including important val ### ReadUtxos -Fetches specific UTXOs by their transaction reference (hash and index). Useful when you need to look up known UTXOs directly. +Fetches specific UTxOs by their output reference (hash and index). Useful when you need to look up known UTxOs directly. @@ -52,10 +81,10 @@ Fetches specific UTXOs by their transaction reference (hash and index). Useful w ### SearchUtxos -Search for UTXOs using various filtering patterns. The following search methods are available: +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. +Search for all UTxOs controlled by a specific Cardano address. The address must be base64 encoded. @@ -79,7 +108,7 @@ Search for all UTXOs controlled by a specific Cardano address. The address must #### 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. +Search for UTxOs by just the payment credential part of an address. Useful when you want to find UTxOs regardless of stake credential. @@ -103,7 +132,7 @@ Search for UTXOs by just the payment credential part of an address. Useful when #### 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. +Search for UTxOs by just the stake credential (delegation part) of an address. Helps find all UTxOs delegated to a specific stake key. @@ -127,7 +156,7 @@ Search for UTXOs by just the stake credential (delegation part) of an address. H #### By Asset Policy -Search for UTXOs containing tokens from a specific policy ID. The policy ID must be base64 encoded. +Search for UTxOs containing tokens from a specific policy ID. The policy ID must be base64 encoded. @@ -151,7 +180,7 @@ Search for UTXOs containing tokens from a specific policy ID. The policy ID must #### By Specific Asset -Search for UTXOs containing a specific token, identified by both policy ID and asset name (combined and base64 encoded). +Search for UTxOs containing a specific token, identified by both policy ID and asset name (combined and base64 encoded). @@ -177,7 +206,7 @@ Search for UTXOs containing a specific token, identified by both policy ID and a ### ReadData Read specific data (plural of datum) by hash. - This operation is yet to be implemented in Dolos and is still getting worked on. + This operation is currently under development in Dolos and is not yet available. @@ -197,29 +226,4 @@ Read specific data (plural of datum) by hash. The schema details can be found in the [spec reference](spec). - - -## Sequence Example - -```mermaid -%%{init: { 'theme': 'dark' } }%% -sequenceDiagram - actor Client - participant QueryService - - Note over Client,QueryService: query params to define fees / other criteria - Client->>+QueryService: ReadParams (field_mask) - QueryService-->>-Client: [] - - Note over Client,QueryService: read UTxO by ref to resolve tx inputs - Client->>+QueryService: ReadUtxos (refs) - QueryService-->>-Client: ReadUtxos (utxos) - - Note over Client,QueryService: query UTxO by address to balance tx - Client->>+QueryService: SearchUtxos (address_pattern) - QueryService-->>-Client: SearchUtxos (utxos) - - Note over Client,QueryService: query UTxO by token used as beacon - Client->>+QueryService: SearchUtxos (token_pattern) - QueryService-->>-Client: SearchUtxos (utxos) -``` + \ No newline at end of file diff --git a/pages/submit/intro.mdx b/pages/submit/intro.mdx index a2eb74c..090982f 100644 --- a/pages/submit/intro.mdx +++ b/pages/submit/intro.mdx @@ -5,6 +5,29 @@ import { Tabs, Tab } from 'nextra-theme-docs' The _Submit_ module provides an interface for submitting transactions and monitoring their progress through various stages in their lifecycle. +## Sequence Example + +The following diagram describes the message exchange between a client and service where the client submits a transaction and waits for status updates asynchrounously. + +```mermaid +%%{init: { 'theme': 'dark' } }%% +sequenceDiagram + actor Client + participant SubmitService + Client->>+SubmitService: Submit (Tx) + SubmitService-->>-Client: Tx Ref + Client->>SubmitService: Wait For (Tx Ref) + activate SubmitService + SubmitService--)Client: Tx Acknowledged + SubmitService--)Client: Tx in Mempool + SubmitService--)Client: Tx in Network + SubmitService--)Client: Tx Confirmed (1 block) + SubmitService--)Client: Tx Confirmed (2 block) + SubmitService--)Client: Tx Confirmed (n block) + Client->>SubmitService: Done + deactivate SubmitService +``` + ## Operations @@ -111,7 +134,7 @@ Watch mempool by just the stake credential (delegation part) of an address. #### By Asset Policy -Watch mempool for UTXOs containing tokens from a specific policy ID. The policy ID must be base64 encoded. +Watch mempool for UTxOs containing tokens from a specific policy ID. The policy ID must be base64 encoded. @@ -135,7 +158,7 @@ Watch mempool for UTXOs containing tokens from a specific policy ID. The policy #### By Specific Asset -Watch mempool for UTXOs containing a specific token, identified by both policy ID and asset name (combined and base64 encoded). +Watch mempool for UTxOs containing a specific token, identified by both policy ID and asset name (combined and base64 encoded). @@ -202,7 +225,7 @@ Evaluate transactions before submission to verify their validity and estimate ex Query the current state of the mempool to check status of pending transactions. - This operation is yet to be implemented in Dolos and is still getting worked on. + This operation is currently under development in Dolos and is not yet available. @@ -218,26 +241,4 @@ Query the current state of the mempool to check status of pending transactions. The schema details can be found in the [spec reference](spec). - - -## Sequence Example - -The following diagram describes the message exchange between a client and service where the client submits a transaction and waits for status updates asynchrounously. - -```mermaid -%%{init: { 'theme': 'dark' } }%% -sequenceDiagram - actor Client - participant SubmitService - Client->>+SubmitService: Submit (Tx) - SubmitService-->>-Client: Tx Ref - Client->>SubmitService: Wait For (Tx Ref) - activate SubmitService - SubmitService--)Client: Tx Acknowledged - SubmitService--)Client: Tx in Mempool - SubmitService--)Client: Tx in Network - SubmitService--)Client: Tx Confirmed (1 block) - SubmitService--)Client: Tx Confirmed (2 block) - SubmitService--)Client: Tx Confirmed (n block) - Client->>SubmitService: Done - deactivate SubmitService + \ No newline at end of file diff --git a/pages/sync/intro.mdx b/pages/sync/intro.mdx index e72e4f6..f0ce914 100644 --- a/pages/sync/intro.mdx +++ b/pages/sync/intro.mdx @@ -5,6 +5,37 @@ import { Tabs, Tab } from 'nextra-theme-docs' The _Sync_ module provides an interface for synchronizing chain data, fetching blocks, and tracking the tip of the blockchain. +## Sequence Example + +The following diagram describes the message exchange between a client and service where the client fetches a block, dumps history of chain, and streams the events from tip of the chain. + +```mermaid +%%{init: { 'theme': 'dark' } }%% +sequenceDiagram + actor Client + participant SyncService + + Note over Client,SyncService: fetch a particular block + Client->>+SyncService: FetchBlock () + SyncService-->>-Client: + + Note over Client,SyncService: dump history of chain in chunks of 100 blocks + Client->>+SyncService: DumpHistory (origin, 100) + SyncService-->>-Client: [origin..100] + + Client->>+SyncService: DumpHistory (last_ref, 100) + SyncService-->>-Client: [101..200] + + Note over Client,SyncService: stream change events from tip of the chain + Client->>SyncService: FollowTip () + activate SyncService + SyncService-->>Client: (block) + SyncService-->>Client: (block) + SyncService-->>Client: (point) + Client->>SyncService: Done + deactivate SyncService +``` + ## Operations **Important**: All byte fields in grpcurl examples (like hashes, addresses, assets) must be base64 encoded. @@ -67,7 +98,7 @@ Follow the blockchain tip with streaming updates. Get the current blockchain tip information. - This operation is yet to be implemented in Dolos and is still getting worked on. + This operation is currently under development in Dolos and is not yet available. @@ -83,32 +114,4 @@ Get the current blockchain tip information. The schema details can be found in the [spec reference](spec). - - -## Sequence Example - -```mermaid -%%{init: { 'theme': 'dark' } }%% -sequenceDiagram - actor Client - participant SyncService - - Note over Client,SyncService: fetch a particular block - Client->>+SyncService: FetchBlock () - SyncService-->>-Client: - - Note over Client,SyncService: dump history of chain in chunks of 100 blocks - Client->>+SyncService: DumpHistory (origin, 100) - SyncService-->>-Client: [origin..100] - - Client->>+SyncService: DumpHistory (last_ref, 100) - SyncService-->>-Client: [101..200] - - Note over Client,SyncService: stream change events from tip of the chain - Client->>SyncService: FollowTip () - activate SyncService - SyncService-->>Client: (block) - SyncService-->>Client: (block) - SyncService-->>Client: (point) - Client->>SyncService: Done - deactivate SyncService + \ No newline at end of file diff --git a/pages/watch/intro.mdx b/pages/watch/intro.mdx index 5b5006a..9b1a47f 100644 --- a/pages/watch/intro.mdx +++ b/pages/watch/intro.mdx @@ -5,6 +5,50 @@ import { Tabs, Tab } from 'nextra-theme-docs' The _Watch_ module provides an interface for streaming transactions based on specified predicates, allowing clients to monitor specific aspects of the blockchain. +## Sequence Example + +The following diagram describes the message exchange between a client and service where the client watches transactions with a specific addresss, UTxO, asset, or datum. + +```mermaid +%%{init: { 'theme': 'dark' } }%% +sequenceDiagram + actor Client + participant WatchService + + note over Client,WatchService: watch txs involved with specific address + Client->>WatchService: WatchTx (addr1xxx) + activate WatchService + WatchService--)Client: (tx with input from addr1xxx) + WatchService--)Client: (tx with output to addr1xxx) + Client->>WatchService: Done + deactivate WatchService + + note over Client,WatchService: watch txs involved with specific utxo + Client->>WatchService: WatchTx (tx hash, tx output index) + activate WatchService + WatchService--)Client: (tx with matching input) + Client->>WatchService: Done + deactivate WatchService + + + note over Client,WatchService: watch txs involved with specific asset + Client->>WatchService: WatchTx (asset policy, asset name) + activate WatchService + WatchService--)Client: (tx with asset mint) + WatchService--)Client: (tx with asset in output) + WatchService--)Client: (tx with asset in input) + Client->>WatchService: Done + deactivate WatchService + + note over Client,WatchService: watch txs involved with specific datum + Client->>WatchService: WatchTx (datum hash) + activate WatchService + WatchService--)Client: (tx with inline datum) + WatchService--)Client: (tx with redeemer datum) + Client->>WatchService: Done + deactivate WatchService +``` + ## Operations **Important**: All byte fields in grpcurl examples (like hashes, addresses, assets) must be base64 encoded. @@ -44,7 +88,7 @@ Watch all tx controlled by a specific Cardano address. The address must be base6 #### By Address Payment Part -Watch tx by just the payment credential part of an address. Useful when you want to find UTXOs regardless of stake credential. +Watch tx by just the payment credential part of an address. Useful when you want to find UTxOs regardless of stake credential. @@ -68,7 +112,7 @@ Watch tx by just the payment credential part of an address. Useful when you want #### By Address Delegation Part -Watch tx by just the stake credential (delegation part) of an address. Helps find all UTXOs delegated to a specific stake key. +Watch tx by just the stake credential (delegation part) of an address. Helps find all UTxOs delegated to a specific stake key. @@ -141,45 +185,4 @@ Watch tx containing a specific token, identified by both policy ID and asset nam The schema details can be found in the [spec reference](spec). - - -## Sequence Example - -```mermaid -%%{init: { 'theme': 'dark' } }%% -sequenceDiagram - actor Client - participant WatchService - - note over Client,WatchService: watch txs involved with specific address - Client->>WatchService: WatchTx (addr1xxx) - activate WatchService - WatchService--)Client: (tx with input from addr1xxx) - WatchService--)Client: (tx with output to addr1xxx) - Client->>WatchService: Done - deactivate WatchService - - note over Client,WatchService: watch txs involved with specific utxo - Client->>WatchService: WatchTx (tx hash, tx output index) - activate WatchService - WatchService--)Client: (tx with matching input) - Client->>WatchService: Done - deactivate WatchService - - - note over Client,WatchService: watch txs involved with specific asset - Client->>WatchService: WatchTx (asset policy, asset name) - activate WatchService - WatchService--)Client: (tx with asset mint) - WatchService--)Client: (tx with asset in output) - WatchService--)Client: (tx with asset in input) - Client->>WatchService: Done - deactivate WatchService - - note over Client,WatchService: watch txs involved with specific datum - Client->>WatchService: WatchTx (datum hash) - activate WatchService - WatchService--)Client: (tx with inline datum) - WatchService--)Client: (tx with redeemer datum) - Client->>WatchService: Done - deactivate WatchService + \ No newline at end of file diff --git a/theme.config.jsx b/theme.config.jsx index 8f11248..8e8ce3f 100644 --- a/theme.config.jsx +++ b/theme.config.jsx @@ -1,5 +1,5 @@ export default { - logo: , + logo: , project: { link: "https://github.com/utxorpc", },