Skip to content

Commit

Permalink
feat: added deno docs (#30)
Browse files Browse the repository at this point in the history
* feat: added deno docs

* chore: deno docs cleanup

* chore: cleanup v2
  • Loading branch information
johnquinnvictaboada authored Nov 7, 2024
1 parent 3ed0d0e commit 7eb8dc7
Show file tree
Hide file tree
Showing 5 changed files with 191 additions and 0 deletions.
1 change: 1 addition & 0 deletions pages/_meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@
"python": "Python",
"go": "Go",
"nodejs": "NodeJS",
"deno": "Deno",
"dotnet": ".NET",
"-- Ecosystem --": {
"type": "separator",
Expand Down
188 changes: 188 additions & 0 deletions pages/deno.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,188 @@
# 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.

## Prerequisites

Ensure you have Deno 2.0 or higher installed. Deno 2 is compatible with Node.js and npm packages, which allows you to use the `@utxorpc/sdk` package directly in your Deno project.

To install Deno, refer to the [official Deno installation guide](https://deno.land/[email protected]/getting_started/installation).

## Project Setup

You can set up a new Deno project with the `deno init` command, which generates a `deno.json` configuration file to manage dependencies and settings.

```bash
deno init
```

After running this command, you’ll see a `deno.json` file in your project directory.

## Installation with `deno add`

With Deno 2, you can use `deno add` to install npm packages without needing a `package.json` or `node_modules` folder. To install the UTxORPC SDK, run:

```bash
deno add npm:@utxorpc/sdk
```

Running this command will add `@utxorpc/sdk` to your project and update `deno.json` with an entry for `@utxorpc/sdk` as a dependency.

## Manual Installation

In Deno 2, you can also use npm packages without a `package.json` or `node_modules` folder as long as you used `deno init` . Instead, you can directly specify the package using the `npm:` prefix and it will automatically do everything for you even without the import in your `deno.json`.

```typescript
import { CardanoSyncClient, CardanoQueryClient, CardanoSubmitClient } from "npm:@utxorpc/sdk";
```

If you'd prefer to use a configuration file to manage dependencies, add an `npm:` specifier in your `deno.json` configuration if you manually added it without using `deno add` and even when using this command it should also look like this:

```json
// deno.json
{
"imports": {
"@utxorpc/sdk": "npm:@utxorpc/sdk"
}
}
```

Then import as follows:

```typescript
import { CardanoSyncClient, CardanoQueryClient, CardanoSubmitClient } from "@utxorpc/sdk";
```

## Overview

The SDK includes three primary clients for interacting with UTxORPC nodes:

1. **CardanoSyncClient**: Synchronize chain data, fetch blocks, and track blockchain tips.
2. **CardanoQueryClient**: Submit transactions and monitor their progress.
3. **CardanoSubmitClient**: Query the ledger state and construct new transactions.

## 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).

Below are examples of how to use each of the clients in the SDK.

### 1. CardanoSyncClient

`CardanoSyncClient` helps you follow the tip and fetch specific blocks.

#### Example: Following the Tip

```typescript
import { CardanoSyncClient } from "npm:@utxorpc/sdk";

async function followTipExample() {
const syncClient = new CardanoSyncClient({
uri: "http://localhost:50051"
});

const tip = syncClient.followTip([
{ slot: 54131816, hash: "34c65aba4b299113a488b74e2efe3a3dd272d25b470d25f374b2c693d4386535" },
]);

for await (const event of tip) {
console.log(event);
}
}

followTipExample().catch(console.error);
```

#### Example: Fetching a Block

```typescript
import { CardanoSyncClient } from "npm:@utxorpc/sdk";

async function fetchBlockExample() {
const syncClient = new CardanoSyncClient({
uri: "http://localhost:50051"
});

const block = await syncClient.fetchBlock({
slot: 54131816,
hash: "34c65aba4b299113a488b74e2efe3a3dd272d25b470d25f374b2c693d4386535",
});

console.log(block);
}

fetchBlockExample().catch(console.error);
```

### 2. CardanoQueryClient

`CardanoQueryClient` lets you query blockchain data, read protocol parameters, and search UTXOs.

#### Example: Reading Blockchain Parameters

```typescript
import { CardanoQueryClient } from "npm:@utxorpc/sdk";

async function readParamsExample() {
const queryClient = new CardanoQueryClient({
uri: "http://localhost:50051"
});

const params = await queryClient.readParams();
console.log(params);
}

readParamsExample().catch(console.error);
```

#### Example: Searching UTXOs by Address

```typescript
import { CardanoQueryClient } from "npm:@utxorpc/sdk";

async function searchUtxosByAddressExample() {
const queryClient = new CardanoQueryClient({
uri: "http://localhost:50051"
});

const utxos = await queryClient.searchUtxosByAddress(
Buffer.from("705c87cbca3a88cbfee6f6ad820acea99f484b4830fc632610f2a30146", "hex")
);

utxos.forEach((utxo) => {
console.log(utxo);
});
}

searchUtxosByAddressExample().catch(console.error);
```

### 3. CardanoSubmitClient

`CardanoSubmitClient` allows transaction submission.

#### Example: Submitting a Transaction

```typescript
import { CardanoSubmitClient } from "npm:@utxorpc/sdk";

async function submitTxExample() {
const submitClient = new CardanoSubmitClient({
uri: "http://localhost:50051"
});

const txSample = "84a300d90102818258203dc5d9977e7b3d51acaea81031d2f461404536b2828549b73876a5980295f81b00018282581d60916c769efc6e2a3339594818a1d0c3998c29e3a6303d8711de8567591a004c4b4082581d60916c769efc6e2a3339594818a1d0c3998c29e3a6303d8711de8567591b0000000253bcffb3021a0002990da100d9010281825820526fa19e3694cda4f3c0d2fb2d2bb8768925eccc49a89d5f12b1972644ac769858403d6d6599193b17e67827cd9f48aaf35ac762c6fb0c5402c52724f307b69ff96f3f7e6c3fb107670c28679c148bf510f479c01a34b9d95d0dbb7e4ff6f3cb560af5f6";
const txHash = await submitClient.submitTx(Buffer.from(txSample, "hex"));

const txHashHex = Buffer.from(txHash).toString("hex");
console.log(txHashHex);
}

submitTxExample().catch(console.error);
```

## Conclusion

The NodeJS UTxORPC SDK which is compatible with the Deno runtime allows seamless integration with UTxORPC nodes. With Deno’s compatibility with npm, you can access `@utxorpc/sdk` easily and use its tools for building robust blockchain applications in a secure and modern environment while utilizing Deno's wide variety of tools.
1 change: 1 addition & 0 deletions pages/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -64,4 +64,5 @@ import { CardGrid, Card, SDKCard, SectionHeader } from "../components/features";
<SDKCard title="Rust SDK" iconSrc="rust.png" href="rust" />
<SDKCard title="NodeJS SDK" iconSrc="node.png" href="nodejs" />
<SDKCard title=".NET SDK" iconSrc="dotnet.png" href="dotnet" />
<SDKCard title="Deno SDK" iconSrc="deno.png" href="deno" />
</CardGrid>
1 change: 1 addition & 0 deletions pages/introduction.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ Thanks to all of the available gRPC toolchain, generating SDKs in several progra
<Card title="NodeJs" href="nodejs" />
<Card title="Python" href="python" />
<Card title=".NET" href="dotnet" />
<Card title="Deno" href="deno" />


</Cards>
Expand Down
Binary file added public/deno.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 7eb8dc7

Please sign in to comment.